Class UnsafeUtilities

Namespace

Stride.Core.UnsafeExtensions

Assembly

Stride.Core.dll

Provides a set of methods to supplement or replace Unsafe and MemoryMarshal, mainly for working with structs and unmanaged types.

public static class UnsafeUtilities

Inheritance

object

UnsafeUtilities

Methods

AsBytes<T>(ReadOnlySpan<T>)

Casts a ReadOnlySpan<T> of one primitive type, T, to a ReadOnlySpan<Byte>.

public static ReadOnlySpan<byte> AsBytes<T>(this ReadOnlySpan<T> span) where T : struct

Parameters

span ReadOnlySpan<T>

The source slice to convert.

Returns

ReadOnlySpan<byte>

A read-only span of type byte.

Type Parameters

T

The type of items in the read-only span.

Exceptions

ArgumentException

T contains managed object references.

OverflowException

The Length property of the new ReadOnlySpan<T> would exceed Int32.MaxValue

AsBytes<T>(Span<T>)

Casts a Span<T> of one primitive type, T, to a Span<Byte>.

public static Span<byte> AsBytes<T>(this Span<T> span) where T : struct

Parameters

span Span<T>

The source slice to convert.

Returns

Span<byte>

A span of type byte.

Type Parameters

T

The type of items in the span.

Exceptions

ArgumentException

T contains managed object references.

OverflowException

The Length property of the new ReadOnlySpan<T> would exceed Int32.MaxValue

AsPointer<T>(ref T)

public static T* AsPointer<T>(this ref T value) where T : unmanaged

Parameters

value T

Returns

T*

Type Parameters

T

AsReadOnlySpan<T>(T[]?)

Creates a new read-only span over the target array.

public static ReadOnlySpan<T> AsReadOnlySpan<T>(this T[]? array)

Parameters

array T[]

The array.

Returns

ReadOnlySpan<T>

A read-only span over the provided array.

Type Parameters

T

AsReadOnlySpan<TFrom, TTo>(scoped ref TFrom)

Reinterprets a regular managed object as a read-only span of elements of another type. This can be useful if a managed object represents a "fixed array".

public static ReadOnlySpan<TTo> AsReadOnlySpan<TFrom, TTo>(this scoped ref TFrom reference) where TFrom : unmanaged where TTo : unmanaged

Parameters

reference TFrom

A reference to data.

Returns

ReadOnlySpan<TTo>

A read-only span representing the specified reference as elements of type TTo.

Type Parameters

TFrom

TTo

Remarks

This method should be used with caution. Even though the ref is annotated as scoped, it will be stored into the returned span, and the lifetime of the returned span will not be validated for safety, even by span-aware languages.

AsReadOnlySpan<TFrom, TTo>(scoped ref TFrom, int)

Reinterprets a regular managed object as an array of elements of another type and returns a read-only span over a portion of that array. This can be useful if a managed object represents a "fixed array". This is dangerous because the elementCount is not checked.

public static ReadOnlySpan<TTo> AsReadOnlySpan<TFrom, TTo>(this scoped ref TFrom reference, int elementCount) where TFrom : unmanaged where TTo : unmanaged

Parameters

reference TFrom

A reference to data.

elementCount int

The number of TTo elements the memory contains.

Returns

ReadOnlySpan<TTo>

A read-only span representing the specified reference as elementCount elements of type TTo.

Type Parameters

TFrom

TTo

Remarks

This method should be used with caution. It is dangerous because the elementCount argument is not checked. Even though the ref is annotated as scoped, it will be stored into the returned span, and the lifetime of the returned span will not be validated for safety, even by span-aware languages.

AsReadOnlySpan<TFrom, TTo>(TFrom[]?)

Reinterprets a regular array as a read-only span of elements of another type. This can be useful if the types are the same size and interchangeable.

public static ReadOnlySpan<TTo> AsReadOnlySpan<TFrom, TTo>(this TFrom[]? array) where TFrom : unmanaged where TTo : unmanaged

Parameters

array TFrom[]

An array of data.

Returns

ReadOnlySpan<TTo>

A read-only span representing the data of array reinterpreted as elements of type TTo. If the array is null, returns an empty span.

Type Parameters

TFrom

TTo

