static_collections/

string.rs

// The static-string module

use core::{char::DecodeUtf16Error, fmt::{self, Debug, Display}, ops::{AddAssign, Deref, DerefMut}, str};

use crate::{ffi::c_str::strnlen, vec::StaticVec};

#[derive(Debug)]
pub enum InsertError
{
	InsufficientSpace,
	NonUtf8Boundary,
	Utf16Error(DecodeUtf16Error)
}

/// The `StaticString` type is a fixed-capacity UTF-8 string object. \
/// To estimate length `N` you need, consider the following UTF-8 facts:
/// - 1-byte: English letters and basic punctuations.
/// - 2-byte: Latin-based, Greek, Cyrillic, Hebrew, Armenian letters and Thai characters.
/// - 3-byte: Chinese, Japanese and Korean characters.
/// - 4-byte: Emoji and rare symbols.
#[derive(Clone)]
pub struct StaticString<const N:usize>
{
	internal:StaticVec<N,u8>
}

impl<const N:usize> Default for StaticString<N>
{
	fn default() -> Self
	{
		Self::new()
	}
}

impl<const N:usize> StaticString<N>
{
	/// Creates a new empty `StaticString`.
	/// 
	/// Given that the string is empty, the buffer that contains the string isn't initialized.
	/// This means the initial operation is very inexpensive.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let s:StaticString<512>=StaticString::new();
	/// ```
	pub const fn new()->Self
	{
		Self
		{
			internal:StaticVec::new()
		}
	}

	/// Returns a byte slice of this `StaticString`'s contents.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let s:StaticString<64>=StaticString::from("Hello");
	/// assert_eq!(s.as_bytes(),b"Hello");
	/// ```
	#[inline(always)] pub const fn as_bytes(&self)->&[u8]
	{
		self.internal.as_slice()
	}

	/// Returns a mutable byte slice of this `StaticString`'s contents.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let mut s:StaticString<64>=StaticString::from("Hello");
	/// let array=s.as_mut_bytes();
	/// array[0]=b'C';
	/// assert_eq!(s.as_bytes(),b"Cello");
	/// ```
	#[inline(always)] pub const fn as_mut_bytes(&mut self)->&mut [u8]
	{
		self.internal.as_mut_slice()
	}

	/// Returns a string slice of this `StaticString`'s contents.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let s:StaticString<64>=StaticString::from("Hello, World!");
	/// assert_eq!(s.as_str(),"Hello, World!");
	/// ```
	#[inline(always)] pub const fn as_str(&self)->&str
	{
		unsafe
		{
			str::from_utf8_unchecked(self.as_bytes())
		}
	}

	/// Returns a string slice of this `StaticString`'s contents.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let mut s:StaticString<64>=StaticString::from("Hello, World!");
	/// assert_eq!(s.as_mut_str(),"Hello, World!");
	/// ```
	#[inline(always)] pub const fn as_mut_str(&mut self)->&mut str
	{
		unsafe
		{
			str::from_utf8_unchecked_mut(self.as_mut_bytes())
		}
	}

	/// Appends a given `char` to the end of this `StaticString`.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let mut s:StaticString<64>=StaticString::from("Hello");
	/// s.push('!');
	/// assert_eq!(s.as_str(),"Hello!");
	/// ```
	pub fn push(&mut self,ch:char)->Result<(),InsertError>
	{
		let ch_len=ch.len_utf8();
		let insertion_index=self.len();
		if insertion_index+ch_len>N
		{
			Err(InsertError::InsufficientSpace)
		}
		else
		{
			unsafe
			{
				self.internal.force_resize(insertion_index+ch_len);
			}
			ch.encode_utf8(&mut self.internal[insertion_index..]);
			Ok(())
		}
	}

	/// Appends a given string slice to the end of this `StaticString`.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let mut s:StaticString<64>=StaticString::from("Hello");
	/// s.push_str(", World!");
	/// assert_eq!(s.as_str(),"Hello, World!");
	/// ```
	pub fn push_str(&mut self,string:&str)->Result<(),InsertError>
	{
		let str_len=string.len();
		let insertion_index=self.len();
		if insertion_index+str_len>N
		{
			Err(InsertError::InsufficientSpace)
		}
		else
		{
			unsafe
			{
				self.internal.force_resize(insertion_index+str_len);
			}
			let dest_buff=&mut self.internal[insertion_index..];
			dest_buff.copy_from_slice(string.as_bytes());
			Ok(())
		}
	}

