Struct FixedString128Bytes

An unmanaged UTF-8 string whose content is stored directly in the 128-byte struct.

Implements
Namespace: Unity.Collections
Assembly: Unity.Collections.dll
Syntax
[Serializable]
public struct FixedString128Bytes : INativeList<byte>, IIndexable<byte>, IUTF8Bytes
Remarks

The binary layout of this string is guaranteed, for now and all time, to be a length (a little-endian two byte integer) followed by the bytes of the characters (with no padding). A zero byte always immediately follows the last character. Effectively, the number of bytes for storing characters is 3 less than 128 (two length bytes and one null byte).

This layout is identical to a FixedList128Bytes<T> of bytes, thus allowing reinterpretation between FixedString128Bytes and FixedList128Bytes.

By virtue of being an unmanaged, non-allocated struct with no pointers, this string is fully compatible with jobs and Burst compilation. Unlike managed string types, these strings can be put in any unmanaged ECS components, FixedList, or any other unmanaged structs.

Constructors

FixedString128Bytes(string)

Initializes and returns an instance of FixedString128Bytes with the characters copied from a string.

Declaration
[ExcludeFromBurstCompatTesting("Takes managed string")]
public FixedString128Bytes(string source)
Parameters
Type Name Description
string source

The source string to copy.
Exceptions
Type Condition
ArgumentException

Thrown if the string to copy's length exceeds the capacity of FixedString128Bytes.

FixedString128Bytes(in FixedString128Bytes)

Initializes and returns an instance of FixedString128Bytes that is a copy of another string.

Declaration
public FixedString128Bytes(in FixedString128Bytes other)
Parameters
Type Name Description
FixedString128Bytes other

The string to copy.
Exceptions
Type Condition
ArgumentException

Thrown if the string to copy's length exceeds the capacity of FixedString128Bytes.

FixedString128Bytes(in FixedString32Bytes)

Initializes and returns an instance of FixedString128Bytes that is a copy of another string.

Declaration
public FixedString128Bytes(in FixedString32Bytes other)
Parameters
Type Name Description
FixedString32Bytes other

The string to copy.
Exceptions
Type Condition
ArgumentException

Thrown if the string to copy's length exceeds the capacity of FixedString128Bytes.

FixedString128Bytes(in FixedString4096Bytes)

Initializes and returns an instance of FixedString128Bytes that is a copy of another string.

Declaration
public FixedString128Bytes(in FixedString4096Bytes other)
Parameters
Type Name Description
FixedString4096Bytes other

The string to copy.
Exceptions
Type Condition
ArgumentException

Thrown if the string to copy's length exceeds the capacity of FixedString128Bytes.

FixedString128Bytes(in FixedString512Bytes)

Initializes and returns an instance of FixedString128Bytes that is a copy of another string.

Declaration
public FixedString128Bytes(in FixedString512Bytes other)
Parameters
Type Name Description
FixedString512Bytes other

The string to copy.
Exceptions
Type Condition
ArgumentException

Thrown if the string to copy's length exceeds the capacity of FixedString128Bytes.

FixedString128Bytes(in FixedString64Bytes)

Initializes and returns an instance of FixedString128Bytes that is a copy of another string.

Declaration
public FixedString128Bytes(in FixedString64Bytes other)
Parameters
Type Name Description
FixedString64Bytes other

The string to copy.
Exceptions
Type Condition
ArgumentException

Thrown if the string to copy's length exceeds the capacity of FixedString128Bytes.

FixedString128Bytes(in UnsafeText)

Initializes and returns an instance of FixedString128Bytes that is a copy of another string.

Declaration
public FixedString128Bytes(in UnsafeText other)
Parameters
Type Name Description
UnsafeText other

The UnsafeText to copy.
Exceptions
Type Condition
ArgumentException

Thrown if the string to copy's length exceeds the capacity of FixedString128Bytes.

FixedString128Bytes(ReadOnly)

Initializes and returns an instance of FixedString128Bytes that is a copy of another string.

Declaration
public FixedString128Bytes(NativeText.ReadOnly other)
Parameters
Type Name Description
NativeText.ReadOnly other

The string to copy.
Exceptions
Type Condition
ArgumentException

Thrown if the string to copy's length exceeds the capacity of FixedString128Bytes.

FixedString128Bytes(Rune, int)

