eschmid Sat Aug 25 19:01:29 2001 EDT
Modified files:
/phpdoc/en/functions strings.xml
Log:
Only whitespace changes.
Index: phpdoc/en/functions/strings.xml
diff -u phpdoc/en/functions/strings.xml:1.105 phpdoc/en/functions/strings.xml:1.106
--- phpdoc/en/functions/strings.xml:1.105 Sat Aug 25 17:08:41 2001
+++ phpdoc/en/functions/strings.xml Sat Aug 25 19:01:28 2001
@@ -1,5 +1,5 @@
<?xml encoding="iso-8859-1"?>
-<!-- $Revision: 1.105 $ -->
+<!-- $Revision: 1.106 $ -->
<reference id="ref.strings">
<title>String functions</title>
<titleabbrev>Strings</titleabbrev>
@@ -10,7 +10,6 @@
specialized sections can be found in the regular expression and
URL handling sections.
</simpara>
-
<para>
For information on how strings behave, especially with regard to
usage of single quotes, double quotes, and escape sequences, see
@@ -58,23 +57,23 @@
$escaped = addcslashes($not_escaped, "\0..\37!@\177..\377");
</programlisting>
</example>
- </para>
- <para>
- When you define a sequence of characters in the charlist argument
- make sure that you know what characters come between the characters
- that you set as the start and end of the range.
+ </para>
+ <para>
+ When you define a sequence of characters in the charlist argument
+ make sure that you know what characters come between the
+ characters that you set as the start and end of the range.
<informalexample>
<programlisting role="php">
echo addcslashes('foo[]', 'A..z');
// All upper and lower-case letters will be escaped
-// ..but so will the [\]^_` and space characters.
+// ... but so will the [\]^_` and space characters.
</programlisting>
</informalexample>
-
- Also, if the first character in a range has a lower ASCII value
- than the second character in the range, no range will be constructed.
- Only the start, end and period characters will be escaped. Use the
- <function>ord</function> function to find the ASCII value for a character.
+ Also, if the first character in a range has a lower ASCII value
+ than the second character in the range, no range will be
+ constructed. Only the start, end and period characters will be
+ escaped. Use the <function>ord</function> function to find the
+ ASCII value for a character.
<informalexample>
<programlisting role="php">
echo addcslashes("zoo['.']", 'z..A');
@@ -84,7 +83,6 @@
*/
</programlisting>
</informalexample>
-
<note>
<simpara>
Added in PHP 4</simpara>
@@ -393,13 +391,13 @@
</funcprototype>
</funcsynopsis>
<para>
- Generates the cyclic redundancy checksum polynomial of 32-bit lengths of
- the <parameter>str</parameter>. This is usually used to validate the
- integrity of data being transmitted.
- </para>
- <para>
- See also: <function>md5</function>
- </para>
+ Generates the cyclic redundancy checksum polynomial of 32-bit
+ lengths of the <parameter>str</parameter>. This is usually used
+ to validate the integrity of data being transmitted.
+ </para>
+ <para>
+ See also: <function>md5</function>
+ </para>
</refsect1>
</refentry>
@@ -488,7 +486,7 @@
uses a one-way algorithm.
</simpara>
<simpara>
- See also: <function>md5</function>.
+ See also: <function>md5</function>.
</simpara>
</refsect1>
</refentry>
@@ -591,21 +589,24 @@
</funcsynopsis>
<para>
Returns an array of strings, each of which is a substring of
- <parameter>string</parameter> formed by splitting it on boundaries formed
- by the string <parameter>separator</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 whole rest of <parameter>string</parameter>.
- If an empty string ("") is used as the <parameter>separator</parameter>
- argument, then <function>explode</function> will return &false;.
- If <parameter>separator</parameter> contains a value that is not contained in
- the <parameter>string</parameter> argument, then<function>explode</function>
- will return the <parameter>string</parameter> argument.
+ <parameter>string</parameter> formed by splitting it on
+ boundaries formed by the string <parameter>separator</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 whole rest of
+ <parameter>string</parameter>. If an empty string ("") is used
+ as the <parameter>separator</parameter> argument, then
+ <function>explode</function> will return &false;. If
+ <parameter>separator</parameter> contains a value that is not
+ contained in the <parameter>string</parameter> argument,
+ then<function>explode</function> will return the
+ <parameter>string</parameter> argument.
</para>
<note>
<para>
- The <parameter>limit</parameter> parameter was added in PHP 4.0.1
- </para>
+ The <parameter>limit</parameter> parameter was added in PHP
+ 4.0.1
+ </para>
</note>
<para>
<example>
@@ -629,7 +630,7 @@
See also
<function>preg_split</function>,
<function>spliti</function>,
- <function>split</function> and
+ <function>split</function>, and
<function>implode</function>.
</para>
</refsect1>
@@ -652,7 +653,9 @@
<function>get_html_translation_table</function>
</funcdef>
<paramdef>int <parameter>table</parameter></paramdef>
- <paramdef>int <parameter><optional>quote_style</optional></parameter></paramdef>
+ <paramdef>int
+ <parameter><optional>quote_style</optional></parameter>
+ </paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -663,10 +666,11 @@
(<parameter>HTML_ENTITIES</parameter>,
<parameter>HTML_SPECIALCHARS</parameter>) that allow you to
specify the table you want. And as in the
- <function>htmlspecialchars</function> and
- <function>htmlentities</function> functions you can optionally specify the
- quote_style you are working with. The default is ENT_COMPAT mode. See
- the description of these modes in <function>htmlspecialchars</function>.
+ <function>htmlspecialchars</function> and
+ <function>htmlentities</function> functions you can optionally
+ specify the quote_style you are working with. The default is
+ ENT_COMPAT mode. See the description of these modes in
+ <function>htmlspecialchars</function>.
<example>
<title>Translation Table Example</title>
<programlisting role="php">
@@ -767,16 +771,16 @@
<funcdef>string <function>hebrev</function></funcdef>
<paramdef>string <parameter>hebrew_text</parameter></paramdef>
<paramdef>int
- <parameter><optional>max_chars_per_line</optional></parameter>
- </paramdef>
+ <parameter><optional>max_chars_per_line</optional></parameter>
+ </paramdef>
</funcprototype>
</funcsynopsis>
<para>
- The optional parameter <parameter>max_chars_per_line</parameter>
- indicates maximum number of characters per line will be output. The
- function tries to avoid breaking words.
+ The optional parameter <parameter>max_chars_per_line</parameter>
+ indicates maximum number of characters per line will be
+ output. The function tries to avoid breaking words.
</para>
- <para>
+ <para>
See also <function>hebrevc</function>
</para>
</refsect1>
@@ -796,18 +800,18 @@
<funcdef>string <function>hebrevc</function></funcdef>
<paramdef>string <parameter>hebrew_text</parameter></paramdef>
<paramdef>int
- <parameter><optional>max_chars_per_line</optional></parameter>
- </paramdef>
+ <parameter><optional>max_chars_per_line</optional></parameter>
+ </paramdef>
</funcprototype>
</funcsynopsis>
<para>
- This function is similar to <function>hebrev</function> with the
- difference that it converts newlines (\n) to "<br>\n".
- The optional parameter <parameter>max_chars_per_line</parameter>
- indicates maximum number of characters per line will be output. The
- function tries to avoid breaking words.
+ 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 will be
+ output. The function tries to avoid breaking words.
</para>
- <para>
+ <para>
See also <function>hebrev</function>
</para>
</refsect1>
@@ -826,7 +830,9 @@
<funcprototype>
<funcdef>string <function>htmlentities</function></funcdef>
<paramdef>string <parameter>string</parameter></paramdef>
- <paramdef>int <parameter><optional>quote_style</optional></parameter></paramdef>
+ <paramdef>int
+ <parameter><optional>quote_style</optional></parameter>
+ </paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -843,8 +849,8 @@
both double and single quotes unconverted.
</para>
<para>
- At present, the ISO-8859-1 character set is used. Note that the optional
- second argument was added in PHP 3.0.17 and PHP 4.0.3.
+ At present, the ISO-8859-1 character set is used. Note that the
+ optional second argument was added in PHP 3.0.17 and PHP 4.0.3.
</para>
<para>
See also <function>htmlspecialchars</function> and
@@ -866,7 +872,9 @@
<funcprototype>
<funcdef>string <function>htmlspecialchars</function></funcdef>
<paramdef>string <parameter>string</parameter></paramdef>
- <paramdef>int <parameter><optional>quote_style</optional></parameter></paramdef>
+ <paramdef>int
+ <parameter><optional>quote_style</optional></parameter>
+ </paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -881,13 +889,13 @@
<simpara>
This function is useful in preventing user-supplied text from
containing HTML markup, such as in a message board or guest book
- application. The optional second argument, quote_style, tells the
- function what to do with single and double quote characters. The
- default mode, ENT_COMPAT, is the backwards compatible mode which only
- translates the double-quote character and leaves the single-quote
- untranslated. If ENT_QUOTES is set, both single and double quotes
- are translated and if ENT_NOQUOTES is set neither single nor double quotes
- are translated.
+ application. The optional second argument, quote_style, tells
+ the function what to do with single and double quote characters.
+ The default mode, ENT_COMPAT, is the backwards compatible mode
+ which only translates the double-quote character and leaves the
+ single-quote untranslated. If ENT_QUOTES is set, both single and
+ double quotes are translated and if ENT_NOQUOTES is set neither
+ single nor double quotes are translated.
</simpara>
<para>
The translations performed are:
@@ -899,12 +907,14 @@
</listitem>
<listitem>
<simpara>
- '"' (double quote) becomes '&quot;' when ENT_NOQUOTES is not set.
+ '"' (double quote) becomes '&quot;' when ENT_NOQUOTES
+ is not set.
</simpara>
</listitem>
<listitem>
<simpara>
- ''' (single quote) becomes '&#039;' only when ENT_QUOTES is set.
+ ''' (single quote) becomes '&#039;' only when
+ ENT_QUOTES is set.
</simpara>
</listitem>
<listitem>
@@ -928,8 +938,8 @@
<para>
Note that this function does not translate anything beyond what
is listed above. For full entity translation, see
- <function>htmlentities</function>. Also note that the optional second
- argument was added in PHP 3.0.17 and PHP 4.0.3.
+ <function>htmlentities</function>. Also note that the optional
+ second argument was added in PHP 3.0.17 and PHP 4.0.3.
</para>
<para>
See also <function>htmlentities</function> and
@@ -1015,22 +1025,22 @@
<funcsynopsis>
<funcprototype>
<funcdef>int <function>levenshtein</function></funcdef>
- <paramdef>string <parameter>str1</parameter></paramdef>
- <paramdef>string <parameter>str2</parameter></paramdef>
- </funcprototype>
- <funcprototype>
- <funcdef>int <function>levenshtein</function></funcdef>
- <paramdef>string <parameter>str1</parameter></paramdef>
- <paramdef>string <parameter>str2</parameter></paramdef>
- <paramdef>int <parameter>cost_ins</parameter></paramdef>
- <paramdef>int <parameter>cost_rep</parameter></paramdef>
- <paramdef>int <parameter>cost_del</parameter></paramdef>
- </funcprototype>
- <funcprototype>
- <funcdef>int <function>levenshtein</function></funcdef>
- <paramdef>string <parameter>str1</parameter></paramdef>
- <paramdef>string <parameter>str2</parameter></paramdef>
- <paramdef>function <parameter>cost</parameter></paramdef>
+ <paramdef>string <parameter>str1</parameter></paramdef>
+ <paramdef>string <parameter>str2</parameter></paramdef>
+ </funcprototype>
+ <funcprototype>
+ <funcdef>int <function>levenshtein</function></funcdef>
+ <paramdef>string <parameter>str1</parameter></paramdef>
+ <paramdef>string <parameter>str2</parameter></paramdef>
+ <paramdef>int <parameter>cost_ins</parameter></paramdef>
+ <paramdef>int <parameter>cost_rep</parameter></paramdef>
+ <paramdef>int <parameter>cost_del</parameter></paramdef>
+ </funcprototype>
+ <funcprototype>
+ <funcdef>int <function>levenshtein</function></funcdef>
+ <paramdef>string <parameter>str1</parameter></paramdef>
+ <paramdef>string <parameter>str2</parameter></paramdef>
+ <paramdef>function <parameter>cost</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -1051,81 +1061,81 @@
<function>similar_text</function>, which is O(max(n,m)**3),
but still expensive).
</para>
- <para>
- In its simplest form the function will take only the two
+ <para>
+ In its simplest form the function will take only the two
strings as parameter and will calculate just the number of
insert, replace and delete operations needed to transform
<parameter>str1</parameter> into <parameter>str2</parameter>.
</para>
- <para>
- A second variant will take three additional parameters that
- define the cost of insert, replace and delete operations.
- This is more general and adaptive than variant one, but not
- as efficient.
- </para>
- <para>
- The third variant (which is not implemented yet) will be
- the most general and adaptive, but also the slowest alternative.
- It will call a user-supplied function that will determine the
- cost for every possible operation.
- </para>
- <para>
- The user-supplied function will be called with the following
+ <para>
+ A second variant will take three additional parameters that
+ define the cost of insert, replace and delete operations. This
+ is more general and adaptive than variant one, but not as
+ efficient.
+ </para>
+ <para>
+ The third variant (which is not implemented yet) will be the most
+ general and adaptive, but also the slowest alternative. It will
+ call a user-supplied function that will determine the cost for
+ every possible operation.
+ </para>
+ <para>
+ The user-supplied function will be called with the following
arguments:
<itemizedlist>
<listitem>
<simpara>
- operation to apply: 'I', 'R' or 'D'
+ operation to apply: 'I', 'R' or 'D'
</simpara>
</listitem>
<listitem>
<simpara>
- actual character in string 1
+ actual character in string 1
</simpara>
</listitem>
<listitem>
<simpara>
- actual character in string 2
+ actual character in string 2
</simpara>
</listitem>
<listitem>
<simpara>
- position in string 1
+ position in string 1
</simpara>
</listitem>
<listitem>
<simpara>
- position in string 2
+ position in string 2
</simpara>
</listitem>
<listitem>
<simpara>
- remaining characters in string 1
+ remaining characters in string 1
</simpara>
</listitem>
<listitem>
<simpara>
- remaining characters in string 2
+ remaining characters in string 2
</simpara>
</listitem>
</itemizedlist>
- The user-supplied function has to return a positive integer
- describing the cost for this particular operation, but it
- may decide to use only some of the supplied arguments.
- </para>
- <para>
- The user-supplied function approach offers the possibility to
- take into account the relevance of and/or difference between
+ The user-supplied function has to return a positive integer
+ describing the cost for this particular operation, but it may
+ decide to use only some of the supplied arguments.
+ </para>
+ <para>
+ The user-supplied function approach offers the possibility to
+ take into account the relevance of and/or difference between
certain symbols (characters) or even the context those symbols
- appear in to determine the cost of insert, replace and delete
+ appear in to determine the cost of insert, replace and delete
operations, but at the cost of losing all optimizations done
regarding cpu register utilization and cache misses that have
- been worked into the other two variants.
- </para>
+ been worked into the other two variants.
+ </para>
<para>
- See also <function>soundex</function>,
- <function>similar_text</function>
- and <function>metaphone</function>.
+ See also <function>soundex</function>,
+ <function>similar_text</function>, and
+ <function>metaphone</function>.
</para>
</refsect1>
</refentry>
@@ -1144,8 +1154,8 @@
</funcprototype>
</funcsynopsis>
<para>
- Returns an associative array containing localized numeric and monetary
- formatting information.
+ Returns an associative array containing localized numeric and
+ monetary formatting information.
</para>
<para>
<function>localeconv</function> returns data based upon the current locale
@@ -1210,68 +1220,103 @@
</row>
<row>
<entry>p_cs_precedes</entry>
- <entry>&true; if currency_symbol precedes a positive value, &false; if it
succeeds one</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>
+ <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>
+ <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 columns="2" type="horiz">
- <member>0</member>
- <member>Parentheses surround the quantity and currency_symbol</member>
- <member>1</member>
- <member>The sign string precedes the quantity and currency_symbol</member>
- <member>2</member>
- <member>The sign string succeeds the quantity and currency_symbol</member>
- <member>3</member>
- <member>The sign string immediately precedes the currency_symbol</member>
- <member>4</member>
- <member>The sign string immediately succeeds the currency_symbol</member>
- </simplelist>
- </entry>
+ &true; if a space separates currency_symbol from a negative
+ value, &false; otherwise
+ </entry>
</row>
<row valign="top">
- <entry>n_sign_posn</entry>
+ <entry>p_sign_posn</entry>
<entry>
- <simplelist columns="2" type="horiz">
- <member>0</member>
- <member>Parentheses surround the quantity and currency_symbol</member>
- <member>1</member>
- <member>The sign string precedes the quantity and currency_symbol</member>
- <member>2</member>
- <member>The sign string succeeds the quantity and currency_symbol</member>
- <member>3</member>
- <member>The sign string immediately precedes the currency_symbol</member>
- <member>4</member>
- <member>The sign string immediately succeeds the currency_symbol</member>
- </simplelist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- The grouping fields contain arrays that define the way numbers should be grouped.
- For example, the grouping field for the en_US locale, 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 CHAR_MAX, no further grouping is
done.
- If an array element is equal to 0, the previous element should be used.
+
+<!-- something wrong with the indentation -->
+
+ <simplelist columns="2" type="horiz">
+ <member>0</member>
+ <member>
+ Parentheses surround the quantity and currency_symbol</member>
+ <member>1</member>
+ <member>
+ The sign string precedes the quantity and currency_symbol
+ </member>
+ <member>2</member>
+ <member>
+ The sign string succeeds the quantity and currency_symbol
+ </member>
+ <member>3</member>
+ <member>
+ The sign string immediately precedes the currency_symbol
+ </member>
+ <member>4</member>
+ <member>
+ The sign string immediately succeeds the currency_symbol
+ </member>
+ </simplelist>
+ </entry>
+ </row>
+ <row valign="top">
+ <entry>n_sign_posn</entry>
+ <entry>
+ <simplelist columns="2" type="horiz">
+ <member>0</member>
+ <member>
+ Parentheses surround the quantity and currency_symbol
+ </member>
+ <member>1</member>
+ <member>
+ The sign string precedes the quantity and currency_symbol
+ </member>
+ <member>2</member>
+ <member>
+ The sign string succeeds the quantity and currency_symbol
+ </member>
+ <member>3</member>
+ <member>
+ The sign string immediately precedes the currency_symbol
+ </member>
+ <member>4</member>
+ <member>The sign string immediately succeeds the currency_symbol
+ </member>
+ </simplelist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ The grouping fields contain arrays that define the way numbers
+ should be grouped. For example, the grouping field for the en_US
+ locale, 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 CHAR_MAX, 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">
+ <example>
+ <title><function>localeconv</function> example</title>
+ <programlisting role="php">
setlocale(LC_ALL, "en_US");
$locale_info = localeconv();
@@ -1296,8 +1341,8 @@
echo "p_sign_posn: {$locale_info["p_sign_posn"]}\n";
echo "n_sign_posn: {$locale_info["n_sign_posn"]}\n";
echo "</PRE>\n";
- </programlisting>
- </example>
+ </programlisting>
+ </example>
<para>
The constant CHAR_MAX is also defined for the use mentioned above.
</para>
@@ -1311,7 +1356,7 @@
</para>
</refsect1>
</refentry>
-
+
<!-- this section is nearly-identical to trim, ltrim and rtrim -->
<refentry id="function.ltrim">
<refnamediv>
@@ -1357,7 +1402,7 @@
<listitem>
<simpara>
"\n" (<acronym>ASCII</acronym> <literal>13</literal>
- (<literal>0x0A</literal>)), a new line.(new line NL)
+ (<literal>0x0A</literal>)), a new line (line feed).
</simpara>
</listitem>
<listitem>
@@ -1436,9 +1481,9 @@
<ulink url="&url.rfc;rfc1321.html">RSA Data Security, Inc.
MD5 Message-Digest Algorithm</ulink>, and returns that hash.
</para>
- <para>
- See also: <function>crc32</function>
- </para>
+ <para>
+ See also: <function>crc32</function>
+ </para>
</refsect1>
</refentry>
@@ -1482,7 +1527,9 @@
<refentry id="function.nl2br">
<refnamediv>
<refname>nl2br</refname>
- <refpurpose>Inserts HTML line breaks before all newlines in a string</refpurpose>
+ <refpurpose>
+ Inserts HTML line breaks before all newlines in a string
+ </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -1559,7 +1606,10 @@
<funcprototype>
<funcdef>void <function>parse_str</function></funcdef>
<paramdef>string <parameter>str</parameter></paramdef>
- <paramdef>array <parameter><optional>arr</optional></parameter></paramdef>
+ <paramdef>array
+ <parameter><optional>arr</optional>
+ </parameter>
+ </paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -1797,7 +1847,9 @@
<refentry id="function.sscanf">
<refnamediv>
<refname>sscanf</refname>
- <refpurpose>Parses input from a string according to a format</refpurpose>
+ <refpurpose>
+ Parses input from a string according to a format
+ </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -1867,8 +1919,9 @@
</funcprototype>
</funcsynopsis>
<para>
- <parameter>Category</parameter> is a named constant (or string)
- specifying the category of the functions affected by the locale setting:
+ <parameter>Category</parameter> is a named constant (or string)
+ specifying the category of the functions affected by the locale
+ setting:
<itemizedlist>
<listitem>
<simpara>
@@ -1877,7 +1930,8 @@
</listitem>
<listitem>
<simpara>
- LC_COLLATE for string comparison, see <function>strcoll</function>
+ LC_COLLATE for string comparison, see
+ <function>strcoll</function>
</simpara>
</listitem>
<listitem>
@@ -1892,13 +1946,14 @@
</simpara>
</listitem>
<listitem>
- <simpara>
- LC_NUMERIC for decimal separator (See also: <function>localeconv</function>)
+ <simpara> LC_NUMERIC for decimal separator (See also:
+ <function>localeconv</function>)
</simpara>
</listitem>
<listitem>
<simpara>
- LC_TIME for date and time formatting with <function>strftime</function>
+ LC_TIME for date and time formatting with
+ <function>strftime</function>
</simpara>
</listitem>
</itemizedlist>
@@ -2123,51 +2178,54 @@
</listitem>
</orderedlist>
</para>
- <para>
- As of PHP version 4.0.6 the format string supports argument
- numbering/swapping. Here is an example:
- <example>
- <title>Argument swapping</title>
- <programlisting role="php">
+ <para>
+ As of PHP version 4.0.6 the format string supports argument
+ numbering/swapping. Here is an example:
+ <example>
+ <title>Argument swapping</title>
+ <programlisting role="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">
$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">
$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">
-$format = "The %2\$s contains %1\$d monkeys. That's a nice %2\$s full of %1\$d
monkeys.";
-printf($format,$num,$location);
- </programlisting>
- </example>
- </para>
+ </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">
+$format = "The %2\$s contains %1\$d monkeys.
+ That's a nice %2\$s full of %1\$d monkeys.";
+printf($format, $num, $location);
+ </programlisting>
+ </example>
+ </para>
<simpara>
- See also: <function>printf</function>, <function>sscanf</function>,
- <function>fscanf</function>, and <function>number_format</function>.
+ See also: <function>printf</function>,
+ <function>sscanf</function>, <function>fscanf</function>, and
+ <function>number_format</function>.
</simpara>
</refsect1>
<refsect1>
@@ -2198,7 +2256,8 @@
<refnamediv>
<refname>strncasecmp</refname>
<refpurpose>
- Binary safe case-insensitive string comparison of the first n characters
+ Binary safe case-insensitive string comparison of the first n
+ characters
</refpurpose>
</refnamediv>
<refsect1>
@@ -2212,12 +2271,12 @@
</funcprototype>
</funcsynopsis>
<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. If any of the strings is shorter than
- <parameter>len</parameter>, then the length of that string will be
- used for the comparison.
+ 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. If any of the strings is
+ shorter than <parameter>len</parameter>, then the length of that
+ string will be used for the comparison.
</para>
<simpara>
Returns < 0 if <parameter>str1</parameter> is less than
@@ -2254,7 +2313,7 @@
<parameter>str2</parameter>; > 0 if <parameter>str1</parameter>
is greater than <parameter>str2</parameter>, and 0 if they are
equal.
- <example>
+ <example>
<title><function>strcasecmp</function> example</title>
<programlisting role="php">
$var1 = "Hello";
@@ -2263,12 +2322,13 @@
echo '$var1 is equal to $var2 in a case-insensitive string comparison';
}
</programlisting>
- </example>
+ </example>
</para>
<simpara>
See also <function>ereg</function>, <function>strcmp</function>,
<function>substr</function>, <function>stristr</function>,
- <function>strncasecmp</function>, and <function>strstr</function>.
+ <function>strncasecmp</function>, and
+ <function>strstr</function>.
</simpara>
</refsect1>
</refentry>
@@ -2344,10 +2404,11 @@
</funcsynopsis>
<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
+ <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>
@@ -2363,8 +2424,8 @@
See also <function>ereg</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>.
+ <function>strncmp</function>, <function>strstr</function>, and
+ <function>setlocale</function>.
</simpara>
</refsect1>
</refentry>
@@ -2413,11 +2474,11 @@
</funcprototype>
</funcsynopsis>
<para>
- This function tries to return a string with all HTML and PHP
- tags stripped from a given <parameter>str</parameter>.
- It errors on the side of caution in case of incomplete
- or bogus tags. It uses the same tag stripping state machine as
- the <function>fgetss</function> function.
+ This function tries to return a string with all HTML and PHP tags
+ stripped from a given <parameter>str</parameter>. It errors on
+ the side of caution in case of incomplete or bogus tags. 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
@@ -2549,8 +2610,8 @@
<refnamediv>
<refname>strnatcmp</refname>
<refpurpose>
- String comparisons using a "natural order" algorithm
- </refpurpose>
+ String comparisons using a "natural order" algorithm
+ </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -2562,14 +2623,14 @@
</funcprototype>
</funcsynopsis>
<para>
- This function implements a comparison algorithm that orders
- alphanumeric strings in the way a human being would, this is
- described as a "natural ordering". An example of the difference
- between this algorithm and the regular computer string sorting
- algorithms (used in <function>strcmp</function>) can be seen
- below:
- <informalexample>
- <programlisting>
+ This function implements a comparison algorithm that orders
+ alphanumeric strings in the way a human being would, this is
+ described as a "natural ordering". An example of the difference
+ between this algorithm and the regular computer string sorting
+ algorithms (used in <function>strcmp</function>) can be seen
+ below:
+ <informalexample>
+ <programlisting>
$arr1 = $arr2 = array("img12.png","img10.png","img2.png","img1.png");
echo "Standard string comparison\n";
usort($arr1,"strcmp");
@@ -2577,11 +2638,11 @@
echo "\nNatural order string comparison\n";
usort($arr2,"strnatcmp");
print_r($arr2);
- </programlisting>
- </informalexample>
- The code above will generate the following output:
- <informalexample>
- <programlisting>
+ </programlisting>
+ </informalexample>
+ The code above will generate the following output:
+ <informalexample>
+ <programlisting>
Standard string comparison
Array
(
@@ -2599,18 +2660,18 @@
[2] => img10.png
[3] => img12.png
)
- </programlisting>
- </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.
+ </programlisting>
+ </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.
@@ -2630,8 +2691,9 @@
<refnamediv>
<refname>strnatcasecmp</refname>
<refpurpose>
- Case insensitive string comparisons using a "natural order" algorithm
- </refpurpose>
+ Case insensitive string comparisons using a "natural order"
+ algorithm
+ </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -2643,20 +2705,20 @@
</funcprototype>
</funcsynopsis>
<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 infomation see: Martin Pool's
- <ulink url="&url.strnatcmp;">Natural Order String
- Comparison</ulink> page.
- </para>
- <simpara>
- Similar to other string comparison functions, this one returns
- < 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.
+ 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 infomation see: Martin Pool's <ulink
+ url="&url.strnatcmp;">Natural Order String Comparison</ulink>
+ page.
+ </para>
+ <simpara>
+ Similar to other string comparison functions, this one returns
+ < 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>ereg</function>,
@@ -2672,8 +2734,8 @@
<refnamediv>
<refname>strncmp</refname>
<refpurpose>
- Binary safe string comparison of the first n characters
- </refpurpose>
+ Binary safe string comparison of the first n characters
+ </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -2686,14 +2748,14 @@
</funcprototype>
</funcsynopsis>
<para>
- This function is similar to <function>strcmp</function>, with the
- difference that you can specify the (upper limit of the) number of
- characters (<parameter>len</parameter>) from each string to be
- used in the comparison. If any of the strings is shorter than
- <parameter>len</parameter>, then the length of that string will be
- used for the comparison.
- </para>
- <simpara>
+ This function is similar to <function>strcmp</function>, with the
+ difference that you can specify the (upper limit of the) number
+ of characters (<parameter>len</parameter>) from each string to be
+ used in the comparison. If any of the strings is shorter than
+ <parameter>len</parameter>, then the length of that string will
+ be used for the comparison.
+ </para>
+ <simpara>
Returns < 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
@@ -2703,10 +2765,11 @@
Note that this comparison is case sensitive.
</simpara>
<simpara>
- See also <function>ereg</function>, <function>strncasecmp</function>,
+ See also <function>ereg</function>,
+ <function>strncasecmp</function>,
<function>strcasecmp</function>, <function>substr</function>,
- <function>stristr</function>, <function>strcmp</function>,
- and <function>strstr</function>.
+ <function>stristr</function>, <function>strcmp</function>, and
+ <function>strstr</function>.
</simpara>
</refsect1>
</refentry>
@@ -2714,7 +2777,9 @@
<refentry id="function.str-pad">
<refnamediv>
<refname>str_pad</refname>
- <refpurpose>Pad a string to a certain length with another string</refpurpose>
+ <refpurpose>
+ Pad a string to a certain length with another string
+ </refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -2724,7 +2789,8 @@
<paramdef>string <parameter>input</parameter></paramdef>
<paramdef>int <parameter>pad_length</parameter></paramdef>
<paramdef>string
- <parameter><optional>pad_string</optional></parameter></paramdef>
+ <parameter><optional>pad_string</optional></parameter>
+ </paramdef>
<paramdef>int
<parameter><optional>pad_type</optional></parameter>
</paramdef>
@@ -2739,20 +2805,16 @@
is padded with characters from <parameter>pad_string</parameter>
up to the limit.
</para>
-
<para>
Optional argument <parameter>pad_type</parameter> can be
STR_PAD_RIGHT, STR_PAD_LEFT, or STR_PAD_BOTH. If
<parameter>pad_type</parameter> is not specified it is assumed to
be STR_PAD_RIGHT.
</para>
-
<para>
- If the value of <parameter>pad_length</parameter> is negative or
- less than the length of the input string, no padding takes
- place.
+ 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>
@@ -3248,20 +3310,24 @@
<function>str_replace</function> can be an array.
</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_replace</function> takes a value from each
- array and uses them to do search and replace on
- <parameter>subject</parameter>. If <parameter>replace</parameter> has
- fewer values than <parameter>search</parameter>, then an empty string is
- used for the rest of replacement values. If <parameter>search</parameter>
- is an array and <parameter>replace</parameter> is a string; then this
- replacement string is used for every value of
- <parameter>search</parameter>. The converse would not make sense, though.
+ If <parameter>subject</parameter> is an array, then the search
+ and replace is performed with every entry of
+ <parameter>subject</parameter>, and the return value is an array
+ as well.
+ </para>
+ <para>
+ If <parameter>search</parameter> and
+ <parameter>replace</parameter> are arrays, then
+ <function>str_replace</function> takes a value from each array
+ and uses them to do search and replace on
+ <parameter>subject</parameter>. If
+ <parameter>replace</parameter> has fewer values than
+ <parameter>search</parameter>, then an empty string is used for
+ the rest of replacement values. If <parameter>search</parameter>
+ is an array and <parameter>replace</parameter> is a string; then
+ this replacement string is used for every value of
+ <parameter>search</parameter>. The converse would not make
+ sense, though.
</para>
<para>
<example>
