[PHP-DOC] cvs: phpdoc /it/functions strings.xml From: Luca Perugini (l.perugini <email protected>)
Date: 09/18/00

perugini Mon Sep 18 08:47:18 2000 EDT

  Modified files:
    /phpdoc/it/functions strings.xml
  Log:
  Sync : PHP3 -> PHP 3 , PHP4 -> PHP 4
  
  
Index: phpdoc/it/functions/strings.xml
diff -u phpdoc/it/functions/strings.xml:1.5 phpdoc/it/functions/strings.xml:1.6
--- phpdoc/it/functions/strings.xml:1.5 Thu Aug 31 01:45:01 2000
+++ phpdoc/it/functions/strings.xml Mon Sep 18 08:47:17 2000
@@ -8,12 +8,20 @@
     specialized sections can be found in the regular expression and
     URL handling sections.
    </simpara>
+
+ <para>
+ For information on how strings behave, especially with regard to
+ usage of single quotes, double quotes, and escape sequences, see
+ the <link linkend="language.types.string">Strings</link> entry in
+ the <link linkend="language.types">Types</link> section of the
+ manual.
+ </para>
   </partintro>
 
   <refentry id="function.addcslashes">
    <refnamediv>
     <refname>AddCSlashes</refname>
- <refpurpose>Quote string with slashes in a C style.</refpurpose>
+ <refpurpose>Quote string with slashes in a C style</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -108,7 +116,7 @@
   <refentry id="function.chop">
    <refnamediv>
     <refname>Chop</refname>
- <refpurpose>Remove trailing whitespace.</refpurpose>
+ <refpurpose>Remove trailing whitespace</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -128,8 +136,16 @@
       </programlisting>
      </example>
     </para>
+ <note>
+ <para>
+ <function>chop</function> is different than the Perl
+ <parameter>chop()</parameter> function, which removes the last
+ character in the string.
+ </para>
+ </note>
     <para>
- See also <function>trim</function>.
+ See also <function>trim</function>, <function>ltrim</function>,
+ <function>rtrim</function>, and <function>chop</function>.
     </para>
    </refsect1>
   </refentry>
@@ -137,7 +153,7 @@
   <refentry id="function.chr">
    <refnamediv>
     <refname>Chr</refname>
- <refpurpose>Return a specific character.</refpurpose>
+ <refpurpose>Return a specific character</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -170,7 +186,7 @@
   <refentry id="function.chunk-split">
    <refnamediv>
     <refname>chunk_split</refname>
- <refpurpose>Split a string into smaller chunks.</refpurpose>
+ <refpurpose>Split a string into smaller chunks</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -217,7 +233,7 @@
    <refnamediv>
     <refname>convert_cyr_string</refname>
     <refpurpose>
- Convert from one Cyrillic character set to another.
+ Convert from one Cyrillic character set to another
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -276,7 +292,7 @@
    <refnamediv>
     <refname>count_chars</refname>
     <refpurpose>
- Return information abouts characters used in a string.
+ Return information abouts characters used in a string
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -308,7 +324,7 @@
       <listitem>
        <simpara>
         1 - same as 0 but only byte-values with a frequency greater
- zero are listed.
+ than zero are listed.
        </simpara>
       </listitem>
       <listitem>
@@ -336,11 +352,35 @@
     </note>
    </refsect1>
   </refentry>
+
+ <refentry id="function.crc32">
+ <refnamediv>
+ <refname>crc32</refname>
+ <refpurpose>Calculates the crc32 polynomial of a string</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>crc32</function></funcdef>
+ <paramdef>string <parameter>str</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Generates the cyclic redundancy checksum polynomial of 32-bit lengths of
+ the <parameter>str</parameter>. This is usually used to validate the
+ integrity of data being trasmited.
+ </para>
+ <para>
+ See also: <function>md5</function>
+ </para>
+ </refsect1>
+ </refentry>
  
   <refentry id="function.crypt">
    <refnamediv>
     <refname>crypt</refname>
- <refpurpose>DES-encrypt a string.</refpurpose>
+ <refpurpose>DES-encrypt a string</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -361,7 +401,7 @@
      crypt function for more information.
     </para>
     <simpara>
- If the salt argument is not provided, it will be randomly
+ If the salt argument is not provided, one will be randomly
      generated by PHP.
     </simpara>
     <simpara>
@@ -371,14 +411,20 @@
      by the salt argument. At install time, PHP determines the
      capabilities of the crypt function and will accept salts for
      other encryption types. If no salt is provided, PHP will
- auto-generate a standard 2-character DES salt by default unless
- the default encryption type on the system is MD5 in which case a
+ auto-generate a standard 2-character DES salt by default, unless
+ the default encryption type on the system is MD5, in which case a
      random MD5-compatible salt is generated. PHP sets a constant
      named CRYPT_SALT_LENGTH which tells you whether a regular
      2-character salt applies to your system or the longer 12-char MD5
      salt is applicable.
     </simpara>
     <simpara>
+ If you are using the supplied salt, you should be aware that the
+ salt is generated once. If you are calling this function
+ recursively, this may impact both appearance and, to a certain
+ extent, security.
+ </simpara>
+ <simpara>
      The standard DES encryption <function>crypt</function> contains
      the salt as the first two characters of the output.
     </simpara>
@@ -415,13 +461,16 @@
      There is no decrypt function, since <function>crypt</function>
      uses a one-way algorithm.
     </simpara>
+ <simpara>
+ See also: <function>md5</function>.
+ </simpara>
    </refsect1>
   </refentry>
 
   <refentry id="function.echo">
    <refnamediv>
     <refname>echo</refname>
- <refpurpose>Output one or more strings.</refpurpose>
+ <refpurpose>Output one or more strings</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -481,11 +530,20 @@
       <funcdef>array <function>explode</function></funcdef>
       <paramdef>string <parameter>separator</parameter></paramdef>
       <paramdef>string <parameter>string</parameter></paramdef>
+ <paramdef>int
+ <parameter><optional>limit</optional></parameter>
+ </paramdef>
      </funcprototype>
     </funcsynopsis>
+ <para>
+ Returns an array of strings, each of which is a substring of
+ <parameter>string</parameter> formed by splitting it on boundaries formed
+ by the string <parameter>delim</parameter>.
+ If <parameter>limit</parameter> is set, the returned array will contaion
+ a maximum of <parameter>limit</parameter> elements with the last element
+ containing the whole rest of <parameter>string</parameter>.
+ </para>
     <para>