Initializes and returns an instance of FixedString128Bytes with a single character repeatedly appended some number of times.

Declaration
public FixedString128Bytes(Unicode.Rune rune, int count = 1)
Parameters
Type Name Description
Unicode.Rune rune

The Unicode.Rune to repeat.
int count

The number of times to repeat the character. Default is 1.

Properties

Capacity

The number of bytes this string has for storing UTF-8 characters.

Declaration
public int Capacity { readonly get; set; }
Property Value
Type Description
int

The number of bytes this string has for storing UTF-8 characters.
Remarks

Does not include the null-terminator byte.

A setter is included for conformity with INativeList<T>, but Capacity is fixed at 125. Setting the value to anything other than 125 throws an exception.

In UTF-8 encoding, each Unicode code point (character) requires 1 to 4 bytes, so the number of characters that can be stored may be less than the capacity.

Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown if attempting to set the capacity to anything other than 125.

IsEmpty

Returns true if this string is empty (has no characters).

Declaration
public readonly bool IsEmpty { get; }
Property Value
Type Description
bool

True if this string is empty (has no characters).

this[int]

Returns the byte (not character) at an index.

Declaration
public byte this[int index] { readonly get; set; }
Parameters
Type Name Description
int index

A byte index.
Property Value
Type Description
byte

The byte at the index.
Exceptions
Type Condition
IndexOutOfRangeException

Thrown if the index is out of bounds.

Length

The current length in bytes of this string's content.

Declaration
public int Length { readonly get; set; }
Property Value
Type Description
int

The current length in bytes of this string's content.
Remarks

The length value does not include the null-terminator byte.

Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown if the new length is out of bounds.

UTF8MaxLengthInBytes

Returns the maximum number of UTF-8 bytes that can be stored in this string.

Declaration
public static int UTF8MaxLengthInBytes { get; }
Property Value
Type Description
int

The maximum number of UTF-8 bytes that can be stored in this string.

Methods

Add(in byte)

Appends a byte.

Declaration
public void Add(in byte value)
Parameters
Type Name Description
byte value

A byte to append.
Remarks

A zero byte will always follow the newly appended byte.

No validation is performed: it is your responsibility for the bytes of the string to form valid UTF-8 when you're done appending bytes.

AsFixedList()

Returns a reference to a FixedList128Bytes<byte> representation of this string.

Declaration
public ref FixedList128Bytes<byte> AsFixedList()
Returns
Type Description
FixedList128Bytes<byte>

A ref to a FixedListByte128 representation of the FixedString128Bytes.
Remarks

The referenced FixedListByte128 is the very same bytes as the original FixedString128Bytes, so it is only valid as long as the original FixedString128Bytes is valid.

Clear()

Sets the length to 0.

Declaration
public void Clear()

CompareTo(string)

Returns the lexicographical sort order of this string relative to another.

Declaration
[ExcludeFromBurstCompatTesting("Takes managed string")]
public int CompareTo(string other)
Parameters
Type Name Description
string other

A System.String to compare with.
Returns
Type Description
int

An integer denoting the lexicographical sort order of this string relative to the other:

 0 denotes both strings have the same sort position.<br />
 -1 denotes that this string should be sorted to precede the other string.<br />
 +1 denotes that this string should be sorted to follow the other string.<br />

CompareTo(FixedString128Bytes)

Returns the lexicographical sort order of this string relative to another.

Declaration
public int CompareTo(FixedString128Bytes other)
Parameters
Type Name Description
FixedString128Bytes other

A string to compare with.
Returns
Type Description
int

A number denoting the lexicographical sort order of this string relative to the other:

 0 denotes that both strings have the same sort position.<br />
 -1 denotes that this string should be sorted to precede the other.<br />
 +1 denotes that this string should be sorted to follow the other.<br />

CompareTo(FixedString32Bytes)

Returns the lexicographical sort order of this string relative to another.

Declaration
public int CompareTo(FixedString32Bytes other)
Parameters
Type Name Description
FixedString32Bytes other

A string to compare with.
Returns
Type Description
int

A number denoting the lexicographical sort order of this string relative to the other:

 0 denotes that both strings have the same sort position.<br />
 -1 denotes that this string should be sorted to precede the other.<br />
 +1 denotes that this string should be sorted to follow the other.<br />

CompareTo(FixedString4096Bytes)

Returns the lexicographical sort order of this string relative to another.

