Struct ciphercore_base::data_values::Value

pub struct Value { /* private fields */ }

A structure that stores pointer to a value that corresponds to an input, output or an intermediate result of a computation.

A value is:

• Either a vector of bytes (for scalars or arrays);
• Or a vector of pointers to other values (for vectors, tuples or named tuples).

Overall, a value can be seen as a rooted tree of byte vectors.

Clone trait duplicates the pointer, not the underlying value (see Value::deep_clone for deep cloning).

PartialEq trait performs the deep recursive comparison.

Implementations

impl Value

pub fn deep_clone(&self) -> Value

Creates a fully disjoint clone of self via recursive traversal.

Returns

Clone of self

pub fn deep_hash<H: Hasher>(&self, state: &mut H)

Hashes self via recursive traversal.

Arguments

state - hasher used for hashing

impl Value

pub fn from_bytes(bytes: Vec<u8>) -> Self

Constructs a value from a given byte buffer.

Not recommended to be used directly (instead, please use higher-level wrappers such as Value::from_scalar).

Arguments

bytes - byte vector

Returns

New value

pub fn from_vector(v: Vec<Value>) -> Self

Constructs a value from a vector of other values.

Arguments

v - vector of values

Returns

New value constructed from v

Examples

let v = Value::from_vector(
    vec![
        Value::from_bytes(vec![1, 2, 3]),
        Value::from_bytes(vec![4, 5, 6]),
        Value::from_vector(vec![])]);

pub fn from_scalar<T: TryInto<u64> + Not<Output = T> + TryInto<u8> + Copy>(
    x: T,
    st: ScalarType
) -> Result<Self>

Constructs a value from a given bit or integer scalar.

Arguments

• x - scalar to be converted to a value, can be of any standard integer type
• st - scalar type corresponding to x

Returns

New value constructed from x

Examples

let v = Value::from_scalar(-123456, INT32).unwrap();
v.access_bytes(|bytes| {
    assert_eq!(*bytes, vec![192, 29, 254, 255]);
    Ok(())
}).unwrap();

pub fn from_flattened_array<T: TryInto<u64> + Not<Output = T> + TryInto<u8> + Copy>(
    x: &[T],
    st: ScalarType
) -> Result<Value>

Constructs a value from a flattened bit or integer array.

Arguments

• x - array to be converted to a value, can have entries of any standard integer type
• st - scalar type corresponding to the entries of x

Returns

New value constructed from x

Examples

let v = Value::from_flattened_array(&[0, 1, 1, 0, 1, 0, 0, 1], BIT).unwrap();
v.access_bytes(|bytes| {
    assert_eq!(*bytes, vec![150]);
    Ok(())
}).unwrap();

pub fn from_ndarray<T: TryInto<u64> + Not<Output = T> + TryInto<u8> + Copy>(
    a: ArrayD<T>,
    st: ScalarType
) -> Result<Value>

Constructs a value from a multi-dimensional bit or integer array.

Arguments

• x - array to be converted to a value, can have entries of any standard integer type
• st - scalar type corresponding to the entries of x

Returns

New value constructed from x

Examples

let a = array![[0, 1, 1, 0], [1, 0, 0, 1]].into_dyn();
let v = Value::from_ndarray(a, BIT).unwrap();
v.access_bytes(|bytes| {
    assert_eq!(*bytes, vec![150]);
    Ok(())
}).unwrap();

pub fn to_u8(&self, st: ScalarType) -> Result<u8>

Converts self to a scalar if it is a byte vector, then casts the result to u8.

Arguments

st - scalar type used to interpret self

Result

Resulting scalar cast to u8

Examples

let v = Value::from_scalar(-123456, INT32).unwrap();
assert_eq!(v.to_u8(INT32).unwrap(), -123456i32 as u8);

pub fn to_i8(&self, st: ScalarType) -> Result<i8>

Converts self to a scalar if it is a byte vector, then casts the result to i8.

Arguments

st - scalar type used to interpret self

Result

Resulting scalar cast to i8

Examples

let v = Value::from_scalar(-123456, INT32).unwrap();
assert_eq!(v.to_i8(INT32).unwrap(), -123456i32 as i8);

pub fn to_u16(&self, st: ScalarType) -> Result<u16>

