Struct NativeMemory<T>

Namespace

Sdl3Sharp.Utilities

Assembly

Sdl3Sharp.dll

Represents an allocated native memory buffer of elements of type T

public readonly struct NativeMemory<T> : IEquatable<ReadOnlyNativeMemory>, IEqualityOperators<NativeMemory<T>, ReadOnlyNativeMemory, bool>, IEquatable<NativeMemory<T>>, ISpanFormattable, IFormattable, IEqualityOperators<NativeMemory<T>, NativeMemory<T>, bool>, IEnumerable<T>, IEnumerable where T : unmanaged

Type Parameters

T

The type of the elements in the native memory buffer

Implements

IEquatable<ReadOnlyNativeMemory>

IEqualityOperators<NativeMemory<T>, ReadOnlyNativeMemory, bool>

IEquatable<NativeMemory<T>>

ISpanFormattable

IFormattable

IEqualityOperators<NativeMemory<T>, NativeMemory<T>, bool>

IEnumerable<T>

IEnumerable

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Properties

Empty

Gets an empty NativeMemory<T>

public static NativeMemory<T> Empty { get; }

Property Value

NativeMemory<T>

An empty NativeMemory<T>

IsEmpty

Gets a value indicating whether the allocated memory buffer is empty

public bool IsEmpty { get; }

Property Value

bool

A value indicating whether the allocated memory buffer is empty

See Also

Empty

IsPinned

Gets a value indicating whether the underlying NativeMemoryManagerBase of this allocated memory buffer is pinned

[MemberNotNullWhen(true, new string[] { "mMemoryManager", "MemoryManager" })]
public bool IsPinned { get; }

Property Value

bool

A value indicating whether the underlying NativeMemoryManagerBase of this allocated memory buffer is pinned

See Also

Pin()

IsValid

Gets a value indicating whether the allocated memory buffer is valid

public bool IsValid { get; }

Property Value

bool

A value indicating whether the allocated memory buffer is valid

Remarks

A valid NativeMemory<T> might become invalid after the underlying NativeMemoryManager changed (e.g. by calling TryRealloc(ref NativeMemoryManager?, nuint) on it).

this[nuint]

Gets a reference to the element of type T at a specified index into the allocated memory buffer

public ref T this[nuint index] { get; }

Parameters

index nuint

The index of the element of type T into the allocated memory buffer to get a reference to

Property Value

T

A reference to the element of type T at a specified index into the allocated memory buffer

Exceptions

ArgumentOutOfRangeException

index is greater or equal to Length

InvalidOperationException

The NativeMemory<T> instance is invalid (the underlying NativeMemoryManager might have changed)

Length

Gets the number of elements of type T in the allocated memory buffer

public nuint Length { get; }

Property Value

nuint

The number of elements of type T in the allocated memory buffer

Pointer

Gets a pointer to the start of the allocated memory buffer

public nint Pointer { get; }

Property Value

nint

A pointer to the start of the allocated memory buffer

Span

Gets the allocated memory buffer as a Span<T>

public Span<T> Span { get; }

Property Value

Span<T>

The allocated memory buffer as a Span<T>

Examples

This example demonstrates how you could do a chunk-based approach with Span<T>s:

 tempMemory = ...;
for ( span = tempMemory.; !span.; tempMemory = tempMemory.(()span.), span = tempMemory.)
{
	// Do something with the memory in chunks using 'span'
}

Remarks

The returned Span<T> might not cover the whole memory region this NativeMemory<T> covers. This comes from a technical limitation where Span<T> uses int as the type for it's Length property where as NativeMemory<T> uses nuint as the type for it's Length property. Therefore, especially on 64-bit platforms, a NativeMemory<T> could cover a larger memory region than Span<T> ever could. If that's the case, you need to do a chunk-based approach, in order to cover the whole memory region with Span<T>s.

Exceptions

InvalidOperationException

The NativeMemory<T> instance is invalid (the underlying NativeMemoryManager might have changed)

Methods

Equals(NativeMemory<T>)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(NativeMemory<T> other)

Parameters

other NativeMemory<T>

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(ReadOnlyNativeMemory)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(ReadOnlyNativeMemory other)

Parameters

other ReadOnlyNativeMemory

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(object?)

Indicates whether this instance and a specified object are equal.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current instance.

Returns

bool

true if obj and this instance are the same type and represent the same value; otherwise, false.

GetEnumerator()

Returns an enumerator that iterates through the collection.

public NativeMemory<T>.Enumerator GetEnumerator()

Returns

NativeMemory<T>.Enumerator

An enumerator that can be used to iterate through the collection.

Remarks

Note: This operation pins the given nativeMemory.

Exceptions

InvalidOperationException

The NativeMemory<T> instance is invalid (the underlying NativeMemoryManager might have changed)

GetHashCode()

Returns the hash code for this instance.

public override int GetHashCode()

Returns

int

A 32-bit signed integer that is the hash code for this instance.

Pin()

Pins the underlying NativeMemoryManager

public NativeMemoryPin Pin()

Returns

NativeMemoryPin

A pin pinning the underlying NativeMemoryManager

Slice(nuint)

Gets a slice of the allocate memory buffer starting at a specified element index

public NativeMemory<T> Slice(nuint start)

Parameters

start nuint

The index of an element of type T where the resulting NativeMemory<T> should start

Returns

NativeMemory<T>

A slice of the allocate memory buffer starting at a element index start

Exceptions

ArgumentOutOfRangeException

start is greater than Length

InvalidOperationException

The NativeMemory<T> instance is invalid (the underlying NativeMemoryManager might have changed)

Slice(nuint, nuint)

Gets a slice of the allocate memory buffer starting at a specified element index and containing a specified number of elements of type T

public NativeMemory<T> Slice(nuint start, nuint length)

