Struct FixedString4096Bytes

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

Namespace: Unity.Collections
Syntax
[Serializable]
public struct FixedString4096Bytes : INativeList<byte>, IIndexable<byte>, IUTF8Bytes, IComparable<string>, IEquatable<string>, IComparable<FixedString32Bytes>, IEquatable<FixedString32Bytes>, IComparable<FixedString64Bytes>, IEquatable<FixedString64Bytes>, IComparable<FixedString128Bytes>, IEquatable<FixedString128Bytes>, IComparable<FixedString512Bytes>, IEquatable<FixedString512Bytes>, IComparable<FixedString4096Bytes>, IEquatable<FixedString4096Bytes>
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 4096 (two length bytes and one null byte).

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

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

FixedString4096Bytes(String)

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

Declaration
[ExcludeFromBurstCompatTesting("Takes managed string")]
public FixedString4096Bytes(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 FixedString4096Bytes.

FixedString4096Bytes(in FixedString128Bytes)

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

Declaration
public FixedString4096Bytes(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 FixedString4096Bytes.

FixedString4096Bytes(in FixedString32Bytes)

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

Declaration
public FixedString4096Bytes(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 FixedString4096Bytes.

FixedString4096Bytes(in FixedString4096Bytes)

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

Declaration
public FixedString4096Bytes(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 FixedString4096Bytes.

FixedString4096Bytes(in FixedString512Bytes)

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

Declaration
public FixedString4096Bytes(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 FixedString4096Bytes.

FixedString4096Bytes(in FixedString64Bytes)

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

Declaration
public FixedString4096Bytes(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 FixedString4096Bytes.

FixedString4096Bytes(in UnsafeText)

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

Declaration
public FixedString4096Bytes(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 FixedString4096Bytes.

FixedString4096Bytes(NativeText.ReadOnly)

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

Declaration
public FixedString4096Bytes(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 FixedString4096Bytes.

FixedString4096Bytes(Unicode.Rune, Int32)

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

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

The Unicode.Rune to repeat.
Int32 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
Int32

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

Does not include the null-terminator byte.

A setter is included for conformity with INativeList<T>, but Capacity is fixed at 4093. Setting the value to anything other than 4093 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 4093.

IsEmpty

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

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

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

Item[Int32]

Returns the byte (not character) at an index.

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

A byte index.
Property Value
Type Description
Byte

The byte at the index.
Implements
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
Int32

The current length in bytes of this string's content.
Implements
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 readonly int UTF8MaxLengthInBytes { get; }
Property Value
Type Description
Int32

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

Value

For internal use only. Use ToString() instead.

Declaration
[CreateProperty]
[ExcludeFromBurstCompatTesting("Returns managed string")]
public readonly string Value { get; }
Property Value
Type Description
String

For internal use only. Use ToString() instead.

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 FixedList4096Bytes<byte> representation of this string.

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

A ref to a FixedListByte4096 representation of the FixedString4096Bytes.
Remarks

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

Clear()

Sets the length to 0.

Declaration
public void Clear()
Implements

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
Int32

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

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

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
Int32

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

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

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
Int32

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

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

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
Int32

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

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

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
Int32

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

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

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
Int32

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

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

ElementAt(Int32)

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

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

A byte index.
Returns
Type Description
Byte

A reference to the byte at the index.
Implements
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
Boolean

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
Boolean

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
Boolean

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
Boolean

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
Boolean

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
Boolean

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
Boolean

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 FixedString4096Bytes.Enumerator GetEnumerator()
Returns
Type Description
FixedString4096Bytes.Enumerator

An enumerator for iterating over the characters of the FixedString4096Bytes.

GetHashCode()

Returns a hash code of this string.

Declaration
public override int GetHashCode()
Returns
Type Description
Int32

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.
Implements
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(Int32, 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
Int32 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
Boolean

True if the new length is valid.
Implements

Operators

Equality(in FixedString4096Bytes, in FixedString128Bytes)

Returns true if a FixedString4096Bytes and another string are equal.

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

A FixedString4096Bytes to compare for equality.
FixedString128Bytes b

A FixedString128Bytes to compare for equality.
Returns
Type Description
Boolean

True if the two strings are equal.
Remarks

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

Equality(in FixedString4096Bytes, in FixedString32Bytes)

Returns true if a FixedString4096Bytes and another string are equal.

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

A FixedString4096Bytes to compare for equality.
FixedString32Bytes b

A FixedString32Bytes to compare for equality.
Returns
Type Description
Boolean

True if the two strings are equal.
Remarks

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

Equality(in FixedString4096Bytes, in FixedString4096Bytes)

Returns true if a FixedString4096Bytes and another string are equal.

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

A FixedString4096Bytes to compare for equality.
FixedString4096Bytes b

A FixedString4096Bytes to compare for equality.
Returns
Type Description
Boolean

True if the two strings are equal.
Remarks

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

Equality(in FixedString4096Bytes, in FixedString512Bytes)

Returns true if a FixedString4096Bytes and another string are equal.

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

A FixedString4096Bytes to compare for equality.
FixedString512Bytes b

A FixedString512Bytes to compare for equality.
Returns
Type Description
Boolean

True if the two strings are equal.
Remarks

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

Equality(in FixedString4096Bytes, in FixedString64Bytes)

Returns true if a FixedString4096Bytes and another string are equal.

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

A FixedString4096Bytes to compare for equality.
FixedString64Bytes b

A FixedString64Bytes to compare for equality.
Returns
Type Description
Boolean

True if the two strings are equal.
Remarks

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

Implicit(String to FixedString4096Bytes)

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

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

A string to copy.
Returns
Type Description
FixedString4096Bytes

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

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

Inequality(in FixedString4096Bytes, in FixedString128Bytes)

Returns true if a FixedString4096Bytes and another string are unequal.

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

A FixedString4096Bytes to compare for inequality.
FixedString128Bytes b

A FixedString128Bytes to compare for inequality.
Returns
Type Description
Boolean

True if the two strings are unequal.
Remarks

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

Inequality(in FixedString4096Bytes, in FixedString32Bytes)

Returns true if a FixedString4096Bytes and another string are unequal.

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

A FixedString4096Bytes to compare for inequality.
FixedString32Bytes b

A FixedString32Bytes to compare for inequality.
Returns
Type Description
Boolean

True if the two strings are unequal.
Remarks

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

Inequality(in FixedString4096Bytes, in FixedString4096Bytes)

Returns true if a FixedString4096Bytes and another string are unequal.

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

A FixedString4096Bytes to compare for inequality.
FixedString4096Bytes b

A FixedString4096Bytes to compare for inequality.
Returns
Type Description
Boolean

True if the two strings are unequal.
Remarks

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

Inequality(in FixedString4096Bytes, in FixedString512Bytes)

Returns true if a FixedString4096Bytes and another string are unequal.

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

A FixedString4096Bytes to compare for inequality.
FixedString512Bytes b

A FixedString512Bytes to compare for inequality.
Returns
Type Description
Boolean

True if the two strings are unequal.
Remarks

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

Inequality(in FixedString4096Bytes, in FixedString64Bytes)

Returns true if a FixedString4096Bytes and another string are unequal.

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

A FixedString4096Bytes to compare for inequality.
FixedString64Bytes b

A FixedString64Bytes to compare for inequality.
Returns
Type Description
Boolean

True if the two strings are unequal.
Remarks

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

Extension Methods