Struct InternedString

Wraps around a string to allow for faster case-insensitive string comparisons while preserving original casing.

Implements
Namespace: UnityEngine.InputSystem.Utilities
Assembly: Unity.InputSystem.dll
Syntax
public struct InternedString : IEquatable<InternedString>, IComparable<InternedString>
Remarks

Unlike string, InternedStrings can be compared with a quick Object.ReferenceEquals comparison and without actually comparing string contents.

Also, unlike string, the representation of an empty and a null string is identical.

Note that all string comparisons using InternedStrings are both case-insensitive and culture-insensitive.

There is a non-zero cost to creating an InternedString. The first time a new unique InternedString is encountered, there may also be a GC heap allocation.

Constructors

InternedString(string)

Initialize the InternedString with the given string. Except if the string is null or empty, this requires an internal lookup (this is the reason the conversion from string to InternedString is not implicit).

Declaration
public InternedString(string text)
Parameters
Type Name Description
string text

A string. Can be null.
Remarks

The InternedString preserves the original casing. Meaning that ToString() will return the string as it was supplied through text. However, comparison between two InternedStrings is still always just a reference comparisons regardless of case and culture.

var lowerCase = new InternedString("text");
var upperCase = new InternedString("TEXT");

// This is still just a quick reference comparison:
if (lowerCase == upperCase)
Debug.Log("True");


// But this prints the strings in their original casing.
Debug.Log(lowerCase);
Debug.Log(upperCase);

Properties

length

Length of the string in characters. Equivalent to string.Length.

Declaration
public int length { get; }
Property Value
Type Description
int

Length of the string.

Methods

CompareTo(InternedString)

Declaration
public int CompareTo(InternedString other)
Parameters
Type Name Description
InternedString other
Returns
Type Description
int

Equals(object)

Compare the InternedString to given object.

Declaration
public override bool Equals(object obj)
Parameters
Type Name Description
object obj

An object. If it is a string, performs a string comparison. If it is an InternedString, performs an InternedString-comparison. Otherwise returns false.
Returns
Type Description
bool

True if the InternedString is equal to obj.
Overrides

Equals(InternedString)

Compare two InternedStrings for equality. They are equal if, ignoring case and culture, their text is equal.

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

Another InternedString.
Returns
Type Description
bool

True if the two InternedStrings are equal.
Remarks

This operation is cheap and does not involve an actual string comparison. Instead, a simple Object.ReferenceEquals comparison is performed.

GetHashCode()

Compute a hash code for the string. Equivalent to string.GetHashCode.

Declaration
public override int GetHashCode()
Returns
Type Description
int

A hash code.
Overrides

IsEmpty()

Whether the string is empty, i.e. has a length of zero. If so, the InternedString corresponds to default(InternedString).

Declaration
public bool IsEmpty()
Returns
Type Description
bool

True if the string is empty.

ToLower()

Return a lower-case version of the string, converted using the invariant culture.

Declaration
public string ToLower()
Returns
Type Description
string

A lower-case version of the string, or null if the string is empty.
Remarks

InternedStrings internally store an upper-case version of the string, so this method incurs a GC heap allocation cost on each call. To normalize strings for case-insensitive comparisons, use ToUpper() instead.

ToString()

Declaration
public override string ToString()
Returns
Type Description
string
Overrides

ToUpper()

Return an upper-case version of the string, converted using the invariant culture.

Declaration
public string ToUpper()
Returns
Type Description
string

An upper-case version of the string, or null if the string is empty.
Remarks

InternedStrings internally always store an upper-case version which means that this method does not incur a GC heap allocation cost. Use this method, rather than ToLower(), when normalizing strings for case-insensitive comparisons.

Operators

operator ==(string, InternedString)

Declaration
public static bool operator ==(string a, InternedString b)
Parameters
Type Name Description
string a
InternedString b
Returns
Type Description
bool

operator ==(InternedString, string)

Declaration
public static bool operator ==(InternedString a, string b)
Parameters
Type Name Description
InternedString a
string b
Returns
Type Description
bool

operator ==(InternedString, InternedString)

Declaration
public static bool operator ==(InternedString a, InternedString b)
Parameters
Type Name Description
InternedString a
InternedString b
Returns
Type Description
bool

operator >(InternedString, InternedString)

Declaration
public static bool operator >(InternedString left, InternedString right)
Parameters
Type Name Description
InternedString left
InternedString right
Returns
Type Description
bool

implicit operator string(InternedString)

Convert the given InternedString back to a string. Equivalent to ToString().

Declaration
public static implicit operator string(InternedString str)
Parameters
Type Name Description
InternedString str

An InternedString.
Returns
Type Description
string

A string.

operator !=(string, InternedString)

Declaration
public static bool operator !=(string a, InternedString b)
Parameters
Type Name Description
string a
InternedString b
Returns
Type Description
bool

operator !=(InternedString, string)

Declaration
public static bool operator !=(InternedString a, string b)
Parameters
Type Name Description
InternedString a
string b
Returns
Type Description
bool

operator !=(InternedString, InternedString)

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

operator <(InternedString, InternedString)

Declaration
public static bool operator <(InternedString left, InternedString right)
Parameters
Type Name Description
InternedString left
InternedString right
Returns
Type Description
bool

Implements