Regular expressions
#Header
#include <core/regex.h>
#Functions
| RegEx* | regex_create (...) |
| void | regex_destroy (...) |
| bool_t | regex_match (...) |
| bool_t | regex_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.
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); |
1 2 3 4 5 |
YES: file01.txt NO: image01.png NO: sun01.jpg YES: films.txt NO: document.pdf |
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); |
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. - A period
'.'is equivalent to "any character", except the new line. - 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. - 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. - The POSIX classes (Table 1) can be used inside the brackets. They only include ASCII characters. The form
[[:^alpha:]]negates any of them.
"hello" --> {"hello"}
|
"h.llo" --> {"hello", "htllo", "hällo", "h5llo", ...}
|
"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) (áâãäåæçèéêëìíîïðñòóôõö÷øùú)
|
"[*.?]" --> {"*", ".", "?"}
"[]a]" --> {"]", "a"}
"[a-]" --> {"a", "-"}
"file-1" --> {"file-1"}
|
"[[:alpha:]]+" --> {"a", "Hello", "XYZ", ...}
"[[:digit:][:upper:]]" --> {"0", "9", "A", "Z", ...}
|
| 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. - The parentheses
'(he*llo)'allow grouping a regular expression, so that it behaves as a single character. The form'(?:...)'is also accepted. - The quantifiers (Table 2) set how many times the previous element can appear.
"hello|bye" --> {"hello", "bye"}
"h(e|a)llo" --> {"hello", "hallo"}
"red|blue|" --> {"red", "blue", ""}
|
"(hello)*" --> {"", "hello", "hellohello", "hellohellohello", ... }
"(he*llo)ZZ" --> {"hlloZZ", "helloZZ", "heelloZZ", "heeelloZZ", ... }
|
| 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). |
"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. - The backslash introduces escape sequences (Table 3).
"^ERROR" "ERROR: disk" --> pos=0, len=5 "^ERROR" "disk ERROR" --> FALSE "\.txt$" "doc.txt" --> pos=3, len=4 |
| 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. |
"\(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).
"[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).
#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 |
| errpos | Position (in characters, starting at 0) where the error is detected. |
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 |
#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 |
| len | Length (in characters) of the substring. Can be |
Return
TRUE if a substring has been found.
Remarks
See Match and search.


