cvs: phpdoc /en/reference/strings/functions echo.xml explode.xml fprintf.xml get-html-translation-table.xml hebrev.xml hebrevc.xml
html-entity-decode.xml htmlentities.xml implode.xml localeconv.xml ltrim.xml metaphone.xml parse-str.xml printf.xml quoted-printable-decode.xml
quotemeta.xml rtrim.xml sha1.xml similar-text.xml soundex.xml sprintf.xml str-ireplace.xml str-pad.xml str-replace.xml str-rot13.xml str-split.xml
strcasecmp.xml strcmp.xml strcoll.xml strcspn.xml strip-tags.xml stripos.xml stripslashes.xml stristr.xml strnatcasecmp.xml strnatcmp.xml
strncasecmp.xml strncmp.xml strpos.xml strrchr.xml strripos.xml strrpos.xml strspn.xml strstr.xml strtolower.xml strtoupper.xml substr-compare.xml
substr-replace.xml substr.xml ucwords.xml vfprintf.xml vprintf.xml vsprintf.xml

From:	Mehdi Achour	Date:	Fri, 15 Jun 2007 19:01:57 +0000
Subject:	cvs: phpdoc /en/reference/strings/functions echo.xml explode.xml fprintf.xml get-html-translation-table.xml hebrev.xml hebrevc.xml html-entity-decode.xml htmlentities.xml implode.xml localeconv.xml ltrim.xml metaphone.xml parse-str.xml printf.xml quoted-printable-decode.xml quotemeta.xml rtrim.xml sha1.xml similar-text.xml soundex.xml sprintf.xml str-ireplace.xml str-pad.xml str-replace.xml str-rot13.xml str-split.xml strcasecmp.xml strcmp.xml strcoll.xml strcspn.xml strip-tags.xml stripos.xml stripslashes.xml stristr.xml strnatcasecmp.xml strnatcmp.xml strncasecmp.xml strncmp.xml strpos.xml strrchr.xml strripos.xml strrpos.xml strspn.xml strstr.xml strtolower.xml strtoupper.xml substr-compare.xml substr-replace.xml substr.xml ucwords.xml vfprintf.xml vprintf.xml vsprintf.xml
Groups:	php.doc
Request:	Send a blank email to phpdoc+get-969376715@lists.php.net to get a copy of this message

didou Fri Jun 15 19:01:57 2007 UTC Modified files: /phpdoc/en/reference/strings/functions echo.xml explode.xml fprintf.xml get-html-translation-table.xml hebrev.xml hebrevc.xml html-entity-decode.xml htmlentities.xml implode.xml localeconv.xml ltrim.xml metaphone.xml parse-str.xml printf.xml quoted-printable-decode.xml quotemeta.xml rtrim.xml sha1.xml similar-text.xml soundex.xml sprintf.xml str-ireplace.xml str-pad.xml str-replace.xml str-rot13.xml str-split.xml strcasecmp.xml strcmp.xml strcoll.xml strcspn.xml strip-tags.xml stripos.xml stripslashes.xml stristr.xml strnatcasecmp.xml strnatcmp.xml strncasecmp.xml strncmp.xml strpos.xml strrchr.xml strripos.xml strrpos.xml strspn.xml strstr.xml strtolower.xml strtoupper.xml substr-compare.xml substr-replace.xml substr.xml ucwords.xml vfprintf.xml vprintf.xml vsprintf.xml Log: ref.strings (.* => .*): Switch to new doc style

