Struct SSlice

pub struct SSlice<T>
where
    T: Sentinel,
{ /* private fields */ }

A sentinel-terminated slice.

Implementations

impl<T: Sentinel> SSlice<T>

pub const unsafe fn from_ptr<'a>(ptr: *const T) -> &'a Self

Creates a new SSlice<T> instance from the provided pointer.

Safety

The elements referenced by the provided pointer, until the first sentinel value, must be part of the same allocated object. They must be properly initialized and safe for reads.

This invariant must remain until the end of the lifetime 'a (at least).

pub unsafe fn from_mut_ptr<'a>(ptr: *mut T) -> &'a mut Self

Creates a new SSlice<T> instance from the provided pointer.

Safety

The elements referenced by the provided pointer, until the first sentinel value, must be part of the same allocated object. They must be properly initialized and safe for reads and writes.

This invariant must remain until the end of the lifetime 'a (at least).

pub fn from_slice_split(slice: &[T]) -> Option<(&Self, &[T])>

Creates a SSlice<T> instance from the provided slice.

If the slice contains a sentinel character, the function retuns a SSlice<T> referencing the elements stored in T up to (and including) the first sentinel character. The remaining of the slice is returned as well.

Otherwise, the function returns None

Examples

use sentinel::SSlice;

let input = b"abc\0def";
let (a, b) = SSlice::<u8>::from_slice_split(input).unwrap();
assert_eq!(a, b"abc");
assert_eq!(b, b"def");

pub fn from_slice(slice: &[T]) -> Option<&Self>

Creates a SSlice<T> instance from the provided slice.

If the slice contains a sentinel character, the function returns SSlice<T> referencing the elements stored in T up to (and including) the first sentinel character. Otherwise, the function returns None.

Examples

use sentinel::SSlice;

let sslice = SSlice::<u8>::from_slice(b"abc\0def").unwrap();
assert_eq!(sslice, b"abc");

pub fn from_slice_split_mut(slice: &mut [T]) -> Option<(&mut Self, &mut [T])>

Creates a SSlice<T> instance from the provided slice.

If the slice contains a sentinel character, the function retuns a SSlice<T> referencing the elements stored in T up to (and including) the first sentinel character. The remaining of the slice is returned as well.

Otherwise, the function returns None

Examples

use sentinel::SSlice;

let mut slice = [1, 2, 3, 0, 4, 5, 6];
let (sslice, remainder) = SSlice::<u8>::from_slice_split_mut(&mut slice).unwrap();

assert_eq!(sslice, &[1, 2, 3]);
assert_eq!(remainder, [4, 5, 6]);

pub fn from_slice_mut(slice: &mut [T]) -> Option<&mut Self>

Creates a SSlice<T> instance from the provided slice.

If the slice contains a sentinel character, the function returns SSlice<T> referencing the elements stored in T up to (and including) the first sentinel character. Otherwise, the function returns None.

Examples

use sentinel::SSlice;

let mut slice = [1, 2, 3, 0, 4, 5, 6];
let sslice = SSlice::<u8>::from_slice_mut(&mut slice).unwrap();

assert_eq!(sslice, &[1, 2, 3]);

pub const fn as_ptr(&self) -> *const T

Returns a pointer to the first element that is part of the slice.

Notes

This pointer is always valid and will reference an initialized instance of T. Note, however, that this value cannot be modified (even if it supports interior mutability). Or, rather, if it is a sentinel, it must remain a sentinel.

pub fn as_mut_ptr(&mut self) -> *mut T

Returns a pointer to the first element that is part of the slice.

Notes

This pointer is always valid and will reference an initialized instance of T. Note, however, that this value cannot be modified. Or, rather, if it is a sentinel, it must remain a sentinel.

pub fn iter(&self) -> &Iter<T>

Returns an iterator over the elements of the slice.

Examples

let s = sentinel::cstr!("Hello!");
let mut iter = s.iter();

assert_eq!(iter.next(), Some(&b'H'));
assert_eq!(iter.next(), Some(&b'e'));
assert_eq!(iter.next(), Some(&b'l'));
assert_eq!(iter.next(), Some(&b'l'));
assert_eq!(iter.next(), Some(&b'o'));
assert_eq!(iter.next(), Some(&b'!'));
assert_eq!(iter.next(), None);

pub fn iter_mut(&mut self) -> &mut Iter<T>

Returns an iterator over the elements of the slice.

Examples

let mut array = *b"abc\0";
let mut sslice = sentinel::SSlice::<u8>::from_slice_mut(&mut array).unwrap();
let mut iter = sslice.iter_mut();

*iter.next().unwrap() = b'1';
*iter.next().unwrap() = b'2';
*iter.next().unwrap() = b'3';

assert_eq!(sslice, b"123");

pub unsafe fn get_unchecked<Idx>(&self, index: Idx) -> &Idx::Output

where Idx: SliceIndex<T>,

