3.2 Matching String

Function ctlseqs_match matches a given character string to a matcher. The function accepts four arguments: the matcher, the string to match, length of the string to match, and a buffer which stores the match result.

Before matching, a buffer which is large enough to store the match result should be allocated. The buffer is an array of union ctlseqs_value, whose definition is shown below:

union ctlseqs_value {
    char const    *str;
    size_t         len;
    unsigned long  num;
};

If the string contains a recognizable control function, or part of a control function which is not yet terminated by the end of the string, the length of control function will be stored at len field of match result buffer at offset 0, and the pointer to the first character of the control funtion at the str field at offset 1.

If ctlseqs_match fails to find any control functions, returns CTLSEQS_NOSEQ. For a partial control function, returns CTLSEQS_PARTIAL. If the matcher is not configured with a matching pattern of the control function, the function returns CTLSEQS_NOMATCH.

If the control function matches a pattern configured in the matcher, returns the offset of the matched pattern, and stores the extracted values to the result buffer according to each of the placeholders, starting from offset 2:

• CTLSEQS_PH_NUM, CTLSEQS_PH_HEXNUM: The integer is stored in field num.
• CTLSEQS_PH_NUMS: The number of integers is stored in field len, followed by that many integers stored in field num.
• CTLSEQS_PH_CSI_PARAM, CTLSEQS_PH_CSI_INTMD, CTLSEQS_PH_STR, CTLSEQS_PH_CMDSTR, CTLSEQS_PH_CHRSTR: The length of the string is stored in field len, followed by a pointer to the first character of the string stored in field str.

The following code is an example of invoking ctlseqs_match:

union ctlseqs_value     buffer[4];
struct ctlseqs_matcher *matcher /* = ... */;
// ...
char const *str     = "foo" CTLSEQS_CUP("2", "4");
size_t      str_len = sizeof("foo" CTLSEQS_CUP("2", "4")) - 1;
ssize_t     result  = ctlseqs_match(matcher, str, str_len, buffer);

assert(result == 0);
assert(buffer[0].len == 6 && buffer[1].str == str + 3);
assert(buffer[2].num == 2 && buffer[3].num == 4);

Function ctlseqs_match allows NULL value for argument matcher, in which case it behaves like a matcher configured with zero patterns is provided.

Caution: If the given string can match multiple patterns in the matcher, it is unspecified which one of them will be the final match result.