	/// Decodes a native‑endian UTF‑16 encoded slice `v` into a `StaticString<N>`.
	///
	/// Errors if the input contains invalid UTF‑16 **or** if the resulting
	/// string would overflow the buffer capacity.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::*;
	/// use utf16_lit::utf16;
	/// let s: Result<StaticString<16>, InsertError>=StaticString::from_utf16(&utf16!("Hello, World!"));
	/// assert_eq!(s.unwrap(),"Hello, World!");
	/// // A surrogate alone is definitely not a valid character.
	/// let s:Result<StaticString<16>,InsertError>=StaticString::from_utf16(&[0xd800]);
	/// assert!(s.is_err());
	/// ```
	pub fn from_utf16(v:&[u16])->Result<Self,InsertError>
	{
		let mut r=Self::new();
		for c in char::decode_utf16(v.iter().copied())
		{
			match c
			{
				Ok(ch)=>r.push(ch),
				Err(e)=>return Err(InsertError::Utf16Error(e))
			}?
		}
		Ok(r)
	}

	/// Decodes a little‑endian UTF‑16 slice `v` into a `StaticString<N>`.
	/// 
	/// Behaviour and error conditions are the same as [`from_utf16`]: decoding
	/// failures are wrapped in `InsertError::Utf16Error` and an overflow will
	/// return `InsertError::InsufficientSpace`.
	///
	/// # Examples
	/// ```
	/// use static_collections::string::*;
	/// use utf16_lit::utf16;
	/// let tmp:Vec<u16>=utf16!("Hello, World!").iter().map(|x| x.to_le()).collect();
	/// let s: Result<StaticString<16>,InsertError>=StaticString::from_utf16le(tmp.as_slice());
	/// assert_eq!(s.unwrap().as_str(),"Hello, World!");
	/// // A surrogate alone is definitely not a valid character.
	/// let tmp:u16=0xd800;
	/// let s: Result<StaticString<16>,InsertError>=StaticString::from_utf16le(&[tmp.to_le()]);
	/// assert!(s.is_err());
	/// ```
	pub fn from_utf16le(v:&[u16])->Result<Self,InsertError>
	{
		let mut r=Self::new();
		for c in char::decode_utf16(v.iter().map(|x| x.to_le()))
		{
			match c
			{
				Ok(ch)=>r.push(ch),
				Err(e)=>return Err(InsertError::Utf16Error(e))
			}?
		}
		Ok(r)
	}

	/// Decodes a big‑endian UTF‑16 slice `v` into a `StaticString<N>`.
	/// 
	/// Behaviour and error conditions are identical to [`from_utf16`]: decoding
	/// failures are wrapped in `InsertError::Utf16Error` and an overflow will
	/// return `InsertError::InsufficientSpace`.
	///
	/// # Examples
	/// ```
	/// use static_collections::string::*;
	/// use utf16_lit::utf16;
	/// let tmp:Vec<u16>=utf16!("Hello, World!").iter().map(|x| x.to_be()).collect();
	/// let s:Result<StaticString<16>,InsertError>=StaticString::from_utf16be(tmp.as_slice());
	/// assert_eq!(s.unwrap().as_str(), "Hello, World!");
	/// // A surrogate alone is definitely not a valid character.
	/// let tmp:u16=0xd800;
	/// let s:Result<StaticString<16>,InsertError>=StaticString::from_utf16be(&[tmp.to_be()]);
	/// assert!(s.is_err());
	/// ```
	pub fn from_utf16be(v:&[u16])->Result<Self,InsertError>
	{
		let mut r=Self::new();
		for c in char::decode_utf16(v.iter().map(|x| x.to_be()))
		{
			match c
			{
				Ok(ch)=>r.push(ch),
				Err(e)=>return Err(InsertError::Utf16Error(e))
			}?
		}
		Ok(r)
	}

