Trait SliceLike

pub trait SliceLike {
    type Element: Sized;

    // Required methods
    fn as_element_slice(&self) -> &[Self::Element];
    unsafe fn as_element_slice_mut(&mut self) -> &mut [Self::Element];
    unsafe fn from_element_slice(slice: &[Self::Element]) -> &Self;
    unsafe fn from_element_slice_mut(slice: &mut [Self::Element]) -> &mut Self;
}

Trait for dynamically sized types that wrap some slice type.

Some DSTs, such as str, are mostly a wrapper for a basic slice type, often providing some abstraction to ensure the data isn’t used in an unsafe manner. Implementing this trait for such DSTs exposes conversions to and from the slice type, allowing us to use these types with allocation operations.

Required Associated Types

type Element: Sized

Slice element type.

Required Methods

fn as_element_slice(&self) -> &[Self::Element]

Returns a slice of Self::Element elements containing this slice’s data.

Examples

use scratchpad::SliceLike;

let message = "foo";
let bytes = message.as_element_slice();
assert_eq!(bytes, &[b'f', b'o', b'o']);

unsafe fn as_element_slice_mut(&mut self) -> &mut [Self::Element]

Returns a mutable slice of Self::Element elements containing this slice’s data.

Safety

Slices of this type may perform validity checks against the internal data (e.g. str slices must contain valid UTF-8 data). This function allows for modification of the slice contents outside such checks. Improper use of this function can result in undefined behavior.

Examples

use scratchpad::SliceLike;

let mut message = String::from("foo");

unsafe {
    let bytes = message.as_mut_str().as_element_slice_mut();
    bytes[0] = b'b';
    bytes[1] = b'a';
    bytes[2] = b'r';
}

assert_eq!(message, "bar");

unsafe fn from_element_slice(slice: &[Self::Element]) -> &Self

Reinterprets a slice of Self::Inner elements as a slice of this type.

Safety

Slices of this type may perform validity checks against the internal data (e.g. str slices must contain valid UTF-8 data). This function bypasses any such checks, potentially returning data that is invalid. Improper use of this function can result in undefined behavior.

Examples

use scratchpad::SliceLike;

let bytes = [b'f', b'o', b'o'];
let message = unsafe {
    <str as SliceLike>::from_element_slice(&bytes[..])
};
assert_eq!(message, "foo");

unsafe fn from_element_slice_mut(slice: &mut [Self::Element]) -> &mut Self

Reinterprets a mutable slice of Self::Inner elements as a mutable slice of this type.

Safety

Slices of this type may perform validity checks against the internal data (e.g. str slices must contain valid UTF-8 data). This function bypasses any such checks, potentially returning data that is invalid. Improper use of this function can result in undefined behavior.

Examples

use scratchpad::SliceLike;

let mut bytes = [b'f', b'o', b'o'];

unsafe {
    let message = <str as SliceLike>::from_element_slice_mut(
        &mut bytes[..],
    );
    message.as_bytes_mut()[0] = b'b';
    message.as_bytes_mut()[1] = b'a';
    message.as_bytes_mut()[2] = b'r';
}

assert_eq!(bytes, [b'b', b'a', b'r']);

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl SliceLike for str

type Element = u8

fn as_element_slice(&self) -> &[Self::Element]

unsafe fn as_element_slice_mut(&mut self) -> &mut [Self::Element]

unsafe fn from_element_slice(slice: &[Self::Element]) -> &Self

unsafe fn from_element_slice_mut(slice: &mut [Self::Element]) -> &mut Self

impl SliceLike for CStr

type Element = u8

Slice element type.

u8 is used as the element type instead of c_char, as the CStr methods that handle conversions to and from slices work with u8 slices (c_char is only used when working with raw pointers).

fn as_element_slice(&self) -> &[Self::Element]

Returns a slice of Self::Element elements containing this slice’s data.

This uses CStr::to_bytes_with_nul() to return the entire CStr contents, including the nul terminator.

Examples

use scratchpad::SliceLike;
use std::ffi::CString;

let message = CString::new("foo").unwrap();
let message_c_str = message.as_c_str();
let bytes = message_c_str.as_element_slice();
assert_eq!(bytes, &[b'f', b'o', b'o', b'\0']);

unsafe fn as_element_slice_mut(&mut self) -> &mut [Self::Element]

Returns a mutable slice of Self::Element elements containing this slice’s data.

This is roughly equivalent to CStr::to_bytes_with_nul(), returning a mutable slice instead of an immutable slice.

Safety

This function potentially allows for modification of the CStr contents outside of any validity checks, specifically checks for a nul terminator and no internal nul bytes. Improper use of this function can result in undefined behavior.

Examples

use scratchpad::SliceLike;
use std::ffi::{CStr, CString};

let mut message = CString::new("foo").unwrap().into_boxed_c_str();
let message_c_str = &mut *message;

unsafe {
    let bytes = message_c_str.as_element_slice_mut();
    bytes[0] = b'b';
    bytes[1] = b'a';
    bytes[2] = b'r';
}

assert_eq!(
    message_c_str,
    CStr::from_bytes_with_nul(b"bar\0").unwrap(),
);

unsafe fn from_element_slice(slice: &[Self::Element]) -> &Self

Reinterprets a slice of Self::Inner elements as a slice of this type.

This uses CStr::from_bytes_with_nul_unchecked() to create a CStr from a nul-terminated byte slice.

Safety

No safety checking is performed on the provided byte slice. It must be nul-terminated and not contain any interior nul bytes.

Examples

use scratchpad::SliceLike;
use std::ffi::CStr;

let bytes = [b'f', b'o', b'o', b'\0'];
let message = unsafe {
    <CStr as SliceLike>::from_element_slice(&bytes[..])
};
assert_eq!(message, CStr::from_bytes_with_nul(b"foo\0").unwrap());

unsafe fn from_element_slice_mut(slice: &mut [Self::Element]) -> &mut Self

Reinterprets a mutable slice of Self::Inner elements as a mutable slice of this type.

This is roughly equivalent to CStr::from_bytes_with_nul_unchecked(), returning a mutable CStr reference instead of an immutable reference.

Safety

No safety checking is performed on the provided byte slice. It must be nul-terminated and not contain any interior nul bytes.

Examples

use scratchpad::SliceLike;
use std::ffi::CStr;

let mut bytes = [b'f', b'o', b'o', b'\0'];
let message = unsafe {
    <CStr as SliceLike>::from_element_slice_mut(&mut bytes[..])
};
assert_eq!(message, CStr::from_bytes_with_nul(b"foo\0").unwrap());

impl<T> SliceLike for [T]

type Element = T

fn as_element_slice(&self) -> &[Self::Element]

unsafe fn as_element_slice_mut(&mut self) -> &mut [Self::Element]

unsafe fn from_element_slice(slice: &[Self::Element]) -> &Self

unsafe fn from_element_slice_mut(slice: &mut [Self::Element]) -> &mut Self

Implementors