static_collections/ffi/

c_str.rs

// C-String

use core::{cmp::Ordering, ffi::CStr, fmt, mem::MaybeUninit, ops::AddAssign, slice};

/// This error is used to indicate the string is not null-terminated.
#[derive(Debug)]
pub struct NotNullTerminatedError;

// Usually, CRT routines are seriously optimized by target vendor.
// However, it depends on target vendor's implementation, and the target vendor may not even provide CRT at all.
#[cfg(feature = "use_crt")]
unsafe extern "C"
{
	fn strncat(dest:*mut i8,src:*const i8,cch:usize)->*mut i8;
	fn strncmp(s1:*const i8,s2:*const i8,cch:usize)->isize;
	fn strncpy(dest:*mut i8,src:*const i8,cch:usize)->*mut i8;
	pub(crate) fn strnlen(str:*const i8,cch:usize)->usize;
}

// If usage of CRT is disabled, implement CRT on our own.

#[cfg(not(feature = "use_crt"))]
#[unsafe(no_mangle)] pub(crate) unsafe extern "C" fn strnlen(str:*const i8,cch:usize)->usize
{
	let s=unsafe{slice::from_raw_parts(str,cch)};
	s.iter().position(|&v| v==0).unwrap_or(cch)
}

#[cfg(not(feature = "use_crt"))]
#[unsafe(no_mangle)] unsafe extern "C" fn strncpy(dest:*mut i8,src:*const i8,cch:usize)->*mut i8
{
	let s1=unsafe{slice::from_raw_parts_mut(dest,cch)};
	let s2=unsafe{slice::from_raw_parts(src,cch)};
	for (i,&c) in s2.iter().enumerate()
	{
		s1[i]=c;
		if c==0
		{
			break;
		}
	}
	dest
}

#[cfg(not(feature = "use_crt"))]
#[unsafe(no_mangle)] unsafe extern "C" fn strncmp(str1:*const i8,str2:*const i8,cch:usize)->isize
{
	let s1=unsafe{slice::from_raw_parts(str1,cch)};
	let s2=unsafe{slice::from_raw_parts(str2,cch)};
	for i in 0..cch
	{
		let diff=s1[i]-s2[i];
		if diff!=0
		{
			return diff as isize
		}
	}
	0
}

#[cfg(not(feature = "use_crt"))]
#[unsafe(no_mangle)] unsafe extern "C" fn strncat(dest:*mut i8,src:*const i8,cch:usize)->*mut i8
{
	let start_index=unsafe{strnlen(dest,usize::MAX)};
	let s1=unsafe{slice::from_raw_parts_mut(dest.add(start_index),cch)};
	let s2=unsafe{slice::from_raw_parts(src,cch)};
	for (i,&c) in s2.iter().enumerate()
	{
		s1[i]=c;
		if c==0
		{
			break;
		}
	}
	dest
}

/// A C-compatible, growable but fixed-capacity string. \
/// The exact encoding of the string depends on the target platform. \
/// The `StaticCString` guarantees a null-terminator at the end, so the maximum length is 1 less than capacity.
#[derive(Clone)]
pub struct StaticCString<const N:usize>
{
	buffer:MaybeUninit<[i8;N]>
}

impl<const N:usize> StaticCString<N>
{
	/// Creates a new empty `StaticCString`.
	/// 
	/// Given that the string is empty, the buffer that contains the string isn't initialized.
	/// This means the initial operation is very inexpensive.
	/// 
	/// # Example
	/// ```
	/// use static_collections::ffi::c_str::StaticCString;
	/// let s:StaticCString<32>=StaticCString::from(c"Hello, World!");
	/// assert_eq!(s.len(),13);
	/// ```
	pub const fn new()->Self
	{
		let mut s=Self{buffer:MaybeUninit::uninit()};
		unsafe
		{
			// Just ensure the first byte is null-character.
			s.buffer.assume_init_mut()[0]=0;
		}
		s
	}

