class Slice

Declaration

template <class T>
class Slice { /* full declaration omitted */ };

Description

A dynamically-sized const view into a contiguous sequence of objects of type `const T`. Contiguous here means that elements are laid out so that every element is the same distance from its neighbors, where there are [`sus::mem::size_of <T >()`]($sus::mem::size_of) many bytes between the start of each element. Slices are a view into a block of memory represented as a pointer and a length.

Declared at: sus/collections/slice.h:70

Templates

T

Method Overview

  • public constexpr Slice<T>(::sus::marker::EmptyMarker)
  • public constexpr Slice<T>()
  • public void drop_iterator_invalidation_tracking(::sus::marker::UnsafeFnMarker)
  • public static constexpr Slice<T> from_raw_collection(::sus::marker::UnsafeFnMarker, ::sus::iter::IterRefCounter refs, const T * data, sus::num::usize len) noexcept
  • public static constexpr Slice<T> from_raw_parts(::sus::marker::UnsafeFnMarker, const T * data, sus::num::usize len) noexcept

Methods

constexpr Slice<T>(::sus::marker::EmptyMarker)

Description

Constructs an empty `Slice`. This constructor is implicit so that using the [`EmptyMarker`]( $sus::marker::EmptyMarker) allows the caller to avoid spelling out the full `Slice` type. #[doc.overloads=empty]

Declared at: sus/collections/slice.h:85

Parameters

::sus::marker::EmptyMarker 

constexpr Slice<T>()

Description

Constructs an empty Slice, which has no elements.

Declared at: sus/collections/slice.h:88

void drop_iterator_invalidation_tracking(
    ::sus::marker::UnsafeFnMarker)

Description

Stops tracking iterator invalidation. # Safety If the Slice points into a collection and that collection is invalidated, it will no longer be caught. The caller must provide conditions that can ensure the `Slice`'s pointer into the collection will remain valid. Iterator invalidation tracking also tracks the stability of the collection object itself, not just its contents, which can be overly strict. This function can be used when the collection's contents will remain valid, but the collection itself may be moved, which would invalidate the tracking and be treated as invalidating the iterator. There is no way to restore tracking.

Declared at: sus/collections/slice.h:247

Parameters

::sus::marker::UnsafeFnMarker 

static constexpr Slice<T> from_raw_collection(
    ::sus::marker::UnsafeFnMarker,
    ::sus::iter::IterRefCounter refs,
    const T* data,
    sus::num::usize len) noexcept

Description

Constructs a slice from its raw parts with iterator invalidation tracking. Iterators produced from this slice will interact with the collection to allow it to know when they are being invalidated by the collection. For building a Slice from primitive pointer, use `from_raw_parts()`. # Safety The following must be upheld or Undefined Behaviour may result: * The `len` must be no more than the number of elements in the allocation at and after the position of `data`. * The pointer `data` must be a valid pointer to an allocation, not a dangling pointer, at any point during the Slice's lifetime. This must be true even if `len` is 0. * The `refs` will be `sus::iter::IterRefCounter::empty_for_view()` unless the `Slice` is being constructed from a context that owns an IterRefCounter and wants to be able to observe when it invalidates the `Slice` by tracking its lifetime. In some other langages such as Rust, the slice may hold an invalid pointer when the length is zero. But `Slice` must not hold a dangling pointer. Otherwise addition on the dangling pointer may happen in Slice methods, which is Undefined Behaviour in C++. To support dangling pointers, those methods would need `length == 0` branches. Care must be applied when converting slices between languages as a result.

Declared at: sus/collections/slice.h:150

Parameters

::sus::marker::UnsafeFnMarker
::sus::iter::IterRefCounter refs
const T* data
sus::num::usize len

static constexpr Slice<T> from_raw_parts(
    ::sus::marker::UnsafeFnMarker,
    const T* data,
    sus::num::usize len) noexcept

Description

Constructs a slice from its raw parts. For building a Slice from a collection, use `from_raw_collection()` in order to participate in iterator invalidation tracking. # Safety The following must be upheld or Undefined Behaviour may result: * The `len` must be no more than the number of elements in the allocation at and after the position of `data`. * The pointer `data` must be a valid pointer to an allocation, not a dangling pointer, at any point during the Slice's lifetime. This must be true even if `len` is 0. * The `refs` will be `sus::iter::IterRefCounter::empty_for_view()` unless the `Slice` is being constructed from a context that owns an IterRefCounter and wants to be able to observe when it invalidates the `Slice` by tracking its lifetime. In some other langages such as Rust, the slice may hold an invalid pointer when the length is zero. But `Slice` must not hold a dangling pointer. Otherwise addition on the dangling pointer may happen in Slice methods, which is Undefined Behaviour in C++. To support dangling pointers, those methods would need `length == 0` branches. Care must be applied when converting slices between languages as a result.

Declared at: sus/collections/slice.h:115

Parameters

::sus::marker::UnsafeFnMarker
const T* data
sus::num::usize len