diff options
Diffstat (limited to 'lib/stdlib/doc/src/string.xml')
| -rw-r--r-- | lib/stdlib/doc/src/string.xml | 418 |
1 files changed, 242 insertions, 176 deletions
diff --git a/lib/stdlib/doc/src/string.xml b/lib/stdlib/doc/src/string.xml index d64db6c7ee..dddedf1132 100644 --- a/lib/stdlib/doc/src/string.xml +++ b/lib/stdlib/doc/src/string.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2014</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -24,306 +24,372 @@ <title>string</title> <prepared>Robert Virding</prepared> - <responsible>Bjarne Dacker</responsible> + <responsible>Bjarne Däcker</responsible> <docno>1</docno> <approved>Bjarne Däcker</approved> <checked></checked> - <date>96-09-28</date> + <date>1996-09-28</date> <rev>A</rev> - <file>string.sgml</file> + <file>string.xml</file> </header> <module>string</module> - <modulesummary>String Processing Functions</modulesummary> + <modulesummary>String processing functions.</modulesummary> <description> - <p>This module contains functions for string processing.</p> + <p>This module provides functions for string processing.</p> </description> + <funcs> <func> - <name name="len" arity="1"/> - <fsummary>Return the length of a string</fsummary> + <name name="centre" arity="2"/> + <name name="centre" arity="3"/> + <fsummary>Center a string.</fsummary> <desc> - <p>Returns the number of characters in the string.</p> + <p>Returns a string, where <c><anno>String</anno></c> is centered in the + string and surrounded by blanks or <c><anno>Character</anno></c>. + The resulting string has length <c><anno>Number</anno></c>.</p> </desc> </func> + <func> - <name name="equal" arity="2"/> - <fsummary>Test string equality</fsummary> + <name name="chars" arity="2"/> + <name name="chars" arity="3"/> + <fsummary>Returns a string consisting of numbers of characters.</fsummary> <desc> - <p>Tests whether two strings are equal. Returns <c>true</c> if - they are, otherwise <c>false</c>.</p> + <p>Returns a string consisting of <c><anno>Number</anno></c> characters + <c><anno>Character</anno></c>. Optionally, the string can end with + string <c><anno>Tail</anno></c>.</p> </desc> </func> + <func> - <name name="concat" arity="2"/> - <fsummary>Concatenate two strings</fsummary> + <name name="chr" arity="2"/> + <fsummary>Return the index of the first occurrence of + a character in a string.</fsummary> <desc> - <p>Concatenates two strings to form a new string. Returns the - new string.</p> + <p>Returns the index of the first occurrence of + <c><anno>Character</anno></c> in <c><anno>String</anno></c>. Returns + <c>0</c> if <c><anno>Character</anno></c> does not occur.</p> </desc> </func> + <func> - <name name="chr" arity="2"/> - <name name="rchr" arity="2"/> - <fsummary>Return the index of the first/last occurrence of<c>Character</c>in <c>String</c></fsummary> + <name name="concat" arity="2"/> + <fsummary>Concatenate two strings.</fsummary> <desc> - <p>Returns the index of the first/last occurrence of - <c><anno>Character</anno></c> in <c><anno>String</anno></c>. <c>0</c> is returned if <c><anno>Character</anno></c> does not - occur.</p> + <p>Concatenates <c><anno>String1</anno></c> and + <c><anno>String2</anno></c> to form a new string + <c><anno>String3</anno></c>, which is returned.</p> </desc> </func> + <func> - <name name="str" arity="2"/> - <name name="rstr" arity="2"/> - <fsummary>Find the index of a substring</fsummary> + <name name="copies" arity="2"/> + <fsummary>Copy a string.</fsummary> <desc> - <p>Returns the position where the first/last occurrence of - <c><anno>SubString</anno></c> begins in <c><anno>String</anno></c>. <c>0</c> is returned if <c><anno>SubString</anno></c> - does not exist in <c><anno>String</anno></c>. - For example:</p> - <code type="none"> -> string:str(" Hello Hello World World ", "Hello World"). -8 </code> + <p>Returns a string containing <c><anno>String</anno></c> repeated + <c><anno>Number</anno></c> times.</p> </desc> </func> + <func> - <name name="span" arity="2"/> <name name="cspan" arity="2"/> - <fsummary>Span characters at start of string</fsummary> + <fsummary>Span characters at start of a string.</fsummary> <desc> <p>Returns the length of the maximum initial segment of - <c><anno>String</anno></c>, which consists entirely of characters from (not - from) <c><anno>Chars</anno></c>.</p> - <p>For example:</p> + <c><anno>String</anno></c>, which consists entirely of characters + not from <c><anno>Chars</anno></c>.</p> + <p><em>Example:</em></p> <code type="none"> -> string:span("\t abcdef", " \t"). -5 > string:cspan("\t abcdef", " \t"). -0 </code> +0</code> </desc> </func> + <func> - <name name="substr" arity="2"/> - <name name="substr" arity="3"/> - <fsummary>Return a substring of <c>String</c></fsummary> + <name name="equal" arity="2"/> + <fsummary>Test string equality.</fsummary> + <desc> + <p>Returns <c>true</c> if <c><anno>String1</anno></c> and + <c><anno>String2</anno></c> are equal, otherwise <c>false</c>.</p> + </desc> + </func> + + <func> + <name name="join" arity="2"/> + <fsummary>Join a list of strings with separator.</fsummary> <desc> - <p>Returns a substring of <c><anno>String</anno></c>, starting at the - position <c><anno>Start</anno></c>, and ending at the end of the string or - at length <c><anno>Length</anno></c>.</p> - <p>For example:</p> + <p>Returns a string with the elements of <c><anno>StringList</anno></c> + separated by the string in <c><anno>Separator</anno></c>.</p> + <p><em>Example:</em></p> <code type="none"> -> substr("Hello World", 4, 5). -"lo Wo" </code> +> join(["one", "two", "three"], ", "). +"one, two, three"</code> </desc> </func> + <func> - <name name="tokens" arity="2"/> - <fsummary>Split string into tokens</fsummary> + <name name="left" arity="2"/> + <name name="left" arity="3"/> + <fsummary>Adjust left end of a string.</fsummary> <desc> - <p>Returns a list of tokens in <c><anno>String</anno></c>, separated by the - characters in <c><anno>SeparatorList</anno></c>.</p> - <p>For example:</p> + <p>Returns <c><anno>String</anno></c> with the length adjusted in + accordance with <c><anno>Number</anno></c>. The left margin is + fixed. If <c>length(<anno>String</anno>)</c> < + <c><anno>Number</anno></c>, then <c><anno>String</anno></c> is padded + with blanks or <c><anno>Character</anno></c>s.</p> + <p><em>Example:</em></p> <code type="none"> -> tokens("abc defxxghix jkl", "x "). -["abc", "def", "ghi", "jkl"] </code> - <p>Note that, as shown in the example above, two or more - adjacent separator characters in <c><anno>String</anno></c> - will be treated as one. That is, there will not be any empty - strings in the resulting list of tokens.</p> +> string:left("Hello",10,$.). +"Hello....."</code> </desc> </func> + <func> - <name name="join" arity="2"/> - <fsummary>Join a list of strings with separator</fsummary> + <name name="len" arity="1"/> + <fsummary>Return the length of a string.</fsummary> <desc> - <p>Returns a string with the elements of <c><anno>StringList</anno></c> - separated by the string in <c><anno>Separator</anno></c>.</p> - <p>For example:</p> - <code type="none"> -> join(["one", "two", "three"], ", "). -"one, two, three" </code> + <p>Returns the number of characters in <c><anno>String</anno></c>.</p> </desc> </func> + <func> - <name name="chars" arity="2"/> - <name name="chars" arity="3"/> - <fsummary>Returns a string consisting of numbers of characters</fsummary> + <name name="rchr" arity="2"/> + <fsummary>Return the index of the last occurrence of + a character in a string.</fsummary> <desc> - <p>Returns a string consisting of <c><anno>Number</anno></c> of characters - <c><anno>Character</anno></c>. Optionally, the string can end with the - string <c><anno>Tail</anno></c>.</p> + <p>Returns the index of the last occurrence of + <c><anno>Character</anno></c> in <c><anno>String</anno></c>. Returns + <c>0</c> if <c><anno>Character</anno></c> does not occur.</p> </desc> </func> + <func> - <name name="copies" arity="2"/> - <fsummary>Copy a string</fsummary> + <name name="right" arity="2"/> + <name name="right" arity="3"/> + <fsummary>Adjust right end of a string.</fsummary> <desc> - <p>Returns a string containing <c><anno>String</anno></c> repeated - <c><anno>Number</anno></c> times.</p> + <p>Returns <c><anno>String</anno></c> with the length adjusted in + accordance with <c><anno>Number</anno></c>. The right margin is + fixed. If the length of <c>(<anno>String</anno>)</c> < + <c><anno>Number</anno></c>, then <c><anno>String</anno></c> is padded + with blanks or <c><anno>Character</anno></c>s.</p> + <p><em>Example:</em></p> + <code type="none"> +> string:right("Hello", 10, $.). +".....Hello"</code> </desc> </func> + <func> - <name name="words" arity="1"/> - <name name="words" arity="2"/> - <fsummary>Count blank separated words</fsummary> + <name name="rstr" arity="2"/> + <fsummary>Find the index of a substring.</fsummary> <desc> - <p>Returns the number of words in <c><anno>String</anno></c>, separated by - blanks or <c><anno>Character</anno></c>.</p> - <p>For example:</p> + <p>Returns the position where the last occurrence of + <c><anno>SubString</anno></c> begins in <c><anno>String</anno></c>. + Returns <c>0</c> if <c><anno>SubString</anno></c> + does not exist in <c><anno>String</anno></c>.</p> + <p><em>Example:</em></p> <code type="none"> -> words(" Hello old boy!", $o). -4 </code> +> string:rstr(" Hello Hello World World ", "Hello World"). +8</code> </desc> </func> + <func> - <name name="sub_word" arity="2"/> - <name name="sub_word" arity="3"/> - <fsummary>Extract subword</fsummary> + <name name="span" arity="2"/> + <fsummary>Span characters at start of a string.</fsummary> <desc> - <p>Returns the word in position <c><anno>Number</anno></c> of <c><anno>String</anno></c>. - Words are separated by blanks or <c><anno>Character</anno></c>s.</p> - <p>For example:</p> + <p>Returns the length of the maximum initial segment of + <c><anno>String</anno></c>, which consists entirely of characters + from <c><anno>Chars</anno></c>.</p> + <p><em>Example:</em></p> <code type="none"> -> string:sub_word(" Hello old boy !",3,$o). -"ld b" </code> +> string:span("\t abcdef", " \t"). +5</code> </desc> </func> + + <func> + <name name="str" arity="2"/> + <fsummary>Find the index of a substring.</fsummary> + <desc> + <p>Returns the position where the first occurrence of + <c><anno>SubString</anno></c> begins in <c><anno>String</anno></c>. + Returns <c>0</c> if <c><anno>SubString</anno></c> + does not exist in <c><anno>String</anno></c>.</p> + <p><em>Example:</em></p> + <code type="none"> +> string:str(" Hello Hello World World ", "Hello World"). +8</code> + </desc> + </func> + <func> <name name="strip" arity="1"/> <name name="strip" arity="2"/> <name name="strip" arity="3"/> - <fsummary>Strip leading or trailing characters</fsummary> + <fsummary>Strip leading or trailing characters.</fsummary> <desc> <p>Returns a string, where leading and/or trailing blanks or a number of <c><anno>Character</anno></c> have been removed. - <c><anno>Direction</anno></c> can be <c>left</c>, <c>right</c>, or - <c>both</c> and indicates from which direction blanks are to be - removed. The function <c>strip/1</c> is equivalent to + <c><anno>Direction</anno></c>, which can be <c>left</c>, <c>right</c>, + or <c>both</c>, indicates from which direction blanks are to be + removed. <c>strip/1</c> is equivalent to <c>strip(String, both)</c>.</p> - <p>For example:</p> + <p><em>Example:</em></p> <code type="none"> > string:strip("...Hello.....", both, $.). -"Hello" </code> +"Hello"</code> </desc> </func> + <func> - <name name="left" arity="2"/> - <name name="left" arity="3"/> - <fsummary>Adjust left end of string</fsummary> + <name name="sub_string" arity="2"/> + <name name="sub_string" arity="3"/> + <fsummary>Extract a substring.</fsummary> <desc> - <p>Returns the <c><anno>String</anno></c> with the length adjusted in - accordance with <c><anno>Number</anno></c>. The left margin is - fixed. If the <c>length(<anno>String</anno>)</c> < <c><anno>Number</anno></c>, - <c><anno>String</anno></c> is padded with blanks or <c><anno>Character</anno></c>s.</p> - <p>For example:</p> + <p>Returns a substring of <c><anno>String</anno></c>, starting at + position <c><anno>Start</anno></c> to the end of the string, or to + and including position <c><anno>Stop</anno></c>.</p> + <p><em>Example:</em></p> <code type="none"> -> string:left("Hello",10,$.). -"Hello....." </code> +sub_string("Hello World", 4, 8). +"lo Wo"</code> </desc> </func> + <func> - <name name="right" arity="2"/> - <name name="right" arity="3"/> - <fsummary>Adjust right end of string</fsummary> + <name name="substr" arity="2"/> + <name name="substr" arity="3"/> + <fsummary>Return a substring of a string.</fsummary> <desc> - <p>Returns the <c><anno>String</anno></c> with the length adjusted in - accordance with <c><anno>Number</anno></c>. The right margin is - fixed. If the length of <c>(<anno>String</anno>)</c> < <c><anno>Number</anno></c>, - <c><anno>String</anno></c> is padded with blanks or <c><anno>Character</anno></c>s.</p> - <p>For example:</p> + <p>Returns a substring of <c><anno>String</anno></c>, starting at + position <c><anno>Start</anno></c>, and ending at the end of the + string or at length <c><anno>Length</anno></c>.</p> + <p><em>Example:</em></p> <code type="none"> -> string:right("Hello", 10, $.). -".....Hello" </code> - </desc> - </func> - <func> - <name name="centre" arity="2"/> - <name name="centre" arity="3"/> - <fsummary>Center a string</fsummary> - <desc> - <p>Returns a string, where <c><anno>String</anno></c> is centred in the - string and surrounded by blanks or characters. The resulting - string will have the length <c><anno>Number</anno></c>.</p> +> substr("Hello World", 4, 5). +"lo Wo"</code> </desc> </func> + <func> - <name name="sub_string" arity="2"/> - <name name="sub_string" arity="3"/> - <fsummary>Extract a substring</fsummary> + <name name="sub_word" arity="2"/> + <name name="sub_word" arity="3"/> + <fsummary>Extract subword.</fsummary> <desc> - <p>Returns a substring of <c><anno>String</anno></c>, starting at the - position <c><anno>Start</anno></c> to the end of the string, or to and - including the <c><anno>Stop</anno></c> position.</p> - <p>For example:</p> + <p>Returns the word in position <c><anno>Number</anno></c> of + <c><anno>String</anno></c>. Words are separated by blanks or + <c><anno>Character</anno></c>s.</p> + <p><em>Example:</em></p> <code type="none"> -sub_string("Hello World", 4, 8). -"lo Wo" </code> +> string:sub_word(" Hello old boy !",3,$o). +"ld b"</code> </desc> </func> + <func> <name name="to_float" arity="1"/> - <fsummary>Returns a float whose text representation is the integers (ASCII values) in String.</fsummary> + <fsummary>Returns a float whose text representation is the integers + (ASCII values) in a string.</fsummary> <desc> - <p>Argument <c><anno>String</anno></c> is expected to start with a valid text - represented float (the digits being ASCII values). Remaining characters - in the string after the float are returned in <c><anno>Rest</anno></c>.</p> - <p>Example:</p> + <p>Argument <c><anno>String</anno></c> is expected to start with a + valid text represented float (the digits are ASCII values). + Remaining characters in the string after the float are returned in + <c><anno>Rest</anno></c>.</p> + <p><em>Example:</em></p> <code type="none"> - > {F1,Fs} = string:to_float("1.0-1.0e-1"), - > {F2,[]} = string:to_float(Fs), - > F1+F2. - 0.9 - > string:to_float("3/2=1.5"). - {error,no_float} - > string:to_float("-1.5eX"). - {-1.5,"eX"}</code> +> {F1,Fs} = string:to_float("1.0-1.0e-1"), +> {F2,[]} = string:to_float(Fs), +> F1+F2. +0.9 +> string:to_float("3/2=1.5"). +{error,no_float} +> string:to_float("-1.5eX"). +{-1.5,"eX"}</code> </desc> </func> + <func> <name name="to_integer" arity="1"/> - <fsummary>Returns an integer whose text representation is the integers (ASCII values) in String.</fsummary> + <fsummary>Returns an integer whose text representation is the integers + (ASCII values) in a string.</fsummary> <desc> - <p>Argument <c><anno>String</anno></c> is expected to start with a valid text - represented integer (the digits being ASCII values). Remaining characters - in the string after the integer are returned in <c><anno>Rest</anno></c>.</p> - <p>Example:</p> + <p>Argument <c><anno>String</anno></c> is expected to start with a + valid text represented integer (the digits are ASCII values). + Remaining characters in the string after the integer are returned in + <c><anno>Rest</anno></c>.</p> + <p><em>Example:</em></p> <code type="none"> - > {I1,Is} = string:to_integer("33+22"), - > {I2,[]} = string:to_integer(Is), - > I1-I2. - 11 - > string:to_integer("0.5"). - {0,".5"} - > string:to_integer("x=2"). - {error,no_integer}</code> +> {I1,Is} = string:to_integer("33+22"), +> {I2,[]} = string:to_integer(Is), +> I1-I2. +11 +> string:to_integer("0.5"). +{0,".5"} +> string:to_integer("x=2"). +{error,no_integer}</code> </desc> </func> + <func> <name name="to_lower" arity="1" clause_i="1"/> <name name="to_lower" arity="1" clause_i="2"/> <name name="to_upper" arity="1" clause_i="1"/> <name name="to_upper" arity="1" clause_i="2"/> - <fsummary>Convert case of string (ISO/IEC 8859-1)</fsummary> + <fsummary>Convert case of string (ISO/IEC 8859-1).</fsummary> <type variable="String" name_i="1"/> <type variable="Result" name_i="1"/> <type variable="Char"/> <type variable="CharResult"/> <desc> - <p>The given string or character is case-converted. Note that - the supported character set is ISO/IEC 8859-1 (a.k.a. Latin 1), - all values outside this set is unchanged</p> + <p>The specified string or character is case-converted. Notice that + the supported character set is ISO/IEC 8859-1 (also called Latin 1); + all values outside this set are unchanged</p> + </desc> + </func> + + <func> + <name name="tokens" arity="2"/> + <fsummary>Split string into tokens.</fsummary> + <desc> + <p>Returns a list of tokens in <c><anno>String</anno></c>, separated + by the characters in <c><anno>SeparatorList</anno></c>.</p> + <p><em>Example:</em></p> + <code type="none"> +> tokens("abc defxxghix jkl", "x "). +["abc", "def", "ghi", "jkl"]</code> + <p>Notice that, as shown in this example, two or more + adjacent separator characters in <c><anno>String</anno></c> + are treated as one. That is, there are no empty + strings in the resulting list of tokens.</p> + </desc> + </func> + + <func> + <name name="words" arity="1"/> + <name name="words" arity="2"/> + <fsummary>Count blank separated words.</fsummary> + <desc> + <p>Returns the number of words in <c><anno>String</anno></c>, separated + by blanks or <c><anno>Character</anno></c>.</p> + <p><em>Example:</em></p> + <code type="none"> +> words(" Hello old boy!", $o). +4</code> </desc> </func> </funcs> <section> <title>Notes</title> - <p>Some of the general string functions may seem to overlap each - other. The reason for this is that this string package is the - combination of two earlier packages and all the functions of - both packages have been retained. - </p> + <p>Some of the general string functions can seem to overlap each + other. The reason is that this string package is the + combination of two earlier packages and all functions of + both packages have been retained.</p> + <note> - <p>Any undocumented functions in <c>string</c> should not be used.</p> + <p>Any undocumented functions in <c>string</c> are not to be used.</p> </note> </section> </erlref> |