	/// Decodes a native-endian UTF‑16 slice `v` into a `StaticString<N>`,
	/// replacing any malformed sequences with [the replacement character (U+FFFD)](https://doc.rust-lang.org/core/char/constant.REPLACEMENT_CHARACTER.html).
	///
	/// Unlike the previous implementation this variant also returns an error if
	/// the output would not fit in the buffer.
	///
	/// # Examples
	/// ```
	/// use static_collections::string::*;
	/// use utf16_lit::utf16;
	/// let s:Result<StaticString<16>,InsertError>=StaticString::from_utf16_lossy(&utf16!("Hello, World!"));
	/// assert_eq!(s.unwrap().as_str(),"Hello, World!");
	/// let s:Result<StaticString<16>,InsertError>=StaticString::from_utf16_lossy(&[0xd800]);
	/// assert_eq!(s.unwrap().as_str(),String::from(char::REPLACEMENT_CHARACTER));
	/// ```
	pub fn from_utf16_lossy(v:&[u16])->Result<Self,InsertError>
	{
		let mut r=Self::new();
		for c in char::decode_utf16(v.iter().copied())
		{
			let ch=match c
			{
				Ok(ch)=>ch,
				Err(_)=>char::REPLACEMENT_CHARACTER
			};
			r.push(ch)?
		}
		Ok(r)
	}

	/// Decodes a little endian UTF-16-encoded vector `v` into this `StaticString<N>`,
	/// replacing any malformed sequences with [the replacement character (U+FFFD)](https://doc.rust-lang.org/core/char/constant.REPLACEMENT_CHARACTER.html).
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::*;
	/// use utf16_lit::utf16;
	/// let tmp:Vec<u16>=utf16!("Hello, World!").iter().map(|x| x.to_le()).collect();
	/// let s:Result<StaticString<16>,InsertError>=StaticString::from_utf16le_lossy(tmp.as_slice());
	/// assert_eq!(s.unwrap().as_str(),"Hello, World!");
	/// // Lone surrogate
	/// let tmp:u16=0xd800;
	/// let s:Result<StaticString<16>,InsertError>=StaticString::from_utf16le_lossy(&[tmp.to_le()]);
	/// assert_eq!(s.unwrap().as_str(), String::from(char::REPLACEMENT_CHARACTER));
	/// ```
	pub fn from_utf16le_lossy(v:&[u16])->Result<Self,InsertError>
	{
		let mut r=Self::new();
		// If native endianness is LE, `to_le` does not invert bytes.
		// If native endianness is BE, `to_le` will invert bytes.
		for c in char::decode_utf16(v.iter().map(|x| x.to_le()))
		{
			let ch=match c
			{
				Ok(ch)=>ch,
				Err(_)=>char::REPLACEMENT_CHARACTER
			};
			r.push(ch)?;
		}
		Ok(r)
	}

	/// Decodes a big endian UTF-16-encoded vector `v` into this `StaticString<N>`,
	/// replacing any malformed sequences with [the replacement character (U+FFFD)](https://doc.rust-lang.org/core/char/constant.REPLACEMENT_CHARACTER.html).
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::*;
	/// use utf16_lit::utf16;
	/// let tmp:Vec<u16>=utf16!("Hello, World!").iter().map(|x| x.to_be()).collect();
	/// let s:Result<StaticString<16>,InsertError>=StaticString::from_utf16be_lossy(tmp.as_slice());
	/// assert_eq!(s.unwrap().as_str(),"Hello, World!");
	/// // Lone surrogate
	/// let tmp:u16=0xd800;
	/// let s:Result<StaticString<16>,InsertError>=StaticString::from_utf16be_lossy(&[tmp.to_be()]);
	/// assert_eq!(s.unwrap().as_str(),String::from(char::REPLACEMENT_CHARACTER));
	/// ```
	pub fn from_utf16be_lossy(v:&[u16])->Result<Self,InsertError>
	{
		let mut r=Self::new();
		// If native endianness is BE, `to_be` does not invert bytes.
		// If native endianness is LE, `to_be` will invert bytes.
		for c in char::decode_utf16(v.iter().map(|x| x.to_be()))
		{
			let ch=match c
			{
				Ok(ch)=>ch,
				Err(_)=>char::REPLACEMENT_CHARACTER
			};
			r.push(ch)?;
		}
		Ok(r)
	}

