diff options
Diffstat (limited to 'lib/stdlib/doc/src/regexp.xml')
| -rw-r--r-- | lib/stdlib/doc/src/regexp.xml | 152 |
1 files changed, 59 insertions, 93 deletions
diff --git a/lib/stdlib/doc/src/regexp.xml b/lib/stdlib/doc/src/regexp.xml index 8c4191c88f..35d8e1c3f8 100644 --- a/lib/stdlib/doc/src/regexp.xml +++ b/lib/stdlib/doc/src/regexp.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2009</year> + <year>1996</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -40,176 +40,150 @@ <p>This module contains functions for regular expression matching and substitution.</p> </description> + <datatypes> + <datatype> + <name name="errordesc"></name> + </datatype> + <datatype> + <name name="regexp"></name> + <desc><p>Internal representation of a regular expression.</p></desc> + </datatype> + </datatypes> <funcs> <func> - <name>match(String, RegExp) -> MatchRes</name> + <name name="match" arity="2"/> <fsummary>Match a regular expression</fsummary> - <type> - <v>String = RegExp = string()</v> - <v>MatchRes = {match,Start,Length} | nomatch | {error,errordesc()}</v> - <v>Start = Length = integer()</v> - </type> <desc> - <p>Finds the first, longest match of the regular expression <c>RegExp</c> in <c>String</c>. This function searches for the longest possible match and returns the first one found if there are several expressions of the same length. It returns as follows:</p> + <p>Finds the first, longest match of the regular expression <c><anno>RegExp</anno></c> in <c><anno>String</anno></c>. This function searches for the longest possible match and returns the first one found if there are several expressions of the same length. It returns as follows:</p> <taglist> - <tag><c>{match,Start,Length}</c></tag> + <tag><c>{match,<anno>Start</anno>,<anno>Length</anno>}</c></tag> <item> - <p>if the match succeeded. <c>Start</c> is the starting - position of the match, and <c>Length</c> is the length of + <p>if the match succeeded. <c><anno>Start</anno></c> is the starting + position of the match, and <c><anno>Length</anno></c> is the length of the matching string.</p> </item> <tag><c>nomatch</c></tag> <item> <p>if there were no matching characters.</p> </item> - <tag><c>{error,Error}</c></tag> + <tag><c>{error,<anno>Error</anno>}</c></tag> <item> - <p>if there was an error in <c>RegExp</c>.</p> + <p>if there was an error in <c><anno>RegExp</anno></c>.</p> </item> </taglist> </desc> </func> <func> - <name>first_match(String, RegExp) -> MatchRes</name> + <name name="first_match" arity="2"/> <fsummary>Match a regular expression</fsummary> - <type> - <v>String = RegExp = string()</v> - <v>MatchRes = {match,Start,Length} | nomatch | {error,errordesc()}</v> - <v>Start = Length = integer()</v> - </type> <desc> - <p>Finds the first match of the regular expression <c>RegExp</c> in <c>String</c>. This call is + <p>Finds the first match of the regular expression <c><anno>RegExp</anno></c> in <c><anno>String</anno></c>. This call is usually faster than <c>match</c> and it is also a useful way to ascertain that a match exists. It returns as follows:</p> <taglist> - <tag><c>{match,Start,Length}</c></tag> + <tag><c>{match,<anno>Start</anno>,<anno>Length</anno>}</c></tag> <item> - <p>if the match succeeded. <c>Start</c> is the starting - position of the match and <c>Length</c> is the length of + <p>if the match succeeded. <c><anno>Start</anno></c> is the starting + position of the match and <c><anno>Length</anno></c> is the length of the matching string.</p> </item> <tag><c>nomatch</c></tag> <item> <p>if there were no matching characters.</p> </item> - <tag><c>{error,Error}</c></tag> + <tag><c>{error,<anno>Error</anno>}</c></tag> <item> - <p>if there was an error in <c>RegExp</c>.</p> + <p>if there was an error in <c><anno>RegExp</anno></c>.</p> </item> </taglist> </desc> </func> <func> - <name>matches(String, RegExp) -> MatchRes</name> + <name name="matches" arity="2"/> <fsummary>Match a regular expression</fsummary> - <type> - <v>String = RegExp = string()</v> - <v>MatchRes = {match, Matches} | {error, errordesc()}</v> - <v>Matches = list()</v> - </type> <desc> <p>Finds all non-overlapping matches of the - expression <c>RegExp</c> in <c>String</c>. + expression <c><anno>RegExp</anno></c> in <c><anno>String</anno></c>. It returns as follows:</p> <taglist> - <tag><c>{match, Matches}</c></tag> + <tag><c>{match, <anno>Matches</anno>}</c></tag> <item> <p>if the regular expression was correct. - The list will be empty if there was no match. Each element in the list looks like <c>{Start, Length}</c>, where <c>Start</c> is the starting position of the match, and <c>Length</c> is the length of the matching string.</p> + The list will be empty if there was no match. Each element in the list looks like <c>{<anno>Start</anno>, <anno>Length</anno>}</c>, where <c><anno>Start</anno></c> is the starting position of the match, and <c><anno>Length</anno></c> is the length of the matching string.</p> </item> - <tag><c>{error,Error}</c></tag> + <tag><c>{error,<anno>Error</anno>}</c></tag> <item> - <p>if there was an error in <c>RegExp</c>.</p> + <p>if there was an error in <c><anno>RegExp</anno></c>.</p> </item> </taglist> </desc> </func> <func> - <name>sub(String, RegExp, New) -> SubRes</name> + <name name="sub" arity="3"/> <fsummary>Substitute the first occurrence of a regular expression</fsummary> - <type> - <v>String = RegExp = New = string()</v> - <v>SubRes = {ok,NewString,RepCount} | {error,errordesc()}</v> - <v>RepCount = integer()</v> - </type> <desc> - <p>Substitutes the first occurrence of a substring matching <c>RegExp</c> in <c>String</c> with the string <c>New</c>. A <c><![CDATA[&]]></c> in the string <c>New</c> is replaced by the matched substring of <c>String</c>. <c><![CDATA[\&]]></c> puts a literal <c><![CDATA[&]]></c> into the replacement string. It returns as follows:</p> + <p>Substitutes the first occurrence of a substring matching <c><anno>RegExp</anno></c> in <c><anno>String</anno></c> with the string <c><anno>New</anno></c>. A <c><![CDATA[&]]></c> in the string <c><anno>New</anno></c> is replaced by the matched substring of <c><anno>String</anno></c>. <c><![CDATA[\&]]></c> puts a literal <c><![CDATA[&]]></c> into the replacement string. It returns as follows:</p> <taglist> - <tag><c>{ok,NewString,RepCount}</c></tag> + <tag><c>{ok,<anno>NewString</anno>,<anno>RepCount</anno>}</c></tag> <item> - <p>if <c>RegExp</c> is correct. <c>RepCount</c> is the number of replacements which have been made + <p>if <c><anno>RegExp</anno></c> is correct. <c><anno>RepCount</anno></c> is the number of replacements which have been made (this will be either 0 or 1).</p> </item> - <tag><c>{error, Error}</c></tag> + <tag><c>{error, <anno>Error</anno>}</c></tag> <item> - <p>if there is an error in <c>RegExp</c>.</p> + <p>if there is an error in <c><anno>RegExp</anno></c>.</p> </item> </taglist> </desc> </func> <func> - <name>gsub(String, RegExp, New) -> SubRes</name> + <name name="gsub" arity="3"/> <fsummary>Substitute all occurrences of a regular expression</fsummary> - <type> - <v>String = RegExp = New = string()</v> - <v>SubRes = {ok,NewString,RepCount} | {error,errordesc()}</v> - <v>RepCount = integer()</v> - </type> <desc> <p>The same as <c>sub</c>, except that all non-overlapping occurrences of a substring matching - <c>RegExp</c> in <c>String</c> are replaced by the string <c>New</c>. It returns:</p> + <c><anno>RegExp</anno></c> in <c><anno>String</anno></c> are replaced by the string <c><anno>New</anno></c>. It returns:</p> <taglist> - <tag><c>{ok,NewString,RepCount}</c></tag> + <tag><c>{ok,<anno>NewString</anno>,<anno>RepCount</anno>}</c></tag> <item> - <p>if <c>RegExp</c> is correct. <c>RepCount</c> is the number of replacements which have been made.</p> + <p>if <c><anno>RegExp</anno></c> is correct. <c><anno>RepCount</anno></c> is the number of replacements which have been made.</p> </item> - <tag><c>{error, Error}</c></tag> + <tag><c>{error, <anno>Error</anno>}</c></tag> <item> - <p>if there is an error in <c>RegExp</c>.</p> + <p>if there is an error in <c><anno>RegExp</anno></c>.</p> </item> </taglist> </desc> </func> <func> - <name>split(String, RegExp) -> SplitRes</name> + <name name="split" arity="2"/> <fsummary>Split a string into fields</fsummary> - <type> - <v>String = RegExp = string()</v> - <v>SubRes = {ok,FieldList} | {error,errordesc()}</v> - <v>Fieldlist = [string()]</v> - </type> <desc> - <p><c>String</c> is split into fields (sub-strings) by the - regular expression <c>RegExp</c>.</p> + <p><c><anno>String</anno></c> is split into fields (sub-strings) by the + regular expression <c><anno>RegExp</anno></c>.</p> <p>If the separator expression is <c>" "</c> (a single space), then the fields are separated by blanks and/or tabs and leading and trailing blanks and tabs are discarded. For all other values of the separator, leading and trailing blanks and tabs are not discarded. It returns:</p> <taglist> - <tag><c>{ok, FieldList}</c></tag> + <tag><c>{ok, <anno>FieldList</anno>}</c></tag> <item> <p>to indicate that the string has been split up into the fields of - <c>FieldList</c>.</p> + <c><anno>FieldList</anno></c>.</p> </item> - <tag><c>{error, Error}</c></tag> + <tag><c>{error, <anno>Error</anno>}</c></tag> <item> - <p>if there is an error in <c>RegExp</c>.</p> + <p>if there is an error in <c><anno>RegExp</anno></c>.</p> </item> </taglist> </desc> </func> <func> - <name>sh_to_awk(ShRegExp) -> AwkRegExp</name> + <name name="sh_to_awk" arity="1"/> <fsummary>Convert an <c>sh</c>regular expression into an <c>AWK</c>one</fsummary> - <type> - <v>ShRegExp AwkRegExp = string()</v> - <v>SubRes = {ok,NewString,RepCount} | {error,errordesc()}</v> - <v>RepCount = integer()</v> - </type> <desc> <p>Converts the <c>sh</c> type regular expression - <c>ShRegExp</c> into a full <c>AWK</c> regular + <c><anno>ShRegExp</anno></c> into a full <c>AWK</c> regular expression. Returns the converted regular expression string. <c>sh</c> expressions are used in the shell for matching file names and have the following special @@ -236,40 +210,32 @@ </desc> </func> <func> - <name>parse(RegExp) -> ParseRes</name> + <name name="parse" arity="1"/> <fsummary>Parse a regular expression</fsummary> - <type> - <v>RegExp = string()</v> - <v>ParseRes = {ok,RE} | {error,errordesc()}</v> - </type> <desc> - <p>Parses the regular expression <c>RegExp</c> and builds the + <p>Parses the regular expression <c><anno>RegExp</anno></c> and builds the internal representation used in the other regular expression functions. Such representations can be used in all of the other functions instead of a regular expression string. This is more efficient when the same regular expression is used in many strings. It returns:</p> <taglist> - <tag><c>{ok, RE}</c>if <c>RegExp</c>is correct and <c>RE</c>is the internal representation.</tag> + <tag><c>{ok, <anno>RE</anno>}</c></tag> <item> - <p></p> + <p>if <c>RegExp</c> is correct and <c><anno>RE</anno></c> is the internal representation.</p> </item> - <tag><c>{error, Error}</c>if there is an error in <c>RegExpString</c>.</tag> + <tag><c>{error, <anno>Error</anno>}</c></tag> <item> - <p></p> + <p>if there is an error in <c><anno>RegExp</anno></c>.</p> </item> </taglist> </desc> </func> <func> - <name>format_error(ErrorDescriptor) -> Chars</name> + <name name="format_error" arity="1"/> <fsummary>Format an error descriptor</fsummary> - <type> - <v>ErrorDescriptor = errordesc()</v> - <v>Chars = [char() | Chars]</v> - </type> <desc> - <p>Returns a string which describes the error <c>ErrorDescriptor</c> + <p>Returns a string which describes the error <c><anno>ErrorDescriptor</anno></c> returned when there is an error in a regular expression.</p> </desc> </func> |