devela/text/str/namespace.rs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217
// devela::text::str::namespace
//
//! `Str` namespace.
//
#[cfg(doc)]
use crate::ExtStr;
use crate::{
iif, Ascii, InvalidUtf8, Slice,
_core::str::{from_utf8, from_utf8_mut},
};
#[allow(unused_imports, reason = "unsafe_str only")]
#[cfg(feature = "alloc")]
use crate::{Box, _dep::_alloc::str::from_boxed_utf8_unchecked};
#[allow(unused_imports, reason = "unsafe_str only")]
use crate::{
_core::str::{from_utf8_unchecked, from_utf8_unchecked_mut},
sf, unwrap,
};
/// A string slice namespace.
///
/// See also the [`std::str`] module.
pub struct Str;
impl Str {
/// Converts a slice of bytes to a string slice.
///
/// See [`from_utf8`].
pub const fn from_utf8(v: &[u8]) -> Result<&str, InvalidUtf8> {
match from_utf8(v) {
Ok(v) => Ok(v),
Err(e) => Err(InvalidUtf8::from_utf8_error(e)),
}
}
/// Converts a mutable slice of bytes to a mutable string slice.
///
/// See [`from_utf8_mut`].
// WAIT: [const_str_from_utf8](https://github.com/rust-lang/rust/issues/91006)
pub fn from_utf8_mut(v: &mut [u8]) -> Result<&mut str, InvalidUtf8> {
match from_utf8_mut(v) {
Ok(v) => Ok(v),
Err(e) => Err(InvalidUtf8::from_utf8_error(e)),
}
}
/// Converts a slice of bytes to a string slice without checking valid UTF-8.
///
/// See [`from_utf8_unchecked`].
///
/// # Safety
/// The bytes passed in must be valid UTF-8.
#[must_use]
#[cfg(all(not(feature = "safe_text"), feature = "unsafe_str"))]
#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "unsafe_str")))]
pub const unsafe fn from_utf8_unchecked(v: &[u8]) -> &str {
// SAFETY: Caller must uphold the safety contract.
unsafe { from_utf8_unchecked(v) }
}
/// Converts a mutable slice of bytes to a mutable string slice without checking valid UTF-8.
///
/// See [`from_utf8_unchecked_mut`].
///
/// # Safety
/// The bytes passed in must be valid UTF-8.
#[must_use]
#[cfg(all(not(feature = "safe_text"), feature = "unsafe_str"))]
#[cfg_attr(feature = "nightly_doc", doc(cfg(feature = "unsafe_str")))]
pub const unsafe fn from_utf8_unchecked_mut(v: &mut [u8]) -> &mut str {
// SAFETY: Caller must uphold the safety contract.
unsafe { from_utf8_unchecked_mut(v) }
}
/// Converts a boxed slice of bytes to a boxed string slice without checking valid UTF-8.
///
/// See [`from_boxed_utf8_unchecked`].
///
/// # Safety
/// The bytes passed in must be valid UTF-8.
#[must_use]
#[cfg(feature = "alloc")]
#[cfg(all(not(feature = "safe_text"), feature = "unsafe_str"))]
#[cfg_attr(feature = "nightly_doc", doc(cfg(all(feature = "alloc", feature = "unsafe_str"))))]
pub unsafe fn from_boxed_utf8_unchecked(v: Box<[u8]>) -> Box<str> {
// SAFETY: Caller must uphold the safety contract.
unsafe { from_boxed_utf8_unchecked(v) }
}
/// Repeats a `string` a given number of times into the provided `buffer`.
/// and returns a reference to the new `&str`.
/// # Examples
/// ```
/// # use devela::Str;
/// let mut buf = [0_u8; 12];
/// let repeated = Str::repeat_into("ay", 3, &mut buf);
/// assert_eq![repeated, "ayayay"];
/// ```
/// # Features
/// Makes use of the `unsafe_str` feature if enabled.
///
/// See also [`ExtStr::new_counter`], which should be faster,
/// because it uses `copy_from_slice`.
#[must_use]
pub const fn repeat_into<'input, const CAP: usize>(
string: &str,
n: usize,
buffer: &'input mut [u8; CAP],
) -> &'input str {
let s_bytes = string.as_bytes();
let mut index = 0;
// for _ in 0..n {
// for &b in s_bytes {
// iif![index == CAP; break];
// buffer[index] = b;
// index += 1;
// }
// } // const loop:
let mut outer_count = 0;
while outer_count < n {
let mut inner_index = 0;
while inner_index < s_bytes.len() {
iif![index == CAP; break];
buffer[index] = s_bytes[inner_index];
index += 1;
inner_index += 1;
}
outer_count += 1;
}
#[cfg(any(feature = "safe_text", not(feature = "unsafe_str")))]
return unwrap![ok Str::from_utf8(Slice::range_to(buffer, index))];
#[cfg(all(not(feature = "safe_text"), feature = "unsafe_str"))]
// SAFETY: since `string` is a valid &str, checks are unneeded.
sf! { unsafe { Str::from_utf8_unchecked(Slice::range_to(buffer, index)) }}
}
/// Returns a [`&str`] backed by a `buffer`, where you always know each
/// character's position.
///
/// A [*counter string*][0] is a graduated string of arbitrary `length`,
/// with a `separator` positioned after the immediately preceding number.
/// # Examples
/// ```
/// # use devela::Str;
/// let mut buf = [0; 15];
/// assert_eq!("2*4*6*8*11*14*", Str::new_counter(&mut buf, 14, '*'));
/// assert_eq!("_3_5_7_9_12_15_", Str::new_counter(&mut buf, 15, '_'));
/// ```
/// # Panics
/// Panics if `buffer.len() < length`, or if `!char.is_ascii()`.
///
/// # Features
/// Makes use of the `unsafe_str` feature if enabled.
///
/// See also [`ExtStr::new_counter`].
///
/// [0]: https://www.satisfice.com/blog/archives/22
pub const fn new_counter(buffer: &mut [u8], length: usize, separator: char) -> &str {
assert![buffer.len() >= length];
assert![separator.is_ascii()];
if length == 0 {
cold_empty_string()
} else {
let separator = separator as u8;
let mut index = length - 1; // start writing from the end
let mut num = length; // the first number to write is the length
let mut separator_turn = true; // start writing the separator
let mut num_buf = Ascii(num).digits();
let mut num_bytes = Slice::trim_leading_bytes(&num_buf, b'0');
// IMPROVE:BENCH use NumToStr
// let mut num_buf = [0u8; 22];
// let mut num_bytes = num.to_bytes_base(10, &mut num_buf);
let mut num_len = num_bytes.len();
loop {
if separator_turn {
buffer[index] = separator;
} else {
iif![index > 0; index -= num_len - 1];
// buffer[index..(num_len + index)].copy_from_slice(&num_bytes[..num_len]);
// Slice::range_mut(buffer, index, num_len + index)
// .copy_from_slice(Slice::range_to(num_bytes, num_len));
let mut i = 0;
while i < num_len {
buffer[index + i] = num_bytes[i];
i += 1;
}
num = index;
num_buf = Ascii(num).digits();
num_bytes = Slice::trim_leading_bytes(&num_buf, b'0');
// IMPROVE: use NumToStr
// num_bytes = num.to_bytes_base(10, &mut num_buf);
num_len = num_bytes.len();
}
iif![index == 0; break; index -= 1];
separator_turn = !separator_turn;
}
#[cfg(any(feature = "safe_text", not(feature = "unsafe_str")))]
return unwrap![ok Str::from_utf8(Slice::range_to(buffer, length))];
#[cfg(all(not(feature = "safe_text"), feature = "unsafe_str"))]
// SAFETY: TODO: since `string` is a valid &str, checks are unneeded.
sf! { unsafe { Str::from_utf8_unchecked(Slice::range_to(buffer, length)) }}
}
}
}
/// The cold path that returns an empty string slice.
#[cold] #[rustfmt::skip]
pub(crate) const fn cold_empty_string() -> &'static str { "" }