AsReadonlyPointer<T>(ref readonly T)

public static T* AsReadonlyPointer<T>(ref readonly T value) where T : unmanaged

Parameters

value T

Returns

T*

Type Parameters

T

AsReadonly<TFrom, TTo>(ref readonly TFrom)

Reinterprets the given managed pointer as a new managed pointer to a value of type TTo.

public static ref readonly TTo AsReadonly<TFrom, TTo>(ref readonly TFrom source)

Parameters

source TFrom

The managed pointer to reinterpret.

Returns

TTo

A managed pointer to a value of type TTo.

Type Parameters

TFrom

The type of managed pointer to reinterpret.

TTo

The desired type of the managed pointer.

AsRef<T>(nint)

Reinterprets the given native integer as a reference.

public static ref T AsRef<T>(nint source)

Parameters

source nint

The native integer to reinterpret.

Returns

T

A reference to a value of type T.

Type Parameters

T

The type of the reference.

AsRef<T>(nuint)

Reinterprets the given native unsigned integer as a reference.

public static ref T AsRef<T>(nuint source)

Parameters

source nuint

The native unsigned integer to reinterpret.

Returns

T

A reference to a value of type T.

Type Parameters

T

The type of the reference.

AsRef<T>(void*)

Converts an unmanaged pointer into a managed pointer to a value of type T.

public static ref T AsRef<T>(void* source)

Parameters

source void*

The unmanaged pointer to convert.

Returns

T

A managed pointer to a value of type T.

Type Parameters

T

The elemental type of the managed pointer.

AsRef<T>(scoped ref readonly T)

Reinterprets the given read-only reference as a mutable reference.

public static ref T AsRef<T>(scoped ref readonly T source)

Parameters

source T

The read-only reference to reinterpret.

Returns

T

A mutable reference to a value of type T.

Type Parameters

T

The underlying type of the reference.

AsRef<TFrom, TTo>(scoped ref readonly TFrom)

Reinterprets the given read-only reference as a mutable reference.

public static ref TTo AsRef<TFrom, TTo>(scoped ref readonly TFrom source)

Parameters

source TFrom

The read-only reference to reinterpret.

Returns

TTo

A mutable reference to a value of type T.

Type Parameters

TFrom

TTo

AsSpan<T>(ReadOnlySpan<T>)

Reinterprets the read-only span as a writeable span.

public static Span<T> AsSpan<T>(this ReadOnlySpan<T> span)

Parameters

span ReadOnlySpan<T>

The read-only span to reinterpret.

Returns

Span<T>

A writeable span that points to the same items as span.

Type Parameters

T

The type of items in span.

AsSpan<TFrom, TTo>(scoped ref TFrom)

Reinterprets a regular managed object as a span of elements of another type. This can be useful if a managed object represents a "fixed array".

public static Span<TTo> AsSpan<TFrom, TTo>(this scoped ref TFrom reference) where TFrom : unmanaged where TTo : unmanaged

Parameters

reference TFrom

A reference to data.

Returns

Span<TTo>

A span representing the specified reference as elements of type TTo.

Type Parameters

TFrom

TTo

Remarks

This method should be used with caution. Even though the ref is annotated as scoped, it will be stored into the returned span, and the lifetime of the returned span will not be validated for safety, even by span-aware languages.

AsSpan<TFrom, TTo>(scoped ref TFrom, int)

Reinterprets a regular managed object as an array of elements of another type and returns a span over a portion of that array. This can be useful if a managed object represents a "fixed array". This is dangerous because the elementCount is not checked.

public static Span<TTo> AsSpan<TFrom, TTo>(this scoped ref TFrom reference, int elementCount) where TFrom : unmanaged where TTo : unmanaged

Parameters

reference TFrom

A reference to data.

elementCount int

The number of TTo elements the memory contains.

Returns

Span<TTo>

A span representing the specified reference as elementCount elements of type TTo.

Type Parameters

TFrom

TTo

Remarks

This method should be used with caution. It is dangerous because the elementCount argument is not checked. Even though the ref is annotated as scoped, it will be stored into the returned span, and the lifetime of the returned span will not be validated for safety, even by span-aware languages.

AsSpan<TFrom, TTo>(TFrom[]?)

