Table of Contents

Class Properties

Namespace
Sdl3Sharp
Assembly
Sdl3Sharp.dll

Represents a group of (named) properties

public sealed class Properties : IEnumerable<string>, IEnumerable, IDisposable, Sdl.IDisposeReceiver, IEquatable<Properties>, ISpanFormattable, IFormattable
Inheritance
Properties
Implements
Inherited Members
Extension Methods

Constructors

Properties(Sdl)

Creates a new group of properties

public Properties(Sdl sdl)

Parameters

sdl Sdl

The current Sdl instance

Remarks

In contrast to most of the remaining API which uses the Try-method pattern, this constructor intentionally fails by throwing an exception. If you want to handle failures wrap the call to this constructor in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

ArgumentNullException

sdl is null

SdlException

Couldn't create a new property group (check TryGet(out string?) for more information)

InvalidOperationException

Could not register the Properties with the given sdl instance

Properties

Id

Gets the id of the group of properties

public uint Id { get; }

Property Value

uint

The id of the group of properties

Remarks

An id value of 0 indicates an invalid group of properties

Methods

Contains(string)

Determines whether a property with a specified name exists within the group of properties

public bool Contains(string name)

Parameters

name string

The name of the property to check if it exists within the group of properties

Returns

bool

true if the property exists within the group of properties; otherwise, false

Dispose()

Diposes and potentially destroys the group of properties

public void Dispose()

Remarks

When a group of properties is destroyed, all properties are deleted and their cleanup callbacks will be called, if any. Alternatively, all properties are automatically destroyed when Dispose() is called.

Equals(Properties?)

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

public bool Equals(Properties? other)

Parameters

other Properties

An object to compare with this object.

Returns

bool

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

Equals(object?)

Determines whether the specified object is equal to the current object.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current object.

Returns

bool

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

~Properties() 

protected ~Properties()

GetBooleanValueOrDefault(string, bool)

Gets the boolean value of a property with a specified name within the group of properties

public bool GetBooleanValueOrDefault(string name, bool defaultValue)

Parameters

name string

The name of the property to get it's boolean value

defaultValue bool

The default value of the property, if it does not exist or isn't a boolean property

Returns

bool

The boolean value of the property, if the property exists within the group of properties and it's set as a boolean property; otherwise, defaultValue

GetEnumerator()

Gets an Properties.Enumerator that enumerates the names of the properties in the group of properties

public Properties.Enumerator GetEnumerator()

Returns

Properties.Enumerator

An Properties.Enumerator that enumerates the names of the properties in the group of properties

Remarks

In contrast to most of the remaining API which uses the Try-method pattern, this method intentionally fails by throwing an exception. If you want to handle failures wrap the call to this method in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

SdlException

Couldn't create an Properties.Enumerator for the group of properties (check TryGet(out string?) for more information)

GetFloatValueOrDefault(string, float)

Gets the floating point value of a property with a specified name within the group of properties

public float GetFloatValueOrDefault(string name, float defaultValue)

Parameters

name string

The name of the property to get it's floating point value

defaultValue float

The default value of the property, if it does not exist or isn't a floating point property

Returns

float

The floating point value of the property, if the property exists within the group of properties and it's set as a floating point property; otherwise, defaultValue

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

GetNumberValueOrDefault(string, long)

Gets the numeric (integer) value of a property with a specified name within the group of properties

public long GetNumberValueOrDefault(string name, long defaultValue)

Parameters

name string

The name of the property to get it's numeric value

defaultValue long

The default value of the property, if it does not exist or isn't a number property

Returns

long

The numeric (integer) value of the property, if the property exists within the group of properties and it's set as a number property; otherwise, defaultValue

GetPointerValueOrDefault(string, nint)

Gets the pointer value of a property with a specified name within the group of properties

public nint GetPointerValueOrDefault(string name, nint defaultValue)

Parameters

name string

The name of the property to get it's pointer value

defaultValue nint

The default value of the property, if it does not exist or isn't a pointer property

Returns

nint

The pointer value of the property, if the property exists within the group of properties and it's set as a pointer property; otherwise, defaultValue

GetStringValueOrDefault(string, string?)

Gets the string value of a property with a specified name within the group of properties

public string? GetStringValueOrDefault(string name, string? defaultValue)

Parameters

name string

The name of the property to get it's string value

defaultValue string

The default value of the property, if it does not exist or isn't a string property

Returns

string

The string value of the property, if the property exists within the group of properties and it's set as a string property; otherwise, defaultValue

GetType(string)

Gets the type of a property with a specified name within the group of properties

public PropertyType GetType(string name)

Parameters

name string

The name of the property to get it's type

Returns

PropertyType

The type of the property, if the property exists and it's set within the group of properties; otherwise, Invalid

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

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.

TryCopyTo(Properties)

Tries to copy a group of properties to another

public bool TryCopyTo(Properties destination)

Parameters

destination Properties

The destination group of properties

Returns

bool

true if the group of properties was successfully copied to destination; otherwise, false (check TryGet(out string?) for more information)

TryForEach(Action<string>)

Tries to enumerate the names of the properties within the group of properties

public bool TryForEach(Action<string> action)

Parameters

action Action<string>

An Action<T> to perform on each name of a property of the group of properties

Returns

bool

true if the enumeration of the properties of the group of properties were successfully performed; otherwise, false (check TryGet(out string?) for more information)

Remarks

The action is called for each property (name) in the group of properties. The properties are locked during enumeration.

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.

TryGetBooleanValue(string, out bool)

Tries to get the boolean value of a property with a specified name within the group of properties

