Utf8String

Namespace: SnowBank.Buffers.Text · struct

Implements: IFormattable, IEnumerable<UnicodeCodePoint>, IEnumerable, IEquatable<Utf8String>, IEquatable<string>, IEquatable<Slice>, IEquatable<ArraySegment<char>>, IEquatable<ReadOnlySpan<byte>>, IEquatable<ReadOnlySpan<char>>

Represents a string that is stored as UTF-8 bytes in managed memory

Remarks

This type can be used as a replacement for in parsers that wants to reduce memory allocations

Properties

IsAscii

bool IsAscii { get; }

Test if this string only contains ASCII characters

IsNull

bool IsNull { get; }

Test if this string is null

IsNullOrEmpty

bool IsNullOrEmpty { get; }

Test if this string is null or empty

Span

ReadOnlySpan<byte> Span { get; }

Returns a span over the UTF-8 encoded bytes of this string

The length of the span may be greater than the of this string, but nether smaller.

Methods

Concat

Utf8String Concat(Utf8String b)

Concatenates two Utf8String

Utf8String Concat(string b)

Concatenates a Utf8String with a String

Contains

bool Contains(char ch)

Tests if this string contains a specific character

bool Contains(char ch, int startIndex)

Tests if this string contains a specific character, at or after the specified index

CreateUnsafe

static Utf8String CreateUnsafe(Slice buffer, int length, int? hashCode)

Wraps a Slice that is expected to contain a UTF-8 encoded string

• buffer — Buffer that contains the UTF-8 bytes
• length — Length of the string (in characters)
• hashCode — Hashcode of the string (or null if unknown)

DangerousGetPinnableReference

byte DangerousGetPinnableReference()

Returns a reference to the first byte in the encoded string.

If the string is empty, returns a reference to the location where the first byte would have been stored. Such a reference can be used for pinning but must never be dereferenced.

EndsWith

bool EndsWith(string suffix)

Tests if this string ends with the given suffix

Warning: This method is O(this.Length), which can be a lot larger than the length of the suffix! Convention is that all strings end with the null or empty suffix.

bool EndsWith(ReadOnlySpan<char> suffix)

Tests if this string ends with the given suffix

Warning: This method is O(this.Length), which can be a lot larger than the length of the suffix! Convention is that all strings end with the null or empty suffix.

bool EndsWith(Utf8String suffix)

Tests if this string ends with the given suffix

Warning: This method is O(this.Length), which can be a lot larger than the length of the suffix! Convention is that all strings end with the null or empty suffix.

bool EndsWith(string suffix, int offset, int count)

Tests if this string ends with the given segment of a suffix

• suffix — String that contains the suffix
• offset — Offset in suffix of the first character of the suffix
• count — Size of the suffix

Warning: This method is O(this.Length), which can be a lot larger than the length of the suffix! Convention is that all strings end with the null or empty suffix.

Equals

bool Equals(object obj)

bool Equals(Utf8String other)

bool Equals(ReadOnlySpan<byte> other)

bool Equals(string other)

bool Equals(ReadOnlySpan<char> other)

bool Equals(ArraySegment<char> other)

bool Equals(Slice other)

static bool Equals(ReadOnlySpan<byte> left, string right)

Tests if a UTF-8 encoded string is equal to a UTF-16 encoded string

FromBuffer

static Utf8String FromBuffer(Slice buffer, bool discardBom = false, bool noHashCode = false)

Returns a string view of a native buffer that contains UTF-8 bytes

• buffer — Bytes that contain UTF-8 encoded characters
• discardBom — If true, discard any UTF-8 BOM if present
• noHashCode — If false, pre-compute the hashcode of the string. If you do not use this string for comparisons or as a key in a dictionary, you can skip this step by passing true.

Returns: Utf8String that maps to the corresponding buffer

This method needs to compute the length (and hashcode) of the string. You should cache the result if you need it more than once.

static Utf8String FromBuffer(byte[] buffer, int offset, int count, bool discardBom = false, bool noHashCode = false)

Returns a string view of a native buffer that contains UTF-8 bytes

• buffer — Buffer that contains UTF-8 encoded characters
• offset — Offset (in bytes) of the start of the string in buffer
• count — Size (in bytes) of the string in buffer
• discardBom — If true, discard any UTF-8 BOM if present
• noHashCode — If false, pre-compute the hashcode of the string. If you do not use this string for comparisons or as a key in a dictionary, you can skip this step by passing true.

Returns: Utf8String that maps to the corresponding buffer

This method needs to compute the length (and hashcode) of the string. You should cache the result if you need it more than once.

FromString

static Utf8String FromString(string text, bool includeBom = false, bool noHashCode = false)

Converts a string into a UTF-8 byte buffer

• text — String to encode
• includeBom — If true, includes the UTF8 BOM at the start of the buffer
• noHashCode — If true, skip the computation of the hashcode of the resulting string.

Returns: Buffer that contains the utf-8 binary representation of text, with an optional BOM.

static Utf8String FromString(ReadOnlySpan<char> text, bool includeBom = false, bool noHashCode = false)