Reinterprets a regular array as a span of elements of another type. This can be useful if the types are the same size and interchangeable.

public static Span<TTo> AsSpan<TFrom, TTo>(this TFrom[]? array) where TFrom : unmanaged where TTo : unmanaged

Parameters

array TFrom[]

An array of data.

Returns

Span<TTo>

A span representing the data of array reinterpreted as elements of type TTo. If the array is null, returns an empty span.

Type Parameters

TFrom

TTo

As<T>(object?)

Casts the given object to the specified type.

public static T? As<T>(this object? o) where T : class?

Parameters

o object

The object to cast.

Returns

T

The original object, cast to the given type.

Type Parameters

T

The type which the object will be cast to.

As<TFrom, TTo>(ReadOnlySpan<TFrom>)

Reinterprets the given managed pointer as a new managed pointer to a value of type TTo.

public static ReadOnlySpan<TTo> As<TFrom, TTo>(this ReadOnlySpan<TFrom> span) where TFrom : unmanaged where TTo : unmanaged

Parameters

span ReadOnlySpan<TFrom>

The span to reinterpret.

Returns

ReadOnlySpan<TTo>

A managed pointer to a value of type TTo.

Type Parameters

TFrom

The type of managed pointer to reinterpret.

TTo

The desired type of the managed pointer.

As<TFrom, TTo>(Span<TFrom>)

Reinterprets the given managed pointer as a new managed pointer to a value of type TTo.

public static Span<TTo> As<TFrom, TTo>(this Span<TFrom> span) where TFrom : unmanaged where TTo : unmanaged

Parameters

span Span<TFrom>

The span to reinterpret.

Returns

Span<TTo>

A managed pointer to a value of type TTo.

Type Parameters

TFrom

The type of managed pointer to reinterpret.

TTo

The desired type of the managed pointer.

As<TFrom, TTo>(ref TFrom)

Reinterprets the given managed pointer as a new managed pointer to a value of type TTo.

public static ref TTo As<TFrom, TTo>(this ref TFrom source) where TFrom : unmanaged where TTo : unmanaged

Parameters

source TFrom

The managed pointer to reinterpret.

Returns

TTo

A managed pointer to a value of type TTo.

Type Parameters

TFrom

The type of managed pointer to reinterpret.

TTo

The desired type of the managed pointer.

BitCast<TFrom, TTo>(TFrom)

Reinterprets the given value of type TFrom as a value of type TTo.

public static TTo BitCast<TFrom, TTo>(this TFrom source) where TFrom : struct where TTo : struct

Parameters

source TFrom

Returns

TTo

A value of type TTo.

Type Parameters

TFrom

TTo

Exceptions

NotSupportedException

The size of TFrom and TTo are not the same.

Cast<TFrom, TTo>(ReadOnlySpan<TFrom>)

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

public static ReadOnlySpan<TTo> Cast<TFrom, TTo>(this ReadOnlySpan<TFrom> span) where TFrom : struct where TTo : struct

Parameters

span ReadOnlySpan<TFrom>

The source slice to convert.

Returns

ReadOnlySpan<TTo>

The converted read-only span.

Type Parameters

TFrom

The type of the source span.

TTo

The type of the target span.

Exceptions

ArgumentException

TFrom or TTo contains managed object references.

OverflowException

The Length property of the new ReadOnlySpan<T> would exceed MaxValue.

Cast<TFrom, TTo>(Span<TFrom>)

Casts a span of one primitive type to a span of another primitive type.

public static Span<TTo> Cast<TFrom, TTo>(this Span<TFrom> span) where TFrom : struct where TTo : struct

Parameters

span Span<TFrom>

The source slice to convert.

Returns

Span<TTo>

The converted span.

Type Parameters

TFrom

The type of the source span.

TTo

The type of the target span.

Exceptions

ArgumentException

TFrom or TTo contains managed object references.

OverflowException

The Length property of the new ReadOnlySpan<T> would exceed MaxValue.

CopyBlockUnaligned<TDestination, TSource>(ref TDestination, ref readonly TSource, uint)

Copies bytes from the source address to the destination address without assuming architecture dependent alignment of the addresses.

public static void CopyBlockUnaligned<TDestination, TSource>(ref TDestination destination, ref readonly TSource source, uint byteCount)

Parameters

