/**
 * Get the values of all groups (RegEx <code>(...)</code>) for the passed
 * value.<br>
 * Note: groups starting with "?:" are non-capturing groups (e.g.
 * <code>(?:a|b)</code>)
 *
 * @param sRegEx
 *        The regular expression containing the groups
 * @param sValue
 *        The value to check
 * @return <code>null</code> if the passed value does not match the regular
 *         expression. An empty array if the regular expression contains no
 *         capturing group.
 */
@Nullable
public static String [] getAllMatchingGroupValues (@Nonnull @RegEx final String sRegEx, @Nonnull final String sValue)
{
  final Matcher aMatcher = getMatcher (sRegEx, sValue);
  if (!aMatcher.find ())
  {
    // Values does not match RegEx
    return null;
  }

  // groupCount is excluding the .group(0) match!!!
  final int nGroupCount = aMatcher.groupCount ();
  final String [] ret = new String [nGroupCount];
  for (int i = 0; i < nGroupCount; ++i)
    ret[i] = aMatcher.group (i + 1);
  return ret;
}
 

protected AbstractPropertyAction(String name, @RegEx String... strPatterns)
{
    this.name = name;
    Pattern[] patterns = new Pattern[strPatterns.length];
    for (int i = 0; i < strPatterns.length; i++)
    {
        patterns[i] = Pattern.compile("^" + strPatterns[i] + "$");
    }
    this.patterns = List.of(patterns);
}
 

@Nonnull
public static String stringReplacePattern (@Nonnull @RegEx final String sRegEx,
                                           @Nonnull final String sValue,
                                           @Nullable final String sReplacement)
{
  // Avoid NPE on invalid replacement parameter
  return getMatcher (sRegEx, sValue).replaceAll (StringHelper.getNotNull (sReplacement));
}
 

@Nonnull
public static String stringReplacePattern (@Nonnull @RegEx final String sRegEx,
                                           @Nonnegative final int nOptions,
                                           @Nonnull final String sValue,
                                           @Nullable final String sReplacement)
{
  // Avoid NPE on invalid replacement parameter
  return getMatcher (sRegEx, nOptions, sValue).replaceAll (StringHelper.getNotNull (sReplacement));
}
 

/**
 * Check if the passed regular expression is invalid.<br>
 * Note: this method may be a performance killer, as it calls
 * {@link Pattern#compile(String)} each time, which is CPU intensive and has a
 * synchronization penalty.
 *
 * @param sRegEx
 *        The regular expression to validate. May not be <code>null</code>.
 * @return <code>true</code> if the pattern is valid, <code>false</code>
 *         otherwise.
 */
public static boolean isValidPattern (@Nonnull @RegEx final String sRegEx)
{
  try
  {
    Pattern.compile (sRegEx);
    return true;
  }
  catch (final PatternSyntaxException ex)
  {
    return false;
  }
}
 

public static void checkPatternConsistency (@Nonnull @RegEx final String sRegEx)
{
  // Check if a '$' is escaped if no digits follow
  int nIndex = 0;
  while (nIndex >= 0)
  {
    nIndex = sRegEx.indexOf ('$', nIndex);
    if (nIndex != -1)
    {
      if (nIndex == sRegEx.length () - 1)
      {
        // '$' at end of String is OK!
      }
      else
        // Is the "$" followed by an int (would indicate a replacement group)
        if (!Character.isDigit (sRegEx.charAt (nIndex + 1)))
        {
          if (nIndex + 1 < sRegEx.length () && sRegEx.charAt (nIndex + 1) == ')')
          {
            // "$" is the last char in a group "(...$)"
          }
          else
            if (nIndex > 0 && sRegEx.charAt (nIndex - 1) == '\\')
            {
              // '$' is quoted
            }
            else
              throw new IllegalArgumentException ("The passed regex '" +
                                                  sRegEx +
                                                  "' contains an unquoted '$' sign at index " +
                                                  nIndex +
                                                  "!");
        }

      // Move beyond the current $
      nIndex++;
    }
  }
}
 

public RegExPattern (@Nonnull @Nonempty @RegEx final String sRegEx, @Nonnegative final int nOptions)
{
  ValueEnforcer.notEmpty (sRegEx, "RegEx");
  ValueEnforcer.isGE0 (nOptions, "Options");
  m_sRegEx = sRegEx;
  m_nOptions = nOptions;

  if (areDebugConsistencyChecksEnabled ())
    checkPatternConsistency (sRegEx);
}
 

