Tcl_RegExpMatch(3tcl)

🌸 Tcl_RegExpMatch — the 3tcl manual page 💅

okay bestie, listen. this is the Tcl Library Procedures page for regex matching in C, and it is lowkey a whole vibe. it covers Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_RegExpExecObj, and Tcl_RegExpGetInfo. grab a strawberry drink, we're doing this 🍓

---

✨ NAME ✨

Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_RegExpExecObj, Tcl_RegExpGetInfo — pattern matching with regular expressions 🦋

---

📜 SYNOPSIS 📜

so here's the lineup, exactly as written, no cap:

#include <tcl.h>

int
Tcl_RegExpMatchObj(interp, textObj, patObj)

int
Tcl_RegExpMatch(interp, text, pattern)

Tcl_RegExp
Tcl_RegExpCompile(interp, pattern)

int
Tcl_RegExpExec(interp, regexp, text, start)

Tcl_RegExpRange(regexp, index, startPtr, endPtr)

Tcl_RegExp
Tcl_GetRegExpFromObj(interp, patObj, cflags)

int
Tcl_RegExpExecObj(interp, regexp, textObj, offset, nmatches, eflags)

Tcl_RegExpGetInfo(regexp, infoPtr)

---

🎀 ARGUMENTS 🎀

every single one of them, in order, because we do not skip:

• Tcl_Interp *interp (in) — the Tcl interpreter you're using to report errors. it is totally fine for this to be NULL if you don't want error reporting, no judgment 💅
• Tcl_Obj *textObj (in/out) — points at the value you're pulling the text-to-search out of. heads up: the internal representation of that value might get converted into a form that can be searched efficiently. it's giving glow up ✨
• Tcl_Obj *patObj (in/out) — points at the value you're getting a regular expression from. the compiled regexp gets cached right there inside the value. iconic behavior 🫶
• const char *text (in) — the text you're hunting for a match in, using a regular expression.
• const char *pattern (in) — a string shaped like a regular expression pattern.
• Tcl_RegExp regexp (in) — a compiled regular expression. it must have been handed to you earlier by Tcl_GetRegExpFromObj or Tcl_RegExpCompile. no bootleg regexps, periodt.
• const char *start (in) — if text is just a slice of some bigger string, this argument marks where that bigger string begins. and if it is not the same as text, then no “^” matches will be allowed. important!! 😤
• Tcl_Size index (in) — says which range you want: 0 means the range of the entire match, 1 or greater means the range that matched a parenthesized sub-expression.
• const char **startPtr (out) — the address of the first character in the range gets stashed here, or NULL if there is no such range.
• const char **endPtr (out) — the address of the character just after the last one in the range gets stashed here, or NULL if there is no such range.
• int cflags (in) — an OR-ed combination of the compilation flags TCL_REG_ADVANCED, TCL_REG_EXTENDED, TCL_REG_BASIC, TCL_REG_EXPANDED, TCL_REG_QUOTE, TCL_REG_NOCASE, TCL_REG_NEWLINE, TCL_REG_NLSTOP, TCL_REG_NLANCH, TCL_REG_NOSUB, and TCL_REG_CANMATCH. more info below, keep scrolling 🌈
• Tcl_Size offset (in) — the character offset into the text where matching should begin. plot twist: the value of the offset has no impact on ^ matches. that behavior is controlled by eflags instead 👀
• Tcl_Size nmatches (in) — how many matching subexpressions should be remembered for later. if this is 0, then no subexpression match info gets computed at all. if it's negative, then all of the matching subexpressions get remembered. any other value is taken as the max number of subexpressions to remember. so many options, we love choices 💖
• int eflags (in) — an OR-ed combination of the execution flags TCL_REG_NOTBOL and TCL_REG_NOTEOL. details below 🌸
• Tcl_RegExpInfo *infoPtr (out) — the address of the spot where Tcl_RegExpGetInfo should store info about a previous match.

---

💖 DESCRIPTION 💖

okay so, the main character: Tcl_RegExpMatch figures out whether its pattern argument matches regexp, where regexp is read as a regular expression using the rules in the re_syntax reference page. if there's a match, Tcl_RegExpMatch returns 1. if there's no match, it returns 0. and if something goes wrong during matching — like, say, pattern isn't a valid regular expression — then Tcl_RegExpMatch returns -1 and leaves an error message in the interpreter result. 😭

Tcl_RegExpMatchObj is basically Tcl_RegExpMatch's cooler sibling: same deal, except it works on the Tcl values textObj and patObj instead of UTF strings. and ngl, Tcl_RegExpMatchObj is generally more efficient than Tcl_RegExpMatch, so it's the preferred interface. bestie, pick the faster one 💅

---

🧚 the low-level crew: Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange 🧚

these three give you lower-level access to the regular expression pattern matcher.

