Struct confitul::CKey

pub struct CKey { /* private fields */ }

CKey implements a consistent hask key. Theory here: https://en.wikipedia.org/wiki/Consistent_hashing

Examples

use confitul::CKey;

let k1 = CKey::new_rand();
let k2 = k1.next();
print!("k1:{:?} k2:{:?}\n", k1, k2);

Implementations

impl CKey

pub fn new_digest(data: impl AsRef<[u8]>) -> Self

Make a digest from data and returns a new key from it. Typical usage is to create a a CKey from a string or an object content.

Examples

use confitul::CKey;

let k = CKey::new_digest("/a/unique/path");
assert_eq!("3b818742b0f27cfc10f4de1e5ba5594c975d580c412a31011ad58d36a2b17cdc", format!("{:?}",k));

pub fn new_rand() -> Self

Generate a random key. This can be time consuming as it is using the OS random generation, which is better from a cryptographic point of view, but possibly slower than a standard prng.

Examples

use confitul::CKey;

let k = CKey::new_rand();
print!("k: {:?}", k);

Examples found in repository

src/node.rs (line 19)

    pub fn new_rand() -> Node {
        Self::new_with_key(CKey::new_rand())
    }

src/ep.rs (line 33)

    pub fn new_local() -> EP {
        let key = CKey::new_rand();
        let url = format!("{}:{}", LOCAL, key);
        EP {
            key,
            url: Url::parse(url.as_str()).unwrap(),
        }
    }

pub fn new_zero() -> Self

Generate a key with the value 0.

Examples

use confitul::CKey;

let k = CKey::new_zero();
assert_eq!("0000000000000000000000000000000000000000000000000000000000000000", format!("{:?}", k));

pub fn new_unit() -> Self

Generate a key with the value 1, the smallest key possible just after zero.

Examples

use confitul::CKey;

let k = CKey::new_unit();
assert_eq!("0000000000000000000000000000000000000000000000000000000000000001", format!("{:?}", k));

Examples found in repository

src/ckey.rs (line 216)

    pub fn next(self) -> CKey {
        self + Self::new_unit()
    }

    /// Return current key minus one.
    ///
    /// # Examples
    /// ```
    /// use confitul::CKey;
    ///
    /// let k = CKey::new_zero();
    /// assert_eq!(CKey::new_last(), k.prev());
    /// ```
    pub fn prev(self) -> CKey {
        self - Self::new_unit()
    }

pub fn new_last() -> Self

Generate a key with the last, highest possible value.

Examples

use confitul::CKey;

let k = CKey::new_last();
assert_eq!("ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", format!("{:?}", k));

pub fn new_half() -> Self

Generate a key which is exactly in the middle of the ring.

Examples

use confitul::CKey;

let k = CKey::new_half();
assert_eq!("8000000000000000000000000000000000000000000000000000000000000000", format!("{:?}", k));

pub fn inside(self, lower: CKey, upper: CKey) -> bool

Returns true if self is inside lower and upper. Lower limit is excluded, upper is included. This is typically used in a ring to know if a given key is handled by a node. You would ask if key is inside previous node (lower) and this node (upper) and if true -> yes, this is the right node to handle it.

Examples

use confitul::CKey;

let k1 = CKey::from(0.1);
let k2 = CKey::from(0.3);
let k3 = CKey::from(0.9);
assert!(k2.inside(k1, k3));

Examples found in repository

src/ckey.rs (line 294)

    pub fn sort(v: &mut Vec<CKey>, start: CKey) {
        v.sort_by(|a, b| {
            // So here, the logic is to consider that everything is
            // "normalized" so that the start is "key 0" and then we
            // look at the order *after* this starting point.
            //
            // In practice, self is lower than other if self is between
            // start and other.
            //
            // And self is greater than other if other is between start
            // and self.
            if *a == *b {
                Ordering::Equal
            } else if a.inside(start, *b) {
                // Other key is after us, considering the "zero" is start.
                Ordering::Less
            } else {
                Ordering::Greater
            }
        });
    }

pub fn incr(&mut self)

Increment current key by one.

Examples

use confitul::CKey;

let mut k = CKey::new_zero();
k.incr();
assert_eq!(CKey::new_unit(), k);

pub fn decr(&mut self)

Decrement current key by one.

Examples

use confitul::CKey;

let mut k = CKey::new_zero();
k.decr();
assert_eq!(CKey::new_last(), k);

pub fn next(self) -> CKey

Return current key plus one.

Examples

use confitul::CKey;

let k = CKey::new_zero();
assert_eq!(CKey::new_unit(), k.next());

Examples found in repository

src/ckey.rs (line 189)

    pub fn incr(&mut self) {
        *self = self.next();
    }

pub fn prev(self) -> CKey

Return current key minus one.

Examples

use confitul::CKey;

let k = CKey::new_zero();
assert_eq!(CKey::new_last(), k.prev());

Examples found in repository

src/ckey.rs (line 203)

    pub fn decr(&mut self) {
        *self = self.prev();
    }

