Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/uregex.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // © 2016 and later: Unicode, Inc. and others.
jpayne@69 2 // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 3 /*
jpayne@69 4 **********************************************************************
jpayne@69 5 * Copyright (C) 2004-2016, International Business Machines
jpayne@69 6 * Corporation and others. All Rights Reserved.
jpayne@69 7 **********************************************************************
jpayne@69 8 * file name: uregex.h
jpayne@69 9 * encoding: UTF-8
jpayne@69 10 * indentation:4
jpayne@69 11 *
jpayne@69 12 * created on: 2004mar09
jpayne@69 13 * created by: Andy Heninger
jpayne@69 14 *
jpayne@69 15 * ICU Regular Expressions, API for C
jpayne@69 16 */
jpayne@69 17
jpayne@69 18 /**
jpayne@69 19 * \file
jpayne@69 20 * \brief C API: Regular Expressions
jpayne@69 21 *
jpayne@69 22 * <p>This is a C wrapper around the C++ RegexPattern and RegexMatcher classes.</p>
jpayne@69 23 */
jpayne@69 24
jpayne@69 25 #ifndef UREGEX_H
jpayne@69 26 #define UREGEX_H
jpayne@69 27
jpayne@69 28 #include "unicode/utext.h"
jpayne@69 29 #include "unicode/utypes.h"
jpayne@69 30
jpayne@69 31 #if !UCONFIG_NO_REGULAR_EXPRESSIONS
jpayne@69 32
jpayne@69 33 #include "unicode/localpointer.h"
jpayne@69 34 #include "unicode/parseerr.h"
jpayne@69 35
jpayne@69 36 struct URegularExpression;
jpayne@69 37 /**
jpayne@69 38 * Structure representing a compiled regular expression, plus the results
jpayne@69 39 * of a match operation.
jpayne@69 40 * @stable ICU 3.0
jpayne@69 41 */
jpayne@69 42 typedef struct URegularExpression URegularExpression;
jpayne@69 43
jpayne@69 44
jpayne@69 45 /**
jpayne@69 46 * Constants for Regular Expression Match Modes.
jpayne@69 47 * @stable ICU 2.4
jpayne@69 48 */
jpayne@69 49 typedef enum URegexpFlag{
jpayne@69 50
jpayne@69 51 #ifndef U_HIDE_DRAFT_API
jpayne@69 52 /** Forces normalization of pattern and strings.
jpayne@69 53 Not implemented yet, just a placeholder, hence draft.
jpayne@69 54 @draft ICU 2.4 */
jpayne@69 55 UREGEX_CANON_EQ = 128,
jpayne@69 56 #endif /* U_HIDE_DRAFT_API */
jpayne@69 57 /** Enable case insensitive matching. @stable ICU 2.4 */
jpayne@69 58 UREGEX_CASE_INSENSITIVE = 2,
jpayne@69 59
jpayne@69 60 /** Allow white space and comments within patterns @stable ICU 2.4 */
jpayne@69 61 UREGEX_COMMENTS = 4,
jpayne@69 62
jpayne@69 63 /** If set, '.' matches line terminators, otherwise '.' matching stops at line end.
jpayne@69 64 * @stable ICU 2.4 */
jpayne@69 65 UREGEX_DOTALL = 32,
jpayne@69 66
jpayne@69 67 /** If set, treat the entire pattern as a literal string.
jpayne@69 68 * Metacharacters or escape sequences in the input sequence will be given
jpayne@69 69 * no special meaning.
jpayne@69 70 *
jpayne@69 71 * The flag UREGEX_CASE_INSENSITIVE retains its impact
jpayne@69 72 * on matching when used in conjunction with this flag.
jpayne@69 73 * The other flags become superfluous.
jpayne@69 74 *
jpayne@69 75 * @stable ICU 4.0
jpayne@69 76 */
jpayne@69 77 UREGEX_LITERAL = 16,
jpayne@69 78
jpayne@69 79 /** Control behavior of "$" and "^"
jpayne@69 80 * If set, recognize line terminators within string,
jpayne@69 81 * otherwise, match only at start and end of input string.
jpayne@69 82 * @stable ICU 2.4 */
jpayne@69 83 UREGEX_MULTILINE = 8,
jpayne@69 84
jpayne@69 85 /** Unix-only line endings.
jpayne@69 86 * When this mode is enabled, only \\u000a is recognized as a line ending
jpayne@69 87 * in the behavior of ., ^, and $.
jpayne@69 88 * @stable ICU 4.0
jpayne@69 89 */
jpayne@69 90 UREGEX_UNIX_LINES = 1,
jpayne@69 91
jpayne@69 92 /** Unicode word boundaries.
jpayne@69 93 * If set, \b uses the Unicode TR 29 definition of word boundaries.
jpayne@69 94 * Warning: Unicode word boundaries are quite different from
jpayne@69 95 * traditional regular expression word boundaries. See
jpayne@69 96 * http://unicode.org/reports/tr29/#Word_Boundaries
jpayne@69 97 * @stable ICU 2.8
jpayne@69 98 */
jpayne@69 99 UREGEX_UWORD = 256,
jpayne@69 100
jpayne@69 101 /** Error on Unrecognized backslash escapes.
jpayne@69 102 * If set, fail with an error on patterns that contain
jpayne@69 103 * backslash-escaped ASCII letters without a known special
jpayne@69 104 * meaning. If this flag is not set, these
jpayne@69 105 * escaped letters represent themselves.
jpayne@69 106 * @stable ICU 4.0
jpayne@69 107 */
jpayne@69 108 UREGEX_ERROR_ON_UNKNOWN_ESCAPES = 512
jpayne@69 109
jpayne@69 110 } URegexpFlag;
jpayne@69 111
jpayne@69 112 /**
jpayne@69 113 * Open (compile) an ICU regular expression. Compiles the regular expression in
jpayne@69 114 * string form into an internal representation using the specified match mode flags.
jpayne@69 115 * The resulting regular expression handle can then be used to perform various
jpayne@69 116 * matching operations.
jpayne@69 117 *
jpayne@69 118 *
jpayne@69 119 * @param pattern The Regular Expression pattern to be compiled.
jpayne@69 120 * @param patternLength The length of the pattern, or -1 if the pattern is
jpayne@69 121 * NUL terminated.
jpayne@69 122 * @param flags Flags that alter the default matching behavior for
jpayne@69 123 * the regular expression, UREGEX_CASE_INSENSITIVE, for
jpayne@69 124 * example. For default behavior, set this parameter to zero.
jpayne@69 125 * See <code>enum URegexpFlag</code>. All desired flags
jpayne@69 126 * are bitwise-ORed together.
jpayne@69 127 * @param pe Receives the position (line and column numbers) of any syntax
jpayne@69 128 * error within the source regular expression string. If this
jpayne@69 129 * information is not wanted, pass NULL for this parameter.
jpayne@69 130 * @param status Receives error detected by this function.
jpayne@69 131 * @stable ICU 3.0
jpayne@69 132 *
jpayne@69 133 */
jpayne@69 134 U_STABLE URegularExpression * U_EXPORT2
jpayne@69 135 uregex_open( const UChar *pattern,
jpayne@69 136 int32_t patternLength,
jpayne@69 137 uint32_t flags,
jpayne@69 138 UParseError *pe,
jpayne@69 139 UErrorCode *status);
jpayne@69 140
jpayne@69 141 /**
jpayne@69 142 * Open (compile) an ICU regular expression. Compiles the regular expression in
jpayne@69 143 * string form into an internal representation using the specified match mode flags.
jpayne@69 144 * The resulting regular expression handle can then be used to perform various
jpayne@69 145 * matching operations.
jpayne@69 146 * <p>
jpayne@69 147 * The contents of the pattern UText will be extracted and saved. Ownership of the
jpayne@69 148 * UText struct itself remains with the caller. This is to match the behavior of
jpayne@69 149 * uregex_open().
jpayne@69 150 *
jpayne@69 151 * @param pattern The Regular Expression pattern to be compiled.
jpayne@69 152 * @param flags Flags that alter the default matching behavior for
jpayne@69 153 * the regular expression, UREGEX_CASE_INSENSITIVE, for
jpayne@69 154 * example. For default behavior, set this parameter to zero.
jpayne@69 155 * See <code>enum URegexpFlag</code>. All desired flags
jpayne@69 156 * are bitwise-ORed together.
jpayne@69 157 * @param pe Receives the position (line and column numbers) of any syntax
jpayne@69 158 * error within the source regular expression string. If this
jpayne@69 159 * information is not wanted, pass NULL for this parameter.
jpayne@69 160 * @param status Receives error detected by this function.
jpayne@69 161 *
jpayne@69 162 * @stable ICU 4.6
jpayne@69 163 */
jpayne@69 164 U_STABLE URegularExpression * U_EXPORT2
jpayne@69 165 uregex_openUText(UText *pattern,
jpayne@69 166 uint32_t flags,
jpayne@69 167 UParseError *pe,
jpayne@69 168 UErrorCode *status);
jpayne@69 169
jpayne@69 170 #if !UCONFIG_NO_CONVERSION
jpayne@69 171 /**
jpayne@69 172 * Open (compile) an ICU regular expression. The resulting regular expression
jpayne@69 173 * handle can then be used to perform various matching operations.
jpayne@69 174 * <p>
jpayne@69 175 * This function is the same as uregex_open, except that the pattern
jpayne@69 176 * is supplied as an 8 bit char * string in the default code page.
jpayne@69 177 *
jpayne@69 178 * @param pattern The Regular Expression pattern to be compiled,
jpayne@69 179 * NUL terminated.
jpayne@69 180 * @param flags Flags that alter the default matching behavior for
jpayne@69 181 * the regular expression, UREGEX_CASE_INSENSITIVE, for
jpayne@69 182 * example. For default behavior, set this parameter to zero.
jpayne@69 183 * See <code>enum URegexpFlag</code>. All desired flags
jpayne@69 184 * are bitwise-ORed together.
jpayne@69 185 * @param pe Receives the position (line and column numbers) of any syntax
jpayne@69 186 * error within the source regular expression string. If this
jpayne@69 187 * information is not wanted, pass NULL for this parameter.
jpayne@69 188 * @param status Receives errors detected by this function.
jpayne@69 189 * @return The URegularExpression object representing the compiled
jpayne@69 190 * pattern.
jpayne@69 191 *
jpayne@69 192 * @stable ICU 3.0
jpayne@69 193 */
jpayne@69 194 U_STABLE URegularExpression * U_EXPORT2
jpayne@69 195 uregex_openC( const char *pattern,
jpayne@69 196 uint32_t flags,
jpayne@69 197 UParseError *pe,
jpayne@69 198 UErrorCode *status);
jpayne@69 199 #endif
jpayne@69 200
jpayne@69 201
jpayne@69 202
jpayne@69 203 /**
jpayne@69 204 * Close the regular expression, recovering all resources (memory) it
jpayne@69 205 * was holding.
jpayne@69 206 *
jpayne@69 207 * @param regexp The regular expression to be closed.
jpayne@69 208 * @stable ICU 3.0
jpayne@69 209 */
jpayne@69 210 U_STABLE void U_EXPORT2
jpayne@69 211 uregex_close(URegularExpression *regexp);
jpayne@69 212
jpayne@69 213 #if U_SHOW_CPLUSPLUS_API
jpayne@69 214
jpayne@69 215 U_NAMESPACE_BEGIN
jpayne@69 216
jpayne@69 217 /**
jpayne@69 218 * \class LocalURegularExpressionPointer
jpayne@69 219 * "Smart pointer" class, closes a URegularExpression via uregex_close().
jpayne@69 220 * For most methods see the LocalPointerBase base class.
jpayne@69 221 *
jpayne@69 222 * @see LocalPointerBase
jpayne@69 223 * @see LocalPointer
jpayne@69 224 * @stable ICU 4.4
jpayne@69 225 */
jpayne@69 226 U_DEFINE_LOCAL_OPEN_POINTER(LocalURegularExpressionPointer, URegularExpression, uregex_close);
jpayne@69 227
jpayne@69 228 U_NAMESPACE_END
jpayne@69 229
jpayne@69 230 #endif
jpayne@69 231
jpayne@69 232 /**
jpayne@69 233 * Make a copy of a compiled regular expression. Cloning a regular
jpayne@69 234 * expression is faster than opening a second instance from the source
jpayne@69 235 * form of the expression, and requires less memory.
jpayne@69 236 * <p>
jpayne@69 237 * Note that the current input string and the position of any matched text
jpayne@69 238 * within it are not cloned; only the pattern itself and the
jpayne@69 239 * match mode flags are copied.
jpayne@69 240 * <p>
jpayne@69 241 * Cloning can be particularly useful to threaded applications that perform
jpayne@69 242 * multiple match operations in parallel. Each concurrent RE
jpayne@69 243 * operation requires its own instance of a URegularExpression.
jpayne@69 244 *
jpayne@69 245 * @param regexp The compiled regular expression to be cloned.
jpayne@69 246 * @param status Receives indication of any errors encountered
jpayne@69 247 * @return the cloned copy of the compiled regular expression.
jpayne@69 248 * @stable ICU 3.0
jpayne@69 249 */
jpayne@69 250 U_STABLE URegularExpression * U_EXPORT2
jpayne@69 251 uregex_clone(const URegularExpression *regexp, UErrorCode *status);
jpayne@69 252
jpayne@69 253 /**
jpayne@69 254 * Returns a pointer to the source form of the pattern for this regular expression.
jpayne@69 255 * This function will work even if the pattern was originally specified as a UText.
jpayne@69 256 *
jpayne@69 257 * @param regexp The compiled regular expression.
jpayne@69 258 * @param patLength This output parameter will be set to the length of the
jpayne@69 259 * pattern string. A NULL pointer may be used here if the
jpayne@69 260 * pattern length is not needed, as would be the case if
jpayne@69 261 * the pattern is known in advance to be a NUL terminated
jpayne@69 262 * string.
jpayne@69 263 * @param status Receives errors detected by this function.
jpayne@69 264 * @return a pointer to the pattern string. The storage for the string is
jpayne@69 265 * owned by the regular expression object, and must not be
jpayne@69 266 * altered or deleted by the application. The returned string
jpayne@69 267 * will remain valid until the regular expression is closed.
jpayne@69 268 * @stable ICU 3.0
jpayne@69 269 */
jpayne@69 270 U_STABLE const UChar * U_EXPORT2
jpayne@69 271 uregex_pattern(const URegularExpression *regexp,
jpayne@69 272 int32_t *patLength,
jpayne@69 273 UErrorCode *status);
jpayne@69 274
jpayne@69 275 /**
jpayne@69 276 * Returns the source text of the pattern for this regular expression.
jpayne@69 277 * This function will work even if the pattern was originally specified as a UChar string.
jpayne@69 278 *
jpayne@69 279 * @param regexp The compiled regular expression.
jpayne@69 280 * @param status Receives errors detected by this function.
jpayne@69 281 * @return the pattern text. The storage for the text is owned by the regular expression
jpayne@69 282 * object, and must not be altered or deleted.
jpayne@69 283 *
jpayne@69 284 * @stable ICU 4.6
jpayne@69 285 */
jpayne@69 286 U_STABLE UText * U_EXPORT2
jpayne@69 287 uregex_patternUText(const URegularExpression *regexp,
jpayne@69 288 UErrorCode *status);
jpayne@69 289
jpayne@69 290 /**
jpayne@69 291 * Get the match mode flags that were specified when compiling this regular expression.
jpayne@69 292 * @param status Receives errors detected by this function.
jpayne@69 293 * @param regexp The compiled regular expression.
jpayne@69 294 * @return The match mode flags
jpayne@69 295 * @see URegexpFlag
jpayne@69 296 * @stable ICU 3.0
jpayne@69 297 */
jpayne@69 298 U_STABLE int32_t U_EXPORT2
jpayne@69 299 uregex_flags(const URegularExpression *regexp,
jpayne@69 300 UErrorCode *status);
jpayne@69 301
jpayne@69 302
jpayne@69 303 /**
jpayne@69 304 * Set the subject text string upon which the regular expression will look for matches.
jpayne@69 305 * This function may be called any number of times, allowing the regular
jpayne@69 306 * expression pattern to be applied to different strings.
jpayne@69 307 * <p>
jpayne@69 308 * Regular expression matching operations work directly on the application's
jpayne@69 309 * string data. No copy is made. The subject string data must not be
jpayne@69 310 * altered after calling this function until after all regular expression
jpayne@69 311 * operations involving this string data are completed.
jpayne@69 312 * <p>
jpayne@69 313 * Zero length strings are permitted. In this case, no subsequent match
jpayne@69 314 * operation will dereference the text string pointer.
jpayne@69 315 *
jpayne@69 316 * @param regexp The compiled regular expression.
jpayne@69 317 * @param text The subject text string.
jpayne@69 318 * @param textLength The length of the subject text, or -1 if the string
jpayne@69 319 * is NUL terminated.
jpayne@69 320 * @param status Receives errors detected by this function.
jpayne@69 321 * @stable ICU 3.0
jpayne@69 322 */
jpayne@69 323 U_STABLE void U_EXPORT2
jpayne@69 324 uregex_setText(URegularExpression *regexp,
jpayne@69 325 const UChar *text,
jpayne@69 326 int32_t textLength,
jpayne@69 327 UErrorCode *status);
jpayne@69 328
jpayne@69 329
jpayne@69 330 /**
jpayne@69 331 * Set the subject text string upon which the regular expression will look for matches.
jpayne@69 332 * This function may be called any number of times, allowing the regular
jpayne@69 333 * expression pattern to be applied to different strings.
jpayne@69 334 * <p>
jpayne@69 335 * Regular expression matching operations work directly on the application's
jpayne@69 336 * string data; only a shallow clone is made. The subject string data must not be
jpayne@69 337 * altered after calling this function until after all regular expression
jpayne@69 338 * operations involving this string data are completed.
jpayne@69 339 *
jpayne@69 340 * @param regexp The compiled regular expression.
jpayne@69 341 * @param text The subject text string.
jpayne@69 342 * @param status Receives errors detected by this function.
jpayne@69 343 *
jpayne@69 344 * @stable ICU 4.6
jpayne@69 345 */
jpayne@69 346 U_STABLE void U_EXPORT2
jpayne@69 347 uregex_setUText(URegularExpression *regexp,
jpayne@69 348 UText *text,
jpayne@69 349 UErrorCode *status);
jpayne@69 350
jpayne@69 351 /**
jpayne@69 352 * Get the subject text that is currently associated with this
jpayne@69 353 * regular expression object. If the input was supplied using uregex_setText(),
jpayne@69 354 * that pointer will be returned. Otherwise, the characters in the input will
jpayne@69 355 * be extracted to a buffer and returned. In either case, ownership remains
jpayne@69 356 * with the regular expression object.
jpayne@69 357 *
jpayne@69 358 * This function will work even if the input was originally specified as a UText.
jpayne@69 359 *
jpayne@69 360 * @param regexp The compiled regular expression.
jpayne@69 361 * @param textLength The length of the string is returned in this output parameter.
jpayne@69 362 * A NULL pointer may be used here if the
jpayne@69 363 * text length is not needed, as would be the case if
jpayne@69 364 * the text is known in advance to be a NUL terminated
jpayne@69 365 * string.
jpayne@69 366 * @param status Receives errors detected by this function.
jpayne@69 367 * @return Pointer to the subject text string currently associated with
jpayne@69 368 * this regular expression.
jpayne@69 369 * @stable ICU 3.0
jpayne@69 370 */
jpayne@69 371 U_STABLE const UChar * U_EXPORT2
jpayne@69 372 uregex_getText(URegularExpression *regexp,
jpayne@69 373 int32_t *textLength,
jpayne@69 374 UErrorCode *status);
jpayne@69 375
jpayne@69 376 /**
jpayne@69 377 * Get the subject text that is currently associated with this
jpayne@69 378 * regular expression object.
jpayne@69 379 *
jpayne@69 380 * This function will work even if the input was originally specified as a UChar string.
jpayne@69 381 *
jpayne@69 382 * @param regexp The compiled regular expression.
jpayne@69 383 * @param dest A mutable UText in which to store the current input.
jpayne@69 384 * If NULL, a new UText will be created as an immutable shallow clone
jpayne@69 385 * of the actual input string.
jpayne@69 386 * @param status Receives errors detected by this function.
jpayne@69 387 * @return The subject text currently associated with this regular expression.
jpayne@69 388 * If a pre-allocated UText was provided, it will always be used and returned.
jpayne@69 389 *
jpayne@69 390 * @stable ICU 4.6
jpayne@69 391 */
jpayne@69 392 U_STABLE UText * U_EXPORT2
jpayne@69 393 uregex_getUText(URegularExpression *regexp,
jpayne@69 394 UText *dest,
jpayne@69 395 UErrorCode *status);
jpayne@69 396
jpayne@69 397 /**
jpayne@69 398 * Set the subject text string upon which the regular expression is looking for matches
jpayne@69 399 * without changing any other aspect of the matching state.
jpayne@69 400 * The new and previous text strings must have the same content.
jpayne@69 401 *
jpayne@69 402 * This function is intended for use in environments where ICU is operating on
jpayne@69 403 * strings that may move around in memory. It provides a mechanism for notifying
jpayne@69 404 * ICU that the string has been relocated, and providing a new UText to access the
jpayne@69 405 * string in its new position.
jpayne@69 406 *
jpayne@69 407 * Note that the regular expression implementation never copies the underlying text
jpayne@69 408 * of a string being matched, but always operates directly on the original text
jpayne@69 409 * provided by the user. Refreshing simply drops the references to the old text
jpayne@69 410 * and replaces them with references to the new.
jpayne@69 411 *
jpayne@69 412 * Caution: this function is normally used only by very specialized
jpayne@69 413 * system-level code. One example use case is with garbage collection
jpayne@69 414 * that moves the text in memory.
jpayne@69 415 *
jpayne@69 416 * @param regexp The compiled regular expression.
jpayne@69 417 * @param text The new (moved) text string.
jpayne@69 418 * @param status Receives errors detected by this function.
jpayne@69 419 *
jpayne@69 420 * @stable ICU 4.8
jpayne@69 421 */
jpayne@69 422 U_STABLE void U_EXPORT2
jpayne@69 423 uregex_refreshUText(URegularExpression *regexp,
jpayne@69 424 UText *text,
jpayne@69 425 UErrorCode *status);
jpayne@69 426
jpayne@69 427 /**
jpayne@69 428 * Attempts to match the input string against the pattern.
jpayne@69 429 * To succeed, the match must extend to the end of the string,
jpayne@69 430 * or cover the complete match region.
jpayne@69 431 *
jpayne@69 432 * If startIndex >= zero the match operation starts at the specified
jpayne@69 433 * index and must extend to the end of the input string. Any region
jpayne@69 434 * that has been specified is reset.
jpayne@69 435 *
jpayne@69 436 * If startIndex == -1 the match must cover the input region, or the entire
jpayne@69 437 * input string if no region has been set. This directly corresponds to
jpayne@69 438 * Matcher.matches() in Java
jpayne@69 439 *
jpayne@69 440 * @param regexp The compiled regular expression.
jpayne@69 441 * @param startIndex The input string (native) index at which to begin matching, or -1
jpayne@69 442 * to match the input Region.
jpayne@69 443 * @param status Receives errors detected by this function.
jpayne@69 444 * @return TRUE if there is a match
jpayne@69 445 * @stable ICU 3.0
jpayne@69 446 */
jpayne@69 447 U_STABLE UBool U_EXPORT2
jpayne@69 448 uregex_matches(URegularExpression *regexp,
jpayne@69 449 int32_t startIndex,
jpayne@69 450 UErrorCode *status);
jpayne@69 451
jpayne@69 452 /**
jpayne@69 453 * 64bit version of uregex_matches.
jpayne@69 454 * Attempts to match the input string against the pattern.
jpayne@69 455 * To succeed, the match must extend to the end of the string,
jpayne@69 456 * or cover the complete match region.
jpayne@69 457 *
jpayne@69 458 * If startIndex >= zero the match operation starts at the specified
jpayne@69 459 * index and must extend to the end of the input string. Any region
jpayne@69 460 * that has been specified is reset.
jpayne@69 461 *
jpayne@69 462 * If startIndex == -1 the match must cover the input region, or the entire
jpayne@69 463 * input string if no region has been set. This directly corresponds to
jpayne@69 464 * Matcher.matches() in Java
jpayne@69 465 *
jpayne@69 466 * @param regexp The compiled regular expression.
jpayne@69 467 * @param startIndex The input string (native) index at which to begin matching, or -1
jpayne@69 468 * to match the input Region.
jpayne@69 469 * @param status Receives errors detected by this function.
jpayne@69 470 * @return TRUE if there is a match
jpayne@69 471 * @stable ICU 4.6
jpayne@69 472 */
jpayne@69 473 U_STABLE UBool U_EXPORT2
jpayne@69 474 uregex_matches64(URegularExpression *regexp,
jpayne@69 475 int64_t startIndex,
jpayne@69 476 UErrorCode *status);
jpayne@69 477
jpayne@69 478 /**
jpayne@69 479 * Attempts to match the input string, starting from the specified index, against the pattern.
jpayne@69 480 * The match may be of any length, and is not required to extend to the end
jpayne@69 481 * of the input string. Contrast with uregex_matches().
jpayne@69 482 *
jpayne@69 483 * <p>If startIndex is >= 0 any input region that was set for this
jpayne@69 484 * URegularExpression is reset before the operation begins.
jpayne@69 485 *
jpayne@69 486 * <p>If the specified starting index == -1 the match begins at the start of the input
jpayne@69 487 * region, or at the start of the full string if no region has been specified.
jpayne@69 488 * This corresponds directly with Matcher.lookingAt() in Java.
jpayne@69 489 *
jpayne@69 490 * <p>If the match succeeds then more information can be obtained via the
jpayne@69 491 * <code>uregexp_start()</code>, <code>uregexp_end()</code>,
jpayne@69 492 * and <code>uregex_group()</code> functions.</p>
jpayne@69 493 *
jpayne@69 494 * @param regexp The compiled regular expression.
jpayne@69 495 * @param startIndex The input string (native) index at which to begin matching, or
jpayne@69 496 * -1 to match the Input Region
jpayne@69 497 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 498 * @return TRUE if there is a match.
jpayne@69 499 * @stable ICU 3.0
jpayne@69 500 */
jpayne@69 501 U_STABLE UBool U_EXPORT2
jpayne@69 502 uregex_lookingAt(URegularExpression *regexp,
jpayne@69 503 int32_t startIndex,
jpayne@69 504 UErrorCode *status);
jpayne@69 505
jpayne@69 506 /**
jpayne@69 507 * 64bit version of uregex_lookingAt.
jpayne@69 508 * Attempts to match the input string, starting from the specified index, against the pattern.
jpayne@69 509 * The match may be of any length, and is not required to extend to the end
jpayne@69 510 * of the input string. Contrast with uregex_matches().
jpayne@69 511 *
jpayne@69 512 * <p>If startIndex is >= 0 any input region that was set for this
jpayne@69 513 * URegularExpression is reset before the operation begins.
jpayne@69 514 *
jpayne@69 515 * <p>If the specified starting index == -1 the match begins at the start of the input
jpayne@69 516 * region, or at the start of the full string if no region has been specified.
jpayne@69 517 * This corresponds directly with Matcher.lookingAt() in Java.
jpayne@69 518 *
jpayne@69 519 * <p>If the match succeeds then more information can be obtained via the
jpayne@69 520 * <code>uregexp_start()</code>, <code>uregexp_end()</code>,
jpayne@69 521 * and <code>uregex_group()</code> functions.</p>
jpayne@69 522 *
jpayne@69 523 * @param regexp The compiled regular expression.
jpayne@69 524 * @param startIndex The input string (native) index at which to begin matching, or
jpayne@69 525 * -1 to match the Input Region
jpayne@69 526 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 527 * @return TRUE if there is a match.
jpayne@69 528 * @stable ICU 4.6
jpayne@69 529 */
jpayne@69 530 U_STABLE UBool U_EXPORT2
jpayne@69 531 uregex_lookingAt64(URegularExpression *regexp,
jpayne@69 532 int64_t startIndex,
jpayne@69 533 UErrorCode *status);
jpayne@69 534
jpayne@69 535 /**
jpayne@69 536 * Find the first matching substring of the input string that matches the pattern.
jpayne@69 537 * If startIndex is >= zero the search for a match begins at the specified index,
jpayne@69 538 * and any match region is reset. This corresponds directly with
jpayne@69 539 * Matcher.find(startIndex) in Java.
jpayne@69 540 *
jpayne@69 541 * If startIndex == -1 the search begins at the start of the input region,
jpayne@69 542 * or at the start of the full string if no region has been specified.
jpayne@69 543 *
jpayne@69 544 * If a match is found, <code>uregex_start(), uregex_end()</code>, and
jpayne@69 545 * <code>uregex_group()</code> will provide more information regarding the match.
jpayne@69 546 *
jpayne@69 547 * @param regexp The compiled regular expression.
jpayne@69 548 * @param startIndex The position (native) in the input string to begin the search, or
jpayne@69 549 * -1 to search within the Input Region.
jpayne@69 550 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 551 * @return TRUE if a match is found.
jpayne@69 552 * @stable ICU 3.0
jpayne@69 553 */
jpayne@69 554 U_STABLE UBool U_EXPORT2
jpayne@69 555 uregex_find(URegularExpression *regexp,
jpayne@69 556 int32_t startIndex,
jpayne@69 557 UErrorCode *status);
jpayne@69 558
jpayne@69 559 /**
jpayne@69 560 * 64bit version of uregex_find.
jpayne@69 561 * Find the first matching substring of the input string that matches the pattern.
jpayne@69 562 * If startIndex is >= zero the search for a match begins at the specified index,
jpayne@69 563 * and any match region is reset. This corresponds directly with
jpayne@69 564 * Matcher.find(startIndex) in Java.
jpayne@69 565 *
jpayne@69 566 * If startIndex == -1 the search begins at the start of the input region,
jpayne@69 567 * or at the start of the full string if no region has been specified.
jpayne@69 568 *
jpayne@69 569 * If a match is found, <code>uregex_start(), uregex_end()</code>, and
jpayne@69 570 * <code>uregex_group()</code> will provide more information regarding the match.
jpayne@69 571 *
jpayne@69 572 * @param regexp The compiled regular expression.
jpayne@69 573 * @param startIndex The position (native) in the input string to begin the search, or
jpayne@69 574 * -1 to search within the Input Region.
jpayne@69 575 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 576 * @return TRUE if a match is found.
jpayne@69 577 * @stable ICU 4.6
jpayne@69 578 */
jpayne@69 579 U_STABLE UBool U_EXPORT2
jpayne@69 580 uregex_find64(URegularExpression *regexp,
jpayne@69 581 int64_t startIndex,
jpayne@69 582 UErrorCode *status);
jpayne@69 583
jpayne@69 584 /**
jpayne@69 585 * Find the next pattern match in the input string. Begin searching
jpayne@69 586 * the input at the location following the end of he previous match,
jpayne@69 587 * or at the start of the string (or region) if there is no
jpayne@69 588 * previous match. If a match is found, <code>uregex_start(), uregex_end()</code>, and
jpayne@69 589 * <code>uregex_group()</code> will provide more information regarding the match.
jpayne@69 590 *
jpayne@69 591 * @param regexp The compiled regular expression.
jpayne@69 592 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 593 * @return TRUE if a match is found.
jpayne@69 594 * @see uregex_reset
jpayne@69 595 * @stable ICU 3.0
jpayne@69 596 */
jpayne@69 597 U_STABLE UBool U_EXPORT2
jpayne@69 598 uregex_findNext(URegularExpression *regexp,
jpayne@69 599 UErrorCode *status);
jpayne@69 600
jpayne@69 601 /**
jpayne@69 602 * Get the number of capturing groups in this regular expression's pattern.
jpayne@69 603 * @param regexp The compiled regular expression.
jpayne@69 604 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 605 * @return the number of capture groups
jpayne@69 606 * @stable ICU 3.0
jpayne@69 607 */
jpayne@69 608 U_STABLE int32_t U_EXPORT2
jpayne@69 609 uregex_groupCount(URegularExpression *regexp,
jpayne@69 610 UErrorCode *status);
jpayne@69 611
jpayne@69 612 /**
jpayne@69 613 * Get the group number corresponding to a named capture group.
jpayne@69 614 * The returned number can be used with any function that access
jpayne@69 615 * capture groups by number.
jpayne@69 616 *
jpayne@69 617 * The function returns an error status if the specified name does not
jpayne@69 618 * appear in the pattern.
jpayne@69 619 *
jpayne@69 620 * @param regexp The compiled regular expression.
jpayne@69 621 * @param groupName The capture group name.
jpayne@69 622 * @param nameLength The length of the name, or -1 if the name is a
jpayne@69 623 * nul-terminated string.
jpayne@69 624 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 625 *
jpayne@69 626 * @stable ICU 55
jpayne@69 627 */
jpayne@69 628 U_STABLE int32_t U_EXPORT2
jpayne@69 629 uregex_groupNumberFromName(URegularExpression *regexp,
jpayne@69 630 const UChar *groupName,
jpayne@69 631 int32_t nameLength,
jpayne@69 632 UErrorCode *status);
jpayne@69 633
jpayne@69 634
jpayne@69 635 /**
jpayne@69 636 * Get the group number corresponding to a named capture group.
jpayne@69 637 * The returned number can be used with any function that access
jpayne@69 638 * capture groups by number.
jpayne@69 639 *
jpayne@69 640 * The function returns an error status if the specified name does not
jpayne@69 641 * appear in the pattern.
jpayne@69 642 *
jpayne@69 643 * @param regexp The compiled regular expression.
jpayne@69 644 * @param groupName The capture group name,
jpayne@69 645 * platform invariant characters only.
jpayne@69 646 * @param nameLength The length of the name, or -1 if the name is
jpayne@69 647 * nul-terminated.
jpayne@69 648 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 649 *
jpayne@69 650 * @stable ICU 55
jpayne@69 651 */
jpayne@69 652 U_STABLE int32_t U_EXPORT2
jpayne@69 653 uregex_groupNumberFromCName(URegularExpression *regexp,
jpayne@69 654 const char *groupName,
jpayne@69 655 int32_t nameLength,
jpayne@69 656 UErrorCode *status);
jpayne@69 657
jpayne@69 658 /** Extract the string for the specified matching expression or subexpression.
jpayne@69 659 * Group #0 is the complete string of matched text.
jpayne@69 660 * Group #1 is the text matched by the first set of capturing parentheses.
jpayne@69 661 *
jpayne@69 662 * @param regexp The compiled regular expression.
jpayne@69 663 * @param groupNum The capture group to extract. Group 0 is the complete
jpayne@69 664 * match. The value of this parameter must be
jpayne@69 665 * less than or equal to the number of capture groups in
jpayne@69 666 * the pattern.
jpayne@69 667 * @param dest Buffer to receive the matching string data
jpayne@69 668 * @param destCapacity Capacity of the dest buffer.
jpayne@69 669 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 670 * @return Length of matching data,
jpayne@69 671 * or -1 if no applicable match.
jpayne@69 672 * @stable ICU 3.0
jpayne@69 673 */
jpayne@69 674 U_STABLE int32_t U_EXPORT2
jpayne@69 675 uregex_group(URegularExpression *regexp,
jpayne@69 676 int32_t groupNum,
jpayne@69 677 UChar *dest,
jpayne@69 678 int32_t destCapacity,
jpayne@69 679 UErrorCode *status);
jpayne@69 680
jpayne@69 681 /** Returns a shallow immutable clone of the entire input string with the current index set
jpayne@69 682 * to the beginning of the requested capture group. The capture group length is also
jpayne@69 683 * returned via groupLength.
jpayne@69 684 * Group #0 is the complete string of matched text.
jpayne@69 685 * Group #1 is the text matched by the first set of capturing parentheses.
jpayne@69 686 *
jpayne@69 687 * @param regexp The compiled regular expression.
jpayne@69 688 * @param groupNum The capture group to extract. Group 0 is the complete
jpayne@69 689 * match. The value of this parameter must be
jpayne@69 690 * less than or equal to the number of capture groups in
jpayne@69 691 * the pattern.
jpayne@69 692 * @param dest A mutable UText in which to store the current input.
jpayne@69 693 * If NULL, a new UText will be created as an immutable shallow clone
jpayne@69 694 * of the entire input string.
jpayne@69 695 * @param groupLength The group length of the desired capture group. Output parameter.
jpayne@69 696 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 697 * @return The subject text currently associated with this regular expression.
jpayne@69 698 * If a pre-allocated UText was provided, it will always be used and returned.
jpayne@69 699
jpayne@69 700 *
jpayne@69 701 * @stable ICU 4.6
jpayne@69 702 */
jpayne@69 703 U_STABLE UText * U_EXPORT2
jpayne@69 704 uregex_groupUText(URegularExpression *regexp,
jpayne@69 705 int32_t groupNum,
jpayne@69 706 UText *dest,
jpayne@69 707 int64_t *groupLength,
jpayne@69 708 UErrorCode *status);
jpayne@69 709
jpayne@69 710 /**
jpayne@69 711 * Returns the index in the input string of the start of the text matched by the
jpayne@69 712 * specified capture group during the previous match operation. Return -1 if
jpayne@69 713 * the capture group was not part of the last match.
jpayne@69 714 * Group #0 refers to the complete range of matched text.
jpayne@69 715 * Group #1 refers to the text matched by the first set of capturing parentheses.
jpayne@69 716 *
jpayne@69 717 * @param regexp The compiled regular expression.
jpayne@69 718 * @param groupNum The capture group number
jpayne@69 719 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 720 * @return the starting (native) position in the input of the text matched
jpayne@69 721 * by the specified group.
jpayne@69 722 * @stable ICU 3.0
jpayne@69 723 */
jpayne@69 724 U_STABLE int32_t U_EXPORT2
jpayne@69 725 uregex_start(URegularExpression *regexp,
jpayne@69 726 int32_t groupNum,
jpayne@69 727 UErrorCode *status);
jpayne@69 728
jpayne@69 729 /**
jpayne@69 730 * 64bit version of uregex_start.
jpayne@69 731 * Returns the index in the input string of the start of the text matched by the
jpayne@69 732 * specified capture group during the previous match operation. Return -1 if
jpayne@69 733 * the capture group was not part of the last match.
jpayne@69 734 * Group #0 refers to the complete range of matched text.
jpayne@69 735 * Group #1 refers to the text matched by the first set of capturing parentheses.
jpayne@69 736 *
jpayne@69 737 * @param regexp The compiled regular expression.
jpayne@69 738 * @param groupNum The capture group number
jpayne@69 739 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 740 * @return the starting (native) position in the input of the text matched
jpayne@69 741 * by the specified group.
jpayne@69 742 * @stable ICU 4.6
jpayne@69 743 */
jpayne@69 744 U_STABLE int64_t U_EXPORT2
jpayne@69 745 uregex_start64(URegularExpression *regexp,
jpayne@69 746 int32_t groupNum,
jpayne@69 747 UErrorCode *status);
jpayne@69 748
jpayne@69 749 /**
jpayne@69 750 * Returns the index in the input string of the position following the end
jpayne@69 751 * of the text matched by the specified capture group.
jpayne@69 752 * Return -1 if the capture group was not part of the last match.
jpayne@69 753 * Group #0 refers to the complete range of matched text.
jpayne@69 754 * Group #1 refers to the text matched by the first set of capturing parentheses.
jpayne@69 755 *
jpayne@69 756 * @param regexp The compiled regular expression.
jpayne@69 757 * @param groupNum The capture group number
jpayne@69 758 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 759 * @return the (native) index of the position following the last matched character.
jpayne@69 760 * @stable ICU 3.0
jpayne@69 761 */
jpayne@69 762 U_STABLE int32_t U_EXPORT2
jpayne@69 763 uregex_end(URegularExpression *regexp,
jpayne@69 764 int32_t groupNum,
jpayne@69 765 UErrorCode *status);
jpayne@69 766
jpayne@69 767 /**
jpayne@69 768 * 64bit version of uregex_end.
jpayne@69 769 * Returns the index in the input string of the position following the end
jpayne@69 770 * of the text matched by the specified capture group.
jpayne@69 771 * Return -1 if the capture group was not part of the last match.
jpayne@69 772 * Group #0 refers to the complete range of matched text.
jpayne@69 773 * Group #1 refers to the text matched by the first set of capturing parentheses.
jpayne@69 774 *
jpayne@69 775 * @param regexp The compiled regular expression.
jpayne@69 776 * @param groupNum The capture group number
jpayne@69 777 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 778 * @return the (native) index of the position following the last matched character.
jpayne@69 779 * @stable ICU 4.6
jpayne@69 780 */
jpayne@69 781 U_STABLE int64_t U_EXPORT2
jpayne@69 782 uregex_end64(URegularExpression *regexp,
jpayne@69 783 int32_t groupNum,
jpayne@69 784 UErrorCode *status);
jpayne@69 785
jpayne@69 786 /**
jpayne@69 787 * Reset any saved state from the previous match. Has the effect of
jpayne@69 788 * causing uregex_findNext to begin at the specified index, and causing
jpayne@69 789 * uregex_start(), uregex_end() and uregex_group() to return an error
jpayne@69 790 * indicating that there is no match information available. Clears any
jpayne@69 791 * match region that may have been set.
jpayne@69 792 *
jpayne@69 793 * @param regexp The compiled regular expression.
jpayne@69 794 * @param index The position (native) in the text at which a
jpayne@69 795 * uregex_findNext() should begin searching.
jpayne@69 796 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 797 * @stable ICU 3.0
jpayne@69 798 */
jpayne@69 799 U_STABLE void U_EXPORT2
jpayne@69 800 uregex_reset(URegularExpression *regexp,
jpayne@69 801 int32_t index,
jpayne@69 802 UErrorCode *status);
jpayne@69 803
jpayne@69 804 /**
jpayne@69 805 * 64bit version of uregex_reset.
jpayne@69 806 * Reset any saved state from the previous match. Has the effect of
jpayne@69 807 * causing uregex_findNext to begin at the specified index, and causing
jpayne@69 808 * uregex_start(), uregex_end() and uregex_group() to return an error
jpayne@69 809 * indicating that there is no match information available. Clears any
jpayne@69 810 * match region that may have been set.
jpayne@69 811 *
jpayne@69 812 * @param regexp The compiled regular expression.
jpayne@69 813 * @param index The position (native) in the text at which a
jpayne@69 814 * uregex_findNext() should begin searching.
jpayne@69 815 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 816 * @stable ICU 4.6
jpayne@69 817 */
jpayne@69 818 U_STABLE void U_EXPORT2
jpayne@69 819 uregex_reset64(URegularExpression *regexp,
jpayne@69 820 int64_t index,
jpayne@69 821 UErrorCode *status);
jpayne@69 822
jpayne@69 823 /**
jpayne@69 824 * Sets the limits of the matching region for this URegularExpression.
jpayne@69 825 * The region is the part of the input string that will be considered when matching.
jpayne@69 826 * Invoking this method resets any saved state from the previous match,
jpayne@69 827 * then sets the region to start at the index specified by the start parameter
jpayne@69 828 * and end at the index specified by the end parameter.
jpayne@69 829 *
jpayne@69 830 * Depending on the transparency and anchoring being used (see useTransparentBounds
jpayne@69 831 * and useAnchoringBounds), certain constructs such as anchors may behave differently
jpayne@69 832 * at or around the boundaries of the region
jpayne@69 833 *
jpayne@69 834 * The function will fail if start is greater than limit, or if either index
jpayne@69 835 * is less than zero or greater than the length of the string being matched.
jpayne@69 836 *
jpayne@69 837 * @param regexp The compiled regular expression.
jpayne@69 838 * @param regionStart The (native) index to begin searches at.
jpayne@69 839 * @param regionLimit The (native) index to end searches at (exclusive).
jpayne@69 840 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 841 * @stable ICU 4.0
jpayne@69 842 */
jpayne@69 843 U_STABLE void U_EXPORT2
jpayne@69 844 uregex_setRegion(URegularExpression *regexp,
jpayne@69 845 int32_t regionStart,
jpayne@69 846 int32_t regionLimit,
jpayne@69 847 UErrorCode *status);
jpayne@69 848
jpayne@69 849 /**
jpayne@69 850 * 64bit version of uregex_setRegion.
jpayne@69 851 * Sets the limits of the matching region for this URegularExpression.
jpayne@69 852 * The region is the part of the input string that will be considered when matching.
jpayne@69 853 * Invoking this method resets any saved state from the previous match,
jpayne@69 854 * then sets the region to start at the index specified by the start parameter
jpayne@69 855 * and end at the index specified by the end parameter.
jpayne@69 856 *
jpayne@69 857 * Depending on the transparency and anchoring being used (see useTransparentBounds
jpayne@69 858 * and useAnchoringBounds), certain constructs such as anchors may behave differently
jpayne@69 859 * at or around the boundaries of the region
jpayne@69 860 *
jpayne@69 861 * The function will fail if start is greater than limit, or if either index
jpayne@69 862 * is less than zero or greater than the length of the string being matched.
jpayne@69 863 *
jpayne@69 864 * @param regexp The compiled regular expression.
jpayne@69 865 * @param regionStart The (native) index to begin searches at.
jpayne@69 866 * @param regionLimit The (native) index to end searches at (exclusive).
jpayne@69 867 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 868 * @stable ICU 4.6
jpayne@69 869 */
jpayne@69 870 U_STABLE void U_EXPORT2
jpayne@69 871 uregex_setRegion64(URegularExpression *regexp,
jpayne@69 872 int64_t regionStart,
jpayne@69 873 int64_t regionLimit,
jpayne@69 874 UErrorCode *status);
jpayne@69 875
jpayne@69 876 /**
jpayne@69 877 * Set the matching region and the starting index for subsequent matches
jpayne@69 878 * in a single operation.
jpayne@69 879 * This is useful because the usual function for setting the starting
jpayne@69 880 * index, urgex_reset(), also resets any region limits.
jpayne@69 881 *
jpayne@69 882 * @param regexp The compiled regular expression.
jpayne@69 883 * @param regionStart The (native) index to begin searches at.
jpayne@69 884 * @param regionLimit The (native) index to end searches at (exclusive).
jpayne@69 885 * @param startIndex The index in the input text at which the next
jpayne@69 886 * match operation should begin.
jpayne@69 887 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 888 * @stable ICU 4.6
jpayne@69 889 */
jpayne@69 890 U_STABLE void U_EXPORT2
jpayne@69 891 uregex_setRegionAndStart(URegularExpression *regexp,
jpayne@69 892 int64_t regionStart,
jpayne@69 893 int64_t regionLimit,
jpayne@69 894 int64_t startIndex,
jpayne@69 895 UErrorCode *status);
jpayne@69 896
jpayne@69 897 /**
jpayne@69 898 * Reports the start index of the matching region. Any matches found are limited to
jpayne@69 899 * to the region bounded by regionStart (inclusive) and regionEnd (exclusive).
jpayne@69 900 *
jpayne@69 901 * @param regexp The compiled regular expression.
jpayne@69 902 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 903 * @return The starting (native) index of this matcher's region.
jpayne@69 904 * @stable ICU 4.0
jpayne@69 905 */
jpayne@69 906 U_STABLE int32_t U_EXPORT2
jpayne@69 907 uregex_regionStart(const URegularExpression *regexp,
jpayne@69 908 UErrorCode *status);
jpayne@69 909
jpayne@69 910 /**
jpayne@69 911 * 64bit version of uregex_regionStart.
jpayne@69 912 * Reports the start index of the matching region. Any matches found are limited to
jpayne@69 913 * to the region bounded by regionStart (inclusive) and regionEnd (exclusive).
jpayne@69 914 *
jpayne@69 915 * @param regexp The compiled regular expression.
jpayne@69 916 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 917 * @return The starting (native) index of this matcher's region.
jpayne@69 918 * @stable ICU 4.6
jpayne@69 919 */
jpayne@69 920 U_STABLE int64_t U_EXPORT2
jpayne@69 921 uregex_regionStart64(const URegularExpression *regexp,
jpayne@69 922 UErrorCode *status);
jpayne@69 923
jpayne@69 924 /**
jpayne@69 925 * Reports the end index (exclusive) of the matching region for this URegularExpression.
jpayne@69 926 * Any matches found are limited to to the region bounded by regionStart (inclusive)
jpayne@69 927 * and regionEnd (exclusive).
jpayne@69 928 *
jpayne@69 929 * @param regexp The compiled regular expression.
jpayne@69 930 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 931 * @return The ending point (native) of this matcher's region.
jpayne@69 932 * @stable ICU 4.0
jpayne@69 933 */
jpayne@69 934 U_STABLE int32_t U_EXPORT2
jpayne@69 935 uregex_regionEnd(const URegularExpression *regexp,
jpayne@69 936 UErrorCode *status);
jpayne@69 937
jpayne@69 938 /**
jpayne@69 939 * 64bit version of uregex_regionEnd.
jpayne@69 940 * Reports the end index (exclusive) of the matching region for this URegularExpression.
jpayne@69 941 * Any matches found are limited to to the region bounded by regionStart (inclusive)
jpayne@69 942 * and regionEnd (exclusive).
jpayne@69 943 *
jpayne@69 944 * @param regexp The compiled regular expression.
jpayne@69 945 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 946 * @return The ending point (native) of this matcher's region.
jpayne@69 947 * @stable ICU 4.6
jpayne@69 948 */
jpayne@69 949 U_STABLE int64_t U_EXPORT2
jpayne@69 950 uregex_regionEnd64(const URegularExpression *regexp,
jpayne@69 951 UErrorCode *status);
jpayne@69 952
jpayne@69 953 /**
jpayne@69 954 * Queries the transparency of region bounds for this URegularExpression.
jpayne@69 955 * See useTransparentBounds for a description of transparent and opaque bounds.
jpayne@69 956 * By default, matching boundaries are opaque.
jpayne@69 957 *
jpayne@69 958 * @param regexp The compiled regular expression.
jpayne@69 959 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 960 * @return TRUE if this matcher is using opaque bounds, false if it is not.
jpayne@69 961 * @stable ICU 4.0
jpayne@69 962 */
jpayne@69 963 U_STABLE UBool U_EXPORT2
jpayne@69 964 uregex_hasTransparentBounds(const URegularExpression *regexp,
jpayne@69 965 UErrorCode *status);
jpayne@69 966
jpayne@69 967
jpayne@69 968 /**
jpayne@69 969 * Sets the transparency of region bounds for this URegularExpression.
jpayne@69 970 * Invoking this function with an argument of TRUE will set matches to use transparent bounds.
jpayne@69 971 * If the boolean argument is FALSE, then opaque bounds will be used.
jpayne@69 972 *
jpayne@69 973 * Using transparent bounds, the boundaries of the matching region are transparent
jpayne@69 974 * to lookahead, lookbehind, and boundary matching constructs. Those constructs can
jpayne@69 975 * see text beyond the boundaries of the region while checking for a match.
jpayne@69 976 *
jpayne@69 977 * With opaque bounds, no text outside of the matching region is visible to lookahead,
jpayne@69 978 * lookbehind, and boundary matching constructs.
jpayne@69 979 *
jpayne@69 980 * By default, opaque bounds are used.
jpayne@69 981 *
jpayne@69 982 * @param regexp The compiled regular expression.
jpayne@69 983 * @param b TRUE for transparent bounds; FALSE for opaque bounds
jpayne@69 984 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 985 * @stable ICU 4.0
jpayne@69 986 **/
jpayne@69 987 U_STABLE void U_EXPORT2
jpayne@69 988 uregex_useTransparentBounds(URegularExpression *regexp,
jpayne@69 989 UBool b,
jpayne@69 990 UErrorCode *status);
jpayne@69 991
jpayne@69 992
jpayne@69 993 /**
jpayne@69 994 * Return true if this URegularExpression is using anchoring bounds.
jpayne@69 995 * By default, anchoring region bounds are used.
jpayne@69 996 *
jpayne@69 997 * @param regexp The compiled regular expression.
jpayne@69 998 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 999 * @return TRUE if this matcher is using anchoring bounds.
jpayne@69 1000 * @stable ICU 4.0
jpayne@69 1001 */
jpayne@69 1002 U_STABLE UBool U_EXPORT2
jpayne@69 1003 uregex_hasAnchoringBounds(const URegularExpression *regexp,
jpayne@69 1004 UErrorCode *status);
jpayne@69 1005
jpayne@69 1006
jpayne@69 1007 /**
jpayne@69 1008 * Set whether this URegularExpression is using Anchoring Bounds for its region.
jpayne@69 1009 * With anchoring bounds, pattern anchors such as ^ and $ will match at the start
jpayne@69 1010 * and end of the region. Without Anchoring Bounds, anchors will only match at
jpayne@69 1011 * the positions they would in the complete text.
jpayne@69 1012 *
jpayne@69 1013 * Anchoring Bounds are the default for regions.
jpayne@69 1014 *
jpayne@69 1015 * @param regexp The compiled regular expression.
jpayne@69 1016 * @param b TRUE if to enable anchoring bounds; FALSE to disable them.
jpayne@69 1017 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 1018 * @stable ICU 4.0
jpayne@69 1019 */
jpayne@69 1020 U_STABLE void U_EXPORT2
jpayne@69 1021 uregex_useAnchoringBounds(URegularExpression *regexp,
jpayne@69 1022 UBool b,
jpayne@69 1023 UErrorCode *status);
jpayne@69 1024
jpayne@69 1025 /**
jpayne@69 1026 * Return TRUE if the most recent matching operation touched the
jpayne@69 1027 * end of the text being processed. In this case, additional input text could
jpayne@69 1028 * change the results of that match.
jpayne@69 1029 *
jpayne@69 1030 * @param regexp The compiled regular expression.
jpayne@69 1031 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 1032 * @return TRUE if the most recent match hit the end of input
jpayne@69 1033 * @stable ICU 4.0
jpayne@69 1034 */
jpayne@69 1035 U_STABLE UBool U_EXPORT2
jpayne@69 1036 uregex_hitEnd(const URegularExpression *regexp,
jpayne@69 1037 UErrorCode *status);
jpayne@69 1038
jpayne@69 1039 /**
jpayne@69 1040 * Return TRUE the most recent match succeeded and additional input could cause
jpayne@69 1041 * it to fail. If this function returns false and a match was found, then more input
jpayne@69 1042 * might change the match but the match won't be lost. If a match was not found,
jpayne@69 1043 * then requireEnd has no meaning.
jpayne@69 1044 *
jpayne@69 1045 * @param regexp The compiled regular expression.
jpayne@69 1046 * @param status A pointer to a UErrorCode to receive any errors.
jpayne@69 1047 * @return TRUE if more input could cause the most recent match to no longer match.
jpayne@69 1048 * @stable ICU 4.0
jpayne@69 1049 */
jpayne@69 1050 U_STABLE UBool U_EXPORT2
jpayne@69 1051 uregex_requireEnd(const URegularExpression *regexp,
jpayne@69 1052 UErrorCode *status);
jpayne@69 1053
jpayne@69 1054
jpayne@69 1055
jpayne@69 1056
jpayne@69 1057
jpayne@69 1058 /**
jpayne@69 1059 * Replaces every substring of the input that matches the pattern
jpayne@69 1060 * with the given replacement string. This is a convenience function that
jpayne@69 1061 * provides a complete find-and-replace-all operation.
jpayne@69 1062 *
jpayne@69 1063 * This method scans the input string looking for matches of the pattern.
jpayne@69 1064 * Input that is not part of any match is copied unchanged to the
jpayne@69 1065 * destination buffer. Matched regions are replaced in the output
jpayne@69 1066 * buffer by the replacement string. The replacement string may contain
jpayne@69 1067 * references to capture groups; these take the form of $1, $2, etc.
jpayne@69 1068 *
jpayne@69 1069 * @param regexp The compiled regular expression.
jpayne@69 1070 * @param replacementText A string containing the replacement text.
jpayne@69 1071 * @param replacementLength The length of the replacement string, or
jpayne@69 1072 * -1 if it is NUL terminated.
jpayne@69 1073 * @param destBuf A (UChar *) buffer that will receive the result.
jpayne@69 1074 * @param destCapacity The capacity of the destination buffer.
jpayne@69 1075 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1076 * @return The length of the string resulting from the find
jpayne@69 1077 * and replace operation. In the event that the
jpayne@69 1078 * destination capacity is inadequate, the return value
jpayne@69 1079 * is still the full length of the untruncated string.
jpayne@69 1080 * @stable ICU 3.0
jpayne@69 1081 */
jpayne@69 1082 U_STABLE int32_t U_EXPORT2
jpayne@69 1083 uregex_replaceAll(URegularExpression *regexp,
jpayne@69 1084 const UChar *replacementText,
jpayne@69 1085 int32_t replacementLength,
jpayne@69 1086 UChar *destBuf,
jpayne@69 1087 int32_t destCapacity,
jpayne@69 1088 UErrorCode *status);
jpayne@69 1089
jpayne@69 1090 /**
jpayne@69 1091 * Replaces every substring of the input that matches the pattern
jpayne@69 1092 * with the given replacement string. This is a convenience function that
jpayne@69 1093 * provides a complete find-and-replace-all operation.
jpayne@69 1094 *
jpayne@69 1095 * This method scans the input string looking for matches of the pattern.
jpayne@69 1096 * Input that is not part of any match is copied unchanged to the
jpayne@69 1097 * destination buffer. Matched regions are replaced in the output
jpayne@69 1098 * buffer by the replacement string. The replacement string may contain
jpayne@69 1099 * references to capture groups; these take the form of $1, $2, etc.
jpayne@69 1100 *
jpayne@69 1101 * @param regexp The compiled regular expression.
jpayne@69 1102 * @param replacement A string containing the replacement text.
jpayne@69 1103 * @param dest A mutable UText that will receive the result.
jpayne@69 1104 * If NULL, a new UText will be created (which may not be mutable).
jpayne@69 1105 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1106 * @return A UText containing the results of the find and replace.
jpayne@69 1107 * If a pre-allocated UText was provided, it will always be used and returned.
jpayne@69 1108 *
jpayne@69 1109 * @stable ICU 4.6
jpayne@69 1110 */
jpayne@69 1111 U_STABLE UText * U_EXPORT2
jpayne@69 1112 uregex_replaceAllUText(URegularExpression *regexp,
jpayne@69 1113 UText *replacement,
jpayne@69 1114 UText *dest,
jpayne@69 1115 UErrorCode *status);
jpayne@69 1116
jpayne@69 1117 /**
jpayne@69 1118 * Replaces the first substring of the input that matches the pattern
jpayne@69 1119 * with the given replacement string. This is a convenience function that
jpayne@69 1120 * provides a complete find-and-replace operation.
jpayne@69 1121 *
jpayne@69 1122 * This method scans the input string looking for a match of the pattern.
jpayne@69 1123 * All input that is not part of the match is copied unchanged to the
jpayne@69 1124 * destination buffer. The matched region is replaced in the output
jpayne@69 1125 * buffer by the replacement string. The replacement string may contain
jpayne@69 1126 * references to capture groups; these take the form of $1, $2, etc.
jpayne@69 1127 *
jpayne@69 1128 * @param regexp The compiled regular expression.
jpayne@69 1129 * @param replacementText A string containing the replacement text.
jpayne@69 1130 * @param replacementLength The length of the replacement string, or
jpayne@69 1131 * -1 if it is NUL terminated.
jpayne@69 1132 * @param destBuf A (UChar *) buffer that will receive the result.
jpayne@69 1133 * @param destCapacity The capacity of the destination buffer.
jpayne@69 1134 * @param status a reference to a UErrorCode to receive any errors.
jpayne@69 1135 * @return The length of the string resulting from the find
jpayne@69 1136 * and replace operation. In the event that the
jpayne@69 1137 * destination capacity is inadequate, the return value
jpayne@69 1138 * is still the full length of the untruncated string.
jpayne@69 1139 * @stable ICU 3.0
jpayne@69 1140 */
jpayne@69 1141 U_STABLE int32_t U_EXPORT2
jpayne@69 1142 uregex_replaceFirst(URegularExpression *regexp,
jpayne@69 1143 const UChar *replacementText,
jpayne@69 1144 int32_t replacementLength,
jpayne@69 1145 UChar *destBuf,
jpayne@69 1146 int32_t destCapacity,
jpayne@69 1147 UErrorCode *status);
jpayne@69 1148
jpayne@69 1149 /**
jpayne@69 1150 * Replaces the first substring of the input that matches the pattern
jpayne@69 1151 * with the given replacement string. This is a convenience function that
jpayne@69 1152 * provides a complete find-and-replace operation.
jpayne@69 1153 *
jpayne@69 1154 * This method scans the input string looking for a match of the pattern.
jpayne@69 1155 * All input that is not part of the match is copied unchanged to the
jpayne@69 1156 * destination buffer. The matched region is replaced in the output
jpayne@69 1157 * buffer by the replacement string. The replacement string may contain
jpayne@69 1158 * references to capture groups; these take the form of $1, $2, etc.
jpayne@69 1159 *
jpayne@69 1160 * @param regexp The compiled regular expression.
jpayne@69 1161 * @param replacement A string containing the replacement text.
jpayne@69 1162 * @param dest A mutable UText that will receive the result.
jpayne@69 1163 * If NULL, a new UText will be created (which may not be mutable).
jpayne@69 1164 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1165 * @return A UText containing the results of the find and replace.
jpayne@69 1166 * If a pre-allocated UText was provided, it will always be used and returned.
jpayne@69 1167 *
jpayne@69 1168 * @stable ICU 4.6
jpayne@69 1169 */
jpayne@69 1170 U_STABLE UText * U_EXPORT2
jpayne@69 1171 uregex_replaceFirstUText(URegularExpression *regexp,
jpayne@69 1172 UText *replacement,
jpayne@69 1173 UText *dest,
jpayne@69 1174 UErrorCode *status);
jpayne@69 1175
jpayne@69 1176 /**
jpayne@69 1177 * Implements a replace operation intended to be used as part of an
jpayne@69 1178 * incremental find-and-replace.
jpayne@69 1179 *
jpayne@69 1180 * <p>The input string, starting from the end of the previous match and ending at
jpayne@69 1181 * the start of the current match, is appended to the destination string. Then the
jpayne@69 1182 * replacement string is appended to the output string,
jpayne@69 1183 * including handling any substitutions of captured text.</p>
jpayne@69 1184 *
jpayne@69 1185 * <p>A note on preflight computation of buffersize and error handling:
jpayne@69 1186 * Calls to uregex_appendReplacement() and uregex_appendTail() are
jpayne@69 1187 * designed to be chained, one after another, with the destination
jpayne@69 1188 * buffer pointer and buffer capacity updated after each in preparation
jpayne@69 1189 * to for the next. If the destination buffer is exhausted partway through such a
jpayne@69 1190 * sequence, a U_BUFFER_OVERFLOW_ERROR status will be returned. Normal
jpayne@69 1191 * ICU conventions are for a function to perform no action if it is
jpayne@69 1192 * called with an error status, but for this one case, uregex_appendRepacement()
jpayne@69 1193 * will operate normally so that buffer size computations will complete
jpayne@69 1194 * correctly.
jpayne@69 1195 *
jpayne@69 1196 * <p>For simple, prepackaged, non-incremental find-and-replace
jpayne@69 1197 * operations, see replaceFirst() or replaceAll().</p>
jpayne@69 1198 *
jpayne@69 1199 * @param regexp The regular expression object.
jpayne@69 1200 * @param replacementText The string that will replace the matched portion of the
jpayne@69 1201 * input string as it is copied to the destination buffer.
jpayne@69 1202 * The replacement text may contain references ($1, for
jpayne@69 1203 * example) to capture groups from the match.
jpayne@69 1204 * @param replacementLength The length of the replacement text string,
jpayne@69 1205 * or -1 if the string is NUL terminated.
jpayne@69 1206 * @param destBuf The buffer into which the results of the
jpayne@69 1207 * find-and-replace are placed. On return, this pointer
jpayne@69 1208 * will be updated to refer to the beginning of the
jpayne@69 1209 * unused portion of buffer, leaving it in position for
jpayne@69 1210 * a subsequent call to this function.
jpayne@69 1211 * @param destCapacity The size of the output buffer, On return, this
jpayne@69 1212 * parameter will be updated to reflect the space remaining
jpayne@69 1213 * unused in the output buffer.
jpayne@69 1214 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1215 * @return The length of the result string. In the event that
jpayne@69 1216 * destCapacity is inadequate, the full length of the
jpayne@69 1217 * untruncated output string is returned.
jpayne@69 1218 *
jpayne@69 1219 * @stable ICU 3.0
jpayne@69 1220 *
jpayne@69 1221 */
jpayne@69 1222 U_STABLE int32_t U_EXPORT2
jpayne@69 1223 uregex_appendReplacement(URegularExpression *regexp,
jpayne@69 1224 const UChar *replacementText,
jpayne@69 1225 int32_t replacementLength,
jpayne@69 1226 UChar **destBuf,
jpayne@69 1227 int32_t *destCapacity,
jpayne@69 1228 UErrorCode *status);
jpayne@69 1229
jpayne@69 1230 /**
jpayne@69 1231 * Implements a replace operation intended to be used as part of an
jpayne@69 1232 * incremental find-and-replace.
jpayne@69 1233 *
jpayne@69 1234 * <p>The input string, starting from the end of the previous match and ending at
jpayne@69 1235 * the start of the current match, is appended to the destination string. Then the
jpayne@69 1236 * replacement string is appended to the output string,
jpayne@69 1237 * including handling any substitutions of captured text.</p>
jpayne@69 1238 *
jpayne@69 1239 * <p>For simple, prepackaged, non-incremental find-and-replace
jpayne@69 1240 * operations, see replaceFirst() or replaceAll().</p>
jpayne@69 1241 *
jpayne@69 1242 * @param regexp The regular expression object.
jpayne@69 1243 * @param replacementText The string that will replace the matched portion of the
jpayne@69 1244 * input string as it is copied to the destination buffer.
jpayne@69 1245 * The replacement text may contain references ($1, for
jpayne@69 1246 * example) to capture groups from the match.
jpayne@69 1247 * @param dest A mutable UText that will receive the result. Must not be NULL.
jpayne@69 1248 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1249 *
jpayne@69 1250 * @stable ICU 4.6
jpayne@69 1251 */
jpayne@69 1252 U_STABLE void U_EXPORT2
jpayne@69 1253 uregex_appendReplacementUText(URegularExpression *regexp,
jpayne@69 1254 UText *replacementText,
jpayne@69 1255 UText *dest,
jpayne@69 1256 UErrorCode *status);
jpayne@69 1257
jpayne@69 1258 /**
jpayne@69 1259 * As the final step in a find-and-replace operation, append the remainder
jpayne@69 1260 * of the input string, starting at the position following the last match,
jpayne@69 1261 * to the destination string. <code>uregex_appendTail()</code> is intended
jpayne@69 1262 * to be invoked after one or more invocations of the
jpayne@69 1263 * <code>uregex_appendReplacement()</code> function.
jpayne@69 1264 *
jpayne@69 1265 * @param regexp The regular expression object. This is needed to
jpayne@69 1266 * obtain the input string and with the position
jpayne@69 1267 * of the last match within it.
jpayne@69 1268 * @param destBuf The buffer in which the results of the
jpayne@69 1269 * find-and-replace are placed. On return, the pointer
jpayne@69 1270 * will be updated to refer to the beginning of the
jpayne@69 1271 * unused portion of buffer.
jpayne@69 1272 * @param destCapacity The size of the output buffer, On return, this
jpayne@69 1273 * value will be updated to reflect the space remaining
jpayne@69 1274 * unused in the output buffer.
jpayne@69 1275 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1276 * @return The length of the result string. In the event that
jpayne@69 1277 * destCapacity is inadequate, the full length of the
jpayne@69 1278 * untruncated output string is returned.
jpayne@69 1279 *
jpayne@69 1280 * @stable ICU 3.0
jpayne@69 1281 */
jpayne@69 1282 U_STABLE int32_t U_EXPORT2
jpayne@69 1283 uregex_appendTail(URegularExpression *regexp,
jpayne@69 1284 UChar **destBuf,
jpayne@69 1285 int32_t *destCapacity,
jpayne@69 1286 UErrorCode *status);
jpayne@69 1287
jpayne@69 1288 /**
jpayne@69 1289 * As the final step in a find-and-replace operation, append the remainder
jpayne@69 1290 * of the input string, starting at the position following the last match,
jpayne@69 1291 * to the destination string. <code>uregex_appendTailUText()</code> is intended
jpayne@69 1292 * to be invoked after one or more invocations of the
jpayne@69 1293 * <code>uregex_appendReplacementUText()</code> function.
jpayne@69 1294 *
jpayne@69 1295 * @param regexp The regular expression object. This is needed to
jpayne@69 1296 * obtain the input string and with the position
jpayne@69 1297 * of the last match within it.
jpayne@69 1298 * @param dest A mutable UText that will receive the result. Must not be NULL.
jpayne@69 1299 *
jpayne@69 1300 * @param status Error code
jpayne@69 1301 *
jpayne@69 1302 * @return The destination UText.
jpayne@69 1303 *
jpayne@69 1304 * @stable ICU 4.6
jpayne@69 1305 */
jpayne@69 1306 U_STABLE UText * U_EXPORT2
jpayne@69 1307 uregex_appendTailUText(URegularExpression *regexp,
jpayne@69 1308 UText *dest,
jpayne@69 1309 UErrorCode *status);
jpayne@69 1310
jpayne@69 1311 /**
jpayne@69 1312 * Split a string into fields. Somewhat like split() from Perl.
jpayne@69 1313 * The pattern matches identify delimiters that separate the input
jpayne@69 1314 * into fields. The input data between the matches becomes the
jpayne@69 1315 * fields themselves.
jpayne@69 1316 *
jpayne@69 1317 * Each of the fields is copied from the input string to the destination
jpayne@69 1318 * buffer, and NUL terminated. The position of each field within
jpayne@69 1319 * the destination buffer is returned in the destFields array.
jpayne@69 1320 *
jpayne@69 1321 * If the delimiter pattern includes capture groups, the captured text will
jpayne@69 1322 * also appear in the destination array of output strings, interspersed
jpayne@69 1323 * with the fields. This is similar to Perl, but differs from Java,
jpayne@69 1324 * which ignores the presence of capture groups in the pattern.
jpayne@69 1325 *
jpayne@69 1326 * Trailing empty fields will always be returned, assuming sufficient
jpayne@69 1327 * destination capacity. This differs from the default behavior for Java
jpayne@69 1328 * and Perl where trailing empty fields are not returned.
jpayne@69 1329 *
jpayne@69 1330 * The number of strings produced by the split operation is returned.
jpayne@69 1331 * This count includes the strings from capture groups in the delimiter pattern.
jpayne@69 1332 * This behavior differs from Java, which ignores capture groups.
jpayne@69 1333 *
jpayne@69 1334 * @param regexp The compiled regular expression.
jpayne@69 1335 * @param destBuf A (UChar *) buffer to receive the fields that
jpayne@69 1336 * are extracted from the input string. These
jpayne@69 1337 * field pointers will refer to positions within the
jpayne@69 1338 * destination buffer supplied by the caller. Any
jpayne@69 1339 * extra positions within the destFields array will be
jpayne@69 1340 * set to NULL.
jpayne@69 1341 * @param destCapacity The capacity of the destBuf.
jpayne@69 1342 * @param requiredCapacity The actual capacity required of the destBuf.
jpayne@69 1343 * If destCapacity is too small, requiredCapacity will return
jpayne@69 1344 * the total capacity required to hold all of the output, and
jpayne@69 1345 * a U_BUFFER_OVERFLOW_ERROR will be returned.
jpayne@69 1346 * @param destFields An array to be filled with the position of each
jpayne@69 1347 * of the extracted fields within destBuf.
jpayne@69 1348 * @param destFieldsCapacity The number of elements in the destFields array.
jpayne@69 1349 * If the number of fields found is less than destFieldsCapacity,
jpayne@69 1350 * the extra destFields elements are set to zero.
jpayne@69 1351 * If destFieldsCapacity is too small, the trailing part of the
jpayne@69 1352 * input, including any field delimiters, is treated as if it
jpayne@69 1353 * were the last field - it is copied to the destBuf, and
jpayne@69 1354 * its position is in the destBuf is stored in the last element
jpayne@69 1355 * of destFields. This behavior mimics that of Perl. It is not
jpayne@69 1356 * an error condition, and no error status is returned when all destField
jpayne@69 1357 * positions are used.
jpayne@69 1358 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1359 * @return The number of fields into which the input string was split.
jpayne@69 1360 * @stable ICU 3.0
jpayne@69 1361 */
jpayne@69 1362 U_STABLE int32_t U_EXPORT2
jpayne@69 1363 uregex_split( URegularExpression *regexp,
jpayne@69 1364 UChar *destBuf,
jpayne@69 1365 int32_t destCapacity,
jpayne@69 1366 int32_t *requiredCapacity,
jpayne@69 1367 UChar *destFields[],
jpayne@69 1368 int32_t destFieldsCapacity,
jpayne@69 1369 UErrorCode *status);
jpayne@69 1370
jpayne@69 1371 /**
jpayne@69 1372 * Split a string into fields. Somewhat like split() from Perl.
jpayne@69 1373 * The pattern matches identify delimiters that separate the input
jpayne@69 1374 * into fields. The input data between the matches becomes the
jpayne@69 1375 * fields themselves.
jpayne@69 1376 * <p>
jpayne@69 1377 * The behavior of this function is not very closely aligned with uregex_split();
jpayne@69 1378 * instead, it is based on (and implemented directly on top of) the C++ split method.
jpayne@69 1379 *
jpayne@69 1380 * @param regexp The compiled regular expression.
jpayne@69 1381 * @param destFields An array of mutable UText structs to receive the results of the split.
jpayne@69 1382 * If a field is NULL, a new UText is allocated to contain the results for
jpayne@69 1383 * that field. This new UText is not guaranteed to be mutable.
jpayne@69 1384 * @param destFieldsCapacity The number of elements in the destination array.
jpayne@69 1385 * If the number of fields found is less than destCapacity, the
jpayne@69 1386 * extra strings in the destination array are not altered.
jpayne@69 1387 * If the number of destination strings is less than the number
jpayne@69 1388 * of fields, the trailing part of the input string, including any
jpayne@69 1389 * field delimiters, is placed in the last destination string.
jpayne@69 1390 * This behavior mimics that of Perl. It is not an error condition, and no
jpayne@69 1391 * error status is returned when all destField positions are used.
jpayne@69 1392 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1393 * @return The number of fields into which the input string was split.
jpayne@69 1394 *
jpayne@69 1395 * @stable ICU 4.6
jpayne@69 1396 */
jpayne@69 1397 U_STABLE int32_t U_EXPORT2
jpayne@69 1398 uregex_splitUText(URegularExpression *regexp,
jpayne@69 1399 UText *destFields[],
jpayne@69 1400 int32_t destFieldsCapacity,
jpayne@69 1401 UErrorCode *status);
jpayne@69 1402
jpayne@69 1403 /**
jpayne@69 1404 * Set a processing time limit for match operations with this URegularExpression.
jpayne@69 1405 *
jpayne@69 1406 * Some patterns, when matching certain strings, can run in exponential time.
jpayne@69 1407 * For practical purposes, the match operation may appear to be in an
jpayne@69 1408 * infinite loop.
jpayne@69 1409 * When a limit is set a match operation will fail with an error if the
jpayne@69 1410 * limit is exceeded.
jpayne@69 1411 * <p>
jpayne@69 1412 * The units of the limit are steps of the match engine.
jpayne@69 1413 * Correspondence with actual processor time will depend on the speed
jpayne@69 1414 * of the processor and the details of the specific pattern, but will
jpayne@69 1415 * typically be on the order of milliseconds.
jpayne@69 1416 * <p>
jpayne@69 1417 * By default, the matching time is not limited.
jpayne@69 1418 * <p>
jpayne@69 1419 *
jpayne@69 1420 * @param regexp The compiled regular expression.
jpayne@69 1421 * @param limit The limit value, or 0 for no limit.
jpayne@69 1422 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1423 * @stable ICU 4.0
jpayne@69 1424 */
jpayne@69 1425 U_STABLE void U_EXPORT2
jpayne@69 1426 uregex_setTimeLimit(URegularExpression *regexp,
jpayne@69 1427 int32_t limit,
jpayne@69 1428 UErrorCode *status);
jpayne@69 1429
jpayne@69 1430 /**
jpayne@69 1431 * Get the time limit for for matches with this URegularExpression.
jpayne@69 1432 * A return value of zero indicates that there is no limit.
jpayne@69 1433 *
jpayne@69 1434 * @param regexp The compiled regular expression.
jpayne@69 1435 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1436 * @return the maximum allowed time for a match, in units of processing steps.
jpayne@69 1437 * @stable ICU 4.0
jpayne@69 1438 */
jpayne@69 1439 U_STABLE int32_t U_EXPORT2
jpayne@69 1440 uregex_getTimeLimit(const URegularExpression *regexp,
jpayne@69 1441 UErrorCode *status);
jpayne@69 1442
jpayne@69 1443 /**
jpayne@69 1444 * Set the amount of heap storage available for use by the match backtracking stack.
jpayne@69 1445 * <p>
jpayne@69 1446 * ICU uses a backtracking regular expression engine, with the backtrack stack
jpayne@69 1447 * maintained on the heap. This function sets the limit to the amount of memory
jpayne@69 1448 * that can be used for this purpose. A backtracking stack overflow will
jpayne@69 1449 * result in an error from the match operation that caused it.
jpayne@69 1450 * <p>
jpayne@69 1451 * A limit is desirable because a malicious or poorly designed pattern can use
jpayne@69 1452 * excessive memory, potentially crashing the process. A limit is enabled
jpayne@69 1453 * by default.
jpayne@69 1454 * <p>
jpayne@69 1455 * @param regexp The compiled regular expression.
jpayne@69 1456 * @param limit The maximum size, in bytes, of the matching backtrack stack.
jpayne@69 1457 * A value of zero means no limit.
jpayne@69 1458 * The limit must be greater than or equal to zero.
jpayne@69 1459 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1460 *
jpayne@69 1461 * @stable ICU 4.0
jpayne@69 1462 */
jpayne@69 1463 U_STABLE void U_EXPORT2
jpayne@69 1464 uregex_setStackLimit(URegularExpression *regexp,
jpayne@69 1465 int32_t limit,
jpayne@69 1466 UErrorCode *status);
jpayne@69 1467
jpayne@69 1468 /**
jpayne@69 1469 * Get the size of the heap storage available for use by the back tracking stack.
jpayne@69 1470 *
jpayne@69 1471 * @return the maximum backtracking stack size, in bytes, or zero if the
jpayne@69 1472 * stack size is unlimited.
jpayne@69 1473 * @stable ICU 4.0
jpayne@69 1474 */
jpayne@69 1475 U_STABLE int32_t U_EXPORT2
jpayne@69 1476 uregex_getStackLimit(const URegularExpression *regexp,
jpayne@69 1477 UErrorCode *status);
jpayne@69 1478
jpayne@69 1479
jpayne@69 1480 /**
jpayne@69 1481 * Function pointer for a regular expression matching callback function.
jpayne@69 1482 * When set, a callback function will be called periodically during matching
jpayne@69 1483 * operations. If the call back function returns FALSE, the matching
jpayne@69 1484 * operation will be terminated early.
jpayne@69 1485 *
jpayne@69 1486 * Note: the callback function must not call other functions on this
jpayne@69 1487 * URegularExpression.
jpayne@69 1488 *
jpayne@69 1489 * @param context context pointer. The callback function will be invoked
jpayne@69 1490 * with the context specified at the time that
jpayne@69 1491 * uregex_setMatchCallback() is called.
jpayne@69 1492 * @param steps the accumulated processing time, in match steps,
jpayne@69 1493 * for this matching operation.
jpayne@69 1494 * @return TRUE to continue the matching operation.
jpayne@69 1495 * FALSE to terminate the matching operation.
jpayne@69 1496 * @stable ICU 4.0
jpayne@69 1497 */
jpayne@69 1498 U_CDECL_BEGIN
jpayne@69 1499 typedef UBool U_CALLCONV URegexMatchCallback (
jpayne@69 1500 const void *context,
jpayne@69 1501 int32_t steps);
jpayne@69 1502 U_CDECL_END
jpayne@69 1503
jpayne@69 1504 /**
jpayne@69 1505 * Set a callback function for this URegularExpression.
jpayne@69 1506 * During matching operations the function will be called periodically,
jpayne@69 1507 * giving the application the opportunity to terminate a long-running
jpayne@69 1508 * match.
jpayne@69 1509 *
jpayne@69 1510 * @param regexp The compiled regular expression.
jpayne@69 1511 * @param callback A pointer to the user-supplied callback function.
jpayne@69 1512 * @param context User context pointer. The value supplied at the
jpayne@69 1513 * time the callback function is set will be saved
jpayne@69 1514 * and passed to the callback each time that it is called.
jpayne@69 1515 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1516 * @stable ICU 4.0
jpayne@69 1517 */
jpayne@69 1518 U_STABLE void U_EXPORT2
jpayne@69 1519 uregex_setMatchCallback(URegularExpression *regexp,
jpayne@69 1520 URegexMatchCallback *callback,
jpayne@69 1521 const void *context,
jpayne@69 1522 UErrorCode *status);
jpayne@69 1523
jpayne@69 1524
jpayne@69 1525 /**
jpayne@69 1526 * Get the callback function for this URegularExpression.
jpayne@69 1527 *
jpayne@69 1528 * @param regexp The compiled regular expression.
jpayne@69 1529 * @param callback Out parameter, receives a pointer to the user-supplied
jpayne@69 1530 * callback function.
jpayne@69 1531 * @param context Out parameter, receives the user context pointer that
jpayne@69 1532 * was set when uregex_setMatchCallback() was called.
jpayne@69 1533 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1534 * @stable ICU 4.0
jpayne@69 1535 */
jpayne@69 1536 U_STABLE void U_EXPORT2
jpayne@69 1537 uregex_getMatchCallback(const URegularExpression *regexp,
jpayne@69 1538 URegexMatchCallback **callback,
jpayne@69 1539 const void **context,
jpayne@69 1540 UErrorCode *status);
jpayne@69 1541
jpayne@69 1542 /**
jpayne@69 1543 * Function pointer for a regular expression find callback function.
jpayne@69 1544 *
jpayne@69 1545 * When set, a callback function will be called during a find operation
jpayne@69 1546 * and for operations that depend on find, such as findNext, split and some replace
jpayne@69 1547 * operations like replaceFirst.
jpayne@69 1548 * The callback will usually be called after each attempt at a match, but this is not a
jpayne@69 1549 * guarantee that the callback will be invoked at each character. For finds where the
jpayne@69 1550 * match engine is invoked at each character, this may be close to true, but less likely
jpayne@69 1551 * for more optimized loops where the pattern is known to only start, and the match
jpayne@69 1552 * engine invoked, at certain characters.
jpayne@69 1553 * When invoked, this callback will specify the index at which a match operation is about
jpayne@69 1554 * to be attempted, giving the application the opportunity to terminate a long-running
jpayne@69 1555 * find operation.
jpayne@69 1556 *
jpayne@69 1557 * If the call back function returns FALSE, the find operation will be terminated early.
jpayne@69 1558 *
jpayne@69 1559 * Note: the callback function must not call other functions on this
jpayne@69 1560 * URegularExpression
jpayne@69 1561 *
jpayne@69 1562 * @param context context pointer. The callback function will be invoked
jpayne@69 1563 * with the context specified at the time that
jpayne@69 1564 * uregex_setFindProgressCallback() is called.
jpayne@69 1565 * @param matchIndex the next index at which a match attempt will be attempted for this
jpayne@69 1566 * find operation. If this callback interrupts the search, this is the
jpayne@69 1567 * index at which a find/findNext operation may be re-initiated.
jpayne@69 1568 * @return TRUE to continue the matching operation.
jpayne@69 1569 * FALSE to terminate the matching operation.
jpayne@69 1570 * @stable ICU 4.6
jpayne@69 1571 */
jpayne@69 1572 U_CDECL_BEGIN
jpayne@69 1573 typedef UBool U_CALLCONV URegexFindProgressCallback (
jpayne@69 1574 const void *context,
jpayne@69 1575 int64_t matchIndex);
jpayne@69 1576 U_CDECL_END
jpayne@69 1577
jpayne@69 1578
jpayne@69 1579 /**
jpayne@69 1580 * Set the find progress callback function for this URegularExpression.
jpayne@69 1581 *
jpayne@69 1582 * @param regexp The compiled regular expression.
jpayne@69 1583 * @param callback A pointer to the user-supplied callback function.
jpayne@69 1584 * @param context User context pointer. The value supplied at the
jpayne@69 1585 * time the callback function is set will be saved
jpayne@69 1586 * and passed to the callback each time that it is called.
jpayne@69 1587 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1588 * @stable ICU 4.6
jpayne@69 1589 */
jpayne@69 1590 U_STABLE void U_EXPORT2
jpayne@69 1591 uregex_setFindProgressCallback(URegularExpression *regexp,
jpayne@69 1592 URegexFindProgressCallback *callback,
jpayne@69 1593 const void *context,
jpayne@69 1594 UErrorCode *status);
jpayne@69 1595
jpayne@69 1596 /**
jpayne@69 1597 * Get the find progress callback function for this URegularExpression.
jpayne@69 1598 *
jpayne@69 1599 * @param regexp The compiled regular expression.
jpayne@69 1600 * @param callback Out parameter, receives a pointer to the user-supplied
jpayne@69 1601 * callback function.
jpayne@69 1602 * @param context Out parameter, receives the user context pointer that
jpayne@69 1603 * was set when uregex_setFindProgressCallback() was called.
jpayne@69 1604 * @param status A reference to a UErrorCode to receive any errors.
jpayne@69 1605 * @stable ICU 4.6
jpayne@69 1606 */
jpayne@69 1607 U_STABLE void U_EXPORT2
jpayne@69 1608 uregex_getFindProgressCallback(const URegularExpression *regexp,
jpayne@69 1609 URegexFindProgressCallback **callback,
jpayne@69 1610 const void **context,
jpayne@69 1611 UErrorCode *status);
jpayne@69 1612
jpayne@69 1613 #endif /* !UCONFIG_NO_REGULAR_EXPRESSIONS */
jpayne@69 1614 #endif /* UREGEX_H */