Converts self to a scalar if it is a byte vector, then casts the result to u16.

Arguments

st - scalar type used to interpret self

Result

Resulting scalar cast to u16

Examples

let v = Value::from_scalar(-123456, INT32).unwrap();
assert_eq!(v.to_u16(INT32).unwrap(), -123456i32 as u16);

pub fn to_i16(&self, st: ScalarType) -> Result<i16>

Converts self to a scalar if it is a byte vector, then casts the result to i16.

Arguments

st - scalar type used to interpret self

Result

Resulting scalar cast to i16

Examples

let v = Value::from_scalar(-123456, INT32).unwrap();
assert_eq!(v.to_i16(INT32).unwrap(), -123456i32 as i16);

pub fn to_u32(&self, st: ScalarType) -> Result<u32>

Converts self to a scalar if it is a byte vector, then casts the result to u32.

Arguments

st - scalar type used to interpret self

Result

Resulting scalar cast to u32

Examples

let v = Value::from_scalar(-123456, INT32).unwrap();
assert_eq!(v.to_u32(INT32).unwrap(), -123456i32 as u32);

pub fn to_i32(&self, st: ScalarType) -> Result<i32>

Converts self to a scalar if it is a byte vector, then casts the result to i32.

Arguments

st - scalar type used to interpret self

Result

Resulting scalar cast to i32

Examples

let v = Value::from_scalar(-123456, INT32).unwrap();
assert_eq!(v.to_i32(INT32).unwrap(), -123456i32 as i32);

pub fn to_u64(&self, st: ScalarType) -> Result<u64>

Converts self to a scalar if it is a byte vector, then casts the result to u64.

Arguments

st - scalar type used to interpret self

Result

Resulting scalar cast to u64

Examples

let v = Value::from_scalar(-123456, INT32).unwrap();
assert_eq!(v.to_u64(INT32).unwrap(), -123456i32 as u32 as u64);

pub fn to_i64(&self, st: ScalarType) -> Result<i64>

Converts self to a scalar if it is a byte vector, then cast the result to i64.

Arguments

st - scalar type used to interpret self

Result

Resulting scalar cast to i64

Examples

let v = Value::from_scalar(-123456, INT32).unwrap();
assert_eq!(v.to_i64(INT32).unwrap(), -123456i32 as u32 as i64);

pub fn to_vector(&self) -> Result<Vec<Value>>

Converts self to a vector of values or return an error if self is a byte vector.

Returns

Extracted vector of values

Examples

let v = Value::from_vector(
    vec![
        Value::from_vector(vec![]),
        Value::from_bytes(vec![1, 2, 3])]);
let vv = v.to_vector().unwrap();
assert_eq!(vv.len(), 2);
vv[0].access_vector(|v| {
    assert_eq!(*v, Vec::<Value>::new());
    Ok(())
}).unwrap();
vv[1].access_bytes(|bytes| {
    assert_eq!(*bytes, vec![1, 2, 3]);
    Ok(())
}).unwrap();

pub fn to_flattened_array_u8(&self, t: Type) -> Result<Vec<u8>>

Converts self to a flattened array if it is a byte vector, then cast the array entries to u8.

Arguments

t - array type used to interpret self

Result

Resulting flattened array with entries cast to u8

Examples

let v = Value::from_flattened_array(&[-123, 123], INT32).unwrap();
let a = v.to_flattened_array_u8(array_type(vec![2], INT32)).unwrap();
assert_eq!(a, vec![-123i32 as u8, 123i32 as u8]);

pub fn to_flattened_array_i8(&self, t: Type) -> Result<Vec<i8>>

Converts self to a flattened array if it is a byte vector, then cast the array entries to i8.

Arguments

t - array type used to interpret self

Result

Resulting flattened array with entries cast to i8

Examples

let v = Value::from_flattened_array(&[-123, 123], INT32).unwrap();
let a = v.to_flattened_array_i8(array_type(vec![2], INT32)).unwrap();
assert_eq!(a, vec![-123i32 as i8, 123i32 as i8]);

pub fn to_flattened_array_u16(&self, t: Type) -> Result<Vec<u16>>

Converts self to a flattened array if it is a byte vector, then cast the array entries to u16.

