Table of Contents

Class WildcardExpression

Namespace
Acuit.Pinpoint.WildcardExpressions
Assembly
Acuit.Pinpoint.WildcardExpressions.dll

A wildcard expression.

public class WildcardExpression
Inheritance
WildcardExpression
Inherited Members

Remarks

This general-purpose wildcard mechanism can be used stand-alone to match strings, or it can be used to generate equivalent matching mechanisms for use elsewhere:

  • Regular expressions.
  • SQL LIKE patterns. NOTE: Not all wildcard expressions have equivalent SQL LIKE patterns.
  • Expressions for use in Linq database queries.

The following are supported in wildcard expressions:

Pattern Description
* Zero or more characters.
? Any one character.
[AB] One character from a set.
[0-9] One character from a range.
[0-9ABCDEF] Combination of the above.
[^AB] One character not from a set or range.
ALT1|ALT2 Alternatives for the overall string.
PRE(ALT1|ALT2)POST Alternatives within the overall string.
\ Treat the next character as a literal.
{name} A named capture, which will match any sequence of one or more characters. Names are case-sensitive. If multiple captures for the same name are included in the pattern, generally the last capture that matches will be used to produce the value. This pattern is only available if captures are explicitly supported when creating the wildcard expression.
/regex/ A regular expression (the entire pattern must be enclosed in slashes).

Literal characters can be any Unicode character, including non-printable control characters.

Constructors

WildcardExpression(string, bool, RegexOptions)

Initializes a new instance of the WildcardExpression class.

public WildcardExpression(string pattern, bool supportCaptures = false, RegexOptions regexOptions = RegexOptions.IgnoreCase | RegexOptions.Singleline | RegexOptions.CultureInvariant)

Parameters

pattern string

The wildcard pattern.

supportCaptures bool

Whether to support captures in the wildcard pattern. This defaults to false.

regexOptions RegexOptions

The regular expression options to use. This defaults to IgnoreCase, CultureInvariant, and Singleline.

Remarks

See the remarks for WildcardExpression for supported wildcard expressions.

Exceptions

ArgumentNullException

pattern is null.

ArgumentException

pattern is not a valid wildcard pattern.

Properties

CaptureNames

Gets the list of capture names in the wildcard pattern. This will be empty if captures are not supported.

public IReadOnlyList<string> CaptureNames { get; }

Property Value

IReadOnlyList<string>

IsLiteral

Gets whether the wildcard expression is a literal string.

public bool IsLiteral { get; }

Property Value

bool

Remarks

ToLiteral() can be used to get the equivalent literal string.

Pattern

Gets the wildcard pattern.

public string Pattern { get; }

Property Value

string

RegexPattern

Gets the regular expression pattern for this wildcard expression.

public string RegexPattern { get; }

Property Value

string

Methods

Escape(string)

Escapes literal text for use within a wildcard pattern.

public static string Escape(string text)

Parameters

text string

The text to escape.

Returns

string

The escaped text.

Exceptions

ArgumentNullException

text is null.

Escape(string, bool)

Escapes literal text for use within a wildcard pattern.

public static string Escape(string text, bool supportCaptures)

Parameters

text string

The text to escape.

supportCaptures bool

Whether to support captures in the wildcard pattern.

Returns

string

The escaped text.

Exceptions

ArgumentNullException

text is null.

IsMatch(string)

Determines whether text matches the wildcard pattern.

public bool IsMatch(string text)

Parameters

text string

The text to compare to the wildcard pattern.

Returns

bool

true if the text matches the wildcard pattern; otherwise, false.

Exceptions

ArgumentNullException

text is null.

IsMatch(string, out IReadOnlyDictionary<string, string>?)

Determines whether text matches the wildcard pattern and gets any captured values upon success.

public bool IsMatch(string text, out IReadOnlyDictionary<string, string>? captures)

Parameters

text string

The text to compare to the wildcard pattern.

captures IReadOnlyDictionary<string, string>

On return, if the text matches the wildcard pattern, this will be set to a dictionary of the captured values; otherwise, it will be null.

Returns

bool

true if the text matches the wildcard pattern; otherwise, false.

Exceptions

ArgumentNullException

text is null.

IsMatch(string, string, RegexOptions)

Determines whether input text matches a wildcard pattern.

public static bool IsMatch(string input, string pattern, RegexOptions regexOptions = RegexOptions.IgnoreCase | RegexOptions.Singleline | RegexOptions.CultureInvariant)

Parameters

input string

The text to compare to the wildcard pattern.

pattern string

The wildcard pattern.

regexOptions RegexOptions

The regular expression options to use. This defaults to IgnoreCase, CultureInvariant, and Singleline.

Returns

bool

Returns true if the input text matches the wildcard pattern.

Remarks

See the remarks for WildcardExpression for supported wildcard expressions.

Exceptions

ArgumentNullException

input is null.

ArgumentNullException

pattern is null.

ArgumentException

pattern is not a valid wildcard pattern.

ToLiteral()

Convert the wildcard expression to a literal string, if possible.

public string ToLiteral()

Returns

string

The equivalent literal string.

Remarks

If the wildcard expression contains anything other than literal string characters, then this will throw a NotSupportedException.

Exceptions

InvalidOperationException

The wildcard expression cannot be converted to a literal string.

ToSqlLikePattern()

Convert the wildcard expression to a SQL LIKE pattern, if possible.

public string ToSqlLikePattern()

Returns

string

The equivalent SQL LIKE pattern.

Remarks

The following cannot be converted to a SQL LIKE pattern:

Pattern Description
ALT1|ALT2 Alternatives for the overall string.
PRE(ALT1|ALT2)POST Alternatives within the overall string.
{name} A named capture, which will match any sequence of one or more characters.
/regex/ A regular expression (the entire pattern must be enclosed in slashes).

Exceptions

NotSupportedException

The wildcard expression cannot be converted to a SQL LIKE pattern.

ToSqlWhereMatchExpression(Expression, Func<Expression, string, Expression>)

Convert the wildcard expression to an expression for use in Linq database queries, if possible.

public Expression ToSqlWhereMatchExpression(Expression sourceValueExpression, Func<Expression, string, Expression> sqlLikeFactory)

Parameters

sourceValueExpression Expression

The expression that yields the source value.

sqlLikeFactory Func<Expression, string, Expression>

An expression factory that yields an expression equivalent to a SQL LIKE suitable for use with the Linq database provider.

Returns

Expression

The equivalent SQL LIKE pattern.

Remarks

The following cannot be converted to an expression for use in Linq database queries:

Pattern Description
PRE(ALT1|ALT2)POST Alternatives within the overall string.
{name} A named capture, which will match any sequence of one or more characters.
/regex/ A regular expression (the entire pattern must be enclosed in slashes).

Exceptions

NotSupportedException

The wildcard expression cannot be converted to an expression for use in Linq database queries.

ToString()

Returns the Pattern value as a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.