+
+This crate provides a macro that enables the use of custom derive attributes.
+
+
To use it, make sure you link to the crate like so:
+
+
+#[macro_use] extern crate custom_derive;
+
+
+Note: the custom_derive! macro itself is not documented, as the automatic documentation for it would be uselessly huge and incomprehensible.
+
+
+
+
The macro should be used to wrap an entire single enum or struct declaration, including its attributes (both derive and others). All derivation attributes which the macro does not recognise will be assumed to be custom, and treated accordingly.
+
+
custom_derive! assumes that custom derivations are implemented as macros (of the same name). For example, here is a simple derivation macro:
+
+
+#[macro_use] extern crate custom_derive;
+
+trait TypeName {
+ fn type_name() -> &'static str;
+}
+
+trait ReprType {
+ type Repr;
+}
+
+macro_rules! TypeName {
+ (() $(pub)* enum $name:ident $($tail:tt)*) => { TypeName! { @impl $name } };
+ (() $(pub)* struct $name:ident $($tail:tt)*) => { TypeName! { @impl $name } };
+
+ (@impl $name:ident) => {
+ impl TypeName for $name {
+ fn type_name() -> &'static str { stringify!($name) }
+ }
+ };
+}
+
+macro_rules! TryFrom {
+ (($repr:ty) $(pub)* enum $name:ident $($tail:tt)*) => {
+ impl ReprType for $name {
+ type Repr = $repr;
+ }
+ };
+}
+
+custom_derive! {
+ #[allow(dead_code)]
+ #[repr(u8)]
+ #[derive(Clone, Copy, Debug, TryFrom(u8), TypeName)]
+ enum Foo { A, B }
+}
+
+fn main() {
+ let foo = Foo::B;
+ let v = foo as <Foo as ReprType>::Repr;
+ let msg = format!("{}: {:?} ({:?})", Foo::type_name(), foo, v);
+ assert_eq!(msg, "Foo: B (1)");
+}
+
+
First, note that custom_derive! passes any arguments on the derivation attribute to the macro. In the case of attributes without any arguments, () is passed instead.
+
+
Secondly, the macro is passed the entire item, sans attributes. It is the derivation macro's job to parse the item correctly.
+
+
Third, each derivation macro is expected to result in zero or more items, not including the item itself. As a result, it is not possible to mutate the item in any way, or attach additional attributes to it.
+
+
Finally, @impl is merely a trick to pack multiple, different functions into a single macro. The sequence has no special meaning; it is simply distinct from the usual invocation syntax.
+
pub fn distance(x: &[u8], y: &[u8]) -> u64
Computes the bitwise Hamming
+distance between
+x and y, that is, the number of bits where x and y differ,
+or, the number of set bits in the xor of x and y.
+
+
When x and y have the same 8-byte alignment, this uses
+distance_fast, a highly optimised version of the following naive
+version:
+
+
+fn naive(x: &[u8], y: &[u8]) -> u64 {
+ x.iter().zip(y).fold(0, |a, (b, c)| a + (*b ^ *c).count_ones() as u64)
+}
+
+
If alignments differ, a slower but less restrictive algorithm is
+used.
+
+
It is essentially guaranteed that x and y will have the same
+8-byte alignment if they are both just Vec<u8>s of non-trivial
+length (e.g. larger than 8) as in the example below.
+
+
+
x and y must have the same length, or else distance panics.
+
+
+
+
+
+| length |
+naive (ns) |
+distance (ns) |
+naive/distance |
+
+
+
+
+
+| 1 |
+5 |
+6 |
+0.83 |
+
+
+| 10 |
+44 |
+45 |
+0.97 |
+
+
+| 100 |
+461 |
+473 |
+0.97 |
+
+
+| 1,000 |
+4,510 |
+397 |
+11 |
+
+
+| 10,000 |
+46,700 |
+2,740 |
+17 |
+
+
+| 100,000 |
+45,600 |
+20,400 |
+22 |
+
+
+| 1,000,000 |
+4,590,000 |
+196,000 |
+23 |
+
+
+
+
+
The benchmarks ensured that x and y had the same alignment.
+
+
+
+let x = vec![0xFF; 1000];
+let y = vec![0; 1000];
+assert_eq!(hamming::distance(&x, &y), 8 * 1000);
+
pub fn distance_fast(x: &[u8], y: &[u8]) -> Result<u64, DistanceError>
Computes the bitwise Hamming
+distance between
+x and y, that is, the number of bits where x and y differ,
+or, the number of set bits in the xor of x and y.
+
+
This is a highly optimised version of the following naive version:
+
+
+fn naive(x: &[u8], y: &[u8]) -> u64 {
+ x.iter().zip(y).fold(0, |a, (b, c)| a + (*b ^ *c).count_ones() as u64)
+}
+
+
This function requires that x and y have the same 8-byte
+alignment (that is, x.as_ptr() as usize % 8 == y.as_ptr() as usize % 8). If not, Err is returned. If sub-optimal performance
+can be tolerated, consider using distance which incorporates a
+fallback to a slower but less restrictive algorithm.
+
+
It is essentially guaranteed that x and y will have the same
+8-byte alignment if they are both just Vec<u8>s of non-trivial
+length (e.g. larger than 8) as in the example below.
+
+
This is implemented using the same tree-merging approach as
+weight, see there for details.
+
+
+
x and y must have the same length, or else distance_fast panics.
+
+
+
+
+
+| length |
+naive (ns) |
+distance_fast (ns) |
+naive/distance_fast |
+
+
+
+
+
+| 1 |
+5 |
+6 |
+0.83 |
+
+
+| 10 |
+44 |
+45 |
+0.97 |
+
+
+| 100 |
+461 |
+473 |
+0.97 |
+
+
+| 1,000 |
+4,510 |
+397 |
+11 |
+
+
+| 10,000 |
+46,700 |
+2,740 |
+17 |
+
+
+| 100,000 |
+45,600 |
+20,400 |
+22 |
+
+
+| 1,000,000 |
+4,590,000 |
+196,000 |
+23 |
+
+
+
+
+
+
+let x = vec![0xFF; 1000];
+let y = vec![0; 1000];
+assert_eq!(hamming::distance_fast(&x, &y), Ok(8 * 1000));
+
+
+assert_eq!(hamming::distance_fast(&x[1..1000 - 8], &y[8 + 1..]), Ok(8 * (1000 - 8 - 1)));
+
+
+assert!(hamming::distance_fast(&x[1..], &y[..999]).is_err());
+
pub fn weight(x: &[u8]) -> u64
Computes the Hamming
+weight of x, that
+is, the population count, or number of ones.
+
+
This is a highly optimised version of the following naive version:
+
+
+fn naive(x: &[u8]) -> u64 {
+ x.iter().fold(0, |a, b| a + b.count_ones() as u64)
+}
+
+
This uses Lauradoux Cédric's tree-merging
+approach
+(as implemented by Kim Walisch in
+primesieve) and achieves on the order of
+1-2 cycles per byte.
+
+
+
+
+
+| length |
+naive (ns) |
+weight (ns) |
+naive/weight |
+
+
+
+
+
+| 1 |
+5 |
+16 |
+0.31 |
+
+
+| 10 |
+29 |
+51 |
+0.56 |
+
+
+| 100 |
+284 |
+392 |
+0.72 |
+
+
+| 1,000 |
+2,780 |
+340 |
+8.2 |
+
+
+| 10,000 |
+27,700 |
+2,300 |
+12 |
+
+
+| 100,000 |
+276,000 |
+17,900 |
+15 |
+
+
+| 1,000,000 |
+2,770,000 |
+172,000 |
+16 |
+
+
+
+
+
+
+assert_eq!(hamming::weight(&[1, 0xFF, 1, 0xFF]), 1 + 8 + 1 + 8);
+
A crate to count ones and xor bytes, fast (aka popcount, hamming
+weight and hamming distance).
+
+
+
Add this to your Cargo.toml:
+
+
[dependencies]
+hamming = "0.1"
+
+
+
+
+assert_eq!(hamming::weight(&[1, 0xFF, 1, 0xFF]), 1 + 8 + 1 + 8);
+assert_eq!(hamming::distance(&[1, 0xFF], &[0xFF, 1]), 7 + 7);
+
+
+ | distance |
+
+ Computes the bitwise Hamming
+distance between
+x and y, that is, the number of bits where x and y differ,
+or, the number of set bits in the xor of x and y.
+ |
+
+
+ | distance_fast |
+
+ Computes the bitwise Hamming
+distance between
+x and y, that is, the number of bits where x and y differ,
+or, the number of set bits in the xor of x and y.
+ |
+
+
+ | weight |
+
+ Computes the Hamming
+weight of x, that
+is, the population count, or number of ones.
+ |
+
+