Tcl_RegExpMatch (3)
Pattern matching with regular expressions
SYNOPSIS
#include <tcl.h>
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)
ARGUMENTS
Tcl_Interp *interp
Tcl_Interp *interp in
Tcl interpreter to use for error reporting.
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_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.
DESCRIPTION
Tcl_RegExpMatch determines whether its pattern argument
matches regexp, where regexp is interpreted
as a regular expression using the same rules as for the
regexp Tcl command.
If there is a match then Tcl_RegExpMatch returns 1.
If there is no match then Tcl_RegExpMatch returns 0.
If an error occurs in the matching process (e.g. pattern
is not a valid regular expression) then Tcl_RegExpMatch
returns -1 and leaves an error message in interp->result.
Tcl_RegExpCompile, Tcl_RegExpExec, and Tcl_RegExpRange
provide 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 can be
used in subsequent calls to Tcl_RegExpExec or Tcl_RegExpRange.
If an error occurs while compiling the regular expression then
Tcl_RegExpCompile returns NULL and leaves an error message
in interp->result.
Note: 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.
Tcl_RegExpExec executes the regular expression pattern matcher.
It returns 1 if string 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_RegExpExec leaves an error
message in interp->result.
When searching a string for multiple matches of a pattern,
it is important to distinguish between the start of the original
string and the start of the current search.
For example, when searching for the second occurrence of a
match, the string argument might point to the character
just after the first match; however, it is important for the
pattern matcher to know that this is not the start of the entire string,
so that it doesn't allow ^ atoms in the pattern to match.
The start argument provides this information by pointing
to the start of the overall string containing string.
Start will be less than or equal to string; if it
is less than string then no ^ matches will be allowed.
Tcl_RegExpRange may be invoked after Tcl_RegExpExec
returns; it provides detailed information about what ranges of
the string matched what 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 indicates which of several ranges is desired:
if index is 0, information is returned about the overall range
of characters that matched the entire pattern; otherwise,
information is returned about the range of characters that matched the
index'th parenthesized subexpression within the pattern.
If there is no range corresponding to index then NULL
is stored in *firstPtr and *lastPtr.
KEYWORDS
match, pattern, regular expression, string, subexpression
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.2 1998/09/14 18:39:49 stanton Exp $
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\" Start paragraph describing an argument to a library procedure.
'\" type is type of argument (int, etc.), in/out is either "in", "out",
'\" or "in/out" to describe whether procedure reads or modifies arg,
'\" and indent is equivalent to second arg of .IP (shouldn't ever be
'\" needed; use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\" Give maximum sizes of arguments for setting tab stops. Type and
'\" name are examples of largest possible arguments that will be passed
'\" to .AP later. If args are omitted, default tab stops are used.
'\"
'\" .BS
'\" Start box enclosure. From here until next .BE, everything will be
'\" enclosed in one large box.
'\"
'\" .BE
'\" End of box enclosure.
'\"
'\" .CS
'\" Begin code excerpt.
'\"
'\" .CE
'\" End code excerpt.
'\"
'\" .VS ?version? ?br?
'\" Begin vertical sidebar, for use in marking newly-changed parts
'\" of man pages. The first argument is ignored and used for recording
'\" the version when the .VS was added, so that the sidebars can be
'\" found and removed when they reach a certain age. If another argument
'\" is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\" End of vertical sidebar.
'\"
'\" .DS
'\" Begin an indented unfilled display.
'\"
'\" .DE
'\" End of indented unfilled display.
'\"
'\" .SO
'\" Start of list of standard options for a Tk widget. The
'\" options follow on successive lines, in four columns separated
'\" by tabs.
'\"
'\" .SE
'\" End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\" Start of description of a specific option. cmdName gives the
'\" option's name as specified in the class command, dbName gives
'\" the option's name in the option database, and dbClass gives
'\" the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\" Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.2 1998/09/14 18:39:54 stanton Exp $
'\"
'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
t .wh -1.3i ^B
^l \n(.l
b
'\" # Start an argument description
AP
!"\\$4"" .TP \\$4
\{\
!"\\$2"" .TP \\n()Cu
.TP 15
|
