SliceMarshal

Namespace: System · class

Advanced or unsafe operations on Slice

Methods

AsRef

static T AsRef<T>(Slice buffer)

Reinterprets a Slice of bytes as a read-only reference to the structure of type T.

• buffer — The Slice to reinterpret.

Returns: The read-only reference to the structure of type T.

Cast

static ReadOnlySpan<TTo> Cast<TTo>(Slice buffer)

Casts a Slice to a read-only span of another primitive type.

• buffer — The source slice to convert.

Returns: The converted read-only span.

Copy

static Slice Copy(IntPtr source, int count)

Creates a new slice with a copy of an unmanaged memory buffer

• source — Pointer to unmanaged buffer
• count — Number of bytes in the buffer

Returns: Slice with a managed copy of the data

static Slice Copy(Void* source, int count)

Creates a new slice with a copy of an unmanaged memory buffer

• source — Pointer to unmanaged buffer
• count — Number of bytes in the buffer

Returns: Slice with a managed copy of the data

static Slice Copy(Byte* source, int count)

Creates a new slice with a copy of an unmanaged memory buffer

• source — Pointer to unmanaged buffer
• count — Number of bytes in the buffer

Returns: Slice with a managed copy of the data

CopyAsBytes

static Slice CopyAsBytes<T>(ReadOnlySpan<T> items)

Returns a copy of the memory content of an array of item

static Slice CopyAsBytes<T>(Span<T> items)

Returns a copy of the memory content of an array of item

static Slice CopyAsBytes<T>(ReadOnlySpan<T> items, ref byte[] buffer)

Returns a copy of the memory content of an array of item

static Slice CopyAsBytes<T>(Span<T> items, ref byte[] buffer)

Returns a copy of the memory content of an array of item

CopyTo

static Byte* CopyTo(Slice buffer, Byte* ptr, Byte* end)

Copy this slice into memory and return the advanced cursor

• buffer — Slice to copy
• ptr — Pointer where to copy this slice
• end — Pointer to the next byte after the last available position in the output buffer

Copy will fail if there is not enough space in the output buffer (ie: if it would write at or after )

static IntPtr CopyTo(Slice buffer, IntPtr destination, UIntPtr capacity)

Copy this slice into memory and return the advanced cursor

• buffer — Slice to copy
• destination — Pointer where to copy this slice
• capacity — Capacity of the output buffer

Copy will fail if there is not enough space in the output buffer

GetBytesOrCopy

static byte[] GetBytesOrCopy(Slice buffer)

Exposes the internal buffer if it has the exact same size as the slice; otherwise, returns a copy of the content

• buffer — Slice with some content

Returns: A byte array which is either the original buffer, or a copy.

Used to optimize situations where the caller needs to pass the content of the slice to a legacy API that requires a byte[] without support for spans or specifying an offset or length, and would like to avoid an extra copy, especially if the buffer is know to have the correct size.

The expected pattern is: LegacyAPI.DoSomething(SliceMarshal.GetBytesOrCopy()); // has a chance to skip an extra copy if the buffer has the correct size already

CAUTION: Slice are expected to be read-only, but exposing the internal buffer may lead to unexpected mutations! Use with caution, and make sure that any consumer of the buffer only read and never write to it!

GetReference

static byte GetReference(Slice buffer)

Returns a valid reference to the first byte in the slice

• buffer — Slice

Returns: Reference to the first byte, or where it would be if the slice is empty

GetReferenceAt

static byte GetReferenceAt(Slice buffer, int index)

Returns a valid reference to a byte at the given location in the slice

• buffer — Slice
• index — Index in the slice.

Returns: Reference to the corresponding byte

static byte GetReferenceAt(Slice buffer, Index index)

Returns a valid reference to a byte at the given location in the slice

• buffer — Slice
• index — Index in the slice.

Returns: Reference to the corresponding byte

GetReferenceToLast

static byte GetReferenceToLast(Slice buffer)

Returns a valid reference to the last byte in the slice

• buffer — Slice

Returns: Reference to the corresponding byte

IsAddressInside

static bool IsAddressInside(Slice buffer, in byte ptr)