destination TDestination

The managed pointer corresponding to the destination address to copy to.

source TSource

The managed pointer corresponding to the source address to copy from.

byteCount uint

The number of bytes to copy.

Type Parameters

TDestination

TSource

CopyBlock<TDestination, TSource>(ref TDestination, ref readonly TSource, uint)

Copies bytes from the source address to the destination address.

public static void CopyBlock<TDestination, TSource>(ref TDestination destination, ref readonly TSource source, uint byteCount)

Parameters

destination TDestination

The managed pointer corresponding to the destination address to copy to.

source TSource

The managed pointer corresponding to the source address to copy from.

byteCount uint

The number of bytes to copy.

Type Parameters

TDestination

TSource

CreateReadOnlySpan<T>(scoped ref readonly T, int)

Creates a new read-only span over a portion of a regular managed object.

public static ReadOnlySpan<T> CreateReadOnlySpan<T>(scoped ref readonly T reference, int length)

Parameters

reference T

A reference to data.

length int

The number of T elements that reference contains.

Returns

ReadOnlySpan<T>

A read-only span.

Type Parameters

T

The type of the data items.

CreateSpan<T>(scoped ref T, int)

Creates a new span over a portion of a regular managed object.

public static Span<T> CreateSpan<T>(scoped ref T reference, int length)

Parameters

reference T

A reference to data.

length int

The number of T elements that reference contains.

Returns

Span<T>

A span.

Type Parameters

T

The type of the data items.

GetPointer<T>(ReadOnlySpan<T>)

Returns a pointer to the element of the span at index zero.

public static T* GetPointer<T>(this ReadOnlySpan<T> span) where T : unmanaged

Parameters

span ReadOnlySpan<T>

The span from which the pointer is retrieved.

Returns

T*

A pointer to the item at index zero of span.

Type Parameters

T

The type of items in span.

GetPointer<T>(Span<T>)

Returns a pointer to the element of the span at index zero.

public static T* GetPointer<T>(this Span<T> span) where T : unmanaged

Parameters

span Span<T>

The span from which the pointer is retrieved.

Returns

T*

A pointer to the item at index zero of span.

Type Parameters

T

The type of items in span.

GetReference<T>(ReadOnlySpan<T>)

Returns a reference to the element of the read-only span at index 0.

public static ref readonly T GetReference<T>(this ReadOnlySpan<T> span)

Parameters

span ReadOnlySpan<T>

The read-only span from which the reference is retrieved.

Returns

T

A reference to the element at index 0.

Type Parameters

T

The type of items in the span.

GetReference<T>(ReadOnlySpan<T>, int)

Returns a reference to the element of the read-only span at index 0.

public static ref readonly T GetReference<T>(this ReadOnlySpan<T> span, int index)

Parameters

span ReadOnlySpan<T>

The read-only span from which the reference is retrieved.

index int

The index of the element of span for which to take a reference.

Returns

T

A reference to the element at index 0.

Type Parameters

T

The type of items in the span.

GetReference<T>(ReadOnlySpan<T>, nuint)

Returns a reference to the element of the read-only span at index 0.

public static ref readonly T GetReference<T>(this ReadOnlySpan<T> span, nuint index)

Parameters

span ReadOnlySpan<T>

The read-only span from which the reference is retrieved.

index nuint

The index of the element of span for which to take a reference.

Returns

T

A reference to the element at index 0.

Type Parameters

T

The type of items in the span.

GetReference<T>(Span<T>)

Returns a reference to the element of the span at index 0.

public static ref T GetReference<T>(this Span<T> span)

Parameters

span Span<T>

The span from which the reference is retrieved.

Returns

T

A reference to the element at index 0.

Type Parameters

T

The type of items in the span.

GetReference<T>(Span<T>, int)

Returns a reference to the element of the span at index 0.

public static ref T GetReference<T>(this Span<T> span, int index)

Parameters

span Span<T>

The span from which the reference is retrieved.

index int

The index of the element of span for which to take a reference.

Returns

T

A reference to the element at index 0.

Type Parameters

T

The type of items in the span.

GetReference<T>(Span<T>, nuint)

Returns a reference to the element of the span at index 0.

public static ref T GetReference<T>(this Span<T> span, nuint index)

