Table of Contents

Class LazyEncodedString

Namespace
Ubiquity.NET.InteropHelpers
Assembly
Ubiquity.NET.InteropHelpers.dll

Lazily encoded string with implicit casting to a read only span of bytes or a normal managed string

[NativeMarshalling(typeof(LazyEncodedStringMarshaller))]
public sealed class LazyEncodedString : IEquatable<LazyEncodedString?>, IEquatable<string?>, IEqualityOperators<LazyEncodedString, LazyEncodedString, bool>
Inheritance
LazyEncodedString
Implements
Inherited Members
Extension Methods

Remarks

This class handles capturing a managed string or a span of bytes for a native one. It supports a lazily evaluated representation of the string as a sequence of native bytes or a managed string. The encoding ONLY happens once, and ONLY when needed the first time. This reduces the overhead to a onetime hit for any strings that "sometimes" get passed to native code or native strings that "sometimes" get used in managed code as a string.

This is essentially a pair of Lazy<T> members to handle conversions in one direction. Constructors exist for an existing ReadOnlySpan<T> of bytes and another for a string. Each constructor will pre-initialize one of the lazy values and set up the evaluation function for the other. Thus the string is encoded/decoded ONLY if needed and then, only once.

This class handles all the subtle complexity regarding terminators as most of the encoding APIs in .NET will drop/ignore a string terminator but native code usually, but not always, requires it. Thus, this ensures the presence of a terminator even if the span provided to the constructor doesn't include one. (It has to copy the string anyway so why not be nice and robust at the cost of one byte of allocated space)

Constructors

LazyEncodedString(ReadOnlySpan<byte>, Encoding?)

Initializes a new instance of the LazyEncodedString class from an existing span of native bytes

LazyEncodedString(string, Encoding?)

Initializes a new instance of the LazyEncodedString class from an existing managed string

Properties

Empty

Gets a LazyEncodedString representation of an empty string

Encoding

Gets the encoding used for this instance

IsEmpty

Gets a value indicating whether this instance represents an empty string

NativeLength

Gets the native size (in bytes, including the terminator) of the memory for this string

NativeStrLen

Gets the native length (in bytes, NOT including the terminator) of the native form of the string

Methods

Equals(object?)

Determines whether the specified object is equal to the current object.

Equals(string?)

Indicates whether the current object is equal to another object of the same type.

Equals(LazyEncodedString?)

Indicates whether the current object is equal to another object of the same type.

From(string?)

Converts a managed string into a LazyEncodedString

FromUnmanaged(byte*)

Creates a nullable LazyEncodedString from an unmanaged string pointer (terminated!)

FromUnmanaged(byte*, nuint)

Creates a nullable LazyEncodedString from an unmanaged view

GetHashCode()

Serves as the default hash function.

IsNullOrEmpty(LazyEncodedString?)

Tests if the given LazyEncodedString is null or Empty

IsNullOrWhiteSpace(LazyEncodedString?)

Gets a value indicating if the provided instance is null or all whitespace

Join(char, params IEnumerable<LazyEncodedString>)

Specialized join that optimizes for LazyEncodedString values

Join<T>(char, params IEnumerable<T>)

Concatenates the members of a collection, using the specified separator between each member.

Pin()

Pins the native representation of this memory for use in native APIs

ToReadOnlySpan(bool)

Gets a ReadOnlySpan<T> of bytes for the native encoding of the string

ToString()

Returns a string that represents the current object.

Operators

operator ==(LazyEncodedString?, LazyEncodedString?)

Compares two values to determine equality.

implicit operator LazyEncodedString(ReadOnlySpan<byte>)

Convenient implicit conversion of a managed string into a Lazily encoded string

implicit operator LazyEncodedString?(string?)

Convenient implicit conversion of a managed string into a Lazily encoded string

implicit operator ReadOnlySpan<byte>(LazyEncodedString)

Implicit cast to a span via ToReadOnlySpan(bool)

implicit operator string(LazyEncodedString)

Implicit cast to a string via ToString()

operator !=(LazyEncodedString?, LazyEncodedString?)

Compares two values to determine inequality.