Tests if a reference points inside the corresponding slice

• buffer — Buffer that is being tested
• ptr — Pointer that may or may not point inside buffer

Returns: true if ptr points to a byte inside the slice, or false if it is outside the slice

Read

static T Read<T>(Slice source)

Reads a structure of type T out of a Slice.

• source — A slice.

Returns: The structure retrieved from the read-only span.

ReadAt

static T ReadAt<T>(Slice source, int index)

Reads a structure of type T out of a Slice.

• source — A slice.
• index — Offset (in bytes) from the start of the slice

Returns: The structure retrieved from the read-only span.

static T ReadAt<T>(Slice source, Index index)

Reads a structure of type T out of a Slice.

• source — A slice.
• index — Offset (in bytes) in the slice

Returns: The structure retrieved from the read-only span.

TryCopyTo

static Byte* TryCopyTo(Slice buffer, Byte* ptr, Byte* end)

Try to copy this slice into memory and return the advanced cursor, if the destination is large enough

• buffer — Slice to copy
• ptr — Pointer where to copy this slice
• end — Pointer to the next byte after the last available position in the output buffer

Returns: Pointer to the advanced memory position, or null if the destination buffer was too small

static bool TryCopyTo(Slice buffer, IntPtr destination, UIntPtr capacity)

Copy this slice into memory and return the advanced cursor

• buffer — Slice to copy
• destination — Pointer where to copy this slice
• capacity — Capacity of the output buffer

TryGetBytes

static bool TryGetBytes(Slice buffer, out byte[] bytes)

Exposes the internal buffer if it has the exact same size as the slice

• buffer — Slice with some content
• bytes — Receives the internal buffer, or null if the buffer is larger than the slice

Returns: true> if the buffer is complete and is exposed in bytes, or false if the slice only cover a part of the buffer.

Used to optimize the case when the caller needs to pass the content of the slice to a legacy API that requires a byte[] without support for spans or specifying an offset or length, and would like to avoid an extra copy, especially if the buffer is know to have the correct size.

The expected pattern is: if (SliceMarshal.TryGetBytes(slice, out var bytes)) { // no copy required LegacyAPI.DoSomething(bytes); } else { // need to allocate and copy!!! LegacyAPI.DoSomething(slice.ToArray()); }

CAUTION: Slice are expected to be read-only, but exposing the internal buffer may lead to unexpected mutations! Use with caution, and make sure that any consumer of the buffer only read and never write to it!

TryGetOffset

static bool TryGetOffset(ref byte ptr, Slice buffer, out int offset)

Returns the offset of an unmanaged pointer inside the slice

• ptr — Unamanged pointer
• buffer — Slice to compare
• offset — If the pointer is inside the slice, receives the offset from the start of the slice

Returns: true if the pointer is contained inside the slice (or after the end).

TryGetReferenceAt

static byte TryGetReferenceAt(Slice buffer, int index, out bool valid)

Returns a reference to a byte at the given location in the slice, or null if it is outside

• buffer — Slice
• index — Index in the slice.
• valid — Receives true if index is inside the slice; otherwise, false.

Returns: Reference to the corresponding byte, or null if index is outside the bounds of the slice.

static byte TryGetReferenceAt(Slice buffer, Index index, out bool valid)

Returns a reference to a byte at the given location in the slice, or null if it is outside

• buffer — Slice
• index — Index in the slice.
• valid — Receives true if index is inside the slice; otherwise, false.

Returns: Reference to the corresponding byte, or null if index is outside the bounds of the slice.

TryGetSlice

static bool TryGetSlice(ReadOnlyMemory<byte> buffer, out Slice slice)

Try to convert a ReadOnlyMemory into a Slice if it is backed by a managed byte array.

• buffer — Buffer that maps a region of memory
• slice — If the method returns true, a slice that maps the same region of managed memory.

Returns: True if the memory was backed by a managed array; otherwise, false.

TryRead

static bool TryRead<T>(Slice source, out T value)

Tries to read a structure of type T from a Slice.

• source — A slice.
• value — When the method returns, an instance of T.

Returns: true if the method succeeds in retrieving an instance of the structure; otherwise, false.