Skip to main content

error_kind/details/
static_string.rs

1// =============================================================================
2// MODULES
3// =============================================================================
4
5// -----------------------------------------------------------------------------
6#[cfg(test)]
7#[path = "static_string.tests.rs"]
8mod tests;
9
10// =============================================================================
11// USES
12// =============================================================================
13
14// -----------------------------------------------------------------------------
15#[cfg(feature = "alloc")]
16use std_alloc::{borrow::Cow, string::String};
17
18// =============================================================================
19// SEALED
20// =============================================================================
21
22// -----------------------------------------------------------------------------
23mod sealed {
24    pub trait Sealed {}
25    impl Sealed for &'static str {}
26    #[cfg(feature = "alloc")]
27    impl Sealed for super::Cow<'static, str> {}
28    #[cfg(feature = "alloc")]
29    impl Sealed for super::String {}
30}
31
32// =============================================================================
33// TYPES
34// =============================================================================
35
36/// Allow for access and conversion from a static string asset.
37///
38/// This is useful for allowing a relaxed reliance on the `alloc` crate.
39/// If the `alloc` feature is not enabled, you cannot use types that would
40/// require taking ownership of an allocated string.
41///
42/// This is to explicitly avoid naming `String` in places.
43pub trait StaticString: sealed::Sealed + Sized + Send + Sync + 'static {
44    /// Take CoW ownership of the provided static string.
45    #[cfg(feature = "alloc")]
46    fn into_cow(self) -> Cow<'static, str>;
47
48    /// Take ownership of the provided static string.
49    #[cfg(feature = "alloc")]
50    fn into_owned(self) -> String;
51
52    /// Attempt to borrow the string as a static string reference.
53    ///
54    /// This can fail if the type this is implemented over does not contain
55    /// a static reference to a string (e.g. it's an allocated `String`).
56    fn try_borrow(&self) -> Option<&'static str>;
57}
58
59// =============================================================================
60// TRAIT IMPLS
61// =============================================================================
62
63// -----------------------------------------------------------------------------
64impl StaticString for &'static str {
65    #[cfg(feature = "alloc")]
66    #[inline(always)]
67    fn into_cow(self) -> Cow<'static, str> {
68        Cow::Borrowed(self)
69    }
70
71    #[cfg(feature = "alloc")]
72    #[inline(always)]
73    fn into_owned(self) -> String {
74        String::from(self)
75    }
76
77    #[inline(always)]
78    fn try_borrow(&self) -> Option<&'static str> {
79        Some(self)
80    }
81}
82
83// -----------------------------------------------------------------------------
84#[cfg(feature = "alloc")]
85impl StaticString for Cow<'static, str> {
86    #[inline(always)]
87    fn into_cow(self) -> Cow<'static, str> {
88        self
89    }
90
91    #[inline]
92    fn into_owned(self) -> String {
93        self.into_owned()
94    }
95
96    #[inline]
97    fn try_borrow(&self) -> Option<&'static str> {
98        match self {
99            Cow::Borrowed(value) => Some(value),
100            Cow::Owned(_) => None,
101        }
102    }
103}
104
105// -----------------------------------------------------------------------------
106#[cfg(feature = "alloc")]
107impl StaticString for String {
108    #[inline(always)]
109    fn into_cow(self) -> Cow<'static, str> {
110        Cow::Owned(self)
111    }
112
113    #[inline(always)]
114    fn into_owned(self) -> String {
115        self
116    }
117
118    #[inline(always)]
119    fn try_borrow(&self) -> Option<&'static str> {
120        None
121    }
122}