Cross-platform C SDK logo
EspañolEnglish
Cross-platform C SDK

Regular expressions

❮ Back
Next ❯

#Header

#include <core/regex.h>


#Functions

RegEx*regex_create (...)
voidregex_destroy (...)
bool_tregex_match (...)
bool_tregex_search (...)

Regular expressions define a text pattern that can be used to find or compare strings. NAppGUI follows the syntax of POSIX extended regular expressions (ERE), the one used by grep -E or awk, with the most common extensions of Perl supported by RE2. Patterns can be tested online at regex101.com by selecting the Golang flavor.

  • Use regex_create to create a regular expression.
  • Use regex_match to check if a whole string matches the pattern.
  • Use regex_search to find the first substring that matches the pattern.
  • Listing 1: Using regular expressions.
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    
    RegEx *regex = regex_create(".*\\.txt", NULL, NULL);
    
    const char_t *str[] = {
        "file01.txt",
        "image01.png",
        "sun01.jpg",
        "films.txt",
        "document.pdf"};
    
    uint32_t i, n = sizeof(str) / sizeof(char_t*);
    
    for (i = 0; i < n; ++i)
    {
        if (regex_match(regex, str[i]) == TRUE)
            bstd_printf("YES: %s\n", str[i]);
        else
            bstd_printf("NO:  %s\n", str[i]);
    }
    
    regex_destroy(®ex);
    
    Result of (Listing 1).
    1
    2
    3
    4
    5
    
    YES: file01.txt
    NO:  image01.png
    NO:  sun01.jpg
    YES: films.txt
    NO:  document.pdf
    
    Listing 2: Searching a pattern inside a string.
    1
    2
    3
    4
    5
    6
    7
    
    RegEx *regex = regex_create("[0-9]+\\.[0-9]+", NULL, NULL);
    uint32_t pos, len;
    
    if (regex_search(regex, "NAppGUI version 1.7", &pos, &len) == TRUE)
        bstd_printf("Found at %d, length %d\n", pos, len);
    
    regex_destroy(®ex);
    
    Result of (Listing 2).
    1
    
    Found at 16, length 3
    

#1. Define patterns

We can build a regular expression from a text string, following these rules:

  • A string pattern corresponds only to that same string. The characters . [ ] ( ) | * + ? { } ^ $ and the backslash have a special meaning and must be escaped to be used as characters.
  • Listing 3:
    "hello" --> {"hello"}
    
  • A period '.' is equivalent to "any character", except the new line.
  • Listing 4:
    "h.llo" --> {"hello", "htllo", "hällo", "h5llo", ...}
    
  • The brackets '[aeiou]' define a character class: any one of the characters inside. A dash between two characters sets a range, using the Unicode code from both ends. A circumflex at the beginning '[^aeiou]' negates the class.
  • Listing 5:
    "h[aeiou]llo" --> {"hallo", "hello", "hillo", "hollo", "hullo"}
    "[A-Z]ello"   --> {"Aello", "Bello", "Cello", ..., "Zello"}
    "[^0-9]"      --> {"a", "b", "-", "ñ", ...}
    
    '[A-Z]': (65-90) (ABCDEFGHIJKLMNOPQRSTUVWXYZ)
    '[0-9]': (48-57) (0123456789)
    '[á-ú]': (225-250) (áâãäåæçèéêëìíîïðñòóôõö÷øùú)
    
  • Inside the brackets, the special characters lose their meaning. A ']' at the beginning and a dash at the beginning or end are regular characters. Outside the brackets, the dash is always a regular character.
  • Listing 6:
    "[*.?]"  --> {"*", ".", "?"}
    "[]a]"   --> {"]", "a"}
    "[a-]"   --> {"a", "-"}
    "file-1" --> {"file-1"}
    
  • The POSIX classes (Table 1) can be used inside the brackets. They only include ASCII characters. The form [[:^alpha:]] negates any of them.
  • Listing 7:
    "[[:alpha:]]+"         --> {"a", "Hello", "XYZ", ...}
    "[[:digit:][:upper:]]" --> {"0", "9", "A", "Z", ...}
    
    Table 1: POSIX classes.
    Class Characters
    [:alnum:] Letters and digits.
    [:alpha:] Letters.
    [:ascii:] ASCII characters.
    [:blank:] Space and tab.
    [:cntrl:] Control characters.
    [:digit:] Digits.
    [:graph:] Visible characters.
    [:lower:] Lowercase letters.
    [:print:] Visible characters and space.
    [:punct:] Punctuation.
    [:space:] Whitespace.
    [:upper:] Uppercase letters.
    [:word:] Letters, digits and underscore.
    [:xdigit:] Hexadecimal digits.
