measure_null_str/

lib.rs

/*
 * Description: Handle null-terminated strings with explicit length measurement.
 *
 * Copyright (C) 2025 d@nny mc² <dmc2@hypnicjerk.ai>
 * SPDX-License-Identifier: LGPL-3.0-or-later
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published
 * by the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

//! Handle null-terminated strings with explicit length measurement.

/* Ensure any doctest warnings fail the doctest! */
#![doc(test(attr(deny(warnings))))]
#![deny(missing_docs)]
#![cfg_attr(feature = "nightly", feature(maybe_uninit_write_slice))]

use std::{borrow, cmp, ffi, fmt, hash, marker::PhantomData, num, ptr, slice};


/// Similar to [`ffi::CStr`], except that [`Self::from_ptr()`] does not implicitly perform
/// a [`libc::strlen()`].
///
/// The stdlib docs note that this is the eventual goal for `CStr`, but in this case we want to
/// control where the length measurement is performed, so that we can avoid performing it until we
/// actually want to use the string data.
#[derive(Copy, Clone)]
#[repr(transparent)]
pub struct NullTermStr<'s> {
  start: *const ffi::c_char,
  _ph: PhantomData<&'s ffi::c_char>,
}

impl<'s> NullTermStr<'s> {
  /// Wrap a null-terminated C-style string, *without* performing any length calculation or reading
  /// any bytes from the pointed-to value.
  ///
  /// # Safety
  /// `start` must be non-null, and point to a contiguous region of memory which ends with
  /// a null byte. This is the same requirement as for [`ffi::CStr::from_ptr()`].
  #[inline]
  pub const unsafe fn from_ptr(start: *const ffi::c_char) -> Self {
    Self {
      start,
      _ph: PhantomData,
    }
  }

  /// Return the input that was provided to [`Self::from_ptr()`].
  #[inline]
  pub const fn as_ptr(&self) -> *const ffi::c_char { self.start }

  /// Execute [`libc::strlen()`] to calculate the length of the pointed-to string.
  #[inline]
  pub fn measure(self) -> &'s MeasuredNullTermStr {
    let n = unsafe { libc::strlen(self.start) };
    unsafe { MeasuredNullTermStr::given_measurement(self, n) }
  }

  /// Return whether this matches either of the always-present directory entries `"."` or `".."`.
  ///
  /// This is performed without any call to `strlen()`, and will not read past the first null byte.
  #[inline]
  pub fn match_dir_entries_unmeasured(&self) -> bool {
    let mut p: *const u8 = self.start.cast();
    match unsafe { p.read() } {
      /* This is a zero-length string (should never happen with directory entries). */
      0 => return false,
      /* This begins with a '.' character, so continue. */
      b'.' => (),
      _ => return false,
    }
    /* We know it's not terminated yet, so we can advance the pointer by 1. */
    p = unsafe { p.add(1) };
    match unsafe { p.read() } {
      /* This was the string ".". */
      0 => return true,
      /* This is ".." so far. */
      b'.' => (),
      _ => return false,
    }
    /* Advance a final time. */
    p = unsafe { p.add(1) };
    match unsafe { p.read() } {
      /* This was the string "..". */
      0 => true,
      _ => false,
    }
  }
}

impl cmp::PartialEq for NullTermStr<'_> {
  fn eq(&self, rhs: &Self) -> bool { ptr::eq(self.start, rhs.start) }
}
impl cmp::Eq for NullTermStr<'_> {}
impl hash::Hash for NullTermStr<'_> {
  fn hash<H>(&self, state: &mut H)
  where H: hash::Hasher {
    ptr::hash(self.start, state);
  }
}

impl fmt::Debug for NullTermStr<'_> {
  fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
    let s: &ffi::CStr = self.measure().into();
    f.debug_tuple("NullTermStr")
      .field(&self.start)
      .field(&s)
      .finish()
  }
}

/// The more direct analog to [`ffi::CStr`] which explicitly knows the length of its string data.
#[repr(transparent)]
pub struct MeasuredNullTermStr {
  inner: [ffi::c_char],
}

