ball_patternutil

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Basic Usage

Purpose

Provide a utility class for string pattern matching.

Classes

• ball::PatternUtil: utility class for string pattern matching

Description

This component defines a namespace, ball::PatternUtil, that provides utility functions for matching input strings to a given pattern based on wild-card and simple escape sequences.

This component participates in the implementation of "Rule-Based Logging". For more information on how to use that feature, please see the package level documentation and usage examples for "Rule-Based Logging".

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage

The following code fragments illustrate basic usage of this component's utility functions.

A string matches a pattern if they are identical:

assert(ball::PatternUtil::isMatch("EQ",           "EQ"));

A string matches a pattern containing an (unescaped) trailing * if that pattern (without the trailing *) is a prefix of the string:

assert(ball::PatternUtil::isMatch("EQ.MARKET",    "EQ*"));
assert(ball::PatternUtil::isMatch("EQ",           "EQ*"));

An escaped * at the end loses its wild-card semantics and matches a single *:

assert(false == ball::PatternUtil::isMatch("EQ.MARKET", "EQ\\*"));
assert(ball::PatternUtil::isMatch("EQ*",          "EQ\\*"));

Escape sequences include '\' and '*' only and they can appear anywhere in the pattern:

assert(ball::PatternUtil::isMatch("\\EQ",         "\\\\EQ"));
assert(ball::PatternUtil::isMatch("E*Q",          "E\\*Q"));

A pattern is invalid if it contains a non-trailing *, or any '\' that is not followed by either '\' or *. The isValidPattern function can be used to determine whether or not a pattern is valid:

assert(false == ball::PatternUtil::isValidPattern("E\\Q"));
assert(false == ball::PatternUtil::isValidPattern("E*Q"));
assert(true  == ball::PatternUtil::isValidPattern("E\\\\Q"));
assert(true  == ball::PatternUtil::isValidPattern("E\\*Q"));

The isMatch function always returns false on an invalid pattern:

assert(false == ball::PatternUtil::isMatch("E\\Q","E\\Q"));
assert(false == ball::PatternUtil::isMatch("E*Q", "E*Q"));
assert(false == ball::PatternUtil::isMatch("ETQ", "E*Q"));