Struct Format 

pub struct Format<const N: usize> { /* private fields */ }

Formatted string.

This is a low-level construct which allows to efficiently work with strings that contain a predefined number of components separated by : characters. If a component contains a : itself, it is percent-encoded, indicated by a flag. This is slower, but not expected to be common.

Formatted strings are optimized for very fast conversion with FromStr or gradual construction through Format::builder, which both produce an immutable instance. To make sure cloning is fast, it’s recommended to wrap the encapsulating type, Selector or Id, in an Arc.

This implementation is currently limited to 64 spans, which should probably be sufficient for all use cases that can ever happen. For our means, an u8 would be more than enough, but since Rust will align the field to 64 bits anyway, there’s no point in being cheap.

Examples

use zrx_id::format::Format;

// Create formatted string builder
let mut builder = Format::<3>::builder();
builder.set(0, "a");
builder.set(1, "b");
builder.set(2, "c");

// Create formatted string from builder
let format = builder.build()?;

// Obtain string representation
assert_eq!(format.as_str(), "a:b:c");

Implementations

impl<const N: usize> Format<N>

pub fn builder<'a>() -> Builder<'a, N>

Creates a formatted string builder.

Examples

use zrx_id::format::Format;

// Create formatted string builder
let mut builder = Format::<3>::builder();

pub fn to_builder(&self) -> Builder<'_, N>

Creates a formatted string builder from the formatted string.

This method creates a builder from the current formatted string, which allows to modify components and build a new formatted string.

Examples

use zrx_id::format::Format;

// Create formatted string from string
let format: Format::<3> = "a:b:c".parse()?;

// Create formatted string builder
let mut builder = format.to_builder();
builder.set(2, "d");

// Create formatted string from builder
let format = builder.build()?;
assert_eq!(format.as_str(), "a:b:d");

impl<const N: usize> Format<N>

pub fn get(&self, index: usize) -> Cow<'_, str>

Returns the value at the index.

If the value is not percent-encoded, which means it does not contain a : character, a borrowed reference is returned which is essentially a zero-cost operation and expected to be the common case. Otherwise, the value is percent-decoded and an owned value is returned.

Panics

Panics if the index is out of bounds. Since Format is a low-level construct, we don’t expect this to happen, as indices should be known.

Examples

use zrx_id::format::Format;

// Create formatted string builder
let mut builder = Format::<3>::builder();
builder.set(0, "a");
builder.set(1, "b");
builder.set(2, "c");

// Create formatted string from builder
let format = builder.build()?;

// Obtain value at index
assert_eq!(format.get(0), "a");

pub fn as_str(&self) -> &str

Returns the string representation.

Examples

use zrx_id::format::Format;

// Create formatted string builder
let mut builder = Format::<3>::builder();
builder.set(0, "a");
builder.set(1, "b");
builder.set(2, "c");

// Create formatted string from builder
let format = builder.build()?;

// Obtain string representation
assert_eq!(format.as_str(), "a:b:c");

Trait Implementations

impl AsRef<Format<7>> for Id

fn as_ref(&self) -> &Format<7>

Returns the formatted string.

Note that it’s normally not necessary to access the formatted string directly, as all components can be accessed via the respective methods. We need to access the underlying formatted string in our internal APIs, e.g., to compute the Specificity for the given Id.

impl AsRef<Format<7>> for Selector

fn as_ref(&self) -> &Format<7>

Returns the formatted string.

Note that it’s normally not necessary to access the formatted string directly, as all components can be accessed via the respective methods. We need to access the underlying formatted string in our internal APIs, e.g., to compute the Specificity for the given Selector.

impl<const N: usize> Clone for Format<N>

fn clone(&self) -> Format<N>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<const N: usize> Debug for Format<N>

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

Formats the formatted string for debugging.

impl<const N: usize> Display for Format<N>

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

Formats the formatted string for display.

impl<const N: usize> FromStr for Format<N>

fn from_str(value: &str) -> Result<Self>

Attempts to create a formatted string from a string.

Errors

If the span number is off, Error::Mismatch is returned.

Examples

use zrx_id::format::Format;

// Create formatted string from string
let format: Format::<3> = "a:b:c".parse()?;
assert_eq!(format.as_str(), "a:b:c");

type Err = Error

The associated error which can be returned from parsing.

impl<const N: usize> Hash for Format<N>

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

Hashes the formatted string.

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<const N: usize> Ord for Format<N>

fn cmp(&self, other: &Self) -> Ordering

Orders two formatted strings.

Examples

use zrx_id::format::Format;

// Create and compare formatted strings
let a: Format::<3> = "b:c:d".parse()?;
let b: Format::<3> = "a:b:c".parse()?;
assert!(a > b);

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<const N: usize> PartialEq for Format<N>

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

Compares two formatted strings for equality.

Examples

use zrx_id::format::Format;

// Create and compare formatted strings
let a: Format::<3> = "a:b:c".parse()?;
let b: Format::<3> = "a:b:c".parse()?;
assert_eq!(a, b);

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

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

impl<const N: usize> PartialOrd for Format<N>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

Orders two formatted strings.

Examples

use zrx_id::format::Format;

// Create and compare formatted strings
let a: Format::<3> = "b:c:d".parse()?;
let b: Format::<3> = "a:b:c".parse()?;
assert!(a > b);

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<const N: usize> Eq for Format<N>