- Returns an array of strings containing the elements separated by
- <replaceable>separator</replaceable>.
      <example>
       <title><function>Explode</function> example</title>
       <programlisting role="php">
@@ -507,7 +565,7 @@
     <refpurpose>
      Returns the translation table used by
      <function>htmlspecialchars</function> and
- <function>htmlentities</function>.
+ <function>htmlentities</function>
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -518,28 +576,33 @@
        <function>get_html_translation_table</function>
       </funcdef>
       <paramdef>int <parameter>table</parameter></paramdef>
+ <paramdef>int <parameter><optional>quote_style</optional></parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
      <function>get_html_translation_table</function> will return the
      translation table that is used internally for
      <function>htmlspecialchars</function> and
- <function>htmlentities</function>. Ther are two new defines
+ <function>htmlentities</function>. There are two new defines
      (<parameter>HTML_ENTITIES</parameter>,
      <parameter>HTML_SPECIALCHARS</parameter>) that allow you to
- specify the table you want.
+ specify the table you want. And as in the
+ <function>htmlspecialchars</function> and
+ <function>htmlentities</function> functions you can optionally specify the
+ quote_style you are working with. The default is ENT_COMPAT mode. See
+ the description of these modes in <function>htmlspecialchars</function>.
      <example>
       <title>Translation Table Example</title>
       <programlisting role="php">
 $trans = get_html_translation_table (HTML_ENTITIES);
-$str = "Hallo & &lt;Frau> & Krämer";
+$str = "Hallo &amp; &lt;Frau> &amp; Kr&auml;mer";
 $encoded = strtr ($str, $trans);
       </programlisting>
      </example>
      The <literal>$encoded</literal> variable will now contain: "Hallo
- &<sgmltag>amp</sgmltag>;
- &<sgmltag>lt</sgmltag>;Frau&<sgmltag>gt</sgmltag>;
- &<sgmltag>amp</sgmltag>; Kr&<sgmltag>auml</sgmltag>;mer".
+ &amp;<sgmltag>amp</sgmltag>;
+ &amp;<sgmltag>lt</sgmltag>;Frau&amp;<sgmltag>gt</sgmltag>;
+ &amp;<sgmltag>amp</sgmltag>; Kr&amp;<sgmltag>auml</sgmltag>;mer".
     </para>
     <para>
      The cool thing is using <function>array_flip</function> to change
@@ -550,8 +613,8 @@
 $original = strtr ($str, $trans);
       </programlisting>
      </informalexample>
- The content of <literal>$original</literal> would be: "Hallo &
- &lt;Frau> & Krämer".
+ The content of <literal>$original</literal> would be: "Hallo &amp;
+ &lt;Frau> &amp; Kr&auml;mer".
      <note>
       <para>
        This function was added in PHP 4.0.
@@ -571,7 +634,7 @@
     <refname>get_meta_tags</refname>
     <refpurpose>
      Extracts all meta tag content attributes from a file and returns
- an array.
+ an array
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -614,11 +677,71 @@
    </refsect1>
   </refentry>
 
+ <refentry id="function.hebrev">
+ <refnamediv>
+ <refname>hebrev</refname>
+ <refpurpose>
+ Convert logical Hebrew text to visual text
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>string <function>hebrev</function></funcdef>
+ <paramdef>string <parameter>hebrew_text</parameter></paramdef>
+ <paramdef>int
+ <parameter><optional>max_chars_per_line</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ The optional parameter <parameter>max_chars_per_line</parameter>
+ indicates maximum number of characters per line will be output. The
+ function tries to avoid breaking words.
+ </para>
+ <para>
+ See also <function>hebrevc</function>
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.hebrevc">
+ <refnamediv>
+ <refname>hebrevc</refname>
+ <refpurpose>
+ Convert logical Hebrew text to visual text with newline conversion
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>string <function>hebrevc</function></funcdef>
+ <paramdef>string <parameter>hebrew_text</parameter></paramdef>
+ <paramdef>int
+ <parameter><optional>max_chars_per_line</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ This function is similar to <function>hebrev</function> with the
+ difference that it converts newlines (\n) to "&lt;br&gt;\n".
+ The optional parameter <parameter>max_chars_per_line</parameter>
+ indicates maximum number of characters per line will be output. The
+ function tries to avoid breaking words.
+ </para>
+ <para>
+ See also <function>hebrev</function>
+ </para>
+ </refsect1>
+ </refentry>
+
   <refentry id="function.htmlentities">
    <refnamediv>
     <refname>htmlentities</refname>
     <refpurpose>
- Convert all applicable characters to HTML entities.
+ Convert all applicable characters to HTML entities
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -627,16 +750,25 @@
      <funcprototype>
       <funcdef>string <function>htmlentities</function></funcdef>
       <paramdef>string <parameter>string</parameter></paramdef>
+ <paramdef>int <parameter><optional>quote_style</optional></parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
      This function is identical to
- <function>Htmlspecialchars</function> in all ways, except that
- all characters which have HTML entity equivalents are translated
- into these entities.
+ <function>htmlspecialchars</function> in all ways, except that
+ all characters which have HTML character entity equivalents are
+ translated into these entities. Like
+ <function>htmlspecialchars</function>, it takes an optional
+ second argument which indicates what should be done with single
+ and double quotes. <constant>ENT_COMPAT</constant> (the default)
+ will only convert double-quotes and leave single-quotes alone.
+ <constant>ENT_QUOTES</constant> will convert both double and
+ single quotes, and <constant>ENT_NOQUOTES</constant> will leave
+ both double and single quotes unconverted.
     </para>
     <para>
- At present, the ISO-8859-1 character set is used.
+ At present, the ISO-8859-1 character set is used. Note that the optional
+ second argument was added in PHP 3.0.17 and PHP 4.0.3.
     </para>
     <para>
      See also <function>htmlspecialchars</function> and
@@ -649,7 +781,7 @@
    <refnamediv>
     <refname>htmlspecialchars</refname>
     <refpurpose>
- Convert special characters to HTML entities.
+ Convert special characters to HTML entities
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -658,21 +790,31 @@
      <funcprototype>
       <funcdef>string <function>htmlspecialchars</function></funcdef>
       <paramdef>string <parameter>string</parameter></paramdef>
+ <paramdef>int <parameter><optional>quote_style</optional></parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
      Certain characters have special significance in HTML, and should
      be represented by HTML entities if they are to preserve their
