Struct NativeText

An unmanaged, mutable, resizable UTF-8 string.

Namespace: Unity.Collections
Syntax
[NativeContainer]
public struct NativeText : INativeList<byte>, IIndexable<byte>, INativeDisposable, IDisposable, IUTF8Bytes, IComparable<string>, IEquatable<string>, IComparable<NativeText>, IEquatable<NativeText>, 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

NativeText(Int32, Allocator)

Initializes and returns an instance of NativeText.

Declaration
public NativeText(int capacity, Allocator allocator)
Parameters
Type Name Description
Int32 capacity

The initial capacity in bytes.
Allocator allocator

The allocator to use.

NativeText(Int32, AllocatorManager.AllocatorHandle)

Initializes and returns an instance of NativeText.

Declaration
public NativeText(int capacity, AllocatorManager.AllocatorHandle allocator)
Parameters
Type Name Description
Int32 capacity

The initial capacity in bytes.
AllocatorManager.AllocatorHandle allocator

The allocator to use.

NativeText(String, Allocator)

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

Declaration
[ExcludeFromBurstCompatTesting("Takes managed string")]
public NativeText(string source, Allocator allocator)
Parameters
Type Name Description
String source

A string to copy characters from.
Allocator allocator

The allocator to use.

NativeText(String, AllocatorManager.AllocatorHandle)

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

Declaration
[ExcludeFromBurstCompatTesting("Takes managed string")]
public NativeText(string source, AllocatorManager.AllocatorHandle allocator)
Parameters
Type Name Description
String source

A string to copy characters from.
AllocatorManager.AllocatorHandle allocator

The allocator to use.

NativeText(Allocator)

Initializes and returns an instance of NativeText with an initial capacity of 512 bytes.

Declaration
public NativeText(Allocator allocator)
Parameters
Type Name Description
Allocator allocator

The allocator to use.

NativeText(AllocatorManager.AllocatorHandle)

Initializes and returns an instance of NativeText with an initial capacity of 512 bytes.

Declaration
public NativeText(AllocatorManager.AllocatorHandle allocator)
Parameters
Type Name Description
AllocatorManager.AllocatorHandle allocator

The allocator to use.

NativeText(in FixedString128Bytes, Allocator)

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

Declaration
public NativeText(in FixedString128Bytes source, Allocator allocator)
Parameters
Type Name Description
FixedString128Bytes source

A string to copy characters from.
Allocator allocator

The allocator to use.

NativeText(in FixedString128Bytes, AllocatorManager.AllocatorHandle)

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

Declaration
public NativeText(in FixedString128Bytes source, AllocatorManager.AllocatorHandle allocator)
Parameters
Type Name Description
FixedString128Bytes source

A string to copy characters from.
AllocatorManager.AllocatorHandle allocator

The allocator to use.

NativeText(in FixedString32Bytes, Allocator)

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

Declaration
public NativeText(in FixedString32Bytes source, Allocator allocator)
Parameters
Type Name Description
FixedString32Bytes source

A string to copy characters from.
Allocator allocator

The allocator to use.

NativeText(in FixedString32Bytes, AllocatorManager.AllocatorHandle)

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

Declaration
public NativeText(in FixedString32Bytes source, AllocatorManager.AllocatorHandle allocator)
Parameters
Type Name Description
FixedString32Bytes source

A string to copy characters from.
AllocatorManager.AllocatorHandle allocator

The allocator to use.

NativeText(in FixedString4096Bytes, Allocator)

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

Declaration
public NativeText(in FixedString4096Bytes source, Allocator allocator)
Parameters
Type Name Description
FixedString4096Bytes source

A string to copy characters from.
Allocator allocator

The allocator to use.

NativeText(in FixedString4096Bytes, AllocatorManager.AllocatorHandle)

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

Declaration
public NativeText(in FixedString4096Bytes source, AllocatorManager.AllocatorHandle allocator)
Parameters
Type Name Description
FixedString4096Bytes source

A string to copy characters from.
AllocatorManager.AllocatorHandle allocator

The allocator to use.

NativeText(in FixedString512Bytes, Allocator)

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

Declaration
public NativeText(in FixedString512Bytes source, Allocator allocator)
Parameters
Type Name Description
FixedString512Bytes source

A string to copy characters from.
Allocator allocator

The allocator to use.

NativeText(in FixedString512Bytes, AllocatorManager.AllocatorHandle)

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

Declaration
public NativeText(in FixedString512Bytes source, AllocatorManager.AllocatorHandle allocator)
Parameters
Type Name Description
FixedString512Bytes source

A string to copy characters from.
AllocatorManager.AllocatorHandle allocator

The allocator to use.

NativeText(in FixedString64Bytes, Allocator)

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

Declaration
public NativeText(in FixedString64Bytes source, Allocator allocator)
Parameters
Type Name Description
FixedString64Bytes source

A string to copy characters from.
Allocator allocator

The allocator to use.

NativeText(in FixedString64Bytes, AllocatorManager.AllocatorHandle)

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

Declaration
public NativeText(in FixedString64Bytes source, AllocatorManager.AllocatorHandle allocator)
Parameters
Type Name Description
FixedString64Bytes source

A string to copy characters from.
AllocatorManager.AllocatorHandle allocator

The allocator to use.

Properties

Capacity

The current capacity in bytes of this string.

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

