Struct cstr

pub struct cstr<const N: usize = 32> { /* private fields */ }

This type is only available with the circular-str option. A circular string is represented underneath by a fixed-size u8 array arranged as a circular queue. The string can wrap around either end and thus become internally non-contiguous. This allows for efficient implementations of operations such as push, trim in front of the string. However, Deref<str> is not implemented as it cannot be done efficiently. Instead, the cstr::to_strs function returns a pair of string slices, the second of which is non-empty if the string is not contiguous. Additionally, only single-byte characters are currently allowed, although this might change in the future by using a “ghost vector” at the end of the array. An iterator cstr::chars is provided over all single-byte chars, which also forms the foundation of other traits such as Eq, Ord, Hash, etc. The Serialization (serde) and no-std options are both supported.

Each cstr<N> can hold up to N bytes and the maximum N is 65535. Values of N that are exact powers of 2 are recommended to speed up the % operation for computing indices in a ciruclar queue.

Examples:

 let mut cb = cstr::<16>::make("abc123");
 cb.push_str("xyz");
 cb.push_front("9876");
 assert_eq!(cb.pop_char().unwrap(), 'z');
 assert_eq!(cb.pop_char_front().unwrap(), '9');
 cb.push_str_front("000");
 assert_eq!(cb.len(),14);
 assert!(&cb == "000876abc123xy");
 cb.truncate_left(10);
 assert_eq!(&cb,"23xy");
 cb.push_str("ijklmno  ");
 cb.push_char_front(' ');
 assert!(!cb.is_contiguous());
 cb.trim_whitespaces();
 assert!("23xyijklmno" == &cb);
 assert!(&cb < "4abc");   // Ord trait
 let mut a = cstr8::from("abc");
 let ba:cstr8 = "123" + a; // concat &str on the left efficiently
 assert_eq!(ba,"123abc");

Implementations

impl<const N: usize> cstr<N>

pub fn make(src: &str) -> cstr<N>

create cstr from &str with silent truncation; panics if N is greater than 65535

pub fn from_ascii(src: &str) -> cstr<N>

version of make that also panics if the input string is not ascii.

pub fn try_make(src: &str) -> Result<cstr<N>, &str>

version of make that does not truncate: returns original str slice as error. Also checks if N is no greater than 65535 without panic.

pub fn try_make_ascii(src: &str) -> Option<cstr<N>>

version of try_make that also checks if the input string is ascii.

pub fn make_remainder(src: &str) -> (cstr<N>, &str)

version of make that returns a pair consisting of the made cstr and the remainder &str that was truncated; panics if N is greater than 65535 (but does not check for ascii strings)

pub fn from_pair(left: &str, right: &str) -> Option<cstr<N>>

make from a pair of str slices, does not truncate, and checks that N is not greater than 65535 without panic. The returned cstr will be contiguous.

pub const fn const_make(src: &str) -> cstr<N>

const constructor, to be called from const contexts. However, as const constructors are restricted from using iterators, it’s slightly better to call the non-const constructors in non-const contexts. Truncates automatically.

pub const fn const_try_make(s: &str) -> Result<cstr<N>, &str>

version of const_make that does not truncate.

pub fn is_contiguous(&self) -> bool

checks if the underlying representation of the string is contiguous (without wraparound).

pub fn reset(&mut self)

resets the internal representation of the cstr so that it is represented contiguously, without wraparound. Calling this function has O(n) cost both in terms of speed and memory as it requires a secondary buffer as well as copying.**

pub fn clear(&mut self)

clears string to empty string

pub fn zero(&mut self)

resets string to empty string and clears underlying buffer to contain all zeros.

pub fn make_contiguous(&mut self)

guarantees a contiguous underlying representation of the string. This is a worst-case O(n) operation.

pub fn nth(&self, n: usize) -> Option<char>

returns the nth char of the fstr. Since only single-byte characters are currently supported by the cstr type, this function is the same as Self::nth_bytechar except that n is checked against the length of the string.

pub const fn nth_bytechar(&self, n: usize) -> char

returns the nth byte of the string as a char, does not check n against length of array

pub fn set(&mut self, n: usize, c: char) -> bool

sets the nth byte of the string to the supplied character. the character must fit in a single byte. Returns true on success.

pub fn push_str<'t>(&mut self, src: &'t str) -> &'t str

pushes given string to the end of the string, returns remainder

pub fn push_front<'t>(&mut self, src: &'t str) -> &'t str

Pushes string to the front of the string, returns remainder. because of the circular-queue backing, this operation has the same cost as pushing to the back of the string (Self::push_str). This function does not check if the input string is ascii.

pub fn push_str_front<'t>(&mut self, src: &'t str) -> &'t str

alias for Self::push_front

pub fn push_char(&mut self, c: char) -> bool

Pushes a single character to the end of the string, returning true on success. This function checks if the given character occupies a single-byte.

pub fn push_char_front(&mut self, c: char) -> bool

Pushes a single character to the front of the string, returning true on success. This function checks if the given character occupies a single-byte.

pub fn pop_char(&mut self) -> Option<char>

remove and return last character in string, if it exists

pub fn pop_char_front(&mut self) -> Option<char>

remove and return first character in string, if it exists

pub fn truncate_right(&mut self, n: usize)

alias for Self::truncate

pub fn truncate(&mut self, n: usize)

right-truncates string up to byte position n. Only the first n bytes will be kept. No effect if n is greater than or equal to the length of the string.

pub fn truncate_left(&mut self, n: usize)

left-truncates string up to byte position n: that is, the first n bytes will be truncated. Because of the circular queue backing, this is an O(1) operation. No effect if n is greater than the length of the string.

