From 039d648a121af78096011e75814d5badb80a5783 Mon Sep 17 00:00:00 2001 From: Mehdi Achour Date: Fri, 2 Feb 2007 22:11:46 +0000 Subject: [PATCH] ref.pcre: switch to new doc style # And fix #40215 git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@228785 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/pcre/functions/preg-grep.xml | 98 +++++-- reference/pcre/functions/preg-last-error.xml | 3 +- reference/pcre/functions/preg-match-all.xml | 247 ++++++++++++------ reference/pcre/functions/preg-match.xml | 228 +++++++++++----- reference/pcre/functions/preg-quote.xml | 59 ++++- .../pcre/functions/preg-replace-callback.xml | 236 ++++++++++++----- reference/pcre/functions/preg-replace.xml | 15 +- reference/pcre/functions/preg-split.xml | 211 ++++++++++----- 8 files changed, 773 insertions(+), 324 deletions(-) diff --git a/reference/pcre/functions/preg-grep.xml b/reference/pcre/functions/preg-grep.xml index f8b51a0825..eaaaf4f43b 100644 --- a/reference/pcre/functions/preg-grep.xml +++ b/reference/pcre/functions/preg-grep.xml @@ -1,49 +1,108 @@ - + preg_grep Return array entries that match the pattern - - Description + + + &reftitle.description; arraypreg_grep stringpattern arrayinput intflags - - preg_grep returns the array consisting of - the elements of the input array that match - the given pattern. + Returns the array consisting of the elements of the + input array that match the given + pattern. + + + &reftitle.parameters; - flags can be the following flag: - PREG_GREP_INVERT + pattern - - If this flag is passed, preg_grep returns the - elements of the input array that do not match + + The pattern to search for, as a string. + + + + + input + + + The input array. + + + + + flags + + + If set to PREG_GREP_INVERT, this function returns + the elements of the input array that do not match the given pattern. - This flag is available since PHP 4.2.0. - + + + + &reftitle.returnvalues; - Since PHP 4.0.4, the results returned by preg_grep - are indexed using the keys from the input array. If this behavior is - undesirable, use array_values on the array returned by - preg_grep to reindex the values. + Returns an array indexed using the keys from the + input array. - + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 4.2.0 + + The flags parameter was added. + + + + 4.0.4 + + + Prior to this version, the returned array was indexed regardless of + the keys of the input array. + + + If you want to reproduce this old behavior, use + array_values on the returned array to reindex + the values. + + + + + + + + + + + &reftitle.examples; <function>preg_grep</function> example @@ -59,6 +118,7 @@ $fl_array = preg_grep("/^(\d+)?\.\d+$/", $array); + + preg_last_error @@ -33,6 +33,7 @@ + + preg_match_all Perform a global regular expression match - - Description + + + &reftitle.description; intpreg_match_all stringpattern @@ -25,23 +26,59 @@ After the first match is found, the subsequent searches are continued on from end of the last match. + + + + &reftitle.parameters; - flags can be a combination of the following flags - (note that it doesn't make sense to use - PREG_PATTERN_ORDER together with - PREG_SET_ORDER): - PREG_PATTERN_ORDER + pattern - Orders results so that $matches[0] is an array of full - pattern matches, $matches[1] is an array of strings matched by - the first parenthesized subpattern, and so on. + The pattern to search for, as a string. + + + + subject + - - + The input string. + + + + + matches + + + In this case, $matches[0] is the first set of matches, and + $matches[0][0] has text matched by full pattern, + $matches[0][1] has text matched by first + subpattern and so on. Similarly, $matches[1] is + the second set of matches, etc. + + + + + flags + + + Can be a combination of the following flags (note that it doesn't make + sense to use PREG_PATTERN_ORDER together with + PREG_SET_ORDER): + + + PREG_PATTERN_ORDER + + + Orders results so that $matches[0] is an array of full + pattern matches, $matches[1] is an array of strings matched by + the first parenthesized subpattern, and so on. + + + + ]+>(.*)]+>|U", @@ -51,33 +88,31 @@ echo $out[0][0] . ", " . $out[0][1] . "\n"; echo $out[1][0] . ", " . $out[1][1] . "\n"; ?> ]]> - - - This example will produce: - - + + &example.outputs; + example: ,
this is a test
example: , this is a test ]]> - - - So, $out[0] contains array of strings that matched full pattern, - and $out[1] contains array of strings enclosed by tags. - - - - - - - PREG_SET_ORDER - - - Orders results so that $matches[0] is an array of first set - of matches, $matches[1] is an array of second set of matches, - and so on. - - + + + So, $out[0] contains array of strings that matched full pattern, + and $out[1] contains array of strings enclosed by tags. + + + + + + + PREG_SET_ORDER + + + Orders results so that $matches[0] is an array of first set + of matches, $matches[1] is an array of second set of matches, + and so on. + + ]+>(.*)]+>|U", @@ -87,71 +122,104 @@ echo $out[0][0] . ", " . $out[0][1] . "\n"; echo $out[1][0] . ", " . $out[1][1] . "\n"; ?> ]]> - - - This example will produce: - - + + &example.outputs; + example: , example:
this is a test
, this is a test ]]> - - + + + + + + + PREG_OFFSET_CAPTURE + + + If this flag is passed, for every occurring match the appendant string + offset will also be returned. Note that this changes the value of + matches in an array where every element is an + array consisting of the matched string at offset 0 + and its string offset into subject at offset + 1. + + + + - In this case, $matches[0] is the first set of matches, and - $matches[0][0] has text matched by full pattern, $matches[0][1] - has text matched by first subpattern and so on. Similarly, - $matches[1] is the second set of matches, etc. + If no order flag is given, PREG_PATTERN_ORDER is + assumed. - PREG_OFFSET_CAPTURE + offset - If this flag is passed, for every occurring match the appendant string - offset will also be returned. Note that this changes the value of - matches in an array where every element is an - array consisting of the matched string at offset 0 - and its string offset into subject at offset - 1. - This flag is available since PHP 4.3.0 . + Normally, the search starts from the beginning of the subject string. + The optional parameter offset can be used to + specify the alternate place from which to start the search. + + + Using offset is not equivalent to passing + substr($subject, $offset) to + preg_match_all in place of the subject string, + because pattern can contain assertions such as + ^, $ or + (?<=x). See preg_match + for examples. + + - - If no order flag is given, PREG_PATTERN_ORDER is - assumed. - - - - Normally, the search starts from the beginning of the subject string. The - optional parameter offset can be used to specify - the alternate place from which to start the search. - The offset parameter is available since - PHP 4.3.3. - - - - - Using offset is not equivalent to - passing substr($subject, $offset) to - preg_match_all in place of the subject string, because - pattern can contain assertions such as - ^, $ or - (?<=x). See preg_match for - examples. - - + + + &reftitle.returnvalues; Returns the number of full pattern matches (which might be zero), or &false; if an error occurred. + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 4.3.3 + + The offset parameter was added + + + + 4.3.0 + + The PREG_OFFSET_CAPTURE flag was added + + + + + + + + + + &reftitle.examples; Getting all phone numbers out of some text. @@ -188,9 +256,7 @@ foreach ($matches as $val) { ?> ]]> - - This example will produce: - + &example.outputs; bold text @@ -206,12 +272,19 @@ part 3: - - See also preg_match, - preg_replace, - and preg_split. - + + + &reftitle.seealso; + + + preg_match + preg_replace + preg_split + + + + + preg_match Perform a regular expression match - - Description + + + &reftitle.description; intpreg_match stringpattern @@ -19,52 +20,80 @@ Searches subject for a match to the regular expression given in pattern. + + + + &reftitle.parameters; - If matches is provided, then it is filled with the - results of search. $matches[0] will contain the text - that matched the full pattern, $matches[1] will have - the text that matched the first captured parenthesized subpattern, and so - on. - - - flags can be the following flag: - PREG_OFFSET_CAPTURE + pattern - - If this flag is passed, for every occurring match the appendant string - offset will also be returned. Note that this changes the return value - in an array where every element is an array consisting of the matched - string at offset 0 and its string offset into - subject at offset 1. This - flag is available since PHP 4.3.0 . - + + The pattern to search for, as a string. + - - The flags parameter is available since - PHP 4.3.0. - - - - Normally, the search starts from the beginning of the subject string. The - optional parameter offset can be used to specify - the alternate place from which to start the search. - The offset parameter is available since - PHP 4.3.3. - - - - Using offset is not equivalent to - passing substr($subject, $offset) to - preg_match in place of the subject string, because - pattern can contain assertions such as - ^, $ or - (?<=x). Compare: - - - + + subject + + + The input string. + + + + + matches + + + If matches is provided, then it is filled with + the results of search. $matches[0] will contain the + text that matched the full pattern, $matches[1] + will have the text that matched the first captured parenthesized + subpattern, and so on. + + + + + flags + + + flags can be the following flag: + + + PREG_OFFSET_CAPTURE + + + If this flag is passed, for every occurring match the appendant string + offset will also be returned. Note that this changes the return value + in an array where every element is an array consisting of the matched + string at offset 0 and its string offset into + subject at offset 1. + + + + + + + + + offset + + + Normally, the search starts from the beginning of the subject string. + The optional parameter offset can be used to + specify the alternate place from which to start the search. + + + + Using offset is not equivalent to passing + substr($subject, $offset) to + preg_match_all in place of the subject string, + because pattern can contain assertions such as + ^, $ or + (?<=x). Compare: + + ]]> - - &example.outputs; - + + &example.outputs; + - - - while this example - - + + + while this example + + ]]> - - - will produce - - + + + will produce + + - - - + + + + + + + + + + + &reftitle.returnvalues; preg_match returns the number of times pattern matches. That will be either 0 times @@ -123,14 +160,46 @@ Array subject. preg_match returns &false; if an error occurred. - - - Do not use preg_match if you only want to check if - one string is contained in another string. Use - strpos or strstr instead as - they will be faster. - - + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 4.3.3 + + The offset parameter was added + + + + 4.3.0 + + The PREG_OFFSET_CAPTURE flag was added + + + + 4.3.0 + + The flags parameter was added + + + + + + + + + + &reftitle.examples; Find the string of text "php" @@ -197,12 +266,31 @@ domain name is: php.net + + + + &reftitle.notes; + + + Do not use preg_match if you only want to check if + one string is contained in another string. Use + strpos or strstr instead as + they will be faster. + + + + + + &reftitle.seealso; - See also preg_match_all, - preg_replace, and - preg_split. + + preg_match_all + preg_replace + preg_split + + + preg_quote Quote regular expression characters - - Description + + + &reftitle.description; stringpreg_quote stringstr @@ -19,15 +20,48 @@ run-time string that you need to match in some text and the string may contain special regex characters. - - If the optional delimiter is specified, it - will also be escaped. This is useful for escaping the delimiter - that is required by the PCRE functions. The / is the most commonly - used delimiter. The special regular expression characters are: . \ + * ? [ ^ ] $ ( ) { } = ! < > | : + + + + &reftitle.parameters; + + + + str + + + The input string. + + + + + delimiter + + + If the optional delimiter is specified, it + will also be escaped. This is useful for escaping the delimiter + that is required by the PCRE functions. The / is the most commonly + used delimiter. + + + + + + + + + &reftitle.returnvalues; + + Returns the quoted string. + + + + + &reftitle.examples; <function>preg_quote</function> example @@ -62,10 +96,13 @@ $textbody = preg_replace ("/" . preg_quote($word) . "/", - - ¬e.bin-safe; - + + + &reftitle.notes; + ¬e.bin-safe; + + + preg_replace_callback Perform a regular expression search and replace using a callback - - Description + + + &reftitle.description; mixedpreg_replace_callback mixedpattern @@ -19,52 +20,46 @@ The behavior of this function is almost identical to preg_replace, except for the fact that instead of replacement parameter, one should specify a - callback that will be called and passed an array of - matched elements in the subject string. The callback should return the - replacement string. - See preg_replace for description of other parameters. + callback. - - <function>preg_replace_callback</function> example - - -]]> - - + + + + &reftitle.parameters; - You'll often need the callback function - for a preg_replace_callback in just one place. - In this case you can use create_function to - declare an anonymous function as callback within the call to - preg_replace_callback. By doing it this way - you have all information for the call in one place and do not - clutter the function namespace with a callback functions name - not used anywhere else. - - - <function>preg_replace_callback</function> and <function>create_function</function> - + + + pattern + + + The pattern to search for. It can be either a string or an array with + strings. + + + + + callback + + + A callback that will be called and passed an array of matched elements + in the subject string. The callback should + return the replacement string. + + + You'll often need the callback function + for a preg_replace_callback in just one place. + In this case you can use create_function to + declare an anonymous function as callback within the call to + preg_replace_callback. By doing it this way + you have all information for the call in one place and do not + clutter the function namespace with a callback function's name + not used anywhere else. + + + + <function>preg_replace_callback</function> and + <function>create_function</function> + ]]> - - - - <function>preg_replace_callback</function> using recursive structure - to handle encapsulated BB code - + + + + + + + subject + + + The string or an array with strings to search and replace. + + + + + limit + + + The maximum possible replacements for each pattern in each + subject string. Defaults to + -1 (no limit). + + + + + count + + + If specified, this variable will be filled with the number of + replacements done. + + + + + + + + + &reftitle.returnvalues; + + preg_replace returns an array if the + subject parameter is an array, or a string + otherwise. + + + If matches are found, the new subject will + be returned, otherwise subject will be + returned unchanged. + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 5.1.0 + + The count parameter was added + + + + + + + + + + &reftitle.examples; + + + <function>preg_replace_callback</function> example + + +]]> + + &example.outputs; + + + + + + + + <function>preg_replace_callback</function> using recursive structure + to handle encapsulated BB code + ]]> - - - - - count parameter is available since PHP 5.1.0. - - - - See also preg_replace, - create_function, - &listendand; &seealso.callback;. + + + + + &reftitle.seealso; + + + preg_replace + create_function + &seealso.callback; + + + + + preg_replace Perform a regular expression search and replace + &reftitle.description; @@ -57,9 +58,9 @@ otherwise PHP will complain about a parse error at the line containing preg_replace. - + - + &reftitle.parameters; @@ -146,9 +147,9 @@ - 4.0.1 + 5.1.0 - Added the limit parameter + Added the count parameter @@ -158,9 +159,9 @@ - 5.1.0 + 4.0.1 - Added the count parameter + Added the limit parameter diff --git a/reference/pcre/functions/preg-split.xml b/reference/pcre/functions/preg-split.xml index bf8d42d69b..ed7db3c219 100644 --- a/reference/pcre/functions/preg-split.xml +++ b/reference/pcre/functions/preg-split.xml @@ -1,12 +1,13 @@ - + preg_split Split string by a regular expression - - Description + + + &reftitle.description; arraypreg_split stringpattern @@ -14,67 +15,134 @@ intlimit intflags - - Returns an array containing substrings of - subject split along boundaries matched by - pattern. + Split the given string by a regular expression. + + + &reftitle.parameters; - If limit is specified, then only substrings up to - limit are returned, and if - limit is -1, it actually means "no limit", which is - useful for specifying the flags. + + + pattern + + + The pattern to search for, as a string. + + + + + subject + + + The input string. + + + + + limit + + + If specified, then only substrings up to limit + are returned, and if limit is -1, it actually + means "no limit", which is useful for specifying the + flags. + + + + + flags + + + flags can be any combination of the following + flags (combined with bitwise | operator): + + + PREG_SPLIT_NO_EMPTY + + + If this flag is set, only non-empty pieces will be returned by + preg_split. + + + + + PREG_SPLIT_DELIM_CAPTURE + + + If this flag is set, parenthesized expression in the delimiter pattern + will be captured and returned as well. + + + + + PREG_SPLIT_OFFSET_CAPTURE + + + If this flag is set, for every occurring match the appendant string + offset will also be returned. Note that this changes the return + value in an array where every element is an array consisting of the + matched string at offset 0 and its string offset + into subject at offset 1. + + + + + + + + + + + &reftitle.returnvalues; - flags can be any combination of the following flags - (combined with bitwise | operator): - - - PREG_SPLIT_NO_EMPTY - - - If this flag is set, only non-empty pieces will be returned by - preg_split. - - - - - PREG_SPLIT_DELIM_CAPTURE - - - If this flag is set, parenthesized expression in the delimiter pattern - will be captured and returned as well. This flag was added for 4.0.5. - - - - - PREG_SPLIT_OFFSET_CAPTURE - - - If this flag is set, for every occurring match the appendant string - offset will also be returned. Note that this changes the return - value in an array where every element is an array consisting of the - matched string at offset 0 and its string offset - into subject at offset 1. - This flag is available since PHP 4.3.0 . - - - - - + Returns an array containing substrings of subject + split along boundaries matched by pattern. + + - - - If you don't need the power of regular expressions, you can choose - faster (albeit simpler) alternatives like explode - or str_split. - - + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 4.3.0 + + The PREG_SPLIT_OFFSET_CAPTURE was added + + + + 4.0.5 + + The PREG_SPLIT_DELIM_CAPTURE was added + + + + 4 Beta 3 + + The flags parameter was added + + + + + + + - + + &reftitle.examples; + <function>preg_split</function> example : Get the parts of a search string @@ -114,9 +182,7 @@ print_r($chars); ?> ]]> - - will yield: - + &example.outputs; - + + + + &reftitle.notes; + - Parameter flags was added in PHP 4 Beta 3. + If you don't need the power of regular expressions, you can choose + faster (albeit simpler) alternatives like explode + or str_split. - + + + + + &reftitle.seealso; - See also spliti, split, - implode, preg_match, - preg_match_all, and - preg_replace. + + spliti + split + implode + preg_match + preg_match_all + preg_replace + +