Arguments

t - array type used to interpret self

Result

Resulting flattened array with entries cast to u16

Examples

let v = Value::from_flattened_array(&[-123, 123], INT32).unwrap();
let a = v.to_flattened_array_u16(array_type(vec![2], INT32)).unwrap();
assert_eq!(a, vec![-123i32 as u16, 123i32 as u16]);

pub fn to_flattened_array_i16(&self, t: Type) -> Result<Vec<i16>>

Converts self to a flattened array if it is a byte vector, then cast the array entries to i16.

Arguments

t - array type used to interpret self

Result

Resulting flattened array with entries cast to i16

Examples

let v = Value::from_flattened_array(&[-123, 123], INT32).unwrap();
let a = v.to_flattened_array_i16(array_type(vec![2], INT32)).unwrap();
assert_eq!(a, vec![-123i32 as i16, 123i32 as i16]);

pub fn to_flattened_array_u32(&self, t: Type) -> Result<Vec<u32>>

Converts self to a flattened array if it is a byte vector, then cast the array entries to u32.

Arguments

t - array type used to interpret self

Result

Resulting flattened array with entries cast to u32

Examples

let v = Value::from_flattened_array(&[-123, 123], INT32).unwrap();
let a = v.to_flattened_array_u32(array_type(vec![2], INT32)).unwrap();
assert_eq!(a, vec![-123i32 as u32, 123i32 as u32]);

pub fn to_flattened_array_i32(&self, t: Type) -> Result<Vec<i32>>

Converts self to a flattened array if it is a byte vector, then cast the array entries to i32.

Arguments

t - array type used to interpret self

Result

Resulting flattened array with entries cast to i32

Examples

let v = Value::from_flattened_array(&[-123, 123], INT32).unwrap();
let a = v.to_flattened_array_i32(array_type(vec![2], INT32)).unwrap();
assert_eq!(a, vec![-123i32, 123i32]);

pub fn to_flattened_array_u64(&self, t: Type) -> Result<Vec<u64>>

Converts self to a flattened array if it is a byte vector, then cast the array entries to u64.

Arguments

t - array type used to interpret self

Result

Resulting flattened array with entries cast to u64

Examples

let v = Value::from_flattened_array(&[-123, 123], INT32).unwrap();
let a = v.to_flattened_array_u64(array_type(vec![2], INT32)).unwrap();
assert_eq!(a, vec![-123i32 as u32 as u64, 123i32 as u32 as u64]);

pub fn to_flattened_array_i64(&self, t: Type) -> Result<Vec<i64>>

Converts self to a flattened array if it is a byte vector, then cast the array entries to i64.

Arguments

t - array type used to interpret self

Result

Resulting flattened array with entries cast to i64

Examples

let v = Value::from_flattened_array(&[-123, 123], INT32).unwrap();
let a = v.to_flattened_array_i64(array_type(vec![2], INT32)).unwrap();
assert_eq!(a, vec![-123i32 as u32 as i64, 123i32 as u32 as i64]);

pub fn to_ndarray_u8(&self, t: Type) -> Result<ArrayD<u8>>

Converts self to a multi-dimensional array if it is a byte vector, then cast the array entries to u8.

Arguments

t - array type used to interpret self

Result

Resulting multi-dimensional array with entries cast to u8

Examples

let a = array![[-123, 123], [-456, 456]].into_dyn();
let v = Value::from_ndarray(a, INT32).unwrap();
let a = v.to_ndarray_u8(array_type(vec![2, 2], INT32)).unwrap();
assert_eq!(a, array![[-123i32 as u8, 123i32 as u8], [-456i32 as u8, 456i32 as u8]].into_dyn());

pub fn to_ndarray_i8(&self, t: Type) -> Result<ArrayD<i8>>

Converts self to a multi-dimensional array if it is a byte vector, then cast the array entries to i8.

Arguments

t - array type used to interpret self

Result

Resulting multi-dimensional array with entries cast to i8

Examples

let a = array![[-123, 123], [-456, 456]].into_dyn();
let v = Value::from_ndarray(a, INT32).unwrap();
let a = v.to_ndarray_i8(array_type(vec![2, 2], INT32)).unwrap();
assert_eq!(a, array![[-123i32 as i8, 123i32 as i8], [-456i32 as i8, 456i32 as i8]].into_dyn());