public bool TryGetBooleanValue(string name, out bool value)

Parameters

name string

The name of the property to get it's boolean value

value bool

The boolean value of the property, when this method returns true; otherwise, default(bool)

Returns

bool

true if the property exists within the group of properties and it's set as a boolean property; otherwise, false

TryGetFloatValue(string, out float)

Tries to get the floating point value of a property with a specified name within the group of properties

public bool TryGetFloatValue(string name, out float value)

Parameters

name string

The name of the property to get it's floating point value

value float

The floating point value of the property, when this method returns true; otherwise, default(float)

Returns

bool

true if the property exists within the group of properties and it's set as a floating point property; otherwise, false

TryGetNumberValue(string, out long)

Tries to get the numeric (integer) value of a property with a specified name within the group of properties

public bool TryGetNumberValue(string name, out long value)

Parameters

name string

The name of the property to get it's numeric value

value long

The numeric (integer) value of the property, when this method returns true; otherwise, default(long)

Returns

bool

true if the property exists within the group of properties and it's set as a number property; otherwise, false

TryGetPointerValue(string, out nint)

Tries to get the pointer value of a property with a specified name within the group of properties

public bool TryGetPointerValue(string name, out nint value)

Parameters

name string

The name of the property to get it's pointer value

value nint

The pointer value of the property, when this method returns true; otherwise, default(nint)

Returns

bool

true if the property exists within the group of properties and it's set as a pointer property; otherwise, false

TryGetStringValue(string, out string?)

Tries to get the string value of a property with a specified name within the group of properties

public bool TryGetStringValue(string name, out string? value)

Parameters

name string

The name of the property to get it's string value

value string

The string value of the property, when this method returns true; otherwise, default(string?)

Returns

bool

true if the property exists within the group of properties and it's set as a string property; otherwise, false

TryLock()

Tries to lock the group of properties

public bool TryLock()

Returns

bool

true if the group of properties was successfully locked; otherwise, false (check TryGet(out string?) for more information)

Remarks

Obtains a multi-threaded lock for these properties. Other threads will wait while trying to lock these properties until they are unlocked. Properties must be unlocked before they are destroyed.

The lock is automatically taken when setting individual properties, calling this method is only needed when you want to set several properties atomically or want to guarantee that properties being queried aren't freed in another thread.

TryRemove(string)

Tries to removes a property with a specified name from the group of properties

public bool TryRemove(string name)

Parameters

name string

The name of the property to remove

Returns

bool

true if the property was successfully removed from the group of properties; otherwise, false (check TryGet(out string?) for more information)

TrySetBooleanValue(string, bool)

Tries to set the boolean value of a property with a specified name within the group of properties and potentially add the property to the group of properties, when it not yet exists

public bool TrySetBooleanValue(string name, bool value)

Parameters

name string

The name of the property to set

value bool

The new value of the property

Returns

bool

true if the boolean value of the property was successfully set within the group of properties; otherwise, false (check TryGet(out string?) for more information)

TrySetFloatValue(string, float)

Tries to set the floating point value of a property with a specified name within the group of properties and potentially add the property to the group of properties, when it not yet exists

public bool TrySetFloatValue(string name, float value)

Parameters

name string

The name of the property to set

value float

The new value of the property

Returns

bool

true if the floating point value of the property was successfully set within the group of properties; otherwise, false (check TryGet(out string?) for more information)

TrySetNumberValue(string, long)

Tries to set the numeric (integer) value of a property with a specified name within the group of properties and potentially add the property to the group of properties, when it not yet exists

public bool TrySetNumberValue(string name, long value)

Parameters

name string

The name of the property to set

value long

The new value of the property

Returns

bool

true if the numeric value of the property was successfully set within the group of properties; otherwise, false (check TryGet(out string?) for more information)

TrySetPointerValue(string, nint)

Tries to set the pointer value of a property with a specified name within the group of properties and potentially add the property to the group of properties, when it not yet exists

public bool TrySetPointerValue(string name, nint value)

Parameters

name string

The name of the property to set

value nint

The new value of the property

Returns

bool

true if the pointer value of the property was successfully set within the group of properties; otherwise, false (check TryGet(out string?) for more information)

TrySetPointerValue(string, nint, Action<nint>?)

Tries to set the pointer value of a property with a specified name within the group of properties and potentially add the property to the group of properties, when it not yet exists. This sets the pointer value of the property together with a cleanup callback that is called when the property is deleted.

public bool TrySetPointerValue(string name, nint value, Action<nint>? cleanup)

Parameters

name string

The name of the property to set

value nint

The new value of the property, or Zero (default(nint)) to delete the property

cleanup Action<nint>

The callback to call when the property is deleted, or null if no cleanup is necessary

Returns

bool

true if the pointer value of the property was successfully set within the group of properties; otherwise, false (check TryGet(out string?) for more information)

Remarks

The cleanup callback is also called if setting the property fails for any reason.

For simply setting basic data types, like numbers, bools, or strings, use TrySetNumberValue(string, long), TrySetBooleanValue(string, bool), or TrySetStringValue(string, string?) instead, as those methods will handle cleanup on your behalf. This method is only for more complex, custom data.

TrySetStringValue(string, string?)

Tries to set the string value of a property with a specified name within the group of properties and potentially add the property to the group of properties, when it not yet exists

public bool TrySetStringValue(string name, string? value)

Parameters

name string

The name of the property to set

value string

The new value of the property

Returns

bool

true if the string value of the property was successfully set within the group of properties; otherwise, false (check TryGet(out string?) for more information)

Unlock()

Unlocks the group of properties

public void Unlock()