Struct TStr 

pub struct TStr<S>(/* private fields */);

A type-level string type, emulates a &'static str const parameter.

This type is zero-sized and has an alignment of 1.

Examples

Emulating named parameters

This example demonstrates how you can use TStr to emulate functions with named parameters overloaded by the name of the parameters.

use tstr::{IsTStr, TS, TStr, ts};

use std::{collections::HashMap, hash::RandomState};

{
    // equivalent to HashMap::new
    let mut map = HashMap::make(args!());
    assert!(map.capacity() == 0);
    map.insert(0, "");;
}
{
    // equivalent to HashMap::with_capacity
    let mut map = HashMap::make(args!(capacity: 10));
    assert!(map.capacity() >= 10);
    map.insert(0, "");;
}
{
    // equivalent to HashMap::with_hasher
    let mut map = HashMap::make(args!(hasher: RandomState::new()));
    assert!(map.capacity() == 0);
    map.insert(0, "");;
}
{
    // equivalent to HashMap::with_capacity_and_hasher
    let mut map = HashMap::make(args!(capacity: 10, hasher: RandomState::new()));
    assert!(map.capacity() >= 10);
    map.insert(0, "");;
}

/// The struct that encodes a named parameter by taking two arguments:
//  - a `TStr` that encodes the name at the type level
/// - the type of the argument.
///
/// The parameter list as a whole is a tuple of this struct.
#[repr(transparent)]
pub struct NamedParameter<N: IsTStr, T> {
    // since TStr is zero-sized, it can be put alongside the non-zero-sized
    // wrapped value in a `#[repr(transparent)]` type.
    name: TStr<N::Arg>,
    pub value: T,
}

impl<N, T> NamedParameter<N, T>
where
    N: IsTStr
{
    pub const fn new(name: N, value: T) -> Self {
        Self {
            // `TStr::from_gen` is needed for constructing a `TStr` from a
            // generic `IsTStr` type
            name: TStr::from_gen(name),
            value,
        }
    }
}

/// Custom trait for constructors.
trait Make<Args>: Sized {
    fn make(args: Args) -> Self;
}

// make constructor with no parameters
impl<K, V> Make<args_ty!()> for HashMap<K, V> {
    fn make(args_pat!{}: args_ty!()) -> Self {
        HashMap::new()
    }
}

// make constructor with a capacity parameter
impl<K, V> Make<args_ty!(capacity: usize)> for HashMap<K, V> {
    fn make(args_pat!{capacity}: args_ty!(capacity: usize)) -> Self {
        HashMap::with_capacity(capacity)
    }
}

// make constructor with a hasher parameter
impl<K, V, S> Make<args_ty!(hasher: S)> for HashMap<K, V, S> {
    fn make(args_pat!{hasher}: args_ty!(hasher: S)) -> Self {
        HashMap::with_hasher(hasher)
    }
}

// make constructor with capacity and hasher parameters
impl<K, V, S> Make<args_ty!(capacity: usize, hasher: S)> for HashMap<K, V, S> {
    fn make(args_pat!{capacity, hasher}: args_ty!(capacity: usize, hasher: S)) -> Self {
        HashMap::with_capacity_and_hasher(capacity, hasher)
    }
}

macro_rules! args {
    ($($name:ident: $val:expr),* $(,)?) => (
        ($(NamedParameter::new(ts!($name), $val),)*)
    )
} use args;

macro_rules! args_ty {
    ($($name:ident: $field_ty:ty),* $(,)?) => (
        ($(NamedParameter<TS!($name), $field_ty>,)*)
    )
} use args_ty;

macro_rules! args_pat {
    ($($name:ident),* $(,)?) => (
        ($( NamedParameter::<TS!($name), _> { value: $name, .. }, )*)
    )
} use args_pat;

Parsing integers

Parsing integers from TStrs, since the primitive integers all have const fn from_str_radix functions, parsing them doesn’t require direct support from TStr itself.

(this example requires the "const_panic" feature because it uses tstr::unwrap)

use tstr::ts;

// parses the number at compile-time!
const NUMBER: u32 = tstr::unwrap!(u32::from_str_radix(tstr::to_str(ts!(1234)), 10));

assert_eq!(NUMBER, 1234u32);

Serde

TStr implements serde::{Serialize, Deserialize} when the "serde" feature is enabled.

use tstr::{TS, ts};

