Struct AsciiStr 

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

Fixed-capacity, stack-only ASCII string stored in a single [u8; N] array.

The string is stored as raw bytes. Its logical length is determined at runtime by the position of the first nul byte (b'\0'). All bytes after the string content are guaranteed to be zero.

Implementations

impl<const N: usize> AsciiStr<N>

pub const WIRE_SIZE: usize = N

Size of the wire representation in bytes (always equal to the capacity N).

pub const DEFAULT: Self

pub const fn new() -> Self

Creates a new empty AsciiStr (all bytes zero).

pub fn to_wire_bytes(&self) -> [u8; N]

Serializes this AsciiStr into a fixed-size byte array.

The entire internal buffer is written (including trailing zeros after the logical string content). This preserves the exact representation.

pub fn from_wire_bytes(bytes: &[u8]) -> Option<Self>

Deserializes an AsciiStr<N> from exactly N bytes.

The input must be valid ASCII. Any bytes after the first nul byte must be zero (as required by the type invariant).

Returns None if the input is not valid ASCII or violates the internal representation rules.

pub fn try_from_filled_buffer(buffer: [u8; N]) -> Result<Self, AsciiStrError>

Attempts to create an AsciiStr<N> from a raw byte buffer safely.

This is the public, validated counterpart to the internal from_filled_buffer.

It performs full validation:

• All bytes must be valid ASCII.
• Every byte after the first b'\0' must be zero (preserves the nul-terminated + trailing-zeros invariant).

Use this when you have untrusted or externally-supplied bytes (network packets, C strftime output, user input, etc.).

This method (and the entire public API) is completely panic-free. All fallible operations return Result or Option.

Errors

• AsciiStrError::InvalidAscii if the buffer contains non-ASCII bytes.
• AsciiStrError::CorruptedData if bytes after the first nul are not all zero (violates the representation invariant).

pub fn try_from_str(s: &str) -> Result<Self, AsciiStrError>

Attempts to create an AsciiStr<N> from a string slice.

Errors

• AsciiStrError::InvalidAscii if the input is not ASCII.
• AsciiStrError::TooLong if the input exceeds capacity N.

pub fn try_from_str_upper(s: &str) -> Result<Self, AsciiStrError>

Attempts to create an AsciiStr<N> from a string slice, uppercasing the input.

This is a convenience wrapper around try_from_str that converts the input to ASCII uppercase before storing it.

Errors

• AsciiStrError::InvalidAscii if the input is not ASCII.
• AsciiStrError::TooLong if the input exceeds capacity N.

pub fn as_str(&self) -> Result<&str, AsciiStrError>

Returns the stored string as &str.

The length is computed by locating the first nul byte.

Errors

Returns AsciiStrError::CorruptedData only if the internal data has become invalid UTF-8 (unreachable via safe constructors).

pub fn as_bytes(&self) -> &[u8]

Returns the raw bytes of the stored string (excluding the trailing nul).

pub fn len(&self) -> usize

Returns the current logical length of the string.

pub const fn is_empty(&self) -> bool

Returns true if the string is empty.

pub const fn capacity(&self) -> usize

Returns the fixed maximum capacity of this type (always N).

pub fn from_str_truncate(s: &str) -> Self

Creates an AsciiStr from a &str, truncating if it exceeds capacity N.

Non-ASCII characters are allowed.

pub fn from_display<T: Display>(value: T) -> Self

Creates an AsciiStr from any type that implements Display. The output is truncated if it exceeds capacity N.

Very useful for embedding numbers, paths, etc. into errors.

pub fn from_fmt(args: Arguments<'_>) -> Self

Convenience: create from a format string (most ergonomic for errors)

Trait Implementations

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

fn clone(&self) -> AsciiStr<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 AsciiStr<N>

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

Formats the value using the given formatter.

impl<const N: usize> Default for AsciiStr<N>

fn default() -> Self

Returns the “default value” for a type.

impl<'de, const N: usize> Deserialize<'de> for AsciiStr<N>

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

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

fn eq(&self, other: &AsciiStr<N>) -> bool

Tests for self and other values to be equal, and is used by ==.

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> Serialize for AsciiStr<N>

Available on crate feature serde only.

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<const N: usize> TryFrom<&str> for AsciiStr<N>

type Error = AsciiStrError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl<const N: usize> TryFrom<[u8; N]> for AsciiStr<N>

fn try_from(buffer: [u8; N]) -> Result<Self, Self::Error>

Attempts to create an AsciiStr<N> from a filled buffer.

This is the idiomatic, completely panic-free way to construct from a byte array using the ? operator or .unwrap_or_else().

type Error = AsciiStrError

The type returned in the event of a conversion error.

impl<const N: usize> Write for AsciiStr<N>

fn write_str(&mut self, s: &str) -> Result

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a char into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Glue for usage of the write! macro with implementors of this trait.

impl<const N: usize> Copy for AsciiStr<N>

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

impl<const N: usize> StructuralPartialEq for AsciiStr<N>