Declaration
public int CompareTo(FixedString4096Bytes other)
Parameters
Type Name Description
FixedString4096Bytes other

A string to compare with.
Returns
Type Description
int

A number denoting the lexicographical sort order of this string relative to the other:

 0 denotes that both strings have the same sort position.<br />
 -1 denotes that this string should be sorted to precede the other.<br />
 +1 denotes that this string should be sorted to follow the other.<br />

CompareTo(FixedString512Bytes)

Returns the lexicographical sort order of this string relative to another.

Declaration
public int CompareTo(FixedString512Bytes other)
Parameters
Type Name Description
FixedString512Bytes other

A string to compare with.
Returns
Type Description
int

A number denoting the lexicographical sort order of this string relative to the other:

 0 denotes that both strings have the same sort position.<br />
 -1 denotes that this string should be sorted to precede the other.<br />
 +1 denotes that this string should be sorted to follow the other.<br />

CompareTo(FixedString64Bytes)

Returns the lexicographical sort order of this string relative to another.

Declaration
public int CompareTo(FixedString64Bytes other)
Parameters
Type Name Description
FixedString64Bytes other

A string to compare with.
Returns
Type Description
int

A number denoting the lexicographical sort order of this string relative to the other:

 0 denotes that both strings have the same sort position.<br />
 -1 denotes that this string should be sorted to precede the other.<br />
 +1 denotes that this string should be sorted to follow the other.<br />

ElementAt(int)

Returns the reference to a byte (not character) at an index.

Declaration
public ref byte ElementAt(int index)
Parameters
Type Name Description
int index

A byte index.
Returns
Type Description
byte

A reference to the byte at the index.
Exceptions
Type Condition
IndexOutOfRangeException

Thrown if the index is out of bounds.

Equals(object)

Returns true if this string and an object are equal.

Declaration
[ExcludeFromBurstCompatTesting("Takes managed object")]
public override bool Equals(object obj)
Parameters
Type Name Description
object obj

An object to compare for equality.
Returns
Type Description
bool

True if this string and the object are equal.
Overrides
Remarks

Returns false if the object is neither a System.String or a FixedString.

Two strings are equal if they have equal length and all their characters match.

Equals(string)

Returns true if this string and another have the same length and all the same characters.

Declaration
[ExcludeFromBurstCompatTesting("Takes managed string")]
public bool Equals(string other)
Parameters
Type Name Description
string other

A string to compare for equality.
Returns
Type Description
bool

True if this string and the other have the same length and all the same characters.

Equals(FixedString128Bytes)

Returns true if this string and another string are equal.

Declaration
public bool Equals(FixedString128Bytes other)
Parameters
Type Name Description
FixedString128Bytes other

A FixedString128Bytes to compare for equality.
Returns
Type Description
bool

True if the two strings are equal.
Remarks

Two strings are equal if they have equal length and all their characters match.

Equals(FixedString32Bytes)

Returns true if this string and another string are equal.

Declaration
public bool Equals(FixedString32Bytes other)
Parameters
Type Name Description
FixedString32Bytes other

A FixedString32Bytes to compare for equality.
Returns
Type Description
bool

True if the two strings are equal.
Remarks

Two strings are equal if they have equal length and all their characters match.

Equals(FixedString4096Bytes)

Returns true if this string and another string are equal.

Declaration
public bool Equals(FixedString4096Bytes other)
Parameters
Type Name Description
FixedString4096Bytes other

A FixedString4096Bytes to compare for equality.
Returns
Type Description
bool

True if the two strings are equal.
Remarks

Two strings are equal if they have equal length and all their characters match.

Equals(FixedString512Bytes)

Returns true if this string and another string are equal.

Declaration
public bool Equals(FixedString512Bytes other)
Parameters
Type Name Description
FixedString512Bytes other

A FixedString512Bytes to compare for equality.
Returns
Type Description
bool

True if the two strings are equal.
Remarks

Two strings are equal if they have equal length and all their characters match.

Equals(FixedString64Bytes)

Returns true if this string and another string are equal.

Declaration
public bool Equals(FixedString64Bytes other)
Parameters
Type Name Description
FixedString64Bytes other

A FixedString64Bytes to compare for equality.
Returns
Type Description
bool

True if the two strings are equal.
Remarks

Two strings are equal if they have equal length and all their characters match.

