---
name: "rgxg_utils_alternation"
section: "3"
platform: "linux"
package: "librgxg-dev"
version: "0.1.2-7"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/rgxg_utils_alternation"
---

# rgxg\_utils\_alternation(3)

create regex that matches any of the given patterns

## 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

**rgxg\_utils\_alternation**() generates the (extended) regular expression that matches any of the given *patterns*, an array of constant character strings. *size* specifies the number of entries of the array to use for the regular expression. Both *patterns* and its entries must be valid and not NULL for *size*\>0.

Note that callers of **rgxg\_utils\_alternation**() which pass a non-constant 'char \*\*' value as *patterns* need to use an explicit cast (i.e. '(const char\*\*)') to avoid an incompatible pointer type warning.

The generated regular expression is written to the character string *regex*, including the terminating null byte ('\\0'), unless **RGXG\_NONULLBYTE** is set. If *regex* is NULL the return value is the number of characters (excluding the terminating null byte) that would have been written in case *regex* has been initialized. Note that the functions assume an arbitrarily long *regex* string, callers must **ensure** that the given string is large enough to not overflow the actual space.

*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.

- **RGXG\_NONULLBYTE**

  Do not add the terminating null byte ('\\0') to the *regex* string.

## RETURN VALUE

**rgxg\_utils\_alternation**() returns the number of characters (excluding the terminating null byte) written to *regex*.

## AVAILABILITY

This function is available since rgxg 0.1.

## SEE ALSO

[**regex**(7)](/regex/7.md), [**rgxg\_utils\_escape\_string**(3)](/rgxg_utils_escape_string/3.md).

## AUTHOR

Hannes von Haugwitz \<hannes@vonhaugwitz.com\>