pub fn to_ndarray_u16(&self, t: Type) -> Result<ArrayD<u16>>

Converts self to a multi-dimensional array if it is a byte vector, then cast the array entries to u16.

Arguments

t - array type used to interpret self

Result

Resulting multi-dimensional array with entries cast to u16

Examples

let a = array![[-123, 123], [-456, 456]].into_dyn();
let v = Value::from_ndarray(a, INT32).unwrap();
let a = v.to_ndarray_u16(array_type(vec![2, 2], INT32)).unwrap();
assert_eq!(a, array![[-123i32 as u16, 123i32 as u16], [-456i32 as u16, 456i32 as u16]].into_dyn());

pub fn to_ndarray_i16(&self, t: Type) -> Result<ArrayD<i16>>

Converts self to a multi-dimensional array if it is a byte vector, then cast the array entries to i16.

Arguments

t - array type used to interpret self

Result

Resulting multi-dimensional array with entries cast to i16

Examples

let a = array![[-123, 123], [-456, 456]].into_dyn();
let v = Value::from_ndarray(a, INT32).unwrap();
let a = v.to_ndarray_i16(array_type(vec![2, 2], INT32)).unwrap();
assert_eq!(a, array![[-123i32 as i16, 123i32 as i16], [-456i32 as i16, 456i32 as i16]].into_dyn());

pub fn to_ndarray_u32(&self, t: Type) -> Result<ArrayD<u32>>

Converts self to a multi-dimensional array if it is a byte vector, then cast the array entries to u32.

Arguments

t - array type used to interpret self

Result

Resulting multi-dimensional array with entries cast to u32

Examples

let a = array![[-123, 123], [-456, 456]].into_dyn();
let v = Value::from_ndarray(a, INT32).unwrap();
let a = v.to_ndarray_u32(array_type(vec![2, 2], INT32)).unwrap();
assert_eq!(a, array![[-123i32 as u32, 123i32 as u32], [-456i32 as u32, 456i32 as u32]].into_dyn());

pub fn to_ndarray_i32(&self, t: Type) -> Result<ArrayD<i32>>

Converts self to a multi-dimensional array if it is a byte vector, then cast the array entries to i32.

Arguments

t - array type used to interpret self

Result

Resulting multi-dimensional array with entries cast to i32

Examples

let a = array![[-123, 123], [-456, 456]].into_dyn();
let v = Value::from_ndarray(a, INT32).unwrap();
let a = v.to_ndarray_i32(array_type(vec![2, 2], INT32)).unwrap();
assert_eq!(a, array![[-123i32, 123i32], [-456i32, 456i32]].into_dyn());

pub fn to_ndarray_u64(&self, t: Type) -> Result<ArrayD<u64>>

Converts self to a multi-dimensional array if it is a byte vector, then cast the array entries to u64.

Arguments

t - array type used to interpret self

Result

Resulting multi-dimensional array with entries cast to u64

Examples

let a = array![[-123, 123], [-456, 456]].into_dyn();
let v = Value::from_ndarray(a, INT32).unwrap();
let a = v.to_ndarray_u64(array_type(vec![2, 2], INT32)).unwrap();
assert_eq!(a, array![[-123i32 as u32 as u64, 123i32 as u32 as u64], [-456i32 as u32 as u64, 456i32 as u32 as u64]].into_dyn());

pub fn to_ndarray_i64(&self, t: Type) -> Result<ArrayD<i64>>

Converts self to a multi-dimensional array if it is a byte vector, then cast the array entries to i64.

Arguments

t - array type used to interpret self

Result

Resulting multi-dimensional array with entries cast to i64

Examples

let a = array![[-123, 123], [-456, 456]].into_dyn();
let v = Value::from_ndarray(a, INT32).unwrap();
let a = v.to_ndarray_i64(array_type(vec![2, 2], INT32)).unwrap();
assert_eq!(a, array![[-123i32 as u32 as i64, 123i32 as u32 as i64], [-456i32 as u32 as i64, 456i32 as u32 as i64]].into_dyn());

pub fn check_type(&self, t: Type) -> Result<bool>