Tcl_RegExpCompile compiles a regular expression string into the internal form used for efficient pattern matching. the return value is a token for this compiled form, which you can then use in later calls to Tcl_RegExpExec or Tcl_RegExpRange. if an error happens while compiling the regular expression, Tcl_RegExpCompile returns NULL and leaves an error message in the interpreter result. and listen — > the return value from Tcl_RegExpCompile is only valid up to the next call to Tcl_RegExpCompile; it is not safe to retain these values for long periods of time. do not cling to it, it's not that kind of token 💀

Tcl_RegExpExec actually runs the regular expression pattern matcher. it returns 1 if text contains a range of characters that match regexp, 0 if no match is found, and -1 if an error occurs. when there's an error, Tcl_RegExpExec leaves an error message in the interpreter result.

now, when you're searching a string for multiple matches of a pattern, it's super important to tell apart the start of the original string from the start of the current search. for example: when you go hunting for the second occurrence of a match, the text argument might point to the character right after the first match. but the pattern matcher needs to know that this isn't the start of the entire string, so that it doesn't let “^” atoms in the pattern match. that's literally what the start argument is for — it points to the start of the overall string containing text. start will be less than or equal to text, and if it is less than text then no ^ matches will be allowed. so set it right or your anchors will be acting up 🙈

Tcl_RegExpRange can be invoked after Tcl_RegExpExec returns — it hands you the detailed tea about which ranges of the string matched which parts of the pattern ☕ Tcl_RegExpRange returns a pair of pointers in *startPtr and *endPtr that identify a range of characters in the source string for the most recent call to Tcl_RegExpExec. index tells you which of several ranges you're getting: if index is 0, you get info about the overall range of characters that matched the entire pattern; otherwise you get info about the range of characters that matched the index'th parenthesized subexpression within the pattern. and if there's no range corresponding to index, then NULL is stored in *startPtr and *endPtr. simple as that ✨

---

👑 the value interfaces: Tcl_GetRegExpFromObj, Tcl_RegExpExecObj, Tcl_RegExpGetInfo 👑

Tcl_GetRegExpFromObj, Tcl_RegExpExecObj, and Tcl_RegExpGetInfo are value interfaces that give you the most direct control over Henry Spencer's regular expression library. if you're a user who needs to modify compilation and execution options directly, it is recommended that you use these interfaces instead of calling the internal regexp functions. they handle all the fiddly details of UTF to Unicode translations, plus they give you improved performance through caching in the pattern and string values. main character energy fr fr 🔥

Tcl_GetRegExpFromObj tries to return a compiled regular expression from the patObj. if the value doesn't already contain a compiled regular expression, it will attempt to create one from the string in the value and assign it to the internal representation of the patObj. the return value of this function is of type Tcl_RegExp, and it's a token for this compiled form, which you can use in subsequent calls to Tcl_RegExpExecObj or Tcl_RegExpGetInfo. if an error occurs while compiling the regular expression, Tcl_GetRegExpFromObj returns NULL and leaves an error message in the interpreter result. the regular expression token can be used as long as the internal representation of patObj refers to the compiled form. 🎀

the cflags argument is a bit-wise OR of zero or more of the following flags that control the compilation of patObj:

• TCL_REG_ADVANCED — compile advanced regular expressions (“ARE”s). this mode corresponds to the normal regular expression syntax accepted by the Tcl regexp and regsub commands. the fancy one 💅
• TCL_REG_EXTENDED — compile extended regular expressions (“ERE”s). this mode corresponds to the regular expression syntax recognized by Tcl 8.0 and earlier versions. vintage, but make it fashion 🌸
• TCL_REG_BASIC — compile basic regular expressions (“BRE”s). this mode corresponds to the regular expression syntax recognized by common Unix utilities like sed and grep. and guess what — this is the default if no flags are specified. the humble icon 👑

…and bestie, there's more where that came from — this page continues! don't go anywhere 💖

