Struct HeapString

An unmanaged, allocated, mutable, resizable UTF-8 string.

Namespace: Unity.Collections

Syntax

public struct HeapString : INativeList<byte>, IIndexable<byte>, IDisposable, IUTF8Bytes, IComparable<String>, IEquatable<String>, IComparable<HeapString>, IEquatable<HeapString>, IComparable<FixedString32Bytes>, IEquatable<FixedString32Bytes>, IComparable<FixedString64Bytes>, IEquatable<FixedString64Bytes>, IComparable<FixedString128Bytes>, IEquatable<FixedString128Bytes>, IComparable<FixedString512Bytes>, IEquatable<FixedString512Bytes>, IComparable<FixedString4096Bytes>, IEquatable<FixedString4096Bytes>

Remarks

The string is always null-terminated, meaning a zero byte always immediately follows the last character.

Constructors

HeapString(Allocator)

Initializes and returns an instance of HeapString with an initial capacity of 128 bytes.

Declaration

public HeapString(Allocator allocator)

Parameters

Type	Name	Description
Allocator	allocator	The allocator to use.

HeapString(String, Allocator)

Initializes and returns an instance of HeapString with the characters copied from another string.

Declaration

public HeapString(String source, Allocator allocator)

Parameters

Type	Name	Description
String	source	A string to copy characters from.
Allocator	allocator	The allocator to use.

HeapString(Int32, Allocator)

Initializes and returns an instance of HeapString with a specified initial capacity.

Declaration

public HeapString(int capacity, Allocator allocator)

Parameters

Type	Name	Description
Int32	capacity	The initial capacity in bytes.
Allocator	allocator	The allocator to use.

HeapString(FixedString128Bytes, Allocator)

Initializes and returns an instance of HeapString with the characters copied from another string.

Declaration

public HeapString(in FixedString128Bytes source, Allocator allocator)

Parameters

Type	Name	Description
FixedString128Bytes	source	A string to copy characters from.
Allocator	allocator	The allocator to use.

HeapString(FixedString32Bytes, Allocator)

Initializes and returns an instance of HeapString with the characters copied from another string.

Declaration

public HeapString(in FixedString32Bytes source, Allocator allocator)

Parameters

Type	Name	Description
FixedString32Bytes	source	A string to copy characters from.
Allocator	allocator	The allocator to use.

HeapString(FixedString4096Bytes, Allocator)

Initializes and returns an instance of HeapString with the characters copied from another string.

Declaration

public HeapString(in FixedString4096Bytes source, Allocator allocator)

Parameters

Type	Name	Description
FixedString4096Bytes	source	A string to copy characters from.
Allocator	allocator	The allocator to use.

HeapString(FixedString512Bytes, Allocator)

Initializes and returns an instance of HeapString with the characters copied from another string.

Declaration

public HeapString(in FixedString512Bytes source, Allocator allocator)

Parameters

Type	Name	Description
FixedString512Bytes	source	A string to copy characters from.
Allocator	allocator	The allocator to use.

HeapString(FixedString64Bytes, Allocator)

Initializes and returns an instance of HeapString with the characters copied from another string.

Declaration

public HeapString(in FixedString64Bytes source, Allocator allocator)

Parameters

Type	Name	Description
FixedString64Bytes	source	A string to copy characters from.
Allocator	allocator	The allocator to use.

Properties

Capacity

The current capacity of this string.

Declaration

public int Capacity { get; set; }

Property Value

Type	Description
Int32	The current capacity of the string.

Implements

INativeList<T>.Capacity

Remarks

The null-terminator byte is not included in the Capacity, so the string's character buffer is Capacity + 1 in size.

IsCreated

Whether this string's character buffer has been allocated and not yet deallocated.

Declaration

public bool IsCreated { get; }

Property Value

Type	Description
Boolean	Whether this string's character buffer has been allocated and not yet deallocated.

IsEmpty

Whether this string has no characters.

Declaration

public bool IsEmpty { get; }

Property Value

Type	Description
Boolean	True if this string has no characters.

Implements

INativeList<T>.IsEmpty

IUTF8Bytes.IsEmpty

Item[Int32]

The byte at an index.

