Rather than using this crate directly, use the
malachite meta-crate. It re-exports all of this crate's
public members.
In malachite-base's doctests you will frequently see import paths beginning with
malachite_base::. When using the malachite crate, replace this part of the paths with
malachite::.
This crate contains many utilities that are used by the
malachite-nz and
malachite-q crates. These utilities include
- Traits that wrap functions from the standard library, like
CheckedAdd.
- Traits that give extra functionality to primitive types, like
Gcd,
FloorSqrt,
and
BitAccess.
- Iterator-producing functions that let you generate values for testing. Here's an example of
an iterator that produces all pairs of
u32s:
```
use malachitebase::num::exhaustive::exhaustiveunsigneds;
use malachitebase::tuples::exhaustive::exhaustivepairsfromsingle;
let mut pairs = exhaustivepairsfromsingle(exhaustiveunsigneds::
- The
[RoundingMode](https://docs.rs/malachite-base/latest/malachite_base/rounding_modes/enum.RoundingMode.html)
enum, which allows you to specify the rounding behavior of various functions.
- The
[NiceFloat](https://docs.rs/malachite-base/latest/malachite_base/num/float/struct.NiceFloat.html) wrapper, which provides alternative implementations of
[Eq](https://doc.rust-lang.org/nightly/core/cmp/trait.Eq.html),
[Ord](https://doc.rust-lang.org/nightly/core/cmp/trait.Ord.html), and
[Display`](https://doc.rust-lang.org/nightly/core/fmt/trait.Display.html)
for floating-point values which are in some ways nicer than the defaults.
This crate comes with a bin target that can be used for running demos and benchmarks.
- Almost all of the public functions in this crate have an associated demo. Running a demo
shows you a function's behavior on a large number of inputs. For example, to demo the
mod_pow
function on u32s, you can use the
following command:
cargo run --features bin_build --release -- -l 10000 -m exhaustive -d demo_mod_pow_u32
This command uses the exhaustive mode, which generates every possible input, generally
starting with the simplest input and progressing to more complex ones. Another mode is
random. The -l flag specifies how many inputs should be generated.
- You can use a similar command to run benchmarks. The following command benchmarks various
GCD algorithms for u64s:
text
cargo run --features bin_build --release -- -l 1000000 -m random -b \
benchmark_gcd_algorithms_u64 -o gcd-bench.gp
This creates a file called gcd-bench.gp. You can use gnuplot to create an SVG from it like
so:
text
gnuplot -e "set terminal svg; l \"gcd-bench.gp\"" > gcd-bench.svg
The list of available demos and benchmarks is not documented anywhere; you must find them by
browsing through
bin_util/demo_and_bench.
test_build: A large proportion of the code in this crate is only used for testing. For a
typical user, building this code would result in an unnecessarily long compilation time and
an unnecessarily large binary. Much of it is also used for testing
malachite-nz and
malachite-q, so it can't just be confined to the
tests directory. My solution is to only build this code when the test_build feature is
enabled. If you want to run unit tests, you must enable test_build. However, doctests don't
require it, since they only test the public interface.bin_build: This feature is used to build the code for demos and benchmarks, which also
takes a long time to build. Enabling this feature also enables test_build.