Checks if self is a valid value for a given type.

Arguments

t - a type to check a value against

Returns

true if self is a valid value of type t, false otherwise

Examples

assert!(Value::from_bytes(vec![1, 2, 3, 4]).check_type(scalar_type(INT32)).unwrap());
assert!(Value::from_bytes(vec![1, 2, 3, 4]).check_type(scalar_type(UINT32)).unwrap());
assert!(Value::from_bytes(vec![1, 2, 3, 4]).check_type(array_type(vec![2, 2], UINT8)).unwrap());
assert!(Value::from_bytes(vec![1, 2, 3, 4]).check_type(array_type(vec![4, 8], BIT)).unwrap());
assert!(!Value::from_bytes(vec![1, 2, 3, 4]).check_type(array_type(vec![3, 5], BIT)).unwrap());
assert!(!Value::from_bytes(vec![1, 2, 3, 4]).check_type(array_type(vec![5], UINT8)).unwrap());
assert!(!Value::from_bytes(vec![1, 2, 3, 4]).check_type(array_type(vec![3], UINT16)).unwrap());
assert!(!Value::from_bytes(vec![1, 2, 3, 4]).check_type(scalar_type(UINT64)).unwrap());

pub fn access_bytes<F, R>(&self, f: F) -> Result<R> where
    F: FnOnce(&[u8]) -> Result<R>, 

Runs a given closure if self corresponds to a byte vector, and panic otherwise.

Arguments

f - a closure, that takes a reference to a slice of bytes, to run

Returns

Return value of f

Panics

Panics if self is a vector of values.

Examples

let v = Value::from_bytes(vec![1, 2, 3]);
v.access_bytes(|bytes| {
    assert_eq!(*bytes, vec![1, 2, 3]);
    Ok(())
}).unwrap();

pub fn access_vector<F, R>(&self, f: F) -> Result<R> where
    F: FnOnce(&Vec<Value>) -> Result<R>, 

Runs a given closure if self corresponds to a vector of values, and panic otherwise.

Arguments

f - a closure, that takes a reference to a vector of values, to run

Returns

Return value of f

Panics

Panics if self is a byte vector.

Examples

let v = Value::from_vector(vec![]);
v.access_vector(|vector| {
    assert!(vector.is_empty());
    Ok(())
}).unwrap();

pub fn access<FB, FV, R>(&self, f_bytes: FB, f_vector: FV) -> Result<R> where
    FB: FnOnce(&[u8]) -> Result<R>,
    FV: FnOnce(&Vec<Value>) -> Result<R>, 

Runs one closure if self corresponds to a byte vector, and another closure if self corresponds to a vector of values.

Arguments

• f_bytes - a closure, that takes a reference to a slice of bytes, to run if self corresponds to a byte vector
• f_vector - a closure, that takes a reference to a vector of values, to run if self corresponds to a vector of values

Returns

Return value of the called closure

Examples

let v1 = Value::from_vector(vec![]);
let v2 = Value::from_bytes(vec![1, 2, 3]);
v1.access(|bytes| {
    assert!(false);
    Ok(())
},
|vector| {
    assert!(vector.is_empty());
    Ok(())
}).unwrap();
v2.access(|bytes| {
    assert_eq!(*bytes, vec![1, 2, 3]);
    Ok(())
},
|vector| {
    assert!(false);
    Ok(())
}).unwrap();

pub fn zero_of_type(t: Type) -> Value

Generates a value of a given type with all-zero bytes.

Arguments

t - the type of a new value

Returns

“Zero” value of type t

Examples

let v = Value::zero_of_type(array_type(vec![2, 2], INT32));
let a = v.to_ndarray_i32(array_type(vec![2, 2], INT32)).unwrap();
assert_eq!(a, array![[0, 0], [0, 0]].into_dyn());

Trait Implementations

impl Clone for Value

fn clone(&self) -> Value

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Value

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Value

fn deserialize<D>(deserializer: D) -> Result<Value, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl PartialEq<Value> for Value

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

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

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

This method tests for !=.

impl Serialize for Value

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

Serialize this value into the given Serde serializer.

impl Eq for Value

impl StructuralEq for Value

impl StructuralPartialEq for Value