/**
 * @return The source regular expression string. Neither <code>null</code> nor
 *         empty.
 */
@Nonnull
@Nonempty
@RegEx
public String getRegEx ()
{
  return m_sRegEx;
}
 

public RegExPattern (@Nonnull @Nonempty @RegEx final String sRegEx)
{
  // Default: no options
  this (sRegEx, 0);
}
 

/**
 * Get a sub-list with all entries that have field names matching the passed
 * regular expression.
 *
 * @param sRegExp
 *        The regular expression to compare the entries against.
 * @return Never <code>null</code>.
 */
@Nonnull
@ReturnsMutableCopy
default IErrorList getListOfFieldsRegExp (@Nonnull @Nonempty @RegEx final String sRegExp)
{
  return getSubList (x -> x.hasErrorFieldName () &&
                          RegExHelper.stringMatchesPattern (sRegExp, x.getErrorFieldName ()));
}
 

/**
 * Split the passed text with the given regular expression. If you do not need
 * a regular expression, {@link StringHelper#getExploded(String, String)} is a
 * faster option.
 *
 * @param sText
 *        The text to be split. May be <code>null</code>.
 * @param sRegEx
 *        The regular expression to use for splitting. May neither be
 *        <code>null</code> nor empty.
 * @return An empty array if the text is <code>null</code>, a non-
 *         <code>null</code> array otherwise. If both text and regular
 *         expression are <code>null</code> an empty array is returned as well
 *         since the text parameter is checked first.
 */
@Nonnull
public static String [] getSplitToArray (@Nullable final CharSequence sText, @Nonnull @RegEx final String sRegEx)
{
  if (sText == null)
    return ArrayHelper.EMPTY_STRING_ARRAY;
  return RegExCache.getPattern (sRegEx).split (sText);
}
 

/**
 * 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,
 * {@link StringHelper#getExploded(String, String, int)} is a faster option.
 *
 * @param sText
 *        The text to be split. May be <code>null</code>.
 * @param sRegEx
 *        The regular expression to use for splitting. May neither be
 *        <code>null</code> nor empty.
 * @param nLimit
 *        The maximum number of tokens to return if the value is &gt; 0. If
 *        the value is &le; 0 it has no effect and all tokens are returned.
 * @return An empty array if the text is <code>null</code>, a non-
 *         <code>null</code> array otherwise. If both text and regular
 *         expression are <code>null</code> an empty array is returned as well
 *         since the text parameter is checked first.
 */
@Nonnull
public static String [] getSplitToArray (@Nullable final CharSequence sText,
                                         @Nonnull @RegEx final String sRegEx,
                                         @Nonnegative final int nLimit)
{
  ValueEnforcer.notNull (sRegEx, "RegEx");
  if (sText == null)
    return ArrayHelper.EMPTY_STRING_ARRAY;
  return RegExCache.getPattern (sRegEx).split (sText, nLimit);
}
 

/**
 * Split the passed text with the given regular expression. If you do not need
 * a regular expression, {@link StringHelper#getExploded(String, String)} is a
 * faster option.
 *
 * @param sText
 *        The text to be split. May be <code>null</code>.
 * @param sRegEx
 *        The regular expression to use for splitting. May neither be
 *        <code>null</code> nor empty.
 * @return An empty list if the text is <code>null</code>, a non-
 *         <code>null</code> list otherwise. If both text and regular
 *         expression are <code>null</code> an empty list is returned as well
 *         since the text parameter is checked first.
 */
@Nonnull
public static ICommonsList <String> getSplitToList (@Nullable final CharSequence sText,
                                                    @Nonnull @RegEx final String sRegEx)
{
  return new CommonsArrayList <> (getSplitToArray (sText, sRegEx));
}
 

/**
 * Split the passed text with the given regular expression. If you do not need
 * a regular expression, {@link StringHelper#getExploded(String, String, int)}
 * is a faster option.
 *
 * @param sText
 *        The text to be split. May be <code>null</code>.
 * @param sRegEx
 *        The regular expression to use for splitting. May neither be
 *        <code>null</code> nor empty.
 * @param nLimit
 *        The maximum number of tokens to return if the value is &gt; 0. If
 *        the value is &le; 0 it has no effect and all tokens are returned.
 * @return An empty list if the text is <code>null</code>, a non-
 *         <code>null</code> list otherwise. If both text and regular
 *         expression are <code>null</code> an empty list is returned as well
 *         since the text parameter is checked first.
 */
