Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.pfsw.text
Class StringPattern

java.lang.Object
  extended by org.pfsw.text.AStringFilter
      extended by org.pfsw.text.StringPattern
All Implemented Interfaces:
java.io.Serializable, org.pfsw.bif.filter.IObjectFilter<java.lang.String>, org.pfsw.bif.text.IJSONConvertible, org.pfsw.bif.text.IStringFilter, org.pfsw.bif.text.IStringRepresentation
public class StringPattern
extends AStringFilter
implements java.io.Serializable, org.pfsw.bif.text.IJSONConvertible, org.pfsw.bif.text.IStringRepresentation

This class provides services for checking strings against string-patterns. Currently it supports the wildcards
'*' for any number of any character and
'?' for any single character.

The API is very simple:

There are two class methods match() and matchIgnoreCase().
Example:
StringPattern.match( 'Hello World", "H* W*" ) ; --> evaluates to true
StringPattern.matchIgnoreCase( 'StringPattern", "str???pat*" ) ; --> evaluates to true

To be compatible with most pattern engines this class also supports that the multi-char wildcard '*' matches empty string. By default it doesn't ! To switch on this behaviour call
pattern.multiCharWildcardMatchesEmptyString(true);
If this option is set to true, the following example returns true, otherwise it would return false: 

 StringPattern pattern = new StringPattern( "Fred*" ) ;
 pattern.multiCharWildcardMatchesEmptyString(true);
 return pattern.matches( "Fred" ) ; // <== returns true

It is also possible to instantiate new pattern object by using the static create() methods rather than the constructors. These methods will create new patterns that have the multiCharWildcardMatchesEmptyString option initialized to true.

See Also:
Serialized Form

Field Summary
protected static char DEFAULT_MULTICHAR_WILDCARD
           
protected static char DEFAULT_SINGLECHAR_WILDCARD
           
protected static java.lang.String SWITCH_OFF
           
protected static java.lang.String SWITCH_ON
           
 
Fields inherited from interface org.pfsw.bif.text.IJSONConvertible
JSON_ARRAY_END, JSON_ARRAY_START, JSON_ELEMENT_SEPARATOR, JSON_LITERAL_FALSE, JSON_LITERAL_NULL, JSON_LITERAL_TRUE, JSON_OBJECT_END, JSON_OBJECT_START, JSON_PAIR_SEPARATOR, JSON_STRING_DELIMITER, JSON_STRING_ESCAPE
 
Fields inherited from interface org.pfsw.bif.text.IStringFilter
ALL, NONE
 
Constructor Summary
StringPattern(java.lang.String pattern)
          Initializes the new instance with the string pattern.
StringPattern(java.lang.String pattern, boolean ignoreCase)
          Initializes the new instance with the string pattern and the selection, if case should be ignored when comparing characters.
StringPattern(java.lang.String pattern, boolean ignoreCase, char digitWildcard)
          Initializes the new instance with the string pattern and the selection, if case should be ignored when comparing characters plus a wildcard character for digits.
StringPattern(java.lang.String pattern, char digitWildcard)
          Initializes the new instance with the string pattern and a digit wildcard character.
 
Method Summary
 void appendAsJSONString(java.lang.Appendable output)
           
 java.lang.String asString()
           
protected  boolean charsAreEqual(char probeChar, char patternChar)
           
static boolean containsWildcard(java.lang.String aString)
          Returns true if the given string contains a single or multi character wildcard.
 StringPattern copy()
          Returns a copy of this pattern.
static StringPattern create(java.lang.String pattern)
          Returns a new instance with the string pattern.
static StringPattern create(java.lang.String pattern, boolean ignoreCase)
          Returns a new instance with the string pattern and the selection, if case should be ignored when comparing characters.
static StringPattern create(java.lang.String pattern, boolean ignoreCase, char digitWildcard)
          Returns a new instance with the string pattern and the selection, if case should be ignored when comparing characters plus a wildcard character for digits.
static StringPattern create(java.lang.String pattern, char digitWildcard)
          Returns anew instance with the string pattern and a digit wildcard character.
protected  java.lang.Character digitWildcard()
           
protected  void digitWildcard(java.lang.Character newValue)
           
protected  char digitWildcardChar()
           
protected  boolean endNotReached(char character)
           
protected  boolean endReached(char character)
           
 boolean equals(java.lang.Object obj)
          Returns true if the given object is equal to the receiver.
protected  boolean eventuallyMatched(char probeCh, char patternCh, StringExaminer patternIterator)
           
static char getDefaultMultiCharWildcard()
          Returns the character that is used to specify any number of any character.
static char getDefaultSingleCharWildcard()
          Returns the character that is used to specify any single character.
 boolean getIgnoreCase()
          Returns whether or not the pattern matching ignores upper and lower case
 char getMultiCharWildcard()
          Returns the wildcard character that is used as placeholder for zero to many occurances of any character(s).
 java.lang.String getPattern()
          Returns the pattern as string.
protected  char getPatternChar(StringExaminer patternIterator, char probeCh)
           
 char getSingleCharWildcard()
          Returns the wildcard character that is used as placeholder for a single occurance of any character.
protected  boolean hasDigitWildcard()
           
 int hashCode()
          Returns a hash code value for the object.
 boolean hasWildcard()
          Returns true if the pattern contains any '*' or '?'
protected  java.lang.String ignoreCaseAsString()
           
protected  java.lang.String inspectString()
           
static boolean match(java.lang.String probe, java.lang.String pattern)
          Returns true, if the given probe string matches the given pattern.
 boolean matches(java.lang.String probe)
          Tests if a specified string matches the pattern.
static boolean matchIgnoreCase(java.lang.String probe, java.lang.String pattern)
          Returns true, if the given probe string matches the given pattern.
protected  boolean matchReverse(java.lang.String patternStr, StringExaminer probeIterator)
           
 boolean multiCharWildcardMatchesEmptyString()
          Returns true, if this StringPattern allows empty strings at the position of the multi character wildcard ('*').
 void multiCharWildcardMatchesEmptyString(boolean newValue)
          sets whether or not this StringPattern allows empty strings at the position of the multi character wildcard ('*').
protected  StringExaminer newExaminer(java.lang.String str)
           
 java.lang.String[] reject(java.lang.String[] strings)
          Returns an array containing all of the given strings that do NOT match this pattern.
 java.lang.String[] select(java.lang.String[] strings)
          Returns an array containing all of the given strings that match this pattern.
protected  java.lang.String[] selectOrReject(java.lang.String[] strings, boolean select)
           
 void setDigitWildcardChar(char digitWildcard)
          Sets the given character as a wildcard character in this pattern to match only digits ('0'-'9').
 void setIgnoreCase(boolean newValue)
          Sets whether the pattern matching should ignore case or not
 void setMultiCharWildcard(char newValue)
          Sets the wildcard character that is used as placeholder for zero to many occurances of any character(s).
 void setPattern(java.lang.String newValue)
          Sets the pattern to a new value
 void setSingleCharWildcard(char newValue)
          Sets the wildcard character that is used as placeholder for a single occurance of any character.
protected  boolean skipAfter(StringExaminer examiner, java.lang.String matchString)
          Increments the given iterator up to the last character that matched the character sequence in the given matchString.
protected  char skipWildcards(StringExaminer iterator)
          Moves the iterator position to the next character that is no wildcard.
protected  StringUtil strUtil()
           
 java.lang.String toJSON()
          Returns a JSON string representation of this object.
 java.lang.String toString()
          Returns the pattern string.
protected  java.lang.String upToEnd(StringExaminer iterator)
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_MULTICHAR_WILDCARD

protected static final char DEFAULT_MULTICHAR_WILDCARD
See Also:
Constant Field Values

DEFAULT_SINGLECHAR_WILDCARD

protected static final char DEFAULT_SINGLECHAR_WILDCARD
See Also:
Constant Field Values

SWITCH_ON

protected static final java.lang.String SWITCH_ON
See Also:
Constant Field Values

SWITCH_OFF

protected static final java.lang.String SWITCH_OFF
See Also:
Constant Field Values
Constructor Detail

StringPattern

public StringPattern(java.lang.String pattern,
                     boolean ignoreCase)
Initializes the new instance with the string pattern and the selection, if case should be ignored when comparing characters.

Parameters:
pattern - The pattern to check against ( May contain '*' and '?' wildcards )
ignoreCase - Definition, if case sensitive character comparison or not.
See Also:
create(String, boolean)

StringPattern

public StringPattern(java.lang.String pattern)
Initializes the new instance with the string pattern. The default is case sensitive checking.

As an alternative see also StringPattern.create() method.

Parameters:
pattern - The pattern to check against ( May contain '*' and '?' wildcards )
See Also:
create(String)

StringPattern

public StringPattern(java.lang.String pattern,
                     char digitWildcard)
Initializes the new instance with the string pattern and a digit wildcard character. The default is case sensitive checking.

Parameters:
pattern - The pattern to check against ( May contain '*', '?' wildcards and the digit wildcard )
digitWildcard - A wildcard character that stands as placeholder for digits
See Also:
create(String, char)

StringPattern

public StringPattern(java.lang.String pattern,
                     boolean ignoreCase,
                     char digitWildcard)
Initializes the new instance with the string pattern and the selection, if case should be ignored when comparing characters plus a wildcard character for digits.

Parameters:
pattern - The pattern to check against ( May contain '*' and '?' wildcards )
ignoreCase - Definition, if case sensitive character comparison or not.
digitWildcard - A wildcard character that stands as placeholder for digits
See Also:
create(String, boolean, char)
Method Detail

create

public static StringPattern create(java.lang.String pattern,
                                   boolean ignoreCase)
Returns a new instance with the string pattern and the selection, if case should be ignored when comparing characters.
The option multiCharWildcardMatchesEmptyString will be initialized to true.

Parameters:
pattern - The pattern to check against ( May contain '*' and '?' wildcards )
ignoreCase - Definition, if case sensitive character comparison or not.

create

public static StringPattern create(java.lang.String pattern,
                                   char digitWildcard)
Returns anew instance with the string pattern and a digit wildcard character. The default is case sensitive checking.
The option multiCharWildcardMatchesEmptyString will be initialized to true.

Parameters:
pattern - The pattern to check against ( May contain '*', '?' wildcards and the digit wildcard )
digitWildcard - A wildcard character that stands as placeholder for digits

create

public static StringPattern create(java.lang.String pattern,
                                   boolean ignoreCase,
                                   char digitWildcard)
Returns a new instance with the string pattern and the selection, if case should be ignored when comparing characters plus a wildcard character for digits.
It is also configured to match the wildcard '*' to empty strings.

Example:
StringPattern.create( "*London*Eye#", true, '#' ).matches( "londonEYE8" ) ==> true

Parameters:
pattern - The pattern to check against ( May contain '*' and '?' wildcards )
ignoreCase - Definition, if case sensitive character comparison or not.
digitWildcard - A wildcard character that stands as placeholder for digits

match

public static boolean match(java.lang.String probe,
                            java.lang.String pattern)
Returns true, if the given probe string matches the given pattern.
The character comparison is done case sensitive.

Parameters:
probe - The string to check against the pattern.
pattern - The patter, that probably contains wildcards ( '*' or '?' )

matchIgnoreCase

public static boolean matchIgnoreCase(java.lang.String probe,
                                      java.lang.String pattern)
Returns true, if the given probe string matches the given pattern.
The character comparison is done ignoring upper/lower-case.

Parameters:
probe - The string to check against the pattern.
pattern - The patter, that probably contains wildcards ( '*' or '?' )

getDefaultMultiCharWildcard

public static char getDefaultMultiCharWildcard()
Returns the character that is used to specify any number of any character. The default is '*'.

getDefaultSingleCharWildcard

public static char getDefaultSingleCharWildcard()
Returns the character that is used to specify any single character. The default is '?'.

containsWildcard

public static boolean containsWildcard(java.lang.String aString)
Returns true if the given string contains a single or multi character wildcard. Of course this checks only the default wildcard characters.

Parameters:
aString - The string to check for wildcard characters

getIgnoreCase

public boolean getIgnoreCase()
Returns whether or not the pattern matching ignores upper and lower case

setIgnoreCase

public void setIgnoreCase(boolean newValue)
Sets whether the pattern matching should ignore case or not

getPattern

public java.lang.String getPattern()
Returns the pattern as string.

setPattern

public void setPattern(java.lang.String newValue)
Sets the pattern to a new value

create

public static StringPattern create(java.lang.String pattern)
Returns a new instance with the string pattern. The default is case sensitive checking.
The option multiCharWildcardMatchesEmptyString will be initialized to true.

Parameters:
pattern - The pattern to check against ( May contain '*' and '?' wildcards )

getSingleCharWildcard

public char getSingleCharWildcard()
Returns the wildcard character that is used as placeholder for a single occurance of any character.

setSingleCharWildcard

public void setSingleCharWildcard(char newValue)
Sets the wildcard character that is used as placeholder for a single occurance of any character.

getMultiCharWildcard

public char getMultiCharWildcard()
Returns the wildcard character that is used as placeholder for zero to many occurances of any character(s).

setMultiCharWildcard

public void setMultiCharWildcard(char newValue)
Sets the wildcard character that is used as placeholder for zero to many occurances of any character(s).

multiCharWildcardMatchesEmptyString

public boolean multiCharWildcardMatchesEmptyString()
Returns true, if this StringPattern allows empty strings at the position of the multi character wildcard ('*').

The default value is false.

multiCharWildcardMatchesEmptyString

public void multiCharWildcardMatchesEmptyString(boolean newValue)
sets whether or not this StringPattern allows empty strings at the position of the multi character wildcard ('*').

The default value is false.

matches

public boolean matches(java.lang.String probe)
Tests if a specified string matches the pattern.

Specified by:
matches in interface org.pfsw.bif.filter.IObjectFilter<java.lang.String>
Specified by:
matches in interface org.pfsw.bif.text.IStringFilter
Parameters:
probe - The string to compare to the pattern
Returns:
true if and only if the probe matches the pattern, false otherwise.

select

public java.lang.String[] select(java.lang.String[] strings)
Returns an array containing all of the given strings that match this pattern.

Parameters:
strings - The strings to be matched against this pattern

reject

public java.lang.String[] reject(java.lang.String[] strings)
Returns an array containing all of the given strings that do NOT match this pattern.

Parameters:
strings - The strings to be matched against this pattern

asString

public java.lang.String asString()
Specified by:
asString in interface org.pfsw.bif.text.IStringRepresentation

toString

public java.lang.String toString()
Returns the pattern string.

Overrides:
toString in class java.lang.Object
See Also:
Object.toString()

hasWildcard

public boolean hasWildcard()
Returns true if the pattern contains any '*' or '?' or digit wildcard wildcard character.

setDigitWildcardChar

public void setDigitWildcardChar(char digitWildcard)
Sets the given character as a wildcard character in this pattern to match only digits ('0'-'9').

Parameters:
digitWildcard - The placeholder character for digits

copy

public StringPattern copy()
Returns a copy of this pattern. The values of the copy are independent of the origin. That means, changes to the copy will have no impact on this string pattern.

equals

public boolean equals(java.lang.Object obj)
Returns true if the given object is equal to the receiver.

Overrides:
equals in class java.lang.Object
See Also:
Object.equals(java.lang.Object)

hashCode

public int hashCode()
Returns a hash code value for the object.

Overrides:
hashCode in class java.lang.Object
See Also:
Object.hashCode()

appendAsJSONString

public void appendAsJSONString(java.lang.Appendable output)
Specified by:
appendAsJSONString in interface org.pfsw.bif.text.IJSONConvertible

toJSON

public java.lang.String toJSON()
Returns a JSON string representation of this object.

Specified by:
toJSON in interface org.pfsw.bif.text.IJSONConvertible
Returns:
JSON object: {"string1":"string2"}

eventuallyMatched

protected boolean eventuallyMatched(char probeCh,
                                    char patternCh,
                                    StringExaminer patternIterator)

hasDigitWildcard

protected boolean hasDigitWildcard()

digitWildcardChar

protected char digitWildcardChar()

skipWildcards

protected char skipWildcards(StringExaminer iterator)
Moves the iterator position to the next character that is no wildcard. Doesn't skip digit wildcards and single-char wildcards !

skipAfter

protected boolean skipAfter(StringExaminer examiner,
                            java.lang.String matchString)
Increments the given iterator up to the last character that matched the character sequence in the given matchString. Returns true, if the matchString was found, otherwise false.

Parameters:
matchString - The string to be found (must not contain *)

upToEnd

protected java.lang.String upToEnd(StringExaminer iterator)

matchReverse

protected boolean matchReverse(java.lang.String patternStr,
                               StringExaminer probeIterator)

charsAreEqual

protected boolean charsAreEqual(char probeChar,
                                char patternChar)

endReached

protected boolean endReached(char character)

endNotReached

protected boolean endNotReached(char character)

getPatternChar

protected char getPatternChar(StringExaminer patternIterator,
                              char probeCh)

newExaminer

protected StringExaminer newExaminer(java.lang.String str)

ignoreCaseAsString

protected java.lang.String ignoreCaseAsString()

selectOrReject

protected java.lang.String[] selectOrReject(java.lang.String[] strings,
                                            boolean select)

inspectString

protected java.lang.String inspectString()

strUtil

protected StringUtil strUtil()

digitWildcard

protected java.lang.Character digitWildcard()

digitWildcard

protected void digitWildcard(java.lang.Character newValue)
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD