Predicates

str_is_empty¶

Test if a string is empty (zero length).

Arguments¶

• $1 (string): The string to test

Exit codes¶

• 0: String is empty
• 1: String is not empty

str_is_blank¶

Test if a string is blank (empty or whitespace only).

Arguments¶

• $1 (string): The string to test

Exit codes¶

• 0: String is blank
• 1: String contains non-whitespace characters

str_starts_with¶

Test if a string starts with a given prefix.

Arguments¶

• $1 (string): The string to test
• $2 (string): The prefix to check for

Exit codes¶

• 0: String starts with prefix
• 1: String does not start with prefix

str_ends_with¶

Test if a string ends with a given suffix.

Arguments¶

• $1 (string): The string to test
• $2 (string): The suffix to check for

Exit codes¶

• 0: String ends with suffix
• 1: String does not end with suffix

str_contains¶

Test if a string contains a given substring.

Arguments¶

• $1 (string): The string to test
• $2 (string): The substring to check for

Exit codes¶

• 0: String contains substring
• 1: String does not contain substring

str_equal_fold¶

Test if two strings are equal ignoring case.

Arguments¶

• $1 (string): First string
• $2 (string): Second string

Exit codes¶

• 0: Strings are equal (case-insensitive)
• 1: Strings are not equal

str_match¶

Test whether a string matches a regex pattern (ERE). On success BASH_REMATCH is populated by the shell.

Example¶

str_match "hello world" "^hello"                             # 0
str_match "2024-03-19" "([0-9]{4})-([0-9]{2})-([0-9]{2})"
printf '%s\n' "${BASH_REMATCH[1]}"                           # => 2024

Arguments¶

• $1 (string): String to test
• $2 (string): Extended regex pattern

Exit codes¶

• 0: Match; 1 No match

str_match_captures¶

Match a string against a regex and populate a named array with the capture groups (BASH_REMATCH[0..n]). Requires bash 4.3+ for namerefs.

Example¶

str_match_captures "2024-03-19" "([0-9]{4})-([0-9]{2})-([0-9]{2})" parts
printf '%s\n' "${parts[1]}"   # => 2024
printf '%s\n' "${parts[2]}"   # => 03
printf '%s\n' "${parts[3]}"   # => 19

Arguments¶

• $1 (string): String to test
• $2 (string): Extended regex pattern
• $3 (string): Name of the caller's array variable to populate

Exit codes¶

• 0: Match found and array populated; 1 No match; 2 Missing argument

str_contains_only¶

Return 0 if the string is composed only of characters in the given set. An empty string always returns 0. A non-empty string against an empty set returns 1. The character set is used as a bracket expression: e.g. "a-z0-9", "[:alpha:]".

Example¶

str_contains_only ""     "abc"      # 0 — empty string always passes
str_contains_only "abab" "abc"      # 0 — only a, b, c
str_contains_only "ab1"  "a-z"      # 1 — digit not in set

Arguments¶

• $1 (string): The string to test
• $2 (string): Allowed character set (bracket expression)

Exit codes¶

• 0: String contains only characters from the set (or is empty)
• 1: String contains characters outside the set, or non-empty with empty set

str_is_alpha¶

Return 0 if the string contains only ASCII alphabetic characters (non-empty).

Arguments¶

• $1 (string): String to test

Exit codes¶

• 0: Non-empty and purely alphabetic; 1 otherwise

str_is_alnum¶

Return 0 if the string contains only ASCII alphanumeric characters (non-empty).

Arguments¶

• $1 (string): String to test

Exit codes¶

• 0: Non-empty and purely alphanumeric; 1 otherwise

str_is_digits¶

Return 0 if the string contains only ASCII digit characters (non-empty).

Arguments¶

• $1 (string): String to test

Exit codes¶

• 0: Non-empty and purely decimal digits; 1 otherwise

str_is_int¶

Return 0 if the string is a valid integer (optional leading minus, digits only). Differs from str_is_digits: allows a leading '-' sign. An empty string or bare '-' returns 1.

Example¶

str_is_int "42"    # => 0
str_is_int "-7"    # => 0
str_is_int "+7"    # => 1  (unary + not accepted)
str_is_int "3.14"  # => 1

Arguments¶

• $1 (string): String to test

Exit codes¶

• 0: Non-empty valid integer; 1 otherwise

str_is_hex¶

Return 0 if the string is a valid hexadecimal value. Case-insensitive. Accepts an optional 0x/0X prefix. An empty string or bare '0x'/'0X' returns 1.

Example¶

str_is_hex "DEADBEEF"   # => 0
str_is_hex "0xff"       # => 0
str_is_hex "0x"         # => 1  (no digits after prefix)
str_is_hex "0xGG"       # => 1

Arguments¶

• $1 (string): String to test

Exit codes¶

• 0: Non-empty valid hex string; 1 otherwise

str_is_base64¶

Return 0 if the string is valid base64-encoded content. Accepts both standard ('+', '/') and URL-safe ('_', '-') alphabets. Requires proper padding: length must be a multiple of 4; trailing '=' or '==' is allowed, but '=' may not appear elsewhere in the string.

Example¶

str_is_base64 "YWJj"     # => 0  ("abc")
str_is_base64 "YQ=="     # => 0  ("a")
str_is_base64 "YQ"       # => 1  (not padded to multiple of 4)
str_is_base64 "YQ==="    # => 1  (over-padded)
str_is_base64 "!!"       # => 1

Arguments¶

• $1 (string): String to test

Exit codes¶

• 0: Valid padded base64 string; 1 otherwise

str_is_upper¶

Return 0 if every letter character in the string is uppercase. Non-letter characters (digits, punctuation, etc.) are ignored. An empty string or a string with no letters passes.

Example¶

str_is_upper "HELLO"      # => 0
str_is_upper "HELLO123"   # => 0
str_is_upper "Hello"      # => 1
str_is_upper "123"        # => 0  (no letters to be wrong)

Arguments¶

• $1 (string): String to test

Exit codes¶

• 0: All letters are uppercase (or no letters present); 1 otherwise

str_is_lower¶

Return 0 if every letter character in the string is lowercase. Non-letter characters (digits, punctuation, etc.) are ignored. An empty string or a string with no letters passes.

Example¶

str_is_lower "hello"      # => 0
str_is_lower "hello123"   # => 0
str_is_lower "Hello"      # => 1
str_is_lower "123"        # => 0  (no letters to be wrong)

Arguments¶

• $1 (string): String to test

Exit codes¶

• 0: All letters are lowercase (or no letters present); 1 otherwise

str_is_email¶

Test if a string is a plausible email address. Checks structural format only — no DNS or deliverability checks.

Example¶

str_is_email "user@example.com"   # => exit 0
str_is_email "notanemail"          # => exit 1

Arguments¶

• $1 (string): String to test

Exit codes¶

• 0: Valid email format
• 1: Invalid format
• 2: Missing argument

str_matches¶

Test whether a string matches a regex, and print the first capture group if it does. Uses bash's =~ operator. Stick to POSIX ERE features for portability across systems, as bash delegates to the system's regex engine.

Example¶

  str_matches "hello world" "^hello (.+)"   # prints "world", exit 0
  str_matches "foo" "^bar"                  # exit 1
Adapted from dylanaraps/pure-bash-bible (MIT) https://github.com/dylanaraps/pure-bash-bible

Arguments¶

• $1 (string): String to test
• $2 (string): Extended regular expression

Exit codes¶

• 0: String matches the regex
• 1: String does not match

Output on stdout¶

• First capture group from BASH_REMATCH if the string matches