RGXG_UTILS_ALTERNATION(3)

RGXG_UTILS_ALTERNATION 💖

okay so this is a page from the librgxg manual, section 3 (that's the library-functions section, iykyk), and bestie, it's literally the glow-up function for making regexes that match any of a bunch of patterns. let's get into it 🦋

✨ NAME ✨

rgxg_utils_alternation — create regex that matches any of the given patterns

✨ SYNOPSIS ✨

#include <rgxg/utils.h>

int rgxg_utils_alternation (const char **patterns, size_t size,
     char *regex, rgxg_options_t options);

✨ DESCRIPTION ✨

so rgxg_utils_alternation() generates the (extended) regular expression that matches any of the given patterns. the patterns come in as an array of constant character strings, and size tells it how many entries of that array to actually use for the regular expression. 🎀

heads up: both patterns and its entries must be valid and not NULL for size>0. no NULL shenanigans allowed, periodt.

also, tiny lil gotcha that WILL bite you: if you're calling rgxg_utils_alternation() and you pass a non-constant 'char **' value as patterns, you need to use an explicit cast (i.e. '(const char**)') to avoid an incompatible pointer type warning. the compiler is dramatic like that. 😭

the generated regular expression gets written to the character string regex, and yes bestie, that includes the terminating null byte ('\0') — unless RGXG_NONULLBYTE is set. and if regex is NULL? then the return value is the number of characters (excluding the terminating null byte) that would have been written in case regex has been initialized. so you can use it as a lil sizing pre-flight. slay. ✨

ok but fr fr: the functions assume an arbitrarily long regex string. callers must ensure that the given string is large enough to not overflow the actual space. that's on you, not on us. 💀

options is either zero, or the bitwise-or of one or more of the following macros:

• RGXG_NOOUTERPARENS — omit the outer parenthesis, if any, of the regular expression. bye bye wrapping, you will not be missed 💅
• RGXG_NONULLBYTE — do not add the terminating null byte ('\0') to the regex string. it's giving "i don't need a proper ending" energy 🧚

✨ RETURN VALUE ✨

rgxg_utils_alternation() returns the number of characters (excluding the terminating null byte) written to regex. cute, tidy, useful. 🍓

✨ AVAILABILITY ✨

this function is available since rgxg 0.1. it's been iconic since day one, no cap. 👑

✨ SEE ALSO ✨

regex(7), rgxg_utils_escape_string(3)

✨ AUTHOR ✨

Hannes von Haugwitz <hannes@vonhaugwitz.com> — the main character who wrote all this, we stan 🫶

mwah that's the whole page bestie 💜 this was pulled from rgxg 0.1.2, dated Apr 12, 2020, and it lives in the librgxg manual as RGXG_UTILS_ALTERNATION(3). go forth and alternate your patterns, you absolute legend 🌈⭐