http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/strings/functions/echo.xml?r1=1.18&r2=1.19&diff_format=u Index: phpdoc/en/reference/strings/functions/echo.xml diff -u phpdoc/en/reference/strings/functions/echo.xml:1.18 phpdoc/en/reference/strings/functions/echo.xml:1.19 --- phpdoc/en/reference/strings/functions/echo.xml:1.18 Fri Jun 15 19:01:26 2007 +++ phpdoc/en/reference/strings/functions/echo.xml Fri Jun 15 19:01:56 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> - - + <refentry id="function.echo"> <refnamediv> <refname>echo</refname> <refpurpose>Output one or more strings</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>void</type><methodname>echo</methodname> <methodparam><type>string</type><parameter>arg1</parameter></methodparam> @@ -26,6 +26,54 @@ must not be enclosed within parentheses. </para> <para> + <function>echo</function> also has a shortcut syntax, where you can + immediately follow the opening tag with an equals sign. This short syntax + only works with the <link + linkend="ini.short-open-tag">short_open_tag</link> configuration setting + enabled. + <informalexample> + <programlisting role="php"> +<![CDATA[ +I have <?=$foo?> foo. +]]> + </programlisting> + </informalexample> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>arg1</parameter></term> + <listitem> + <para> + The parameter to output. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.void; + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> <example> <title><function>echo</function> examples</title> <programlisting role="php"> @@ -83,36 +131,30 @@ </programlisting> </example> </para> - <para> - <function>echo</function> also has a shortcut syntax, where you can - immediately follow the opening tag with an equals sign. This short syntax - only works with the <link - linkend="ini.short-open-tag">short_open_tag</link> configuration setting - enabled. - <informalexample> - <programlisting role="php"> -<![CDATA[ -I have <?=$foo?> foo. -]]> - </programlisting> - </informalexample> - </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <simpara> For a short discussion about the differences between <function>print</function> and <function>echo</function>, see this FAQTs Knowledge Base Article: <ulink url="&url.echo-print;">&url.echo-print; </ulink> </simpara> - &note.language-construct; + </refsect1> - <simpara> - See also - <function>print</function>, - <function>printf</function>, and - <function>flush</function>. - </simpara> + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>print</function></member> + <member><function>printf</function></member> + <member><function>flush</function></member> + </simplelist> + </para> </refsect1> + </refentry>  - + <refentry id="function.explode"> <refnamediv> <refname>explode</refname> <refpurpose>Split a string by string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>explode</methodname> <methodparam><type>string</type><parameter>delimiter</parameter></methodparam> @@ -18,22 +18,44 @@ 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>delimiter</parameter>. - If <parameter>limit</parameter> is set, the returned array will - contain a maximum of <parameter>limit</parameter> elements with - the last element containing the rest of - <parameter>string</parameter>. - </para> - <para> - If <parameter>delimiter</parameter> is an empty string (""), - <function>explode</function> will return &false;. If - <parameter>delimiter</parameter> contains a value that is not contained - in <parameter>string</parameter>, then <function>explode</function> will - return an array containing <parameter>string</parameter>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - If the <parameter>limit</parameter> parameter is negative, all components - except the last -<parameter>limit</parameter> are returned. This feature - was added in PHP 5.1.0. + <variablelist> + <varlistentry> + <term><parameter>delimiter</parameter></term> + <listitem> + <para> + The boundary string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>limit</parameter></term> + <listitem> + <para> + If <parameter>limit</parameter> is set, the returned array will contain + a maximum of <parameter>limit</parameter> elements with the last + element containing the rest of <parameter>string</parameter>. + </para> + <para> + If the <parameter>limit</parameter> parameter is negative, all components + except the last -<parameter>limit</parameter> are returned. + </para> + </listitem> + </varlistentry> + </variablelist> </para> <para> Although <function>implode</function> can, for historical reasons, @@ -42,12 +64,51 @@ <parameter>delimiter</parameter> argument comes before the <parameter>string</parameter> argument. </para> - <note> - <para> - The <parameter>limit</parameter> parameter was added in PHP - 4.0.1 - </para> - </note> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + If <parameter>delimiter</parameter> is an empty string (""), + <function>explode</function> will return &false;. If + <parameter>delimiter</parameter> contains a value that is not contained + in <parameter>string</parameter>, then <function>explode</function> will + return an array containing <parameter>string</parameter>. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>5.1.0</entry> + <entry> + Support for negative <parameter>limit</parameter>s was added + </entry> + </row> + <row> + <entry>4.0.1</entry> + <entry> + The <parameter>limit</parameter> parameter was added + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>explode</function> examples</title> @@ -105,17 +166,25 @@ </screen> </example> </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; &note.bin-safe; + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>preg_split</function>, - <function>str_split</function>, - <function>strtok</function>, and - <function>implode</function>. + <simplelist> + <member><function>preg_split</function></member> + <member><function>str_split</function></member> + <member><function>strtok</function></member> + <member><function>implode</function></member> + </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.fprintf"> <refnamediv> <refname>fprintf</refname> <refpurpose>Write a formatted string to a stream</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>fprintf</methodname> <methodparam><type>resource</type><parameter>handle</parameter></methodparam> @@ -14,25 +15,59 @@ <methodparam choice="opt"><type>mixed</type><parameter>args</parameter></methodparam> <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam> </methodsynopsis> - <simpara> - Write a string produced according to <parameter>format</parameter> - to the stream resource specified by <parameter>handle</parameter>. - <parameter>format</parameter> is described in the documentation for - <function>sprintf</function>. - </simpara> - <simpara> + <para> + Write a string produced according to <parameter>format</parameter> to the + stream resource specified by <parameter>handle</parameter>. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>handle</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>format</parameter></term> + <listitem> + <para> + See <function>sprintf</function> for a description of + <parameter>format</parameter>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> Returns the length of the outputted string. - </simpara> - <simpara> - See also: <function>printf</function>, - <function>sprintf</function>, - <function>sscanf</function>, <function>fscanf</function>, - <function>vsprintf</function>, and - <function>number_format</function>. - </simpara> + </para> </refsect1> - <refsect1> - <title>Examples</title> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>fprintf</function>: zero-padded integers</title> @@ -71,6 +106,21 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>printf</function></member> + <member><function>sprintf</function></member> + <member><function>sscanf</function></member> + <member><function>fscanf</function></member> + <member><function>vsprintf</function></member> + <member><function>number_format</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.get-html-translation-table"> <refnamediv> <refname>get_html_translation_table</refname> <refpurpose>Returns the translation table used by <function>htmlspecialchars</function> and <function>htmlentities</function></refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>get_html_translation_table</methodname> <methodparam choice="opt"><type>int</type><parameter>table</parameter></methodparam> @@ -19,18 +19,6 @@ <function>htmlspecialchars</function> and <function>htmlentities</function>. </para> - <para> - There are two new constants - (<constant>HTML_ENTITIES</constant>, - <constant>HTML_SPECIALCHARS</constant>) that allow you to - specify the table you want. Default value for <parameter>table</parameter> - is <constant>HTML_SPECIALCHARS</constant>. And as in the - <function>htmlspecialchars</function> and - <function>htmlentities</function> functions you can optionally - specify the <parameter>quote_style</parameter> you are working with. The default is - <constant>ENT_COMPAT</constant> mode. See the description of these modes in - <function>htmlspecialchars</function>. - </para> <note> <para> Special characters can be encoded in several ways. E.g. @@ -40,6 +28,48 @@ common form for them. </para> </note> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>table</parameter></term> + <listitem> + <para> + There are two new constants (<constant>HTML_ENTITIES</constant>, + <constant>HTML_SPECIALCHARS</constant>) that allow you to specify the + table you want. Default value for <parameter>table</parameter> is + <constant>HTML_SPECIALCHARS</constant>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>quote_style</parameter></term> + <listitem> + <para> + And as in the <function>htmlspecialchars</function> and + <function>htmlentities</function> functions you can optionally specify + the <parameter>quote_style</parameter> you are working with. The + default is <constant>ENT_COMPAT</constant> mode. See the description + of these modes in <function>htmlspecialchars</function>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the translation table as an array. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>Translation Table Example</title> @@ -57,12 +87,19 @@ <literal>"Hallo &amp; &lt;Frau&gt; &amp; Kr&auml;mer".</literal> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>htmlspecialchars</function>, - <function>htmlentities</function>, and - <function>html_entity_decode</function>. + <simplelist> + <member><function>htmlspecialchars</function></member> + <member><function>htmlentities</function></member> + <member><function>html_entity_decode</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.hebrev"> <refnamediv> <refname>hebrev</refname> <refpurpose>Convert logical Hebrew text to visual text</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>hebrev</methodname> <methodparam><type>string</type><parameter>hebrew_text</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>max_chars_per_line</parameter></methodparam> </methodsynopsis> <para> - The optional parameter <parameter>max_chars_per_line</parameter> - indicates maximum number of characters per line that will be - returned. The function tries to avoid breaking words. + Converts logical Hebrew text to visual text. </para> <para> - See also <function>hebrevc</function> + The function tries to avoid breaking words. </para> </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>hebrew_text</parameter></term> + <listitem> + <para> + A Hebrew input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>max_chars_per_line</parameter></term> + <listitem> + <para> + This optional parameter indicates maximum number of characters per + line that will be returned. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the visual string. + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>hebrevc</function></member> + </simplelist> + </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> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>hebrevc</methodname> <methodparam><type>string</type><parameter>hebrew_text</parameter></methodparam> @@ -15,15 +15,54 @@ </methodsynopsis> <para> This function is similar to <function>hebrev</function> with the - difference that it converts newlines (\n) to "<br>\n". The - optional parameter <parameter>max_chars_per_line</parameter> - indicates maximum number of characters per line that will be - returned. The function tries to avoid breaking words. + difference that it converts newlines (\n) to "<br>\n". </para> <para> - See also <function>hebrev</function> + The function tries to avoid breaking words. </para> </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>hebrew_text</parameter></term> + <listitem> + <para> + A Hebrew input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>max_chars_per_line</parameter></term> + <listitem> + <para> + This optional parameter indicates maximum number of characters per + line that will be returned. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the visual string. + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>hebrev</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.html-entity-decode"> <refnamediv> <refname>html_entity_decode</refname> <refpurpose>Convert all HTML entities to their applicable characters</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>html_entity_decode</methodname> <methodparam><type>string</type><parameter>string</parameter></methodparam> @@ -19,49 +19,105 @@ <function>htmlentities</function> in that it converts all HTML entities to their applicable characters from <parameter>string</parameter>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>quote_style</parameter></term> + <listitem> + <para> + The optional second <parameter>quote_style</parameter> parameter lets + you define what will be done with 'single' and "double" quotes. It takes + on one of three constants with the default being + <constant>ENT_COMPAT</constant>: + <table> + <title>Available <parameter>quote_style</parameter> constants</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Constant Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><constant>ENT_COMPAT</constant></entry> + <entry>Will convert double-quotes and leave single-quotes alone.</entry> + </row> + <row> + <entry><constant>ENT_QUOTES</constant></entry> + <entry>Will convert both double and single quotes.</entry> + </row> + <row> + <entry><constant>ENT_NOQUOTES</constant></entry> + <entry>Will leave both double and single quotes unconverted.</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>charset</parameter></term> + <listitem> + <para> + The ISO-8859-1 character set is used as default for the optional third + <parameter>charset</parameter>. This defines the character set used in + conversion. + </para> + &reference.strings.charsets; + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the decoded string. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; <para> - The optional second <parameter>quote_style</parameter> parameter lets - you define what will be done with 'single' and "double" quotes. It takes - on one of three constants with the default being - <constant>ENT_COMPAT</constant>: - <table> - <title>Available <parameter>quote_style</parameter> constants</title> + <informaltable> <tgroup cols="2"> <thead> <row> - <entry>Constant Name</entry> - <entry>Description</entry> + <entry>&Version;</entry> + <entry>&Description;</entry> </row> </thead> <tbody> <row> - <entry><constant>ENT_COMPAT</constant></entry> - <entry>Will convert double-quotes and leave single-quotes alone.</entry> - </row> - <row> - <entry><constant>ENT_QUOTES</constant></entry> - <entry>Will convert both double and single quotes.</entry> - </row> - <row> - <entry><constant>ENT_NOQUOTES</constant></entry> - <entry>Will leave both double and single quotes unconverted.</entry> + <entry>5.0.0</entry> + <entry> + Support for mutli-byte character sets was added. + </entry> </row> </tbody> </tgroup> - </table> - </para> - <para> - The ISO-8859-1 character set is used as default for the optional third - <parameter>charset</parameter>. This defines the character set used in - conversion. + </informaltable> </para> - &reference.strings.charsets; + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> - <note> - <para> - This function doesn't support multi-byte character sets in PHP < 5. - </para> - </note> <example> <title>Decoding HTML entities</title> <programlisting role="php"> @@ -97,26 +153,35 @@ ?> ]]> </programlisting> - </example> + </example> </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <note> + <para> + You might wonder why trim(html_entity_decode('&nbsp;')); doesn't + reduce the string to an empty string, that's because the '&nbsp;' + entity is not ASCII code 32 (which is stripped by + <function>trim</function>) but ASCII code 160 (0xa0) in the default ISO + 8859-1 characterset. + </para> + </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - <note> - <para> - You might wonder why trim(html_entity_decode('&nbsp;')); doesn't - reduce the string to an empty string, that's because the '&nbsp;' - entity is not ASCII code 32 (which is stripped by - <function>trim</function>) but ASCII code 160 (0xa0) in the default ISO - 8859-1 characterset. - </para> - </note> - </para> - <para> - See also <function>htmlentities</function>, - <function>htmlspecialchars</function>, - <function>get_html_translation_table</function>, - and <function>urldecode</function>. + <simplelist> + <member><function>htmlentities</function></member> + <member><function>htmlspecialchars</function></member> + <member><function>get_html_translation_table</function></member> + <member><function>urldecode</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.htmlentities"> <refnamediv> <refname>htmlentities</refname> <refpurpose>Convert all applicable characters to HTML entities</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>htmlentities</methodname> <methodparam><type>string</type><parameter>string</parameter></methodparam> @@ -16,61 +16,134 @@ <methodparam choice="opt"><type>bool</type><parameter>double_encode</parameter></methodparam> </methodsynopsis> <para> - This function is identical to - <function>htmlspecialchars</function> in all ways, except with - <function>htmlentities</function>, all characters which have HTML - character entity equivalents are translated into these entities. + This function is identical to <function>htmlspecialchars</function> in all + ways, except with <function>htmlentities</function>, all characters which + have HTML character entity equivalents are translated into these entities. </para> <para> - Like <function>htmlspecialchars</function>, the optional second - <parameter>quote_style</parameter> parameter lets you define what will - be done with 'single' and "double" quotes. It takes on one of three - constants with the default being <constant>ENT_COMPAT</constant>: - <table> - <title>Available <parameter>quote_style</parameter> constants</title> + If you're wanting to decode instead (the reverse) you can use + <function>html_entity_decode</function>. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>quote_style</parameter></term> + <listitem> + <para> + Like <function>htmlspecialchars</function>, the optional second + <parameter>quote_style</parameter> parameter lets you define what will + be done with 'single' and "double" quotes. It takes on one of three + constants with the default being <constant>ENT_COMPAT</constant>: + <table> + <title>Available <parameter>quote_style</parameter> constants</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Constant Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><constant>ENT_COMPAT</constant></entry> + <entry>Will convert double-quotes and leave single-quotes alone.</entry> + </row> + <row> + <entry><constant>ENT_QUOTES</constant></entry> + <entry>Will convert both double and single quotes.</entry> + </row> + <row> + <entry><constant>ENT_NOQUOTES</constant></entry> + <entry>Will leave both double and single quotes unconverted.</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>charset</parameter></term> + <listitem> + <para> + Like <function>htmlspecialchars</function>, it takes an optional + third argument <parameter>charset</parameter> which defines character + set used in conversion. + Presently, the ISO-8859-1 character set is used as the default. + </para> + &reference.strings.charsets; + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>double_encode</parameter></term> + <listitem> + <para> + When <parameter>double_encode</parameter> is turned off PHP will not + encode existing html entities. The default is to convert everything. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the encoded string. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> <tgroup cols="2"> <thead> <row> - <entry>Constant Name</entry> - <entry>Description</entry> + <entry>&Version;</entry> + <entry>&Description;</entry> </row> </thead> <tbody> <row> - <entry><constant>ENT_COMPAT</constant></entry> - <entry>Will convert double-quotes and leave single-quotes alone.</entry> + <entry>5.2.3</entry> + <entry> + The <parameter>double_quote</parameter> parameter was added. + </entry> </row> <row> - <entry><constant>ENT_QUOTES</constant></entry> - <entry>Will convert both double and single quotes.</entry> + <entry>4.1.0</entry> + <entry> + The <parameter>charset</parameter> parameter was added. + </entry> </row> <row> - <entry><constant>ENT_NOQUOTES</constant></entry> - <entry>Will leave both double and single quotes unconverted.</entry> + <entry>4.0.3</entry> + <entry> + The <parameter>quote</parameter> parameter was added. + </entry> </row> </tbody> </tgroup> - </table> - </para> - <para> - Like <function>htmlspecialchars</function>, it takes an optional - third argument <parameter>charset</parameter> which defines character - set used in conversion. - Presently, the ISO-8859-1 character set is used as the default. - </para> - &reference.strings.charsets; - <para> - When <parameter>double_encode</parameter> is turned off PHP will not - encode existing html entities. The default is to convert everything. - </para> - <para>The <parameter>double_quote</parameter> parameter was added in PHP 5.2.3, - <parameter>charset</parameter> in 4.1.0 and - <parameter>quote</parameter> in PHP 4.0.3. - </para> - <para> - If you're wanting to decode instead (the reverse) you can use - <function>html_entity_decode</function>. + </informaltable> </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>A <function>htmlentities</function> example</title> @@ -89,13 +162,21 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>html_entity_decode</function>, - <function>get_html_translation_table</function>, - <function>htmlspecialchars</function>, <function>nl2br</function>, - and <function>urlencode</function>. + <simplelist> + <member><function>html_entity_decode</function></member> + <member><function>get_html_translation_table</function></member> + <member><function>htmlspecialchars</function></member> + <member><function>nl2br</function></member> + <member><function>urlencode</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.implode"> <refnamediv> <refname>implode</refname> <refpurpose>Join array elements with a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>implode</methodname> <methodparam><type>string</type><parameter>glue</parameter></methodparam> <methodparam><type>array</type><parameter>pieces</parameter></methodparam> </methodsynopsis> <para> - Returns a string containing a string representation of all the - array elements in the same order, with the glue string between - each element. + Join array elements with a <parameter>glue</parameter> string. + </para> + <note> + <para> + <function>implode</function> can, for historical reasons, accept + its parameters in either order. For consistency with + <function>explode</function>, however, it may be less confusing + to use the documented order of arguments. + </para> + </note> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>glue</parameter></term> + <listitem> + <para> + Defaults to an empty string. This is not the preferred usage of + <function>implode</function> as <parameter>glue</parameter> would be + the second parameter and thus, the bad prototype would be used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>pieces</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns a string containing a string representation of all the array + elements in the same order, with the glue string between each element. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.3.0</entry> + <entry> + The <parameter>glue</parameter> parameter became optional. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> <example> <title><function>implode</function> example</title> <programlisting role="php"> @@ -31,31 +100,25 @@ ?> ]]> </programlisting> - </example> + </example> </para> - <note> - <para> - <function>implode</function> can, for historical reasons, accept - its parameters in either order. For consistency with - <function>explode</function>, however, it may be less confusing - to use the documented order of arguments. - </para> - </note> - <note> - <para> - As of PHP 4.3.0, the glue parameter of <function>implode</function> is - optional and defaults to the empty string(''). This is not the preferred - usage of <function>implode</function>. We recommend to always use two - parameters for compatibility with older versions. - </para> - </note> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; &note.bin-safe; + </refsect1> - <simpara> - See also <function>explode</function>, and <function>split</function>. - </simpara> + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>explode</function></member> + <member><function>split</function></member> + </simplelist> + </para> </refsect1> + </refentry>  - + <refentry id="function.localeconv"> <refnamediv> <refname>localeconv</refname> <refpurpose>Get numeric formatting information</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>localeconv</methodname> <void/> @@ -16,6 +16,10 @@ Returns an associative array containing localized numeric and monetary formatting information. </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> <function>localeconv</function> returns data based upon the current locale as set by <function>setlocale</function>. The associative array that is @@ -134,7 +138,7 @@ </informaltable> </para> <para> - The <literal>n_sign_posn</literal>, and <literal>n_sign_posn</literal> contain a string + The <literal>p_sign_posn</literal>, and <literal>n_sign_posn</literal> contain a string of formatting options. Each number representing one of the above listed conditions. </para> <para> @@ -146,9 +150,14 @@ no further grouping is done. If an array element is equal to 0, the previous element should be used. </para> - <example> - <title><function>localeconv</function> example</title> - <programlisting role="php"> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>localeconv</function> example</title> + <programlisting role="php"> <![CDATA[ <?php if (false !== setlocale(LC_ALL, 'nl_NL.UTF-8@euro')) { @@ -157,9 +166,9 @@ } ?> ]]> - </programlisting> - &example.outputs; - <screen> + </programlisting> + &example.outputs; + <screen> <![CDATA[ Array ( @@ -191,12 +200,20 @@ ) ]]> - </screen> - </example> + </screen> + </example> + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>setlocale</function>. + <simplelist> + <member><function>setlocale</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.ltrim"> <refnamediv> <refname>ltrim</refname> <refpurpose>Strip whitespace (or other characters) from the beginning of a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>ltrim</methodname> <methodparam><type>string</type><parameter>str</parameter></methodparam> <methodparam choice="opt"><type>string</type><parameter>charlist</parameter></methodparam> </methodsynopsis> - <note> - <simpara> - The second parameter was added in PHP 4.1.0 - </simpara> - </note> + <para> + Strip whitespace (or other characters) from the beginning of a string. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>charlist</parameter></term> + <listitem> + <para> + You can also specify the characters you want to strip, by means of the + <parameter>charlist</parameter> parameter. + Simply list all characters that you want to be stripped. With + <literal>..</literal> you can specify a range of characters. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> This function returns a string with whitespace stripped from the beginning of <parameter>str</parameter>. @@ -63,15 +92,38 @@ </listitem> </itemizedlist> </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.1.0</entry> + <entry> + The <parameter>charlist</parameter> parameter was added. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> - You can also specify the characters you want to strip, by means - of the <parameter>charlist</parameter> parameter. - Simply list all characters that you want to be stripped. With - <literal>..</literal> you can specify a range of characters. - </para> - <example> - <title>Usage example of <function>ltrim</function></title> - <programlisting role="php"> + <example> + <title>Usage example of <function>ltrim</function></title> + <programlisting role="php"> <![CDATA[ <?php @@ -99,9 +151,9 @@ ?> ]]> - </programlisting> - &example.outputs; - <screen> + </programlisting> + &example.outputs; + <screen> <![CDATA[ string(32) " These are a few words :) ... " string(16) " Example string @@ -114,12 +166,21 @@ string(15) "Example string " ]]> - </screen> - </example> + </screen> + </example> + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>trim</function> and <function>rtrim</function>. + <simplelist> + <member><function>trim</function></member> + <member><function>rtrim</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.metaphone"> <refnamediv> <refname>metaphone</refname> <refpurpose>Calculate the metaphone key of a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>metaphone</methodname> <methodparam><type>string</type><parameter>str</parameter></methodparam> @@ -17,13 +17,11 @@ Calculates the metaphone key of <parameter>str</parameter>. </para> <para> - Similar to <function>soundex</function> metaphone creates the - same key for similar sounding words. It's more accurate than - <function>soundex</function> as it knows the basic rules of - English pronunciation. The metaphone generated keys are of - variable length. + Similar to <function>soundex</function> metaphone creates the same key for + similar sounding words. It's more accurate than + <function>soundex</function> as it knows the basic rules of English + pronunciation. The metaphone generated keys are of variable length. </para> -  <para> Metaphone was developed by Lawrence Philips <lphilips at verity dot com>. It is described in ["Practical @@ -31,6 +29,37 @@ 1995]. </para> </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>phones</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the metaphone key as a string. + </para> + </refsect1> + </refentry>  - + <refentry id="function.parse-str"> <refnamediv> <refname>parse_str</refname> <refpurpose>Parses the string into variables</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>void</type><methodname>parse_str</methodname> <methodparam><type>string</type><parameter>str</parameter></methodparam> @@ -15,17 +15,10 @@ </methodsynopsis> <para> Parses <parameter>str</parameter> as if it were the query string - passed via a URL and sets variables in the current scope. If - the second parameter <parameter>arr</parameter> is present, - variables are stored in this variable as array elements instead. + passed via a URL and sets variables in the current scope. </para> <note> <para> - Support for the optional second parameter was added in PHP 4.0.3. - </para> - </note> - <note> - <para> To get the current <emphasis>QUERY_STRING</emphasis>, you may use the variable <link linkend="reserved.variables.server">$_SERVER['QUERY_STRING']</link>. Also, you may want to read the section on @@ -40,6 +33,66 @@ <literal>$_POST</literal>, etc. variables. </para> </note> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>arr</parameter></term> + <listitem> + <para> + If the second parameter <parameter>arr</parameter> is present, + variables are stored in this variable as array elements instead. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.void; + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.0.3</entry> + <entry> + The <parameter>arr</parameter> parameter was added + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>Using <function>parse_str</function></title> @@ -62,12 +115,21 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>parse_url</function>, <function>pathinfo</function>, - <function>http_build_query</function>, - <function>get_magic_quotes_gpc</function>, and <function>urldecode</function>. + <simplelist> + <member><function>parse_url</function></member> + <member><function>pathinfo</function></member> + <member><function>http_build_query</function></member> + <member><function>get_magic_quotes_gpc</function></member> + <member><function>urldecode</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.printf"> <refnamediv> <refname>printf</refname> <refpurpose>Output a formatted string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>printf</methodname> <methodparam><type>string</type><parameter>format</parameter></methodparam> @@ -15,22 +15,62 @@ <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam> </methodsynopsis> <simpara> - Produces output according to <parameter>format</parameter>, which - is described in the documentation for <function>sprintf</function>. + Produces output according to <parameter>format</parameter>. </simpara> - <simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>format</parameter></term> + <listitem> + <para> + See <function>sprintf</function> for a description of + <parameter>format</parameter>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> Returns the length of the outputted string. - </simpara> - <simpara> - See also - <function>print</function>, - <function>sprintf</function>, - <function>vprintf</function>, - <function>sscanf</function>, - <function>fscanf</function>, and - <function>flush</function>. - </simpara> + </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>print</function></member> + <member><function>sprintf</function></member> + <member><function>vprintf</function></member> + <member><function>sscanf</function></member> + <member><function>fscanf</function></member> + <member><function>flush</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.quoted-printable-decode"> <refnamediv> <refname>quoted_printable_decode</refname> <refpurpose>Convert a quoted-printable string to an 8 bit string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>quoted_printable_decode</methodname> <methodparam><type>string</type><parameter>str</parameter></methodparam> </methodsynopsis> - <simpara> - This function returns an 8-bit binary string corresponding to the - decoded quoted printable string (according to - <ulink url="&url.rfc;2045">RFC2045</ulink>, section 6.7, not - <ulink url="&url.rfc;2821">RFC2821</ulink>, section 4.5.2, so additional - periods are not stripped from the beginning of line). - This function is similar to - <function>imap_qprint</function>, except this one does not - require the IMAP module to work. - </simpara> + <para> + This function returns an 8-bit binary string corresponding to the decoded + quoted printable string (according to <ulink + url="&url.rfc;2045">RFC2045</ulink>, section 6.7, not <ulink + url="&url.rfc;2821">RFC2821</ulink>, section 4.5.2, so additional periods + are not stripped from the beginning of line). + </para> + <para> + This function is similar to <function>imap_qprint</function>, except this + one does not require the IMAP module to work. + </para> </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the 8-bit binary string. + </para> + </refsect1> + </refentry>  - + <refentry id="function.quotemeta"> <refnamediv> <refname>quotemeta</refname> <refpurpose>Quote meta characters</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>quotemeta</methodname> <methodparam><type>string</type><parameter>str</parameter></methodparam> </methodsynopsis> <para> - Returns a version of str with a backslash character - (<literal>\</literal>) before every character that is among - these: <screen>. \ + * ? [ ^ ] ( $ )</screen> - </para> - - &note.bin-safe; - - <simpara> - See also <function>addslashes</function>, - <function>addcslashes</function>, - <function>htmlentities</function>, - <function>htmlspecialchars</function>, - <function>nl2br</function>, - <function>stripslashes</function>, and - <function>stripcslashes</function>. - </simpara> - </refsect1> - </refentry> + Returns a version of str with a backslash character (<literal>\</literal>) + before every character that is among these: + <screen>. \ + * ? [ ^ ] ( $ )</screen> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the string with meta characters quoted. + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + &note.bin-safe; + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>addslashes</function></member> + <member><function>addcslashes</function></member> + <member><function>htmlentities</function></member> + <member><function>htmlspecialchars</function></member> + <member><function>nl2br</function></member> + <member><function>stripslashes</function></member> + <member><function>stripcslashes</function></member> + </simplelist> + </para> + </refsect1> + +</refentry>  - + <refentry id="function.rtrim"> <refnamediv> <refname>rtrim</refname> <refpurpose>Strip whitespace (or other characters) from the end of a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>rtrim</methodname> <methodparam><type>string</type><parameter>str</parameter></methodparam> <methodparam choice="opt"><type>string</type><parameter>charlist</parameter></methodparam> </methodsynopsis> - <note> - <simpara> - The second parameter was added in PHP 4.1.0 - </simpara> - </note> <para> This function returns a string with whitespace stripped from the end of <parameter>str</parameter>. + </para> + <para> Without the second parameter, <function>rtrim</function> will strip these characters:  @@ -63,15 +60,72 @@ </listitem> </itemizedlist> </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>charlist</parameter></term> + <listitem> + <para> + You can also specify the characters you want to strip, by means + of the <parameter>charlist</parameter> parameter. + Simply list all characters that you want to be stripped. With + <literal>..</literal> you can specify a range of characters. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the modified string. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.1.0</entry> + <entry> + The <parameter>charlist</parameter> parameter was added. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> - You can also specify the characters you want to strip, by means - of the <parameter>charlist</parameter> parameter. - Simply list all characters that you want to be stripped. With - <literal>..</literal> you can specify a range of characters. - </para> - <example> - <title>Usage example of <function>rtrim</function></title> - <programlisting role="php"> + <example> + <title>Usage example of <function>rtrim</function></title> + <programlisting role="php"> <![CDATA[ <?php @@ -98,9 +152,9 @@ ?> ]]> - </programlisting> - &example.outputs; - <screen> + </programlisting> + &example.outputs; + <screen> <![CDATA[ string(32) " These are a few words :) ... " string(16) " Example string @@ -112,12 +166,21 @@ string(9) "Hello Wor" string(15) " Example string" ]]> - </screen> - </example> + </screen> + </example> + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>trim</function> and <function>ltrim</function>. + <simplelist> + <member><function>trim</function></member> + <member><function>ltrim</function></member> + </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.sha1"> <refnamediv> <refname>sha1</refname> <refpurpose>Calculate the sha1 hash of a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>sha1</methodname> <methodparam><type>string</type><parameter>str</parameter></methodparam> @@ -15,17 +16,69 @@ <simpara> Calculates the sha1 hash of <parameter>str</parameter> using the <ulink url="&url.rfc;3174">US Secure Hash Algorithm 1</ulink>, - and returns that hash. The hash is a 40-character hexadecimal number. - If the optional <parameter>raw_output</parameter> is set to &true;, - then the sha1 digest is instead returned in raw binary format with a - length of 20. </simpara> - <note> - <simpara> - The optional <parameter>raw_output</parameter> parameter was added in - PHP 5.0.0 and defaults to &false; - </simpara> - </note> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>raw_output</parameter></term> + <listitem> + <para> + If the optional <parameter>raw_output</parameter> is set to &true;, + then the sha1 digest is instead returned in raw binary format with a + length of 20, otherwise the returned value is a 40-character + hexadecimal number. Defaults to &false;. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the sha1 hash as a string. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>5.0.0</entry> + <entry> + The <parameter>raw_output</parameter> parameter was added. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>A <function>sha1</function> example</title> @@ -43,12 +96,19 @@ </programlisting> </example> </para> - <simpara> - See also <function>sha1_file</function>, - <function>crc32</function>, and - <function>md5</function> - </simpara> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>sha1_file</function></member> + <member><function>crc32</function></member> + <member><function>md5</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.similar-text"> <refnamediv> <refname>similar_text</refname> <refpurpose>Calculate the similarity between two strings</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>similar_text</methodname> <methodparam><type>string</type><parameter>first</parameter></methodparam> @@ -15,23 +15,65 @@ <methodparam choice="opt"><type>float</type><parameter role="reference">percent</parameter></methodparam> </methodsynopsis> <para> - This calculates the similarity between two strings as described - in Oliver [1993]. Note that this implementation does not use a - stack as in Oliver's pseudo code, but recursive calls which may - or may not speed up the whole process. Note also that the - complexity of this algorithm is O(N**3) where N is the length of - the longest string. + This calculates the similarity between two strings as described in Oliver + [1993]. Note that this implementation does not use a stack as in Oliver's + pseudo code, but recursive calls which may or may not speed up the whole + process. Note also that the complexity of this algorithm is O(N**3) where + N is the length of the longest string. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>first</parameter></term> + <listitem> + <para> + The first string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>second</parameter></term> + <listitem> + <para> + The second string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>percent</parameter></term> + <listitem> + <para> + By passing a reference as third argument, + <function>similar_text</function> will calculate the similarity in + percent for you. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - By passing a reference as third argument, - <function>similar_text</function> will calculate the similarity - in percent for you. It returns the number of matching chars in - both strings. + Returns the number of matching chars in both strings. </para> - <simpara> - See also <function>levenshtein</function>, and <function>soundex</function>. - </simpara> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>levenshtein</function></member> + <member><function>soundex</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.soundex"> <refnamediv> <refname>soundex</refname> <refpurpose>Calculate the soundex key of a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>soundex</methodname> <methodparam><type>string</type><parameter>str</parameter></methodparam> @@ -27,6 +27,33 @@ in "The Art Of Computer Programming, vol. 3: Sorting And Searching", Addison-Wesley (1973), pp. 391-392. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the soundex key as a string. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>Soundex Examples</title> @@ -44,13 +71,19 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>levenshtein</function>, - <function>metaphone</function>, and - <function>similar_text</function>. + <simplelist> + <member><function>levenshtein</function></member> + <member><function>metaphone</function></member> + <member><function>similar_text</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.sprintf"> <refnamediv> <refname>sprintf</refname> <refpurpose>Return a formatted string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>sprintf</methodname> <methodparam><type>string</type><parameter>format</parameter></methodparam> <methodparam choice="opt"><type>mixed</type><parameter>args</parameter></methodparam> <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam> </methodsynopsis> - <simpara> + <para> Returns a string produced according to the formatting string <parameter>format</parameter>. - </simpara> - <simpara> - 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 - own parameter. This applies to both <function>sprintf</function> - and <function>printf</function>. - </simpara> - <para> - 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>sign specifier</emphasis> that forces a sign - (- or +) to be used on a number. By default, only the - sign is used - on a number if it's negative. This specifier forces positive numbers - to have the + sign attached as well, and was added in PHP 4.3.0. - </simpara> - </listitem> - <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. - </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. - </simpara> - </listitem> - <listitem> - <simpara> - 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. When using this specifier on a string, it acts as a - cutoff point, setting a maximum character limit to the string. - </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 (signed) decimal number. - </member> - <member> - <literal>e</literal> - the argument is treated as scientific - notation (e.g. 1.2e+2). - The precision specifier stands for the number of digits after the - decimal point since PHP 5.2.1. In earlier versions, it was taken as - number of significant digits (one less). - </member> - <member> - <literal>u</literal> - the argument is treated as an - integer, and presented as an unsigned decimal number. - </member> - <member> - <literal>f</literal> - the argument is treated as a - float, and presented as a floating-point number (locale aware). - </member> - <member> - <literal>F</literal> - the argument is treated as a - float, and presented as a floating-point number (non-locale aware). - Available since PHP 4.3.10 and PHP 5.0.3. - </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> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - As of PHP 4.0.6 the format string supports argument - numbering/swapping. Here is an example: - <example> - <title>Argument swapping</title> - <programlisting role="php"> + <variablelist> + <varlistentry> + <term><parameter>format</parameter></term> + <listitem> + <para> + 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 + own parameter. This applies to both <function>sprintf</function> + and <function>printf</function>. + </para> + <para> + 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>sign specifier</emphasis> that forces a sign + (- or +) to be used on a number. By default, only the - sign is used + on a number if it's negative. This specifier forces positive numbers + to have the + sign attached as well, and was added in PHP 4.3.0. + </simpara> + </listitem> + <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. + </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. + </simpara> + </listitem> + <listitem> + <simpara> + 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. When using this specifier on a string, it acts as a + cutoff point, setting a maximum character limit to the string. + </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 (signed) decimal number. + </member> + <member> + <literal>e</literal> - the argument is treated as scientific + notation (e.g. 1.2e+2). + The precision specifier stands for the number of digits after the + decimal point since PHP 5.2.1. In earlier versions, it was taken as + number of significant digits (one less). + </member> + <member> + <literal>u</literal> - the argument is treated as an + integer, and presented as an unsigned decimal number. + </member> + <member> + <literal>f</literal> - the argument is treated as a + float, and presented as a floating-point number (locale aware). + </member> + <member> + <literal>F</literal> - the argument is treated as a + float, and presented as a floating-point number (non-locale aware). + Available since PHP 4.3.10 and PHP 5.0.3. + </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> + <para> + The format string supports argument numbering/swapping. Here is an + example: + <example> + <title>Argument swapping</title> + <programlisting role="php"> <![CDATA[ <?php $format = 'There are %d monkeys in the %s'; printf($format, $num, $location); ?> ]]> - </programlisting> - </example> - This might output, "There are 5 monkeys in the tree". But - imagine we are creating a format string in a separate file, - commonly because we would like to internationalize it and we - rewrite it as: - <example> - <title>Argument swapping</title> - <programlisting role="php"> + </programlisting> + </example> + This might output, "There are 5 monkeys in the tree". But + imagine we are creating a format string in a separate file, + commonly because we would like to internationalize it and we + rewrite it as: + <example> + <title>Argument swapping</title> + <programlisting role="php"> <![CDATA[ <?php $format = 'The %s contains %d monkeys'; printf($format, $num, $location); ?> ]]> - </programlisting> - </example> - We now have a problem. The order of the placeholders in the - format string does not match the order of the arguments in the - code. We would like to leave the code as is and simply indicate - in the format string which arguments the placeholders refer to. - We would write the format string like this instead: - <example> - <title>Argument swapping</title> - <programlisting role="php"> + </programlisting> + </example> + We now have a problem. The order of the placeholders in the + format string does not match the order of the arguments in the + code. We would like to leave the code as is and simply indicate + in the format string which arguments the placeholders refer to. + We would write the format string like this instead: + <example> + <title>Argument swapping</title> + <programlisting role="php"> <![CDATA[ <?php $format = 'The %2$s contains %1$d monkeys'; printf($format, $num, $location); ?> ]]> - </programlisting> - </example> - An added benefit here is that you can repeat the placeholders without - adding more arguments in the code. For example: - <example> - <title>Argument swapping</title> - <programlisting role="php"> + </programlisting> + </example> + An added benefit here is that you can repeat the placeholders without + adding more arguments in the code. For example: + <example> + <title>Argument swapping</title> + <programlisting role="php"> <![CDATA[ <?php $format = 'The %2$s contains %1$d monkeys. @@ -195,18 +204,63 @@ printf($format, $num, $location); ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns a string produced according to the formatting string + <parameter>format</parameter>. </para> - <simpara> - See also <function>printf</function>, - <function>sscanf</function>, <function>fscanf</function>, - <function>vsprintf</function>, and - <function>number_format</function>. - </simpara> </refsect1> - <refsect1> - <title>Examples</title> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.0.6</entry> + <entry> + Support for argument numbering/swapping was added + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <example> <title><function>printf</function>: various examples</title> <programlisting role="php"> @@ -234,9 +288,7 @@ ?> ]]> </programlisting> - <para> - The printout of this program would be: - </para> + &example.outputs; <screen> <![CDATA[ %b = '10100111101010011010101101' @@ -272,9 +324,7 @@ ?> ]]> </programlisting> - <para> - The printout of this program would be: - </para> + &example.outputs; <screen> <![CDATA[ [monkey] @@ -324,6 +374,20 @@ </programlisting> </example> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>printf</function></member> + <member><function>sscanf</function></member> + <member><function>fscanf</function></member> + <member><function>vsprintf</function></member> + <member><function>number_format</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.str-ireplace"> <refnamediv> <refname>str_ireplace</refname> <refpurpose>Case-insensitive version of <function>str_replace</function>.</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>mixed</type><methodname>str_ireplace</methodname> <methodparam><type>mixed</type><parameter>search</parameter></methodparam> @@ -23,31 +23,99 @@ use this function instead of <function>eregi_replace</function> or <function>preg_replace</function> with the <literal>i</literal> modifier. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - If <parameter>subject</parameter> is an array, then the search - and replace is performed with every entry of - <parameter>subject</parameter>, and the return value is an array - as well. - </para> - <para> - If <parameter>search</parameter> and - <parameter>replace</parameter> are arrays, then - <function>str_ireplace</function> takes a value from each array - and uses them to do search and replace on - <parameter>subject</parameter>. If - <parameter>replace</parameter> has fewer values than - <parameter>search</parameter>, then an empty string is used for - the rest of replacement values. If <parameter>search</parameter> - is an array and <parameter>replace</parameter> is a string; then - this replacement string is used for every value of + <variablelist> + <varlistentry> + <term><parameter>search</parameter></term> + <listitem> + <note> + <para> + Every replacement with <parameter>search</parameter> array is + performed on the result of previous replacement. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>replace</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>subject</parameter></term> + <listitem> + <para> + If <parameter>subject</parameter> is an array, then the search and + replace is performed with every entry of + <parameter>subject</parameter>, and the return value is an array as + well. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>count</parameter></term> + <listitem> + <para> + The number of matched and replaced <parameter>needles</parameter> will + be returned in <parameter>count</parameter> which is passed by + reference. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + If <parameter>search</parameter> and <parameter>replace</parameter> are + arrays, then <function>str_ireplace</function> takes a value from each + array and uses them to do search and replace on + <parameter>subject</parameter>. If <parameter>replace</parameter> has + fewer values than <parameter>search</parameter>, then an empty string is + used for the rest of replacement values. If <parameter>search</parameter> + is an array and <parameter>replace</parameter> is a string; then this + replacement string is used for every value of <parameter>search</parameter>. </para> - <note> - <para> - Every replacement with <parameter>search</parameter> array is performed - on the result of previous replacement. - </para> - </note> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns a string or an array of replacements. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>5.0.0</entry> + <entry> + The <parameter>count</parameter> parameter was added. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>str_ireplace</function> example</title> @@ -60,24 +128,28 @@ </programlisting> </example> </para> - <para> - This function is binary safe. - </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> - <simpara> - As of PHP 5.0.0 the number of matched and replaced - <parameter>needles</parameter> will be returned in - <parameter>count</parameter> which is passed by reference. - Prior to PHP 5.0.0 this parameter is not available. - </simpara> + <para> + This function is binary safe. + </para> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also: - <function>str_replace</function>, - <function>preg_replace</function>, and - <function>strtr</function>. + <simplelist> + <member><function>str_replace</function></member> + <member><function>preg_replace</function></member> + <member><function>strtr</function></member> + </simplelist> </para> </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> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>str_pad</methodname> <methodparam><type>string</type><parameter>input</parameter></methodparam> @@ -24,17 +24,67 @@ is padded with characters from <parameter>pad_string</parameter> up to the limit. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - Optional argument <parameter>pad_type</parameter> can be - <constant>STR_PAD_RIGHT</constant>, <constant>STR_PAD_LEFT</constant>, - or <constant>STR_PAD_BOTH</constant>. If - <parameter>pad_type</parameter> is not specified it is assumed to - be <constant>STR_PAD_RIGHT</constant>. + <variablelist> + <varlistentry> + <term><parameter>input</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>pad_length</parameter></term> + <listitem> + <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> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>pad_string</parameter></term> + <listitem> + <note> + <para> + The <parameter>pad_string</parameter> may be truncated if the + required number of padding characters can't be evenly divided by the + <parameter>pad_string</parameter>'s length. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>pad_type</parameter></term> + <listitem> + <para> + Optional argument <parameter>pad_type</parameter> can be + <constant>STR_PAD_RIGHT</constant>, <constant>STR_PAD_LEFT</constant>, + or <constant>STR_PAD_BOTH</constant>. If + <parameter>pad_type</parameter> is not specified it is assumed to be + <constant>STR_PAD_RIGHT</constant>. + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - If the value of <parameter>pad_length</parameter> is negative or - less than the length of the input string, no padding takes place. + Returns the padded string. </para> + </refsect1> + + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>str_pad</function> example</title> @@ -51,14 +101,8 @@ </programlisting> </example> </para> - <note> - <para> - The <parameter>pad_string</parameter> may be truncated if the - required number of padding characters can't be evenly divided by - the <parameter>pad_string</parameter>'s length. - </para> - </note> </refsect1> + </refentry>  - + <refentry id="function.str-replace"> <refnamediv> <refname>str_replace</refname> <refpurpose>Replace all occurrences of the search string with the replacement string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>mixed</type><methodname>str_replace</methodname> <methodparam><type>mixed</type><parameter>search</parameter></methodparam> @@ -18,52 +18,126 @@ <para> This function returns a string or an array with all occurrences of <parameter>search</parameter> in <parameter>subject</parameter> - replaced with the given <parameter>replace</parameter> value. If you - don't need fancy replacing rules (like regular expressions), you should - always use this function instead of <function>ereg_replace</function> or - <function>preg_replace</function>. - </para> - <para> - As of PHP 4.0.5, every parameter in <function>str_replace</function> - can be an <type>array</type>. - </para> - <warning> - <simpara> - In PHP versions prior to 4.3.3 a bug existed when using arrays as - both <parameter>search</parameter> and <parameter>replace</parameter> - parameters which caused empty <parameter>search</parameter> indexes - to be skipped without advancing the internal pointer on the - <parameter>replace</parameter> array. This has been corrected in - PHP 4.3.3, any scripts which relied on this bug - should remove empty search values prior to calling this function in - order to mimick the original behavior. - </simpara> - </warning> - <para> - If <parameter>subject</parameter> is an array, then the search - and replace is performed with every entry of - <parameter>subject</parameter>, and the return value is an array - as well. - </para> - <para> - If <parameter>search</parameter> and - <parameter>replace</parameter> are arrays, then - <function>str_replace</function> takes a value from each array - and uses them to do search and replace on - <parameter>subject</parameter>. If - <parameter>replace</parameter> has fewer values than - <parameter>search</parameter>, then an empty string is used for - the rest of replacement values. If <parameter>search</parameter> - is an array and <parameter>replace</parameter> is a string, then - this replacement string is used for every value of - <parameter>search</parameter>. The converse would not make sense, - though. + replaced with the given <parameter>replace</parameter> value. + </para> + <para> + If you don't need fancy replacing rules (like regular expressions), you + should always use this function instead of <function>ereg_replace</function> + or <function>preg_replace</function>. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + If <parameter>search</parameter> and <parameter>replace</parameter> are + arrays, then <function>str_replace</function> takes a value from each + array and uses them to do search and replace on + <parameter>subject</parameter>. If <parameter>replace</parameter> has + fewer values than <parameter>search</parameter>, then an empty string is + used for the rest of replacement values. If <parameter>search</parameter> + is an array and <parameter>replace</parameter> is a string, then this + replacement string is used for every value of + <parameter>search</parameter>. The converse would not make sense, though. </para> <para> If <parameter>search</parameter> or <parameter>replace</parameter> are arrays, their elements are processed first to last. </para> <para> + <variablelist> + <varlistentry> + <term><parameter>search</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>replace</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>subject</parameter></term> + <listitem> + <para> + If <parameter>subject</parameter> is an array, then the search and + replace is performed with every entry of + <parameter>subject</parameter>, and the return value is an array as + well. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>count</parameter></term> + <listitem> + <note> + <simpara> + If passed, this will hold the number of matched and replaced needles. + </simpara> + </note> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + This function returns a string or an array with the replaced values. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>5.0.0</entry> + <entry> + The <parameter>count</parameter> parameter was added. + </entry> + </row> + <row> + <entry>4.3.3</entry> + <entry> + The behaviour of this function changed. In older versions a bug + existed when using arrays as both <parameter>search</parameter> and + <parameter>replace</parameter> parameters which caused empty + <parameter>search</parameter> indexes to be skipped without advancing + the internal pointer on the <parameter>replace</parameter> array. + This has been corrected in PHP 4.3.3, any scripts which relied on + this bug should remove empty search values prior to calling this + function in order to mimick the original behavior. + </entry> + </row> + <row> + <entry>4.0.5</entry> + <entry> + Most parameters can now be an <type>array</type>. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> <example> <title><function>str_replace</function> examples</title> <programlisting role="php"> @@ -105,32 +179,31 @@ </programlisting> </example> </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; &note.bin-safe; - <note> <para> This function is case-sensitive. Use <function>str_ireplace</function> for case-insensitive replace. </para> </note> + </refsect1> - <note> - <simpara> - As of PHP 5.0.0 the number of matched and replaced - needles (<parameter>search</parameter>) will be returned in - <parameter>count</parameter> which is passed by reference. - Prior to PHP 5.0.0 this parameter is not available. - </simpara> - </note> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>str_ireplace</function>, - <function>substr_replace</function>, - <function>preg_replace</function>, and - <function>strtr</function>. + <simplelist> + <member><function>str_ireplace</function></member> + <member><function>substr_replace</function></member> + <member><function>preg_replace</function></member> + <member><function>strtr</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id='function.str-rot13'> <refnamediv> <refname>str_rot13</refname> <refpurpose>Perform the rot13 transform on a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>str_rot13</methodname> <methodparam><type>string</type><parameter>str</parameter></methodparam> </methodsynopsis> <para> - This function performs the ROT13 encoding on the - <parameter>str</parameter> argument and returns the resulting - string. The ROT13 encoding simply shifts every letter by 13 - places in the alphabet while leaving non-alpha characters - untouched. Encoding and decoding are done by the same function, - passing an encoded string as argument will return the original version. + Performs the ROT13 encoding on the <parameter>str</parameter> argument and + returns the resulting string. </para> <para> + The ROT13 encoding simply shifts every letter by 13 places in the alphabet + while leaving non-alpha characters untouched. Encoding and decoding are + done by the same function, passing an encoded string as argument will + return the original version. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the ROT13 version of the given string. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> <example> <title><function>str_rot13</function> example</title> <programlisting role="php"> @@ -34,14 +63,34 @@ </programlisting> </example> </para> - <note> - <para> - The behaviour of this function was buggy until PHP 4.3.0. Before - this, the <parameter>str</parameter> was also modified, as if - passed by reference. - </para> - </note> </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.3.0</entry> + <entry> + The behaviour of this function was fixed. Before this fix, the + <parameter>str</parameter> was also modified, as if it was passed + by reference. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + </refentry>  + <refentry id="function.str-split"> <refnamediv> <refname>str_split</refname> <refpurpose>Convert a string to an array</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>str_split</methodname> <methodparam><type>string</type><parameter>string</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>split_length</parameter></methodparam> </methodsynopsis> <para> - Converts a string to an array. If the optional - <parameter>split_length</parameter> parameter is specified, the - returned array will be broken down into chunks with each being - <parameter>split_length</parameter> in length, otherwise each chunk + Converts a string to an array. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>split_length</parameter></term> + <listitem> + <para> + Maximum length of the chunk. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + If the optional <parameter>split_length</parameter> parameter is + specified, the returned array will be broken down into chunks with each + being <parameter>split_length</parameter> in length, otherwise each chunk will be one character in length. </para> <para> - &false; is returned if <parameter>split_length</parameter> is less - than 1. If the <parameter>split_length</parameter> length exceeds the - length of <parameter>string</parameter>, the entire string is returned - as the first (and only) array element. + &false; is returned if <parameter>split_length</parameter> is less than 1. + If the <parameter>split_length</parameter> length exceeds the length of + <parameter>string</parameter>, the entire string is returned as the first + (and only) array element. </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>Example uses of <function>str_split</function></title> @@ -43,9 +78,7 @@ ?> ]]> </programlisting> - <para> - Output may look like: - </para> + &example.outputs; <screen> <![CDATA[ Array @@ -75,15 +108,22 @@ </screen> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>chunk_split</function>, - <function>preg_split</function>, - <function>explode</function>, - <function>count_chars</function>, - <function>str_word_count</function>, and - <link linkend="control-structures.for">for</link>. + <simplelist> + <member><function>chunk_split</function></member> + <member><function>preg_split</function></member> + <member><function>explode</function></member> + <member><function>count_chars</function></member> + <member><function>str_word_count</function></member> + <member><link linkend="control-structures.for">for</link></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.strcasecmp"> <refnamediv> <refname>strcasecmp</refname> <refpurpose>Binary safe case-insensitive string comparison</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>strcasecmp</methodname> <methodparam><type>string</type><parameter>str1</parameter></methodparam> <methodparam><type>string</type><parameter>str2</parameter></methodparam> </methodsynopsis> <para> + Binary safe case-insensitive string comparison. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str1</parameter></term> + <listitem> + <para> + The first string + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>str2</parameter></term> + <listitem> + <para> + The second string + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> Returns < 0 if <parameter>str1</parameter> is less than <parameter>str2</parameter>; > 0 if <parameter>str1</parameter> is greater than <parameter>str2</parameter>, and 0 if they are equal. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> <example> <title><function>strcasecmp</function> example</title> <programlisting role="php"> @@ -31,18 +68,24 @@ ?> ]]> </programlisting> - </example> + </example> + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>preg_match</function></member> + <member><function>strcmp</function></member> + <member><function>substr</function></member> + <member><function>stristr</function></member> + <member><function>strncasecmp</function></member> + <member><function>strstr</function></member> + </simplelist> </para> - <simpara> - See also - <function>preg_match</function>, - <function>strcmp</function>, - <function>substr</function>, - <function>stristr</function>, - <function>strncasecmp</function>, and - <function>strstr</function>. - </simpara> </refsect1> + </refentry>  - + <refentry id="function.strcmp"> <refnamediv> <refname>strcmp</refname> <refpurpose>Binary safe string comparison</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>strcmp</methodname> <methodparam><type>string</type><parameter>str1</parameter></methodparam> <methodparam><type>string</type><parameter>str2</parameter></methodparam> </methodsynopsis> <simpara> + Note that this comparison is case sensitive. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str1</parameter></term> + <listitem> + <para> + The first string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>str2</parameter></term> + <listitem> + <para> + The second string. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> Returns < 0 if <parameter>str1</parameter> is less than <parameter>str2</parameter>; > 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>preg_match</function>, - <function>strcasecmp</function>, - <function>substr</function>, - <function>stristr</function>, - <function>strncasecmp</function>, - <function>strncmp</function>, and - <function>strstr</function>. - </simpara> + </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>preg_match</function></member> + <member><function>strcasecmp</function></member> + <member><function>substr</function></member> + <member><function>stristr</function></member> + <member><function>strncasecmp</function></member> + <member><function>strncmp</function></member> + <member><function>strstr</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.strcoll"> <refnamediv> <refname>strcoll</refname> <refpurpose>Locale based string comparison</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>strcoll</methodname> <methodparam><type>string</type><parameter>str1</parameter></methodparam> <methodparam><type>string</type><parameter>str2</parameter></methodparam> </methodsynopsis> - <simpara> + <para> + Note that this comparison is case sensitive, and unlike + <function>strcmp</function> this function is not binary safe. + </para> + <para> + <function>strcoll</function> uses the current locale for doing the + comparisons. If the current locale is C or POSIX, this function is + equivalent to <function>strcmp</function>. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str1</parameter></term> + <listitem> + <para> + The first string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>str2</parameter></term> + <listitem> + <para> + The second string. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> Returns < 0 if <parameter>str1</parameter> is less than <parameter>str2</parameter>; > 0 if <parameter>str1</parameter> is greater than <parameter>str2</parameter>, and 0 if they are equal. - <function>strcoll</function> uses the current locale for doing - the comparisons. If the current locale is C or POSIX, this - function is equivalent to <function>strcmp</function>. - </simpara> - <simpara> - Note that this comparison is case sensitive, and unlike - <function>strcmp</function> this function is not binary safe. - </simpara> - <note> - <para> - <function>strcoll</function> was added in PHP 4.0.5, but was not enabled - for win32 until 4.2.3. - </para> - </note> - <simpara> - See also <function>preg_match</function>, <function>strcmp</function>, - <function>strcasecmp</function>, <function>substr</function>, - <function>stristr</function>, <function>strncasecmp</function>, - <function>strncmp</function>, <function>strstr</function>, and - <function>setlocale</function>. - </simpara> + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.2.3</entry> + <entry> + This function now works on win32. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>preg_match</function></member> + <member><function>strcmp</function></member> + <member><function>strcasecmp</function></member> + <member><function>substr</function></member> + <member><function>stristr</function></member> + <member><function>strncasecmp</function></member> + <member><function>strncmp</function></member> + <member><function>strstr</function></member> + <member><function>setlocale</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.strcspn"> <refnamediv> <refname>strcspn</refname> <refpurpose>Find length of initial segment not matching mask</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>strcspn</methodname> <methodparam><type>string</type><parameter>str1</parameter></methodparam> @@ -15,24 +15,97 @@ <methodparam choice="opt"><type>int</type><parameter>start</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam> </methodsynopsis> - <simpara> + <para> Returns the length of the initial segment of <parameter>str1</parameter> which does <emphasis>not</emphasis> contain any of the characters in <parameter>str2</parameter>. - </simpara> - <simpara> - As of PHP 4.3.0, <function>strcspn</function> accepts two optional - <type>integer</type> parameters that can be used to define the - <parameter>start</parameter> position and the - <parameter>length</parameter> of the string to examine. - </simpara> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str1</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>str2</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>start</parameter></term> + <listitem> + <para> + The start position of the string to examine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>length</parameter></term> + <listitem> + <para> + The length of the string to examine. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the length of the segment as an integer. + </para> + </refsect1> + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.3.0</entry> + <entry> + The <parameter>start</parameter> and <parameter>length</parameter> + were added + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; &note.bin-safe; + </refsect1> - <simpara> - See also <function>strspn</function>. - </simpara> + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>strspn</function></member> + </simplelist> + </para> </refsect1> + </refentry>  - + <refentry id="function.strip-tags"> <refnamediv> <refname>strip_tags</refname> <refpurpose>Strip HTML and PHP tags from a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>strip_tags</methodname> <methodparam><type>string</type><parameter>str</parameter></methodparam> <methodparam choice="opt"><type>string</type><parameter>allowable_tags</parameter></methodparam> </methodsynopsis> <para> - This function tries to return a string with all HTML and PHP tags - stripped from a given <parameter>str</parameter>. It uses - the same tag stripping state machine as the - <function>fgetss</function> function. - </para> - <para> - You can use the optional second parameter to specify tags which - should not be stripped. - <note> - <para> - <parameter>allowable_tags</parameter> was added in PHP 3.0.13 - and PHP 4.0.0. - </para> - <para> - Since PHP 4.3.0, HTML comments are also stripped. This is hardcoded and can - not be changed with <parameter>allowable_tags</parameter>. - </para> - </note> - <warning> - <para> - Because <function>strip_tags</function> does not actually validate the - HTML, partial, or broken tags can result in the removal of more - text/data than expected. - </para> - </warning> - <warning> - <para> - This function does not modify any attributes on the tags that you allow - using <parameter>allowable_tags</parameter>, including the - <literal>style</literal> and <literal>onmouseover</literal> attributes - that a mischievous user may abuse when posting text that will be shown - to other users. - </para> - </warning> + This function tries to return a string with all HTML and PHP tags stripped + from a given <parameter>str</parameter>. It uses the same tag stripping + state machine as the <function>fgetss</function> function. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>allowable_tags</parameter></term> + <listitem> + <para> + You can use the optional second parameter to specify tags which should + not be stripped. + </para> + <note> + <para> + HTML comments are also stripped. This is hardcoded and can not be + changed with <parameter>allowable_tags</parameter>. + </para> + </note> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the stripped string. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>5.0.0</entry> + <entry> + <function>strip_tags</function> is now binary safe + </entry> + </row> + <row> + <entry>4.3.0</entry> + <entry> + HTML comments are now always stripped + </entry> + </row> + <row> + <entry>4.0.0</entry> + <entry> + The <parameter>allowable_tags</parameter> parameter was added + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>strip_tags</function> example</title> @@ -73,13 +120,37 @@ </screen> </example> </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <warning> + <para> + Because <function>strip_tags</function> does not actually validate the + HTML, partial, or broken tags can result in the removal of more + text/data than expected. + </para> + </warning> + <warning> + <para> + This function does not modify any attributes on the tags that you allow + using <parameter>allowable_tags</parameter>, including the + <literal>style</literal> and <literal>onmouseover</literal> attributes + that a mischievous user may abuse when posting text that will be shown + to other users. + </para> + </warning> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - <function>strip_tags</function> has been binary safe since PHP 5.0.0 - </para> - <para> - See also <function>htmlspecialchars</function>. + <simplelist> + <member><function>htmlspecialchars</function></member> + </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.stripos"> <refnamediv> <refname>stripos</refname> <refpurpose>Find position of first occurrence of a case-insensitive string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>stripos</methodname> <methodparam><type>string</type><parameter>haystack</parameter></methodparam> @@ -16,20 +17,64 @@ <para> Returns the numeric position of the first occurrence of <parameter>needle</parameter> in the <parameter>haystack</parameter> - <type>string</type>. Unlike <function>strpos</function>, - <function>stripos</function> is case-insensitive. + <type>string</type>. </para> <para> - Note that the <parameter>needle</parameter> may be a string of one or - more characters. + Unlike <function>strpos</function>, <function>stripos</function> is + case-insensitive. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>haystack</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>needle</parameter></term> + <listitem> + <para> + Note that the <parameter>needle</parameter> may be a string of one or + more characters. + </para> + <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> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>offset</parameter></term> + <listitem> + <para> + The optional <parameter>offset</parameter> parameter allows you + to specify which character in <parameter>haystack</parameter> to + start searching. The position returned is still relative to the + beginning of <parameter>haystack</parameter>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> If <parameter>needle</parameter> is not found, <function>stripos</function> will return <type>boolean</type> &false;. </para> - &return.falseproblem; + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>stripos</function> examples</title> @@ -58,26 +103,29 @@ </programlisting> </example> </para> - <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> - The optional <parameter>offset</parameter> parameter allows you - to specify which character in <parameter>haystack</parameter> to - start searching. The position returned is still relative to the - beginning of <parameter>haystack</parameter>. - </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; &note.bin-safe; + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>strpos</function>, <function>strrpos</function>, - <function>strrchr</function>, <function>substr</function>, - <function>stristr</function>, <function>strstr</function>, - <function>strripos</function> and <function>str_ireplace</function>. + <simplelist> + <member><function>strpos</function></member> + <member><function>strrpos</function></member> + <member><function>strrchr</function></member> + <member><function>substr</function></member> + <member><function>stristr</function></member> + <member><function>strstr</function></member> + <member><function>strripos</function></member> + <member><function>str_ireplace</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.stripslashes"> <refnamediv> <refname>stripslashes</refname> <refpurpose>Un-quote string quoted with <function>addslashes</function></refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>stripslashes</methodname> <methodparam><type>string</type><parameter>str</parameter></methodparam> </methodsynopsis> <para> - Returns a string with backslashes stripped off. - (<literal>\'</literal> becomes <literal>'</literal> and so on.) - Double backslashes (<literal>\\</literal>) are made into a single - backslash (<literal>\</literal>). + Un-quotes a quoted string. </para> <note> <para> @@ -30,9 +27,38 @@ directive <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link> is <literal>on</literal> (it's on by default), and you aren't inserting this data into a place (such as a database) that requires escaping. - For example, if you're simply outputting data straight from an HTML - form. + For example, if you're simply outputting data straight from an HTML form. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns a string with backslashes stripped off. + (<literal>\'</literal> becomes <literal>'</literal> and so on.) + Double backslashes (<literal>\\</literal>) are made into a single + backslash (<literal>\</literal>). + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>A <function>stripslashes</function> example</title> @@ -51,7 +77,8 @@ <note> <para> <function>stripslashes</function> is not recursive. If you want to apply - this function to a mutli-dimensional array, you need to use a recursive function. + this function to a mutli-dimensional array, you need to use a recursive + function. </para> </note> <para> @@ -96,14 +123,18 @@ </screen> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - For more information about "magic quotes", see <function>get_magic_quotes_gpc</function>. + <simplelist> + <member><function>addslashes</function></member> + <member><function>get_magic_quotes_gpc</function></member> + </simplelist> </para> - <simpara> - See also <function>addslashes</function> and - <function>get_magic_quotes_gpc</function>. - </simpara> </refsect1> + </refentry>  - + <refentry id="function.stristr"> <refnamediv> <refname>stristr</refname> <refpurpose>Case-insensitive <function>strstr</function></refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>stristr</methodname> <methodparam><type>string</type><parameter>haystack</parameter></methodparam> @@ -16,16 +16,47 @@ <para> Returns all of <parameter>haystack</parameter> from the first occurrence of <parameter>needle</parameter> to the end. - <parameter>needle</parameter> and <parameter>haystack</parameter> - are examined in a case-insensitive manner. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - If <parameter>needle</parameter> is not found, returns &false;. + <variablelist> + <varlistentry> + <term><parameter>haystack</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>needle</parameter></term> + <listitem> + <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> + </listitem> + </varlistentry> + </variablelist> </para> <para> - If <parameter>needle</parameter> is not a string, it is converted - to an integer and applied as the ordinal value of a character. + <parameter>needle</parameter> and <parameter>haystack</parameter> + are examined in a case-insensitive manner. </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the matched substring. If <parameter>needle</parameter> is not + found, returns &false;. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>stristr</function> example</title> @@ -70,17 +101,25 @@ </programlisting> </example> </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; &note.bin-safe; + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also - <function>strstr</function>, - <function>strrchr</function>, - <function>substr</function>, and - <function>preg_match</function>. + <simplelist> + <member><function>strstr</function></member> + <member><function>strrchr</function></member> + <member><function>substr</function></member> + <member><function>preg_match</function></member> + </simplelist> </para> </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> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>strnatcasecmp</methodname> <methodparam><type>string</type><parameter>str1</parameter></methodparam> <methodparam><type>string</type><parameter>str2</parameter></methodparam> </methodsynopsis> <para> - This function implements a comparison algorithm that orders - alphanumeric strings in the way a human being would. The - behaviour of this function is similar to - <function>strnatcmp</function>, except that the comparison is not - case sensitive. For more information see: Martin Pool's <ulink - url="&url.strnatcmp;">Natural Order String Comparison</ulink> - page. + This function implements a comparison algorithm that orders alphanumeric + strings in the way a human being would. The behaviour of this function is + similar to <function>strnatcmp</function>, except that the comparison is + not case sensitive. For more information 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 - < 0 if <parameter>str1</parameter> is less than - <parameter>str2</parameter> > 0 if - <parameter>str1</parameter> is greater than + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str1</parameter></term> + <listitem> + <para> + The first string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>str2</parameter></term> + <listitem> + <para> + The second string. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Similar to other string comparison functions, this one returns < 0 if + <parameter>str1</parameter> is less than <parameter>str2</parameter> > + 0 if <parameter>str1</parameter> is greater than <parameter>str2</parameter>, and 0 if they are equal. - </simpara> - <simpara> - See also <function>preg_match</function>, - <function>strcasecmp</function>, - <function>substr</function>, - <function>stristr</function>, - <function>strcmp</function>, - <function>strncmp</function>, - <function>strncasecmp</function>, - <function>strnatcmp</function>, and - <function>strstr</function>. - </simpara> + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>preg_match</function></member> + <member><function>strcmp</function></member> + <member><function>strcasecmp</function></member> + <member><function>substr</function></member> + <member><function>stristr</function></member> + <member><function>strncasecmp</function></member> + <member><function>strncmp</function></member> + <member><function>strstr</function></member> + <member><function>setlocale</function></member> + </simplelist> + </para> </refsect1> + </refentry>  - + <refentry id="function.strnatcmp"> <refnamediv> <refname>strnatcmp</refname> <refpurpose>String comparisons using a "natural order" algorithm</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>strnatcmp</methodname> <methodparam><type>string</type><parameter>str1</parameter></methodparam> @@ -16,10 +16,51 @@ <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: + described as a "natural ordering". + Note that this comparison is case sensitive. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str1</parameter></term> + <listitem> + <para> + The first string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>str2</parameter></term> + <listitem> + <para> + The second string. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Similar to other string comparison functions, this one returns < 0 if + <parameter>str1</parameter> is less than <parameter>str2</parameter>; > + 0 if <parameter>str1</parameter> is greater than + <parameter>str2</parameter>, and 0 if they are equal. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + 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 role="php"> <![CDATA[ @@ -34,9 +75,7 @@ ?> ]]> </programlisting> - </informalexample> - The code above will generate the following output: - <informalexample> + &example.outputs; <screen> <![CDATA[ Standard string comparison @@ -63,25 +102,27 @@ url="&url.strnatcmp;">Natural Order String Comparison</ulink> page. </para> - <simpara> - Similar to other string comparison functions, this one returns - < 0 if <parameter>str1</parameter> is less than - <parameter>str2</parameter>; > 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>preg_match</function>, - <function>strcasecmp</function>, <function>substr</function>, - <function>stristr</function>, <function>strcmp</function>, - <function>strncmp</function>, <function>strncasecmp</function>, - <function>strnatcasecmp</function>, <function>strstr</function>, - <function>natsort</function> and <function>natcasesort</function>. - </simpara> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>preg_match</function></member> + <member><function>strcasecmp</function></member> + <member><function>substr</function></member> + <member><function>stristr</function></member> + <member><function>strcmp</function></member> + <member><function>strncmp</function></member> + <member><function>strncasecmp</function></member> + <member><function>strnatcasecmp</function></member> + <member><function>strstr</function></member> + <member><function>natsort</function></member> + <member><function>natcasesort</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.strncasecmp"> <refnamediv> <refname>strncasecmp</refname> <refpurpose>Binary safe case-insensitive string comparison of the first n characters</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>strncasecmp</methodname> <methodparam><type>string</type><parameter>str1</parameter></methodparam> @@ -15,25 +15,67 @@ <methodparam><type>int</type><parameter>len</parameter></methodparam> </methodsynopsis> <para> - This function is similar to <function>strcasecmp</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. </para> - <simpara> + This function is similar to <function>strcasecmp</function>, with the + difference that you can specify the (upper limit of the) number of + characters from each string to be used in the comparison. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str1</parameter></term> + <listitem> + <para> + The first string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>str2</parameter></term> + <listitem> + <para> + The second string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>len</parameter></term> + <listitem> + <para> + The length of strings to be used in the comparison. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> Returns < 0 if <parameter>str1</parameter> is less than - <parameter>str2</parameter>; > 0 if <parameter>str1</parameter> - is greater than <parameter>str2</parameter>, and 0 if they are - equal. - </simpara> - <simpara> - See also <function>preg_match</function>, - <function>strcasecmp</function>, - <function>strcmp</function>, - <function>substr</function>, - <function>stristr</function>, and - <function>strstr</function>. - </simpara> + <parameter>str2</parameter>; > 0 if <parameter>str1</parameter> is + greater than <parameter>str2</parameter>, and 0 if they are equal. + </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>preg_match</function></member> + <member><function>strcmp</function></member> + <member><function>strcasecmp</function></member> + <member><function>substr</function></member> + <member><function>stristr</function></member> + <member><function>strstr</function></member> + </simplelist> + </para> + </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> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>strncmp</methodname> <methodparam><type>string</type><parameter>str1</parameter></methodparam> @@ -16,27 +16,71 @@ </methodsynopsis> <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. + difference that you can specify the (upper limit of the) number of + characters from each string to be used in the comparison. </para> - <simpara> + <para> + Note that this comparison is case sensitive. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str1</parameter></term> + <listitem> + <para> + The first string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>str2</parameter></term> + <listitem> + <para> + The second string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>len</parameter></term> + <listitem> + <para> + Number of characters to use in the comparison. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> Returns < 0 if <parameter>str1</parameter> is less than <parameter>str2</parameter>; > 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>preg_match</function>, - <function>strncasecmp</function>, - <function>strcasecmp</function>, <function>substr</function>, - <function>stristr</function>, <function>strcmp</function>, and - <function>strstr</function>. - </simpara> + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>preg_match</function></member> + <member><function>strcmp</function></member> + <member><function>strcasecmp</function></member> + <member><function>substr</function></member> + <member><function>stristr</function></member> + <member><function>strncasecmp</function></member> + <member><function>strstr</function></member> + </simplelist> + </para> </refsect1> + </refentry>  - + <refentry id="function.strpos"> <refnamediv> <refname>strpos</refname> <refpurpose>Find position of first occurrence of a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>strpos</methodname> <methodparam><type>string</type><parameter>haystack</parameter></methodparam> @@ -16,22 +16,63 @@ </methodsynopsis> <para> Returns the numeric position of the first occurrence of - <parameter>needle</parameter> in the - <parameter>haystack</parameter> string. Unlike the - <function>strrpos</function> before PHP 5, this function can take a full - string as the <parameter>needle</parameter> parameter and the - entire string will be used. + <parameter>needle</parameter> in the <parameter>haystack</parameter> + string. Unlike the <function>strrpos</function> before PHP 5, this + function can take a full string as the <parameter>needle</parameter> + parameter and the entire string will be used. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - If <parameter>needle</parameter> is not found, - <function>strpos</function> will return <type>boolean</type> &false;. + <variablelist> + <varlistentry> + <term><parameter>haystack</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>needle</parameter></term> + <listitem> + <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> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>offset</parameter></term> + <listitem> + <para> + The optional <parameter>offset</parameter> parameter allows you + to specify which character in <parameter>haystack</parameter> to + start searching. The position returned is still relative to the + beginning of <parameter>haystack</parameter>. + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the position as an integer. If <parameter>needle</parameter> is + not found, <function>strpos</function> will return <type>boolean</type> + &false;. + </para> &return.falseproblem; - &note.bin-safe; + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> - <title><function>strpos</function> examples</title> + <title><function>strpos</function> examples</title> <programlisting role="php"> <![CDATA[ <?php @@ -56,26 +97,28 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + &note.bin-safe; + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <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> - The optional <parameter>offset</parameter> parameter allows you - to specify which character in <parameter>haystack</parameter> to - start searching. The position returned is still relative to the - beginning of <parameter>haystack</parameter>. - </para> - <para> - See also <function>strrpos</function>, - <function>stripos</function>, - <function>strripos</function>, - <function>strrchr</function>, - <function>substr</function>, - <function>stristr</function>, and - <function>strstr</function>. + <simplelist> + <member><function>strrpos</function></member> + <member><function>stripos</function></member> + <member><function>strripos</function></member> + <member><function>strrchr</function></member> + <member><function>substr</function></member> + <member><function>stristr</function></member> + <member><function>strstr</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.strrchr"> <refnamediv> <refname>strrchr</refname> <refpurpose>Find the last occurrence of a character in a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>strrchr</methodname> <methodparam><type>string</type><parameter>haystack</parameter></methodparam> <methodparam><type>string</type><parameter>needle</parameter></methodparam> </methodsynopsis> <para> - This function returns the portion of - <parameter>haystack</parameter> which starts at the last - occurrence of <parameter>needle</parameter> and goes until the - end of <parameter>haystack</parameter>. + This function returns the portion of <parameter>haystack</parameter> which + starts at the last occurrence of <parameter>needle</parameter> and goes + until the end of <parameter>haystack</parameter>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - Returns &false; if <parameter>needle</parameter> is not found. + <variablelist> + <varlistentry> + <term><parameter>haystack</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>needle</parameter></term> + <listitem> + <para> + If <parameter>needle</parameter> contains more than one character, + only the first is used. This behavior is different from that of + <function>strchr</function>. + </para> + <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> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - If <parameter>needle</parameter> contains more than one - character, only the first is used. This behavior is different from that - of <function>strchr</function>. + This function returns the portion of string, or &false; if + <parameter>needle</parameter> is not found. </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.3.0</entry> + <entry> + This function is now binary safe. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> - If <parameter>needle</parameter> is not a string, it is converted - to an integer and applied as the ordinal value of a character. <example> <title><function>strrchr</function> example</title> <programlisting role="php"> @@ -44,16 +98,26 @@ ?> ]]> </programlisting> - </example> - </para> - <para> - <function>strrchr</function> has been binary safe since PHP 4.3.0 + </example> </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + &note.bin-safe; + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>strstr</function>, <function>substr</function>, and - <function>stristr</function>. + <simplelist> + <member><function>strstr</function></member> + <member><function>substr</function></member> + <member><function>stristr</function></member> + </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.strripos"> <refnamediv> <refname>strripos</refname> <refpurpose>Find position of last occurrence of a case-insensitive string in a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>strripos</methodname> <methodparam><type>string</type><parameter>haystack</parameter></methodparam> @@ -14,23 +15,65 @@ <methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam> </methodsynopsis> <para> - Returns the numeric position of the last occurrence of - <parameter>needle</parameter> in the - <parameter>haystack</parameter> string. Unlike - <function>strrpos</function>, <function>strripos</function> is - case-insensitive. Also note that string positions start at 0, and not - 1. + Find position of last occurrence of a case-insensitive string in a string. + Unlike <function>strrpos</function>, <function>strripos</function> is + case-insensitive. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>haystack</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>needle</parameter></term> + <listitem> + <para> + Note that the <parameter>needle</parameter> may be a string of one or + more characters. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>offset</parameter></term> + <listitem> + <para> + The <parameter>offset</parameter> parameter may be specified to begin + searching an arbitrary number of characters into the string. + </para> + <para> + Negative offset values will start the search at + <parameter>offset</parameter> characters from the + <emphasis>start</emphasis> of the string. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - Note that the <parameter>needle</parameter> may be a string of one or - more characters. + Returns the numerical position of the last occurence of + <parameter>needle</parameter>. Also note that string positions start at 0, + and not 1. </para> <para> If <parameter>needle</parameter> is not found, &false; is returned. </para> - &return.falseproblem; + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>A simple <function>strripos</function> example</title> @@ -51,9 +94,7 @@ ?> ]]> </programlisting> - <para> - Outputs: - </para> + &example.outputs; <screen> <![CDATA[ Congratulations! @@ -62,22 +103,22 @@ </screen> </example> </para> - <simpara> - The <parameter>offset</parameter> parameter may be specified to begin - searching an arbitrary number of characters into the string. - </simpara> - <simpara> - Negative offset values will start the search at - <parameter>offset</parameter> characters from the - <emphasis>start</emphasis> of the string. - </simpara> - <para> - See also <function>strrpos</function>, - <function>strrchr</function>, - <function>substr</function>, <function>stripos</function> and - <function>stristr</function>. + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>strpos</function></member> + <member><function>stripos</function></member> + <member><function>strrchr</function></member> + <member><function>substr</function></member> + <member><function>stristr</function></member> + <member><function>strstr</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.strrpos"> <refnamediv> <refname>strrpos</refname> <refpurpose>Find position of last occurrence of a char in a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>strrpos</methodname> <methodparam><type>string</type><parameter>haystack</parameter></methodparam> @@ -68,15 +68,72 @@ character as of PHP 5.0.0. </simpara> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>strpos</function></member> + <member><function>strripos</function></member> + <member><function>strrchr</function></member> + <member><function>substr</function></member> + <member><function>stristr</function></member> + <member><function>strstr</function></member> + </simplelist> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - See also <function>strpos</function>, - <function>strripos</function>, - <function>strrchr</function>, - <function>substr</function>, - <function>stristr</function>, and - <function>strstr</function>. + <variablelist> + <varlistentry> + <term><parameter>haystack</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>needle</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>offset</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> </para> </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>strpos</function></member> + <member><function>strripos</function></member> + <member><function>strrchr</function></member> + <member><function>substr</function></member> + <member><function>stristr</function></member> + <member><function>strstr</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.strspn"> <refnamediv> <refname>strspn</refname> <refpurpose>Find length of initial segment matching mask</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>strspn</methodname> <methodparam><type>string</type><parameter>str1</parameter></methodparam> @@ -15,11 +15,9 @@ <methodparam choice="opt"><type>int</type><parameter>start</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam> </methodsynopsis> - <simpara> - Returns the length of the initial segment of - <parameter>str1</parameter> which consists entirely of characters - in <parameter>str2</parameter>. - </simpara> + <para> + Finds the length of the initial segment matching mask. + </para> <para> The line of code: <informalexample> @@ -34,14 +32,86 @@ will assign 2 to <varname>$var</varname>, because the string "42" will be the longest segment containing characters from "1234567890". </para> - <simpara> - As of PHP 4.3.0, <function>strspn</function> accepts two optional - <type>integer</type> parameters that can be used to define the - <parameter>start</parameter> position and the - <parameter>length</parameter> of the string to examine. - </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - <informalexample> + <variablelist> + <varlistentry> + <term><parameter>str1</parameter></term> + <listitem> + <para> + The first string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>str2</parameter></term> + <listitem> + <para> + The second string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>start</parameter></term> + <listitem> + <para> + The start position of the string to examine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>length</parameter></term> + <listitem> + <para> + The length of the string to examine. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the length of the initial segment of <parameter>str1</parameter> + which consists entirely of characters in <parameter>str2</parameter>. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.3.0</entry> + <entry> + The <parameter>start</parameter> and <parameter>length</parameter> + parameters were added + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>strspn</function> example</title> <programlisting role="php"> <![CDATA[ <?php @@ -49,15 +119,24 @@ ?> ]]> </programlisting> - </informalexample> + </example> </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; &note.bin-safe; + </refsect1> - <simpara> - See also <function>strcspn</function>. - </simpara> + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>strcspn</function></member> + </simplelist> + </para> </refsect1> + </refentry>  - + <refentry id="function.strstr"> <refnamediv> <refname>strstr</refname> <refpurpose>Find first occurrence of a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>strstr</methodname> <methodparam><type>string</type><parameter>haystack</parameter></methodparam> <methodparam><type>string</type><parameter>needle</parameter></methodparam> </methodsynopsis> <para> - Returns part of <parameter>haystack</parameter> string from the - first occurrence of <parameter>needle</parameter> to the end of + Returns part of <parameter>haystack</parameter> string from the first + occurrence of <parameter>needle</parameter> to the end of <parameter>haystack</parameter>. </para> - <para> - If <parameter>needle</parameter> is not found, returns &false;. - </para> - <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> <note> <para> This function is case-sensitive. For case-insensitive searches, use <function>stristr</function>. </para> </note> + <note> + <para> + If you only want to determine if a particular <parameter>needle</parameter> + occurs within <parameter>haystack</parameter>, use the faster and less memory + intensive function <function>strpos</function> instead. + </para> + </note> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>haystack</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>needle</parameter></term> + <listitem> + <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> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the portion of string, or &false; if <parameter>needle</parameter> + is not found. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.3.0</entry> + <entry> + <function>strstr</function> was made binary safe. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>strstr</function> example</title> @@ -45,24 +106,21 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - <note> - <para> - If you only want to determine if a particular <parameter>needle</parameter> - occurs within <parameter>haystack</parameter>, use the faster and less memory - intensive function <function>strpos</function> instead. - </para> - </note> - </para> - <para> - <function>strstr</function> has been binary safe since PHP 4.3.0 - </para> - <para> - See also <function>preg_match</function>, - <function>stristr</function>, <function>strpos</function>, - <function>strrchr</function>, and <function>substr</function>. + <simplelist> + <member><function>preg_match</function></member> + <member><function>stristr</function></member> + <member><function>strpos</function></member> + <member><function>strrchr</function></member> + <member><function>substr</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.strtolower"> <refnamediv> <refname>strtolower</refname> <refpurpose>Make a string lowercase</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>strtolower</methodname> <methodparam><type>string</type><parameter>str</parameter></methodparam> </methodsynopsis> <para> - Returns <parameter>string</parameter> with all alphabetic - characters converted to lowercase. + Returns <parameter>string</parameter> with all alphabetic characters + converted to lowercase. </para> <para> - Note that 'alphabetic' is determined by the current locale. This - means that in i.e. the default "C" locale, characters such as - umlaut-A (Ä) will not be converted. + Note that 'alphabetic' is determined by the current locale. This means + that in i.e. the default "C" locale, characters such as umlaut-A + (Ä) will not be converted. </para> - <example> - <title><function>strtolower</function> example</title> - <programlisting role="php"> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the lowercased string. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>strtolower</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $str = "Mary Had A Little Lamb and She LOVED It So"; @@ -31,16 +59,28 @@ echo $str; // Prints mary had a little lamb and she loved it so ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; &note.bin-safe; + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>strtoupper</function>, <function>ucfirst</function>, - <function>ucwords</function> and <function>mb_strtolower</function>. + <simplelist> + <member><function>strtoupper</function></member> + <member><function>ucfirst</function></member> + <member><function>ucwords</function></member> + <member><function>mb_strtolower</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.strtoupper"> <refnamediv> <refname>strtoupper</refname> <refpurpose>Make a string uppercase</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>strtoupper</methodname> <methodparam><type>string</type><parameter>string</parameter></methodparam> </methodsynopsis> <para> - Returns <parameter>string</parameter> with all alphabetic - characters converted to uppercase. + Returns <parameter>string</parameter> with all alphabetic characters + converted to uppercase. </para> <para> - 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. + 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. </para> - <example> - <title><function>strtoupper</function> example</title> - <programlisting role="php"> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the uppercased string. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>strtoupper</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $str = "Mary Had A Little Lamb and She LOVED It So"; @@ -31,16 +59,28 @@ echo $str; // Prints MARY HAD A LITTLE LAMB AND SHE LOVED IT SO ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; &note.bin-safe; + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>strtolower</function>, <function>ucfirst</function>, - <function>ucwords</function> and <function>mb_strtoupper</function>. + <simplelist> + <member><function>strtolower</function></member> + <member><function>ucfirst</function></member> + <member><function>ucwords</function></member> + <member><function>mb_strtoupper</function></member> + </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.substr-compare"> <refnamediv> <refname>substr_compare</refname> - <refpurpose>Binary safe optionally case insensitive comparison of 2 strings from an offset, up to length characters</refpurpose> + <refpurpose>Binary safe comparison of 2 strings from an offset, up to length characters</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>substr_compare</methodname> <methodparam><type>string</type><parameter>main_str</parameter></methodparam> @@ -15,12 +16,62 @@ <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam> <methodparam choice="opt"><type>bool</type><parameter>case_insensitivity</parameter></methodparam> </methodsynopsis> - <para> <function>substr_compare</function> compares <parameter>main_str</parameter> from position <parameter>offset</parameter> with <parameter>str</parameter> up to <parameter>length</parameter> characters. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>main_str</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>str</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>offset</parameter></term> + <listitem> + <para> + The start position for the comparison. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>length</parameter></term> + <listitem> + <para> + The length of the comparison. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>case_insensitivity</parameter></term> + <listitem> + <para> + If <parameter>case_insensitivity</parameter> is &true;, comparison is + case insensitive. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> Returns < 0 if <parameter>main_str</parameter> from position <parameter>offset</parameter> is less than <parameter>str</parameter>, > @@ -29,10 +80,10 @@ <parameter>main_str</parameter> and <parameter>length</parameter> is set, <function>substr_compare</function> prints warning and returns &false;. </para> - <para> - If <parameter>case_insensitivity</parameter> is &true;, comparison is case - insensitive. - </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>A <function>substr_compare</function> example</title> @@ -50,8 +101,8 @@ </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> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>mixed</type><methodname>substr_replace</methodname> <methodparam><type>mixed</type><parameter>string</parameter></methodparam> @@ -20,33 +20,77 @@ <parameter>string</parameter> delimited by the <parameter>start</parameter> and (optionally) <parameter>length</parameter> parameters with the string given in - <parameter>replacement</parameter>. The result string is returned. - If <parameter>string</parameter> is an array then array is returned. - </para> - <para> - If <parameter>start</parameter> is positive, the replacing will - begin at the <parameter>start</parameter>'th offset into - <parameter>string</parameter>. + <parameter>replacement</parameter>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - If <parameter>start</parameter> is negative, the replacing will - begin at the <parameter>start</parameter>'th character from the - end of <parameter>string</parameter>. + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>replacement</parameter></term> + <listitem> + <para> + The replacement string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>start</parameter></term> + <listitem> + <para> + If <parameter>start</parameter> is positive, the replacing will + begin at the <parameter>start</parameter>'th offset into + <parameter>string</parameter>. + </para> + <para> + If <parameter>start</parameter> is negative, the replacing will + begin at the <parameter>start</parameter>'th character from the + end of <parameter>string</parameter>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>length</parameter></term> + <listitem> + <para> + If given and is positive, it represents the length of the portion of + <parameter>string</parameter> which is to be replaced. If it is + negative, it represents the number of characters from the end of + <parameter>string</parameter> at which to stop replacing. If it + is not given, then it will default to strlen( + <parameter>string</parameter> ); i.e. end the replacing at the + end of <parameter>string</parameter>. Of course, if + <parameter>length</parameter> is zero then this function will have the + effect of inserting <parameter>replacement</parameter> into + <parameter>string</parameter> at the given + <parameter>start</parameter> offset. + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - If <parameter>length</parameter> is given and is positive, it - represents the length of the portion of - <parameter>string</parameter> which is to be replaced. If it is - negative, it represents the number of characters from the end of - <parameter>string</parameter> at which to stop replacing. If it - is not given, then it will default to strlen( - <parameter>string</parameter> ); i.e. end the replacing at the - end of <parameter>string</parameter>. Of course, if - <parameter>length</parameter> is zero then this function will have the - effect of inserting <parameter>replacement</parameter> into - <parameter>string</parameter> at the given - <parameter>start</parameter> offset. + The result string is returned. If <parameter>string</parameter> is an + array then array is returned. </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>substr_replace</function> example</title> @@ -74,14 +118,23 @@ </programlisting> </example> </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; &note.bin-safe; + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>str_replace</function> and - <function>substr</function>. + <simplelist> + <member><function>str_replace</function></member> + <member><function>substr</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.substr"> <refnamediv> <refname>substr</refname> <refpurpose>Return part of a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>substr</methodname> <methodparam><type>string</type><parameter>string</parameter></methodparam> @@ -15,22 +15,107 @@ <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam> </methodsynopsis> <para> - <function>substr</function> returns the portion of <parameter>string</parameter> - specified by the <parameter>start</parameter> and - <parameter>length</parameter> parameters. + Returns the portion of <parameter>string</parameter> specified by the + <parameter>start</parameter> and <parameter>length</parameter> parameters. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>start</parameter></term> + <listitem> + <para> + If <parameter>start</parameter> is non-negative, the returned string + 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> + If <parameter>start</parameter> is negative, the returned string + will start at the <parameter>start</parameter>'th character + from the end of <parameter>string</parameter>. + </para> + <para> + <example> + <title>Using a negative <parameter>start</parameter></title> + <programlisting role="php"> +<![CDATA[ +<?php +$rest = substr("abcdef", -1); // returns "f" +$rest = substr("abcdef", -2); // returns "ef" +$rest = substr("abcdef", -3, 1); // returns "d" +?> +]]> + </programlisting> + </example> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>length</parameter></term> + <listitem> + <para> + If <parameter>length</parameter> is given and is positive, the string + returned will contain at most <parameter>length</parameter> characters + beginning from <parameter>start</parameter> (depending on the length of + <parameter>string</parameter>). If <parameter>string</parameter> is less + than or equal to <parameter>start</parameter> characters long, &false; + will be returned. + </para> + <para> + If <parameter>length</parameter> is given and is negative, then that many + characters will be omitted from the end of <parameter>string</parameter> + (after the start position has been calculated when a + <parameter>start</parameter> is negative). If + <parameter>start</parameter> denotes a position beyond this truncation, + an empty string will be returned. + </para> + <example> + <title>Using a negative <parameter>length</parameter></title> + <programlisting role="php"> +<![CDATA[ +<?php +$rest = substr("abcdef", 0, -1); // returns "abcde" +$rest = substr("abcdef", 2, -1); // returns "cde" +$rest = substr("abcdef", 4, -4); // returns "" +$rest = substr("abcdef", -3, -1); // returns "de" +?> +]]> + </programlisting> + </example> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - If <parameter>start</parameter> is non-negative, the returned string - 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. + Returns the extracted part of string. </para> - <example> - <title>Basic <function>substr</function> usage</title> - <programlisting role="php"> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title>Basic <function>substr</function> usage</title> + <programlisting role="php"> <![CDATA[ <?php echo substr('abcdef', 1); // bcdef @@ -48,63 +133,25 @@ ?> ]]> - </programlisting> - </example> - <para> - If <parameter>start</parameter> is negative, the returned string - will start at the <parameter>start</parameter>'th character - from the end of <parameter>string</parameter>. - </para> - <example> - <title>Using a negative <parameter>start</parameter></title> - <programlisting role="php"> -<![CDATA[ -<?php -$rest = substr("abcdef", -1); // returns "f" -$rest = substr("abcdef", -2); // returns "ef" -$rest = substr("abcdef", -3, 1); // returns "d" -?> -]]> - </programlisting> - </example> - <para> - If <parameter>length</parameter> is given and is positive, the string - returned will contain at most <parameter>length</parameter> characters - beginning from <parameter>start</parameter> (depending on the length of - <parameter>string</parameter>). If <parameter>string</parameter> is less - than or equal to <parameter>start</parameter> characters long, &false; - will be returned. - </para> - <para> - If <parameter>length</parameter> is given and is negative, then that many - characters will be omitted from the end of <parameter>string</parameter> - (after the start position has been calculated when a - <parameter>start</parameter> is negative). If - <parameter>start</parameter> denotes a position beyond this truncation, - an empty string will be returned. + </programlisting> + </example> </para> - <example> - <title>Using a negative <parameter>length</parameter></title> - <programlisting role="php"> -<![CDATA[ -<?php -$rest = substr("abcdef", 0, -1); // returns "abcde" -$rest = substr("abcdef", 2, -1); // returns "cde" -$rest = substr("abcdef", 4, -4); // returns "" -$rest = substr("abcdef", -3, -1); // returns "de" -?> -]]> - </programlisting> - </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>strrchr</function>, - <function>substr_replace</function>, - <function>preg_match</function>, - <function>trim</function>, - <function>mb_substr</function> and - <function>wordwrap</function>. + <simplelist> + <member><function>strrchr</function></member> + <member><function>substr_replace</function></member> + <member><function>preg_match</function></member> + <member><function>trim</function></member> + <member><function>mb_substr</function></member> + <member><function>wordwrap</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.ucwords"> <refnamediv> <refname>ucwords</refname> <refpurpose>Uppercase the first character of each word in a string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>ucwords</methodname> <methodparam><type>string</type><parameter>str</parameter></methodparam> </methodsynopsis> <para> Returns a string with the first character of each word in - <parameter>str</parameter> capitalized, if that character is - alphabetic. + <parameter>str</parameter> capitalized, if that character is alphabetic. </para> - <simpara> - The definition of a word is any string of characters - that is immediately after a whitespace (These are: - space, form-feed, newline, carriage return, horizontal tab, - and vertical tab). - </simpara> + <para> + The definition of a word is any string of characters that is immediately + after a whitespace (These are: space, form-feed, newline, carriage return, + horizontal tab, and vertical tab). + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>str</parameter></term> + <listitem> + <para> + The input string. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the modified string. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>ucwords</function> example</title> @@ -40,14 +65,24 @@ </programlisting> </example> </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; &note.bin-safe; + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>strtoupper</function>, - <function>strtolower</function> and <function>ucfirst</function>. + <simplelist> + <member><function>strtoupper</function></member> + <member><function>strtolower</function></member> + <member><function>ucfirst</function></member> + </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.vfprintf"> <refnamediv> <refname>vfprintf</refname> <refpurpose>Write a formatted string to a stream</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>vfprintf</methodname> <methodparam><type>resource</type><parameter>handle</parameter></methodparam> <methodparam><type>string</type><parameter>format</parameter></methodparam> <methodparam><type>array</type><parameter>args</parameter></methodparam> </methodsynopsis> - <simpara> - Write a string produced according to <parameter>format</parameter> - to the stream resource specified by <parameter>handle</parameter>. - <parameter>format</parameter> is described in the documentation for - <function>sprintf</function>. - </simpara> - <simpara> + <para> + Write a string produced according to <parameter>format</parameter> to the + stream resource specified by <parameter>handle</parameter>. + </para> + <para> Operates as <function>fprintf</function> but accepts an array of arguments, rather than a variable number of arguments. - </simpara> - <simpara> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>handle</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>format</parameter></term> + <listitem> + <para> + See <function>sprintf</function> for a description of + <parameter>format</parameter>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> Returns the length of the outputted string. - </simpara> - <simpara> - See also: <function>printf</function>, - <function>sprintf</function>, - <function>sscanf</function>, <function>fscanf</function>, - <function>vsprintf</function>, and - <function>number_format</function>. - </simpara> + </para> </refsect1> - <refsect1> - <title>Examples</title> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>vfprintf</function>: zero-padded integers</title> @@ -53,6 +81,21 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>printf</function></member> + <member><function>sprintf</function></member> + <member><function>sscanf</function></member> + <member><function>fscanf</function></member> + <member><function>vsprintf</function></member> + <member><function>number_format</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.vprintf"> <refnamediv> <refname>vprintf</refname> <refpurpose>Output a formatted string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>vprintf</methodname> <methodparam><type>string</type><parameter>format</parameter></methodparam> <methodparam><type>array</type><parameter>args</parameter></methodparam> </methodsynopsis> - <simpara> + <para> Display array values as a formatted string according to <parameter>format</parameter> (which is described in the documentation for <function>sprintf</function>). - </simpara> - <simpara> + </para> + <para> Operates as <function>printf</function> but accepts an array of arguments, rather than a variable number of arguments. - </simpara> - <simpara> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>format</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> Returns the length of the outputted string. - </simpara> - <simpara> - See also <function>printf</function>, <function>sprintf</function>, - <function>vsprintf</function> - </simpara> + </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>printf</function></member> + <member><function>sprintf</function></member> + <member><function>vsprintf</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.vsprintf"> <refnamediv> <refname>vsprintf</refname> <refpurpose>Return a formatted string</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>vsprintf</methodname> <methodparam><type>string</type><parameter>format</parameter></methodparam> <methodparam><type>array</type><parameter>args</parameter></methodparam> </methodsynopsis> - <simpara> + <para> + Operates as <function>sprintf</function> but accepts an array of + arguments, rather than a variable number of arguments. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>format</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> Return array values as a formatted string according to <parameter>format</parameter> (which is described in the documentation for <function>sprintf</function>). - </simpara> - <simpara> - Operates as <function>sprintf</function> but accepts an array of - arguments, rather than a variable number of arguments. - </simpara> - <simpara> - See also <function>sprintf</function> and <function>vprintf</function> - </simpara> + </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>sprintf</function></member> + <member><function>vprintf</function></member> + </simplelist> + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file