GetEnumerator()

Returns an enumerator for iterating over the characters of this string.

Declaration
public FixedString128Bytes.Enumerator GetEnumerator()
Returns
Type Description
FixedString128Bytes.Enumerator

An enumerator for iterating over the characters of the FixedString128Bytes.

GetHashCode()

Returns a hash code of this string.

Declaration
public override int GetHashCode()
Returns
Type Description
int

The hash code of this string.
Overrides
Remarks

Only the character bytes are included in the hash: any bytes beyond Length are not part of the hash.

GetUnsafePtr()

Returns a pointer to the character bytes.

Declaration
public readonly byte* GetUnsafePtr()
Returns
Type Description
byte*

A pointer to the character bytes.
Remarks

The pointer returned by this method points into the internals of the target FixedString object. It is the caller's responsibility to ensure that the pointer is not used after the FixedString object is destroyed or goes out of scope.

ToString()

Returns a new managed string that is a copy of this string.

Declaration
[ExcludeFromBurstCompatTesting("Returns managed string")]
public override string ToString()
Returns
Type Description
string

A new managed string that is a copy of this string.
Overrides

TryResize(int, NativeArrayOptions)

Attempts to set the length in bytes. Does nothing if the new length is invalid.

Declaration
public bool TryResize(int newLength, NativeArrayOptions clearOptions = NativeArrayOptions.ClearMemory)
Parameters
Type Name Description
int newLength

The desired length.
NativeArrayOptions clearOptions

Whether added or removed bytes should be cleared (zeroed). (Increasing the length adds bytes; decreasing the length removes bytes.)
Returns
Type Description
bool

True if the new length is valid.

Operators

operator ==(in FixedString128Bytes, in FixedString128Bytes)

Returns true if a FixedString128Bytes and another string are equal.

Declaration
public static bool operator ==(in FixedString128Bytes a, in FixedString128Bytes b)
Parameters
Type Name Description
FixedString128Bytes a

A FixedString128Bytes to compare for equality.
FixedString128Bytes b

A FixedString128Bytes to compare for equality.
Returns
Type Description
bool

True if the two strings are equal.
Remarks

Two strings are equal if they have equal length and all their characters match.

operator ==(in FixedString128Bytes, in FixedString32Bytes)

Returns true if a FixedString128Bytes and another string are equal.

Declaration
public static bool operator ==(in FixedString128Bytes a, in FixedString32Bytes b)
Parameters
Type Name Description
FixedString128Bytes a

A FixedString128Bytes to compare for equality.
FixedString32Bytes b

A FixedString32Bytes to compare for equality.
Returns
Type Description
bool

True if the two strings are equal.
Remarks

Two strings are equal if they have equal length and all their characters match.

operator ==(in FixedString128Bytes, in FixedString4096Bytes)

Returns true if a FixedString128Bytes and another string are equal.

Declaration
public static bool operator ==(in FixedString128Bytes a, in FixedString4096Bytes b)
Parameters
Type Name Description
FixedString128Bytes a

A FixedString128Bytes to compare for equality.
FixedString4096Bytes b

A FixedString4096Bytes to compare for equality.
Returns
Type Description
bool

True if the two strings are equal.
Remarks

Two strings are equal if they have equal length and all their characters match.

operator ==(in FixedString128Bytes, in FixedString512Bytes)

Returns true if a FixedString128Bytes and another string are equal.

Declaration
public static bool operator ==(in FixedString128Bytes a, in FixedString512Bytes b)
Parameters
Type Name Description
FixedString128Bytes a

A FixedString128Bytes to compare for equality.
FixedString512Bytes b

A FixedString512Bytes to compare for equality.
Returns
Type Description
bool

True if the two strings are equal.
Remarks

Two strings are equal if they have equal length and all their characters match.

operator ==(in FixedString128Bytes, in FixedString64Bytes)

Returns true if a FixedString128Bytes and another string are equal.

Declaration
public static bool operator ==(in FixedString128Bytes a, in FixedString64Bytes b)
Parameters
Type Name Description
FixedString128Bytes a

A FixedString128Bytes to compare for equality.
FixedString64Bytes b

A FixedString64Bytes to compare for equality.
Returns
Type Description
bool

True if the two strings are equal.
Remarks

Two strings are equal if they have equal length and all their characters match.

