Crate dilate

A compact, high performance integer dilation library for Rust.

Integer dilation is the process of converting cartesian indices (eg. coordinates) into a format suitable for use in D-dimensional algorithms such Morton Order curves. The dilation process takes an integer’s bit sequence and inserts a number of 0 bits (D - 1) between each original bit successively. Thus, the original bit sequence becomes evenly padded. For example:

• 0b1101 D2-dilated becomes 0b1010001 (values chosen arbitrarily)
• 0b1011 D3-dilated becomes 0b1000001001

The process of undilation, or ‘contraction’, does the opposite:

• 0b1010001 D2-undilated becomes 0b1101
• 0b1000001001 D3-undilated becomes 0b1011

This libary also supports a limited subset of arthimetic operations on dilated integers via the standard rust operater traits. Whilst slightly more involved than regular integer arithmetic, these operations are still highly performant.

Which Dilation Method to Choose

There are currently two distinct ways to dilate integers; Expanding or Fixed. To help decide which is right for your application, consider the following:

Use dilate_expand() when you want all bits of the source integer to be dilated and you don’t mind how the dilated integer is stored behind the scenes. This is the most intuitive method of interacting with dilated integers.

Use dilate_fixed() when you want control over the storage type and want to maximise the number of bits occupied within that storage type.

Notice that the difference between the two is that of focus; dilate_expand() focusses on maximising the usage of the source integer, whereas dilate_fixed() focusses on maximising the usage of the dilated integer.

You may also use the raw Expand and Fixed DilationMethod implementations directly, though they tend to be more verbose.

Supported Dilations

For more information on the supported dilations and possible type combinations, please see Supported Expand Dilations and Supported Fixed Dilations.

Examples

use dilate::*;

let original: u8 = 0b1101;

// Dilating
let dilated = original.dilate_expand::<2>();
assert_eq!(dilated.value(), 0b1010001);

// This is the actual dilated type
assert_eq!(dilated, DilatedInt::<Expand<u8, 2>>::new(0b1010001));

// Undilating
assert_eq!(dilated.undilate(), original);

Example 2-dilation and undilation usage

use dilate::*;

let original: u8 = 0b1011;

// Dilating
let dilated = original.dilate_expand::<3>();
assert_eq!(dilated.value(), 0b1000001001);

// This is the actual dilated type
assert_eq!(dilated, DilatedInt::<Expand<u8, 3>>::new(0b1000001001));

// Undilating
assert_eq!(dilated.undilate(), original);

Example 3-dilation and undilation usage

Re-exports

pub use crate::expand::DilateExpand;

pub use crate::expand::Expand;

pub use crate::fixed::DilateFixed;

pub use crate::fixed::Fixed;

Modules

expand

Contains the Expand dilation method and all supporting items

fixed

Contains the Fixed dilation method and all supporting items

Structs

DilatedInt

A storage type holding and identifying dilated integers

Traits

DilatableType

Denotes an integer type supported by the various dilation and undilation methods

DilationMethod

Allows for custom decoupled dilation behaviours