X-Git-Url: https://git.saurik.com/apple/icu.git/blobdiff_plain/4388f060552cc537e71e957d32f35e9d75a61233..f3c0d7a59d99c2a94c6b8822291f0e42be3773c9:/icuSources/i18n/unicode/uregex.h diff --git a/icuSources/i18n/unicode/uregex.h b/icuSources/i18n/unicode/uregex.h index 1a9209e3..7aac256b 100644 --- a/icuSources/i18n/unicode/uregex.h +++ b/icuSources/i18n/unicode/uregex.h @@ -1,10 +1,12 @@ +// © 2016 and later: Unicode, Inc. and others. +// License & terms of use: http://www.unicode.org/copyright.html /* ********************************************************************** -* Copyright (C) 2004-2012, International Business Machines +* Copyright (C) 2004-2016, International Business Machines * Corporation and others. All Rights Reserved. ********************************************************************** * file name: uregex.h -* encoding: US-ASCII +* encoding: UTF-8 * indentation:4 * * created on: 2004mar09 @@ -51,7 +53,7 @@ typedef enum URegexpFlag{ Not implemented yet, just a placeholder, hence draft. @draft ICU 2.4 */ UREGEX_CANON_EQ = 128, -#endif +#endif /* U_HIDE_DRAFT_API */ /** Enable case insensitive matching. @stable ICU 2.4 */ UREGEX_CASE_INSENSITIVE = 2, @@ -159,7 +161,7 @@ uregex_open( const UChar *pattern, * * @stable ICU 4.6 */ -U_DRAFT URegularExpression * U_EXPORT2 +U_STABLE URegularExpression * U_EXPORT2 uregex_openUText(UText *pattern, uint32_t flags, UParseError *pe, @@ -225,7 +227,7 @@ U_DEFINE_LOCAL_OPEN_POINTER(LocalURegularExpressionPointer, URegularExpression, U_NAMESPACE_END -#endif +#endif // U_SHOW_CPLUSPLUS_API /** * Make a copy of a compiled regular expression. Cloning a regular @@ -281,7 +283,7 @@ uregex_pattern(const URegularExpression *regexp, * * @stable ICU 4.6 */ -U_DRAFT UText * U_EXPORT2 +U_STABLE UText * U_EXPORT2 uregex_patternUText(const URegularExpression *regexp, UErrorCode *status); @@ -341,7 +343,7 @@ uregex_setText(URegularExpression *regexp, * * @stable ICU 4.6 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 uregex_setUText(URegularExpression *regexp, UText *text, UErrorCode *status); @@ -387,7 +389,7 @@ uregex_getText(URegularExpression *regexp, * * @stable ICU 4.6 */ -U_DRAFT UText * U_EXPORT2 +U_STABLE UText * U_EXPORT2 uregex_getUText(URegularExpression *regexp, UText *dest, UErrorCode *status); @@ -415,9 +417,9 @@ uregex_getUText(URegularExpression *regexp, * @param text The new (moved) text string. * @param status Receives errors detected by this function. * - * @stable ICU 4.8 + * @stable ICU 4.8 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 uregex_refreshUText(URegularExpression *regexp, UText *text, UErrorCode *status); @@ -468,7 +470,7 @@ uregex_matches(URegularExpression *regexp, * @return TRUE if there is a match * @stable ICU 4.6 */ -U_DRAFT UBool U_EXPORT2 +U_STABLE UBool U_EXPORT2 uregex_matches64(URegularExpression *regexp, int64_t startIndex, UErrorCode *status); @@ -487,7 +489,7 @@ uregex_matches64(URegularExpression *regexp, * *

If the match succeeds then more information can be obtained via the * uregexp_start(), uregexp_end(), - * and uregexp_group() functions.

+ * and uregex_group() functions.