Converts part of a string into a UTF-8 byte buffer

• text — Span of characters to encode
• includeBom — If true, includes the UTF8 BOM at the start of the buffer
• noHashCode — If true, skip the computation of the hashcode of the resulting string.

Returns: Buffer that contains the utf-8 binary representation of text, with an optional BOM.

static Utf8String FromString(ReadOnlySpan<char> text, ref byte[] buffer, bool includeBom = false, bool noHashCode = false)

Converts part of a string into a UTF-8 byte buffer

• text — String to encode
• buffer — Buffer that should be used to store the converted string. If null or not large enough, will be replaced by a newly allocated buffer.
• includeBom — If true, includes the UTF8 BOM at the start of the buffer
• noHashCode — If true, skip the computation of the hashcode of the resulting string.

Returns: Buffer that contains the utf-8 binary representation of text, with an optional BOM.

static Utf8String FromString(string text, int offset, int count, bool includeBom = false, bool noHashCode = false)

Converts part of a string into a UTF-8 byte buffer

• text — String to encode
• offset — Offset (in characters) of the part of text to encode
• count — Size (in characters) of the part of text to encode
• includeBom — If true, includes the UTF8 BOM at the start of the buffer
• noHashCode — If true, skip the computation of the hashcode of the resulting string.

Returns: Buffer that contains the utf-8 binary representation of text, with an optional BOM.

static Utf8String FromString(string text, int offset, int count, ref byte[] buffer, bool includeBom = false, bool noHashCode = false)

Converts part of a string into a UTF-8 byte buffer

• text — String to encode
• offset — Offset (in characters) of the part of text to encode
• count — Size (in characters) of the part of text to encode
• buffer — Buffer that should be used to store the converted string. If null or not large enough, will be replaced by a newly allocated buffer.
• includeBom — If true, includes the UTF8 BOM at the start of the buffer
• noHashCode — If true, skip the computation of the hashcode of the resulting string.

Returns: Buffer that contains the utf-8 binary representation of text, with an optional BOM.

GetBuffer

Slice GetBuffer()

Returns an Slice that points to the UTF-8 encoded bytes of this string

CAUTION: you should NOT mutate the content of the buffer. Doing so will invalidate the pre-computed and and potentially generate corrupted data.

GetBytes

byte[] GetBytes()

Returns an array with a copy of the UTF-8 encoded bytes of this string

GetCachedHashCode

int GetCachedHashCode()

Returns the hashcode of the string only if it has been pre-computed; otherwise, returns 0.

Only use this method if the cost of computing the hashcode would be too high

GetEnumerator

Enumerator GetEnumerator()

Returns an enumerator that will list all the UnicodeCodePoint in this string

GetHashCode

int GetHashCode()

Returns the hashcode of the string

GetPinnableReference

byte GetPinnableReference()

Returns a reference to the first character in the string. If the string is empty, returns null reference.

IndexOf

int IndexOf(char ch)

Returns the index of the first occurrence of a specific character in this string

Returns: Index of the character if found; otherwise, -1

int IndexOf(char ch, int startIndex)

Returns the index of the first occurrence of a specific character in this string, at or after the specified index

Returns: Index of the character if found; otherwise, -1

RemoveBom

static Slice RemoveBom(Slice buffer)

Truncates the UTF-8 BOM prefix from a buffer, if it is present

static ReadOnlySpan<byte> RemoveBom(ReadOnlySpan<byte> buffer)

Truncates the UTF-8 BOM prefix from a buffer, if it is present

StartsWith

bool StartsWith(char value)

Tests if this string starts with the given character

bool StartsWith(ReadOnlySpan<char> prefix)

Tests if this string starts with the given prefix

This method is O(.Length). Convention is that all strings start with the null or empty prefix.

bool StartsWith(string prefix)

Tests if this string starts with the given prefix

This method is O(.Length). Convention is that all strings start with the null or empty prefix.

bool StartsWith(Utf8String prefix)

Tests if this string starts with the given prefix

This method is O(.Length). Convention is that all strings start with the null or empty prefix.

bool StartsWith(string prefix, int offset, int count)

Tests if this string starts with the given prefix

This method is O(). Convention is that all strings start with the empty prefix.

Substring

Utf8String Substring(int startIndex, bool noHashCode = false)

Returns a substring that shares the same buffer as this one

Utf8String Substring(int startIndex, int count, bool noHashCode = false)

Returns a substring that shares the same buffer as this one

ToCharArray

char[] ToCharArray()

Returns an array with the decoded characters of this string

ToString

string ToString()

Returns the equivalent String

string ToString(string fmt)

Returns the equivalent String, in the given format.

string ToString(string fmt, IFormatProvider provider)

Returns the equivalent String, in the given format.

Fields

Buffer

readonly Slice Buffer

Buffer that points to the UTF-8 bytes of the string in memory

Empty

static readonly Utf8String Empty

Logical equivalent to the empty string.

Length

readonly int Length

Length (in characters) of the string

Nil

static readonly Utf8String Nil

Logical equivalent to the null string.