impl MeasuredNullTermStr {
  /// Construct a C-style string with a known length.
  ///
  /// # Safety
  /// The length `n` must correctly describe the number of bytes in the string value pointed to by
  /// `s`, *without* including the trailing null byte. This is to say that `n` may be 0, but the
  /// string pointed to by `s` must be non-null, and must point to a region of memory exactly 1 byte
  /// longer than `n`.
  ///
  /// If the string's length is not known in advance, use [`NullTermStr::measure()`], which
  /// internally calls this method.
  #[inline]
  pub const unsafe fn given_measurement<'s>(s: NullTermStr<'s>, n: usize) -> &'s Self {
    let n = unsafe { n.unchecked_add(1) };
    let bytes: &'s [ffi::c_char] = unsafe { slice::from_raw_parts(s.as_ptr(), n) };
    unsafe { &*(bytes as *const [ffi::c_char] as *const Self) }
  }

  /// Translate a reference to a byte slice into a measured null-terminated string.
  ///
  /// This method will panic if `s` is empty, if it does not end with a null byte, or if it contains
  /// any internal null bytes.
  #[inline]
  pub fn from_bytes_with_nul<'s>(s: &'s [u8]) -> &'s Self {
    assert!(!s.is_empty(), "expected non-empty slice");
    assert_eq!(s[s.len() - 1], 0, "slice must end with null byte");
    assert_eq!(
      memchr::memchr(0, s),
      Some(s.len() - 1),
      "slice must contain no internal null bytes"
    );
    unsafe { Self::from_bytes_with_nul_unchecked(s) }
  }

  /// Translate a reference to a byte slice into a measured null-terminated string.
  ///
  /// # Safety
  /// `s` must be non-empty, must end with a null byte, and may not contain any internal null
  /// bytes. [`Self::from_bytes_with_nul()`] may be used to validate slices.
  #[inline]
  pub const unsafe fn from_bytes_with_nul_unchecked<'s>(s: &'s [u8]) -> &'s Self {
    let bytes: &'s [ffi::c_char] = unsafe { slice::from_raw_parts(s.as_ptr().cast(), s.len()) };
    unsafe { &*(bytes as *const [ffi::c_char] as *const Self) }
  }

  /// Return a slice of the internal string data, *without* trailing null byte.
  #[inline]
  pub const fn as_bytes(&self) -> &[u8] {
    unsafe { slice::from_raw_parts(self.as_ptr().cast(), self.len()) }
  }

  /// Translate this data to a platform-specific string, suitable for translation to
  /// [`Path`](std::path::Path).
  #[inline]
  pub fn as_os_str(&self) -> &ffi::OsStr {
    use std::os::unix::ffi::OsStrExt;
    ffi::OsStr::from_bytes(self.as_bytes())
  }

  #[inline]
  const fn as_ptr(&self) -> *const ffi::c_char { self.as_unmeasured().as_ptr() }

  /// Length of the internal string data, *without* trailing null byte.
  #[inline]
  pub const fn len(&self) -> usize { unsafe { self.inner.len().unchecked_sub(1) } }

  /// Whether the internal string data points to a single null byte.
  #[inline]
  pub const fn is_empty(&self) -> bool { self.len() == 0 }

  /// Length of the internal string data, *with* trailing null byte.
  #[inline]
  pub const fn len_with_nul(&self) -> num::NonZeroUsize {
    unsafe { num::NonZeroUsize::new_unchecked(self.inner.len()) }
  }

  /// Return a slice of the internal string data, *with* trailing null byte.
  #[inline]
  pub const fn as_bytes_with_nul(&self) -> &[u8] {
    unsafe { slice::from_raw_parts(self.as_ptr().cast(), self.len_with_nul().get()) }
  }

  /// Retrieve the internal string data, which may be converted to a pointer again.
  #[inline]
  pub const fn as_unmeasured<'s>(&'s self) -> NullTermStr<'s> {
    unsafe { NullTermStr::from_ptr(self.inner.as_ptr()) }
  }

  /// Allocate the necessary space in `v` and copy over the internal string data.
  ///
  /// `v`'s length will be reset to the length of the internal string data, although it will not
  /// reallocate the underlying vector.
  #[inline]
  pub fn clone_into(&self, v: &mut NullTermString) {
    let NullTermString(v) = v;
    v.clear();
    let src = self.as_bytes_with_nul();
    v.reserve(src.len());
    unsafe {
      cfg_if::cfg_if! {
        if #[cfg(feature = "nightly")] {
          v.spare_capacity_mut()[..src.len()].write_copy_of_slice(src);
        } else {
          v.as_mut_ptr()
            .copy_from_nonoverlapping(src.as_ptr(), src.len());
        }
      }
      v.set_len(src.len());
    }
  }
}