- meanings. This function returns a string with these conversions
- made.
+ meanings. This function returns a string with some of these
+ conversions made; the translations made are those most
+ useful for everyday web programming. If you require all HTML
+ character entities to be translated, use
+ <function>htmlentities</function> instead.
     </para>
     <simpara>
      This function is useful in preventing user-supplied text from
      containing HTML markup, such as in a message board or guest book
- application.
+ application. The optional second argument, quote_style, tells the
+ function what to do with single and double quote characters. The
+ default mode, ENT_COMPAT, is the backwards compatible mode which only
+ translates the double-quote character and leaves the single-quote
+ untranslated. If ENT_QUOTES is set, both single and double quotes
+ are translated and if ENT_NOQUOTES is set neither single nor double quotes
+ are translated.
     </simpara>
     <para>
- At present, the translations that are done are:
+ The translations performed are:
      <itemizedlist>
       <listitem>
        <simpara>
@@ -681,11 +823,16 @@
       </listitem>
       <listitem>
        <simpara>
- '&quot;' (double quote) becomes '&amp;quot;'
+ '&quot;' (double quote) becomes '&amp;quot;' when ENT_NOQUOTES is not set.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
+ '&#039;' (single quote) becomes '&amp;#039;' only when ENT_QUOTES is set.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
         '&lt;' (less than) becomes '&amp;lt;'
        </simpara>
       </listitem>
@@ -695,11 +842,18 @@
        </simpara>
       </listitem>
      </itemizedlist>
+ <example>
+ <title><function>htmlspecialchars</function> example</title>
+ <programlisting role="php">
+$new = htmlspecialchars("&lt;a href='test'&gt;Test&lt;/a&gt;", ENT_QUOTES);
+ </programlisting>
+ </example>
     </para>
     <para>
- Note that this functions does not translate anything beyond what
+ Note that this function does not translate anything beyond what
      is listed above. For full entity translation, see
- <function>htmlentities</function>.
+ <function>htmlentities</function>. Also note that the optional second
+ argument was added in PHP 3.0.17 and PHP 4.0.3.
     </para>
     <para>
      See also <function>htmlentities</function> and
@@ -743,7 +897,7 @@
   <refentry id="function.join">
    <refnamediv>
     <refname>join</refname>
- <refpurpose>Join array elements with a string.</refpurpose>
+ <refpurpose>Join array elements with a string</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -765,11 +919,51 @@
    </refsect1>
   </refentry>
 
+ <refentry id="function.levenshtein">
+ <refnamediv>
+ <refname>levenshtein</refname>
+ <refpurpose>
+ Calculate Levenshtein distance between two strings
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>levenshtein</function></funcdef>
+ <paramdef>string <parameter>str1</parameter></paramdef>
+ <paramdef>string <parameter>str2</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ This function return the Levenshtein-Distance between the two
+ argument strings or -1, if one of the argument strings is longer
+ than the limit of 255 characters.
+ </para>
+ <para>
+ The Levenshtein distance is defined as the minimal number of
+ characters you have to replace, insert or delete to transform
+ <parameter>str1</parameter> into <parameter>str2</parameter>.
+ The complexity of the algorithm is <literal>O(m*n)</literal>,
+ where <literal>n</literal> and <literal>m</literal> are the
+ length of <parameter>str1</parameter> and
+ <parameter>str2</parameter> (rather good when compared to
+ <function>similar_text</function>, which is O(max(n,m)**3), but
+ still expensive).
+ </para>
+ <para>
+ See also <function>soundex</function>,
+ <function>similar_text</function> and
+ <function>metaphone</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
   <refentry id="function.ltrim">
    <refnamediv>
     <refname>ltrim</refname>
     <refpurpose>
- Strip whitespace from the beginning of a string.
+ Strip whitespace from the beginning of a string
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -787,7 +981,8 @@
      and a plain space.
     </para>
     <para>
- See also <function>chop</function> and <function>trim</function>.
+ See also <function>chop</function>, <function>rtrim</function>, and
+ <function>trim</function>.
     </para>
    </refsect1>
   </refentry>
@@ -795,7 +990,7 @@
   <refentry id="function.md5">
    <refnamediv>
     <refname>md5</refname>
- <refpurpose>Calculate the md5 hash of a string.</refpurpose>
+ <refpurpose>Calculate the md5 hash of a string</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -807,16 +1002,19 @@
     </funcsynopsis>
     <para>
      Calculates the MD5 hash of <parameter>str</parameter> using the
- <ulink url="http://ds.internic.net/rfc/rfc1321.txt">RSA Data
- Security, Inc. MD5 Message-Digest Algorithm</ulink>.
+ <ulink url="&url.rfc;rfc1321.html">RSA Data Security, Inc.
+ MD5 Message-Digest Algorithm</ulink>.
     </para>
+ <para>
+ See also: <function>crc32</function>
+ </para>
    </refsect1>
   </refentry>
 
   <refentry id="function.metaphone">
    <refnamediv>
     <refname>Metaphone</refname>
- <refpurpose>Calculate the metaphone key of a string.</refpurpose>
+ <refpurpose>Calculate the metaphone key of a string</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -839,7 +1037,7 @@
     <para>
      Metaphone was developed by Lawrence Philips
      &lt;lphilips <email protected>>. It is described in ["Practical
- Algorithms for Programmers", Binstock & Rex, Addison Wesley,
+ Algorithms for Programmers", Binstock &amp; Rex, Addison Wesley,
      1995].
      <note>
       <para>
@@ -853,7 +1051,7 @@
   <refentry id="function.nl2br">
    <refnamediv>
     <refname>nl2br</refname>
- <refpurpose>Converts newlines to HTML line breaks.</refpurpose>
+ <refpurpose>Converts newlines to HTML line breaks</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -868,8 +1066,9 @@
      before all newlines.
     </para>
     <para>
- See also <function>htmlspecialchars</function> and
- <function>htmlentities</function>.
+ See also <function>htmlspecialchars</function>,
+ <function>htmlentities</function> and
+ <function>wordwrap</function>.
     </para>
    </refsect1>
   </refentry>
@@ -877,7 +1076,7 @@
   <refentry id="function.ord">
    <refnamediv>
     <refname>Ord</refname>
- <refpurpose>Return ASCII value of character.</refpurpose>
+ <refpurpose>Return ASCII value of character</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -909,7 +1108,7 @@
   <refentry id="function.parse-str">
    <refnamediv>
     <refname>parse_str</refname>