	/// Returns the length of the static-string by using `strnlen`.
	/// 
	/// # Example
	/// ```
	/// use static_collections::ffi::c_str::StaticCString;
	/// let s:StaticCString<32>=StaticCString::from(c"Hello, World!");
	/// assert_eq!(s.len(),13);
	/// ```
	#[inline(always)] pub fn len(&self)->usize
	{
		unsafe
		{
			strnlen(self.buffer.assume_init_ref().as_ptr(),N)
		}
	}

	#[inline(always)] pub fn is_empty(&self)->bool
	{
		self.len()==0
	}

	/// Returns the capacity of the static-string.
	/// 
	/// # Example
	/// ```
	/// use static_collections::ffi::c_str::StaticCString;
	/// let s:StaticCString<32>=StaticCString::from(c"Hello, World!");
	/// assert_eq!(s.capacity(),32);
	/// ```
	#[inline(always)] pub const fn capacity(&self)->usize
	{
		N
	}

	/// Returns the immutable pointer to the first character.
	/// 
	/// The returned pointer can be passed to C-FFI routines that accepts raw pointers.
	#[inline(always)] pub const fn as_ptr(&self)->*const i8
	{
		unsafe
		{
			self.buffer.assume_init_ref().as_ptr()
		}
	}

	/// Returns the mutable pointer to the first character.
	/// 
	/// The returned pointer can be passed to C-FFI routines that accepts raw pointers.
	#[inline(always)] pub const fn as_mut_ptr(&mut self)->*mut i8
	{
		unsafe
		{
			self.buffer.assume_init_mut().as_mut_ptr()
		}
	}

	/// Returns the contents of this `StaticCString` as a slice of bytes.
	/// 
	/// The returned slice does **not** contain the trailing null-terminator, and it is
	/// guaranteed to not contain any interior null bytes. If you need this null-terminator,
	/// use `StaticCString::as_bytes_with_nul` instead.
	#[inline(always)] pub fn as_bytes(&self)->&[u8]
	{
		let l=self.len();
		unsafe
		{
			slice::from_raw_parts(self.as_ptr().cast(),l)
		}
	}

	/// Returns the contents of this `StaticCString` as a mutable slice of bytes.
	/// 
	/// The returned slice does **not** contain the trailing null-terminator, and it is
	/// guaranteed to not contain any interior null bytes. If you need this null-terminator,
	/// use `StaticCString::as_mut_bytes_with_nul` instead.
	#[inline(always)] pub fn as_mut_bytes(&mut self)->&mut [u8]
	{
		let l=self.len();
		unsafe
		{
			slice::from_raw_parts_mut(self.as_mut_ptr().cast(),l)
		}
	}

	/// Returns the contents of this `StaticCString` as a slice of bytes, including the trailing null-terminator.
	#[inline(always)] pub fn as_bytes_with_nul(&self)->&[u8]
	{
		let l=self.len();
		unsafe
		{
			slice::from_raw_parts(self.as_ptr().cast(),l+1)
		}
	}

	/// Returns the contents of this `StaticCString` as a slice of bytes, including the trailing null-terminator.
	/// 
	/// # Safety
	/// You must ensure the slice contains a null-terminator throughout the lifetime of the slice.
	#[inline(always)] pub unsafe fn as_mut_bytes_with_nul(&mut self)->&mut [u8]
	{
		let l=self.len();
		unsafe
		{
			slice::from_raw_parts_mut(self.as_mut_ptr().cast(),l+1)
		}
	}

	#[inline(always)] pub fn as_c_str(&self)->&CStr
	{
		unsafe
		{
			CStr::from_ptr(self.as_ptr())
		}
	}
}