Indexes into this SSlice<T> instance without checking the bounds.

Safety

index must be in bounds.

pub unsafe fn get_unchecked_mut<Idx>(&mut self, index: Idx) -> &mut Idx::Output

where Idx: SliceIndex<T>,

Indexes into this SSlice<T> instance without checking the bounds.

Safety

index must be in bounds.

pub fn len(&self) -> usize

Returns the length of the SSlice<T>. This is the number of elements referenced by that instance, not including the terminating sentinel character.

Examples

use sentinel::SSlice;

let sslice = SSlice::<u8>::from_slice(b"Hello\0World").unwrap();
assert_eq!(sslice.len(), 5);

pub fn is_empty(&self) -> bool

Returns whether the slice is currently empty.

Examples

use sentinel::SSlice;

assert!(!SSlice::<u8>::from_slice(b"123\0").unwrap().is_empty());
assert!(SSlice::<u8>::from_slice(b"\0").unwrap().is_empty());

pub fn first(&self) -> Option<&T>

Returns the first element of the slice, or None if it is empty.

Examples

use sentinel::SSlice;

assert_eq!(SSlice::<u8>::from_slice(b"123\0").unwrap().first(), Some(&b'1'));
assert_eq!(SSlice::<u8>::from_slice(b"\0").unwrap().first(), None);

pub fn first_mut(&mut self) -> Option<&mut T>

Returns the first element of the slice, or None if it is empty.

Examples

use sentinel::SSlice;

let mut array = [1, 2, 3, 0];
let mut sslice = SSlice::<u8>::from_slice_mut(&mut array).unwrap();

*sslice.first_mut().unwrap() = 0;

assert_eq!(sslice.first_mut(), None);

pub fn split_first(&self) -> Option<(&T, &Self)>

Returns a pointer to the first element of the slice, and a slice to the remaining elements. None is returned if the slice is empty.

Examples

use sentinel::SSlice;

let sslice = SSlice::<u8>::from_slice(b"1234\0").unwrap();
let (first, remainder) = sslice.split_first().unwrap();
assert_eq!(*first, '1' as u8);
assert_eq!(remainder, b"234");

pub fn split_first_mut(&mut self) -> Option<(&mut T, &mut Self)>

Returns a pointer to the first element of the slice, and a slice to the remaining elements. None is returned if the slice is empty.

Examples

use sentinel::SSlice;

let mut array = *b"1234\0";
let mut sslice = SSlice::<u8>::from_slice_mut(&mut array).unwrap();
let (first, remainder) = sslice.split_first_mut().unwrap();
assert_eq!(*first, '1' as u8);
assert_eq!(remainder, b"234");

*first = 0;

assert!(sslice.is_empty());

pub const unsafe fn raw_first(&self) -> &T

Returns a shared reference to the first element of the slice, or a sentinel value if the slice is empty.

Safety

If the returned value is a sentinel, it must not be modified (or rather, it must remain a sentinel).

pub unsafe fn raw_first_mut(&mut self) -> &mut T

Returns an exclusive reference to the first element of the slice, or a sentinel value if the slice is empty.

Safety

If the returned value is a sentinel, it must not be modified (or rather, it must remain a sentinel).

pub fn as_slice(&self) -> &[T]

Returns a slice referencing every element of this SSlice<T>, not including the terminating sentinel character.

pub fn as_slice_mut(&mut self) -> &mut [T]

Returns a slice referencing every element of this SSlice<T>, not including the terminating sentinel character.

pub fn as_slice_with_sentinel(&self) -> &[T]

Returns a slice referencing every element of this SSlice<T>, including the terminating sentinel character.

pub fn as_slice_with_sentinel_mut(&mut self) -> &mut [T]

Returns a slice referencing every element of this SSlice<T>, including the terminating sentinel character.

pub const fn cast_to_slice_of_ptrs<'a>(slice: &'a [&Self]) -> &'a [*const T]

Casts a slice of SSlice<T> values into a slice of *const Ts.

pub const unsafe fn cast_to_slice_of_sslices<'a>( slice: &[*const T], ) -> &[&'a Self]

Casts a slice of *const Ts into a slice of SSlice<T> values.

Safety

It must be safe to call SSlice::from_ptr for every pointer in the slice (for the lifetime 'a).

impl SSlice<u8>

pub const fn from_std_cstr(cstr: &CStr) -> &Self

Creates a new SSlice<T> from the provided standard core::ffi::CStr.

pub fn as_std_cstr(&self) -> &CStr

Turns this SSlice<T> into a standard core::ffi::CStr.

pub const fn cast_to_slice_of_cstrs<'a>( slice: &'a [&Self], ) -> &'a [*const c_char]

Casts a slice of CStr values into a slice of *const c_chars.

pub const fn display(&self) -> &Display

An implementation of fmt::Display and fmt::Debug for the CStr type.

When an invalid character is found, the REPLACEMENT_CHARACTER is displayed instead.

