SYNOPSIS
#include <tcl.h>
int Tcl_RegExpMatchObj(interp, strObj, patObj)
int Tcl_RegExpMatch(interp, string, pattern)
Tcl_RegExp Tcl_RegExpCompile(interp, pattern)
int Tcl_RegExpExec(interp, regexp, string, start)
Tcl_RegExpRange(regexp, index, startPtr, endPtr)
Tcl_RegExp Tcl_GetRegExpFromObj(interp, patObj, cflags)
int Tcl_RegExpExecObj(interp, regexp, objPtr, offset, nmatches, eflags)
Tcl_RegExpGetInfo(regexp, infoPtr)
ARGUMENTS
- Tcl_Interp *interp (in)
-
Tcl interpreter to use for error reporting. The interpreter may be NULL if no error reporting is desired.
- Tcl_Obj *strObj (in/out)
-
Refers to the object from which to get the string to search. The internal representation of the object may be converted to a form that can be efficiently searched.
- Tcl_Obj *patObj (in/out)
-
Refers to the object from which to get a regular expression. The compiled regular expression is cached in the object.
- char *string (in)
-
String to check for a match with a regular expression.
- char *pattern (in)
-
String in the form of a regular expression pattern.
- Tcl_RegExp regexp (in)
-
Compiled regular expression. Must have been returned previously by
Tcl_GetRegExpFromObj() orTcl_RegExpCompile() . - char *start (in)
-
If string is just a portion of some other string, this argument identifies the beginning of the larger string. If it isn't the same as string, then no ^ matches will be allowed.
- int index (in)
-
Specifies which range is desired: 0 means the range of the entire match, 1 or greater means the range that matched a parenthesized sub-expression.
- char **startPtr (out)
-
The address of the first character in the range is stored here, or NULL if there is no such range.
- char **endPtr (out)
-
The address of the character just after the last one in the range is stored here, or NULL if there is no such range.
- int cflags (in)
-
OR-ed combination of compilation flags. See below for more information.
- Tcl_Obj *objPtr (in/out)
-
An object which contains the string to check for a match with a regular expression.
- int offset (in)
-
The character offset into the string where matching should begin. The value of the offset has no impact on ^ matches. This behavior is controlled by eflags.
- int nmatches (in)
-
The number of matching subexpressions that should be remembered for later use. If this value is 0, then no subexpression match information will be computed. If the value is -1, then all of the matching subexpressions will be remembered. Any other value will be taken as the maximum number of subexpressions to remember.
- int eflags (in)
-
OR-ed combination of the values TCL_REG_NOTBOL and TCL_REG_NOTEOL. See below for more information.
- Tcl_RegExpInfo *infoPtr (out)
-
The address of the location where information about a previous match should be stored by
Tcl_RegExpGetInfo() .
DESCRIPTION
- TCL_REG_ADVANCED
-
Compile advanced regular expressions (AREs). This mode corresponds to the normal regular expression syntax accepted by the Tcl regexp and regsub commands.
- TCL_REG_EXTENDED
-
Compile extended regular expressions (EREs). This mode corresponds to the regular expression syntax recognized by Tcl 8.0 and earlier versions.
- TCL_REG_BASIC
-
Compile basic regular expressions (BREs). This mode corresponds to the regular expression syntax recognized by common UNIX utilities like sed and grep. This is the default if no flags are specified.
- TCL_REG_EXPANDED
-
Compile the regular expression (basic, extended, or advanced) using an expanded syntax that allows comments and whitespace. This mode causes non-backslashed non-bracket-expression white space and #-to-end-of-line comments to be ignored.
- TCL_REG_QUOTE
-
Compile a literal string, with all characters treated as ordinary characters.
- TCL_REG_NOCASE
-
Compile for matching that ignores upper/lower case distinctions.
- TCL_REG_NEWLINE
-
Compile 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, [^ 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 bitwise OR of REG_NLSTOP and REG_NLANCH.
- TCL_REG_NLSTOP
-
Compile for partial newline-sensitive matching, with the behavior of [^ bracket expressions and . affected, but not the behavior of ^ and $. In this mode, [^ bracket expressions and . never match newline.
- TCL_REG_NLANCH
-
Compile for inverse partial newline-sensitive matching, with the behavior of of ^ and $ (the anchors) affected, but not the behavior of [^ bracket expressions and .. 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.
- TCL_REG_NOSUB
-
Compile for matching that reports only success or failure, not what was matched. This reduces compile overhead and may improve performance. Subsequent calls to
Tcl_RegExpGetInfo() orTcl_RegExpRange() will not report any match information. - TCL_REG_CANMATCH
-
Compile for matching that reports the potential to complete a partial match given more text (see below).
Only one of TCL_REG_EXTENDED, TCL_REG_ADVANCED, TCL_REG_BASIC, and TCL_REG_QUOTE may be specified.
- 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.
typedef struct Tcl_RegExpInfo { int nsubs; Tcl_RegExpIndices *matches; long 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 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_RegExpIndices { long start; long 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.
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.
PORTABILITY
Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022. Windows Server 2025.
AVAILABILITY
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition
SEE ALSO
- Commands:
- re_syntax
PTC MKS Toolkit 10.5 Documentation Build 40.