• TCL_REG_EXPANDED — compiles your regex (basic, extended, or advanced, whichever vibe you picked) using an expanded syntax where comments and whitespace are allowed to just exist. In this mode, whitespace that isn't backslashed and isn't inside a bracket expression gets ignored, and so does any #-to-end-of-line comment. Living your truth, unbothered. ✨
• TCL_REG_QUOTE — compiles a literal string, where every character is treated as an ordinary character. No special meanings, no drama, just text being text. 🎀
• TCL_REG_NOCASE — compiles for matching that ignores upper/lower case distinctions. Case-sensitive? Never heard of her. 💅
• TCL_REG_NEWLINE — compiles for newline-sensitive matching. By default, newline is a completely ordinary character with no special meaning in either regular expressions or strings. With this flag on, though, “[^” bracket expressions and “.” never match newline, “^” matches an empty string after any newline in addition to its normal function, and “$” matches an empty string before any newline in addition to its normal function. REG_NEWLINE is the bit-wise OR of REG_NLSTOP and REG_NLANCH. So it's giving both halves of the newline-sensitivity story. 🌈
• TCL_REG_NLSTOP — compiles for partial newline-sensitive matching, where the behavior of “[^” bracket expressions and “.” is affected, but the behavior of “^” and “$” is not. In this mode, “[^” bracket expressions and “.” never match newline. Half the vibe, all of the commitment. 💖
• TCL_REG_NLANCH — compiles for inverse partial newline-sensitive matching, where the behavior of “^” and “$” (the “anchors”) is affected, but the behavior of “[^” bracket expressions and “.” is not. In this mode, “^” matches an empty string after any newline in addition to its normal function, and “$” matches an empty string before any newline in addition to its normal function. The other half of the vibe. 🦋
• TCL_REG_NOSUB — compiles for matching that reports only success or failure, not what was matched. This reduces compile overhead and may improve performance. Heads up though: subsequent calls to Tcl_RegExpGetInfo or Tcl_RegExpRange will not report any match information. So you get a yes/no and that's it, bestie. 🙈
• TCL_REG_CANMATCH — compiles for matching that reports the potential to complete a partial match given more text (see below, iykyk).

Only one of TCL_REG_EXTENDED, TCL_REG_ADVANCED, TCL_REG_BASIC, and TCL_REG_QUOTE may be specified. Pick one, bestie, you can't have all four. ✋

Tcl_RegExpExecObj executes the regular expression pattern matcher. It returns 1 if objPtr contains a range of characters that match regexp, 0 if no match is found, and -1 if an error occurs. In the case of an error, Tcl_RegExpExecObj leaves an error message in the interpreter result. 😭

The nmatches value indicates to the matcher how many subexpressions are of interest. If nmatches is 0, then no subexpression match information is recorded, which may allow the matcher to make various optimizations. If the value is -1, then all of the subexpressions in the pattern are remembered. If the value is a positive integer, then only that number of subexpressions will be remembered.

Matching begins at the specified Unicode character index given by offset. Unlike Tcl_RegExpExec, the behavior of anchors is not affected by the offset value. Instead, the behavior of the anchors is explicitly controlled by the eflags argument, which is a bit-wise OR of zero or more of the following flags:

• TCL_REG_NOTBOL — the starting character will not be treated as the beginning of a line or the beginning of the string, so “^” will not match there. Note that this flag has no effect on how “\A” matches. 💀
• TCL_REG_NOTEOL — the last character in the string will not be treated as the end of a line or the end of the string, so “$” will not match there. Note that this flag has no effect on how “\Z” matches. 💀

Tcl_RegExpGetInfo retrieves information about the last match performed with a given regular expression regexp. The infoPtr argument contains a pointer to a structure that is defined as follows:

typedef struct {
    Tcl_Size nsubs;
    Tcl_RegExpIndices *matches;
    Tcl_Size extendStart;
} Tcl_RegExpInfo;

The nsubs field contains a count of the number of parenthesized subexpressions within the regular expression. If the TCL_REG_NOSUB was used, then this value will be zero. The matches field points to an array of nsubs+1 values that indicate the bounds of each subexpression matched. The first element in the array refers to the range matched by the entire regular expression, and subsequent elements refer to the parenthesized subexpressions in the order that they appear in the pattern. Each element is a structure that is defined as follows:

typedef struct {
    Tcl_Size start;
    Tcl_Size end;
} Tcl_RegExpIndices;

The start and end values are Unicode character indices relative to the offset location within objPtr where matching began. The start index identifies the first character of the matched subexpression. The end index identifies the first character after the matched subexpression. If the subexpression matched the empty string, then start and end will be equal. If the subexpression did not participate in the match, then start and end will be set to -1. Not me getting emotional over empty-string matches 🥲

The extendStart field in Tcl_RegExpInfo is only set if the TCL_REG_CANMATCH flag was used. It indicates the first character in the string where a match could occur. If a match was found, this will be the same as the beginning of the current match. If no match was found, then it indicates the earliest point at which a match might occur if additional text is appended to the string. If it is no match is possible even with further text, this field will be set to -1. So basically: "here's where hope lives, or -1 if hope has left the chat." 🫶

---

💖 REFERENCE COUNT MANAGEMENT 💖

Okay this part is important, do not skip it, this is the part where things crash if you're sloppy. ⚠️

The textObj and patObj arguments to Tcl_RegExpMatchObj must have reference counts of at least 1. Note however that this function may set the interpreter result; neither argument should be the direct interpreter result without an additional reference being taken. 👑

The patObj argument to Tcl_GetRegExpFromObj must have a reference count of at least 1. Note however that this function may set the interpreter result; the argument should not be the direct interpreter result without an additional reference being taken. 🦋

The textObj argument to Tcl_RegExpExecObj must have a reference count of at least 1. Note however that this function may set the interpreter result; the argument should not be the direct interpreter result without an additional reference being taken. 🌸

---

👀 SEE ALSO 👀

• re_syntax(3tcl)

---

🔑 KEYWORDS 🔑

match, pattern, regular expression, string, subexpression, Tcl_RegExpIndices, Tcl_RegExpInfo

---

And that's the whole page, bestie!! This one's from the Tcl crew, version 8.1, filed under Tcl_RegExpMatch(3tcl) — go forth and match responsibly, mwah 💜✨