File: string.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (558 lines) | stat: -rw-r--r-- 14,726 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>string</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>string</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
string
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
String Processing Functions
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>This module contains functions for string processing.

</DIV>

<H3>EXPORTS</H3>

<P><A NAME="len/1"><STRONG><CODE>len(String) -&#62; Length</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = string()</CODE></STRONG><BR>
<STRONG><CODE>Length = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns the number of characters in the string.

</DIV>

<P><A NAME="equal/2"><STRONG><CODE>equal(String1, String2) -&#62; bool()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String1 = String2 = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Tests whether two strings are equal. Returns <CODE>true</CODE> if
they are, otherwise <CODE>false</CODE>.

</DIV>

<P><A NAME="concat/2"><STRONG><CODE>concat(String1, String2) -&#62; String3</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String1 = String2 = String3 = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Concatenates two strings to form a new string. Returns the
new string.

</DIV>

<P><A NAME="chr/2"><STRONG><CODE>chr(String, Character) -&#62; Index</CODE></STRONG></A><BR>
<A NAME="rchr/2"><STRONG><CODE>rchr(String, Character) -&#62; Index</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = string()</CODE></STRONG><BR>
<STRONG><CODE>Character = char()</CODE></STRONG><BR>
<STRONG><CODE>Index = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns the index of the first/last occurrence of
<CODE>Character</CODE> in <CODE>String</CODE>. <CODE>0</CODE> is returned if <CODE>Character</CODE> does not
occur.

</DIV>

<P><A NAME="str/2"><STRONG><CODE>str(String, SubString) -&#62; Index</CODE></STRONG></A><BR>
<A NAME="rstr/2"><STRONG><CODE>rstr(String, SubString) -&#62; Index</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = SubString = string()</CODE></STRONG><BR>
<STRONG><CODE>Index = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns the position where the first/last occurrence of
<CODE>SubString</CODE> begins in <CODE>String</CODE>. <CODE>0</CODE> is returned if <CODE>SubString</CODE>
does not exist in <CODE>String</CODE>.
For example:
<PRE>
&#62; string:str(&#34; Hello Hello World World &#34;, &#34;Hello World&#34;).
8
</PRE>

</DIV>

<P><A NAME="span/2"><STRONG><CODE>span(String, Chars) -&#62; Length </CODE></STRONG></A><BR>
<A NAME="cspan/2"><STRONG><CODE>cspan(String, Chars) -&#62; Length</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = Chars = string()</CODE></STRONG><BR>
<STRONG><CODE>Length = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns the length of the maximum initial segment of
String, which consists entirely of characters from (not
from) Chars.

<P>For example:
<PRE>
&#62; string:span(&#34;\t    abcdef&#34;, &#34; \t&#34;).
5
&#62; string:cspan(&#34;\t    abcdef&#34;, &#34; \t&#34;).
0
</PRE>

</DIV>

<P><A NAME="substr/2"><STRONG><CODE>substr(String, Start) -&#62; SubString</CODE></STRONG></A><BR>
<A NAME="substr/3"><STRONG><CODE>substr(String, Start, Length) -&#62; Substring</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = SubString = string()</CODE></STRONG><BR>
<STRONG><CODE>Start = Length = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns a substring of <CODE>String</CODE>, starting at the
position <CODE>Start</CODE>, and ending at the end of the string or
at length <CODE>Length</CODE>.

<P>For example:
<PRE>
&#62; substr(&#34;Hello World&#34;, 4, 5).
&#34;lo Wo&#34;
</PRE>

</DIV>

<P><A NAME="tokens/2"><STRONG><CODE>tokens(String, SeparatorList) -&#62; Tokens</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = SeparatorList = string()</CODE></STRONG><BR>
<STRONG><CODE>Tokens = [string()]</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns a list of tokens in <CODE>String</CODE>, separated by the
characters in <CODE>SeparatorList</CODE>.