	/// Inserts a given `char` to the end of this `StaticString` at specified byte location `index`.
	/// 
	/// Returns `Err(InsertError)` if insertion failed:
	/// - Insertion could fail if it overflows the capacity.
	/// - Insertion could fail if `index` is in the middle of a character.
	/// 
	/// Note that calling this in a loop can result in quadratic time complexity.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let mut s:StaticString<64>=StaticString::from("Hello World!");
	/// s.insert(5,',');
	/// assert_eq!(s.as_str(),"Hello, World!");
	/// ```
	pub fn insert(&mut self,index:usize,ch:char)->Result<(),InsertError>
	{
		if !self.is_char_boundary(index)
		{
			return Err(InsertError::NonUtf8Boundary);
		}
		let ch_len=ch.len_utf8();
		let old_end=self.len();
		if old_end+ch_len>N
		{
			Err(InsertError::InsufficientSpace)
		}
		else
		{
			// Move string contents.
			unsafe
			{
				self.internal.force_resize(old_end+ch_len);
			}
			self.internal.copy_within(index..old_end,index+ch_len);
			ch.encode_utf8(&mut self.internal[index..index+ch_len]);
			Ok(())
		}
	}

	/// Inserts a given string slice to the end of this `StaticString` at specified byte location `index`.
	/// 
	/// Returns `Err(InsertError)` if insertion failed:
	/// - Insertion could fail if it overflows the capacity.
	/// - Insertion could fail if `index` is in the middle of a character.
	/// 
	/// Note that calling this in a loop can result in quadratic time complexity.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let mut s:StaticString<64>=StaticString::from("Hello!");
	/// s.insert_str(5,", World");
	/// assert_eq!(s.as_str(),"Hello, World!");
	/// ```
	pub fn insert_str(&mut self,index:usize,string:&str)->Result<(),InsertError>
	{
		if !self.is_char_boundary(index)
		{
			return Err(InsertError::NonUtf8Boundary);
		}
		let str_len=string.len();
		let old_end=self.len();
		if old_end+str_len>N
		{
			Err(InsertError::InsufficientSpace)
		}
		else
		{
			// Move string contents.
			unsafe
			{
				self.internal.force_resize(old_end+str_len);
			}
			self.internal.copy_within(index..old_end,index+str_len);
			self.internal[index..index+str_len].copy_from_slice(string.as_bytes());
			Ok(())
		}
	}

	/// Shortens this `StaticString` so that no null terminator is present in the string.
	/// 
	/// # Example
	/// ```
	/// use static_collections::string::StaticString;
	/// let mut s:StaticString<64>=StaticString::from("Hello,\0World!");
	/// s.truncate_to_nul();
	/// assert_eq!(s.as_str(),"Hello,");
	/// ```
	pub fn truncate_to_nul(&mut self)
	{
		unsafe
		{
			let new_size=strnlen(self.as_bytes().as_ptr().cast(),self.len());
			self.internal.force_resize(new_size);
		};
	}

	/// Shortens this `StaticString` to the specified `new_len`.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let mut s:StaticString<64>=StaticString::from("Hello, World!");
	/// s.truncate(5);
	/// assert_eq!(s.as_str(),"Hello");
	/// ```
	pub fn truncate(&mut self,new_len:usize)
	{
		if new_len<=self.len()
		{
			unsafe
			{
				self.internal.force_resize(new_len);
			}
			if str::from_utf8(self.as_bytes()).is_err()
			{
				panic!("The new length {new_len} does not lie on UTF-8 character boundary!");
			}
		}
	}

	/// Removes the last character from this `StaticString` and returns it. \
	/// Returns `None` if this `StaticString` is empty.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let mut s:StaticString<64>=StaticString::from("Hello!");
	/// assert_eq!(s.pop(),Some('!'));
	/// assert_eq!(s.as_str(),"Hello");
	/// ```
	pub fn pop(&mut self)->Option<char>
	{
		let s=self.as_str();
		match s.chars().last()
		{
			Some(c)=>
			{
				let new_size=self.len()-c.len_utf8();
				unsafe
				{
					self.internal.force_resize(new_size);
				}
				Some(c)
			}
			None=>None
		}
	}

	/// Removes the character from this `StaticString` specified at byte location and returns it.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let mut s:StaticString<64>=StaticString::from("Hello, World!");
	/// assert_eq!(s.remove(5),',');
	/// assert_eq!(s.as_str(),"Hello World!");
	/// ```
	pub fn remove(&mut self,index:usize)->char
	{
		match str::from_utf8(&self.internal[index..])
		{
			Ok(s)=>
			{
				let c=s.chars().nth(0).unwrap();
				let ch_len=c.len_utf8();
				self.internal.copy_within(index+ch_len..,index);
				unsafe
				{
					self.internal.force_resize(self.len()-ch_len);
				}
				c
			}
			Err(_)=>panic!("Index {index} does not lie on UTF-8 character boundary!")
		}
	}