impl<'s> From<&'s [u8]> for &'s MeasuredNullTermStr {
  fn from(s: &'s [u8]) -> Self { MeasuredNullTermStr::from_bytes_with_nul(s) }
}

impl<'s> From<&'s MeasuredNullTermStr> for &'s [u8] {
  fn from(s: &'s MeasuredNullTermStr) -> Self { s.as_bytes_with_nul() }
}

impl<'s> From<&'s ffi::CStr> for &'s MeasuredNullTermStr {
  fn from(s: &'s ffi::CStr) -> Self {
    unsafe { MeasuredNullTermStr::from_bytes_with_nul_unchecked(s.to_bytes_with_nul()) }
  }
}

impl<'s> From<&'s MeasuredNullTermStr> for &'s ffi::CStr {
  fn from(s: &'s MeasuredNullTermStr) -> &'s ffi::CStr {
    unsafe { ffi::CStr::from_bytes_with_nul_unchecked(s.as_bytes_with_nul()) }
  }
}

impl cmp::PartialEq for MeasuredNullTermStr {
  fn eq(&self, rhs: &Self) -> bool { self.as_bytes().eq(rhs.as_bytes()) }
}
impl cmp::Eq for MeasuredNullTermStr {}
impl cmp::PartialOrd for MeasuredNullTermStr {
  fn partial_cmp(&self, rhs: &Self) -> Option<cmp::Ordering> { Some(self.cmp(rhs)) }
}
impl cmp::Ord for MeasuredNullTermStr {
  fn cmp(&self, rhs: &Self) -> cmp::Ordering { self.as_bytes().cmp(rhs.as_bytes()) }
}
impl hash::Hash for MeasuredNullTermStr {
  fn hash<H>(&self, state: &mut H)
  where H: hash::Hasher {
    self.as_bytes_with_nul().hash(state);
  }
}

impl fmt::Debug for MeasuredNullTermStr {
  fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
    let s: &ffi::CStr = (*self).into();
    f.debug_tuple("MeasuredNullTermStr")
      .field(&self.as_ptr())
      .field(&self.len())
      .field(&s)
      .finish()
  }
}

/// Owned version of [`MeasuredNullTermStr`].
///
/// Create with [`Self::new()`], then copy over data with [`MeasuredNullTermStr::clone_into()`].
#[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct NullTermString(Vec<u8>);

impl NullTermString {
  /// Create a new owned string without any data reserved.
  pub const fn new() -> Self { Self(Vec::new()) }

  /// Create a new owned string with at least `n` bytes reserved.
  pub fn with_capacity(n: usize) -> Self { Self(Vec::with_capacity(n)) }
}

impl Default for NullTermString {
  fn default() -> Self { Self::new() }
}

impl From<NullTermString> for ffi::CString {
  fn from(x: NullTermString) -> Self {
    let NullTermString(v) = x;
    unsafe { ffi::CString::from_vec_with_nul_unchecked(v) }
  }
}

impl From<ffi::CString> for NullTermString {
  fn from(x: ffi::CString) -> Self { Self(x.into_bytes_with_nul()) }
}

impl fmt::Debug for NullTermString {
  fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
    let s: ffi::CString = self.clone().into();
    f.debug_tuple("NullTermString").field(&s).finish()
  }
}

impl borrow::Borrow<MeasuredNullTermStr> for NullTermString {
  fn borrow(&self) -> &MeasuredNullTermStr { self.as_null_term_str() }
}

impl borrow::ToOwned for MeasuredNullTermStr {
  type Owned = NullTermString;

  fn to_owned(&self) -> Self::Owned {
    let mut ret = NullTermString::default();
    Self::clone_into(self, &mut ret);
    ret
  }