Like String objects, patterns are expressed in UTF-8, therefore the entire Unicode set can be used to create regular expressions.
  • The vertical bar '|' separates alternatives. It has the lowest priority.
  • Listing 8:
    "hello|bye"  --> {"hello", "bye"}
    "h(e|a)llo"  --> {"hello", "hallo"}
    "red|blue|"  --> {"red", "blue", ""}
    
  • The parentheses '(he*llo)' allow grouping a regular expression, so that it behaves as a single character. The form '(?:...)' is also accepted.
  • Listing 9:
    "(hello)*"   --> {"", "hello", "hellohello", "hellohellohello", ... }
    "(he*llo)ZZ" --> {"hlloZZ", "helloZZ", "heelloZZ", "heeelloZZ", ... }
    
  • The quantifiers (Table 2) set how many times the previous element can appear.
  • Table 2: Quantifiers.
    Quantifier Repetitions
    * Zero or more times.
    + One or more times.
    ? Zero or one time.
    {m} Exactly m times.
    {m,} At least m times.
    {m,n} Between m and n times (maximum 1000).
    Listing 10:
    "he*llo"         --> {"hllo", "hello", "heello", "heeello", ...}
    "FILE_[0-9]*.PNG" --> {"FILE_.PNG", "FILE_0.PNG", "FILE_01.PNG", ...}
    "colou?r"        --> {"color", "colour"}
    "[a-z]+"         --> {"a", "b", "ab", "hello", ...}
    "[0-9]{2,4}"     --> {"12", "123", "1234"}
    
A quantifier followed by '?' (non-greedy in other engines) is accepted, but behaves as the normal one. See Match and search.
  • The circumflex '^' and the dollar '$' mark the beginning and the end of the string. They are useful with regex_search.
  • Listing 11:
    "^ERROR"  "ERROR: disk"  --> pos=0, len=5
    "^ERROR"  "disk ERROR"   --> FALSE
    "\.txt$"  "doc.txt"      --> pos=3, len=4
    
  • The backslash introduces escape sequences (Table 3).
  • Table 3: Escape sequences.
    Sequence Meaning
    \. \* \( \[ ... The special character itself.
    \t \n \r \f \v \a Control characters.
    \xhh \x{hhhh} Unicode character from its hexadecimal code.
    \d \D Digit [0-9] and its negation.
    \w \W Word character [0-9A-Za-z_] and its negation.
    \s \S Whitespace (space, tab, new line, carriage return, form feed) and its negation.
    \A \z Beginning and end of the string.
    Listing 12:
    "\(he\*\-llo\)"  --> {"(he*-llo)"}
    "\d{1,3}[dwmy]"  --> {"7d", "30w", "365y", ...}
    
Remember that for expressions inserted as constants in C code, the backslash character is represented by a double slash "\\(he\\*\\-llo\\)".

#2. Match and search

regex_match checks if the whole string matches the pattern. regex_search finds a substring that matches the pattern and returns its position and length, in characters. When there are several possible matches, it returns the one that starts at the leftmost position and, from there, the longest one (POSIX criteria).

Listing 13:
"[0-9]+"  "abc123def"  --> pos=3, len=3 ("123")
"a|ab"    "xab"        --> pos=1, len=2 ("ab")
"x*"      "bxx"        --> pos=0, len=0 ("")
"^ERR"    "disk ERR"   --> FALSE
"txt$"    "a.txt"      --> pos=2, len=3 ("txt")
Engines like Perl, Python or JavaScript return the first alternative that matches. With alternatives or quantifiers, the length of the match may be different. In "a|ab", they return "a" and NAppGUI returns "ab".

Some features of other engines are not supported. Most of them require backtracking and are incompatible with the finite automata, which guarantees a time linear to the length of the string.

  • Backreferences, lookahead and lookbehind.
  • Capture groups. All groups are non-capturing.
  • Flags (case insensitive, multiline), word boundaries and Unicode property classes.

#3. Regular languages ​​and automata

Regular languages ​​are those that are defined recursively using three basic operations on the set of characters (or symbols) available. They can be described using the regular expressions discussed above.

  • Each character 'a' is a regular language 'A'.
  • The union of two regular languages, is a regular language A∪B.
  • The concatenation of two regular languages, is a regular language A·B.
  • The closure of a regular language is a regular language A*. This is where recursion comes in.
In this context the symbols are all Unicode characters. But you can define languages ​​based on other alphabets, including the binary {0, 1}.

To recognize whether or not a string belongs to a certain regular language, it is necessary to build a Finite Automata based on the rules reflected in (Figure 1).

Figure 1: Construction of finite automata to filter regular expressions.
❮ Back
Next ❯

#regex_create ()

Create a regular expression from a pattern.

RegEx*
regex_create(const char_t *pattern,
             rerror_t *error,
             uint32_t *errpos);
pattern

Search pattern.

error

Error code if the pattern is not valid. Can be NULL.

errpos

Position (in characters, starting at 0) where the error is detected. UINT32_MAX if the pattern is valid. Can be NULL.

Return

Regular expression (automata) or NULL if the pattern is not valid.

Remarks

See Define patterns.


#regex_destroy ()

Destroy a regular expression.

void
regex_destroy(RegEx **regex);
regex

Regular expresion. Will be set to NULL after destruction.


#regex_match ()

Check if a whole string matches the search pattern.

bool_t
regex_match(const RegEx *regex,
            const char_t *str);
regex

Regular expresion.

str

String to evaluate.

Return

TRUE if the string is accepted by the regular expression.


#regex_search ()

Find the first substring that matches the search pattern.

bool_t
regex_search(const RegEx *regex,
             const char_t *str,
             uint32_t *pos,
             uint32_t *len);
regex

Regular expresion.

str

String where to search.

pos

Position (in characters, starting at 0) of the substring. Can be NULL.

len

Length (in characters) of the substring. Can be NULL.

Return

TRUE if a substring has been found.

Remarks

See Match and search.

❮ Back
Next ❯