impl<'a, T> Split<&'a T>

fn via_immutable(self: Self) -> (&'a T, &'a [<T as >::Elem])
where
    T: Immutable

Produces the split parts of self, using Immutable to ensure that it is sound to have concurrent references to both parts.

Examples

use zerocopy::{SplitAt, FromBytes};
# use zerocopy_derive::*;

#[derive(SplitAt, FromBytes, KnownLayout, Immutable)]
#[repr(C)]
struct Packet {
    length: u8,
    body: [u8],
}

// These bytes encode a `Packet`.
let bytes = &[4, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let packet = Packet::ref_from_bytes(bytes).unwrap();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 5, 6, 7, 8, 9]);

// Attempt to split `packet` at `length`.
let split = packet.split_at(packet.length as usize).unwrap();

// Use the `Immutable` bound on `Packet` to prove that it's okay to
// return concurrent references to `packet` and `rest`.
let (packet, rest) = split.via_immutable();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4]);
assert_eq!(rest, [5, 6, 7, 8, 9]);

fn via_into_bytes(self: Self) -> (&'a T, &'a [<T as >::Elem])
where
    T: IntoBytes

Produces the split parts of self, using IntoBytes to ensure that it is sound to have concurrent references to both parts.

Examples

use zerocopy::{SplitAt, FromBytes};
# use zerocopy_derive::*;

#[derive(SplitAt, FromBytes, KnownLayout, Immutable, IntoBytes)]
#[repr(C)]
struct Packet<B: ?Sized> {
    length: u8,
    body: B,
}

// These bytes encode a `Packet`.
let bytes = &[4, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let packet = Packet::<[u8]>::ref_from_bytes(bytes).unwrap();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 5, 6, 7, 8, 9]);

// Attempt to split `packet` at `length`.
let split = packet.split_at(packet.length as usize).unwrap();

// Use the `IntoBytes` bound on `Packet` to prove that it's okay to
// return concurrent references to `packet` and `rest`.
let (packet, rest) = split.via_into_bytes();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4]);
assert_eq!(rest, [5, 6, 7, 8, 9]);

fn via_unaligned(self: Self) -> (&'a T, &'a [<T as >::Elem])
where
    T: Unaligned

Produces the split parts of self, using Unaligned to ensure that it is sound to have concurrent references to both parts.

Examples

use zerocopy::{SplitAt, FromBytes};
# use zerocopy_derive::*;

#[derive(SplitAt, FromBytes, KnownLayout, Immutable, Unaligned)]
#[repr(C)]
struct Packet {
    length: u8,
    body: [u8],
}

// These bytes encode a `Packet`.
let bytes = &[4, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let packet = Packet::ref_from_bytes(bytes).unwrap();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 5, 6, 7, 8, 9]);

// Attempt to split `packet` at `length`.
let split = packet.split_at(packet.length as usize).unwrap();

// Use the `Unaligned` bound on `Packet` to prove that it's okay to
// return concurrent references to `packet` and `rest`.
let (packet, rest) = split.via_unaligned();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4]);
assert_eq!(rest, [5, 6, 7, 8, 9]);

fn via_runtime_check(self: Self) -> Result<(&'a T, &'a [<T as >::Elem]), Self>

Produces the split parts of self, using a dynamic check to ensure that it is sound to have concurrent references to both parts. You should prefer using Self::via_immutable, Self::via_into_bytes, or Self::via_unaligned, which have no runtime cost.

Note that this check is overly conservative if T is Immutable; for some types, this check will reject some splits which Self::via_immutable will accept.

Examples

use zerocopy::{SplitAt, FromBytes, IntoBytes, network_endian::U16};
# use zerocopy_derive::*;

#[derive(SplitAt, FromBytes, KnownLayout, Immutable, Debug)]
#[repr(C, align(2))]
struct Packet {
    length: U16,
    body: [u8],
}

// These bytes encode a `Packet`.
let bytes = [
    4u16.to_be(),
    1u16.to_be(),
    2u16.to_be(),
    3u16.to_be(),
    4u16.to_be()
];

let packet = Packet::ref_from_bytes(bytes.as_bytes()).unwrap();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [0, 1, 0, 2, 0, 3, 0, 4]);

// Attempt to split `packet` at `length`.
let split = packet.split_at(packet.length.into()).unwrap();

// Use a dynamic check to prove that it's okay to return concurrent
// references to `packet` and `rest`.
let (packet, rest) = split.via_runtime_check().unwrap();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [0, 1, 0, 2]);
assert_eq!(rest, [0, 3, 0, 4]);

// Attempt to split `packet` at `length - 1`.
let idx = packet.length.get() - 1;
let split = packet.split_at(idx as usize).unwrap();

// Attempt (and fail) to use a dynamic check to prove that it's okay
// to return concurrent references to `packet` and `rest`. Note that
// this is a case of `via_runtime_check` being overly conservative.
// Although the left and right parts indeed overlap, the `Immutable`
// bound ensures that concurrently referencing these overlapping
// parts is sound.
assert!(split.via_runtime_check().is_err());

unsafe fn via_unchecked(self: Self) -> (&'a T, &'a [<T as >::Elem])

Unsafely produces the split parts of self.

Safety