pub fn parse(value: &str) -> Result<CKey, <Self as TryFrom<&str>>::Error>

Try to convert from a &str.

Examples

use confitul::CKey;
use std::convert::TryFrom;

let k = CKey::parse("12345678ffffffff01234567fffffffff00123456ffffffff0012345ffffffff").unwrap();
assert_eq!("12345678ffffffff01234567fffffffff00123456ffffffff0012345ffffffff", format!("{:?}", k));

Examples found in repository

src/ckey.rs (line 418)

    fn try_from(value: &str) -> Result<CKey, Self::Error> {
        Self::parse(value)
    }

src/ep.rs (line 51)

    pub fn parse(key: &str, url: &str) -> Result<EP, Box<dyn std::error::Error>> {
        let parsed_key = CKey::parse(key)?;
        let parsed_url = Url::parse(url)?;
        Ok(EP {
            key: parsed_key,
            url: parsed_url,
        })
    }

pub fn sort(v: &mut Vec<CKey>, start: CKey)

Sort an array of keys, using a start reference.

There is no way to sort keys in an absolute way, since they are virtually on a circle and wrapping, everything depends on where you start from.

This is why there’s a start parameter.

Examples

use confitul::CKey;

let start = CKey::from(0.7);
let k1 = CKey::from(0.2);
let k2 = CKey::from(0.4);
let k3 = CKey::from(0.3);
let k4 = CKey::from(0.9);
let mut sorted = vec![k1, k2, k3, k4];
CKey::sort(&mut sorted, start);
assert_eq!(4, sorted.len());
assert_eq!("0.900000000", format!("{}", sorted[0]));
assert_eq!("0.200000000", format!("{}", sorted[1]));
assert_eq!("0.300000000", format!("{}", sorted[2]));
assert_eq!("0.400000000", format!("{}", sorted[3]));

Trait Implementations

impl Add<CKey> for CKey

fn add(self, other: CKey) -> CKey

Add another key.

If the result is outside key space, will loop back, as in wrapping mode. So the result is always within key space.

Examples

use confitul::CKey;

let k1 = CKey::from(0.6f64);
let k2 = CKey::from(0.8f64);
let k_sum = k1 + k2;
assert_eq!("0.400000000", String::from(k_sum));

type Output = CKey

The resulting type after applying the + operator.

impl Add<f64> for CKey

fn add(self, delta: f64) -> CKey

Add an f64.

The value is first converted to a key, considering key space goes from 0 to 1.

Examples

use confitul::CKey;

let k = CKey::from(0.3f64);
assert_eq!("0.700000000", String::from(k + 0.4f64));

type Output = CKey

The resulting type after applying the + operator.

impl Add<u32> for CKey

fn add(self, delta: u32) -> CKey

Add a u32.

The value is first converted to a key, considering key space goes from 0 to 2^32.

Examples

use confitul::CKey;

let k = CKey::from(0.1f64);
assert_eq!("0.100232831", String::from(k + 1_000_000u32))

type Output = CKey

The resulting type after applying the + operator.

impl Add<u64> for CKey

fn add(self, delta: u64) -> CKey

Add a u64.

The value is first converted to a key, considering key space goes from 0 to 2^64.

Examples

use confitul::CKey;

let k = CKey::from(0.1f64);
assert_eq!("0.100542101", String::from(k + 10_000_000_000_000_000u64))

type Output = CKey

The resulting type after applying the + operator.

impl Clone for CKey

fn clone(&self) -> CKey

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CKey

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Debug-print a key.

The representation we use is an hex dump, the way you would write down the 2^256 integer corresponding to the key.

Examples

use confitul::CKey;
use std::convert::TryFrom;

let k = CKey::parse("12345678ffffffff01234567fffffffff00123456ffffffff0012345ffffffff").unwrap();
assert_eq!("12345678ffffffff01234567fffffffff00123456ffffffff0012345ffffffff", format!("{:?}", k));

impl Default for CKey

fn default() -> CKey

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for CKey

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
    __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for CKey

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Pretty-print a key.

The representation we use is a 9-digits decimal float number, 11 chars in total, including a leading “0.”.

The reason for this is -> 1 billion keys is enough to tell them apart, there CAN be collisions, but it should remain rare. To check for equality, use == operator, do not compare string reprs.

At the same time, decimals between 0 and 1 are easier to reason about when debugging, much more than 64 chars hexa dumps.

Examples

use confitul::CKey;
use std::convert::TryFrom;

let k = CKey::parse("12345678ffffffff01234567fffffffff00123456ffffffff0012345ffffffff").unwrap();
assert_eq!("0.071111111", format!("{}", k));

impl From<CKey> for String

fn from(k: CKey) -> String

Try to convert to a String.

The representation it gives is the fmt::Display impl, which gives a short (not complete/unique) yet readable representation of the key, as a floating point from 0 to 1.

Examples

use confitul::CKey;