	/// Returns the length of this string in bytes.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let mut s:StaticString<64>=StaticString::from("Hello, World!");
	/// assert_eq!(s.len(),13);
	/// ```
	#[inline(always)] pub fn len(&self)->usize
	{
		self.internal.len()
	}

	/// Returns the capacity of this string in bytes.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let s:StaticString<128>=StaticString::new();
	/// assert_eq!(s.capacity(),128);
	/// ```
	#[inline(always)] pub fn capacity(&self)->usize
	{
		N
	}

	/// Checks if this string is empty.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let mut s:StaticString<64>=StaticString::from("Hello, World!");
	/// assert_eq!(s.is_empty(),false);
	/// s=StaticString::new();
	/// assert_eq!(s.is_empty(),true);
	/// ```
	#[inline(always)] pub fn is_empty(&self)->bool
	{
		self.len()==0
	}

	/// Remove all contents of the string.
	/// 
	/// # Examples
	/// ```
	/// use static_collections::string::StaticString;
	/// let mut s:StaticString<64>=StaticString::from("Hello, World!");
	/// assert_eq!(s.is_empty(),false);
	/// s.clear();
	/// assert_eq!(s.is_empty(),true);
	/// ```
	#[inline(always)] pub fn clear(&mut self)
	{
		self.internal.clear();
	}
}

impl<const N:usize> Deref for StaticString<N>
{
	type Target = str;

	fn deref(&self) -> &Self::Target
	{
		self.as_str()
	}
}

impl<const N:usize> DerefMut for StaticString<N>
{
	fn deref_mut(&mut self) -> &mut Self::Target
	{
		self.as_mut_str()
	}
}

impl<const N:usize> From<&str> for StaticString<N>
{
	fn from(value:&str)->Self
	{
		let mut s=Self::default();
		if s.insert_str(0,value).is_err()
		{
			panic!("String is too large!");
		}
		s
	}
}

impl<const N:usize> fmt::Write for StaticString<N>
{
	fn write_str(&mut self, s: &str) -> fmt::Result
	{
		match self.push_str(s)
		{
			Ok(())=>Ok(()),
			Err(_)=>Err(fmt::Error)
		}
	}

	fn write_char(&mut self, c: char) -> fmt::Result
	{
		match self.push(c)
		{
			Ok(_)=>Ok(()),
			Err(_)=>Err(fmt::Error)
		}
	}
}

impl<const N:usize> Display for StaticString<N>
{
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
	{
		f.write_str(self.as_str())
	}
}

impl<const N:usize> Debug for StaticString<N>
{
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
	{
		f.write_str(self.as_str())
	}
}

impl<const N:usize> AddAssign<&str> for StaticString<N>
{
	fn add_assign(&mut self, rhs: &str)
	{
		if self.push_str(rhs).is_err()
		{
			panic!("StaticString buffer Overflow!");
		}
	}
}

impl<const N:usize> PartialEq<&str> for StaticString<N>
{
	fn eq(&self,other:&&str)->bool
	{
		self.as_str().eq(*other)
	}
}

/// This routine is the internal helper function for `format_static` macro. Do not use directly.
pub fn _static_fmt_str<const N:usize>(args:fmt::Arguments)->Result<StaticString<N>,InsertError>
{
	let mut s:StaticString<N>=StaticString::new();
	match fmt::write(&mut s,args)
	{
		Ok(_)=>Ok(s),
		Err(_)=>Err(InsertError::InsufficientSpace)
	}
}

/// The `format_static` macro builds a static string via format.
/// 
/// # Example
/// ```
/// use static_collections::*;
/// let s=format_static!(256,"Hello, {}!","World");
/// assert_eq!(s.unwrap(),"Hello, World!");
/// ```
#[macro_export] macro_rules! format_static
{
	($len:expr,$($arg:tt)*)=>
	{
		$crate::string::_static_fmt_str::<$len>(format_args!($($arg)*))
	};
}