Struct StringComparisonRules

Namespace

RDCore.SDK.Runtime

Assembly

RDCore.SDK.dll

How the relational operators compare String values where an operation is evaluated or analyzed (MS-VBAL §5.6.9.5): the comparison mode of the module, and the regional settings of the environment.

public readonly record struct StringComparisonRules : IEquatable<StringComparisonRules>

Implements

IEquatable<StringComparisonRules>

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Constructors

StringComparisonRules(OptionCompare, CultureInfo?)

How the relational operators compare String values where an operation is evaluated or analyzed (MS-VBAL §5.6.9.5): the comparison mode of the module, and the regional settings of the environment.

public StringComparisonRules(OptionCompare Mode = OptionCompare.Binary, CultureInfo? Culture = null)

Parameters

Mode OptionCompare

The comparison mode of the module (MS-VBAL §5.2.1.1): Text compares regardless of case, anything else compares the data of the strings (Compare(VBStringValue, VBStringValue)). Never Database: that is resolved to one of the two by the platform.

Culture CultureInfo

The regional settings of the environment, that text is collated by. The invariant culture when none is given.

Properties

Comparer

Compares strings the way the relational operators do: by their data in binary mode (Compare(VBStringValue, VBStringValue)), and regardless of case according to the environment's collation in text mode.

public StringComparer Comparer { get; }

Property Value

StringComparer

Remarks

👉 A string is whole characters, so this cannot see a trailing byte: Compare(VBStringValue, VBStringValue) is what compares two String values, and agrees with this wherever neither has one.

Culture

The regional settings of the environment, that text is collated by. The invariant culture when none is given.

public CultureInfo? Culture { get; init; }

Property Value

CultureInfo

EffectiveCulture

The culture text comparisons are collated by.

public CultureInfo EffectiveCulture { get; }

Property Value

CultureInfo

IgnoresCase

Whether strings that differ in case only are equal.

public bool IgnoresCase { get; }

Property Value

bool

Mode

The comparison mode of the module (MS-VBAL §5.2.1.1): Text compares regardless of case, anything else compares the data of the strings (Compare(VBStringValue, VBStringValue)). Never Database: that is resolved to one of the two by the platform.

public OptionCompare Mode { get; init; }

Property Value

OptionCompare

Methods

Compare(VBStringValue, VBStringValue)

Compares two String values the way the relational operators do (MS-VBAL §5.6.9.5), a trailing byte included.

public int Compare(VBStringValue lhs, VBStringValue rhs)

Parameters

lhs VBStringValue

The left operand.

rhs VBStringValue

The right operand.

Returns

int

Less than zero when lhs is less than rhs, zero when they are equal, and greater than zero otherwise.

Remarks

In binary mode "each byte of the implementation-specific representation of the string data is compared", which is every byte of GetBytes(), in the one order CompareBinary(ReadOnlySpan<byte>, ReadOnlySpan<byte>) defines. In text mode "the text of the strings is compared in a case-insensitive manner", and a trailing byte is not text: it only breaks a tie between two texts that are equal regardless of case - no trailing byte before any, then by value - since an extra byte is not a difference in case.

🚧 Whether MS-VBA's text mode sees a trailing byte at all is yet to be run against MS-VBA; ignoring it would be returning the text comparison alone.

Compare(ReadOnlySpan<char>, ReadOnlySpan<char>)

Compares two strings of whole characters the way the relational operators do, as StrComp reports it.

public int Compare(ReadOnlySpan<char> left, ReadOnlySpan<char> right)

Parameters

left ReadOnlySpan<char>

The characters of the left operand.

right ReadOnlySpan<char>

The characters of the right operand.

Returns

int

-1 when left is less than right, 0 when they are equal, and 1 otherwise.

FindAll(string, string)

Every occurrence of value in source that is made of whole characters, from left to right and never overlapping, the way Replace and Split find them: each search resumes after the occurrence it found.

public IEnumerable<(int Index, int Length)> FindAll(string source, string value)

Parameters

source string

The characters to search.

value string

The characters to search for.

Returns

IEnumerable<(int Index, int Length)>

Remarks

Text mode searches the letters as TryFind(ReadOnlySpan<char>, ReadOnlySpan<char>, out int, out int) does, and takes an occurrence only where it starts and ends with a character: a part of a character that is expanded is not replaced, nor split at. Replace("xæx", "a", "-", , , vbTextCompare) is "xæx", and Replace("xaex", "æ", "-", , , vbTextCompare) is "x-x" (MS-VBA, recorded in Excel: oracle\instr-text N07). A zero-length value finds nothing - there is no run to replace or to split at.

TryFind(ReadOnlySpan<char>, ReadOnlySpan<char>, out int, out int)

Finds the first occurrence of value in source, the way InStr finds it.

public bool TryFind(ReadOnlySpan<char> source, ReadOnlySpan<char> value, out int index, out int length)

Parameters

source ReadOnlySpan<char>

The characters to search.

value ReadOnlySpan<char>

The characters to search for.

index int

The 0-based position in source of the character the occurrence starts in.

length int

How many characters of source the occurrence takes up, the ones it starts and ends in included.

Returns

bool

true when it is found; a zero-length value is found at the start.

Remarks

Binary mode finds the code units of value, which is where either reading of binary mode finds two strings equal. Text mode is not the comparison = makes: it searches the letters of both (Letters(ReadOnlySpan<char>, TextInfo, out int[])) - folded to one case, and æ, œ, ß and þ as the two letters they expand to - and an occurrence may start or end inside a character that is expanded. It is found at the character it starts in: InStr(1, "xæx", "ex", vbTextCompare) is 2, and so is InStr(1, "xaex", "æ", vbTextCompare). Nothing is ignored: a soft hyphen, a full-width letter or katakana is a character of its own, where = would ignore it (MS-VBA, recorded in Excel: oracle\instr-text N01-N06). MS-VBAL says nothing of how a text search matches.

TryFindLast(ReadOnlySpan<char>, ReadOnlySpan<char>, out int, out int)

Finds the last occurrence of value in source, the way TryFind(ReadOnlySpan<char>, ReadOnlySpan<char>, out int, out int) finds the first.

public bool TryFindLast(ReadOnlySpan<char> source, ReadOnlySpan<char> value, out int index, out int length)

Parameters

source ReadOnlySpan<char>

The characters to search.

value ReadOnlySpan<char>

The characters to search for.

index int

The 0-based position in source of the character the occurrence starts in.

length int

How many characters of source the occurrence takes up, the ones it starts and ends in included.

Returns

bool

true when it is found; a zero-length value is found at the end.