- <refpurpose>Parses the string into variables.</refpurpose>
+ <refpurpose>Parses the string into variables</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -917,11 +1116,14 @@
      <funcprototype>
       <funcdef>void <function>parse_str</function></funcdef>
       <paramdef>string <parameter>str</parameter></paramdef>
+ <paramdef>array <parameter><optional>arr</optional></parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
      Parses <parameter>str</parameter> as if it were the query string
- passed via an URL and sets variables in the current scope.
+ passed via an URL and sets variables in the current scope. If
+ the second parameter <parameter>arr</parameter> is present,
+ variables are stored in this variable as an array elements instead.
     </para>
     <para>
      <example>
@@ -964,7 +1166,7 @@
   <refentry id="function.printf">
    <refnamediv>
     <refname>printf</refname>
- <refpurpose>Output a formatted string.</refpurpose>
+ <refpurpose>Output a formatted string</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -982,8 +1184,9 @@
      is described in the documentation for <function>sprintf</function>.
     </simpara>
     <simpara>
- See also: <function>print</function>,
- <function>sprintf</function>, and <function>flush</function>.
+ See also: <function>print</function>, <function>sprintf</function>,
+ <function>sscanf</function>, <function>fscanf</function>,
+ and <function>flush</function>.
     </simpara>
    </refsect1>
   </refentry>
@@ -992,7 +1195,7 @@
    <refnamediv>
     <refname>quoted_printable_decode</refname>
     <refpurpose>
- Convert a quoted-printable string to an 8 bit string.
+ Convert a quoted-printable string to an 8 bit string
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -1016,8 +1219,8 @@
 
   <refentry id="function.quotemeta">
    <refnamediv>
- <refname>QuoteMeta</refname>
- <refpurpose>quote meta characters</refpurpose>
+ <refname>quotemeta</refname>
+ <refpurpose>Quote meta characters</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -1042,80 +1245,94 @@
    </refsect1>
   </refentry>
 
- <refentry id="function.rawurldecode">
+ <refentry id="function.rtrim">
    <refnamediv>
- <refname>rawurldecode</refname>
- <refpurpose>Decode URL-encoded strings</refpurpose>
+ <refname>rtrim</refname>
+ <refpurpose>Remove trailing whitespace.</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
     <funcsynopsis>
- <funcprototype>
- <funcdef>string <function>rawurldecode</function></funcdef>
- <paramdef>string <parameter>str</parameter></paramdef>
- </funcprototype>
+ <funcdef>string <function>rtrim</function></funcdef>
+ <paramdef>string <parameter>str</parameter></paramdef>
     </funcsynopsis>
     <para>
- Returns a string in which the sequences with percent
- (<literal>%</literal>) signs followed by two hex digits have been
- replaced with literal characters. For example, the string
- <screen>foo%20bar%40baz</screen> decodes into <screen>foo
- bar <email protected></screen>.
+ Returns the argument string without trailing whitespace,
+ including newlines. This is an alias for <function>chop</function>.
+ <example>
+ <title><function>rtrim</function> example</title>
+ <programlisting role="php">
+$trimmed = rtrim ($line);
+ </programlisting>
+ </example>
     </para>
- <simpara>
- See also <function>rawurlencode</function>.
- </simpara>
+ <para>
+ See also <function>trim</function>, <function>ltrim</function>, and
+ <function>rtrim</function>.
+ </para>
    </refsect1>
   </refentry>
 
- <refentry id="function.rawurlencode">
+ <refentry id="function.sscanf">
    <refnamediv>
- <refname>rawurlencode</refname>
- <refpurpose>URL-encode according to RFC1738.</refpurpose>
+ <refname>sscanf</refname>
+ <refpurpose>Parses input from a string according to a format</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
     <funcsynopsis>
      <funcprototype>
- <funcdef>string <function>rawurlencode</function></funcdef>
+ <funcdef>mixed <function>sscanf</function></funcdef>
       <paramdef>string <parameter>str</parameter></paramdef>
+ <paramdef>string <parameter>format</parameter></paramdef>
+ <paramdef>string
+ <parameter><optional>var1</optional></parameter>...
+ </paramdef>
      </funcprototype>
     </funcsynopsis>
     <para>
- Returns a string in which all non-alphanumeric characters except
- <screen>-_.</screen> have been replaced with a percent
- (<literal>%</literal>) sign followed by two hex digits. This is
- the encoding described in RFC1738 for protecting literal
- characters from being interpreted as special URL delimiters, and
- for protecting URL's from being mangled by transmission media
- with character conversions (like some email systems). For
- example, if you want to include a password in an ftp url:
- <example>
- <title><function>Rawurlencode</function> example 1</title>
- <programlisting role="php">
-echo '&lt;A HREF="ftp://user:', rawurlencode ('foo @+%/'),
- ' <email protected>/x.txt">';
- </programlisting>
- </example>
- Or, if you pass information in a path info component of the url:
- <example>
- <title><function>Rawurlencode</function> example 2</title>
- <programlisting role="php">
-echo '&lt;A HREF="http://x.com/department_list_script/',
- rawurlencode ('sales and marketing/Miami'), '">';
- </programlisting>
- </example>
+ The function <function>sscanf</function> is the input analog of
+ <function>printf</function>. <function>Sscanf</function> reads from
+ the string <parameter>str</parameter> and interprets it according to
+ the specified <parameter>format</parameter>. If only two parameters were
+ passed to this function, the values parsed will be returned as an array.
+ <example>
+ <title><function>Sscanf</function> Example</title>
+ <programlisting role="php">
+// getting the serial number
+$serial = sscanf("SN/2350001","SN/%d");
+// and the date of manufacturing
+$mandate = "January 01 2000";
+list($month, $day, $year) = sscanf($mandate,"%s %d %d");
+echo "Item $serial was manufactured on: $year-".substr($month,0,3)."-$day\n";
+ </programlisting>
+ </example>
+ If optional parameters are passed, the function will return the number of
+ assigned values. The optional parameters must be passed by reference.
+ <example>
+ <title><function>Sscanf</function> - using optional parameters</title>
+ <programlisting role="php">
+// get author info and generate DocBook entry
+$auth = "24\tLewis Carroll";
+$n = sscanf($auth,"%d\t%s %s", &amp;$id, &amp;$first, &amp;$last);
+echo "&lt;author id='$id'&gt;
+ &lt;firstname&gt;$first&lt;/firstname&gt;
+ &lt;surname&gt;$last&lt;/surname&gt;
+&lt;/author&gt;\n";
+ </programlisting>
+ </example>
     </para>
