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}