impl<'a,const N:usize> StaticCString<N>
{
	/// Gets an immutable fixed-capacity StaticCString object reference from a raw pointer.
	/// 
	/// Returns `Err(NotNullTerminatedError)` if the string is not null-terminated.
	/// 
	/// # Safety
	/// You must ensure the lifetime of the `&'a StaticCString` lives long enough. \
	/// You must ensure `ptr` points to a valid region that has `N` bytes.
	/// 
	/// # Panic
	/// The `strnlen` will be called by this function. It may trigger an exception. \
	/// The program may either panic, crash, or run normally if the exception is handled.
	#[inline(always)] pub unsafe fn from_raw_ptr(ptr:*const i8)->Result<&'a Self,NotNullTerminatedError>
	{
		let r:&Self=unsafe{&*ptr.cast()};
		if r.len()>=N
		{
			Err(NotNullTerminatedError)
		}
		else
		{
			Ok(r)
		}
	}
	
	/// Gets a mutable fixed-capacity StaticCString object reference from a raw pointer.
	/// 
	/// Returns `Err(NotNullTerminatedError)` if the string is not null-terminated.
	/// 
	/// # Safety
	/// You must ensure the lifetime of the `&'a mut StaticCString` lives long enough. \
	/// You must ensure `ptr` points to a valid region that has `N` bytes.
	/// 
	/// # Panic
	/// The `strnlen` will be called by this function. It may trigger an exception. \
	/// The program may either panic, crash, or run normally if the exception is handled.
	#[inline(always)] pub unsafe fn from_raw_mut_ptr(ptr:*mut i8)->Result<&'a mut Self,NotNullTerminatedError>
	{
		let r:&mut Self=unsafe{&mut *ptr.cast()};
		if r.len()>=N
		{
			Err(NotNullTerminatedError)
		}
		else
		{
			Ok(r)
		}
	}
}

impl<const N:usize> From<&CStr> for StaticCString<N>
{
	fn from(value: &CStr) -> Self
	{
		let mut s=Self::new();
		unsafe
		{
			let p=value.as_ptr();
			let q=s.buffer.assume_init_mut().as_mut_ptr();
			strncpy(q,p,N);
			// Force the final byte to null-character.
			q.add(N-1).write(0);
		}
		s
	}
}

impl<const M:usize,const N:usize> PartialEq<StaticCString<M>> for StaticCString<N>
{
	fn eq(&self, other: &StaticCString<M>) -> bool
	{
		unsafe
		{
			let p=self.buffer.assume_init_ref().as_ptr();
			let q=other.buffer.assume_init_ref().as_ptr();
			strncmp(p,q,if M<N {M} else {N})==0
		}
	}
}

impl<const M:usize,const N:usize> PartialOrd<StaticCString<M>> for StaticCString<N>
{
	fn partial_cmp(&self, other: &StaticCString<M>) -> Option<Ordering>
	{
		let r=unsafe
		{
			let p=self.buffer.assume_init_ref().as_ptr();
			let q=other.buffer.assume_init_ref().as_ptr();
			strncmp(p,q,if M<N {M} else {N})
		};
		match r
		{
			..0=>Some(Ordering::Less),
			0=>Some(Ordering::Equal),
			1.. =>Some(Ordering::Greater)
		}
	}
}

impl<const M:usize,const N:usize> AddAssign<StaticCString<M>> for StaticCString<N>
{
	fn add_assign(&mut self, rhs: StaticCString<M>)
	{
		unsafe
		{
			let p=rhs.buffer.assume_init_ref().as_ptr();
			let q=self.buffer.assume_init_mut().as_mut_ptr();
			strncat(q,p,if M<N {M} else {N});
			// Force the final byte to null-character.
			q.add(N-1).write(0);
		}
	}
}

// The CString type does not implement Display trait. So won't we.
// Only Debug trait will be implemented.
impl<const N:usize> fmt::Debug for StaticCString<N>
{
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
	{
		self.as_c_str().fmt(f)
	}
}

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

unsafe impl<const N:usize> Send for StaticCString<N> {}
unsafe impl<const N:usize> Sync for StaticCString<N> {}