- <simpara>
- See also <function>rawurldecode</function>.
- </simpara>
+ <para>
+ See also: <function>fscanf</function>, <function>printf</function>,
+ and <function>sprintf</function>.
+ </para>
    </refsect1>
   </refentry>
-
+
   <refentry id="function.setlocale">
    <refnamediv>
     <refname>setlocale</refname>
- <refpurpose>Set locale information.</refpurpose>
+ <refpurpose>Set locale information</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -1188,7 +1405,7 @@
    <refnamediv>
     <refname>similar_text</refname>
     <refpurpose>
- Calculate the similarity between two strings.
+ Calculate the similarity between two strings
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -1284,7 +1501,7 @@
      <parameter>format</parameter>.
     </simpara>
     <simpara>
- The format string is composed by zero or more directives:
+ The format string is composed of zero or more directives:
      ordinary characters (excluding <literal>%</literal>) that are
      copied directly to the result, and <emphasis>conversion
      specifications</emphasis>, each of which results in fetching its
@@ -1292,96 +1509,97 @@
      and <function>printf</function>.
     </simpara>
     <para>
- Each conversion specification consists of these elements, in
- order:
+ Each conversion specification consists of a percent sign
+ (<literal>%</literal>), followed by one or more of these
+ elements, in order:
      <orderedlist>
       <listitem>
        <simpara>