pub fn truncate_front(&mut self, n: usize)

alias for truncate_left

pub fn find<P>(&self, predicate: P) -> Option<usize>

where P: Fn(char) -> bool,

finds the position of first character that satisfies given predicate

pub fn rfind<P>(&self, predicate: P) -> Option<usize>

where P: Fn(char) -> bool,

finds the position of last character that satisfies given predicate

pub fn find_substr(&self, s: &str) -> Option<usize>

finds position of first matching substring

pub fn rfind_substr(&self, s: &str) -> Option<usize>

finds position of last matching substring

pub fn trim_left(&mut self)

in-place trimming of white spaces at the front of the string

pub fn trim_right(&mut self)

in-place trimming of white spaces at the end of the string

pub fn trim_whitespaces(&mut self)

in-place trimming of white spaces at either end of the string

pub const fn len(&self) -> usize

length of string in bytes

pub const fn new() -> Self

construct new, empty string (same as cstr::default)

pub fn to_strs(&self) -> (&str, &str)

returns a pair of string slices (left,right) which, when concatenated, will yield an equivalent string underneath. In case of no wraparound, the right str will be empty.

pub fn chars<'a>(&'a self) -> CircCharIter<'a>

returns iterator over the characters of the string

pub fn iter<'a>(&'a self) -> CircCharIter<'a>

alias for [Self.chars]

pub fn to_contiguous(&self) -> cstr<N>

returns a copy of the same string that is contiguous underneath. This may call cstr::reset, which is an O(n) operation.

pub fn force_str(&self) -> &str

returns a single str slice if the cstr is contiguous underneath, otherwise panics.

pub fn to_string(&self) -> String

converts cstr to an owned string

pub fn substr(&self, start: usize, end: usize) -> cstr<N>

returns a copy of the portion of the string. Will return empty string if indices are invalid. The returned string will be contiguous.

pub fn make_ascii_lowercase(&mut self)

in-place modification of ascii characters to lower-case.

pub fn make_ascii_uppercase(&mut self)

in-place modification of ascii characters to upper-case.

pub fn case_insensitive_eq<TA>(&self, other: TA) -> bool

where TA: AsRef<str>,

Tests for ascii case-insensitive equality with another string. This function does not check if the argument is ascii.

pub fn from_utf16(v: &[u16]) -> Result<Self, Self>

Decodes a UTF-16 encodeded slice. If a decoding error is encountered or capacity exceeded, an Err(s) is returned where s is the the encoded string up to the point of the error. The returned string will be contiguous.

impl<const M: usize> cstr<M>

pub fn resize<const N: usize>(&self) -> cstr<N>

converts an cstr<M> to an cstr<N>. If the length of the string being converted is greater than N, the extra characters are ignored. This operation produces a new string that is contiguous underneath.

pub fn reallocate<const N: usize>(&self) -> Option<cstr<N>>

version of resize that does not allow string truncation due to length

Trait Implementations

impl<const N: usize> Add<&cstr<N>> for &str

type Output = cstr<N>

The resulting type after applying the + operator.

fn add(self, other: &cstr<N>) -> cstr<N>

Performs the + operation.

impl<const N: usize, TA: AsRef<str>> Add<TA> for cstr<N>

type Output = cstr<N>

The resulting type after applying the + operator.

fn add(self, other: TA) -> cstr<N>

Performs the + operation.

impl<const N: usize> Add<cstr<N>> for &str

type Output = cstr<N>

The resulting type after applying the + operator.

fn add(self, other: cstr<N>) -> cstr<N>

Performs the + operation.

impl<const N: usize> Add for &cstr<N>

type Output = cstr<N>

The resulting type after applying the + operator.

fn add(self, other: &cstr<N>) -> cstr<N>

Performs the + operation.

impl<const N: usize> Add for cstr<N>

type Output = cstr<N>

The resulting type after applying the + operator.

fn add(self, other: cstr<N>) -> cstr<N>

Performs the + operation.

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

fn default() -> Self

Returns the “default value” for a type.

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

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

Deserialize this value from the given Serde deserializer.

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

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

Formats the value using the given formatter.

impl<T: AsRef<str> + ?Sized, const N: usize> From<&T> for cstr<N>

fn from(s: &T) -> cstr<N>

Converts to this type from the input type.

impl<T: AsMut<str> + ?Sized, const N: usize> From<&mut T> for cstr<N>

fn from(s: &mut T) -> cstr<N>

Converts to this type from the input type.

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

type Err = &'static str

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

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

Hashing is implemented character-by-character, starting with the last char and ending with the first

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

Feeds this value into the given Hasher.

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 cstr<N>

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

This method returns an Ordering between self and other.

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<&cstr<N>> for &str

fn eq(&self, other: &&cstr<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> PartialEq<&str> for &cstr<N>

fn eq(&self, other: &&str) -> 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> PartialEq<&str> for cstr<N>

fn eq(&self, other: &&str) -> 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, const M: usize> PartialEq<cstr<M>> for cstr<N>

The implementation of this trait allows comparison between circular strings of different capacity. This could affect the type inference of the cstr::resize function.

fn eq(&self, other: &cstr<M>) -> 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> PartialEq<cstr<N>> for &str

fn eq(&self, other: &cstr<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> PartialOrd<&str> for &cstr<N>

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

This method returns an ordering between self and other values if one exists.

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> PartialOrd<&str> for cstr<N>

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

This method returns an ordering between self and other values if one exists.

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> PartialOrd for cstr<N>

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

This method returns an ordering between self and other values if one exists.

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

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

Serialize this value into the given Serde serializer.

impl<const N: usize> Write for cstr<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 cstr<N>

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