Package rife.bld.extension.tools

Class TextTools

java.lang.Object
rife.bld.extension.tools.TextTools
@NullMarked public final class TextTools extends Object
Utility methods for working with text and character sequences.

Provides null‑safe checks for blankness and emptiness across CharSequence and general Object inputs, along with a whitespace‑insensitive equality comparison.

Since:
1.0
Author:
Erik C. Thauvin

  • Method Details

    • equalsIgnoreWhitespace

      public static boolean equalsIgnoreWhitespace(@Nullable CharSequence @Nullable ... strings)
      Compares two or more character sequences by removing all whitespace.
      Parameters:
      strings - the character sequences to compare
      Returns:
      true if all character sequences are equivalent when whitespace is ignored, false otherwise. Returns false if null or fewer than 2 elements
      Since:
      1.0
      Implementation Note:
      null elements within the array are treated as empty strings, so equalsIgnoreWhitespace(null, "") returns true.

    • isBlank

      public static boolean isBlank(@Nullable CharSequence str)
      Checks if a character sequence is null, empty, or contains only whitespace characters.
      Parameters:
      str - the character sequence to check
      Returns:
      true if the character sequence is null, empty, or whitespace-only; false otherwise
      Since:
      1.0

    • isBlank

      public static boolean isBlank(@Nullable CharSequence @Nullable ... strings)
      Checks if all character sequences are null, empty, or contain only whitespace characters.
      Parameters:
      strings - the character sequences to check
      Returns:
      true if all character sequences are null, empty, or whitespace-only; false otherwise. Returns true for null or empty array (vacuous truth)
      Since:
      1.0

    • isBlank

      public static boolean isBlank(@Nullable Object @Nullable ... objects)
      Checks if all objects are null, empty, or contain only whitespace characters.

      CharSequence instances are checked directly; all other objects are checked via their Object.toString() representation. This varargs overload exists to support mixed-type arrays — prefer the CharSequence... overload for homogeneous inputs.

      Parameters:
      objects - the objects to check
      Returns:
      true if all objects are null, their string representations are empty, or their string representations are whitespace-only; false otherwise. Returns true for null or empty array (vacuous truth)
      Since:
      1.0

    • isEmpty

      public static boolean isEmpty(@Nullable CharSequence str)
      Checks if a character sequence is null or empty.
      Parameters:
      str - the character sequence to check
      Returns:
      true if the character sequence is null or empty; false otherwise
      Since:
      1.0

    • isEmpty

      public static boolean isEmpty(@Nullable CharSequence @Nullable ... strings)
      Checks if all character sequences are null or empty.
      Parameters:
      strings - the character sequences to check
      Returns:
      true if all character sequences are null or empty; false otherwise. Returns true for null or empty array (vacuous truth)
      Since:
      1.0

    • isEmpty

      public static boolean isEmpty(@Nullable Object @Nullable ... objects)
      Checks if all objects are null or their string representations are empty.

      CharSequence instances are checked directly; all other objects are checked via their Object.toString() representation. This varargs overload exists to support mixed-type arrays — prefer the CharSequence... overload for homogeneous inputs.

      Parameters:
      objects - the objects to check
      Returns:
      true if all objects are null or their string representations are empty; false otherwise. Returns true for null or empty array (vacuous truth)
      Since:
      1.0

    • isNotBlank

      public static boolean isNotBlank(@Nullable CharSequence str)
      Checks if a character sequence is not null, not empty, and not whitespace-only.
      Parameters:
      str - the character sequence to check
      Returns:
      true if the character sequence is not null, not empty, and not whitespace-only; false otherwise
      Since:
      1.0

    • isNotBlank

      public static boolean isNotBlank(@Nullable CharSequence @Nullable ... strings)
      Checks if all character sequences are not null, not empty, and not whitespace-only.
      Parameters:
      strings - the character sequences to check
      Returns:
      true if all character sequences are not null, not empty, and not whitespace-only; false otherwise. Returns false for null or empty array
      Since:
      1.0

    • isNotBlank

      public static boolean isNotBlank(@Nullable Object @Nullable ... objects)
      Checks if all objects are not null, not empty, and not whitespace-only.

      CharSequence instances are checked directly; all other objects are checked via their Object.toString() representation. This varargs overload exists to support mixed-type arrays — prefer the CharSequence... overload for homogeneous inputs.

      Parameters:
      objects - the objects to check
      Returns:
      true if all objects are not null, their string representations are not empty, and their string representations are not whitespace-only; false otherwise
      Since:
      1.0

    • isNotEmpty

      public static boolean isNotEmpty(@Nullable CharSequence str)
      Checks if a character sequence is not null and not empty.
      Parameters:
      str - the character sequence to check
      Returns:
      true if the character sequence is not null and not empty; false otherwise
      Since:
      1.0

    • isNotEmpty

      public static boolean isNotEmpty(@Nullable CharSequence @Nullable ... strings)
      Checks if all character sequences are not null and not empty.
      Parameters:
      strings - the character sequences to check
      Returns:
      true if all character sequences are not null and not empty; false otherwise. Returns false for null or empty array
      Since:
      1.0

    • isNotEmpty

      public static boolean isNotEmpty(@Nullable Object @Nullable ... objects)
      Checks if all objects are not null and their string representations are not empty.

      CharSequence instances are checked directly; all other objects are checked via their Object.toString() representation. This varargs overload exists to support mixed-type arrays — prefer the CharSequence... overload for homogeneous inputs.

      Parameters:
      objects - the objects to check
      Returns:
      true if all objects are not null and their string representations are not empty; false otherwise
      Since:
      1.0

    • requireNotBlank

      @Contract("null, _, _ -> fail;!null, _, _ ->!null") @NullUnmarked public static <T extends @Nullable Object & CharSequence> @NonNull T requireNotBlank(@Nullable T str, @NonNull Supplier<String> nullMessage, @NonNull Supplier<String> blankMessage)
      Checks that the specified character sequence is not null, not empty, and not whitespace-only.
      Type Parameters:
      T - the type of the character sequence
      Parameters:
      str - the character sequence to check
      nullMessage - the supplier of the NullPointerException message; must not be null
      blankMessage - the supplier of the IllegalArgumentException message; must not be null
      Returns:
      str if not blank
      Throws:
      NullPointerException - if str is null
      IllegalArgumentException - if str is empty or whitespace-only
      Since:
      1.0

    • requireNotBlank

      @Contract("null, _ -> fail;!null, _ ->!null") @NullUnmarked public static <T extends @Nullable Object & CharSequence> @NonNull T requireNotBlank(@Nullable T str, @NonNull String context)
      Checks that the specified character sequence is not null, not empty, and not whitespace-only.
      Type Parameters:
      T - the type of the character sequence
      Parameters:
      str - the character sequence to check
      context - the context description used in the exception messages
      Returns:
      str if not blank
      Throws:
      NullPointerException - if str or context is null
      IllegalArgumentException - if str is empty or whitespace-only
      Since:
      1.0

    • requireNotBlank

      @Contract("null, _, _ -> fail;!null, _, _ ->!null") @NullUnmarked public static <T extends CharSequence> @NonNull Collection<@NonNull T> requireNotBlank(@Nullable Collection<@Nullable T> coll, @NonNull Supplier<String> nullMessage, @NonNull Supplier<String> blankMessage)
      Checks that the specified collection of character sequences is not null, not empty, and contains no null, empty, or whitespace-only elements.
      Type Parameters:
      T - the type of the character sequence
      Parameters:
      coll - the collection to check
      nullMessage - the supplier of the NullPointerException message; must not be null
      blankMessage - the supplier of the IllegalArgumentException message; must not be null
      Returns:
      coll if valid
      Throws:
      NullPointerException - if coll is null or contains null elements
      IllegalArgumentException - if coll is empty or contains blank elements
      Since:
      1.0

    • requireNotBlank

      @Contract("null, _ -> fail;!null, _ ->!null") @NullUnmarked public static <T extends CharSequence> @NonNull Collection<@NonNull T> requireNotBlank(@Nullable Collection<@Nullable T> coll, @NonNull String context)
      Checks that the specified collection of character sequences is not null, not empty, and contains no null, empty, or whitespace-only elements.
      Type Parameters:
      T - the type of the character sequence
      Parameters:
      coll - the collection to check
      context - the context description used in the exception messages
      Returns:
      coll if valid
      Throws:
      NullPointerException - if coll is null or contains null elements
      IllegalArgumentException - if coll is empty or contains blank elements
      Since:
      1.0

    • requireNotBlank

      @Contract("_, _, null -> fail; _, _,!null ->!null") @NullUnmarked @SafeVarargs public static <T extends CharSequence> @NonNull T @NonNull [] requireNotBlank(@NonNull Supplier<String> nullMessage, @NonNull Supplier<String> blankMessage, @Nullable T @Nullable ... elements)
      Checks that the specified varargs array of character sequences is not null, not empty, and contains no null, empty, or whitespace-only elements.
      Type Parameters:
      T - the type of the character sequence
      Parameters:
      nullMessage - the supplier of the NullPointerException message; must not be null
      blankMessage - the supplier of the IllegalArgumentException message; must not be null
      elements - the elements to check
      Returns:
      elements if valid
      Throws:
      NullPointerException - if elements is null or contains null elements
      IllegalArgumentException - if elements is empty or contains blank elements
      Since:
      1.0

    • requireNotBlank

      @Contract("_, null -> fail; _,!null ->!null") @NullUnmarked @SafeVarargs public static <T extends CharSequence> @NonNull T @NonNull [] requireNotBlank(@NonNull String context, @Nullable T @Nullable ... elements)
      Checks that the specified varargs array of character sequences is not null, not empty, and contains no null, empty, or whitespace-only elements.
      Type Parameters:
      T - the type of the character sequence
      Parameters:
      context - the context description used in the exception messages
      elements - the elements to check
      Returns:
      elements if valid
      Throws:
      NullPointerException - if elements is null or contains null elements
      IllegalArgumentException - if elements is empty or contains blank elements
      Since:
      1.0

    • requireNotEmpty

      @Contract("null, _, _ -> fail;!null, _, _ ->!null") @NullUnmarked public static <T extends @Nullable Object & CharSequence> @NonNull T requireNotEmpty(@Nullable T str, @NonNull Supplier<String> nullMessage, @NonNull Supplier<String> emptyMessage)
      Checks that the specified character sequence is not null and not empty.
      Type Parameters:
      T - the type of the character sequence
      Parameters:
      str - the character sequence to check
      nullMessage - the supplier of the NullPointerException message; must not be null
      emptyMessage - the supplier of the IllegalArgumentException message; must not be null
      Returns:
      str if not empty
      Throws:
      NullPointerException - if str is null
      IllegalArgumentException - if str is empty
      Since:
      1.0

    • requireNotEmpty

      @Contract("null, _ -> fail;!null, _ ->!null") @NullUnmarked public static <T extends @Nullable Object & CharSequence> @NonNull T requireNotEmpty(@Nullable T str, @NonNull String context)
      Checks that the specified character sequence is not null and not empty.
      Type Parameters:
      T - the type of the character sequence
      Parameters:
      str - the character sequence to check
      context - the context description used in the exception messages
      Returns:
      str if not empty
      Throws:
      NullPointerException - if str is null
      IllegalArgumentException - if str is empty
      Since:
      1.0

    • requireNotEmpty

      @Contract("null, _, _ -> fail;!null, _, _ ->!null") @NullUnmarked public static <T extends CharSequence> @NonNull Collection<@NonNull T> requireNotEmpty(@Nullable Collection<@Nullable T> coll, @NonNull Supplier<String> nullMessage, @NonNull Supplier<String> emptyMessage)
      Checks that the specified collection of character sequences is not null, not empty, and contains no null or empty elements.
      Type Parameters:
      T - the type of the character sequence
      Parameters:
      coll - the collection to check
      nullMessage - the supplier of the NullPointerException message; must not be null
      emptyMessage - the supplier of the IllegalArgumentException message; must not be null
      Returns:
      coll if valid
      Throws:
      NullPointerException - if coll is null or contains null elements
      IllegalArgumentException - if coll is empty or contains empty elements
      Since:
      1.0

    • requireNotEmpty

      @Contract("null, _ -> fail;!null, _ ->!null") @NullUnmarked public static <T extends CharSequence> @NonNull Collection<@NonNull T> requireNotEmpty(@Nullable Collection<@Nullable T> coll, @NonNull String context)
      Checks that the specified collection of character sequences is not null, not empty, and contains no null or empty elements.
      Type Parameters:
      T - the type of the character sequence
      Parameters:
      coll - the collection to check
      context - the context description used in the exception messages
      Returns:
      coll if valid
      Throws:
      NullPointerException - if coll is null or contains null elements
      IllegalArgumentException - if coll is empty or contains empty elements
      Since:
      1.0

    • requireNotEmpty

      @Contract("_, _, null -> fail; _, _,!null ->!null") @NullUnmarked @SafeVarargs public static <T extends CharSequence> @NonNull T @NonNull [] requireNotEmpty(@NonNull Supplier<String> nullMessage, @NonNull Supplier<String> emptyMessage, @Nullable T @Nullable ... elements)
      Checks that the specified varargs array of character sequences is not null, not empty, and contains no null or empty elements.
      Type Parameters:
      T - the type of the character sequence
      Parameters:
      nullMessage - the supplier of the NullPointerException message; must not be null
      emptyMessage - the supplier of the IllegalArgumentException message; must not be null
      elements - the elements to check
      Returns:
      elements if valid
      Throws:
      NullPointerException - if elements is null or contains null elements
      IllegalArgumentException - if elements is empty or contains empty elements
      Since:
      1.0

    • requireNotEmpty

      @Contract("_, null -> fail; _,!null ->!null") @NullUnmarked @SafeVarargs public static <T extends CharSequence> @NonNull T @NonNull [] requireNotEmpty(@NonNull String context, @Nullable T @Nullable ... elements)
      Checks that the specified varargs array of character sequences is not null, not empty, and contains no null or empty elements.
      Type Parameters:
      T - the type of the character sequence
      Parameters:
      context - the context description used in the exception messages
      elements - the elements to check
      Returns:
      elements if valid
      Throws:
      NullPointerException - if elements is null or contains null elements
      IllegalArgumentException - if elements is empty or contains empty elements
      Since:
      1.0