Struct HeapString
An unmanaged string in UTF-8 format that maintains a variable-length allocated inner buffer. The string is guaranteed to be null-terminated, at the byte at the current Length offset. This structure is a native collection, and as such requires creating with an allocator and requires being disposed.
Namespace: Unity.Collections
Syntax
public struct HeapString : INativeList<byte>, IDisposable, IUTF8Bytes, IComparable<string>, IEquatable<string>, IComparable<HeapString>, IEquatable<HeapString>, IComparable<FixedString32>, IEquatable<FixedString32>, IComparable<FixedString64>, IEquatable<FixedString64>, IComparable<FixedString128>, IEquatable<FixedString128>, IComparable<FixedString512>, IEquatable<FixedString512>, IComparable<FixedString4096>, IEquatable<FixedString4096>Constructors
HeapString(Int32, Allocator)
Construct an empty HeapString with the given 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 for the underlying memory |
HeapString(String, Allocator)
Construct a HeapString from a System.String object.
Declaration
public HeapString(string source, Allocator allocator)Parameters
| Type | Name | Description |
|---|---|---|
| String | source | The System.String object to construct this HeapString with |
| Allocator | allocator | the Allocator to use for the underlying memory |
HeapString(Allocator)
Construct an empty HeapString with a default capacity of 512 bytes.
Declaration
public HeapString(Allocator allocator)Parameters
| Type | Name | Description |
|---|---|---|
| Allocator | allocator | the Allocator to use for the underlying memory |
HeapString(FixedString128, Allocator)
Construct a HeapString by copying from another FixedString source.
Declaration
public HeapString(in FixedString128 source, Allocator allocator)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString128 | source | |
| Allocator | allocator | the Allocator to use for the underlying memory |
HeapString(FixedString32, Allocator)
Construct a HeapString by copying from another FixedString source.
Declaration
public HeapString(in FixedString32 source, Allocator allocator)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString32 | source | |
| Allocator | allocator | the Allocator to use for the underlying memory |
HeapString(FixedString4096, Allocator)
Construct a HeapString by copying from another FixedString source.
Declaration
public HeapString(in FixedString4096 source, Allocator allocator)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString4096 | source | |
| Allocator | allocator | the Allocator to use for the underlying memory |
HeapString(FixedString512, Allocator)
Construct a HeapString by copying from another FixedString source.
Declaration
public HeapString(in FixedString512 source, Allocator allocator)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString512 | source | |
| Allocator | allocator | the Allocator to use for the underlying memory |
HeapString(FixedString64, Allocator)
Construct a HeapString by copying from another FixedString source.
Declaration
public HeapString(in FixedString64 source, Allocator allocator)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString64 | source | |
| Allocator | allocator | the Allocator to use for the underlying memory |
Properties
Capacity
The current capacity of this HeapString. Setting this value may cause the underlying buffer to be reallocated.
Declaration
public int Capacity { get; set; }Property Value
| Type | Description |
|---|---|
| Int32 |
Implements
IsCreated
Reports whether memory for the container is allocated.
Declaration
public bool IsCreated { get; }Property Value
| Type | Description |
|---|---|
| Boolean | True if this container object's internal storage has been allocated. |
Remarks
Note that the container storage is not created if you use the default constructor. You must specify at least an allocation type to construct a usable container.
Warning: the IsCreated property can't be used to determine whether a copy of a container is still valid.
If you dispose any copy of the container, the container storage is deallocated. However, the properties of
the other copies of the container (including the original) are not updated. As a result the IsCreated property
of the copies still return true even though the container storage has been deallocated.
Accessing the data of a native container that has been disposed throws a InvalidOperationException exception.
IsEmpty
Reports whether container is empty.
Declaration
public bool IsEmpty { get; }Property Value
| Type | Description |
|---|---|
| Boolean | True if this container empty. |
Implements
Item[Int32]
Return the byte at the given byte (not character) index. The index must be in the range of [0..Length)
Declaration
public byte this[int index] { get; set; }Parameters
| Type | Name | Description |
|---|---|---|
| Int32 | index |
Property Value
| Type | Description |
|---|---|
| Byte |
Implements
Length
The current length of the UTF-8 encoded string, in bytes. The string is guaranteed to be null-terminated. The length value does not include the null terminating byte. It is valid to read the null byte at the Length position when accessing this data by raw pointer.
Declaration
public int Length { get; set; }Property Value
| Type | Description |
|---|---|
| Int32 |
Implements
Value
A property in order to display the value in Unity.Properties generated UI.
Declaration
public string Value { get; }Property Value
| Type | Description |
|---|---|
| String |
Methods
Add(Byte)
Append the given byte value to this string. The string will remain null-terminated after the new byte. Appending an invalid UTF-8 sequence will cause the contents of this string to be invalid when converted to UTF-16 or UCS-2. No validation of the appended bytes is done.
Declaration
public void Add(in byte value)Parameters
| Type | Name | Description |
|---|---|---|
| Byte | value | The byte to append. |
Clear()
Clear this string by setting its Length to 0.
Declaration
public void Clear()Implements
CompareTo(String)
Compare this HeapString with a System.String in terms of lexigraphical order, and return which of the two strings would come first if sorted.
Declaration
public int CompareTo(string other)Parameters
| Type | Name | Description |
|---|---|---|
| String | other | The System.String to compare with |
Returns
| Type | Description |
|---|---|
| Int32 | -1 if this HeapString would appear first if sorted, 0 if they are identical, or 1 if the other System.String would appear first if sorted. |
CompareTo(FixedString128)
Compare this HeapString with a FixedString128 in terms of lexigraphical order, and return which of the two strings would come first if sorted.
Declaration
public int CompareTo(FixedString128 other)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString128 | other | The FixedString to compare with |
Returns
| Type | Description |
|---|---|
| Int32 | -1 if this HeapString would appear first if sorted, 0 if they are identical, or 1 if the other FixedString128 would appear first if sorted. |
CompareTo(FixedString32)
Compare this HeapString with a FixedString32 in terms of lexigraphical order, and return which of the two strings would come first if sorted.
Declaration
public int CompareTo(FixedString32 other)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString32 | other | The FixedString to compare with |
Returns
| Type | Description |
|---|---|
| Int32 | -1 if this HeapString would appear first if sorted, 0 if they are identical, or 1 if the other FixedString32 would appear first if sorted. |
CompareTo(FixedString4096)
Compare this HeapString with a FixedString4096 in terms of lexigraphical order, and return which of the two strings would come first if sorted.
Declaration
public int CompareTo(FixedString4096 other)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString4096 | other | The FixedString to compare with |
Returns
| Type | Description |
|---|---|
| Int32 | -1 if this HeapString would appear first if sorted, 0 if they are identical, or 1 if the other FixedString4096 would appear first if sorted. |
CompareTo(FixedString512)
Compare this HeapString with a FixedString512 in terms of lexigraphical order, and return which of the two strings would come first if sorted.
Declaration
public int CompareTo(FixedString512 other)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString512 | other | The FixedString to compare with |
Returns
| Type | Description |
|---|---|
| Int32 | -1 if this HeapString would appear first if sorted, 0 if they are identical, or 1 if the other FixedString512 would appear first if sorted. |
CompareTo(FixedString64)
Compare this HeapString with a FixedString64 in terms of lexigraphical order, and return which of the two strings would come first if sorted.
Declaration
public int CompareTo(FixedString64 other)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString64 | other | The FixedString to compare with |
Returns
| Type | Description |
|---|---|
| Int32 | -1 if this HeapString would appear first if sorted, 0 if they are identical, or 1 if the other FixedString64 would appear first if sorted. |
CompareTo(HeapString)
Compare this HeapString with another in terms of lexigraphical order, and return which of the two strings would come first if sorted.
Declaration
public int CompareTo(HeapString other)Parameters
| Type | Name | Description |
|---|---|---|
| HeapString | other | The HeapString to compare with |
Returns
| Type | Description |
|---|---|
| Int32 | negative value if this HeapString would appear first if sorted, 0 if they are identical, or positive value if the other HeapString would appear first if sorted. |
Dispose()
Dispose this HeapString's underlying allocation.
Declaration
public void Dispose()ElementAt(Int32)
Return a ref to the the byte at the given byte (not character) index. The index must be in the range of [0..Length). The ref byte is a direct reference into this HeapString, and is only valid while this HeapString's underlying allocation doesn't change.
Declaration
public byte ElementAt(int index)Parameters
| Type | Name | Description |
|---|---|---|
| Int32 | index | The byte index to access |
Returns
| Type | Description |
|---|---|
| Byte | A ref byte for the requested index |
Implements
Equals(Object)
Determines whether a HeapString has the same value as some other object.
Declaration
public override bool Equals(object obj)Parameters
| Type | Name | Description |
|---|---|---|
| Object | obj | The object to compare for equality |
Returns
| Type | Description |
|---|---|
| Boolean |
Overrides
Equals(String)
Compare this HeapString with a System.String, and return whether they contain the same string or not.
Declaration
public bool Equals(string other)Parameters
| Type | Name | Description |
|---|---|---|
| String | other | The System.String to compare with |
Returns
| Type | Description |
|---|---|
| Boolean | true if they are equal, or false if they are not. |
Equals(FixedString128)
Declaration
public bool Equals(FixedString128 other)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString128 | other |
Returns
| Type | Description |
|---|---|
| Boolean |
Equals(FixedString32)
Declaration
public bool Equals(FixedString32 other)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString32 | other |
Returns
| Type | Description |
|---|---|
| Boolean |
Equals(FixedString4096)
Declaration
public bool Equals(FixedString4096 other)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString4096 | other |
Returns
| Type | Description |
|---|---|
| Boolean |
Equals(FixedString512)
Declaration
public bool Equals(FixedString512 other)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString512 | other |
Returns
| Type | Description |
|---|---|
| Boolean |
Equals(FixedString64)
Declaration
public bool Equals(FixedString64 other)Parameters
| Type | Name | Description |
|---|---|---|
| FixedString64 | other |
Returns
| Type | Description |
|---|---|
| Boolean |
Equals(HeapString)
Compare this HeapString with another, and return whether they contain the same string or not.
Declaration
public bool Equals(HeapString other)Parameters
| Type | Name | Description |
|---|---|---|
| HeapString | other | The HeapString to compare with |
Returns
| Type | Description |
|---|---|
| Boolean | true if they are equal, or false if they are not. |
GetEnumerator()
Returns an enumerator that iterates through a container.
Declaration
public HeapString.Enumerator GetEnumerator()Returns
| Type | Description |
|---|---|
| HeapString.Enumerator | An IEnumerator object that can be used to iterate through the container. |
GetHashCode()
Compute a hash code of this HeapString: an integer that is likely to be different for two HeapString, if their contents are different.
Declaration
public override int GetHashCode()Returns
| Type | Description |
|---|---|
| Int32 | A hash code of this HeapString |
Overrides
GetUnsafePtr()
Returns a pointer to the underlying byte stream. This pointer will become invalid if the underlying allocation is changed, such as by changing the Capacity or adding any data to the HeapString.
Declaration
public byte *GetUnsafePtr()Returns
| Type | Description |
|---|---|
| Byte* |
Implements
ToString()
Convert this HeapString to a System.String.
Declaration
public override string ToString()Returns
| Type | Description |
|---|---|
| String | A System.String with a copy of this HeapString |
Overrides
TryResize(Int32, NativeArrayOptions)
Attempt to set the length of the string, in UTF-8 bytes.
Declaration
public bool TryResize(int newLength, NativeArrayOptions clearOptions = NativeArrayOptions.ClearMemory)Parameters
| Type | Name | Description |
|---|---|---|
| Int32 | newLength | The new length of the string |
| NativeArrayOptions | clearOptions | Whether the new memory should be initialized or not |
Returns
| Type | Description |
|---|---|
| Boolean | Whether the resize was successful. |
Implements
Operators
Equality(HeapString, FixedString128)
Declaration
public static bool operator ==(in HeapString a, in FixedString128 b)Parameters
| Type | Name | Description |
|---|---|---|
| HeapString | a | |
| FixedString128 | b |
Returns
| Type | Description |
|---|---|
| Boolean |
Equality(HeapString, FixedString32)
Declaration
public static bool operator ==(in HeapString a, in FixedString32 b)Parameters
| Type | Name | Description |
|---|---|---|
| HeapString | a | |
| FixedString32 | b |
Returns
| Type | Description |
|---|---|
| Boolean |
Equality(HeapString, FixedString4096)
Declaration
public static bool operator ==(in HeapString a, in FixedString4096 b)Parameters
| Type | Name | Description |
|---|---|---|
| HeapString | a | |
| FixedString4096 | b |
Returns
| Type | Description |
|---|---|
| Boolean |
Equality(HeapString, FixedString512)
Declaration
public static bool operator ==(in HeapString a, in FixedString512 b)Parameters
| Type | Name | Description |
|---|---|---|
| HeapString | a | |
| FixedString512 | b |
Returns
| Type | Description |
|---|---|
| Boolean |
Equality(HeapString, FixedString64)
Declaration
public static bool operator ==(in HeapString a, in FixedString64 b)Parameters
| Type | Name | Description |
|---|---|---|
| HeapString | a | |
| FixedString64 | b |
Returns
| Type | Description |
|---|---|
| Boolean |
Inequality(HeapString, FixedString128)
Declaration
public static bool operator !=(in HeapString a, in FixedString128 b)Parameters
| Type | Name | Description |
|---|---|---|
| HeapString | a | |
| FixedString128 | b |
Returns
| Type | Description |
|---|---|
| Boolean |
Inequality(HeapString, FixedString32)
Declaration
public static bool operator !=(in HeapString a, in FixedString32 b)Parameters
| Type | Name | Description |
|---|---|---|
| HeapString | a | |
| FixedString32 | b |
Returns
| Type | Description |
|---|---|
| Boolean |
Inequality(HeapString, FixedString4096)
Declaration
public static bool operator !=(in HeapString a, in FixedString4096 b)Parameters
| Type | Name | Description |
|---|---|---|
| HeapString | a | |
| FixedString4096 | b |
Returns
| Type | Description |
|---|---|
| Boolean |
Inequality(HeapString, FixedString512)
Declaration
public static bool operator !=(in HeapString a, in FixedString512 b)Parameters
| Type | Name | Description |
|---|---|---|
| HeapString | a | |
| FixedString512 | b |
Returns
| Type | Description |
|---|---|
| Boolean |
Inequality(HeapString, FixedString64)
Declaration
public static bool operator !=(in HeapString a, in FixedString64 b)Parameters
| Type | Name | Description |
|---|---|---|
| HeapString | a | |
| FixedString64 | b |
Returns
| Type | Description |
|---|---|
| Boolean |