Struct Utf8Encoding 

pub struct Utf8Encoding { /* private fields */ }

Implementations

impl Utf8Encoding

pub fn try_from( modulus: u64, encoding_type: Utf8EncodingType, ) -> Result<Self, EncodingError>

Builds an encoding configuration for the provided modulus.

Errors

• Returns EncodingError::ModulusTooSmall if modulus < 2.
• Returns EncodingError::DecodingError when base-m rANS parameters are invalid for the provided modulus.

impl Utf8Encoding

pub fn encode_bytes_base_m_len( &self, bytes: &[u8], ) -> Result<Vec<RingElement>, EncodingError>

Encodes bytes into base-modulus digits with an embedded byte length.

This encoding is length-delimited and self-contained: the output embeds the original byte length (as a fixed-width base-modulus prefix) and uses a uniform rANS transducer to convert the bytes into payload digits, all strictly < modulus.

Target behavior

• Uses all residues: digits are only required to satisfy value < modulus (there is no "[0, 2^b)" restriction as in [encode_bytes]).
• Near-linear time: amortized O(1) work per input byte, plus a constant-size header for the given modulus.
• Padding tolerance: trailing elements do not affect decoding because the decoded length is explicit.
• Same public API: this preserves the existing function signature and high-level behavior (but the on-wire representation is not backward compatible).

Wire format

For k = length_prefix_digits(modulus), the returned element sequence is:

• k digits: len as a u64 in base modulus (little-endian),
• k digits: state as a u64 in base modulus (little-endian),
• n digits: payload stream digits produced by uniform rANS (each < modulus).

The payload digit count n depends on bytes.len() and modulus.

The rANS state is placed immediately after the length prefix so decoding can proceed FIFO (left-to-right): read len, read state, then consume as many payload digits as needed to emit exactly len bytes.

Decoding behavior

[decode_bytes_base_m_len] uses the embedded len to decode exactly that many bytes and ignores any trailing elements beyond what is required. This makes the representation robust to padding or garbage appended at the end.

Complexity

Near-linear in bytes.len() (amortized O(1) renormalization per byte), avoiding quadratic base-conversion of large payloads.

Compatibility

This is not compatible with older *_base_m_len encodings that used a different payload conversion scheme.

Errors

• Returns EncodingError::ModulusTooSmall if modulus < 2.
• Returns EncodingError::DecodingError if the byte length does not fit in u64 or if valid rANS parameters cannot be chosen for the given modulus.

pub fn decode_bytes_base_m_len( &self, elements: &[RingElement], ) -> Result<Vec<u8>, EncodingError>

Decodes bytes encoded by [encode_bytes_base_m_len].

This parses the fixed-width base-modulus len prefix and state, then uses the uniform rANS decoder to reconstruct exactly len bytes.

Any trailing elements after the consumed payload are ignored, so appending zero-padding or garbage does not change the decoded result.

Decoding is FIFO: it reads the len prefix, then the fixed-width state, and then consumes only as many payload digits as needed to emit len bytes.

Errors

• Returns EncodingError::DecodingError if the stream is malformed (not enough prefix/payload digits, out-of-range digits, invalid state, or length that does not fit in usize).

pub fn encode_text_base_m_len( &self, text: &str, ) -> Result<Vec<RingElement>, EncodingError>

Encodes a UTF-8 string using [encode_bytes_base_m_len].

Errors

• Propagates any error returned by Self::encode_bytes_base_m_len.

pub fn decode_text_base_m_len( &self, elements: &[RingElement], ) -> Result<String, EncodingError>

Decodes text encoded by [encode_text_base_m_len].

This is [decode_bytes_base_m_len] followed by UTF-8 validation.

Errors

• Returns EncodingError::DecodingError if the element stream is malformed or the decoded bytes are not valid UTF-8.

impl Utf8Encoding

pub fn encode_bytes(&self, bytes: &[u8]) -> Vec<RingElement>

Encodes a byte slice into a sequence of RingElements.

The input bytes are treated as a little-endian bitstream and packed into chunks of b bits, where b = floor(log2(modulus)). Each chunk becomes the value of a RingElement with the provided modulus.

This encoding uses only values in the range [0, 2^b), which is always a subset of the ring when modulus is not a power of two.

Notes

• The output does not carry the original byte length. If the final chunk is only partially filled, it is emitted with implicit zero-padding in the high bits. For some moduli (notably when b > 8), this can cause decoding to produce extra trailing 0x00 bytes unless you truncate to the original length.

pub fn decode_bytes(&self, elements: &[RingElement]) -> Vec<u8>

Decodes a sequence of RingElements back into bytes.

This reconstructs the same little-endian bitstream produced by [encode_bytes], assuming b = floor(log2(modulus)) bits of payload per element and emitting 8-bit bytes from the stream.

Notes

• This function does not validate that the provided modulus matches the modulus stored in each element; they must agree for meaningful results.
• This function assumes each element value fits in b bits (i.e., it lies in [0, 2^b)) as produced by [encode_bytes]. If elements were modified (or originate elsewhere), higher bits can leak into the reconstructed byte stream.
• Because the encoding does not include the original length, decoding may yield extra trailing 0x00 bytes for some parameter choices; truncate to the known original length when exact recovery is required.

Panics

Panics only if an internal invariant is violated and extracting the low 8 bits of the bit buffer fails to fit in a u8.

pub fn encode_text(&self, text: &str) -> Vec<RingElement>

Encodes a UTF-8 string as bytes using [encode_bytes].

pub fn decode_text( &self, elements: &[RingElement], ) -> Result<String, EncodingError>

Decodes elements into bytes with [decode_bytes] and interprets them as UTF-8.

Errors

• Returns EncodingError::DecodingError if the decoded bytes are not valid UTF-8.

Notes

This encoding does not embed the original byte length. Depending on the modulus and upstream padding, the decoded byte stream may contain trailing 0x00 bytes, which are valid UTF-8 and will appear as \0 characters in the returned string.