<P>For example:
<PRE>
&#62; tokens(&#34;abc defxxghix jkl&#34;, &#34;x &#34;).
[&#34;abc&#34;, &#34;def&#34;, &#34;ghi&#34;, &#34;jkl&#34;]
</PRE>

</DIV>

<P><A NAME="chars/2"><STRONG><CODE>chars(Character, Number) -&#62; String</CODE></STRONG></A><BR>
<A NAME="chars/3"><STRONG><CODE>chars(Character, Number, Tail) -&#62; String</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Character = char()</CODE></STRONG><BR>
<STRONG><CODE>Number = integer()</CODE></STRONG><BR>
<STRONG><CODE>String = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns a string consisting of <CODE>Number</CODE> of characters
<CODE>Character</CODE>. Optionally, the string can end with the
string <CODE>Tail</CODE>.

</DIV>

<P><A NAME="copies/2"><STRONG><CODE>copies(String, Number) -&#62; Copies</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = Copies = string()</CODE></STRONG><BR>
<STRONG><CODE>Number = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns a string containing <CODE>String</CODE> repeated
<CODE>Number</CODE> times.

</DIV>

<P><A NAME="words/1"><STRONG><CODE>words(String) -&#62; Count</CODE></STRONG></A><BR>
<A NAME="words/2"><STRONG><CODE>words(String, Character) -&#62; Count</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = string()</CODE></STRONG><BR>
<STRONG><CODE>Character = char()</CODE></STRONG><BR>
<STRONG><CODE>Count = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns the number of words in <CODE>String</CODE>, separated by
blanks or <CODE>Character</CODE>.

<P>For example:
<PRE>
&#62; words(&#34; Hello old boy!&#34;, $o).
4
</PRE>

</DIV>

<P><A NAME="sub_word/2"><STRONG><CODE>sub_word(String, Number) -&#62; Word</CODE></STRONG></A><BR>
<A NAME="sub_word/3"><STRONG><CODE>sub_word(String, Number, Character) -&#62; Word</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = Word = string()</CODE></STRONG><BR>
<STRONG><CODE>Character = char()</CODE></STRONG><BR>
<STRONG><CODE>Number = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns the word in position <CODE>Number</CODE> of <CODE>String</CODE>.
Words are separated by blanks or <CODE>Character</CODE>s.

<P>For example:
<PRE>
&#62; string:sub_word(&#34; Hello old boy !&#34;,3,$o).
&#34;ld b&#34;
</PRE>

</DIV>

<P><A NAME="strip/1"><STRONG><CODE>strip(String) -&#62; Stripped</CODE></STRONG></A><BR>
<A NAME="strip/2"><STRONG><CODE>strip(String, Direction) -&#62; Stripped</CODE></STRONG></A><BR>
<A NAME="strip/3"><STRONG><CODE>strip(String, Direction, Character) -&#62; Stripped</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = Stripped = string()</CODE></STRONG><BR>
<STRONG><CODE>Direction = left | right | both</CODE></STRONG><BR>
<STRONG><CODE>Character = char()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns a string, where leading and/or trailing blanks or a
number of <CODE>Character</CODE> have been removed.
<CODE>Direction</CODE> can be <CODE>left</CODE>, <CODE>right</CODE>, or
<CODE>both</CODE> and indicates from which direction blanks are to be
removed. The function <CODE>strip/1</CODE> is equivalent to
<CODE>strip(String, both)</CODE>.

<P>For example:
<PRE>
&#62; string:strip(&#34;...Hello.....&#34;, both, $.).
&#34;Hello&#34;
</PRE>

</DIV>

<P><A NAME="left/2"><STRONG><CODE>left(String, Number) -&#62; Left</CODE></STRONG></A><BR>
<A NAME="left/3"><STRONG><CODE>left(String, Number, Character) -&#62; Left</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = Left = string()</CODE></STRONG><BR>
<STRONG><CODE>Character = char</CODE></STRONG><BR>
<STRONG><CODE>Number = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns the <CODE>String</CODE> with the length adjusted in
accordance with <CODE>Number</CODE>. The left margin is
fixed. If the <CODE>length(String)</CODE> &#60; <CODE>Number</CODE>,
<CODE>String</CODE> is padded with blanks or <CODE>Character</CODE>s.

<P>For example:
<PRE>
&#62; string:left(&#34;Hello&#34;,10,$.).
&#34;Hello.....&#34;
</PRE>

</DIV>

<P><A NAME="right/2"><STRONG><CODE>right(String, Number) -&#62; Right</CODE></STRONG></A><BR>
<A NAME="right/3"><STRONG><CODE>right(String, Number, Character) -&#62; Right</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = Right = string()</CODE></STRONG><BR>
<STRONG><CODE>Character = char</CODE></STRONG><BR>
<STRONG><CODE>Number = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns the <CODE>String</CODE> with the length adjusted in
accordance with <CODE>Number</CODE>. The right margin is
fixed. If the length of <CODE>(String)</CODE> &#60; <CODE>Number</CODE>,
<CODE>String</CODE> is padded with blanks or <CODE>Character</CODE>s.

<P>For example:
<PRE>
&#62; string:right(&#34;Hello&#34;, 10, $.).
&#34;.....Hello&#34;
</PRE>

</DIV>

<P><A NAME="centre/2"><STRONG><CODE>centre(String, Number) -&#62; Centered</CODE></STRONG></A><BR>
<A NAME="centre/3"><STRONG><CODE>centre(String, Number, Character) -&#62; Centered</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = Centered = string()</CODE></STRONG><BR>
<STRONG><CODE>Character = char</CODE></STRONG><BR>
<STRONG><CODE>Number = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns a string, where <CODE>String</CODE> is centred in the
string and surrounded by blanks or characters. The resulting
string will have the length <CODE>Number</CODE>.

</DIV>

<P><A NAME="sub_string/2"><STRONG><CODE>sub_string(String, Start) -&#62; SubString</CODE></STRONG></A><BR>
<A NAME="sub_string/3"><STRONG><CODE>sub_string(String, Start, Stop) -&#62; SubString</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = SubString = string()</CODE></STRONG><BR>
<STRONG><CODE>Start = Stop = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns a substring of <CODE>String</CODE>, starting at the
position <CODE>Start</CODE> to the end of the string, or to and
including the <CODE>Stop</CODE> position.

<P>For example:
<PRE>
sub_string(&#34;Hello World&#34;, 4, 8).
&#34;lo Wo&#34;
</PRE>

</DIV>

<P><A NAME="to_float/1"><STRONG><CODE>to_float(String) -&#62; {Float,Rest} | {error,Reason} </CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = string()</CODE></STRONG><BR>
<STRONG><CODE>Float = float()</CODE></STRONG><BR>
<STRONG><CODE>Rest = string()</CODE></STRONG><BR>
<STRONG><CODE>Reason = no_float | not_a_list</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Argument <CODE>String</CODE> 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 <CODE>Rest</CODE>.

<P>Example:
        
<PRE>
          &#62; {F1,Fs} = string:to_float(&#34;1.0-1.0e-1&#34;),
          &#62; {F2,[]} = string:to_float(Fs),
          &#62; F1+F2.
          0.900000
          &#62; string:to_float(&#34;3/2=1.5&#34;).
          {error,no_float}
          &#62; string:to_float(&#34;-1.5eX&#34;).
          {-1.50000,&#34;eX&#34;}
        
</PRE>

</DIV>

<P><A NAME="to_integer/1"><STRONG><CODE>to_integer(String) -&#62; {Int,Rest} | {error,Reason} </CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>String = string()</CODE></STRONG><BR>
<STRONG><CODE>Int = integer()</CODE></STRONG><BR>
<STRONG><CODE>Rest = string()</CODE></STRONG><BR>
<STRONG><CODE>Reason = no_integer | not_a_list</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Argument <CODE>String</CODE> 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 <CODE>Rest</CODE>.

<P>Example:
        
<PRE>
          &#62; {I1,Is} = string:to_integer(&#34;33+22&#34;),
          &#62; {I2,[]} = string:to_integer(Is),
          &#62; I1-I2.
          11
          &#62; string:to_integer(&#34;0.5&#34;).
          {0,&#34;.5&#34;}
          &#62; string:to_integer(&#34;x=2&#34;).
          {error,no_integer}
        
</PRE>

</DIV>

<H3>Notes</H3>
<DIV CLASS=REFBODY>

<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>The regular expression functions have been moved to their own
module <CODE>regexp</CODE> (see <A HREF="regexp.html">regexp(3)</A>). 
The old entry points still
exist for backwards compatibility, but will be removed in a
future release so that users are encouraged to use the module
<CODE>regexp</CODE>.


<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Note!" SRC="note.gif"></TD>
    <TD>

<P>Any undocumented functions in <CODE>string</CODE> should not be used.
    </TD>
  </TR>
</TABLE>

</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Robert Virding - support@erlang.ericsson.se<BR>
Torbjorn Tornkvist - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>stdlib 1.14.2<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>