From f4bf9876278ff59fb7105203ab5f75bbcaa53ded Mon Sep 17 00:00:00 2001 From: Trinity Pointard Date: Sat, 20 Mar 2021 20:38:44 +0100 Subject: document util crate --- src/util/data.rs | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'src/util/data.rs') diff --git a/src/util/data.rs b/src/util/data.rs index 8cd6dd96..b269edac 100644 --- a/src/util/data.rs +++ b/src/util/data.rs @@ -1,8 +1,10 @@ +//! Contains common types and functions related to serialization and integrity use rand::Rng; use serde::de::{self, Visitor}; use serde::{Deserialize, Deserializer, Serialize, Serializer}; use std::fmt; +/// An array of 32 bytes #[derive(Default, PartialOrd, Ord, Clone, Hash, PartialEq, Copy)] pub struct FixedBytes32([u8; 32]); @@ -61,15 +63,20 @@ impl Serialize for FixedBytes32 { } impl FixedBytes32 { + /// Access the content as a slice pub fn as_slice(&self) -> &[u8] { &self.0[..] } + /// Access the content as a mutable slice pub fn as_slice_mut(&mut self) -> &mut [u8] { &mut self.0[..] } + /// Copy to a slice pub fn to_vec(&self) -> Vec { self.0.to_vec() } + /// Try building a FixedBytes32 from a slice + /// Return None if the slice is not 32 bytes long pub fn try_from(by: &[u8]) -> Option { if by.len() != 32 { return None; @@ -80,9 +87,12 @@ impl FixedBytes32 { } } +/// A 32 bytes UUID pub type UUID = FixedBytes32; +/// A 256 bit cryptographic hash, can be sha256 or blake2 depending on provenance pub type Hash = FixedBytes32; +/// Compute the sha256 of a slice pub fn sha256sum(data: &[u8]) -> Hash { use sha2::{Digest, Sha256}; @@ -93,6 +103,7 @@ pub fn sha256sum(data: &[u8]) -> Hash { hash.into() } +/// Compute the blake2 of a slice pub fn blake2sum(data: &[u8]) -> Hash { use blake2::{Blake2b, Digest}; @@ -103,8 +114,10 @@ pub fn blake2sum(data: &[u8]) -> Hash { hash.into() } +/// A 64 bit non cryptographic hash pub type FastHash = u64; +/// Compute a (non cryptographic) of a slice pub fn fasthash(data: &[u8]) -> FastHash { use xxhash_rust::xxh3::Xxh3; @@ -113,12 +126,14 @@ pub fn fasthash(data: &[u8]) -> FastHash { h.digest() } +/// Generate a random 32 bytes UUID pub fn gen_uuid() -> UUID { rand::thread_rng().gen::<[u8; 32]>().into() } // RMP serialization with names of fields and variants +/// Serialize to MessagePack pub fn rmp_to_vec_all_named(val: &T) -> Result, rmp_serde::encode::Error> where T: Serialize + ?Sized, @@ -131,10 +146,13 @@ where Ok(wr) } +/// Serialize to JSON, truncating long result pub fn debug_serialize(x: T) -> String { match serde_json::to_string(&x) { Ok(ss) => { if ss.len() > 100 { + // TODO this can panic if 100 is not a codepoint boundary, but inside a 2 Bytes + // (or more) codepoint ss[..100].to_string() } else { ss -- cgit v1.2.3 From b476b702c8a1e4027a1abc16d54afbd61fdcf984 Mon Sep 17 00:00:00 2001 From: Trinity Pointard Date: Mon, 22 Mar 2021 00:01:44 +0100 Subject: run cargo fmt on util and make missing doc warning --- src/util/data.rs | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'src/util/data.rs') diff --git a/src/util/data.rs b/src/util/data.rs index b269edac..34ee8a18 100644 --- a/src/util/data.rs +++ b/src/util/data.rs @@ -63,20 +63,20 @@ impl Serialize for FixedBytes32 { } impl FixedBytes32 { - /// Access the content as a slice + /// Access the content as a slice pub fn as_slice(&self) -> &[u8] { &self.0[..] } - /// Access the content as a mutable slice + /// Access the content as a mutable slice pub fn as_slice_mut(&mut self) -> &mut [u8] { &mut self.0[..] } - /// Copy to a slice + /// Copy to a slice pub fn to_vec(&self) -> Vec { self.0.to_vec() } - /// Try building a FixedBytes32 from a slice - /// Return None if the slice is not 32 bytes long + /// Try building a FixedBytes32 from a slice + /// Return None if the slice is not 32 bytes long pub fn try_from(by: &[u8]) -> Option { if by.len() != 32 { return None; @@ -151,8 +151,8 @@ pub fn debug_serialize(x: T) -> String { match serde_json::to_string(&x) { Ok(ss) => { if ss.len() > 100 { - // TODO this can panic if 100 is not a codepoint boundary, but inside a 2 Bytes - // (or more) codepoint + // TODO this can panic if 100 is not a codepoint boundary, but inside a 2 Bytes + // (or more) codepoint ss[..100].to_string() } else { ss -- cgit v1.2.3