#![doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/", env!("CARGO_PKG_README")))]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![cfg_attr(all(feature = "verus", verus_keep_ghost), feature(sized_hierarchy))]
#![no_std]
#[cfg(feature = "alloc")]
extern crate alloc;
#[cfg(test)]
extern crate std;
#[doc(hidden)]
pub mod __private {
#[cfg(feature = "alloc")]
pub use alloc::borrow::ToOwned;
#[cfg(feature = "alloc")]
pub use alloc::string::String;
#[cfg(feature = "serde")]
pub use serde;
#[cfg(feature = "verus")]
pub use vstd;
}
#[cfg(all(feature = "verus", verus_keep_ghost))]
const _: () = {
vstd::prelude::verus! {
#[verifier::external_trait_specification]
pub trait ExAsRef<T: ::core::marker::PointeeSized>: ::core::marker::PointeeSized {
type ExternalTraitSpecificationFor: ::core::convert::AsRef<T>;
}
}
};
#[macro_export]
macro_rules! strkind {
() => {};
(
$(#[$meta:meta])*
$vis:vis $Name:ident ;
$($rest:tt)*
) => {
$crate::__strkind_struct! { $(#[$meta])* $vis $Name }
impl<T: AsRef<str>> $Name<T> {
$vis const fn new(storage: T) -> Self {
Self(storage)
}
$vis fn into_inner(self) -> T {
self.0
}
$vis fn convert<U: AsRef<str> + ::core::convert::From<T>>(self) -> $Name<U> {
$Name(U::from(self.0))
}
}
impl<T: ?Sized + AsRef<str>> $Name<T> {
$vis fn as_str(&self) -> &str {
self.0.as_ref()
}
}
impl $Name<str> {
$vis const fn from_ref(s: &str) -> &Self {
unsafe { &*(::core::ptr::from_ref::<str>(s) as *const Self) }
}
}
impl<T: ?Sized + AsRef<str>> ::core::convert::AsRef<str> for $Name<T> {
fn as_ref(&self) -> &str {
self.0.as_ref()
}
}
impl<T: ?Sized + AsRef<str>> ::core::convert::AsRef<$Name<str>> for $Name<T> {
fn as_ref(&self) -> &$Name<str> {
$Name::from_ref(self.0.as_ref())
}
}
impl<T: ?Sized + AsRef<str>> ::core::fmt::Display for $Name<T> {
fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
::core::fmt::Display::fmt(self.0.as_ref(), f)
}
}
impl<A: ?Sized + AsRef<str>, B: ?Sized + AsRef<str>>
::core::cmp::PartialEq<$Name<B>> for $Name<A>
{
fn eq(&self, other: &$Name<B>) -> bool {
self.0.as_ref() == other.0.as_ref()
}
}
impl<T: ?Sized + AsRef<str>> ::core::cmp::Eq for $Name<T> {}
impl<A: ?Sized + AsRef<str>, B: ?Sized + AsRef<str>>
::core::cmp::PartialOrd<$Name<B>> for $Name<A>
{
fn partial_cmp(&self, other: &$Name<B>) -> ::core::option::Option<::core::cmp::Ordering> {
self.0.as_ref().partial_cmp(other.0.as_ref())
}
}
impl<T: ?Sized + AsRef<str>> ::core::cmp::Ord for $Name<T> {
fn cmp(&self, other: &Self) -> ::core::cmp::Ordering {
self.0.as_ref().cmp(other.0.as_ref())
}
}
impl<T: ?Sized + AsRef<str>> ::core::hash::Hash for $Name<T> {
fn hash<H: ::core::hash::Hasher>(&self, state: &mut H) {
self.0.as_ref().hash(state)
}
}
impl<T: AsRef<str> + for<'a> ::core::convert::From<&'a str>> ::core::str::FromStr
for $Name<T>
{
type Err = ::core::convert::Infallible;
fn from_str(s: &str) -> ::core::result::Result<Self, Self::Err> {
::core::result::Result::Ok(Self(T::from(s)))
}
}
impl<T: ?Sized + AsRef<str> + ::core::ops::Deref<Target = str>> ::core::ops::Deref
for $Name<T>
{
type Target = $Name<str>;
fn deref(&self) -> &$Name<str> {
$Name::from_ref(self.0.as_ref())
}
}
impl<T: AsRef<str> + ::core::ops::Deref<Target = str>>
::core::borrow::Borrow<$Name<str>> for $Name<T>
{
fn borrow(&self) -> &$Name<str> {
self
}
}
$crate::__strkind_alloc! { $Name }
$crate::__strkind_serde! { $Name }
$crate::__strkind_verus! { $vis $Name }
$crate::strkind! { $($rest)* }
};
}
#[cfg(feature = "alloc")]
#[doc(hidden)]
#[macro_export]
macro_rules! __strkind_struct {
( $(#[$meta:meta])* $vis:vis $Name:ident ) => {
$(#[$meta])*
#[derive(Debug, Clone)]
#[repr(transparent)]
$vis struct $Name<T: ?Sized + AsRef<str> = $crate::__private::String>(T);
};
}
#[cfg(not(feature = "alloc"))]
#[doc(hidden)]
#[macro_export]
macro_rules! __strkind_struct {
( $(#[$meta:meta])* $vis:vis $Name:ident ) => {
$(#[$meta])*
#[derive(Debug, Clone)]
#[repr(transparent)]
$vis struct $Name<T: ?Sized + AsRef<str>>(T);
};
}
#[cfg(feature = "alloc")]
#[doc(hidden)]
#[macro_export]
macro_rules! __strkind_alloc {
( $Name:ident ) => {
impl $crate::__private::ToOwned for $Name<str> {
type Owned = $Name<$crate::__private::String>;
fn to_owned(&self) -> Self::Owned {
$Name($crate::__private::ToOwned::to_owned(&self.0))
}
}
impl ::core::convert::From<&str> for $Name<$crate::__private::String> {
fn from(s: &str) -> Self {
Self($crate::__private::ToOwned::to_owned(s))
}
}
impl ::core::convert::From<$crate::__private::String> for $Name<$crate::__private::String> {
fn from(s: $crate::__private::String) -> Self {
Self(s)
}
}
};
}
#[cfg(not(feature = "alloc"))]
#[doc(hidden)]
#[macro_export]
macro_rules! __strkind_alloc {
( $Name:ident ) => {};
}
#[cfg(feature = "serde")]
#[doc(hidden)]
#[macro_export]
macro_rules! __strkind_serde {
( $Name:ident ) => {
impl<T: ?Sized + AsRef<str> + $crate::__private::serde::Serialize>
$crate::__private::serde::Serialize for $Name<T>
{
fn serialize<S: $crate::__private::serde::Serializer>(
&self,
serializer: S,
) -> ::core::result::Result<S::Ok, S::Error> {
self.0.serialize(serializer)
}
}
impl<'de, T: AsRef<str> + $crate::__private::serde::Deserialize<'de>>
$crate::__private::serde::Deserialize<'de> for $Name<T>
{
fn deserialize<D: $crate::__private::serde::Deserializer<'de>>(
deserializer: D,
) -> ::core::result::Result<Self, D::Error> {
T::deserialize(deserializer).map(Self)
}
}
};
}
#[cfg(not(feature = "serde"))]
#[doc(hidden)]
#[macro_export]
macro_rules! __strkind_serde {
( $Name:ident ) => {};
}
#[cfg(feature = "verus")]
#[doc(hidden)]
#[macro_export]
macro_rules! __strkind_verus {
( $vis:vis $Name:ident ) => {
#[allow(
clippy::allow_attributes,
unexpected_cfgs,
reason = "`verus_keep_ghost` is set by the Verus driver"
)]
const _: () = {
#[cfg(verus_keep_ghost)]
$crate::__private::vstd::prelude::verus! {
#[verifier::external_type_specification]
#[verifier::external_body]
#[verifier::reject_recursive_types(T)]
pub struct Ex<T: ?Sized + AsRef<str>>($Name<T>);
}
};
#[cfg(verus_keep_ghost)]
$crate::__private::vstd::prelude::verus! {
impl<T: ?Sized + AsRef<str>> $crate::__private::vstd::view::View for $Name<T> {
type V = $crate::__private::vstd::seq::Seq<char>;
uninterp spec fn view(&self) -> $crate::__private::vstd::seq::Seq<char>;
}
impl<T: ?Sized + AsRef<str>> $Name<T> {
$vis uninterp spec fn storage_obeys_str_model() -> bool;
}
impl $Name<str> {
$vis broadcast axiom fn axiom_str_storage_obeys_str_model()
ensures #[trigger] Self::storage_obeys_str_model();
}
}
#[allow(
clippy::allow_attributes,
unexpected_cfgs,
unsafe_code,
reason = "`verus_keep_ghost` is set by the Verus driver, and the trusted `assume_specification` axiom expands to unsafe-marked items"
)]
const _: () = {
#[cfg(verus_keep_ghost)]
$crate::__private::vstd::prelude::verus! {
$vis assume_specification<T: ?Sized + AsRef<str>>[ $Name::<T>::as_str ](id: &$Name<T>) -> (s: &str)
ensures $Name::<T>::storage_obeys_str_model() ==> s@ == id@;
}
};
$crate::__strkind_verus_alloc! { $vis $Name }
};
}
#[cfg(not(feature = "verus"))]
#[doc(hidden)]
#[macro_export]
macro_rules! __strkind_verus {
( $vis:vis $Name:ident ) => {};
}
#[cfg(all(feature = "verus", feature = "alloc"))]
#[doc(hidden)]
#[macro_export]
macro_rules! __strkind_verus_alloc {
( $vis:vis $Name:ident ) => {
#[cfg(verus_keep_ghost)]
$crate::__private::vstd::prelude::verus! {
impl $Name<$crate::__private::String> {
$vis broadcast axiom fn axiom_string_storage_obeys_str_model()
ensures #[trigger] Self::storage_obeys_str_model();
}
}
};
}
#[cfg(not(all(feature = "verus", feature = "alloc")))]
#[doc(hidden)]
#[macro_export]
macro_rules! __strkind_verus_alloc {
( $vis:vis $Name:ident ) => {};
}
#[cfg(feature = "_example")]
#[cfg_attr(docsrs, doc(cfg(feature = "_example")))]
pub mod example {
strkind! {
pub ExampleId;
}
}
#[cfg(test)]
mod core_tests {
strkind! {
pub(crate) CoreId;
}
#[test]
fn core_only_surface() {
const A: &CoreId<str> = CoreId::from_ref("a");
assert_eq!(A.as_str(), "a");
let b: CoreId<&str> = CoreId::new("a");
assert_eq!(A, &b); assert!(A <= &b);
let c: CoreId<&str> = b.clone().convert();
assert_eq!(c.into_inner(), "a");
fn takes_kinded(id: &(impl ?Sized + AsRef<CoreId<str>>)) -> &str {
id.as_ref().as_str()
}
assert_eq!(takes_kinded(&b), "a");
assert_eq!(takes_kinded(A), "a");
}
const _CONST_METHODS: () = {
let _id: CoreId<&str> = CoreId::new("a");
let _borrowed: &CoreId<str> = CoreId::from_ref("a");
};
}
#[cfg(all(test, feature = "alloc"))]
mod tests {
use std::collections::{BTreeMap, HashMap};
use std::format;
use std::prelude::rust_2024::*;
use std::sync::Arc;
use smol_str::SmolStr;
strkind! {
pub(crate) ThreadId;
pub(crate) RawTag;
}
strkind! {
pub(crate) OtherId;
}
#[test]
fn new_wraps_and_unwraps() {
let id = ThreadId::new("thread-7".to_owned());
assert_eq!(id.as_str(), "thread-7");
assert_eq!(id.to_string(), "thread-7");
assert_eq!(id.into_inner(), "thread-7");
}
#[test]
fn from_and_from_str() {
let id = ThreadId::from("thread-7");
assert_eq!(id.as_str(), "thread-7");
let from_owned = ThreadId::from("thread-7".to_owned());
assert_eq!(from_owned, id);
let parsed: ThreadId = "thread-7".parse().expect("infallible");
assert_eq!(parsed, id);
let small: ThreadId<SmolStr> = "thread-7".parse().expect("infallible");
let shared: ThreadId<Arc<str>> = "thread-7".parse().expect("infallible");
assert_eq!(small, id);
assert_eq!(shared, id);
}
#[test]
fn from_ref_is_const_and_zero_copy() {
const ID: &ThreadId<str> = ThreadId::from_ref("thread-7");
assert_eq!(ID.as_str(), "thread-7");
assert_eq!(ID, &ThreadId::from("thread-7"));
}
#[test]
fn deref_gives_borrowed_form() {
fn takes_borrowed(id: &ThreadId<str>) -> &str {
id.as_str()
}
let owned = ThreadId::from("thread-7");
assert_eq!(takes_borrowed(&owned), "thread-7");
}
#[test]
fn as_ref_kinded_bound() {
fn takes_any_storage(id: impl AsRef<ThreadId<str>>) -> String {
id.as_ref().as_str().to_owned()
}
let owned = ThreadId::from("thread-7");
let shared: ThreadId<Arc<str>> = owned.clone().convert();
let borrowed: &ThreadId<str> = ThreadId::from_ref("thread-7");
assert_eq!(takes_any_storage(&owned), "thread-7");
assert_eq!(takes_any_storage(owned), "thread-7");
assert_eq!(takes_any_storage(shared), "thread-7");
assert_eq!(takes_any_storage(borrowed), "thread-7"); }
#[test]
fn as_ref_str_still_available() {
fn takes_stringish(s: impl AsRef<str>) -> String {
s.as_ref().to_owned()
}
assert_eq!(takes_stringish(ThreadId::from("thread-7")), "thread-7");
let id = ThreadId::from("thread-7");
let s: &str = id.as_ref(); assert_eq!(s, "thread-7");
}
#[test]
fn to_owned_round_trips() {
let borrowed: &ThreadId<str> = ThreadId::from_ref("thread-7");
let owned: ThreadId = borrowed.to_owned();
assert_eq!(owned, *borrowed);
}
#[test]
fn map_lookup_by_borrowed_form() {
let mut hash_map: HashMap<ThreadId, u32> = HashMap::new();
hash_map.insert(ThreadId::from("a"), 1);
assert_eq!(hash_map.get(ThreadId::from_ref("a")), Some(&1));
assert_eq!(hash_map.get(ThreadId::from_ref("b")), None);
let mut btree_map: BTreeMap<ThreadId, u32> = BTreeMap::new();
btree_map.insert(ThreadId::from("a"), 1);
assert_eq!(btree_map.get(ThreadId::from_ref("a")), Some(&1));
}
#[test]
fn alternate_storages_interoperate() {
let owned = ThreadId::from("thread-7");
let shared: ThreadId<Arc<str>> = owned.clone().convert();
let small: ThreadId<SmolStr> = ThreadId::new(SmolStr::new("thread-7"));
assert_eq!(shared, owned);
assert_eq!(small, owned);
assert_eq!(shared, small);
let mut map: HashMap<ThreadId<Arc<str>>, u32> = HashMap::new();
map.insert(shared, 1);
assert_eq!(map.get(ThreadId::from_ref("thread-7")), Some(&1));
}
#[test]
fn kinds_are_distinct_types() {
fn takes_thread_id(id: &ThreadId<str>) -> &str {
id.as_str()
}
let other = OtherId::new("x".to_owned());
let thread = ThreadId::from("x");
assert_eq!(takes_thread_id(&thread), other.as_str());
assert_eq!(other.convert::<Box<str>>().into_inner().as_ref(), "x");
let tag = RawTag::new("x".to_owned());
assert_eq!(tag.as_str(), "x");
assert_eq!(tag.convert::<Arc<str>>().into_inner().as_ref(), "x");
}
#[cfg(feature = "serde")]
#[test]
fn serde_round_trip_is_transparent() {
let id = ThreadId::from("thread-7");
let json = serde_json::to_string(&id).expect("serialize");
assert_eq!(json, r#""thread-7""#, "serializes as a plain string");
let back: ThreadId = serde_json::from_str(&json).expect("deserialize");
assert_eq!(back, id);
let borrowed_json =
serde_json::to_string(ThreadId::from_ref("thread-7")).expect("serialize");
assert_eq!(borrowed_json, json);
let small: ThreadId<SmolStr> = serde_json::from_str(&json).expect("deserialize");
assert_eq!(small, id);
}
#[cfg(feature = "serde")]
#[test]
fn serde_map_keys() {
let mut map: HashMap<ThreadId, u32> = HashMap::new();
map.insert(ThreadId::from("a"), 1);
let json = serde_json::to_string(&map).expect("serialize");
assert_eq!(json, r#"{"a":1}"#);
let back: HashMap<ThreadId, u32> = serde_json::from_str(&json).expect("deserialize");
assert_eq!(back, map);
}
#[test]
fn debug_names_the_kind() {
assert_eq!(format!("{:?}", ThreadId::from("a")), r#"ThreadId("a")"#);
}
#[test]
fn ordering_is_by_content() {
let mut ids = [
ThreadId::from("b"),
ThreadId::from("a"),
ThreadId::from("c"),
];
ids.sort();
let sorted: Vec<&str> = ids.iter().map(|i| i.as_str()).collect();
assert_eq!(sorted, ["a", "b", "c"]);
assert!(ThreadId::from("a") < ThreadId::from("b"));
}
}