Parameters

span Span<T>

The span from which the reference is retrieved.

index nuint

The index of the element of span for which to take a reference.

Returns

T

A reference to the element at index 0.

Type Parameters

T

The type of items in the span.

GetReference<T>(T[])

Returns a reference to the 0th element of array. If the array is empty, returns a reference to where the 0th element would have been stored. Such a reference may be used for pinning but must never be dereferenced.

public static ref T GetReference<T>(this T[] array)

Parameters

array T[]

The array to analyze.

Returns

T

Reference to the 0th element in array.

Type Parameters

T

The type of the array elements.

Exceptions

NullReferenceException

array is null.

GetReference<T>(T[], int)

Returns a reference to the 0th element of array. If the array is empty, returns a reference to where the 0th element would have been stored. Such a reference may be used for pinning but must never be dereferenced.

public static ref T GetReference<T>(this T[] array, int index)

Parameters

array T[]

The array to analyze.

index int

The index of the element of array for which to take a reference.

Returns

T

Reference to the 0th element in array.

Type Parameters

T

The type of the array elements.

Exceptions

NullReferenceException

array is null.

GetReference<T>(T[], nuint)

Returns a reference to the 0th element of array. If the array is empty, returns a reference to where the 0th element would have been stored. Such a reference may be used for pinning but must never be dereferenced.

public static ref T GetReference<T>(this T[] array, nuint index)

Parameters

array T[]

The array to analyze.

index nuint

The index of the element of array for which to take a reference.

Returns

T

Reference to the 0th element in array.

Type Parameters

T

The type of the array elements.

Exceptions

NullReferenceException

array is null.

IsNotNullRef<T>(ref readonly T)

Determines if a given reference to a value of type T is not a null reference.

public static bool IsNotNullRef<T>(ref readonly T source)

Parameters

source T

The reference to check.

Returns

bool

true if source is not a null reference; otherwise, false.

Type Parameters

T

The type of the reference.

IsNullRef<T>(ref readonly T)

Determines if a given managed pointer to a value of type T is a null reference.

public static bool IsNullRef<T>(ref readonly T source)

Parameters

source T

The managed pointer to check.

Returns

bool

true if source is a null reference; otherwise, false.

Type Parameters

T

The elemental type of the managed pointer.

NullRef<T>()

Returns a null managed pointer to a value of type T.

public static ref T NullRef<T>()

Returns

T

A null managed pointer to a value of type T.

Type Parameters

T

The elemental type of the managed pointer.

ReadUnaligned<T>(void*)

Reads a value of type T from the given location without assuming architecture dependent alignment of the source address.

public static T ReadUnaligned<T>(void* source) where T : unmanaged

Parameters

source void*

An unmanaged pointer containing the address to read from.

Returns

T

A value of type T read from the given location.

Type Parameters

T

The type of the value to read.

ReadUnaligned<T>(void*, nuint)

Reads a value of type T from the given location without assuming architecture dependent alignment of the source address.

public static T ReadUnaligned<T>(void* source, nuint offset) where T : unmanaged

Parameters

source void*

An unmanaged pointer containing the address to read from.

offset nuint

The offset in bytes from the location pointed to by source.

Returns

T

A value of type T read from the given location.

Type Parameters

T

The type of the value to read.

SizeOf<T>()

Returns the size of a value of the given type parameter.

public static uint SizeOf<T>()

Returns

uint

The size, in bytes, of a value of type T.

Type Parameters

T

The type whose size is to be retrieved.

WriteUnaligned<T>(void*, nuint, T)

Writes a value of type T to the given location without assuming architecture dependent alignment of the destination address.

public static void WriteUnaligned<T>(void* destination, nuint offset, T value) where T : unmanaged

Parameters

destination void*

A managed pointer containing the address to write to.

offset nuint

The offset in bytes from the location pointed to by destination.

value T

The value to write.

Type Parameters

T

The type of the value to write.

WriteUnaligned<T>(void*, T)

Writes a value of type T to the given location without assuming architecture dependent alignment of the destination address.

public static void WriteUnaligned<T>(void* destination, T value) where T : unmanaged

Parameters

destination void*

A managed pointer containing the address to write to.

value T

The value to write.

Type Parameters

T

The type of the value to write.