Trait Implementations

impl<T, const N: usize> AsMut<SSlice<T>> for InlineSSlice<T, N>

where T: Sentinel,

fn as_mut(&mut self) -> &mut SSlice<T>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T: Sentinel, A: Allocator> AsMut<SSlice<T>> for SBox<T, A>

fn as_mut(&mut self) -> &mut SSlice<T>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T, const N: usize> AsRef<SSlice<T>> for InlineSSlice<T, N>

where T: Sentinel,

fn as_ref(&self) -> &SSlice<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: Sentinel, A: Allocator> AsRef<SSlice<T>> for SBox<T, A>

fn as_ref(&self) -> &SSlice<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: Sentinel, A: Allocator> Borrow<SSlice<T>> for SBox<T, A>

fn borrow(&self) -> &SSlice<T>

Immutably borrows from an owned value.

impl<T: Sentinel, A: Allocator> BorrowMut<SSlice<T>> for SBox<T, A>

fn borrow_mut(&mut self) -> &mut SSlice<T>

Mutably borrows from an owned value.

impl<T: Debug + Sentinel> Debug for SSlice<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Sentinel> Drop for SSlice<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Sentinel + Hash> Hash for SSlice<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a, T: Sentinel> IntoIterator for &'a SSlice<T>

type IntoIter = &'a Iter<T>

Which kind of iterator are we turning this into?

type Item = &'a T

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T: Sentinel> IntoIterator for &'a mut SSlice<T>

type IntoIter = &'a mut Iter<T>

Which kind of iterator are we turning this into?

type Item = &'a mut T

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: Ord + Sentinel> Ord for SSlice<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T1, T2> PartialEq<[T2]> for SSlice<T1>

where T1: PartialEq<T2> + Sentinel,

fn eq(&self, other: &[T2]) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T1, T2, const N: usize> PartialEq<[T2; N]> for SSlice<T1>

where T1: PartialEq<T2> + Sentinel,

fn eq(&self, other: &[T2; N]) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, U, const N: usize> PartialEq<InlineSSlice<U, N>> for SSlice<T>

where T: PartialEq<U> + Sentinel, U: Sentinel,

fn eq(&self, other: &InlineSSlice<U, N>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, T2, A> PartialEq<SBox<T, A>> for SSlice<T2>

where T: Sentinel, T2: Sentinel + PartialEq<T>, A: Allocator,

fn eq(&self, other: &SBox<T, A>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T1, T2> PartialEq<SSlice<T2>> for [T1]

where T1: PartialEq<T2>, T2: Sentinel,

fn eq(&self, other: &SSlice<T2>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T1, T2, const N: usize> PartialEq<SSlice<T2>> for [T1; N]

where T1: PartialEq<T2>, T2: Sentinel,

fn eq(&self, other: &SSlice<T2>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T1, T2> PartialEq<SSlice<T2>> for SSlice<T1>

where T1: PartialEq<T2> + Sentinel, T2: Sentinel,

fn eq(&self, other: &SSlice<T2>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, U, const N: usize> PartialEq<SSlice<U>> for InlineSSlice<T, N>

where T: PartialEq<U> + Sentinel, U: Sentinel,

fn eq(&self, other: &SSlice<U>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T1, T2> PartialOrd<[T2]> for SSlice<T1>

where T1: PartialOrd<T2> + Sentinel,

fn partial_cmp(&self, other: &[T2]) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T1, T2, const N: usize> PartialOrd<[T2; N]> for SSlice<T1>

where T1: PartialOrd<T2> + Sentinel,

fn partial_cmp(&self, other: &[T2; N]) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T, T2, A> PartialOrd<SBox<T, A>> for SSlice<T2>

where T: Sentinel, T2: Sentinel + PartialOrd<T>, A: Allocator,

fn partial_cmp(&self, other: &SBox<T, A>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T1, T2> PartialOrd<SSlice<T2>> for [T1]

where T1: PartialOrd<T2>, T2: Sentinel,

fn partial_cmp(&self, other: &SSlice<T2>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T1, T2, const N: usize> PartialOrd<SSlice<T2>> for [T1; N]

where T1: PartialOrd<T2>, T2: Sentinel,

fn partial_cmp(&self, other: &SSlice<T2>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T1, T2> PartialOrd<SSlice<T2>> for SSlice<T1>

where T1: PartialOrd<T2> + Sentinel, T2: Sentinel,

fn partial_cmp(&self, other: &SSlice<T2>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: Eq + Sentinel> Eq for SSlice<T>

impl<T: RefUnwindSafe + Sentinel> RefUnwindSafe for SSlice<T>

impl<T: Send + Sentinel> Send for SSlice<T>

impl<T: Sync + Sentinel> Sync for SSlice<T>

impl<T: Unpin + Sentinel> Unpin for SSlice<T>

impl<T: UnwindSafe + Sentinel> UnwindSafe for SSlice<T>