com.phloc.commons.regex

Class RegExHelper

java.lang.Object

com.phloc.commons.regex.RegExHelper

@Immutable
public final class RegExHelper
extends Object

This class offers helper methods that work on cached regular expression pattern as offered by RegExPool.

Author:

Philip Helger

Method Summary

Methods

Modifier and Type	Method and Description
static String[]	getAllMatchingGroupValues(String sRegEx, String sValue) Get the values of all groups (RegEx (...)
static String	getAsIdentifier(String s) Convert an identifier to a programming language identifier by replacing all non-word characters with an underscore ("_").
static String	getAsIdentifier(String s, char cReplacement) Convert an identifier to a programming language identifier by replacing all non-word characters with an underscore.
static String	getAsIdentifier(String s, String sReplacement) Convert an identifier to a programming language identifier by replacing all non-word characters with an underscore.
static Matcher	getMatcher(String sRegEx, int nOptions, String sValue) Get the Java Matcher object for the passed pair of regular expression and value.
static Matcher	getMatcher(String sRegEx, String sValue) Get the Java Matcher object for the passed pair of regular expression and value.
static String[]	getSplitToArray(CharSequence sText, String sRegEx) Split the passed text with the given regular expression.
static String[]	getSplitToArray(CharSequence sText, String sRegEx, int nLimit) Split the passed text with the given regular expression returning at most the given number of tokens.
static List<String>	getSplitToList(CharSequence sText, String sRegEx) Split the passed text with the given regular expression.
static List<String>	getSplitToList(CharSequence sText, String sRegEx, int nLimit) Split the passed text with the given regular expression.
static boolean	isValidPattern(String sRegEx) Check if the passed regular expression is invalid.
static boolean	stringMatchesPattern(String sRegEx, int nOptions, String sValue) A shortcut helper method to determine whether a string matches a certain regular expression or not.
static boolean	stringMatchesPattern(String sRegEx, String sValue) A shortcut helper method to determine whether a string matches a certain regular expression or not.
static String	stringReplacePattern(String sRegEx, int nOptions, String sValue, String sReplacement)
static String	stringReplacePattern(String sRegEx, String sValue, String sReplacement)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getSplitToArray

@Nonnull
public static String[] getSplitToArray(@Nullable
                               CharSequence sText,
                               @Nonnull@RegEx
                               String sRegEx)

Split the passed text with the given regular expression. If you do not need a regular expression, StringHelper.getExploded(String, String) is a faster option.

Parameters:

sText - The text to be split. May be null.

sRegEx - The regular expression to use for splitting. May neither be null nor empty.

Returns:

An empty array if the text is null, a non- null array otherwise. If both text and regular expression are null an empty array is returned as well since the text parameter is checked first.

getSplitToArray

@Nonnull
public static String[] getSplitToArray(@Nullable
                               CharSequence sText,
                               @Nonnull@RegEx
                               String sRegEx,
                               @Nonnegative
                               int nLimit)

Split the passed text with the given regular expression returning at most the given number of tokens. If you do not need a regular expression, StringHelper.getExploded(String, String, int) is a faster option.

Parameters:

sText - The text to be split. May be null.

sRegEx - The regular expression to use for splitting. May neither be null nor empty.

nLimit - The maximum number of tokens to return if the value is > 0. If the value is ≤ 0 it has no effect and all tokens are returned.

Returns:

An empty array if the text is null, a non- null array otherwise. If both text and regular expression are null an empty array is returned as well since the text parameter is checked first.

getSplitToList

@Nonnull
public static List<String> getSplitToList(@Nullable
                                  CharSequence sText,
                                  @Nonnull@RegEx
                                  String sRegEx)

Split the passed text with the given regular expression. If you do not need a regular expression, StringHelper.getExploded(String, String) is a faster option.

Parameters:

sText - The text to be split. May be null.

sRegEx - The regular expression to use for splitting. May neither be null nor empty.

Returns:

An empty list if the text is null, a non- null list otherwise. If both text and regular expression are null an empty list is returned as well since the text parameter is checked first.

getSplitToList

@Nonnull
public static List<String> getSplitToList(@Nullable
                                  CharSequence sText,
                                  @Nonnull@RegEx
                                  String sRegEx,
                                  @Nonnegative
                                  int nLimit)

Split the passed text with the given regular expression. If you do not need a regular expression, StringHelper.getExploded(String, String, int) is a faster option.

Parameters:

sText - The text to be split. May be null.

sRegEx - The regular expression to use for splitting. May neither be null nor empty.

nLimit - The maximum number of tokens to return if the value is > 0. If the value is ≤ 0 it has no effect and all tokens are returned.

Returns:

An empty list if the text is null, a non- null list otherwise. If both text and regular expression are null an empty list is returned as well since the text parameter is checked first.

getMatcher

@Nonnull
public static Matcher getMatcher(@Nonnull@RegEx
                         String sRegEx,
                         @Nonnull
                         String sValue)

Get the Java Matcher object for the passed pair of regular expression and value.

Parameters:

sRegEx - The regular expression to use. May neither be null nor empty.

sValue - The value to create the matcher for. May not be null.

Returns:

A non-null matcher.

getMatcher

@Nonnull
public static Matcher getMatcher(@Nonnull@RegEx
                         String sRegEx,
                         @Nonnegative
                         int nOptions,
                         @Nonnull
                         String sValue)

Get the Java Matcher object for the passed pair of regular expression and value.

Parameters:

sRegEx - The regular expression to use. May neither be null nor empty.

nOptions - The pattern compilations options to be used.

sValue - The value to create the matcher for. May not be null.

Returns:

A non-null matcher.

See Also:

Pattern.compile(String, int)

stringMatchesPattern

public static boolean stringMatchesPattern(@Nonnull@RegEx
                           String sRegEx,
                           @Nonnull
                           String sValue)

A shortcut helper method to determine whether a string matches a certain regular expression or not.

Parameters:

sRegEx - The regular expression to be used. The compiled regular expression pattern is cached. May neither be null nor empty.

sValue - The string value to compare against the regular expression.

Returns:

true if the string matches the regular expression, false otherwise.

stringMatchesPattern

public static boolean stringMatchesPattern(@Nonnull@RegEx
                           String sRegEx,
                           @Nonnegative
                           int nOptions,
                           @Nonnull
                           String sValue)

A shortcut helper method to determine whether a string matches a certain regular expression or not.

Parameters:

sRegEx - The regular expression to be used. The compiled regular expression pattern is cached. May neither be null nor empty.

nOptions - The pattern compilations options to be used.

sValue - The string value to compare against the regular expression.

Returns:

true if the string matches the regular expression, false otherwise.

See Also:

Pattern.compile(String, int)

stringReplacePattern

@Nonnull
public static String stringReplacePattern(@Nonnull@RegEx
                                  String sRegEx,
                                  @Nonnull
                                  String sValue,
                                  @Nullable
                                  String sReplacement)

stringReplacePattern

@Nonnull
public static String stringReplacePattern(@Nonnull@RegEx
                                  String sRegEx,
                                  @Nonnegative
                                  int nOptions,
                                  @Nonnull
                                  String sValue,
                                  @Nullable
                                  String sReplacement)

getAsIdentifier

@Nullable
public static String getAsIdentifier(@Nullable
                              String s)

Convert an identifier to a programming language identifier by replacing all non-word characters with an underscore ("_").

Parameters:

s - The string to convert. May be null or empty.

Returns:

The converted string or null if the input string is null.

getAsIdentifier

@Nullable
public static String getAsIdentifier(@Nullable
                              String s,
                              char cReplacement)

Convert an identifier to a programming language identifier by replacing all non-word characters with an underscore.

Parameters:

s - The string to convert. May be null or empty.

cReplacement - The replacement character to be used for all non-identifier characters

Returns:

The converted string or null if the input string is null.

getAsIdentifier

@Nullable
public static String getAsIdentifier(@Nullable
                              String s,
                              @Nonnull
                              String sReplacement)

Convert an identifier to a programming language identifier by replacing all non-word characters with an underscore.

Parameters:

s - The string to convert. May be null or empty.

sReplacement - The replacement string to be used for all non-identifier characters. May be empty but not be null.

Returns:

The converted string or null if the input string is null. Maybe an invalid identifier, if the replacement is empty, and the identifier starts with an illegal character, or if the replacement is empty and the source string only contains invalid characters!

isValidPattern

public static boolean isValidPattern(@Nonnull@RegEx
                     String sRegEx)

Check if the passed regular expression is invalid.
Note: this method may be a performance killer, as it calls Pattern.compile(String) each time, which is CPU intensive and has a synchronization penalty.

Parameters:

sRegEx - The regular expression to validate. May not be null.

Returns:

true if the pattern is valid, false otherwise.

getAllMatchingGroupValues

@Nullable
public static String[] getAllMatchingGroupValues(@Nonnull@RegEx
                                          String sRegEx,
                                          @Nonnull
                                          String sValue)

Get the values of all groups (RegEx (...)) for the passed value.
Note: groups starting with "?:" are non-capturing groups (e.g. (?:a|b))

Parameters:

sRegEx - The regular expression containing the groups

sValue - The value to check

Returns:

null if the passed value does not match the regular expression. An empty array if the regular expression contains no capturing group.