implicit operator FixedString128Bytes(string)

Returns a new FixedString128Bytes that is a copy of another string.

Declaration
[ExcludeFromBurstCompatTesting("Takes managed string")]
public static implicit operator FixedString128Bytes(string b)
Parameters
Type Name Description
string b

A string to copy.
Returns
Type Description
FixedString128Bytes

A new FixedString128Bytes that is a copy of another string.
Exceptions
Type Condition
ArgumentException

Thrown if the string to copy's length exceeds the capacity of FixedString128Bytes.

implicit operator FixedString4096Bytes(in FixedString128Bytes)

Returns a new FixedString4096Bytes that is a copy of another string.

Declaration
public static implicit operator FixedString4096Bytes(in FixedString128Bytes fs)
Parameters
Type Name Description
FixedString128Bytes fs

A FixedString128Bytes to copy.
Returns
Type Description
FixedString4096Bytes

A new FixedString4096Bytes that is a copy of the other string.
Exceptions
Type Condition
ArgumentException

Thrown if the string to copy's length exceeds the capacity of FixedString4096Bytes.

implicit operator FixedString512Bytes(in FixedString128Bytes)

Returns a new FixedString512Bytes that is a copy of another string.

Declaration
public static implicit operator FixedString512Bytes(in FixedString128Bytes fs)
Parameters
Type Name Description
FixedString128Bytes fs

A FixedString128Bytes to copy.
Returns
Type Description
FixedString512Bytes

A new FixedString512Bytes that is a copy of the other string.
Exceptions
Type Condition
ArgumentException

Thrown if the string to copy's length exceeds the capacity of FixedString512Bytes.

operator !=(in FixedString128Bytes, in FixedString128Bytes)

Returns true if a FixedString128Bytes and another string are unequal.

Declaration
public static bool operator !=(in FixedString128Bytes a, in FixedString128Bytes b)
Parameters
Type Name Description
FixedString128Bytes a

A FixedString128Bytes to compare for inequality.
FixedString128Bytes b

A FixedString128Bytes to compare for inequality.
Returns
Type Description
bool

True if the two strings are unequal.
Remarks

Two strings are equal if they have equal length and all their characters match.

operator !=(in FixedString128Bytes, in FixedString32Bytes)

Returns true if a FixedString128Bytes and another string are unequal.

Declaration
public static bool operator !=(in FixedString128Bytes a, in FixedString32Bytes b)
Parameters
Type Name Description
FixedString128Bytes a

A FixedString128Bytes to compare for inequality.
FixedString32Bytes b

A FixedString32Bytes to compare for inequality.
Returns
Type Description
bool

True if the two strings are unequal.
Remarks

Two strings are equal if they have equal length and all their characters match.

operator !=(in FixedString128Bytes, in FixedString4096Bytes)

Returns true if a FixedString128Bytes and another string are unequal.

Declaration
public static bool operator !=(in FixedString128Bytes a, in FixedString4096Bytes b)
Parameters
Type Name Description
FixedString128Bytes a

A FixedString128Bytes to compare for inequality.
FixedString4096Bytes b

A FixedString4096Bytes to compare for inequality.
Returns
Type Description
bool

True if the two strings are unequal.
Remarks

Two strings are equal if they have equal length and all their characters match.

operator !=(in FixedString128Bytes, in FixedString512Bytes)

Returns true if a FixedString128Bytes and another string are unequal.

Declaration
public static bool operator !=(in FixedString128Bytes a, in FixedString512Bytes b)
Parameters
Type Name Description
FixedString128Bytes a

A FixedString128Bytes to compare for inequality.
FixedString512Bytes b

A FixedString512Bytes to compare for inequality.
Returns
Type Description
bool

True if the two strings are unequal.
Remarks

Two strings are equal if they have equal length and all their characters match.

operator !=(in FixedString128Bytes, in FixedString64Bytes)

Returns true if a FixedString128Bytes and another string are unequal.

Declaration
public static bool operator !=(in FixedString128Bytes a, in FixedString64Bytes b)
Parameters
Type Name Description
FixedString128Bytes a

A FixedString128Bytes to compare for inequality.
FixedString64Bytes b

A FixedString64Bytes to compare for inequality.
Returns
Type Description
bool

True if the two strings are unequal.
Remarks

Two strings are equal if they have equal length and all their characters match.

Implements

Extension Methods