assert_eq!(serde_json::from_str::<TS!(foo)>(r#""foo""#).unwrap(), ts!(foo));

// trying to deserialize a `TS!(foo)` from any value other than `"foo"` produces an error
assert!(serde_json::from_str::<TS!(foo)>(r#""bar""#).is_err());


assert_eq!(serde_json::to_string(&ts!(wtf)).unwrap(), r#""wtf""#);

assert_eq!(serde_json::to_string(&ts!("hello")).unwrap(), r#""hello""#);

assert_eq!(serde_json::to_string(&ts!(12345)).unwrap(), r#""12345""#);

Implementations

impl<S> TStr<S>

pub const fn new() -> Self

Constructs the TStr.

impl<S: TStrArg> TStr<S>

pub const fn from_gen<G>(tstr: G) -> Self

where G: IsTStr<Arg = S>,

Coerces an impl IsTStr into a TStr, only necessary in generic contexts

The trait method equivalent of this const function is IsTStr::to_tstr.

While it’s always possible to construct a TStr through its new constructor, this method ensures that it’s the same string as the argument.

Example

use tstr::{IsTStr, TStr};

#[repr(transparent)]
struct Foo<T, N: IsTStr> {
    val: T,
    // since TStr is zero-sized, it can be put in `#[repr(transparent)]` types
    // next to the wrapped non-Zero-Sized-Type.
    name: TStr<N::Arg>,
}

impl<T, N: IsTStr> Foo<T, N> {
    pub fn new(val: T, tstr: N) -> Self {
        Self{ val, name: TStr::from_gen(tstr) }
    }
}

pub const fn to_gen<G>(self) -> G

where G: IsTStr<Arg = S>,

Coerces a TStr into an impl IsTStr, only necessary in generic contexts

While it’s always possible to construct an IsTStr through its VAL associated constant, this method ensures that it’s the same string as Self.

Example

use tstr::{IsTStr, TStr};

#[repr(transparent)]
struct Foo<T, N: IsTStr> {
    val: T,
    // since TStr is zero-sized, it can be put in `#[repr(transparent)]` types
    // next to the wrapped non-Zero-Sized-Type.
    name: TStr<N::Arg>,
}

impl<T, N: IsTStr> Foo<T, N> {
    const fn name(&self) -> N {
        self.name.to_gen()
    }
}

impl<S> TStr<S>

pub const fn to_panicval(&self, fmtarg: FmtArg) -> PanicVal<'static>

where S: TStrArg,

Available on crate feature const_panic only.

const_panic-based-formatting of TStr

pub const fn to_panicvals(&self, fmtarg: FmtArg) -> [PanicVal<'static>; 1]

where S: TStrArg,

Available on crate feature const_panic only.

const_panic-based-formatting of TStr

Trait Implementations

impl<S> Clone for TStr<S>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<S> Debug for TStr<S>

where S: TStrArg,

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

Formats the value using the given formatter.

impl<S> Default for TStr<S>

fn default() -> Self

Returns the “default value” for a type.

impl<'de, SA: TStrArg> Deserialize<'de> for TStr<SA>

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<S> Display for TStr<S>

where S: TStrArg,

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

Formats the value using the given formatter.

impl<S> Hash for TStr<S>

where S: TStrArg,

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

where H: Hasher,

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<S> IsTStr for TStr<S>

where S: TStrArg,

const VAL: Self

Constructs this IsTStr

const LENGTH: usize = S::__LENGTH

The length of this string when encoded to utf8

const BYTES: &[u8] = S::__BYTES

This string converted to a uf8-encoded byte slice

const STR: &str = S::__STR

This type-level string converted to a string

type Arg = S

The type parameter of TStr

fn to_tstr(self) -> TStr<Self::Arg>

Coerces Self to TStr<Self::Arg>, only necessary in generic contexts

fn from_tstr(tstr: TStr<Self::Arg>) -> Self

Coerces a TStr into Self, only necessary in generic contexts.

fn len(self) -> usize

Gets the length of the string in utf8

fn to_str(self) -> &'static str

Gets the &'static str equivalent of this TStr

fn to_bytes(self) -> &'static [u8]

Gets the &'static [u8] equivalent of this TStr

fn tstr_eq<Rhs: IsTStr>(self, rhs: Rhs) -> bool

Compares two TStrs for equality

fn tstr_ne<Rhs: IsTStr>(self, rhs: Rhs) -> bool

Compares two TStrs for inequality

fn tstr_cmp<Rhs: IsTStr>(self, rhs: Rhs) -> Ordering

Compares two TStrs for ordering

fn type_eq<Rhs: IsTStr>(self, rhs: Rhs) -> TypeCmp<Self, Rhs>

Compares two TStrs for equality, returning a proof of (in)equality of Self and Rhs

impl<S> Ord for TStr<S>

where S: TStrArg,

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<S> PanicFmt for TStr<S>

where S: TStrArg,

Available on crate feature const_panic only.

const PV_COUNT: usize = 1

The length of the array returned in Self::to_panicvals (an inherent method that formats the type for panic messages).

type This = TStr<S>

The type after dereferencing all references.

type Kind = IsCustomType

Whether this is a user-defined type or standard library type.

const PROOF: IsPanicFmt<Self, Self::This, Self::Kind> = IsPanicFmt::NEW

A marker type that proves that Self implements PanicFmt.

impl<S> PartialEq<&&str> for TStr<S>

where S: TStrArg,

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<S> PartialEq<&str> for TStr<S>

where S: TStrArg,

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<S, S2> PartialEq<S2> for TStr<S>

where S: TStrArg, S2: ?Sized + StrLike,

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

where S2: TStrArg,

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

where S2: TStrArg,

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

where S2: TStrArg,

fn eq(&self, other: &TStr<S2>) -> 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<S> PartialOrd<&&str> for TStr<S>

where S: TStrArg,

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<S> PartialOrd<&str> for TStr<S>

where S: TStrArg,

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<S, S2> PartialOrd<S2> for TStr<S>

where S: TStrArg, S2: ?Sized + StrLike,

fn partial_cmp(&self, other: &S2) -> 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<S2> PartialOrd<TStr<S2>> for &&str

where S2: TStrArg,

fn partial_cmp(&self, other: &TStr<S2>) -> 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<S2> PartialOrd<TStr<S2>> for &str

where S2: TStrArg,

fn partial_cmp(&self, other: &TStr<S2>) -> 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<S2> PartialOrd<TStr<S2>> for str

where S2: TStrArg,

fn partial_cmp(&self, other: &TStr<S2>) -> 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<SA: TStrArg> Serialize for TStr<SA>

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<S> Copy for TStr<S>

impl<S> Eq for TStr<S>

where S: TStrArg,