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:27 +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-969376714@lists.php.net to get a copy of this message

didou Fri Jun 15 19:01:27 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: WS, prepare for new doc style

http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/strings/functions/echo.xml?r1=1.17&r2=1.18&diff_format=u Index: phpdoc/en/reference/strings/functions/echo.xml diff -u phpdoc/en/reference/strings/functions/echo.xml:1.17 phpdoc/en/reference/strings/functions/echo.xml:1.18 --- phpdoc/en/reference/strings/functions/echo.xml:1.17 Tue Aug 9 17:41:06 2005 +++ phpdoc/en/reference/strings/functions/echo.xml Fri Jun 15 19:01:26 2007 @@ -1,40 +1,40 @@ <?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> - <methodsynopsis> - <type>void</type><methodname>echo</methodname> - <methodparam><type>string</type><parameter>arg1</parameter></methodparam> - <methodparam choice="opt"><type>string</type><parameter>...</parameter></methodparam> - </methodsynopsis> - <simpara> - Outputs all parameters. - </simpara> - <para> - <function>echo</function> is not actually a function (it is a - language construct), so you are not required to use parentheses - with it. <function>echo</function> (unlike some other language - constructs) does not behave like a function, so it cannot - always be used in the context of a function. Additionally, if you want to - pass more than one parameter to <function>echo</function>, the parameters - must not be enclosed within parentheses. - </para> - <para> - <example> - <title><function>echo</function> examples</title> - <programlisting role="php"> +<refentry id="function.echo"> + <refnamediv> + <refname>echo</refname> + <refpurpose>Output one or more strings</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>void</type><methodname>echo</methodname> + <methodparam><type>string</type><parameter>arg1</parameter></methodparam> + <methodparam choice="opt"><type>string</type><parameter>...</parameter></methodparam> + </methodsynopsis> + <simpara> + Outputs all parameters. + </simpara> + <para> + <function>echo</function> is not actually a function (it is a + language construct), so you are not required to use parentheses + with it. <function>echo</function> (unlike some other language + constructs) does not behave like a function, so it cannot + always be used in the context of a function. Additionally, if you want to + pass more than one parameter to <function>echo</function>, the parameters + must not be enclosed within parentheses. + </para> + <para> + <example> + <title><function>echo</function> examples</title> + <programlisting role="php"> <![CDATA[ <?php echo "Hello World"; echo "This spans -multiple lines. The newlines will be +multiple lines. The newlines will be output as well"; echo "This spans\nmultiple lines. The newlines will be\noutput as well."; @@ -80,40 +80,40 @@ echo $some_var ? 'true': 'false'; // changing the statement around ?> ]]> - </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"> + </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> - <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; - - <simpara> - See also - <function>print</function>, - <function>printf</function>, and - <function>flush</function>. - </simpara> - </refsect1> - </refentry> + </programlisting> + </informalexample> + </para> + <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; + + <simpara> + See also + <function>print</function>, + <function>printf</function>, and + <function>flush</function>. + </simpara> + </refsect1> +</refentry>  +  - <refentry id="function.explode"> - <refnamediv> - <refname>explode</refname> - <refpurpose>Split a string by string</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>array</type><methodname>explode</methodname> - <methodparam><type>string</type><parameter>delimiter</parameter></methodparam> - <methodparam><type>string</type><parameter>string</parameter></methodparam> - <methodparam choice="opt"><type>int</type><parameter>limit</parameter></methodparam> - </methodsynopsis> - <para> - Returns an array of strings, each of which is a substring of - <parameter>string</parameter> formed by splitting it on - boundaries formed by the string <parameter>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> - <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. - </para> - <para> - Although <function>implode</function> can, for historical reasons, - accept its parameters in either order, - <function>explode</function> cannot. You must ensure that the - <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> - <para> - <example> - <title><function>explode</function> examples</title> - <programlisting role="php"> +<refentry id="function.explode"> + <refnamediv> + <refname>explode</refname> + <refpurpose>Split a string by string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>array</type><methodname>explode</methodname> + <methodparam><type>string</type><parameter>delimiter</parameter></methodparam> + <methodparam><type>string</type><parameter>string</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>limit</parameter></methodparam> + </methodsynopsis> + <para> + Returns an array of strings, each of which is a substring of + <parameter>string</parameter> formed by splitting it on + boundaries formed by the string <parameter>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> + <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. + </para> + <para> + Although <function>implode</function> can, for historical reasons, + accept its parameters in either order, + <function>explode</function> cannot. You must ensure that the + <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> + <para> + <example> + <title><function>explode</function> examples</title> + <programlisting role="php"> <![CDATA[ <?php // Example 1 @@ -68,13 +68,13 @@ ?> ]]> - </programlisting> - </example> - </para> - <para> - <example> - <title><parameter>limit</parameter> parameter examples</title> - <programlisting role="php"> + </programlisting> + </example> + </para> + <para> + <example> + <title><parameter>limit</parameter> parameter examples</title> + <programlisting role="php"> <![CDATA[ <?php $str = 'one|two|three|four'; @@ -86,9 +86,9 @@ print_r(explode('|', $str, -1)); ?> ]]> - </programlisting> - &example.outputs; - <screen> + </programlisting> + &example.outputs; + <screen> <![CDATA[ Array ( @@ -102,21 +102,21 @@ [2] => three ) ]]> - </screen> - </example> - </para> - - &note.bin-safe; - - <para> - See also - <function>preg_split</function>, - <function>str_split</function>, - <function>strtok</function>, and - <function>implode</function>. - </para> - </refsect1> - </refentry> + </screen> + </example> + </para> + + &note.bin-safe; + + <para> + See also + <function>preg_split</function>, + <function>str_split</function>, + <function>strtok</function>, and + <function>implode</function>. + </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> - <methodsynopsis> - <type>int</type><methodname>fprintf</methodname> - <methodparam><type>resource</type><parameter>handle</parameter></methodparam> - <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> - 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> - 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> - </refsect1> - <refsect1> - <title>Examples</title> - <para> - <example> - <title><function>fprintf</function>: zero-padded integers</title> - <programlisting role="php"> + +<refentry id="function.fprintf"> + <refnamediv> + <refname>fprintf</refname> + <refpurpose>Write a formatted string to a stream</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>int</type><methodname>fprintf</methodname> + <methodparam><type>resource</type><parameter>handle</parameter></methodparam> + <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> + 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> + 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> + </refsect1> + <refsect1> + <title>Examples</title> + <para> + <example> + <title><function>fprintf</function>: zero-padded integers</title> + <programlisting role="php"> <![CDATA[ <?php if (!($fp = fopen('date.txt', 'w'))) @@ -46,11 +46,11 @@ // will write the formatted ISO date to date.txt ?> ]]> - </programlisting> - </example> - <example> - <title><function>fprintf</function>: formatting currency</title> - <programlisting role="php"> + </programlisting> + </example> + <example> + <title><function>fprintf</function>: formatting currency</title> + <programlisting role="php"> <![CDATA[ <?php if (!($fp = fopen('currency.txt', 'w'))) @@ -67,11 +67,11 @@ // use the return value of fprintf to determine how many bytes we wrote ?> ]]> - </programlisting> - </example> - </para> - </refsect1> - </refentry> + </programlisting> + </example> + </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> - <methodsynopsis> - <type>array</type><methodname>get_html_translation_table</methodname> - <methodparam choice="opt"><type>int</type><parameter>table</parameter></methodparam> - <methodparam choice="opt"><type>int</type><parameter>quote_style</parameter></methodparam> - </methodsynopsis> - <para> - <function>get_html_translation_table</function> will return the - translation table that is used internally for - <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. - <literal>"</literal> can be encoded as <literal>&quot;</literal>, - <literal>&#34;</literal> or <literal>&#x22</literal>. - <function>get_html_translation_table</function> returns only the most - common form for them. - </para> - </note> - <para> - <example> - <title>Translation Table Example</title> - <programlisting role="php"> +<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> + <methodsynopsis> + <type>array</type><methodname>get_html_translation_table</methodname> + <methodparam choice="opt"><type>int</type><parameter>table</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>quote_style</parameter></methodparam> + </methodsynopsis> + <para> + <function>get_html_translation_table</function> will return the + translation table that is used internally for + <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. + <literal>"</literal> can be encoded as <literal>&quot;</literal>, + <literal>&#34;</literal> or <literal>&#x22</literal>. + <function>get_html_translation_table</function> returns only the most + common form for them. + </para> + </note> + <para> + <example> + <title>Translation Table Example</title> + <programlisting role="php"> <![CDATA[ <?php $trans = get_html_translation_table(HTML_ENTITIES); @@ -55,19 +51,19 @@ $encoded = strtr($str, $trans); ?> ]]> - </programlisting> - </example> - The <literal>$encoded</literal> variable will now contain: - <literal>"Hallo &amp; &lt;Frau&gt; &amp; - Kr&auml;mer".</literal> - </para> - <para> - See also <function>htmlspecialchars</function>, - <function>htmlentities</function>, and - <function>html_entity_decode</function>. - </para> - </refsect1> - </refentry> + </programlisting> + </example> + The <literal>$encoded</literal> variable will now contain: + <literal>"Hallo &amp; &lt;Frau&gt; &amp; + Kr&auml;mer".</literal> + </para> + <para> + See also <function>htmlspecialchars</function>, + <function>htmlentities</function>, and + <function>html_entity_decode</function>. + </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> - <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. - </para> - <para> - See also <function>hebrevc</function> - </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> + <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. + </para> + <para> + See also <function>hebrevc</function> + </para> + </refsect1> +</refentry>  +  - <refentry id="function.hebrevc"> - <refnamediv> - <refname>hebrevc</refname> - <refpurpose> - Convert logical Hebrew text to visual text with newline conversion - </refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>string</type><methodname>hebrevc</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> - 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. - </para> - <para> - See also <function>hebrev</function> - </para> - </refsect1> - </refentry> +<refentry id="function.hebrevc"> + <refnamediv> + <refname>hebrevc</refname> + <refpurpose>Convert logical Hebrew text to visual text with newline conversion</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>string</type><methodname>hebrevc</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> + 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. + </para> + <para> + See also <function>hebrev</function> + </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> - <methodsynopsis> - <type>string</type><methodname>html_entity_decode</methodname> - <methodparam><type>string</type><parameter>string</parameter></methodparam> - <methodparam choice="opt"><type>int</type><parameter>quote_style</parameter></methodparam> - <methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam> - </methodsynopsis> - <para> - <function>html_entity_decode</function> is the opposite of - <function>htmlentities</function> in that it converts all HTML entities - to their applicable characters from <parameter>string</parameter>. - </para> - <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> - <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; - <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"> +<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> + <methodsynopsis> + <type>string</type><methodname>html_entity_decode</methodname> + <methodparam><type>string</type><parameter>string</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>quote_style</parameter></methodparam> + <methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam> + </methodsynopsis> + <para> + <function>html_entity_decode</function> is the opposite of + <function>htmlentities</function> in that it converts all HTML entities + to their applicable characters from <parameter>string</parameter>. + </para> + <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> + <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; + <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"> <![CDATA[ <?php $orig = "I'll \"walk\" the <b>dog</b> now"; @@ -81,7 +79,7 @@ // For users prior to PHP 4.3.0 you may do this: -function unhtmlentities($string) +function unhtmlentities($string) { // replace numeric entities $string = preg_replace('~&#x([0-9a-f]+);~ei', 'chr(hexdec("\\1"))', $string); @@ -98,28 +96,28 @@ ?> ]]> - </programlisting> - </example> - </para> - <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>. - </para> - </refsect1> - </refentry> + </programlisting> + </example> + </para> + <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>. + </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> - <methodsynopsis> - <type>string</type><methodname>htmlentities</methodname> - <methodparam><type>string</type><parameter>string</parameter></methodparam> - <methodparam choice="opt"><type>int</type><parameter>quote_style</parameter></methodparam> - <methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam> - <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. - </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> - <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> - <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>. - </para> - <para> - <example> - <title>A <function>htmlentities</function> example</title> - <programlisting role="php"> +<refentry id="function.htmlentities"> + <refnamediv> + <refname>htmlentities</refname> + <refpurpose>Convert all applicable characters to HTML entities</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>string</type><methodname>htmlentities</methodname> + <methodparam><type>string</type><parameter>string</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>quote_style</parameter></methodparam> + <methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam> + <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. + </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> + <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> + <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>. + </para> + <para> + <example> + <title>A <function>htmlentities</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $str = "A 'quote' is <b>bold</b>"; @@ -88,17 +86,17 @@ echo htmlentities($str, ENT_QUOTES); ?> ]]> - </programlisting> - </example> - </para> - <para> - See also <function>html_entity_decode</function>, - <function>get_html_translation_table</function>, - <function>htmlspecialchars</function>, <function>nl2br</function>, - and <function>urlencode</function>. - </para> - </refsect1> - </refentry> + </programlisting> + </example> + </para> + <para> + See also <function>html_entity_decode</function>, + <function>get_html_translation_table</function>, + <function>htmlspecialchars</function>, <function>nl2br</function>, + and <function>urlencode</function>. + </para> + </refsect1> +</refentry>  +  - <refentry id="function.implode"> - <refnamediv> - <refname>implode</refname> - <refpurpose>Join array elements with a string</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <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. - <example> - <title><function>implode</function> example</title> - <programlisting role="php"> +<refentry id="function.implode"> + <refnamediv> + <refname>implode</refname> + <refpurpose>Join array elements with a string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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. + <example> + <title><function>implode</function> example</title> + <programlisting role="php"> <![CDATA[ <?php @@ -30,33 +30,33 @@ ?> ]]> - </programlisting> - </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> - - &note.bin-safe; - - <simpara> - See also <function>explode</function>, and <function>split</function>. - </simpara> - </refsect1> - </refentry> + </programlisting> + </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> + + &note.bin-safe; + + <simpara> + See also <function>explode</function>, and <function>split</function>. + </simpara> + </refsect1> +</refentry>  +  - <refentry id="function.localeconv"> - <refnamediv> - <refname>localeconv</refname> - <refpurpose>Get numeric formatting information</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>array</type><methodname>localeconv</methodname> - <void/> - </methodsynopsis> - <para> - Returns an associative array containing localized numeric and - monetary formatting information. - </para> - <para> - <function>localeconv</function> returns data based upon the current locale - as set by <function>setlocale</function>. The associative array that is - returned contains the following fields: - <informaltable > - <tgroup cols="2"> - <thead> - <row> - <entry>Array element</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>decimal_point</entry> - <entry>Decimal point character</entry> - </row> - <row> - <entry>thousands_sep</entry> - <entry>Thousands separator</entry> - </row> - <row> - <entry>grouping</entry> - <entry>Array containing numeric groupings</entry> - </row> - <row> - <entry>int_curr_symbol</entry> - <entry>International currency symbol (i.e. USD)</entry> - </row> - <row> - <entry>currency_symbol</entry> - <entry>Local currency symbol (i.e. $)</entry> - </row> - <row> - <entry>mon_decimal_point</entry> - <entry>Monetary decimal point character</entry> - </row> - <row> - <entry>mon_thousands_sep</entry> - <entry>Monetary thousands separator</entry> - </row> - <row> - <entry>mon_grouping</entry> - <entry>Array containing monetary groupings</entry> - </row> - <row> - <entry>positive_sign</entry> - <entry>Sign for positive values</entry> - </row> - <row> - <entry>negative_sign</entry> - <entry>Sign for negative values</entry> - </row> - <row> - <entry>int_frac_digits</entry> - <entry>International fractional digits</entry> - </row> - <row> - <entry>frac_digits</entry> - <entry>Local fractional digits</entry> - </row> - <row> - <entry>p_cs_precedes</entry> - <entry> - &true; if currency_symbol precedes a positive value, &false; - if it succeeds one - </entry> - </row> - <row> - <entry>p_sep_by_space</entry> - <entry> - &true; if a space separates currency_symbol from a positive - value, &false; otherwise - </entry> - </row> - <row> - <entry>n_cs_precedes</entry> - <entry> - &true; if currency_symbol precedes a negative value, &false; - if it succeeds one - </entry> - </row> - <row> - <entry>n_sep_by_space</entry> - <entry> - &true; if a space separates currency_symbol from a negative - value, &false; otherwise - </entry> - </row> - <row valign="top"> - <entry>p_sign_posn</entry> - <entry> - <simplelist> - <member>0 - Parentheses surround the quantity and currency_symbol</member> - <member>1 - The sign string precedes the quantity and currency_symbol</member> - <member>2 - The sign string succeeds the quantity and currency_symbol</member> - <member>3 - The sign string immediately precedes the currency_symbol</member> - <member>4 - The sign string immediately succeeds the currency_symbol</member> - </simplelist> - </entry> - </row> - <row valign="top"> - <entry>n_sign_posn</entry> - <entry> - <simplelist> - <member>0 - Parentheses surround the quantity and currency_symbol</member> - <member>1 - The sign string precedes the quantity and currency_symbol</member> - <member>2 - The sign string succeeds the quantity and currency_symbol</member> - <member>3 - The sign string immediately precedes the currency_symbol</member> - <member>4 - The sign string immediately succeeds the currency_symbol</member> - </simplelist> - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - <para> - The <literal>n_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> - The grouping fields contain arrays that define the way numbers should be - grouped. For example, the monetary grouping field for the nl_NL locale (in - UTF-8 mode with the euro sign), would contain a 2 item array with the - values 3 and 3. The higher the index in the array, the farther left the - grouping is. If an array element is equal to <constant>CHAR_MAX</constant>, - 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"> +<refentry id="function.localeconv"> + <refnamediv> + <refname>localeconv</refname> + <refpurpose>Get numeric formatting information</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>array</type><methodname>localeconv</methodname> + <void/> + </methodsynopsis> + <para> + Returns an associative array containing localized numeric and + monetary formatting information. + </para> + <para> + <function>localeconv</function> returns data based upon the current locale + as set by <function>setlocale</function>. The associative array that is + returned contains the following fields: + <informaltable > + <tgroup cols="2"> + <thead> + <row> + <entry>Array element</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>decimal_point</entry> + <entry>Decimal point character</entry> + </row> + <row> + <entry>thousands_sep</entry> + <entry>Thousands separator</entry> + </row> + <row> + <entry>grouping</entry> + <entry>Array containing numeric groupings</entry> + </row> + <row> + <entry>int_curr_symbol</entry> + <entry>International currency symbol (i.e. USD)</entry> + </row> + <row> + <entry>currency_symbol</entry> + <entry>Local currency symbol (i.e. $)</entry> + </row> + <row> + <entry>mon_decimal_point</entry> + <entry>Monetary decimal point character</entry> + </row> + <row> + <entry>mon_thousands_sep</entry> + <entry>Monetary thousands separator</entry> + </row> + <row> + <entry>mon_grouping</entry> + <entry>Array containing monetary groupings</entry> + </row> + <row> + <entry>positive_sign</entry> + <entry>Sign for positive values</entry> + </row> + <row> + <entry>negative_sign</entry> + <entry>Sign for negative values</entry> + </row> + <row> + <entry>int_frac_digits</entry> + <entry>International fractional digits</entry> + </row> + <row> + <entry>frac_digits</entry> + <entry>Local fractional digits</entry> + </row> + <row> + <entry>p_cs_precedes</entry> + <entry> + &true; if currency_symbol precedes a positive value, &false; + if it succeeds one + </entry> + </row> + <row> + <entry>p_sep_by_space</entry> + <entry> + &true; if a space separates currency_symbol from a positive + value, &false; otherwise + </entry> + </row> + <row> + <entry>n_cs_precedes</entry> + <entry> + &true; if currency_symbol precedes a negative value, &false; + if it succeeds one + </entry> + </row> + <row> + <entry>n_sep_by_space</entry> + <entry> + &true; if a space separates currency_symbol from a negative + value, &false; otherwise + </entry> + </row> + <row valign="top"> + <entry>p_sign_posn</entry> + <entry> + <simplelist> + <member>0 - Parentheses surround the quantity and currency_symbol</member> + <member>1 - The sign string precedes the quantity and currency_symbol</member> + <member>2 - The sign string succeeds the quantity and currency_symbol</member> + <member>3 - The sign string immediately precedes the currency_symbol</member> + <member>4 - The sign string immediately succeeds the currency_symbol</member> + </simplelist> + </entry> + </row> + <row valign="top"> + <entry>n_sign_posn</entry> + <entry> + <simplelist> + <member>0 - Parentheses surround the quantity and currency_symbol</member> + <member>1 - The sign string precedes the quantity and currency_symbol</member> + <member>2 - The sign string succeeds the quantity and currency_symbol</member> + <member>3 - The sign string immediately precedes the currency_symbol</member> + <member>4 - The sign string immediately succeeds the currency_symbol</member> + </simplelist> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + <para> + The <literal>n_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> + The grouping fields contain arrays that define the way numbers should be + grouped. For example, the monetary grouping field for the nl_NL locale (in + UTF-8 mode with the euro sign), would contain a 2 item array with the + values 3 and 3. The higher the index in the array, the farther left the + grouping is. If an array element is equal to <constant>CHAR_MAX</constant>, + 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"> <![CDATA[ <?php if (false !== setlocale(LC_ALL, 'nl_NL.UTF-8@euro')) { @@ -157,9 +157,9 @@ } ?> ]]> - </programlisting> - &example.outputs; - <screen> + </programlisting> + &example.outputs; + <screen> <![CDATA[ Array ( @@ -191,13 +191,13 @@ ) ]]> - </screen> - </example> - <para> - See also <function>setlocale</function>. - </para> - </refsect1> - </refentry> + </screen> + </example> + <para> + See also <function>setlocale</function>. + </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> - <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> +<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> + <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> + This function returns a string with whitespace stripped from the + beginning of <parameter>str</parameter>. + Without the second parameter, + <function>ltrim</function> will strip these characters: +  + <itemizedlist> + <listitem> <simpara> - The second parameter was added in PHP 4.1.0 + " " (<acronym>ASCII</acronym> <literal>32</literal> + (<literal>0x20</literal>)), an ordinary space. </simpara> - </note> - <para> - This function returns a string with whitespace stripped from the - beginning of <parameter>str</parameter>. - Without the second parameter, - <function>ltrim</function> will strip these characters: -  - <itemizedlist> - <listitem> - <simpara> - " " (<acronym>ASCII</acronym> <literal>32</literal> - (<literal>0x20</literal>)), an ordinary space. - </simpara> - </listitem> - <listitem> - <simpara> - "\t" (<acronym>ASCII</acronym> <literal>9</literal> - (<literal>0x09</literal>)), a tab. - </simpara> - </listitem> - <listitem> - <simpara> - "\n" (<acronym>ASCII</acronym> <literal>10</literal> - (<literal>0x0A</literal>)), a new line (line feed). - </simpara> - </listitem> - <listitem> - <simpara> - "\r" (<acronym>ASCII</acronym> <literal>13</literal> - (<literal>0x0D</literal>)), a carriage return. - </simpara> - </listitem> - <listitem> - <simpara> - "\0" (<acronym>ASCII</acronym> <literal>0</literal> - (<literal>0x00</literal>)), the <literal>NUL</literal>-byte. - </simpara> - </listitem> - <listitem> - <simpara>  - "\x0B" (<acronym>ASCII</acronym> <literal>11</literal> - (<literal>0x0B</literal>)), a vertical tab. - </simpara> - </listitem> - </itemizedlist> - </para> - <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"> + </listitem> + <listitem> + <simpara> + "\t" (<acronym>ASCII</acronym> <literal>9</literal> + (<literal>0x09</literal>)), a tab. + </simpara> + </listitem> + <listitem> + <simpara> + "\n" (<acronym>ASCII</acronym> <literal>10</literal> + (<literal>0x0A</literal>)), a new line (line feed). + </simpara> + </listitem> + <listitem> + <simpara> + "\r" (<acronym>ASCII</acronym> <literal>13</literal> + (<literal>0x0D</literal>)), a carriage return. + </simpara> + </listitem> + <listitem> + <simpara> + "\0" (<acronym>ASCII</acronym> <literal>0</literal> + (<literal>0x00</literal>)), the <literal>NUL</literal>-byte. + </simpara> + </listitem> + <listitem> + <simpara>  + "\x0B" (<acronym>ASCII</acronym> <literal>11</literal> + (<literal>0x0B</literal>)), a vertical tab. + </simpara> + </listitem> + </itemizedlist> + </para> + <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"> <![CDATA[ <?php @@ -101,9 +99,9 @@ ?> ]]> - </programlisting> - &example.outputs; - <screen> + </programlisting> + &example.outputs; + <screen> <![CDATA[ string(32) " These are a few words :) ... " string(16) " Example string @@ -116,13 +114,13 @@ string(15) "Example string " ]]> - </screen> - </example> - <para> - See also <function>trim</function> and <function>rtrim</function>. - </para> - </refsect1> - </refentry> + </screen> + </example> + <para> + See also <function>trim</function> and <function>rtrim</function>. + </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> - <methodsynopsis> - <type>string</type><methodname>metaphone</methodname> - <methodparam><type>string</type><parameter>str</parameter></methodparam> - <methodparam choice="opt"><type>int</type><parameter>phones</parameter></methodparam> - </methodsynopsis> - <para> - 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. - </para> -  - <para> - Metaphone was developed by Lawrence Philips - <lphilips at verity dot com>. It is described in ["Practical - Algorithms for Programmers", Binstock & Rex, Addison Wesley, - 1995]. - </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> + <methodsynopsis> + <type>string</type><methodname>metaphone</methodname> + <methodparam><type>string</type><parameter>str</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>phones</parameter></methodparam> + </methodsynopsis> + <para> + 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. + </para> +  + <para> + Metaphone was developed by Lawrence Philips + <lphilips at verity dot com>. It is described in ["Practical + Algorithms for Programmers", Binstock & Rex, Addison Wesley, + 1995]. + </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> - <methodsynopsis> - <type>void</type><methodname>parse_str</methodname> - <methodparam><type>string</type><parameter>str</parameter></methodparam> - <methodparam choice="opt"><type>array</type><parameter role="reference">arr</parameter></methodparam> - </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. - </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 - <link linkend="language.variables.external">variables from outside of PHP</link>. - </para> - </note> - <note> - <para> - The <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link> setting - affects the output of this function, as <function>parse_str</function> uses - the same mechanism that PHP uses to populate the <literal>$_GET</literal>, - <literal>$_POST</literal>, etc. variables. - </para> - </note> - <para> - <example> - <title>Using <function>parse_str</function></title> - <programlisting role="php"> +<refentry id="function.parse-str"> + <refnamediv> + <refname>parse_str</refname> + <refpurpose>Parses the string into variables</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>void</type><methodname>parse_str</methodname> + <methodparam><type>string</type><parameter>str</parameter></methodparam> + <methodparam choice="opt"><type>array</type><parameter role="reference">arr</parameter></methodparam> + </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. + </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 + <link linkend="language.variables.external">variables from outside of PHP</link>. + </para> + </note> + <note> + <para> + The <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link> setting + affects the output of this function, as <function>parse_str</function> uses + the same mechanism that PHP uses to populate the <literal>$_GET</literal>, + <literal>$_POST</literal>, etc. variables. + </para> + </note> + <para> + <example> + <title>Using <function>parse_str</function></title> + <programlisting role="php"> <![CDATA[ <?php $str = "first=value&arr[]=foo+bar&arr[]=baz"; @@ -59,16 +59,16 @@ ?> ]]> - </programlisting> - </example> - </para> - <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>. - </para> - </refsect1> - </refentry> + </programlisting> + </example> + </para> + <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>. + </para> + </refsect1> +</refentry>  +  - <refentry id="function.printf"> - <refnamediv> - <refname>printf</refname> - <refpurpose>Output a formatted string</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>int</type><methodname>printf</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> - Produces output according to <parameter>format</parameter>, which - is described in the documentation for <function>sprintf</function>. - </simpara> - <simpara> - 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> - </refsect1> - </refentry> +<refentry id="function.printf"> + <refnamediv> + <refname>printf</refname> + <refpurpose>Output a formatted string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>int</type><methodname>printf</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> + Produces output according to <parameter>format</parameter>, which + is described in the documentation for <function>sprintf</function>. + </simpara> + <simpara> + 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> + </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> - <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> - </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> + <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> + </refsect1> +</refentry>  +  - <refentry id="function.quotemeta"> - <refnamediv> - <refname>quotemeta</refname> - <refpurpose>Quote meta characters</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <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> +<refentry id="function.quotemeta"> + <refnamediv> + <refname>quotemeta</refname> + <refpurpose>Quote meta characters</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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; @@ -23,8 +23,8 @@ <simpara> See also <function>addslashes</function>, <function>addcslashes</function>, - <function>htmlentities</function>, - <function>htmlspecialchars</function>, + <function>htmlentities</function>, + <function>htmlspecialchars</function>, <function>nl2br</function>, <function>stripslashes</function>, and <function>stripcslashes</function>. http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/strings/functions/rtrim.xml?r1=1.8&r2=1.9&diff_format=u Index: phpdoc/en/reference/strings/functions/rtrim.xml diff -u phpdoc/en/reference/strings/functions/rtrim.xml:1.8 phpdoc/en/reference/strings/functions/rtrim.xml:1.9 --- phpdoc/en/reference/strings/functions/rtrim.xml:1.8 Wed Feb 7 16:24:13 2007 +++ phpdoc/en/reference/strings/functions/rtrim.xml Fri Jun 15 19:01:26 2007 @@ -1,79 +1,77 @@ <?xml version="1.0" encoding="iso-8859-1"?> - +  - <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> - <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> +<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> + <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>. + Without the second parameter, + <function>rtrim</function> will strip these characters: +  + <itemizedlist> + <listitem> <simpara> - The second parameter was added in PHP 4.1.0 + " " (<acronym>ASCII</acronym> <literal>32</literal> + (<literal>0x20</literal>)), an ordinary space. </simpara> - </note> - <para> - This function returns a string with whitespace stripped from the - end of <parameter>str</parameter>. - Without the second parameter, - <function>rtrim</function> will strip these characters: -  - <itemizedlist> - <listitem> - <simpara> - " " (<acronym>ASCII</acronym> <literal>32</literal> - (<literal>0x20</literal>)), an ordinary space. - </simpara> - </listitem> - <listitem> - <simpara> - "\t" (<acronym>ASCII</acronym> <literal>9</literal> - (<literal>0x09</literal>)), a tab. - </simpara> - </listitem> - <listitem> - <simpara> - "\n" (<acronym>ASCII</acronym> <literal>10</literal> - (<literal>0x0A</literal>)), a new line (line feed). - </simpara> - </listitem> - <listitem> - <simpara> - "\r" (<acronym>ASCII</acronym> <literal>13</literal> - (<literal>0x0D</literal>)), a carriage return. - </simpara> - </listitem> - <listitem> - <simpara> - "\0" (<acronym>ASCII</acronym> <literal>0</literal> - (<literal>0x00</literal>)), the <literal>NUL</literal>-byte. - </simpara> - </listitem> - <listitem> - <simpara>  - "\x0B" (<acronym>ASCII</acronym> <literal>11</literal> - (<literal>0x0B</literal>)), a vertical tab. - </simpara> - </listitem> - </itemizedlist> - </para> - <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"> + </listitem> + <listitem> + <simpara> + "\t" (<acronym>ASCII</acronym> <literal>9</literal> + (<literal>0x09</literal>)), a tab. + </simpara> + </listitem> + <listitem> + <simpara> + "\n" (<acronym>ASCII</acronym> <literal>10</literal> + (<literal>0x0A</literal>)), a new line (line feed). + </simpara> + </listitem> + <listitem> + <simpara> + "\r" (<acronym>ASCII</acronym> <literal>13</literal> + (<literal>0x0D</literal>)), a carriage return. + </simpara> + </listitem> + <listitem> + <simpara> + "\0" (<acronym>ASCII</acronym> <literal>0</literal> + (<literal>0x00</literal>)), the <literal>NUL</literal>-byte. + </simpara> + </listitem> + <listitem> + <simpara>  + "\x0B" (<acronym>ASCII</acronym> <literal>11</literal> + (<literal>0x0B</literal>)), a vertical tab. + </simpara> + </listitem> + </itemizedlist> + </para> + <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"> <![CDATA[ <?php @@ -100,9 +98,9 @@ ?> ]]> - </programlisting> - &example.outputs; - <screen> + </programlisting> + &example.outputs; + <screen> <![CDATA[ string(32) " These are a few words :) ... " string(16) " Example string @@ -114,13 +112,13 @@ string(9) "Hello Wor" string(15) " Example string" ]]> - </screen> - </example> - <para> - See also <function>trim</function> and <function>ltrim</function>. - </para> - </refsect1> - </refentry> + </screen> + </example> + <para> + See also <function>trim</function> and <function>ltrim</function>. + </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> - <methodsynopsis> - <type>string</type><methodname>sha1</methodname> - <methodparam><type>string</type><parameter>str</parameter></methodparam> - <methodparam choice='opt'><type>bool</type><parameter>raw_output</parameter></methodparam> - </methodsynopsis> - <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> - <para> - <example> - <title>A <function>sha1</function> example</title> - <programlisting role="php"> + +<refentry id="function.sha1"> + <refnamediv> + <refname>sha1</refname> + <refpurpose>Calculate the sha1 hash of a string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>string</type><methodname>sha1</methodname> + <methodparam><type>string</type><parameter>str</parameter></methodparam> + <methodparam choice='opt'><type>bool</type><parameter>raw_output</parameter></methodparam> + </methodsynopsis> + <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> + <para> + <example> + <title>A <function>sha1</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $str = 'apple'; - + if (sha1($str) === 'd0be2dc421be4fcd0172e5afceea3970e2f3d940') { echo "Would you like a green or red apple?"; exit; } ?> ]]> - </programlisting> - </example> - </para> - <simpara> - See also <function>sha1_file</function>, - <function>crc32</function>, and - <function>md5</function> - </simpara> - </refsect1> - </refentry> + </programlisting> + </example> + </para> + <simpara> + See also <function>sha1_file</function>, + <function>crc32</function>, and + <function>md5</function> + </simpara> + </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> - <methodsynopsis> - <type>int</type><methodname>similar_text</methodname> - <methodparam><type>string</type><parameter>first</parameter></methodparam> - <methodparam><type>string</type><parameter>second</parameter></methodparam> - <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. - </para> - <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. - </para> - <simpara> - See also <function>levenshtein</function>, and <function>soundex</function>. - </simpara> - </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> + <methodsynopsis> + <type>int</type><methodname>similar_text</methodname> + <methodparam><type>string</type><parameter>first</parameter></methodparam> + <methodparam><type>string</type><parameter>second</parameter></methodparam> + <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. + </para> + <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. + </para> + <simpara> + See also <function>levenshtein</function>, and <function>soundex</function>. + </simpara> + </refsect1> +</refentry>  +  - <refentry id="function.soundex"> - <refnamediv> - <refname>soundex</refname> - <refpurpose>Calculate the soundex key of a string</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>string</type><methodname>soundex</methodname> - <methodparam><type>string</type><parameter>str</parameter></methodparam> - </methodsynopsis> - <para> - Calculates the soundex key of <parameter>str</parameter>. - </para> - <para> - Soundex keys have the property that words pronounced similarly - produce the same soundex key, and can thus be used to simplify - searches in databases where you know the pronunciation but not - the spelling. This soundex function returns a string 4 characters - long, starting with a letter. - </para> - <para> - This particular soundex function is one described by Donald Knuth - in "The Art Of Computer Programming, vol. 3: Sorting And - Searching", Addison-Wesley (1973), pp. 391-392. - </para> - <para> - <example> - <title>Soundex Examples</title> - <programlisting role="php"> +<refentry id="function.soundex"> + <refnamediv> + <refname>soundex</refname> + <refpurpose>Calculate the soundex key of a string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>string</type><methodname>soundex</methodname> + <methodparam><type>string</type><parameter>str</parameter></methodparam> + </methodsynopsis> + <para> + Calculates the soundex key of <parameter>str</parameter>. + </para> + <para> + Soundex keys have the property that words pronounced similarly + produce the same soundex key, and can thus be used to simplify + searches in databases where you know the pronunciation but not + the spelling. This soundex function returns a string 4 characters + long, starting with a letter. + </para> + <para> + This particular soundex function is one described by Donald Knuth + in "The Art Of Computer Programming, vol. 3: Sorting And + Searching", Addison-Wesley (1973), pp. 391-392. + </para> + <para> + <example> + <title>Soundex Examples</title> + <programlisting role="php"> <![CDATA[ <?php soundex("Euler") == soundex("Ellery"); // E460 @@ -41,17 +41,17 @@ soundex("Lukasiewicz") == soundex("Lissajous"); // L222 ?> ]]> - </programlisting> - </example> - </para> - <para> - See also - <function>levenshtein</function>, - <function>metaphone</function>, and - <function>similar_text</function>. - </para> - </refsect1> - </refentry> + </programlisting> + </example> + </para> + <para> + See also + <function>levenshtein</function>, + <function>metaphone</function>, and + <function>similar_text</function>. + </para> + </refsect1> +</refentry>  +  - <refentry id="function.sprintf"> - <refnamediv> - <refname>sprintf</refname> - <refpurpose>Return a formatted string</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <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> - 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> - <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"> +<refentry id="function.sprintf"> + <refnamediv> + <refname>sprintf</refname> + <refpurpose>Return a formatted string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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> + 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> + <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"> <![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,21 +195,21 @@ printf($format, $num, $location); ?> ]]> - </programlisting> - </example> - </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> - <example> - <title><function>printf</function>: various examples</title> - <programlisting role="php"> + </programlisting> + </example> + </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> + <example> + <title><function>printf</function>: various examples</title> + <programlisting role="php"> <![CDATA[ <?php $n = 43951789; @@ -233,11 +233,11 @@ printf("%%+d = '%+d'\n", $u); // sign specifier on a negative integer ?> ]]> - </programlisting> - <para> - The printout of this program would be: - </para> - <screen> + </programlisting> + <para> + The printout of this program would be: + </para> + <screen> <![CDATA[ %b = '10100111101010011010101101' %c = 'A' @@ -253,11 +253,11 @@ %+d = '+43951789' %+d = '-43951789' ]]> - </screen> - </example> - <example> - <title><function>printf</function>: string specifiers</title> - <programlisting role="php"> + </screen> + </example> + <example> + <title><function>printf</function>: string specifiers</title> + <programlisting role="php"> <![CDATA[ <?php $s = 'monkey'; @@ -271,11 +271,11 @@ printf("[%10.10s]\n", $t); // left-justification but with a cutoff of 10 characters ?> ]]> - </programlisting> - <para> - The printout of this program would be: - </para> - <screen> + </programlisting> + <para> + The printout of this program would be: + </para> + <screen> <![CDATA[ [monkey] [ monkey] @@ -284,21 +284,21 @@ [####monkey] [many monke] ]]> - </screen> - </example> - <example> - <title><function>sprintf</function>: zero-padded integers</title> - <programlisting role="php"> + </screen> + </example> + <example> + <title><function>sprintf</function>: zero-padded integers</title> + <programlisting role="php"> <![CDATA[ <?php $isodate = sprintf("%04d-%02d-%02d", $year, $month, $day); ?> ]]> - </programlisting> - </example> - <example> - <title><function>sprintf</function>: formatting currency</title> - <programlisting role="php"> + </programlisting> + </example> + <example> + <title><function>sprintf</function>: formatting currency</title> + <programlisting role="php"> <![CDATA[ <?php $money1 = 68.75; @@ -309,11 +309,11 @@ // echo $formatted will output "123.10" ?> ]]> - </programlisting> - </example> - <example> - <title><function>sprintf</function>: scientific notation</title> - <programlisting role="php"> + </programlisting> + </example> + <example> + <title><function>sprintf</function>: scientific notation</title> + <programlisting role="php"> <![CDATA[ <?php $number = 362525200; @@ -321,10 +321,10 @@ echo sprintf("%.3e", $number); // outputs 3.625e+8 ?> ]]> - </programlisting> - </example> - </refsect1> - </refentry> + </programlisting> + </example> + </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> - <methodsynopsis> - <type>mixed</type><methodname>str_ireplace</methodname> - <methodparam><type>mixed</type><parameter>search</parameter></methodparam> - <methodparam><type>mixed</type><parameter>replace</parameter></methodparam> - <methodparam><type>mixed</type><parameter>subject</parameter></methodparam> - <methodparam choice="opt"><type>int</type><parameter role="reference">count</parameter></methodparam> - </methodsynopsis> - <para> - This function returns a string or an array with all occurrences of - <parameter>search</parameter> in <parameter>subject</parameter> - (ignoring case) replaced with the given <parameter>replace</parameter> - value. If you don't need fancy replacing rules, you should generally - use this function instead of <function>eregi_replace</function> or - <function>preg_replace</function> with the <literal>i</literal> modifier. - </para> - <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 - <parameter>search</parameter>. - </para> - <note> - <para> - Every replacement with <parameter>search</parameter> array is performed - on the result of previous replacement. - </para> - </note> - <para> - <example> - <title><function>str_ireplace</function> example</title> - <programlisting role="php"> +<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> + <methodsynopsis> + <type>mixed</type><methodname>str_ireplace</methodname> + <methodparam><type>mixed</type><parameter>search</parameter></methodparam> + <methodparam><type>mixed</type><parameter>replace</parameter></methodparam> + <methodparam><type>mixed</type><parameter>subject</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter role="reference">count</parameter></methodparam> + </methodsynopsis> + <para> + This function returns a string or an array with all occurrences of + <parameter>search</parameter> in <parameter>subject</parameter> + (ignoring case) replaced with the given <parameter>replace</parameter> + value. If you don't need fancy replacing rules, you should generally + use this function instead of <function>eregi_replace</function> or + <function>preg_replace</function> with the <literal>i</literal> modifier. + </para> + <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 + <parameter>search</parameter>. + </para> + <note> + <para> + Every replacement with <parameter>search</parameter> array is performed + on the result of previous replacement. + </para> + </note> + <para> + <example> + <title><function>str_ireplace</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $bodytag = str_ireplace("%body%", "black", "<body text=%BODY%>"); ?> ]]> - </programlisting> - </example> - </para> - <para> - This function is binary safe. - </para> - <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> - </note> - <para> - See also: - <function>str_replace</function>, - <function>preg_replace</function>, and - <function>strtr</function>. - </para> - </refsect1> - </refentry> + </programlisting> + </example> + </para> + <para> + This function is binary safe. + </para> + <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> + </note> + <para> + See also: + <function>str_replace</function>, + <function>preg_replace</function>, and + <function>strtr</function>. + </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> - <methodsynopsis> - <type>string</type><methodname>str_pad</methodname> - <methodparam><type>string</type><parameter>input</parameter></methodparam> - <methodparam><type>int</type><parameter>pad_length</parameter></methodparam> - <methodparam choice="opt"><type>string</type><parameter>pad_string</parameter></methodparam> - <methodparam choice="opt"><type>int</type><parameter>pad_type</parameter></methodparam> - </methodsynopsis> - <para> - This functions returns the <parameter>input</parameter> string - padded on the left, the right, or both sides to the specified - padding length. If the optional argument - <parameter>pad_string</parameter> is not supplied, the - <parameter>input</parameter> is padded with spaces, otherwise it - is padded with characters from <parameter>pad_string</parameter> - up to the limit. - </para> - <para> - Optional argument <parameter>pad_type</parameter> can be - <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> - <para> - If the value of <parameter>pad_length</parameter> is negative or - less than the length of the input string, no padding takes place. - </para> - <para> - <example> - <title><function>str_pad</function> example</title> - <programlisting role="php"> +<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> + <methodsynopsis> + <type>string</type><methodname>str_pad</methodname> + <methodparam><type>string</type><parameter>input</parameter></methodparam> + <methodparam><type>int</type><parameter>pad_length</parameter></methodparam> + <methodparam choice="opt"><type>string</type><parameter>pad_string</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>pad_type</parameter></methodparam> + </methodsynopsis> + <para> + This functions returns the <parameter>input</parameter> string + padded on the left, the right, or both sides to the specified + padding length. If the optional argument + <parameter>pad_string</parameter> is not supplied, the + <parameter>input</parameter> is padded with spaces, otherwise it + is padded with characters from <parameter>pad_string</parameter> + up to the limit. + </para> + <para> + Optional argument <parameter>pad_type</parameter> can be + <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> + <para> + If the value of <parameter>pad_length</parameter> is negative or + less than the length of the input string, no padding takes place. + </para> + <para> + <example> + <title><function>str_pad</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $input = "Alien"; @@ -50,18 +48,18 @@ echo str_pad($input, 6 , "___"); // produces "Alien_" ?> ]]> - </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> + </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> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/strings/functions/str-rot13.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/strings/functions/str-rot13.xml diff -u phpdoc/en/reference/strings/functions/str-rot13.xml:1.5 phpdoc/en/reference/strings/functions/str-rot13.xml:1.6 --- phpdoc/en/reference/strings/functions/str-rot13.xml:1.5 Fri Jan 23 20:06:32 2004 +++ phpdoc/en/reference/strings/functions/str-rot13.xml Fri Jun 15 19:01:26 2007 @@ -1,29 +1,29 @@ <?xml version="1.0" encoding="iso-8859-1"?> - +  - <refentry id='function.str-rot13'> - <refnamediv> - <refname>str_rot13</refname> - <refpurpose>Perform the rot13 transform on a string</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <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. - </para> - <para> - <example> - <title><function>str_rot13</function> example</title> - <programlisting role="php"> +<refentry id='function.str-rot13'> + <refnamediv> + <refname>str_rot13</refname> + <refpurpose>Perform the rot13 transform on a string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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. + </para> + <para> + <example> + <title><function>str_rot13</function> example</title> + <programlisting role="php"> <![CDATA[ <?php @@ -31,18 +31,18 @@ ?> ]]> - </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> - </refentry> + </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> +</refentry>  - <refentry id="function.str-split"> - <refnamediv> - <refname>str_split</refname> - <refpurpose> - Convert a string to an array - </refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <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 - 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. - </para> - <para> - <example> - <title>Example uses of <function>str_split</function></title> - <programlisting role="php"> + +<refentry id="function.str-split"> + <refnamediv> + <refname>str_split</refname> + <refpurpose>Convert a string to an array</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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 + 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. + </para> + <para> + <example> + <title>Example uses of <function>str_split</function></title> + <programlisting role="php"> <![CDATA[ <?php @@ -44,11 +42,11 @@ ?> ]]> - </programlisting> - <para> - Output may look like: - </para> - <screen> + </programlisting> + <para> + Output may look like: + </para> + <screen> <![CDATA[ Array ( @@ -69,24 +67,24 @@ Array ( [0] => Hel - [1] => lo + [1] => lo [2] => Fri [3] => end ) ]]> - </screen> - </example> - </para> - <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>. - </para> - </refsect1> - </refentry> + </screen> + </example> + </para> + <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>. + </para> + </refsect1> +</refentry>  +  - <refentry id="function.strcasecmp"> - <refnamediv> - <refname>strcasecmp</refname> - <refpurpose> - Binary safe case-insensitive string comparison - </refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <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> - 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. - <example> - <title><function>strcasecmp</function> example</title> - <programlisting role="php"> +<refentry id="function.strcasecmp"> + <refnamediv> + <refname>strcasecmp</refname> + <refpurpose>Binary safe case-insensitive string comparison</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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> + 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. + <example> + <title><function>strcasecmp</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $var1 = "Hello"; @@ -32,20 +30,20 @@ } ?> ]]> - </programlisting> - </example> - </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> + </programlisting> + </example> + </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> - <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> - 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> - </refsect1> - </refentry> +<refentry id="function.strcmp"> + <refnamediv> + <refname>strcmp</refname> + <refpurpose>Binary safe string comparison</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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> + 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> + </refsect1> +</refentry>  +  - <refentry id="function.strcoll"> - <refnamediv> - <refname>strcoll</refname> - <refpurpose>Locale based string comparison</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <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> - 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> - </refsect1> - </refentry> +<refentry id="function.strcoll"> + <refnamediv> + <refname>strcoll</refname> + <refpurpose>Locale based string comparison</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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> + 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> + </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> - <methodsynopsis> - <type>int</type><methodname>strcspn</methodname> - <methodparam><type>string</type><parameter>str1</parameter></methodparam> - <methodparam><type>string</type><parameter>str2</parameter></methodparam> - <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 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> +<refentry id="function.strcspn"> + <refnamediv> + <refname>strcspn</refname> + <refpurpose>Find length of initial segment not matching mask</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>int</type><methodname>strcspn</methodname> + <methodparam><type>string</type><parameter>str1</parameter></methodparam> + <methodparam><type>string</type><parameter>str2</parameter></methodparam> + <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 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> - &note.bin-safe; + &note.bin-safe; - <simpara> - See also <function>strspn</function>. - </simpara> - </refsect1> - </refentry> + <simpara> + See also <function>strspn</function>. + </simpara> + </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> - <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> +<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> + <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> - 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. + <parameter>allowable_tags</parameter> was added in PHP 3.0.13 + and PHP 4.0.0. </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> + 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> - <example> - <title><function>strip_tags</function> example</title> - <programlisting role="php"> + 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> + </para> + <para> + <example> + <title><function>strip_tags</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $text = '<p>Test paragraph.</p> <a href="#fragment">Other text</a>'; @@ -63,24 +63,24 @@ echo strip_tags($text, '<p><a>'); ?> ]]> - </programlisting> - &example.outputs; - <screen> + </programlisting> + &example.outputs; + <screen> <![CDATA[ Test paragraph. Other text <p>Test paragraph.</p> <a href="#fragment">Other text</a> ]]> - </screen> - </example> - </para> - <para> - <function>strip_tags</function> has been binary safe since PHP 5.0.0 - </para> - <para> - See also <function>htmlspecialchars</function>. - </para> - </refsect1> - </refentry> + </screen> + </example> + </para> + <para> + <function>strip_tags</function> has been binary safe since PHP 5.0.0 + </para> + <para> + See also <function>htmlspecialchars</function>. + </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> - <methodsynopsis> - <type>int</type><methodname>stripos</methodname> - <methodparam><type>string</type><parameter>haystack</parameter></methodparam> - <methodparam><type>string</type><parameter>needle</parameter></methodparam> - <methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam> - </methodsynopsis> - <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. - </para> - <para> - Note that the <parameter>needle</parameter> may be a string of one or - more characters. - </para> - <para> - If <parameter>needle</parameter> is not found, - <function>stripos</function> will return <type>boolean</type> &false;. - </para> - - &return.falseproblem; - - <para> - <example> - <title><function>stripos</function> examples</title> - <programlisting role="php"> + +<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> + <methodsynopsis> + <type>int</type><methodname>stripos</methodname> + <methodparam><type>string</type><parameter>haystack</parameter></methodparam> + <methodparam><type>string</type><parameter>needle</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam> + </methodsynopsis> + <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. + </para> + <para> + Note that the <parameter>needle</parameter> may be a string of one or + more characters. + </para> + <para> + If <parameter>needle</parameter> is not found, + <function>stripos</function> will return <type>boolean</type> &false;. + </para> + + &return.falseproblem; + + <para> + <example> + <title><function>stripos</function> examples</title> + <programlisting role="php"> <![CDATA[ <?php $findme = 'a'; @@ -57,30 +55,30 @@ } ?> ]]> - </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> - - &note.bin-safe; - - <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>. - </para> - </refsect1> - </refentry> + </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> + + &note.bin-safe; + + <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>. + </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> - <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>). - </para> - <note> - <para> - If <link linkend="ini.magic-quotes-sybase">magic_quotes_sybase</link> is - on, no backslashes are stripped off but two apostrophes are replaced by - one instead. - </para> - </note> - <para> - An example use of <function>stripslashes</function> is when the PHP - 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. - </para> - <para> - <example> - <title>A <function>stripslashes</function> example</title> - <programlisting role="php"> +<refentry id="function.stripslashes"> + <refnamediv> + <refname>stripslashes</refname> + <refpurpose>Un-quote string quoted with <function>addslashes</function></refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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>). + </para> + <note> + <para> + If <link linkend="ini.magic-quotes-sybase">magic_quotes_sybase</link> is + on, no backslashes are stripped off but two apostrophes are replaced by + one instead. + </para> + </note> + <para> + An example use of <function>stripslashes</function> is when the PHP + 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. + </para> + <para> + <example> + <title>A <function>stripslashes</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $str = "Is your name O\'reilly?"; @@ -47,19 +45,19 @@ echo stripslashes($str); ?> ]]> - </programlisting> - </example> - </para> - <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. - </para> - </note> - <para> - <example> - <title>Using <function>stripslashes</function> on an array</title> - <programlisting role="php"> + </programlisting> + </example> + </para> + <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. + </para> + </note> + <para> + <example> + <title>Using <function>stripslashes</function> on an array</title> + <programlisting role="php"> <![CDATA[ <?php function stripslashes_deep($value) @@ -79,9 +77,9 @@ print_r($array); ?> ]]> - </programlisting> - &example.outputs; - <screen> + </programlisting> + &example.outputs; + <screen> <![CDATA[ Array ( @@ -95,18 +93,18 @@ ) ]]> - </screen> - </example> - </para> - <para> - For more information about "magic quotes", see <function>get_magic_quotes_gpc</function>. - </para> - <simpara> - See also <function>addslashes</function> and - <function>get_magic_quotes_gpc</function>. - </simpara> - </refsect1> - </refentry> + </screen> + </example> + </para> + <para> + For more information about "magic quotes", see <function>get_magic_quotes_gpc</function>. + </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> - <methodsynopsis> - <type>string</type><methodname>stristr</methodname> - <methodparam><type>string</type><parameter>haystack</parameter></methodparam> - <methodparam><type>string</type><parameter>needle</parameter></methodparam> - </methodsynopsis> - <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> - <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> - <para> - <example> - <title><function>stristr</function> example</title> - <programlisting role="php"> +<refentry id="function.stristr"> + <refnamediv> + <refname>stristr</refname> + <refpurpose>Case-insensitive <function>strstr</function></refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>string</type><methodname>stristr</methodname> + <methodparam><type>string</type><parameter>haystack</parameter></methodparam> + <methodparam><type>string</type><parameter>needle</parameter></methodparam> + </methodsynopsis> + <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> + <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> + <para> + <example> + <title><function>stristr</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $email = 'USER@EXAMPLE.com'; @@ -39,13 +37,13 @@ // outputs ER@EXAMPLE.com ?> ]]> - </programlisting> - </example> - </para> - <para> - <example> - <title>Testing if a string is found or not</title> - <programlisting role="php"> + </programlisting> + </example> + </para> + <para> + <example> + <title>Testing if a string is found or not</title> + <programlisting role="php"> <![CDATA[ <?php $string = 'Hello World!'; @@ -55,13 +53,13 @@ // outputs: "earth" not found in string ?> ]]> - </programlisting> - </example> - </para> - <para> - <example> - <title>Using a non "string" needle</title> - <programlisting role="php"> + </programlisting> + </example> + </para> + <para> + <example> + <title>Using a non "string" needle</title> + <programlisting role="php"> <![CDATA[ <?php $string = 'APPLE'; @@ -69,21 +67,21 @@ // outputs: APPLE ?> ]]> - </programlisting> - </example> - </para> + </programlisting> + </example> + </para> - &note.bin-safe; + &note.bin-safe; - <para> - See also - <function>strstr</function>, - <function>strrchr</function>, - <function>substr</function>, and - <function>preg_match</function>. - </para> - </refsect1> - </refentry> + <para> + See also + <function>strstr</function>, + <function>strrchr</function>, + <function>substr</function>, and + <function>preg_match</function>. + </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> - <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. - </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> - 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> - </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> + <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. + </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> + 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> + </refsect1> +</refentry>  +  - <refentry id="function.strnatcmp"> - <refnamediv> - <refname>strnatcmp</refname> - <refpurpose> - String comparisons using a "natural order" algorithm - </refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>int</type><methodname>strnatcmp</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, this is - described as a "natural ordering". An example of the difference - between this algorithm and the regular computer string sorting - algorithms (used in <function>strcmp</function>) can be seen - below: - <informalexample> - <programlisting role="php"> +<refentry id="function.strnatcmp"> + <refnamediv> + <refname>strnatcmp</refname> + <refpurpose>String comparisons using a "natural order" algorithm</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>int</type><methodname>strnatcmp</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, this is + described as a "natural ordering". An example of the difference + between this algorithm and the regular computer string sorting + algorithms (used in <function>strcmp</function>) can be seen + below: + <informalexample> + <programlisting role="php"> <![CDATA[ <?php $arr1 = $arr2 = array("img12.png", "img10.png", "img2.png", "img1.png"); @@ -35,11 +33,11 @@ print_r($arr2); ?> ]]> - </programlisting> - </informalexample> - The code above will generate the following output: - <informalexample> - <screen> + </programlisting> + </informalexample> + The code above will generate the following output: + <informalexample> + <screen> <![CDATA[ Standard string comparison Array @@ -59,32 +57,32 @@ [3] => img12.png ) ]]> - </screen> - </informalexample> - 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 - <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> - </refentry> + </screen> + </informalexample> + 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 + <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> +</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> - <methodsynopsis> - <type>int</type><methodname>strncasecmp</methodname> - <methodparam><type>string</type><parameter>str1</parameter></methodparam> - <methodparam><type>string</type><parameter>str2</parameter></methodparam> - <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> - 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> - </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> + <methodsynopsis> + <type>int</type><methodname>strncasecmp</methodname> + <methodparam><type>string</type><parameter>str1</parameter></methodparam> + <methodparam><type>string</type><parameter>str2</parameter></methodparam> + <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> + 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> + </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> - <methodsynopsis> - <type>int</type><methodname>strncmp</methodname> - <methodparam><type>string</type><parameter>str1</parameter></methodparam> - <methodparam><type>string</type><parameter>str2</parameter></methodparam> - <methodparam><type>int</type><parameter>len</parameter></methodparam> - </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. - </para> - <simpara> - 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> - </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> + <methodsynopsis> + <type>int</type><methodname>strncmp</methodname> + <methodparam><type>string</type><parameter>str1</parameter></methodparam> + <methodparam><type>string</type><parameter>str2</parameter></methodparam> + <methodparam><type>int</type><parameter>len</parameter></methodparam> + </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. + </para> + <simpara> + 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> + </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> - <methodsynopsis> - <type>int</type><methodname>strpos</methodname> - <methodparam><type>string</type><parameter>haystack</parameter></methodparam> - <methodparam><type>mixed</type><parameter>needle</parameter></methodparam> - <methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam> - </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. - </para> - <para> - If <parameter>needle</parameter> is not found, - <function>strpos</function> will return <type>boolean</type> &false;. - </para> - - &return.falseproblem; - &note.bin-safe; - <para> - <example> - <title><function>strpos</function> examples</title> - <programlisting role="php"> +<refentry id="function.strpos"> + <refnamediv> + <refname>strpos</refname> + <refpurpose>Find position of first occurrence of a string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>int</type><methodname>strpos</methodname> + <methodparam><type>string</type><parameter>haystack</parameter></methodparam> + <methodparam><type>mixed</type><parameter>needle</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam> + </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. + </para> + <para> + If <parameter>needle</parameter> is not found, + <function>strpos</function> will return <type>boolean</type> &false;. + </para> + + &return.falseproblem; + &note.bin-safe; + <para> + <example> + <title><function>strpos</function> examples</title> + <programlisting role="php"> <![CDATA[ <?php $mystring = 'abc'; @@ -55,30 +53,30 @@ $pos = strpos($newstring, 'a', 1); // $pos = 7, not 0 ?> ]]> - </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> - <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>. - </para> - </refsect1> - </refentry> + </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> + <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>. + </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> - <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>. - </para> - <para> - Returns &false; if <parameter>needle</parameter> is not found. - </para> - <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. - <example> - <title><function>strrchr</function> example</title> - <programlisting role="php"> +<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> + <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>. + </para> + <para> + Returns &false; if <parameter>needle</parameter> is not found. + </para> + <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. + <example> + <title><function>strrchr</function> example</title> + <programlisting role="php"> <![CDATA[ <?php // get last directory in $PATH @@ -45,18 +43,18 @@ $last = substr(strrchr($text, 10), 1 ); ?> ]]> - </programlisting> - </example> - </para> - <para> - <function>strrchr</function> has been binary safe since PHP 4.3.0 - </para> - <para> - See also <function>strstr</function>, <function>substr</function>, and - <function>stristr</function>. - </para> - </refsect1> - </refentry> + </programlisting> + </example> + </para> + <para> + <function>strrchr</function> has been binary safe since PHP 4.3.0 + </para> + <para> + See also <function>strstr</function>, <function>substr</function>, and + <function>stristr</function>. + </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> - <methodsynopsis> - <type>int</type><methodname>strripos</methodname> - <methodparam><type>string</type><parameter>haystack</parameter></methodparam> - <methodparam><type>string</type><parameter>needle</parameter></methodparam> - <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. - </para> - <para> - Note that the <parameter>needle</parameter> may be a string of one or - more characters. - </para> - <para> - If <parameter>needle</parameter> is not found, &false; is returned. - </para> - - &return.falseproblem; - - <para> - <example> - <title>A simple <function>strripos</function> example</title> - <programlisting role="php"> + +<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> + <methodsynopsis> + <type>int</type><methodname>strripos</methodname> + <methodparam><type>string</type><parameter>haystack</parameter></methodparam> + <methodparam><type>string</type><parameter>needle</parameter></methodparam> + <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. + </para> + <para> + Note that the <parameter>needle</parameter> may be a string of one or + more characters. + </para> + <para> + If <parameter>needle</parameter> is not found, &false; is returned. + </para> + + &return.falseproblem; + + <para> + <example> + <title>A simple <function>strripos</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $haystack = 'ababcd'; @@ -52,35 +50,35 @@ } ?> ]]> - </programlisting> - <para> - Outputs: - </para> - <screen> + </programlisting> + <para> + Outputs: + </para> + <screen> <![CDATA[ Congratulations! We found the last (aB) in (ababcd) at position (2) ]]> - </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>. - </para> - </refsect1> - </refentry> + </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>. + </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> - <methodsynopsis> - <type>int</type><methodname>strrpos</methodname> - <methodparam><type>string</type><parameter>haystack</parameter></methodparam> - <methodparam><type>string</type><parameter>needle</parameter></methodparam> - <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. Note that the needle in - this case can only be a single character in PHP 4. If a string is passed - as the needle, then only the first character of that string will - be used. - </para> - <para> - If <parameter>needle</parameter> is not found, returns &false;. - </para> - <para> - It is easy to mistake the return values for "character found at - position 0" and "character not found". Here's how to detect - the difference: - <informalexample> - <programlisting role="php"> +<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> + <methodsynopsis> + <type>int</type><methodname>strrpos</methodname> + <methodparam><type>string</type><parameter>haystack</parameter></methodparam> + <methodparam><type>string</type><parameter>needle</parameter></methodparam> + <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. Note that the needle in + this case can only be a single character in PHP 4. If a string is passed + as the needle, then only the first character of that string will + be used. + </para> + <para> + If <parameter>needle</parameter> is not found, returns &false;. + </para> + <para> + It is easy to mistake the return values for "character found at + position 0" and "character not found". Here's how to detect + the difference: + <informalexample> + <programlisting role="php"> <![CDATA[ <?php @@ -49,37 +47,37 @@ } ?> ]]> - </programlisting> - </informalexample> - </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> - <simpara> - As of PHP 5.0.0 <parameter>offset</parameter> may - be specified to begin searching an arbitrary number of characters into - the string. Negative values will stop searching at an arbitrary point - prior to the end of the string. - </simpara> - </note> - <note> - <simpara> - The <parameter>needle</parameter> may be a string of more than one - character as of PHP 5.0.0. - </simpara> - </note> - <para> - See also <function>strpos</function>, - <function>strripos</function>, - <function>strrchr</function>, - <function>substr</function>, - <function>stristr</function>, and - <function>strstr</function>. - </para> - </refsect1> - </refentry> + </programlisting> + </informalexample> + </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> + <simpara> + As of PHP 5.0.0 <parameter>offset</parameter> may + be specified to begin searching an arbitrary number of characters into + the string. Negative values will stop searching at an arbitrary point + prior to the end of the string. + </simpara> + </note> + <note> + <simpara> + The <parameter>needle</parameter> may be a string of more than one + character as of PHP 5.0.0. + </simpara> + </note> + <para> + See also <function>strpos</function>, + <function>strripos</function>, + <function>strrchr</function>, + <function>substr</function>, + <function>stristr</function>, and + <function>strstr</function>. + </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> - <methodsynopsis> - <type>int</type><methodname>strspn</methodname> - <methodparam><type>string</type><parameter>str1</parameter></methodparam> - <methodparam><type>string</type><parameter>str2</parameter></methodparam> - <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> - The line of code: - <informalexample> - <programlisting role="php"> +<refentry id="function.strspn"> + <refnamediv> + <refname>strspn</refname> + <refpurpose>Find length of initial segment matching mask</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>int</type><methodname>strspn</methodname> + <methodparam><type>string</type><parameter>str1</parameter></methodparam> + <methodparam><type>string</type><parameter>str2</parameter></methodparam> + <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> + The line of code: + <informalexample> + <programlisting role="php"> <![CDATA[ <?php $var = strspn("42 is the answer, what is the question ...", "1234567890"); ?> ]]> - </programlisting> - </informalexample> - 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> - <para> - <informalexample> - <programlisting role="php"> + </programlisting> + </informalexample> + 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> + <para> + <informalexample> + <programlisting role="php"> <![CDATA[ <?php echo strspn("foo", "o", 1, 2); // 2 ?> ]]> - </programlisting> - </informalexample> - </para> + </programlisting> + </informalexample> + </para> - &note.bin-safe; + &note.bin-safe; - <simpara> - See also <function>strcspn</function>. - </simpara> - </refsect1> - </refentry> + <simpara> + See also <function>strcspn</function>. + </simpara> + </refsect1> +</refentry>  +  - <refentry id="function.strstr"> - <refnamediv> - <refname>strstr</refname> - <refpurpose>Find first occurrence of a string</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <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 - <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> - <para> - <example> - <title><function>strstr</function> example</title> - <programlisting role="php"> +<refentry id="function.strstr"> + <refnamediv> + <refname>strstr</refname> + <refpurpose>Find first occurrence of a string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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 + <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> + <para> + <example> + <title><function>strstr</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $email = 'user@example.com'; @@ -42,28 +42,28 @@ echo $domain; // prints @example.com ?> ]]> - </programlisting> - </example> - </para> - <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>. - </para> - </refsect1> - </refentry> + </programlisting> + </example> + </para> + <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>. + </para> + </refsect1> +</refentry>  +  - <refentry id="function.strtolower"> - <refnamediv> - <refname>strtolower</refname> - <refpurpose>Make a string lowercase</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <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. - </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. - </para> - <example> - <title><function>strtolower</function> example</title> - <programlisting role="php"> +<refentry id="function.strtolower"> + <refnamediv> + <refname>strtolower</refname> + <refpurpose>Make a string lowercase</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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. + </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. + </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,17 +31,17 @@ echo $str; // Prints mary had a little lamb and she loved it so ?> ]]> - </programlisting> - </example> + </programlisting> + </example> - &note.bin-safe; + &note.bin-safe; - <para> - See also <function>strtoupper</function>, <function>ucfirst</function>, - <function>ucwords</function> and <function>mb_strtolower</function>. - </para> - </refsect1> - </refentry> + <para> + See also <function>strtoupper</function>, <function>ucfirst</function>, + <function>ucwords</function> and <function>mb_strtolower</function>. + </para> + </refsect1> +</refentry>  +  - <refentry id="function.strtoupper"> - <refnamediv> - <refname>strtoupper</refname> - <refpurpose>Make a string uppercase</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <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. - </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. - </para> - <example> - <title><function>strtoupper</function> example</title> - <programlisting role="php"> +<refentry id="function.strtoupper"> + <refnamediv> + <refname>strtoupper</refname> + <refpurpose>Make a string uppercase</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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. + </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. + </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,17 +31,17 @@ echo $str; // Prints MARY HAD A LITTLE LAMB AND SHE LOVED IT SO ?> ]]> - </programlisting> - </example> + </programlisting> + </example> - &note.bin-safe; + &note.bin-safe; - <para> - See also <function>strtolower</function>, <function>ucfirst</function>, - <function>ucwords</function> and <function>mb_strtoupper</function>. - </para> - </refsect1> - </refentry> + <para> + See also <function>strtolower</function>, <function>ucfirst</function>, + <function>ucwords</function> and <function>mb_strtoupper</function>. + </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> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>int</type><methodname>substr_compare</methodname> - <methodparam><type>string</type><parameter>main_str</parameter></methodparam> - <methodparam><type>string</type><parameter>str</parameter></methodparam> - <methodparam><type>int</type><parameter>offset</parameter></methodparam> - <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam> - <methodparam choice="opt"><type>bool</type><parameter>case_insensitivity</parameter></methodparam> - </methodsynopsis> + +<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> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>int</type><methodname>substr_compare</methodname> + <methodparam><type>string</type><parameter>main_str</parameter></methodparam> + <methodparam><type>string</type><parameter>str</parameter></methodparam> + <methodparam><type>int</type><parameter>offset</parameter></methodparam> + <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> - <para> - Returns < 0 if <parameter>main_str</parameter> from position - <parameter>offset</parameter> is less than <parameter>str</parameter>, > - 0 if it is greater than <parameter>str</parameter>, and 0 if they are equal. - If <parameter>length</parameter> is equal or greater than length of - <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> - <para> - <example> - <title>A <function>substr_compare</function> example</title> - <programlisting role="php"> + <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> + <para> + Returns < 0 if <parameter>main_str</parameter> from position + <parameter>offset</parameter> is less than <parameter>str</parameter>, > + 0 if it is greater than <parameter>str</parameter>, and 0 if they are equal. + If <parameter>length</parameter> is equal or greater than length of + <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> + <para> + <example> + <title>A <function>substr_compare</function> example</title> + <programlisting role="php"> <![CDATA[ <?php echo substr_compare("abcde", "bc", 1, 2); // 0 @@ -49,12 +47,12 @@ echo substr_compare("abcde", "abc", 5, 1); // warning ?> ]]> - </programlisting> - </example> - </para> + </programlisting> + </example> + </para> - </refsect1> - </refentry> + </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> - <methodsynopsis> - <type>mixed</type><methodname>substr_replace</methodname> - <methodparam><type>mixed</type><parameter>string</parameter></methodparam> - <methodparam><type>string</type><parameter>replacement</parameter></methodparam> - <methodparam><type>int</type><parameter>start</parameter></methodparam> - <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam> - </methodsynopsis> - <para> - <function>substr_replace</function> replaces a copy of - <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>. - </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> - <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. - </para> - <para> - <example> - <title><function>substr_replace</function> example</title> - <programlisting role="php"> +<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> + <methodsynopsis> + <type>mixed</type><methodname>substr_replace</methodname> + <methodparam><type>mixed</type><parameter>string</parameter></methodparam> + <methodparam><type>string</type><parameter>replacement</parameter></methodparam> + <methodparam><type>int</type><parameter>start</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam> + </methodsynopsis> + <para> + <function>substr_replace</function> replaces a copy of + <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>. + </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> + <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. + </para> + <para> + <example> + <title><function>substr_replace</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $var = 'ABCDEFGH:/MNRPQR/'; @@ -71,18 +71,18 @@ echo substr_replace($var, '', 10, -1) . "<br />\n"; ?> ]]> - </programlisting> - </example> - </para> - - &note.bin-safe; - - <para> - See also <function>str_replace</function> and - <function>substr</function>. - </para> - </refsect1> - </refentry> + </programlisting> + </example> + </para> + + &note.bin-safe; + + <para> + See also <function>str_replace</function> and + <function>substr</function>. + </para> + </refsect1> +</refentry>  +  - <refentry id="function.substr"> - <refnamediv> - <refname>substr</refname> - <refpurpose>Return part of a string</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>string</type><methodname>substr</methodname> - <methodparam><type>string</type><parameter>string</parameter></methodparam> - <methodparam><type>int</type><parameter>start</parameter></methodparam> - <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. - </para> - <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> - <example> - <title>Basic <function>substr</function> usage</title> - <programlisting role="php"> +<refentry id="function.substr"> + <refnamediv> + <refname>substr</refname> + <refpurpose>Return part of a string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>string</type><methodname>substr</methodname> + <methodparam><type>string</type><parameter>string</parameter></methodparam> + <methodparam><type>int</type><parameter>start</parameter></methodparam> + <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. + </para> + <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> + <example> + <title>Basic <function>substr</function> usage</title> + <programlisting role="php"> <![CDATA[ <?php echo substr('abcdef', 1); // bcdef @@ -48,16 +48,16 @@ ?> ]]> - </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"> + </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" @@ -65,27 +65,27 @@ $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. - </para> - <example> - <title>Using a negative <parameter>length</parameter></title> - <programlisting role="php"> + </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. + </para> + <example> + <title>Using a negative <parameter>length</parameter></title> + <programlisting role="php"> <![CDATA[ <?php $rest = substr("abcdef", 0, -1); // returns "abcde" @@ -94,18 +94,18 @@ $rest = substr("abcdef", -3, -1); // returns "de" ?> ]]> - </programlisting> - </example> - <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>. - </para> - </refsect1> - </refentry> + </programlisting> + </example> + <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>. + </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> - <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. - </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> - <example> - <title><function>ucwords</function> example</title> - <programlisting role="php"> +<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> + <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. + </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> + <example> + <title><function>ucwords</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $foo = 'hello world!'; -$foo = ucwords($foo); // Hello World! +$foo = ucwords($foo); // Hello World! $bar = 'HELLO WORLD!'; $bar = ucwords($bar); // HELLO WORLD! $bar = ucwords(strtolower($bar)); // Hello World! ?> ]]> - </programlisting> - </example> - </para> + </programlisting> + </example> + </para> - &note.bin-safe; + &note.bin-safe; - <para> - See also <function>strtoupper</function>, - <function>strtolower</function> and <function>ucfirst</function>. - </para> - </refsect1> - </refentry> + <para> + See also <function>strtoupper</function>, + <function>strtolower</function> and <function>ucfirst</function>. + </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> - <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> - Operates as <function>fprintf</function> but accepts an array of - arguments, rather than a variable number of arguments. - </simpara> - <simpara> - 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> - </refsect1> - <refsect1> - <title>Examples</title> - <para> - <example> - <title><function>vfprintf</function>: zero-padded integers</title> - <programlisting role="php"> + +<refentry id="function.vfprintf"> + <refnamediv> + <refname>vfprintf</refname> + <refpurpose>Write a formatted string to a stream</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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> + Operates as <function>fprintf</function> but accepts an array of + arguments, rather than a variable number of arguments. + </simpara> + <simpara> + 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> + </refsect1> + <refsect1> + <title>Examples</title> + <para> + <example> + <title><function>vfprintf</function>: zero-padded integers</title> + <programlisting role="php"> <![CDATA[ <?php if (!($fp = fopen('date.txt', 'w'))) @@ -49,11 +49,11 @@ // will write the formatted ISO date to date.txt ?> ]]> - </programlisting> - </example> - </para> - </refsect1> - </refentry> + </programlisting> + </example> + </para> + </refsect1> +</refentry>  +  - <refentry id="function.vprintf"> - <refnamediv> - <refname>vprintf</refname> - <refpurpose>Output a formatted string</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <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> - Display 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>printf</function> but accepts an array of - arguments, rather than a variable number of arguments. - </simpara> - <simpara> - Returns the length of the outputted string. - </simpara> - <simpara> - See also <function>printf</function>, <function>sprintf</function>, - <function>vsprintf</function> - </simpara> - </refsect1> - </refentry> +<refentry id="function.vprintf"> + <refnamediv> + <refname>vprintf</refname> + <refpurpose>Output a formatted string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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> + Display 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>printf</function> but accepts an array of + arguments, rather than a variable number of arguments. + </simpara> + <simpara> + Returns the length of the outputted string. + </simpara> + <simpara> + See also <function>printf</function>, <function>sprintf</function>, + <function>vsprintf</function> + </simpara> + </refsect1> +</refentry>  +  - <refentry id="function.vsprintf"> - <refnamediv> - <refname>vsprintf</refname> - <refpurpose>Return a formatted string</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <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> - 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> - </refsect1> - </refentry> +<refentry id="function.vsprintf"> + <refnamediv> + <refname>vsprintf</refname> + <refpurpose>Return a formatted string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <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> + 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> + </refsect1> +</refentry> <!-- Keep this comment at the end of the file Local variables: