Package org.checkerframework.checker.regex.util

Class RegexUtil

  • @AnnotatedFor("nullness")
public final class RegexUtil
extends java.lang.Object
    Utility methods for regular expressions, most notably for testing whether a string is a regular expression.

    For an example of intended use, see section Testing whether a string is a regular expression in the Checker Framework manual.

    Runtime Dependency: If you use this class, you must distribute (or link to) checker-qual.jar, along with your binaries. Or, you can copy this class into your own project.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static @Regex java.lang.String asRegex​(java.lang.String s)
      Returns the argument as a @Regex String if it is a regex, otherwise throws an error.
      static @Regex java.lang.String asRegex​(java.lang.String s, int groups)
      Returns the argument as a @Regex(groups) String if it is a regex with at least the given number of groups, otherwise throws an error.
      static boolean everyStringMatchesSomeRegex​(java.util.Collection<java.lang.String> strings, java.util.Collection<@Regex java.lang.String> regexes)
      Return true if every string is matched by at least one regex.
      static boolean isRegex​(char c)
      Returns true if the argument is a syntactically valid regular expression.
      static boolean isRegex​(java.lang.String s)
      Returns true if the argument is a syntactically valid regular expression.
      static boolean isRegex​(java.lang.String s, int groups)
      Returns true if the argument is a syntactically valid regular expression with at least the given number of groups.
      static <@KeyForBottom FROM extends @Nullable @UnknownKeyFor java.lang.Object,​@KeyForBottom TO extends @Nullable @UnknownKeyFor java.lang.Object>
      java.util.List<TO>      		 mapList​(java.util.function.Function<? super @KeyForBottom FROM,​? extends @KeyForBottom TO> f, java.lang.Iterable<@KeyForBottom FROM> iterable)
      Applies the function to each element of the given iterable, producing a list of the results.
      static java.util.List<java.lang.String> matchesNoRegex​(java.util.Collection<java.lang.String> strings, java.util.Collection<@Regex java.lang.String> regexes)
      Return the strings that are matched by no regex.
      static java.util.List<java.lang.String> matchesSomeRegex​(java.util.Collection<java.lang.String> strings, java.util.Collection<@Regex java.lang.String> regexes)
      Return the strings such that any one of the regexes matches it.
      static boolean noStringMatchesAnyRegex​(java.util.Collection<java.lang.String> strings, java.util.Collection<@Regex java.lang.String> regexes)
      Return true if no string is matched by any regex.
      static @Nullable java.lang.String regexError​(java.lang.String s)
      Returns null if the argument is a syntactically valid regular expression.
      static @Nullable java.lang.String regexError​(java.lang.String s, int groups)
      Returns null if the argument is a syntactically valid regular expression with at least the given number of groups.
      static @Nullable java.util.regex.PatternSyntaxException regexException​(java.lang.String s)
      Returns null if the argument is a syntactically valid regular expression.
      static @Nullable java.util.regex.PatternSyntaxException regexException​(java.lang.String s, int groups)
      Returns null if the argument is a syntactically valid regular expression with at least the given number of groups.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • isRegex

        @Pure
@EnsuresQualifierIf(result=true,
                    expression="#1",
                    qualifier=Regex.class)
public static boolean isRegex​(java.lang.String s)
        Returns true if the argument is a syntactically valid regular expression.
        Parameters:
        s - string to check for being a regular expression
        Returns:
        true iff s is a regular expression

      • isRegex

        @Pure
@EnsuresQualifierIf(result=true,
                    expression="#1",
                    qualifier=Regex.class)
public static boolean isRegex​(java.lang.String s,
                              int groups)
        Returns true if the argument is a syntactically valid regular expression with at least the given number of groups.
        Parameters:
        s - string to check for being a regular expression
        groups - number of groups expected
        Returns:
        true iff s is a regular expression with groups groups

      • isRegex

        @Pure
@EnsuresQualifierIf(result=true,
                    expression="#1",
                    qualifier=Regex.class)
public static boolean isRegex​(char c)
        Returns true if the argument is a syntactically valid regular expression.
        Parameters:
        c - char to check for being a regular expression
        Returns:
        true iff c is a regular expression

      • asRegex

        @SideEffectFree
public static @Regex java.lang.String asRegex​(java.lang.String s)
        Returns the argument as a @Regex String if it is a regex, otherwise throws an error. The purpose of this method is to suppress Regex Checker warnings. It should be very rarely needed.
        Parameters:
        s - string to check for being a regular expression
        Returns:
        its argument
        Throws:
        java.lang.Error - if argument is not a regex

      • asRegex

        @SideEffectFree
public static @Regex java.lang.String asRegex​(java.lang.String s,
                                              int groups)
        Returns the argument as a @Regex(groups) String if it is a regex with at least the given number of groups, otherwise throws an error. The purpose of this method is to suppress Regex Checker warnings. It should be very rarely needed.
        Parameters:
        s - string to check for being a regular expression
        groups - number of groups expected
        Returns:
        its argument
        Throws:
        java.lang.Error - if argument is not a regex

      • regexError

        @SideEffectFree
public static @Nullable java.lang.String regexError​(java.lang.String s)
        Returns null if the argument is a syntactically valid regular expression. Otherwise returns a string describing why the argument is not a regex.
        Parameters:
        s - string to check for being a regular expression
        Returns:
        null, or a string describing why the argument is not a regex

      • regexError

        @SideEffectFree
public static @Nullable java.lang.String regexError​(java.lang.String s,
                                                    int groups)
        Returns null if the argument is a syntactically valid regular expression with at least the given number of groups. Otherwise returns a string describing why the argument is not a regex.
        Parameters:
        s - string to check for being a regular expression
        groups - number of groups expected
        Returns:
        null, or a string describing why the argument is not a regex

      • regexException

        @SideEffectFree
public static @Nullable java.util.regex.PatternSyntaxException regexException​(java.lang.String s)
        Returns null if the argument is a syntactically valid regular expression. Otherwise returns a PatternSyntaxException describing why the argument is not a regex.
        Parameters:
        s - string to check for being a regular expression
        Returns:
        null, or a PatternSyntaxException describing why the argument is not a regex

      • regexException

        @SideEffectFree
public static @Nullable java.util.regex.PatternSyntaxException regexException​(java.lang.String s,
                                                                              int groups)
        Returns null if the argument is a syntactically valid regular expression with at least the given number of groups. Otherwise returns a PatternSyntaxException describing why the argument is not a regex.
        Parameters:
        s - string to check for being a regular expression
        groups - number of groups expected
        Returns:
        null, or a PatternSyntaxException describing why the argument is not a regex

      • matchesSomeRegex

        public static java.util.List<java.lang.String> matchesSomeRegex​(java.util.Collection<java.lang.String> strings,
                                                                java.util.Collection<@Regex java.lang.String> regexes)
        Return the strings such that any one of the regexes matches it.
        Parameters:
        strings - a collection of strings
        regexes - a collection of regular expressions
        Returns:
        the strings such that any one of the regexes matches it

      • everyStringMatchesSomeRegex

        public static boolean everyStringMatchesSomeRegex​(java.util.Collection<java.lang.String> strings,
                                                  java.util.Collection<@Regex java.lang.String> regexes)
        Return true if every string is matched by at least one regex.
        Parameters:
        strings - a collection of strings
        regexes - a collection of regular expressions
        Returns:
        true if every string is matched by at least one regex

      • matchesNoRegex

        public static java.util.List<java.lang.String> matchesNoRegex​(java.util.Collection<java.lang.String> strings,
                                                              java.util.Collection<@Regex java.lang.String> regexes)
        Return the strings that are matched by no regex.
        Parameters:
        strings - a collection of strings
        regexes - a collection of regular expressions
        Returns:
        the strings such that none of the regexes matches it

      • noStringMatchesAnyRegex

        public static boolean noStringMatchesAnyRegex​(java.util.Collection<java.lang.String> strings,
                                              java.util.Collection<@Regex java.lang.String> regexes)
        Return true if no string is matched by any regex.
        Parameters:
        strings - a collection of strings
        regexes - a collection of regular expressions
        Returns:
        true if no string is matched by any regex

      • mapList

        public static <@KeyForBottom FROM extends @Nullable @UnknownKeyFor java.lang.Object,​@KeyForBottom TO extends @Nullable @UnknownKeyFor java.lang.Object> java.util.List<TO> mapList​(java.util.function.Function<? super @KeyForBottom FROM,​? extends @KeyForBottom TO> f,
                                                                                                                                                                                         java.lang.Iterable<@KeyForBottom FROM> iterable)
        Applies the function to each element of the given iterable, producing a list of the results.

        The point of this method is to make mapping operations more concise. Import it with 

        import static org.plumelib.util.CollectionsPlume.mapList;
        This method is just like transform, but with the arguments in the other order.

        To perform replacement in place, see List.replaceAll.

        Type Parameters:
        FROM - the type of elements of the given iterable
        TO - the type of elements of the result list
        Parameters:
        f - a function
        iterable - an iterable
        Returns:
        a list of the results of applying f to the elements of iterable