Parameters

start nuint

The index of an element of type T where the resulting NativeMemory<T> should start

length nuint

The number of elements of type T that the resulting NativeMemory<T> should contain

Returns

NativeMemory<T>

A slice of the allocate memory buffer starting at a element index start and containing length number of elements of type T

Exceptions

ArgumentOutOfRangeException

start is greater than Length

• or - start + length is greater than Length

InvalidOperationException

The NativeMemory<T> instance is invalid (the underlying NativeMemoryManager might have changed)

ToString()

Returns the fully qualified type name of this instance.

public override string ToString()

Returns

string

The fully qualified type name.

ToString(IFormatProvider?)

Formats the value of the current instance using the specified format.

public string ToString(IFormatProvider? formatProvider)

Parameters

formatProvider IFormatProvider

The provider to use to format the value.

-or-

A null reference (Nothing in Visual Basic) to obtain the numeric format information from the current locale setting of the operating system.

Returns

string

The value of the current instance in the specified format.

ToString(string?)

Formats the value of the current instance using the specified format.

public string ToString(string? format)

Parameters

format string

The format to use.

-or-

A null reference (Nothing in Visual Basic) to use the default format defined for the type of the IFormattable implementation.

Returns

string

The value of the current instance in the specified format.

ToString(string?, IFormatProvider?)

Formats the value of the current instance using the specified format.

public string ToString(string? format, IFormatProvider? formatProvider)

Parameters

format string

The format to use.

-or-

A null reference (Nothing in Visual Basic) to use the default format defined for the type of the IFormattable implementation.

formatProvider IFormatProvider

The provider to use to format the value.

-or-

A null reference (Nothing in Visual Basic) to obtain the numeric format information from the current locale setting of the operating system.

Returns

string

The value of the current instance in the specified format.

TryFormat(Span<char>, out int, ReadOnlySpan<char>, IFormatProvider?)

Tries to format the value of the current instance into the provided span of characters.

public bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format = default, IFormatProvider? provider = null)

Parameters

destination Span<char>

The span in which to write this instance's value formatted as a span of characters.

charsWritten int

When this method returns, contains the number of characters that were written in destination.

format ReadOnlySpan<char>

A span containing the characters that represent a standard or custom format string that defines the acceptable format for destination.

provider IFormatProvider

An optional object that supplies culture-specific formatting information for destination.

Returns

bool

true if the formatting was successful; otherwise, false.

Operators

operator ==(NativeMemory<T>, NativeMemory<T>)

Compares two values to determine equality.

public static bool operator ==(NativeMemory<T> left, NativeMemory<T> right)

Parameters

left NativeMemory<T>

The value to compare with right.

right NativeMemory<T>

The value to compare with left.

Returns

bool

true if left is equal to right; otherwise, false.

operator ==(NativeMemory<T>, ReadOnlyNativeMemory)

Compares two values to determine equality.

public static bool operator ==(NativeMemory<T> left, ReadOnlyNativeMemory right)

Parameters

left NativeMemory<T>

The value to compare with right.

right ReadOnlyNativeMemory

The value to compare with left.

Returns

bool

true if left is equal to right; otherwise, false.

explicit operator NativeMemory<T>(NativeMemory)

Converts an allocated memory buffer of unspecified type to an allocated memory buffer of type T

public static explicit operator NativeMemory<T>(NativeMemory nativeMemory)

Parameters

nativeMemory NativeMemory

The allocated memory buffer of unspecified type to convert to an allocated memory buffer of type T

Returns

NativeMemory<T>

An allocated memory buffer of type T spanning the same or a similar memory region as the given nativeMemory

Remarks

The resulting allocated memory buffer of type T might not span all of the same memory region of the given nativeMemory. Depending on the size of an instance of T, on how it aligns in the memory region given by nativeMemory, and on the offset from the originally allocated memory's starting point, the resulting allocated memory buffer of type T might span a memory region which is a mere segment of the given nativeMemory's memory region. Note: This might be still true, even if the given nativeMemory's Length is a multiple of the size of an instance of type T!

implicit operator NativeMemory(NativeMemory<T>)

Converts an allocated memory buffer of type T to an allocated memory buffer of unspecified type

public static implicit operator NativeMemory(NativeMemory<T> nativeMemory)

Parameters

nativeMemory NativeMemory<T>

The allocated memory buffer of type T to convert to an allocated memory buffer of unspecified type

Returns

NativeMemory

An allocated memory buffer of unspecified type spanning the exact same memory region as the given nativeMemory

implicit operator ReadOnlyNativeMemory(NativeMemory<T>)

Converts an allocated memory buffer of type T to an allocated read-only memory buffer of unspecified type

public static implicit operator ReadOnlyNativeMemory(NativeMemory<T> nativeMemory)

Parameters

nativeMemory NativeMemory<T>

The allocated memory buffer of type T to convert to an allocated read-only memory buffer of unspecified type

Returns

ReadOnlyNativeMemory

An allocated read-only memory buffer of unspecified type spanning the exact same memory region as the given nativeMemory

operator !=(NativeMemory<T>, NativeMemory<T>)

Compares two values to determine inequality.

public static bool operator !=(NativeMemory<T> left, NativeMemory<T> right)

Parameters

left NativeMemory<T>

The value to compare with right.

right NativeMemory<T>

The value to compare with left.

Returns

bool

true if left is not equal to right; otherwise, false.

operator !=(NativeMemory<T>, ReadOnlyNativeMemory)

Compares two values to determine inequality.

public static bool operator !=(NativeMemory<T> left, ReadOnlyNativeMemory right)

Parameters

left NativeMemory<T>

The value to compare with right.

right ReadOnlyNativeMemory

The value to compare with left.

Returns

bool

true if left is not equal to right; otherwise, false.