# Crate malachite_base

Expand description

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 malachite_base::num::exhaustive::exhaustive_unsigneds;
use malachite_base::tuples::exhaustive::exhaustive_pairs_from_single;

let mut pairs = exhaustive_pairs_from_single(exhaustive_unsigneds::<u32>());
assert_eq!(
pairs.take(20).collect::<Vec<_>>(),
&[
(0, 0), (0, 1), (1, 0), (1, 1), (0, 2), (0, 3), (1, 2), (1, 3), (2, 0), (2, 1),
(3, 0), (3, 1), (2, 2), (2, 3), (3, 2), (3, 3), (0, 4), (0, 5), (1, 4), (1, 5)
]
);
• The RoundingMode enum, which allows you to specify the rounding behavior of various functions.
• The NiceFloat wrapper, which provides alternative implementations of Eq, Ord, and Display for floating-point values which are in some ways nicer than the defaults.

## Demos and benchmarks

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:
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:
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.

## Features

• 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.

## Modules

Functions for working with bools.
Functions for working with chars.
Macros and traits related to comparing values.
The Named trait, for getting a type’s name.
Never, a type that cannot be instantiated.
Functions for working with primitive integers and floats.
Functions for working with Orderings.
Functions for working with Options.
Functions for generating random values.
RationalSequence, a type representing a sequence that is finite or eventually repeating, just like the digits of a rational number.
RoundingMode, an enum used to specify rounding behavior.
Functions for working with HashSets and BTreeSets.
Functions for working with slices.
Functions for working with Strings.
Functions for working with tuples.
Unions (sum types). These are essentially generic enums.
Functions for working with Vecs.

## Macros

Defines custom exhaustive tuple generators.
Defines exhaustive ordered unique tuple generators.
Defines exhaustive tuple generators.
Defines exhaustive tuple generators that generate tuples from a single iterator.
Defines exhaustive union generators.
Defines lexicographic unique tuple generators.
Defines exhaustive fixed-length Vec generators.
Automatically implements Named for a type.
Defines custom lexicographic tuple generators.
Defines lexicographic ordered unique tuple generators.
Defines lexicographic tuple generators.
Defines lexicographic unique tuple generators.
Defines lexicographic fixed-length Vec generators.
Computes the maximum of a list of expressions.
Computes the minimum of a list of expressions.
Defines custom random tuple generators.
Defines random ordered unique tuple generators.
Defines random tuple generators.
Defines random union generators.
Defines random unique tuple generators.
Defines random fixed-length Vec generators.
Splits an immutable slice into adjacent immutable chunks.
Splits a mutable slice into adjacent mutable chunks.
Defines unions.