- An optional <emphasis>padding specifier</emphasis> that says
- what character will be used for padding the results to the
- right string size. This may be a space character or a
- <literal>0</literal> (zero character). The default is to pad
- with spaces. An alternate padding character can be specified
- by prefixing it with a single quote (<literal>'</literal>).
- See the examples below.
+ An optional <emphasis>padding specifier</emphasis> that says
+ what character will be used for padding the results to the
+ right string size. This may be a space character or a
+ <literal>0</literal> (zero character). The default is to pad
+ with spaces. An alternate padding character can be specified
+ by prefixing it with a single quote (<literal>'</literal>).
+ See the examples below.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
- An optional <emphasis>alignment specifier</emphasis> that says
- if the result should be left-justified or right-justified.
- The default is right-justified; a <literal>-</literal>
- character here will make it left-justified.
+ An optional <emphasis>alignment specifier</emphasis> that says
+ if the result should be left-justified or right-justified.
+ The default is right-justified; a <literal>-</literal>
+ character here will make it left-justified.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
- An optional number, a <emphasis>width specifier</emphasis>
- that says how many characters (minimum) this conversion should
- result in.
+ An optional number, a <emphasis>width specifier</emphasis>
+ that says how many characters (minimum) this conversion should
+ result in.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
- An optional <emphasis>precision specifier</emphasis> that says
- how many decimal digits should be displayed for floating-point
- numbers. This option has no effect for other types than
- double. (Another function useful for formatting numbers is
- <function>number_format</function>.)
+ An optional <emphasis>precision specifier</emphasis> that says
+ how many decimal digits should be displayed for floating-point
+ numbers. This option has no effect for other types than
+ double. (Another function useful for formatting numbers is
+ <function>number_format</function>.)
        </simpara>
       </listitem>
       <listitem>
        <para>
- A <emphasis>type specifier</emphasis> that says what type the
- argument data should be treated as. Possible types:
- <simplelist>
- <member>
- <literal>%</literal> - a literal percent character. No
- argument is required.
- </member>
- <member>
- <literal>b</literal> - the argument is treated as an
- integer, and presented as a binary number.
- </member>
- <member>
- <literal>c</literal> - the argument is treated as an
- integer, and presented as the character with that ASCII
- value.
- </member>
- <member>
- <literal>d</literal> - the argument is treated as an
- integer, and presented as a decimal number.
- </member>
- <member>
- <literal>f</literal> - the argument is treated as a double,
- and presented as a floating-point number.
- </member>
- <member>
- <literal>o</literal> - the argument is treated as an
- integer, and presented as an octal number.
- </member>
- <member>
- <literal>s</literal> - the argument is treated as and
- presented as a string.
- </member>
- <member>
- <literal>x</literal> - the argument is treated as an integer
- and presented as a hexadecimal number (with lowercase
- letters).
- </member>
- <member>
- <literal>X</literal> - the argument is treated as an integer
- and presented as a hexadecimal number (with uppercase
- letters).
- </member>
- </simplelist>
+ A <emphasis>type specifier</emphasis> that says what type the
+ argument data should be treated as. Possible types:
+ <simplelist>
+ <member>
+ <literal>%</literal> - a literal percent character. No
+ argument is required.
+ </member>
+ <member>
+ <literal>b</literal> - the argument is treated as an
+ integer, and presented as a binary number.
+ </member>
+ <member>
+ <literal>c</literal> - the argument is treated as an
+ integer, and presented as the character with that ASCII
+ value.
+ </member>
+ <member>
+ <literal>d</literal> - the argument is treated as an
+ integer, and presented as a decimal number.
+ </member>
+ <member>
+ <literal>f</literal> - the argument is treated as a double,
+ and presented as a floating-point number.
+ </member>
+ <member>
+ <literal>o</literal> - the argument is treated as an
+ integer, and presented as an octal number.
+ </member>
+ <member>
+ <literal>s</literal> - the argument is treated as and
+ presented as a string.
+ </member>
+ <member>
+ <literal>x</literal> - the argument is treated as an integer
+ and presented as a hexadecimal number (with lowercase
+ letters).
+ </member>
+ <member>
+ <literal>X</literal> - the argument is treated as an integer
+ and presented as a hexadecimal number (with uppercase
+ letters).
+ </member>
+ </simplelist>
        </para>
       </listitem>
      </orderedlist>
     </para>
     <simpara>
- See also: <function>printf</function> and
- <function>number_format</function>.
+ See also: <function>printf</function>, <function>sscanf</function>,
+ <function>fscanf</function>, and <function>number_format</function>.
     </simpara>
    </refsect1>
    <refsect1>
@@ -1412,7 +1630,7 @@
    <refnamediv>
     <refname>strcasecmp</refname>
     <refpurpose>
- Binary safe case-insensitive string comparison.
+ Binary safe case-insensitive string comparison
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -1425,8 +1643,8 @@
      </funcprototype>
     </funcsynopsis>
     <para>
- Returns < 0 if <parameter>str1</parameter> is less than
- <parameter>str2</parameter>; > 0 if <parameter>str1</parameter>
+ Returns &lt; 0 if <parameter>str1</parameter> is less than
+ <parameter>str2</parameter>; &gt; 0 if <parameter>str1</parameter>
      is greater than <parameter>str2</parameter>, and 0 if they are
      equal.
     <example>
@@ -1434,7 +1652,7 @@
       <programlisting role="php">
 $var1 = "Hello";
 $var2 = "hello";
-if ( !strcasecmp($var1,$var2) ) {
+if (!strcasecmp ($var1, $var2)) {
     echo '$var1 is equal to $var2 in a case-insensitive string comparison';
 }
       </programlisting>
@@ -1452,7 +1670,7 @@
    <refnamediv>
     <refname>strchr</refname>
     <refpurpose>
- Find the first occurrence of a character.
+ Find the first occurrence of a character
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -1486,8 +1704,8 @@
      </funcprototype>
     </funcsynopsis>
     <simpara>
- Returns < 0 if <parameter>str1</parameter> is less than
- <parameter>str2</parameter>; > 0 if <parameter>str1</parameter>
+ Returns &lt; 0 if <parameter>str1</parameter> is less than
+ <parameter>str2</parameter>; &gt; 0 if <parameter>str1</parameter>
      is greater than <parameter>str2</parameter>, and 0 if they are
      equal.
     </simpara>
@@ -1497,7 +1715,8 @@
     <simpara>
      See also <function>ereg</function>,
      <function>strcasecmp</function>, <function>substr</function>,
- <function>stristr</function>, and <function>strstr</function>.
+ <function>stristr</function>, <function>strncmp</function>,
+ and <function>strstr</function>.
     </simpara>
    </refsect1>
   </refentry>
@@ -1506,7 +1725,7 @@
    <refnamediv>
     <refname>strcspn</refname>
     <refpurpose>
- Find length of initial segment not matching mask.
+ Find length of initial segment not matching mask
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -1566,8 +1785,10 @@
 
   <refentry id="function.stripcslashes">
    <refnamediv>
- <refname>StripCSlashes</refname>
- <refpurpose>un-quote string quoted with addcslashes</refpurpose>
+ <refname>stripcslashes</refname>
+ <refpurpose>
+ Un-quote string quoted with <function>addcslashes</function>
+ </refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -1595,8 +1816,10 @@
 
   <refentry id="function.stripslashes">
    <refnamediv>
- <refname>StripSlashes</refname>
- <refpurpose>Un-quote string quoted with addslashes</refpurpose>
+ <refname>stripslashes</refname>
+ <refpurpose>
+ Un-quote string quoted with <function>addslashes</function>
+ </refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -1621,7 +1844,7 @@
    <refnamediv>
     <refname>stristr</refname>
     <refpurpose>
- Case-insensitive <function>strstr</function>.
+ Case-insensitive <function>strstr</function>
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -1657,7 +1880,7 @@
   <refentry id="function.strlen">
    <refnamediv>
     <refname>strlen</refname>
- <refpurpose>Get string length.</refpurpose>
+ <refpurpose>Get string length</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -1673,11 +1896,233 @@
    </refsect1>
   </refentry>
 
+ <refentry id="function.strnatcmp">
+ <refnamediv>
+ <refname>strnatcmp</refname>
+ <refpurpose>
+ String comparisons using a "natural order" algorithm
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>strnatcmp</function></funcdef>
+ <paramdef>string <parameter>str1</parameter></paramdef>
+ <paramdef>string <parameter>str2</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ This function implements a comparison algorithm that orders
+ alphanumeric strings in the way a human being would, this is
+ described as a "natural ordering". An example of the difference
+ between this algorithm and the regular computer string sorting
+ algorithms (used in <function>strcmp</function>) can be seen
+ below:
+ <informalexample>
+ <programlisting>
+$arr1 = $arr2 = array ("img12.png","img10.png","img2.png","img1.png");
+echo "Standard string comparison\n";
+usort($arr1,"strcmp");
+print_r($arr1);
+echo "\nNatural order string comparison\n";
+usort($arr2,"strnatcmp");
+print_r($arr2);
+ </programlisting>
+ </informalexample>
+ The code above will generate the following output:
+ <informalexample>
+ <programlisting>
+Standard string comparison
+Array
+(
+ [0] =&gt; img1.png
+ [1] =&gt; img10.png
+ [2] =&gt; img12.png
+ [3] =&gt; img2.png
+)
+
+Natural order string comparison
+Array
+(
+ [0] =&gt; img1.png
+ [1] =&gt; img2.png
+ [2] =&gt; img10.png
+ [3] =&gt; img12.png
+)
+ </programlisting>
+ </informalexample>
+ For more infomation see: Martin Pool's <ulink
+ url="&url.strnatcmp;">Natural Order String Comparison</ulink>
+ page.
+ </para>
+ <simpara>
+ Similar to other string comparison functions, this one returns
+ &lt; 0 if <parameter>str1</parameter> is less than
+ <parameter>str2</parameter>; &gt; 0 if <parameter>str1</parameter>
+ is greater than <parameter>str2</parameter>, and 0 if they are
+ equal.
+ </simpara>
+ <simpara>
+ Note that this comparison is case sensitive.
+ </simpara>
+ <simpara>
+ See also <function>ereg</function>,
+ <function>strcasecmp</function>, <function>substr</function>,
+ <function>stristr</function>, <function>strcmp</function>,
+ <function>strncmp</function>, <function>strnatcasecmp</function>,
+ <function>strstr</function>, <function>natsort</function> and
+ <function>natcasesort</function>.
+ </simpara>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.strnatcasecmp">
+ <refnamediv>
+ <refname>strnatcasecmp</refname>
+ <refpurpose>
+ Case insensitive string comparisons using a "natural order" algorithm
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>strnatcasecmp</function></funcdef>
+ <paramdef>string <parameter>str1</parameter></paramdef>
+ <paramdef>string <parameter>str2</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ This function implements a comparison algorithm that orders
+ alphanumeric strings in the way a human being would. The
+ behavior of this function is similar to
+ <function>strnatcmp</function>, except that the comparison is
+ not case sensitive. For more infomation see: Martin Pool's
+ <ulink url="&url.strnatcmp;">Natural Order String
+ Comparison</ulink> page.
+ </para>
+ <simpara>
+ Similar to other string comparison functions, this one returns
+ &lt; 0 if <parameter>str1</parameter> is less than
+ <parameter>str2</parameter>; &gt; 0 if <parameter>str1</parameter>
+ is greater than <parameter>str2</parameter>, and 0 if they are
+ equal.
+ </simpara>
+ <simpara>
+ See also <function>ereg</function>,
+ <function>strcasecmp</function>, <function>substr</function>,
+ <function>stristr</function>, <function>strcmp</function>,
+ <function>strncmp</function>, <function>strnatcmp</function>,
+ and <function>strstr</function>.
+ </simpara>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.strncmp">
+ <refnamediv>
+ <refname>strncmp</refname>
+ <refpurpose>
+ Binary safe string comparison of the first n characters
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>strncmp</function></funcdef>
+ <paramdef>string <parameter>str1</parameter></paramdef>
+ <paramdef>string <parameter>str2</parameter></paramdef>
+ <paramdef>int <parameter>len</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ This function is similar to <function>strcmp</function>, with the
+ difference that you can specify the (upper limit of the) number of
+ characters (<parameter>len</parameter>) from each string to be
+ used in the comparison. If any of the strings is shorter than
+ <parameter>len</parameter>, then the length of that string will be
+ used for the comparison.
+ </para>
+ <simpara>
+ Returns &lt; 0 if <parameter>str1</parameter> is less than
+ <parameter>str2</parameter>; &gt; 0 if <parameter>str1</parameter>
+ is greater than <parameter>str2</parameter>, and 0 if they are
+ equal.
+ </simpara>
+ <simpara>
+ Note that this comparison is case sensitive.
+ </simpara>
+ <simpara>
+ See also <function>ereg</function>,
+ <function>strcasecmp</function>, <function>substr</function>,
+ <function>stristr</function>, <function>strcmp</function>,
+ and <function>strstr</function>.
+ </simpara>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.str-pad">
+ <refnamediv>
+ <refname>str_pad</refname>
+ <refpurpose>Pad a string to a certain length with another string</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>string <function>str_pad</function></funcdef>
+ <paramdef>string <parameter>input</parameter></paramdef>
+ <paramdef>int <parameter>pad_length</parameter></paramdef>
+ <paramdef>string
+ <parameter><optional>pad_string</optional></parameter></paramdef>
+ <paramdef>int
+ <parameter><optional>pad_type</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ This functions pads the <parameter>input</parameter> string on
+ the left, the right, or both sides to the specifed padding
+ length. If the optional argument
+ <parameter>pad_string</parameter> is not supplied, the
+ <parameter>input</parameter> is padded with spaces, otherwise it
+ is padded with characters from <parameter>pad_string</parameter>
+ up to the limit.
+ </para>
+
+ <para>
+ Optional argument <parameter>pad_type</parameter> can be
+ STR_PAD_RIGHT, STR_PAD_LEFT, or STR_PAD_BOTH. If
+ <parameter>pad_type</parameter> is not specified it is assumed to
+ be STR_PAD_RIGHT.
+ </para>
+
+ <para>
+ If the value of <parameter>pad_length</parameter> is negative or
+ less than the length of the input string, no padding takes
+ place.
+ </para>
+
+ <para>
+ <example>
+ <title><function>str_pad</function> example</title>
+ <programlisting role="php">
+$input = "Alien";
+print str_pad($input, 10); // produces "Alien "
+print str_pad($input, 10, "-=", STR_PAD_LEFT); // produces "-=-=-Alien"
+print str_pad($input, 10, "_", STR_PAD_BOTH); // produces "__Alien___"
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+ </refentry>
+
   <refentry id="function.strpos">
    <refnamediv>
     <refname>strpos</refname>
     <refpurpose>
- Find position of first occurrence of a string.
+ Find position of first occurrence of a string
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -1717,7 +2162,7 @@
 
 // in versions older than 4.0b3:
 $pos = strpos ($mystring, "b");
-if (is_string ($pos) && !$pos) {
+if (is_string ($pos) &amp;&amp; !$pos) {
     // not found...
 }
         </programlisting>
@@ -1747,7 +2192,7 @@
    <refnamediv>
     <refname>strrchr</refname>
     <refpurpose>
- Find the last occurrence of a character in a string.
+ Find the last occurrence of a character in a string
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -1797,7 +2242,7 @@
   <refentry id="function.str-repeat">
    <refnamediv>
     <refname>str_repeat</refname>
- <refpurpose>Repeat a string.</refpurpose>
+ <refpurpose>Repeat a string</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -1833,7 +2278,7 @@
   <refentry id="function.strrev">
    <refnamediv>
     <refname>strrev</refname>
- <refpurpose>Reverse a string.</refpurpose>
+ <refpurpose>Reverse a string</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -1853,7 +2298,7 @@
    <refnamediv>
     <refname>strrpos</refname>
     <refpurpose>
- Find position of last occurrence of a char in a string.
+ Find position of last occurrence of a char in a string
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -1892,7 +2337,7 @@
    <refnamediv>
     <refname>strspn</refname>
     <refpurpose>
- Find length of initial segment matching mask.
+ Find length of initial segment matching mask
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -1909,6 +2354,16 @@
      <parameter>str1</parameter> which consists entirely of characters
      in <parameter>str2</parameter>.
     </simpara>
+ <para>
+ <informalexample>
+ <programlisting role="php">
+strspn ("42 is the answer, what is the question ...", "1234567890");
+ </programlisting>
+ <para>
+ will return 2 as result.
+ </para>
+ </informalexample>
+ </para>
     <simpara>
      See also <function>strcspn</function>.
     </simpara>
@@ -1918,7 +2373,7 @@
   <refentry id="function.strstr">
    <refnamediv>
     <refname>strstr</refname>
- <refpurpose>Find first occurrence of a string.</refpurpose>
+ <refpurpose>Find first occurrence of a string</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -1939,12 +2394,22 @@
     <para>
      If <parameter>needle</parameter> is not a string, it is converted
      to an integer and applied as the ordinal value of a character.
+ </para>
+ <para>
+ <note>
+ <para>
+ Note that this function is case-sensitive. For
+ case-insensitive searches, use <function>stristr</function>.
+ </para>
+ </note>
+ </para>
+ <para>
      <example>
       <title><function>Strstr</function> example</title>
       <programlisting role="php">
 $email = 'sterling <email protected>';
 $domain = strstr ($email, '@');
-print $domain; // prints designmultimedia.com
+print $domain; // prints  <email protected>
       </programlisting>
      </example>
     </para>
@@ -2011,7 +2476,7 @@
   <refentry id="function.strtolower">
    <refnamediv>
     <refname>strtolower</refname>
- <refpurpose>Make a string lowercase.</refpurpose>
+ <refpurpose>Make a string lowercase</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -2048,7 +2513,7 @@
   <refentry id="function.strtoupper">
    <refnamediv>
     <refname>strtoupper</refname>
- <refpurpose>Make a string uppercase.</refpurpose>
+ <refpurpose>Make a string uppercase</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -2086,7 +2551,7 @@
    <refnamediv>
     <refname>str_replace</refname>
     <refpurpose>
- Replace all occurrences of needle in haystack with str.
+ Replace all occurrences of needle in haystack with str
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -2132,7 +2597,7 @@
   <refentry id="function.strtr">
    <refnamediv>
     <refname>strtr</refname>
- <refpurpose>Translate certain characters.</refpurpose>
+ <refpurpose>Translate certain characters</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -2174,7 +2639,7 @@
      Examples:
      <informalexample>
       <programlisting role="php">
-$trans = array ("hello" => "hi", "hi" => "hello");
+$trans = array ("hello" =&gt; "hi", "hi" =&gt; "hello");
 echo strtr("hi all, I said hello", $trans) . "\n";
       </programlisting>
      </informalexample>
@@ -2215,9 +2680,13 @@
     </para>
     <para>
      If <parameter>start</parameter> is positive, the returned string
- will start at the <parameter>start</parameter>'th character of
- <parameter>string</parameter>.
- </para>
+ will start at the <parameter>start</parameter>'th position in
+ <parameter>string</parameter>, counting from zero. For instance,
+ in the string '<literal>abcdef</literal>', the character at
+ position <literal>0</literal> is '<literal>a</literal>', the
+ character at position <literal>2</literal> is
+ '<literal>c</literal>', and so forth.
+ </para>
     <para>
      Examples:
      <informalexample>
@@ -2272,10 +2741,41 @@
    </refsect1>
   </refentry>
 
+ <refentry id="function.substr-count">
+ <refnamediv>
+ <refname>substr_count</refname>
+ <refpurpose>Count the number of substring occurrences</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>substr_count</function></funcdef>
+ <paramdef>string <parameter>haystrack</parameter></paramdef>
+ <paramdef>string <parameter>needle</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>substr_count</function> returns the number of times the
+ <parameter>needle</parameter> substring occurs in the
+ <parameter>haystack</parameter> string.
+ </para>
+
+ <para>
+ <example>
+ <title><function>substr_count</function> example</title>
+ <programlisting>
+print substr_count("This is a test", "is"); // prints out 2
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+ </refentry>
+
   <refentry id="function.substr-replace">
    <refnamediv>
     <refname>substr_replace</refname>
- <refpurpose>Replace text within a portion of a string.</refpurpose>
+ <refpurpose>Replace text within a portion of a string</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -2358,7 +2858,7 @@
    <refnamediv>
     <refname>trim</refname>
     <refpurpose>
- Strip whitespace from the beginning and end of a string.
+ Strip whitespace from the beginning and end of a string
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -2376,7 +2876,7 @@
      and a plain space.
     </para>
     <para>
- See also <function>chop</function> and
+ See also <function>chop</function>, <function>rtrim</function> and
      <function>ltrim</function>.
     </para>
    </refsect1>
@@ -2385,9 +2885,7 @@
   <refentry id="function.ucfirst">
    <refnamediv>
     <refname>ucfirst</refname>
- <refpurpose>
- Make a string's first character uppercase.
- </refpurpose>
+ <refpurpose>Make a string's first character uppercase</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -2405,13 +2903,14 @@
      Note that 'alphabetic' is determined by the current locale. For
      instance, in the default "C" locale characters such as umlaut-a
      (ä) will not be converted.
- <example>
- <title><function>ucfirst</function> example</title>
- <programlisting role="php">
+ <example>
+ <title><function>Ucfirst</function> example</title>
+ <programlisting role="php">
 $text = 'mary had a little lamb and she loved it so.';
-$text = ucfirst($text); // $text is now Mary had a little lamb and she loved it so.
- </programlisting>
- </example>
+$text = ucfirst ($text); // $text is now Mary had a little lamb
+ // and she loved it so.
+ </programlisting>
+ </example>
     </para>
     <para>
      See also <function>strtoupper</function> and
@@ -2438,13 +2937,14 @@
     <para>
      Capitalizes the first character of each word in
      <parameter>str</parameter> if that character is alphabetic.
- <example>
- <title><function>ucwords</function> example</title>
- <programlisting role="php">
+ <example>
+ <title><function>ucwords</function> example</title>
+ <programlisting role="php">
 $text = "mary had a little lamb and she loved it so.";
-$text = ucwords($text); // $text is now: Mary Had A Little Lamb And She Loved It So.
- </programlisting>
- </example>
+$text = ucwords($text); // $text is now: Mary Had A Little
+ // Lamb And She Loved It So.
+ </programlisting>
+ </example>
     </para>
     <para>
      See also <function>strtoupper</function>,
@@ -2452,6 +2952,102 @@
     </para>
    </refsect1>
   </refentry>
+
+
+ <refentry id="function.wordwrap">
+ <refnamediv>
+ <refname>wordwrap</refname>
+ <refpurpose>
+ Wraps a string to a given number of characters using a string
+ break character.
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>string <function>wordwrap</function></funcdef>
+ <paramdef>string <parameter>str</parameter></paramdef>
+ <paramdef>int
+ <parameter><optional>width</optional></parameter>
+ </paramdef>
+ <paramdef>string
+ <parameter><optional>break</optional></parameter>
+ </paramdef>
+ <paramdef>int
+ <parameter><optional>cut</optional></parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Wraps the string <parameter>str</parameter> at the column number
+ specified by the (optional) <parameter>width</parameter>
+ parameter. The line is broken using the (optional)
+ <parameter>break</parameter> parameter.
+ </para>
+ <para>
+ <function>wordwrap</function> will automatically wrap at column
+ 75 and break using '\n' (newline) if <parameter>width</parameter>
+ or <parameter>break</parameter> are not given.
+ </para>
+ <para>
+ If the <parameter>cut</parameter> is set to 1, the string is
+ always wrapped at the specified width. So if you have a word
+ that is larger than the given width, it is broken appart.
+ (See second example).
+ </para>
+ <para>
+ <example>
+ <title><function>wordwrap</function> example</title>
+ <programlisting role="php">
+$text = "The quick brown fox jumped over the lazy dog.";
+$newtext = wordwrap( $text, 20 );
+
+echo "$newtext\n";
+ </programlisting>
+ </example>
+ </para>
+ <para>