If T permits interior mutation, the trailing padding bytes of the left portion must not overlap the right portion. For some dynamically sized types, the padding that appears after the trailing slice field is a dynamic function of the trailing slice length. Thus, for some types, this condition is dependent on the length of the left portion.

impl<'a, T> Split<&'a mut T>

fn via_into_bytes(self: Self) -> (&'a mut T, &'a mut [<T as >::Elem])
where
    T: IntoBytes

Produces the split parts of self, using IntoBytes to ensure that it is sound to have concurrent references to both parts.

Examples

use zerocopy::{SplitAt, FromBytes};
# use zerocopy_derive::*;

#[derive(SplitAt, FromBytes, KnownLayout, IntoBytes)]
#[repr(C)]
struct Packet<B: ?Sized> {
    length: u8,
    body: B,
}

// These bytes encode a `Packet`.
let mut bytes = &mut [4, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let packet = Packet::<[u8]>::mut_from_bytes(bytes).unwrap();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 5, 6, 7, 8, 9]);

{
    // Attempt to split `packet` at `length`.
    let split = packet.split_at_mut(packet.length as usize).unwrap();

    // Use the `IntoBytes` bound on `Packet` to prove that it's okay to
    // return concurrent references to `packet` and `rest`.
    let (packet, rest) = split.via_into_bytes();

    assert_eq!(packet.length, 4);
    assert_eq!(packet.body, [1, 2, 3, 4]);
    assert_eq!(rest, [5, 6, 7, 8, 9]);

    rest.fill(0);
}

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 0, 0, 0, 0, 0]);

fn via_unaligned(self: Self) -> (&'a mut T, &'a mut [<T as >::Elem])
where
    T: Unaligned

Produces the split parts of self, using Unaligned to ensure that it is sound to have concurrent references to both parts.

Examples

use zerocopy::{SplitAt, FromBytes};
# use zerocopy_derive::*;

#[derive(SplitAt, FromBytes, KnownLayout, IntoBytes, Unaligned)]
#[repr(C)]
struct Packet<B: ?Sized> {
    length: u8,
    body: B,
}

// These bytes encode a `Packet`.
let mut bytes = &mut [4, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let packet = Packet::<[u8]>::mut_from_bytes(bytes).unwrap();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 5, 6, 7, 8, 9]);

{
    // Attempt to split `packet` at `length`.
    let split = packet.split_at_mut(packet.length as usize).unwrap();

    // Use the `Unaligned` bound on `Packet` to prove that it's okay to
    // return concurrent references to `packet` and `rest`.
    let (packet, rest) = split.via_unaligned();

    assert_eq!(packet.length, 4);
    assert_eq!(packet.body, [1, 2, 3, 4]);
    assert_eq!(rest, [5, 6, 7, 8, 9]);

    rest.fill(0);
}

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 0, 0, 0, 0, 0]);

fn via_runtime_check(self: Self) -> Result<(&'a mut T, &'a mut [<T as >::Elem]), Self>

Produces the split parts of self, using a dynamic check to ensure that it is sound to have concurrent references to both parts. You should prefer using Self::via_into_bytes or Self::via_unaligned, which have no runtime cost.

Examples

use zerocopy::{SplitAt, FromBytes};
# use zerocopy_derive::*;

#[derive(SplitAt, FromBytes, KnownLayout, IntoBytes, Debug)]
#[repr(C)]
struct Packet<B: ?Sized> {
    length: u8,
    body: B,
}

// These bytes encode a `Packet`.
let mut bytes = &mut [4, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let packet = Packet::<[u8]>::mut_from_bytes(bytes).unwrap();

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 5, 6, 7, 8, 9]);

{
    // Attempt to split `packet` at `length`.
    let split = packet.split_at_mut(packet.length as usize).unwrap();

    // Use a dynamic check to prove that it's okay to return concurrent
    // references to `packet` and `rest`.
    let (packet, rest) = split.via_runtime_check().unwrap();

    assert_eq!(packet.length, 4);
    assert_eq!(packet.body, [1, 2, 3, 4]);
    assert_eq!(rest, [5, 6, 7, 8, 9]);

    rest.fill(0);
}

assert_eq!(packet.length, 4);
assert_eq!(packet.body, [1, 2, 3, 4, 0, 0, 0, 0, 0]);

unsafe fn via_unchecked(self: Self) -> (&'a mut T, &'a mut [<T as >::Elem])

Unsafely produces the split parts of self.

Safety

The trailing padding bytes of the left portion must not overlap the right portion. For some dynamically sized types, the padding that appears after the trailing slice field is a dynamic function of the trailing slice length. Thus, for some types, this condition is dependent on the length of the left portion.

impl<T> Any for Split<T>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Split<T>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for Split<T>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> Freeze for Split<T>

impl<T> From for Split<T>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> RefUnwindSafe for Split<T>

impl<T> Send for Split<T>

impl<T> Sync for Split<T>

impl<T> Unpin for Split<T>

impl<T> UnsafeUnpin for Split<T>

impl<T> UnwindSafe for Split<T>

impl<T, U> Into for Split<T>

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for Split<T>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for Split<T>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>

impl<T: $crate::fmt::Debug> Debug for Split<T>

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