  fn clone_into(&self, target: &mut Self::Owned) { Self::clone_into(self, target); }
}

/// Allow [`NullTermString`] instances to be interpreted as references to [`MeasuredNullTermStr`].
pub trait AsNullTermStr {
  /// Similar to [`AsRef`] or [`Borrow`](std::borrow::Borrow).
  ///
  /// This is necessary because those traits require the use of DSTs (dynamically-sized types) and
  /// cannot be made to work with tagged lifetimes like we use in this module.
  fn as_null_term_str(&self) -> &MeasuredNullTermStr;
}

impl AsNullTermStr for MeasuredNullTermStr {
  fn as_null_term_str(&self) -> &MeasuredNullTermStr { self }
}

impl AsNullTermStr for NullTermString {
  fn as_null_term_str(&self) -> &MeasuredNullTermStr {
    unsafe { MeasuredNullTermStr::from_bytes_with_nul_unchecked(&self.0) }
  }
}


#[cfg(test)]
mod test {
  use proptest::{prelude::*, string::bytes_regex};

  use super::*;

  #[test]
  fn matches_dir_entries() {
    let s = NullTermString(vec![b'.', 0]);
    let s = s.as_null_term_str().as_unmeasured();
    assert!(s.match_dir_entries_unmeasured());

    let s = NullTermString(vec![b'.', b'.', 0]);
    let s = s.as_null_term_str().as_unmeasured();
    assert!(s.match_dir_entries_unmeasured());
  }

  proptest! {
    #[test]
    fn not_dir_entries(
      mut s in bytes_regex("(?s-u:[^\x00]*)").unwrap()
        .prop_filter("not '.' or '..'",
                     |v| !(&v[..] == b"." || &v[..] == b".."))
    ) {
      s.push(0);
      let s = NullTermString(s);
      let s = s.as_null_term_str().as_unmeasured();
      prop_assert!(!s.match_dir_entries_unmeasured());
    }

    #[test]
    fn cstring_roundtrip(s in any::<Vec<u8>>()) {
      let n1 = NullTermString(s);
      let c1: ffi::CString = n1.clone().into();
      let n2: NullTermString = c1.into();
      prop_assert_eq!(n1, n2);
    }

    #[test]
    fn nonnull_roundtrip(mut s in bytes_regex("(?s-u:[^\x00]*)").unwrap()) {
      s.push(0);
      let s = NullTermString(s);
      let c: ffi::CString = s.clone().into();
      let c2: &ffi::CStr = s.as_null_term_str().into();
      prop_assert_eq!(c.as_c_str(), c2);
    }

    #[test]
    fn slice_roundtrip(mut s in bytes_regex("(?s-u:[^\x00]*)").unwrap()) {
      s.push(0);
      let s = NullTermString(s);
      let s: &MeasuredNullTermStr = s.as_null_term_str();
      let sl: &[u8] = s.into();
      let s2: &MeasuredNullTermStr = sl.into();
      prop_assert_eq!(s, s2);
      let sl2: &[u8] = s2.into();
      prop_assert_eq!(sl, sl2);
    }

    #[test]
    fn nonnull_ref(s in bytes_regex("(?s-u:[^\x00]*)").unwrap()) {
      let mut t = s.clone();
      t.push(0);
      let v = NullTermString(t.clone());
      prop_assert_eq!(&t[..], v.as_null_term_str().as_bytes_with_nul());
      prop_assert_eq!(&s[..], v.as_null_term_str().as_bytes());
    }

    #[test]
    fn nonnull_measure(mut s in bytes_regex("(?s-u:[^\x00]*)").unwrap()) {
      s.push(0);
      let s = NullTermString(s);
      let s = s.as_null_term_str();
      prop_assert_eq!(s, s.as_unmeasured().measure());
    }

    #[test]
    fn nonnull_clone_into(mut s in bytes_regex("(?s-u:[^\x00]*)").unwrap()) {
      s.push(0);
      let v = NullTermString(s);
      let s = v.as_null_term_str();
      let mut v2 = NullTermString(Vec::new());
      s.clone_into(&mut v2);
      let s2 = v2.as_null_term_str();
      prop_assert_eq!(s, s2);
      prop_assert_eq!(v, v2);
    }
  }
}