* * @param regexp The compiled regular expression. * @param startIndex The input string (native) index at which to begin matching, or @@ -516,7 +518,7 @@ uregex_lookingAt(URegularExpression *regexp, * *

If the match succeeds then more information can be obtained via the * uregexp_start(), uregexp_end(), - * and uregexp_group() functions.

+ * and uregex_group() functions.

* * @param regexp The compiled regular expression. * @param startIndex The input string (native) index at which to begin matching, or @@ -525,7 +527,7 @@ uregex_lookingAt(URegularExpression *regexp, * @return TRUE if there is a match. * @stable ICU 4.6 */ -U_DRAFT UBool U_EXPORT2 +U_STABLE UBool U_EXPORT2 uregex_lookingAt64(URegularExpression *regexp, int64_t startIndex, UErrorCode *status); @@ -574,7 +576,7 @@ uregex_find(URegularExpression *regexp, * @return TRUE if a match is found. * @stable ICU 4.6 */ -U_DRAFT UBool U_EXPORT2 +U_STABLE UBool U_EXPORT2 uregex_find64(URegularExpression *regexp, int64_t startIndex, UErrorCode *status); @@ -607,6 +609,52 @@ U_STABLE int32_t U_EXPORT2 uregex_groupCount(URegularExpression *regexp, UErrorCode *status); +/** + * Get the group number corresponding to a named capture group. + * The returned number can be used with any function that access + * capture groups by number. + * + * The function returns an error status if the specified name does not + * appear in the pattern. + * + * @param regexp The compiled regular expression. + * @param groupName The capture group name. + * @param nameLength The length of the name, or -1 if the name is a + * nul-terminated string. + * @param status A pointer to a UErrorCode to receive any errors. + * + * @stable ICU 55 + */ +U_STABLE int32_t U_EXPORT2 +uregex_groupNumberFromName(URegularExpression *regexp, + const UChar *groupName, + int32_t nameLength, + UErrorCode *status); + + +/** + * Get the group number corresponding to a named capture group. + * The returned number can be used with any function that access + * capture groups by number. + * + * The function returns an error status if the specified name does not + * appear in the pattern. + * + * @param regexp The compiled regular expression. + * @param groupName The capture group name, + * platform invariant characters only. + * @param nameLength The length of the name, or -1 if the name is + * nul-terminated. + * @param status A pointer to a UErrorCode to receive any errors. + * + * @stable ICU 55 + */ +U_STABLE int32_t U_EXPORT2 +uregex_groupNumberFromCName(URegularExpression *regexp, + const char *groupName, + int32_t nameLength, + UErrorCode *status); + /** Extract the string for the specified matching expression or subexpression. * Group #0 is the complete string of matched text. * Group #1 is the text matched by the first set of capturing parentheses. @@ -630,8 +678,8 @@ uregex_group(URegularExpression *regexp, int32_t destCapacity, UErrorCode *status); -/** Returns a shallow immutable clone of the entire input string. The returned UText current native index - * is set to the beginning of the requested capture group. The capture group length is also +/** Returns a shallow immutable clone of the entire input string with the current index set + * to the beginning of the requested capture group. The capture group length is also * returned via groupLength. * Group #0 is the complete string of matched text. * Group #1 is the text matched by the first set of capturing parentheses. @@ -644,7 +692,7 @@ uregex_group(URegularExpression *regexp, * @param dest A mutable UText in which to store the current input. * If NULL, a new UText will be created as an immutable shallow clone * of the entire input string. - * @param groupLength The group length of the desired capture group. + * @param groupLength The group length of the desired capture group. Output parameter. * @param status A reference to a UErrorCode to receive any errors. * @return The subject text currently associated with this regular expression. * If a pre-allocated UText was provided, it will always be used and returned. @@ -652,38 +700,13 @@ uregex_group(URegularExpression *regexp, * * @stable ICU 4.6 */ -U_DRAFT UText * U_EXPORT2 +U_STABLE UText * U_EXPORT2 uregex_groupUText(URegularExpression *regexp, int32_t groupNum, UText *dest, int64_t *groupLength, UErrorCode *status); -#ifndef U_HIDE_INTERNAL_API -/** Extract the string for the specified matching expression or subexpression. - * Group #0 is the complete string of matched text. - * Group #1 is the text matched by the first set of capturing parentheses. - * - * @param regexp The compiled regular expression. - * @param groupNum The capture group to extract. Group 0 is the complete - * match. The value of this parameter must be - * less than or equal to the number of capture groups in - * the pattern. - * @param dest Mutable UText to receive the matching string data. - * If NULL, a new UText will be created (which may not be mutable). - * @param status A reference to a UErrorCode to receive any errors. - * @return The matching string data. If a pre-allocated UText was provided, - * it will always be used and returned. - * - * @internal ICU 4.4 technology preview - */ -U_INTERNAL UText * U_EXPORT2 -uregex_groupUTextDeep(URegularExpression *regexp, - int32_t groupNum, - UText *dest, - UErrorCode *status); -#endif /* U_HIDE_INTERNAL_API */ - /** * Returns the index in the input string of the start of the text matched by the * specified capture group during the previous match operation. Return -1 if @@ -718,7 +741,7 @@ uregex_start(URegularExpression *regexp, * by the specified group. * @stable ICU 4.6 */ -U_DRAFT int64_t U_EXPORT2 +U_STABLE int64_t U_EXPORT2 uregex_start64(URegularExpression *regexp, int32_t groupNum, UErrorCode *status); @@ -755,7 +778,7 @@ uregex_end(URegularExpression *regexp, * @return the (native) index of the position following the last matched character. * @stable ICU 4.6 */ -U_DRAFT int64_t U_EXPORT2 +U_STABLE int64_t U_EXPORT2 uregex_end64(URegularExpression *regexp, int32_t groupNum, UErrorCode *status); @@ -792,7 +815,7 @@ uregex_reset(URegularExpression *regexp, * @param status A reference to a UErrorCode to receive any errors. * @stable ICU 4.6 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 uregex_reset64(URegularExpression *regexp, int64_t index, UErrorCode *status); @@ -844,7 +867,7 @@ uregex_setRegion(URegularExpression *regexp, * @param status A pointer to a UErrorCode to receive any errors. * @stable ICU 4.6 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 uregex_setRegion64(URegularExpression *regexp, int64_t regionStart, int64_t regionLimit, @@ -864,7 +887,7 @@ uregex_setRegion64(URegularExpression *regexp, * @param status A pointer to a UErrorCode to receive any errors. * @stable ICU 4.6 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 uregex_setRegionAndStart(URegularExpression *regexp, int64_t regionStart, int64_t regionLimit, @@ -894,7 +917,7 @@ uregex_regionStart(const URegularExpression *regexp, * @return The starting (native) index of this matcher's region. * @stable ICU 4.6 */ -U_DRAFT int64_t U_EXPORT2 +U_STABLE int64_t U_EXPORT2 uregex_regionStart64(const URegularExpression *regexp, UErrorCode *status); @@ -923,7 +946,7 @@ uregex_regionEnd(const URegularExpression *regexp, * @return The ending point (native) of this matcher's region. * @stable ICU 4.6 */ -U_DRAFT int64_t U_EXPORT2 +U_STABLE int64_t U_EXPORT2 uregex_regionEnd64(const URegularExpression *regexp, UErrorCode *status); @@ -1085,7 +1108,7 @@ uregex_replaceAll(URegularExpression *regexp, * * @stable ICU 4.6 */ -U_DRAFT UText * U_EXPORT2 +U_STABLE UText * U_EXPORT2 uregex_replaceAllUText(URegularExpression *regexp, UText *replacement, UText *dest, @@ -1144,7 +1167,7 @@ uregex_replaceFirst(URegularExpression *regexp, * * @stable ICU 4.6 */ -U_DRAFT UText * U_EXPORT2 +U_STABLE UText * U_EXPORT2 uregex_replaceFirstUText(URegularExpression *regexp, UText *replacement, UText *dest, @@ -1226,7 +1249,7 @@ uregex_appendReplacement(URegularExpression *regexp, * * @stable ICU 4.6 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 uregex_appendReplacementUText(URegularExpression *regexp, UText *replacementText, UText *dest, @@ -1280,7 +1303,7 @@ uregex_appendTail(URegularExpression *regexp, * * @stable ICU 4.6 */ -U_DRAFT UText * U_EXPORT2 +U_STABLE UText * U_EXPORT2 uregex_appendTailUText(URegularExpression *regexp, UText *dest, UErrorCode *status); @@ -1371,7 +1394,7 @@ uregex_split( URegularExpression *regexp, * * @stable ICU 4.6 */ -U_DRAFT int32_t U_EXPORT2 +U_STABLE int32_t U_EXPORT2 uregex_splitUText(URegularExpression *regexp, UText *destFields[], int32_t destFieldsCapacity, @@ -1431,8 +1454,8 @@ uregex_getTimeLimit(const URegularExpression *regexp, *

* @param regexp The compiled regular expression. * @param limit The maximum size, in bytes, of the matching backtrack stack. - * A value of -1 means no limit. - * The limit must be greater than zero, or -1. + * A value of zero means no limit. + * The limit must be greater than or equal to zero. * @param status A reference to a UErrorCode to receive any errors. * * @stable ICU 4.0 @@ -1564,7 +1587,7 @@ U_CDECL_END * @param status A reference to a UErrorCode to receive any errors. * @stable ICU 4.6 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 uregex_setFindProgressCallback(URegularExpression *regexp, URegexFindProgressCallback *callback, const void *context, @@ -1581,7 +1604,7 @@ uregex_setFindProgressCallback(URegularExpression *regexp, * @param status A reference to a UErrorCode to receive any errors. * @stable ICU 4.6 */ -U_DRAFT void U_EXPORT2 +U_STABLE void U_EXPORT2 uregex_getFindProgressCallback(const URegularExpression *regexp, URegexFindProgressCallback **callback, const void **context,