Declaration

public byte this[int index] { get; set; }

Parameters

Type	Name	Description
Int32	index	A zero-based byte index.

Property Value

Type	Description
Byte	The byte at the index.

Implements

INativeList<T>.Item[Int32]

Length

The current length in bytes of this string.

Declaration

public int Length { get; set; }

Property Value

Type	Description
Int32	The current length in bytes of the UTF-8 encoded string.

Implements

IIndexable<T>.Length

Remarks

The length does not include the null terminator byte.

Value

A copy of this string as a managed string.

Declaration

public string Value { get; }

Property Value

Type	Description
String	A copy of this string as a managed string.

Remarks

For internal use only. Use ToString() instead.

Methods

Add(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.

Clear()

Sets the length to 0.

Declaration

public void Clear()

Implements

INativeList<T>.Clear()

CompareTo(String)

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

Declaration

public int CompareTo(String other)

Parameters

Type	Name	Description
String	other	Another string to compare with.

Returns

Type	Description
Int32	A number denoting the lexicographical sort order of this string relative to the other string: 0 denotes 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(FixedString128Bytes)

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

Declaration

public int CompareTo(FixedString128Bytes other)

Parameters

Type	Name	Description
FixedString128Bytes	other	Another string to compare with.

Returns

Type	Description
Int32	A number denoting the lexicographical sort order of this string relative to the other string: 0 denotes 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	Another string to compare with.

Returns

Type	Description
Int32	A number denoting the lexicographical sort order of this string relative to the other string: 0 denotes 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	Another string to compare with.

Returns

Type	Description
Int32	A number denoting the lexicographical sort order of this string relative to the other string: 0 denotes 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	Another string to compare with.

Returns

Type	Description
Int32	A number denoting the lexicographical sort order of this string relative to the other string: 0 denotes 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	Another string to compare with.

Returns

Type	Description
Int32	A number denoting the lexicographical sort order of this string relative to the other string: 0 denotes 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(HeapString)

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

Declaration

public int CompareTo(HeapString other)

Parameters

Type	Name	Description
HeapString	other	Another string to compare with.

Returns

Type	Description
Int32	A number denoting the lexicographical sort order of this string relative to the other string: 0 denotes 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.

Dispose()

Releases all resources (memory and safety handles).

Declaration

public void Dispose()

ElementAt(Int32)

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

Declaration

public 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

IIndexable<T>.ElementAt(Int32)

Remarks

Deallocating or reallocating this string's character buffer makes the reference invalid.

Equals(String)

Returns true if this string and another are equal.

Declaration

public bool Equals(String other)

Parameters

Type	Name	Description
String	other	Another string to compare with.

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(Object)

Returns true if this string and another object are equal.

Declaration

public override bool Equals(object other)

Parameters

Type	Name	Description
Object	other	Another string to compare with.

Returns

Type	Description
Boolean	True if this string and the object are equal.

Remarks

For the object to be equal, it must itself be a managed string, HeapString, or FixedStringNBytes.

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

Equals(FixedString128Bytes)

Returns true if this string and another are equal.

Declaration

public bool Equals(FixedString128Bytes other)

Parameters

Type	Name	Description
FixedString128Bytes	other	Another string to compare with.

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 are equal.

Declaration

public bool Equals(FixedString32Bytes other)

Parameters

Type	Name	Description
FixedString32Bytes	other	Another string to compare with.

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 are equal.

Declaration

public bool Equals(FixedString4096Bytes other)

Parameters

Type	Name	Description
FixedString4096Bytes	other	Another string to compare with.

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 are equal.

Declaration

public bool Equals(FixedString512Bytes other)

Parameters

Type	Name	Description
FixedString512Bytes	other	Another string to compare with.

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 are equal.

Declaration

public bool Equals(FixedString64Bytes other)

Parameters

Type	Name	Description
FixedString64Bytes	other	Another string to compare with.

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(HeapString)

Returns true if this string and another are equal.

Declaration

public bool Equals(HeapString other)

Parameters

Type	Name	Description
HeapString	other	Another string to compare with.

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 the HeapString.

Declaration

public HeapString.Enumerator GetEnumerator()

Returns

Type	Description
HeapString.Enumerator	An enumerator for iterating over the characters of the HeapString.

GetHashCode()

Returns a hash code of this string.

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32	A hash code of this string.

Remarks

The hash code is an integer that is always the same for two equal strings but (very likely) different for two unequal strings.

GetUnsafePtr()

Returns a pointer to this string's character buffer.

Declaration

public byte *GetUnsafePtr()

Returns

Type	Description
Byte*	A pointer to this string's character buffer.

Implements

IUTF8Bytes.GetUnsafePtr()

Remarks

The pointer is made invalid by operations that reallocate the character buffer, such as setting Capacity.

ToString()

Returns a managed string copy of this string.

Declaration

public override String ToString()

Returns

Type	Description
String	A managed string copy of this string.

TryResize(Int32, NativeArrayOptions)

Attempt to set the length in bytes of this string.

Declaration

public bool TryResize(int newLength, NativeArrayOptions clearOptions = null)

Parameters

Type	Name	Description
Int32	newLength	The new length in bytes of the string.
NativeArrayOptions	clearOptions	Whether any bytes added should be zeroed out.

Returns

Type	Description
Boolean	Always true.

Implements

IUTF8Bytes.TryResize(Int32, NativeArrayOptions)

Operators

Equality(HeapString, FixedString128Bytes)

Returns true if two strings are equal.

Declaration

public static bool operator ==(in HeapString a, in FixedString128Bytes b)

Parameters

Type	Name	Description
HeapString	a	A string to compare.
FixedString128Bytes	b	Another string to compare.

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(HeapString, FixedString32Bytes)

Returns true if two strings are equal.

Declaration

public static bool operator ==(in HeapString a, in FixedString32Bytes b)

Parameters

Type	Name	Description
HeapString	a	A string to compare.
FixedString32Bytes	b	Another string to compare.

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(HeapString, FixedString4096Bytes)

Returns true if two strings are equal.

Declaration

public static bool operator ==(in HeapString a, in FixedString4096Bytes b)

Parameters

Type	Name	Description
HeapString	a	A string to compare.
FixedString4096Bytes	b	Another string to compare.

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(HeapString, FixedString512Bytes)

Returns true if two strings are equal.

Declaration

public static bool operator ==(in HeapString a, in FixedString512Bytes b)

Parameters

Type	Name	Description
HeapString	a	A string to compare.
FixedString512Bytes	b	Another string to compare.

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(HeapString, FixedString64Bytes)

Returns true if two strings are equal.

Declaration

public static bool operator ==(in HeapString a, in FixedString64Bytes b)

Parameters

Type	Name	Description
HeapString	a	A string to compare.
FixedString64Bytes	b	Another string to compare.

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.

Inequality(HeapString, FixedString128Bytes)

Returns true if two strings are unequal.

Declaration

public static bool operator !=(in HeapString a, in FixedString128Bytes b)

Parameters

Type	Name	Description
HeapString	a	A string to compare.
FixedString128Bytes	b	Another string to compare.

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(HeapString, FixedString32Bytes)

Returns true if two strings are unequal.

Declaration

public static bool operator !=(in HeapString a, in FixedString32Bytes b)

Parameters

Type	Name	Description
HeapString	a	A string to compare.
FixedString32Bytes	b	Another string to compare.

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(HeapString, FixedString4096Bytes)

Returns true if two strings are unequal.

Declaration

public static bool operator !=(in HeapString a, in FixedString4096Bytes b)

Parameters

Type	Name	Description
HeapString	a	A string to compare.
FixedString4096Bytes	b	Another string to compare.

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(HeapString, FixedString512Bytes)

Returns true if two strings are unequal.

Declaration

public static bool operator !=(in HeapString a, in FixedString512Bytes b)

Parameters

Type	Name	Description
HeapString	a	A string to compare.
FixedString512Bytes	b	Another string to compare.

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(HeapString, FixedString64Bytes)

Returns true if two strings are unequal.

Declaration

public static bool operator !=(in HeapString a, in FixedString64Bytes b)

Parameters

Type	Name	Description
HeapString	a	A string to compare.
FixedString64Bytes	b	Another string to compare.

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.