let k = CKey::from(0.6 as f64);
assert_eq!("0.600000000", String::from(k));

impl From<CKey> for f64

fn from(k: CKey) -> f64

Convert to an f64, considering the ring goes from 0 to 1.

Examples

use confitul::CKey;
use std::convert::TryFrom;

let k = CKey::parse("123456ffffffffffffffffffffffffffffffffffffffffffffffffffffffffff").unwrap();
assert_eq!("0.071111143", format!("{:0.9}", f64::from(k)));

impl From<CKey> for u32

fn from(k: CKey) -> u32

Convert to a u32, considering the ring goes from 0 to 2^32.

Examples

use confitul::CKey;
use std::convert::TryFrom;

let k = CKey::parse("123456ffffffffffffffffffffffffffffffffffffffffffffffffffffffffff").unwrap();
assert_eq!(305420031, u32::from(k));

impl From<CKey> for u64

fn from(k: CKey) -> u64

Convert to a u64, considering the ring goes from 0 to 2^64.

Examples

use confitul::CKey;
use std::convert::TryFrom;

let k = CKey::parse("123456ffffffffffffffffffffffffffffffffffffffffffffffffffffffffff").unwrap();
assert_eq!(1311769048983273471, u64::from(k));

impl From<f64> for CKey

fn from(f: f64) -> CKey

Convert from an f64, considering the ring goes from 0 to 1.

Examples

use confitul::CKey;

let k = CKey::from(0.5f64);
assert_eq!("0.500000000", format!("{}", k));

impl From<u32> for CKey

fn from(u: u32) -> CKey

Convert from a u32, considering the ring goes from 0 to 2^32.

Examples

use confitul::CKey;

let k = CKey::from(1073741824u32);
assert_eq!("0.250000000", format!("{}", k));

impl From<u64> for CKey

fn from(u: u64) -> CKey

Convert from a u64, considering the ring goes from 0 to 2^64.

Examples

use confitul::CKey;

let k = CKey::from(1000000000000000000u64);
assert_eq!("0.054210109", format!("{}", k));

impl Hash for CKey

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where
    H: Hasher,
    Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq<CKey> for CKey

fn eq(&self, other: &CKey) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for CKey

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>where
    __S: Serializer,

Serialize this value into the given Serde serializer.

impl Sub<CKey> for CKey

fn sub(self, other: CKey) -> CKey

Sub another key.

If the result is outside key space, will loop back, as in wrapping mode. So the result is always within key space.

Examples

use confitul::CKey;

let k1 = CKey::from(0.5f64);
let k2 = CKey::from(0.9f64);
let k_diff = k1 - k2;
assert_eq!("0.600000000", String::from(k_diff));

type Output = CKey

The resulting type after applying the - operator.

impl Sub<f64> for CKey

fn sub(self, delta: f64) -> CKey

Sub an f64.

The value is first converted to a key, considering key space goes from 0 to 1.

Examples

use confitul::CKey;

let k = CKey::from(0.3f64);
assert_eq!("0.900000000", String::from(k - 0.4f64));

type Output = CKey

The resulting type after applying the - operator.

impl Sub<u32> for CKey

fn sub(self, delta: u32) -> CKey

Sub a u32.

The value is first converted to a key, considering key space goes from 0 to 2^32.

Examples

use confitul::CKey;

let k = CKey::from(0.1f64);
assert_eq!("0.099767169", String::from(k - 1_000_000u32))

type Output = CKey

The resulting type after applying the - operator.

impl Sub<u64> for CKey

fn sub(self, delta: u64) -> CKey

Sub a u64.

The value is first converted to a key, considering key space goes from 0 to 2^64.

Examples

use confitul::CKey;

let k = CKey::from(0.1f64);
assert_eq!("0.099457899", String::from(k - 10_000_000_000_000_000u64))

type Output = CKey

The resulting type after applying the - operator.

impl TryFrom<&str> for CKey

fn try_from(value: &str) -> Result<CKey, Self::Error>

Try to convert from a &str.

Examples

use confitul::CKey;
use std::convert::TryFrom;

let k = CKey::try_from("12345678ffffffff01234567fffffffff00123456ffffffff0012345ffffffff").unwrap();
assert_eq!("12345678ffffffff01234567fffffffff00123456ffffffff0012345ffffffff", format!("{:?}", k));

type Error = FromHexError

The type returned in the event of a conversion error.

impl TryFrom<String> for CKey

fn try_from(value: String) -> Result<CKey, Self::Error>

Try to convert from a String.

Examples

use confitul::CKey;
use std::convert::TryFrom;

let k = CKey::try_from(String::from("12345678ffffffff01234567fffffffff00123456ffffffff0012345ffffffff")).unwrap();
assert_eq!("12345678ffffffff01234567fffffffff00123456ffffffff0012345ffffffff", format!("{:?}", k));

type Error = FromHexError

The type returned in the event of a conversion error.

impl Copy for CKey

impl Eq for CKey

impl StructuralEq for CKey

impl StructuralPartialEq for CKey