The current capacity in bytes of the string.
Implements
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 readonly 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 readonly bool IsEmpty { get; }
Property Value
Type Description
Boolean

True if this string has no characters or the string has not been constructed.
Implements
Exceptions
Type Condition
NotSupportedException

Thrown if ENABLE_UNITY_COLLECTIONS_CHECKS is defined and a write is attempted.

Item[Int32]

The byte at an index. Note that writing to a NativeText.Readonly is not supported; the setter of this property throws when safety checks are enabled.

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
Exceptions
Type Condition
IndexOutOfRangeException

Thrown if the index is out of bounds.

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
Remarks

The length does not include the null terminator byte.

Value

A copy of this string as a managed string.

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

AsReadOnly()

Returns a readonly version of this NativeText instance.

Declaration
public NativeText.ReadOnly AsReadOnly()
Returns
Type Description
NativeText.ReadOnly

ReadOnly instance for this.
Remarks

ReadOnly containers point to the same underlying data as the NativeText it is made from. Note while ReadOnly contains methods that would write to the string data these methods will perform no writes and/or throw a NotSupportedException.

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

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

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

Declaration
public int CompareTo(NativeText other)
Parameters
Type Name Description
NativeText 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(NativeText.ReadOnly)

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

Declaration
public int CompareTo(NativeText.ReadOnly other)
Parameters
Type Name Description
NativeText.ReadOnly 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()

Dispose(JobHandle)

Creates and schedules a job that releases all resources (memory and safety handles) of this NativeText.

Declaration
public JobHandle Dispose(JobHandle inputDeps)
Parameters
Type Name Description
JobHandle inputDeps

The dependency for the new job.
Returns
Type Description
JobHandle

The handle of the new job. The job depends upon inputDeps and releases all resources (memory and safety handles) of this NativeText.
Implements

ElementAt(Int32)

Returns a reference to the 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
Remarks

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

Exceptions
Type Condition
IndexOutOfRangeException

Thrown if the index is out of bounds.

Equals(Object)

Returns true if this string and another object are equal.

Declaration
[ExcludeFromBurstCompatTesting("Takes managed object")]
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.
Overrides
Remarks

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

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

Equals(String)

Returns true if this string and another are equal.

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

Returns true if this string and another are equal.

Declaration
public bool Equals(NativeText other)
Parameters
Type Name Description
NativeText 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(NativeText.ReadOnly)

Returns true if this string and another are equal.

Declaration
public bool Equals(NativeText.ReadOnly other)
Parameters
Type Name Description
NativeText.ReadOnly 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 NativeText.

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

An enumerator for iterating over the characters of the NativeText.

GetHashCode()

Returns a hash code of this string.

Declaration
public override int GetHashCode()
Returns
Type Description
Int32

A hash code of this string.
Overrides
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
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
[ExcludeFromBurstCompatTesting("Returns managed string")]
public override string ToString()
Returns
Type Description
String

A managed string copy of this string.
Overrides

TryResize(Int32, NativeArrayOptions)

Attempt to set the length in bytes of this string.

Declaration
public bool TryResize(int newLength, NativeArrayOptions clearOptions = NativeArrayOptions.ClearMemory)
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

Operators

Equality(in NativeText, in FixedString128Bytes)

Returns true if two strings are equal.

Declaration
public static bool operator ==(in NativeText a, in FixedString128Bytes b)
Parameters
Type Name Description
NativeText 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(in NativeText, in FixedString32Bytes)

Returns true if two strings are equal.

Declaration
public static bool operator ==(in NativeText a, in FixedString32Bytes b)
Parameters
Type Name Description
NativeText 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(in NativeText, in FixedString4096Bytes)

Returns true if two strings are equal.

Declaration
public static bool operator ==(in NativeText a, in FixedString4096Bytes b)
Parameters
Type Name Description
NativeText 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(in NativeText, in FixedString512Bytes)

Returns true if two strings are equal.

Declaration
public static bool operator ==(in NativeText a, in FixedString512Bytes b)
Parameters
Type Name Description
NativeText 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(in NativeText, in FixedString64Bytes)

Returns true if two strings are equal.

Declaration
public static bool operator ==(in NativeText a, in FixedString64Bytes b)
Parameters
Type Name Description
NativeText 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(in NativeText, in FixedString128Bytes)

Returns true if two strings are unequal.

Declaration
public static bool operator !=(in NativeText a, in FixedString128Bytes b)
Parameters
Type Name Description
NativeText 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(in NativeText, in FixedString32Bytes)

Returns true if two strings are unequal.

Declaration
public static bool operator !=(in NativeText a, in FixedString32Bytes b)
Parameters
Type Name Description
NativeText 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(in NativeText, in FixedString4096Bytes)

Returns true if two strings are unequal.

Declaration
public static bool operator !=(in NativeText a, in FixedString4096Bytes b)
Parameters
Type Name Description
NativeText 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(in NativeText, in FixedString512Bytes)

Returns true if two strings are unequal.

Declaration
public static bool operator !=(in NativeText a, in FixedString512Bytes b)
Parameters
Type Name Description
NativeText 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(in NativeText, in FixedString64Bytes)

Returns true if two strings are unequal.

Declaration
public static bool operator !=(in NativeText a, in FixedString64Bytes b)
Parameters
Type Name Description
NativeText 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.

Extension Methods