@Nonnull
public static ICommonsList <String> getSplitToList (@Nullable final CharSequence sText,
                                                    @Nonnull @RegEx final String sRegEx,
                                                    @Nonnegative final int nLimit)
{
  return new CommonsArrayList <> (getSplitToArray (sText, sRegEx, nLimit));
}
 

/**
 * Get the Java Matcher object for the passed pair of regular expression and
 * value.
 *
 * @param sRegEx
 *        The regular expression to use. May neither be <code>null</code> nor
 *        empty.
 * @param sValue
 *        The value to create the matcher for. May not be <code>null</code>.
 * @return A non-<code>null</code> matcher.
 */
@Nonnull
public static Matcher getMatcher (@Nonnull @RegEx final String sRegEx, @Nonnull final String sValue)
{
  ValueEnforcer.notNull (sValue, "Value");

  return RegExCache.getPattern (sRegEx).matcher (sValue);
}
 

/**
 * Get the Java Matcher object for the passed pair of regular expression and
 * value.
 *
 * @param sRegEx
 *        The regular expression to use. May neither be <code>null</code> nor
 *        empty.
 * @param nOptions
 *        The pattern compilations options to be used.
 * @param sValue
 *        The value to create the matcher for. May not be <code>null</code>.
 * @return A non-<code>null</code> matcher.
 * @see Pattern#compile(String, int)
 */
@Nonnull
public static Matcher getMatcher (@Nonnull @RegEx final String sRegEx,
                                  @Nonnegative final int nOptions,
                                  @Nonnull final String sValue)
{
  ValueEnforcer.notNull (sValue, "Value");

  return RegExCache.getPattern (sRegEx, nOptions).matcher (sValue);
}
 

/**
 * A shortcut helper method to determine whether a string matches a certain
 * regular expression or not.
 *
 * @param sRegEx
 *        The regular expression to be used. The compiled regular expression
 *        pattern is cached. May neither be <code>null</code> nor empty.
 * @param nOptions
 *        The pattern compilations options to be used.
 * @param sValue
 *        The string value to compare against the regular expression.
 * @return <code>true</code> if the string matches the regular expression,
 *         <code>false</code> otherwise.
 * @see Pattern#compile(String, int)
 */
public static boolean stringMatchesPattern (@Nonnull @RegEx final String sRegEx,
                                            @Nonnegative final int nOptions,
                                            @Nonnull final String sValue)
{
  return getMatcher (sRegEx, nOptions, sValue).matches ();
}
 

/**
 * A shortcut helper method to determine whether a string matches a certain
 * regular expression or not.
 *
 * @param sRegEx
 *        The regular expression to be used. The compiled regular expression
 *        pattern is cached. May neither be <code>null</code> nor empty.
 * @param sValue
 *        The string value to compare against the regular expression.
 * @return <code>true</code> if the string matches the regular expression,
 *         <code>false</code> otherwise.
 */
public static boolean stringMatchesPattern (@Nonnull @RegEx final String sRegEx, @Nonnull final String sValue)
{
  return getMatcher (sRegEx, sValue).matches ();
}
 

/**
 * Get the cached regular expression pattern.
 *
 * @param sRegEx
 *        The regular expression to retrieve. May neither be <code>null</code>
 *        nor empty.
 * @return The compiled regular expression pattern and never <code>null</code>
 *         .
 * @throws IllegalArgumentException
 *         If the passed regular expression has an illegal syntax
 */
@Nonnull
public static Pattern getPattern (@Nonnull @Nonempty @RegEx final String sRegEx)
{
  return getInstance ().getFromCache (new RegExPattern (sRegEx));
}
 

/**
 * Get the cached regular expression pattern.
 *
 * @param sRegEx
 *        The regular expression to retrieve. May neither be <code>null</code>
 *        nor empty.
 * @param nOptions
 *        The options used for Pattern.compile
 * @return The compiled regular expression pattern and never <code>null</code>
 *         .
 * @see Pattern#compile(String, int)
 * @throws IllegalArgumentException
 *         If the passed regular expression has an illegal syntax
 */
@Nonnull
public static Pattern getPattern (@Nonnull @Nonempty @RegEx final String sRegEx, @Nonnegative final int nOptions)
{
  return getInstance ().getFromCache (new RegExPattern (sRegEx, nOptions));
}