sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-17 01:18:55 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
php-doc-en/functions/strings.xml
Derek Ford 9d5f08a749 undoing changes 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@147061 c90b9560-bf6c-de11-be94-00142212c4b1
2003-12-21 02:58:42 +00:00

4122 lines
135 KiB
XML
Raw Blame History

<!-- D O N O T E D I T T H I S F I L E ! ! !
it is still here for historical reasons only
(as translators may need to check old revision diffs)
if you want to change things documented in this file
you should now edit the files found under en/reference
instead -->
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.175 $ -->
<reference id="ref.strings">
<title>String functions</title>
<titleabbrev>Strings</titleabbrev>
<partintro>
<simpara>
These functions all manipulate strings in various ways. Some more
specialized sections can be found in the regular expression and
URL handling sections.
</simpara>
<para>
For information on how strings behave, especially with regard to
usage of single quotes, double quotes, and escape sequences, see
the <link linkend="language.types.string">Strings</link> entry in
the <link linkend="language.types">Types</link> section of the
manual.
</para>
<para>
For even more powerful string handling and manipulating functions
take a look at the <link linkend="ref.regex">POSIX regular
expression functions</link> and the <link linkend="ref.pcre">Perl
compatible regular expression functions</link>
</para>
</partintro>
<refentry id="function.addcslashes">
<refnamediv>
<refname>addcslashes</refname>
<refpurpose>Quote string with slashes in a C style</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>addcslashes</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
<methodparam><type>string</type><parameter>charlist</parameter></methodparam>
</methodsynopsis>
<para>
Returns a string with backslashes before characters that are
listed in <parameter>charlist</parameter> parameter. It escapes
<literal>\n</literal>, <literal>\r</literal> etc. in C-like
style, characters with ASCII code lower than 32 and higher than
126 are converted to octal representation.
</para>
<para>
Be careful if you choose to escape characters 0, a, b, f, n, r,
t and v. They will be converted to \0, \a, \b, \f, \n, \r, \t
and \v.
In PHP \0 (&null;), \r (carriage return), \n (newline) and \t (tab)
are predefined escape sequences, while in C all of these are
predefined escape sequences.
</para>
<para>
<parameter>charlist</parameter> like "\0..\37", which would
escape all characters with ASCII code between 0 and 31.
<example>
<title><function>addcslashes</function> example</title>
<programlisting role="php">
<![CDATA[
$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.
<informalexample>
<programlisting role="php">
<![CDATA[
echo addcslashes('foo[ ]', 'A..z');
// output: \f\o\o\[ \]
// All upper and lower-case letters will be escaped
// ... but so will the [\]^_` and any tabs, line
// feeds, carriage returns, etc.
]]>
</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.
<informalexample>
<programlisting role="php">
<![CDATA[
echo addcslashes("zoo['.']", 'z..A');
// output: \zoo['\.']
]]>
</programlisting>
</informalexample>
</para>
<para>
See also <function>stripcslashes</function>,
<function>stripslashes</function>,
<function>htmlspecialchars</function>, and
<function>quotemeta</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.addslashes">
<refnamediv>
<refname>addslashes</refname>
<refpurpose>Quote string with slashes</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>addslashes</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
</methodsynopsis>
<para>
Returns a string with backslashes before characters that need
to be quoted in database queries etc. These characters are
single quote (<literal>'</literal>), double quote
(<literal>"</literal>), backslash (<literal>\</literal>)
and NUL (the &null; byte).
</para>
<note>
<para>
<link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link> is ON by default.
</para>
</note>
<para>
See also <function>stripslashes</function>,
<function>htmlspecialchars</function>, and
<function>quotemeta</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.bin2hex">
<refnamediv>
<refname>bin2hex</refname>
<refpurpose>
Convert binary data into hexadecimal representation
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>bin2hex</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
</methodsynopsis>
<para>
Returns an ASCII string containing the hexadecimal representation
of <parameter>str</parameter>. The conversion is done byte-wise
with the high-nibble first.
</para>
<para>
See also <function>pack</function> and <function>unpack</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.chop">
<refnamediv>
<refname>chop</refname>
<refpurpose>Alias of <function>rtrim</function></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<para>
This function is an alias of <function>rtrim</function>.
</para>
<note>
<para>
<function>chop</function> is different than the Perl
<literal>chop()</literal> function, which removes the last
character in the string.
</para>
</note>
</refsect1>
</refentry>
<refentry id="function.chr">
<refnamediv>
<refname>chr</refname>
<refpurpose>Return a specific character</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>chr</methodname>
<methodparam><type>int</type><parameter>ascii</parameter></methodparam>
</methodsynopsis>
<para>
Returns a one-character string containing the character specified
by <parameter>ascii</parameter>.
<example>
<title><function>chr</function> example</title>
<programlisting role="php">
<![CDATA[
$str .= chr(27); /* add an escape character at the end of $str */
/* Often this is more useful */
$str = sprintf("The string ends in escape: %c", 27);
]]>
</programlisting>
</example>
</para>
<para>
You can find an ASCII-table over here: <ulink url="&url.asciitable;"
>&url.asciitable;</ulink>.
</para>
<para>
This function complements <function>ord</function>. See also
<function>sprintf</function> with a format string of
<literal>%c</literal>.
</para>
</refsect1>
</refentry>
<refentry id="function.chunk-split">
<refnamediv>
<refname>chunk_split</refname>
<refpurpose>Split a string into smaller chunks</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>chunk_split</methodname>
<methodparam><type>string</type><parameter>body</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>chunklen</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>end</parameter></methodparam>
</methodsynopsis>
<para>
Can be used to split a string into smaller chunks which is useful for
e.g. converting <link
linkend="function.base64-encode">base64_encode</link> output to match RFC
2045 semantics. It inserts <parameter>end</parameter> (defaults to
"\r\n") every <parameter>chunklen</parameter> characters (defaults to
76). It returns the new string leaving the original string untouched.
<example>
<title><function>chunk_split</function> example</title>
<programlisting role="php">
<![CDATA[
# format $data using RFC 2045 semantics
$new_string = chunk_split(base64_encode($data));
]]>
</programlisting>
</example>
</para>
<simpara>
See also <function>explode</function>, <function>split</function>
and <function>wordwrap</function>.
</simpara>
</refsect1>
</refentry>
<refentry id="function.convert-cyr-string">
<refnamediv>
<refname>convert_cyr_string</refname>
<refpurpose>
Convert from one Cyrillic character set to another
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>convert_cyr_string</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
<methodparam><type>string</type><parameter>from</parameter></methodparam>
<methodparam><type>string</type><parameter>to</parameter></methodparam>
</methodsynopsis>
<para>
This function returns the given string converted from one
Cyrillic character set to another. The <parameter>from</parameter>
and <parameter>to</parameter> arguments are single characters that
represent the source and target Cyrillic character sets. The
supported types are:
<itemizedlist>
<listitem>
<simpara>
k - koi8-r
</simpara>
</listitem>
<listitem>
<simpara>
w - windows-1251
</simpara>
</listitem>
<listitem>
<simpara>
i - iso8859-5
</simpara>
</listitem>
<listitem>
<simpara>
a - x-cp866
</simpara>
</listitem>
<listitem>
<simpara>
d - x-cp866
</simpara>
</listitem>
<listitem>
<simpara>
m - x-mac-cyrillic
</simpara>
</listitem>
</itemizedlist>
</para>
</refsect1>
</refentry>
<refentry id="function.count-chars">
<refnamediv>
<refname>count_chars</refname>
<refpurpose>
Return information about characters used in a string
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>mixed</type><methodname>count_chars</methodname>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>
mode
</parameter></methodparam>
</methodsynopsis>
<para>
Counts the number of occurrences of every byte-value (0..255) in
<parameter>string</parameter> and returns it in various ways.
The optional parameter <parameter>Mode</parameter> default to
0. Depending on <parameter>mode</parameter>
<function>count_chars</function> returns one of the following:
<itemizedlist>
<listitem>
<simpara>
0 - an array with the byte-value as key and the frequency of
every byte as value.
</simpara>
</listitem>
<listitem>
<simpara>
1 - same as 0 but only byte-values with a frequency greater
than zero are listed.
</simpara>
</listitem>
<listitem>
<simpara>
2 - same as 0 but only byte-values with a frequency equal to
zero are listed.
</simpara>
</listitem>
<listitem>
<simpara>
3 - a string containing all used byte-values is returned.
</simpara>
</listitem>
<listitem>
<simpara>
4 - a string containing all not used byte-values is returned.
</simpara>
</listitem>
</itemizedlist>
</para>
</refsect1>
</refentry>
<refentry id="function.crc32">
<refnamediv>
<refname>crc32</refname>
<refpurpose>Calculates the crc32 polynomial of a string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>crc32</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
</methodsynopsis>
<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>
<refentry id="function.crypt">
<refnamediv>
<refname>crypt</refname>
<refpurpose>One-way string encryption (hashing)</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>crypt</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>salt</parameter></methodparam>
</methodsynopsis>
<para>
<function>crypt</function> will return an encrypted string using the
standard Unix <abbrev>DES</abbrev>-based encryption algorithm or
alternative algorithms that may be available on the system. Arguments
are a string to be encrypted and an optional salt string to base the
encryption on. See the Unix man page for your crypt function for more
information.
</para>
<simpara>
If the salt argument is not provided, one will be randomly
generated by PHP.
</simpara>
<simpara>
Some operating systems support more than one type of encryption. In
fact, sometimes the standard DES-based encryption is replaced by an
MD5-based encryption algorithm. The encryption type is triggered by the
salt argument. At install time, PHP determines the capabilities of the
crypt function and will accept salts for other encryption types. If no
salt is provided, PHP will auto-generate a standard two character salt by
default, unless the default encryption type on the system is MD5, in
which case a random MD5-compatible salt is generated. PHP sets a
constant named CRYPT_SALT_LENGTH which tells you whether a regular two
character salt applies to your system or the longer twelve character salt
is applicable.
</simpara>
<simpara>
If you are using the supplied salt, you should be aware that the salt is
generated once. If you are calling this function recursively, this may
impact both appearance and security.
</simpara>
<simpara>
The standard DES-based encryption <function>crypt</function> returns the
salt as the first two characters of the output. It also only uses the
first eight characters of <parameter>str</parameter>, so longer strings
that start with the same eight characters will generate the same result
(when the same salt is used).
</simpara>
<simpara>
On systems where the crypt() function supports multiple
encryption types, the following constants are set to 0 or 1
depending on whether the given type is available:
</simpara>
<itemizedlist>
<listitem>
<simpara>
CRYPT_STD_DES - Standard DES-based encryption with a two character salt
</simpara>
</listitem>
<listitem>
<simpara>
CRYPT_EXT_DES - Extended DES-based encryption with a nine character salt
</simpara>
</listitem>
<listitem>
<simpara>
CRYPT_MD5 - MD5 encryption with a twelve character salt starting with
$1$
</simpara>
</listitem>
<listitem>
<simpara>
CRYPT_BLOWFISH - Blowfish encryption with a sixteen character salt
starting with $2$
</simpara>
</listitem>
</itemizedlist>
<note>
<simpara>
There is no decrypt function, since <function>crypt</function>
uses a one-way algorithm.
</simpara>
</note>
<example>
<title><function>crypt</function> examples</title>
<programlisting role="php">
<![CDATA[
<?php
$password = crypt("My1sTpassword"); # let salt be generated
# You should pass the entire results of crypt() as the salt for comparing a
# password, to avoid problems when different hashing algorithms are used. (As
# it says above, standard DES-based password hashing uses a 2-character salt,
# but MD5-based hashing uses 12.)
if (crypt($user_input,$password) == $password) {
echo "Password verified!";
}
?>
]]>
</programlisting>
</example>
<simpara>
See also <function>md5</function> and <link linkend="ref.mcrypt">the
Mcrypt extension</link>.
</simpara>
</refsect1>
</refentry>
<refentry id="function.echo">
<refnamediv>
<refname>echo</refname>
<refpurpose>Output one or more strings</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<methodname>echo</methodname>
<methodparam><type>string</type><parameter>arg1</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>argn...</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. In fact, if you want to pass more than one parameter
to echo, you must not enclose the parameters within parentheses.
It is not possible to use <function>echo</function> in a
<link linkend="functions.variable-functions">variable function</link>
context, but you can use <function>print</function> instead.
<example>
<title><function>echo</function> examples</title>
<programlisting role="php">
<![CDATA[
<?php
echo "Hello World";
echo "This spans
multiple lines. The newlines will be
output as well";
echo "This spans\nmultiple lines. The newlines will be\noutput as well.";
echo "escaping characters is done \"Like this\"."
//You can use variables inside of an echo statement
$foo = "foobar";
$bar = "barbaz";
echo "foo is $foo"; // foo is foobar
// Using single quotes will print the variable name, not the value
echo 'foo is $foo'; // foo is $foo
// If you are not using any other characters, you can just echo variables
echo $foo; // foobar
echo $foo,$bar; // foobarbarbaz
echo <<<END
This uses the "here document" syntax to output
multiple lines with $variable interpolation. Note
that the here document terminator must appear on a
line with just a semicolon no extra whitespace!
END;
// because echo is not a function, following code is invalid.
($some_var) ? echo('true'): echo('false');
// However, the following examples will work:
($some_var) ? print('true'): print('false'); // print is a function
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.
<informalexample>
<programlisting role="php">
<![CDATA[
I have <?=$foo?> foo.
]]>
</programlisting>
</informalexample>
</para>
<note>
<para>
This short syntax only works with the
<link linkend="ini.short-open-tag">short_open_tag</link> configuration
setting enabled.
</para>
</note>
<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>separator</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>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 rest of
<parameter>string</parameter>.
</para>
<para>
If <parameter>separator</parameter> is an empty string (""),
<function>explode</function> will return &false;. If
<parameter>separator</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>
<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[
$pizza = "piece1 piece2 piece3 piece4 piece5 piece6";
$pieces = explode(" ", $pizza);
$data = "foo:*:1023:1000::/home/foo:/bin/sh";
list($user,$pass,$uid,$gid,$gecos,$home,$shell) = explode(":",$data);
]]>
</programlisting>
</example>
</para>
<note>
<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>separator</parameter> argument comes before the
<parameter>string</parameter> argument.
</para>
</note>
<para>
See also
<function>preg_split</function>,
<function>spliti</function>,
<function>split</function>, and
<function>implode</function>.
</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>string</type><methodname>get_html_translation_table</methodname>
<methodparam><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>. There are two new defines
(<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>.
<example>
<title>Translation Table Example</title>
<programlisting role="php">
<![CDATA[
$trans = get_html_translation_table(HTML_ENTITIES);
$str = "Hallo & <Frau> & Kr<4B>mer";
$encoded = strtr($str, $trans);
]]>
</programlisting>
</example>
The <literal>$encoded</literal> variable will now contain:
<literal>"Hallo &amp;amp; &amp;lt;Frau&amp;gt; &amp;amp;
Kr&amp;auml;mer".</literal>
</para>
<para>
The cool thing is using <function>array_flip</function> to change
the direction of the translation.
<informalexample>
<programlisting role="php">
<![CDATA[
$trans = array_flip($trans);
$original = strtr($encoded, $trans);
]]>
</programlisting>
</informalexample>
The content of <literal>$original</literal> would be: "Hallo &amp;
&lt;Frau> &amp; Kr&auml;mer".
</para>
<para>
See also: <function>htmlspecialchars</function>,
<function>htmlentities</function>, <function>strtr</function>,
and <function>array_flip</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.get-meta-tags">
<refnamediv>
<refname>get_meta_tags</refname>
<refpurpose>
Extracts all meta tag content attributes from a file and returns
an array
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>get_meta_tags</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>use_include_path</parameter></methodparam>
</methodsynopsis>
<para>
Opens <parameter>filename</parameter> and parses it line by line
for &lt;meta> tags of the form
<example>
<title>Meta Tags Example</title>
<programlisting role="html">
<![CDATA[
<meta name="author" content="name">
<meta name="tags" content="php3 documentation">
</head> <!-- parsing stops here -->
]]>
</programlisting>
</example>
(pay attention to line endings - PHP uses a native function to
parse the input, so a Mac file won't work on Unix).
</para>
<para>
The value of the name property becomes the key, the value of the
content property becomes the value of the returned array, so you
can easily use standard array functions to traverse it or access
single values. Special characters in the value of the name
property are substituted with '_', the rest is converted to lower
case.
</para>
<para>
Setting <parameter>use_include_path</parameter> to 1 will result
in PHP trying to open the file along the standard include path.
</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 will be
output. The function tries to avoid breaking words.
</para>
<para>
See also <function>hebrevc</function>
</para>
</refsect1>
</refentry>
<refentry id="function.hebrevc">
<refnamediv>
<refname>hebrevc</refname>
<refpurpose>
Convert logical Hebrew text to visual text with newline conversion
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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 "&lt;br&gt;\n". The
optional parameter <parameter>max_chars_per_line</parameter>
indicates maximum number of characters per line will be
output. The function tries to avoid breaking words.
</para>
<para>
See also <function>hebrev</function>
</para>
</refsect1>
</refentry>
<refentry id="function.htmlentities">
<refnamediv>
<refname>htmlentities</refname>
<refpurpose>
Convert all applicable characters to HTML entities
</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>
</methodsynopsis>
<para>
This function is identical to
<function>htmlspecialchars</function> in all ways, except that
all characters which have HTML character entity equivalents are
translated into these entities. Like
<function>htmlspecialchars</function>, it takes an optional
second argument which indicates what should be done with single
and double quotes. <constant>ENT_COMPAT</constant> (the default)
will only convert double-quotes and leave single-quotes alone.
<constant>ENT_QUOTES</constant> will convert both double and
single quotes, and <constant>ENT_NOQUOTES</constant> will leave
both double and single quotes unconverted.
</para>
<para>
At present, the ISO-8859-1 character set is used as default.
Support for the optional second argument was added in PHP 3.0.17 and PHP
4.0.3.
</para>
<para>
Like <function>htmlspecialchars</function>, it takes an optional
third argument which defines character set used in conversion.
Support for this argument was added in PHP 4.1.0.
</para>
<para>
See also <function>htmlspecialchars</function> and
<function>nl2br</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.htmlspecialchars">
<refnamediv>
<refname>htmlspecialchars</refname>
<refpurpose>
Convert special characters to HTML entities
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>htmlspecialchars</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>
Certain characters have special significance in HTML, and should
be represented by HTML entities if they are to preserve their
meanings. This function returns a string with some of these
conversions made; the translations made are those most
useful for everyday web programming. If you require all HTML
character entities to be translated, use
<function>htmlentities</function> instead.
</para>
<simpara>
This function is useful in preventing user-supplied text from
containing HTML markup, such as in a message board or guest book
application. 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:
<itemizedlist>
<listitem>
<simpara>
'&amp;' (ampersand) becomes '&amp;amp;'
</simpara>
</listitem>
<listitem>
<simpara>
'&quot;' (double quote) becomes '&amp;quot;' when ENT_NOQUOTES
is not set.
</simpara>
</listitem>
<listitem>
<simpara>
'&#039;' (single quote) becomes '&amp;#039;' only when
ENT_QUOTES is set.
</simpara>
</listitem>
<listitem>
<simpara>
'&lt;' (less than) becomes '&amp;lt;'
</simpara>
</listitem>
<listitem>
<simpara>
'&gt;' (greater than) becomes '&amp;gt;'
</simpara>
</listitem>
</itemizedlist>
<example>
<title><function>htmlspecialchars</function> example</title>
<programlisting role="php">
<![CDATA[
$new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
]]>
</programlisting>
</example>
</para>
<para>
Note that this function does not translate anything beyond what
is listed above. For full entity translation, see
<function>htmlentities</function>. Support for the optional
second argument was added in PHP 3.0.17 and PHP 4.0.3.
</para>
<para>
The third argument defines character set used in conversion. The
default character set is ISO-8859-1. Support for this third argument was
added in PHP 4.1.0.
</para>
<para>
See also <function>htmlentities</function> and
<function>nl2br</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">
<![CDATA[
$colon_separated = implode(":", $array);
]]>
</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>
<simpara>
See also <function>explode</function>, <function>join</function>,
and <function>split</function>.
</simpara>
</refsect1>
</refentry>
<refentry id="function.join">
<refnamediv>
<refname>join</refname>
<refpurpose>Join array elements with a string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>join</methodname>
<methodparam><type>string</type><parameter>glue</parameter></methodparam>
<methodparam><type>array</type><parameter>pieces</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>join</function> is an alias to
<function>implode</function>, and is identical in every way.
</simpara>
<simpara>
See also <function>explode</function>, <function>implode</function>,
and <function>split</function>.
</simpara>
</refsect1>
</refentry>
<refentry id="function.levenshtein">
<refnamediv>
<refname>levenshtein</refname>
<refpurpose>
Calculate Levenshtein distance between two strings
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>levenshtein</methodname>
<methodparam><type>string</type><parameter>str1</parameter></methodparam>
<methodparam><type>string</type><parameter>str2</parameter></methodparam>
</methodsynopsis>
<methodsynopsis>
<type>int</type><methodname>levenshtein</methodname>
<methodparam><type>string</type><parameter>str1</parameter></methodparam>
<methodparam><type>string</type><parameter>str2</parameter></methodparam>
<methodparam><type>int</type><parameter>cost_ins</parameter></methodparam>
<methodparam><type>int</type><parameter>cost_rep</parameter></methodparam>
<methodparam><type>int</type><parameter>cost_del</parameter></methodparam>
</methodsynopsis>
<methodsynopsis>
<type>int</type><methodname>levenshtein</methodname>
<methodparam><type>string</type><parameter>str1</parameter></methodparam>
<methodparam><type>string</type><parameter>str2</parameter></methodparam>
<methodparam><type>function</type><parameter>cost</parameter></methodparam>
</methodsynopsis>
<para>
This function returns the Levenshtein-Distance between the
two argument strings or -1, if one of the argument strings
is longer than the limit of 255 characters (255 should be
more than enough for name or dictionary comparison, and
nobody serious would be doing genetic analysis with PHP).
</para>
<para>
The Levenshtein distance is defined as the minimal number of
characters you have to replace, insert or delete to transform
<parameter>str1</parameter> into <parameter>str2</parameter>.
The complexity of the algorithm is <literal>O(m*n)</literal>,
where <literal>n</literal> and <literal>m</literal> are the
length of <parameter>str1</parameter> and
<parameter>str2</parameter> (rather good when compared to
<function>similar_text</function>, which is O(max(n,m)**3),
but still expensive).
</para>
<para>
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
arguments:
<itemizedlist>
<listitem>
<simpara>
operation to apply: 'I', 'R' or 'D'
</simpara>
</listitem>
<listitem>
<simpara>
actual character in string 1
</simpara>
</listitem>
<listitem>
<simpara>
actual character in string 2
</simpara>
</listitem>
<listitem>
<simpara>
position in string 1
</simpara>
</listitem>
<listitem>
<simpara>
position in string 2
</simpara>
</listitem>
<listitem>
<simpara>
remaining characters in string 1
</simpara>
</listitem>
<listitem>
<simpara>
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
certain symbols (characters) or even the context those symbols
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>
<para>
See also <function>soundex</function>,
<function>similar_text</function>, and
<function>metaphone</function>.
</para>
</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 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">
<![CDATA[
setlocale(LC_ALL, "en_US");
$locale_info = localeconv();
echo "<PRE>\n";
echo "--------------------------------------------\n";
echo " Monetary information for current locale: \n";
echo "--------------------------------------------\n\n";
echo "int_curr_symbol: {$locale_info["int_curr_symbol"]}\n";
echo "currency_symbol: {$locale_info["currency_symbol"]}\n";
echo "mon_decimal_point: {$locale_info["mon_decimal_point"]}\n";
echo "mon_thousands_sep: {$locale_info["mon_thousands_sep"]}\n";
echo "positive_sign: {$locale_info["positive_sign"]}\n";
echo "negative_sign: {$locale_info["negative_sign"]}\n";
echo "int_frac_digits: {$locale_info["int_frac_digits"]}\n";
echo "frac_digits: {$locale_info["frac_digits"]}\n";
echo "p_cs_precedes: {$locale_info["p_cs_precedes"]}\n";
echo "p_sep_by_space: {$locale_info["p_sep_by_space"]}\n";
echo "n_cs_precedes: {$locale_info["n_cs_precedes"]}\n";
echo "n_sep_by_space: {$locale_info["n_sep_by_space"]}\n";
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>
<para>
The constant CHAR_MAX is also defined for the use mentioned above.
</para>
<para>
See also: <function>setlocale</function>.
</para>
</refsect1>
</refentry>
<!-- this section is nearly-identical to trim, ltrim and rtrim -->
<refentry id="function.ltrim">
<refnamediv>
<refname>ltrim</refname>
<refpurpose>
Strip whitespace 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:
<!-- sorted by importance. Printed 3 times: trim, ltrim, rtrim -->
<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> <!-- not \v, since not supported by PHP -->
"\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>
<para>
<programlisting role="php">
<![CDATA[
<?php
$text = "\t\tThese are a few words :) ... ";
$trimmed = ltrim($text);
// $trimmed = "These are a few words :) ... "
$trimmed = ltrim($text," \t.");
// $trimmed = "These are a few words :) ... "
$clean = ltrim($binary,"\0x00..\0x1F");
// trim the ASCII control characters at the beginning of $binary
// (from 0 to 31 inclusive)
?>
]]>
</programlisting>
</para>
</example>
<para>
See also <function>trim</function> and <function>rtrim</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.md5">
<refnamediv>
<refname>md5</refname>
<refpurpose>Calculate the md5 hash of a string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>md5</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
</methodsynopsis>
<para>
Calculates the MD5 hash of <parameter>str</parameter> using the
<ulink url="&url.rfc;1321">RSA Data Security, Inc.
MD5 Message-Digest Algorithm</ulink>, and returns that hash.
The hash is a 32-character hexadecimal number.
</para>
<para>
See also: <function>crc32</function> and <function>md5_file</function>
</para>
</refsect1>
</refentry>
<refentry id="function.md5-file">
<refnamediv>
<refname>md5_file</refname>
<refpurpose>Calculates the md5 hash of a given filename</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>md5_file</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
</methodsynopsis>
<para>
Calculates the MD5 hash of the specified
<parameter>filename</parameter> using the
<ulink url="&url.rfc;1321">RSA Data Security, Inc.
MD5 Message-Digest Algorithm</ulink>, and returns that hash.
</para>
<para>
This function has the same purpose of the command line utility
md5sum.
</para>
<para>
See also: <function>md5</function> and <function>crc32</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>
</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
&lt;lphilips@verity.com>. It is described in ["Practical
Algorithms for Programmers", Binstock &amp; Rex, Addison Wesley,
1995].
</para>
</refsect1>
</refentry>
<refentry id="function.nl-langinfo">
<refnamediv>
<refname>nl_langinfo</refname>
<refpurpose>
Query language and locale information
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>nl_langinfo</methodname>
<methodparam><type>int</type><parameter>item</parameter></methodparam>
</methodsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
<refentry id="function.nl2br">
<refnamediv>
<refname>nl2br</refname>
<refpurpose>
Inserts HTML line breaks before all newlines in a string
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>nl2br</methodname>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
</methodsynopsis>
<para>
Returns <parameter>string</parameter> with '&lt;br /&gt;' inserted
before all newlines.
</para>
<note>
<para>
Starting with PHP 4.0.5, <function>nl2br</function> is now XHTML
compliant. All versions before 4.0.5 will return
<parameter>string</parameter> with '&lt;br&gt;' inserted before
newlines instead of '&lt;br /&gt;'.
</para>
</note>
<para>
See also <function>htmlspecialchars</function>,
<function>htmlentities</function> and
<function>wordwrap</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.ord">
<refnamediv>
<refname>ord</refname>
<refpurpose>Return ASCII value of character</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>ord</methodname>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
</methodsynopsis>
<para>
Returns the ASCII value of the first character of
<parameter>string</parameter>. This function complements
<function>chr</function>.
<example>
<title><function>ord</function> example</title>
<programlisting role="php">
<![CDATA[
if (ord($str) == 10) {
echo "The first character of \$str is a line feed.\n";
}
]]>
</programlisting>
</example>
</para>
<para>
You can find an ASCII-table over here: <ulink url="&url.asciitable;"
>&url.asciitable;</ulink>.
</para>
<simpara>
See also <function>chr</function>.
</simpara>
</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>arr
</parameter></methodparam>
</methodsynopsis>
<para>
Parses <parameter>str</parameter> as if it were the query string
passed via an URL and sets variables in the current scope. If
the second parameter <parameter>arr</parameter> is present,
variables are stored in this variable as an array elements instead.
</para>
<note>
<para>
Support for the optional second parameter was added in PHP 4.0.3.
</para>
</note>
<para>
<example>
<title>Using <function>parse_str</function></title>
<programlisting role="php">
<![CDATA[
$str = "first=value&second[]=this+works&second[]=another";
parse_str($str);
echo $first; /* prints "value" */
echo $second[0]; /* prints "this works" */
echo $second[1]; /* prints "another" */
]]>
</programlisting>
</example>
</para>
<para>
See also <function>set_magic_quotes_runtime</function>
and <function>urldecode</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.print">
<refnamediv>
<refname>print</refname>
<refpurpose>Output a string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<methodname>print</methodname>
<methodparam><type>string</type><parameter>arg</parameter></methodparam>
</methodsynopsis>
<simpara>
Outputs <parameter>arg</parameter>. &return.success;
</simpara>
<para>
<function>print</function> is not actually a real function (it is a
language construct) so you are not required to use parentheses with it.
This also means that you can not use <function>print</function> (just
like <function>echo</function>) as a <link
linkend="functions.variable-functions">variable function</link>.
</para>
<example>
<title><function>print</function> examples</title>
<programlisting role="php">
<![CDATA[
<?php
print("Hello World");
print "print() also works without parentheses.";
print "This spans
multiple lines. The newlines will be
output as well";
print "This spans\nmultiple lines. The newlines will be\noutput as well.";
print "escaping characters is done \"Like this\".";
// You can use variables inside of an print statement
$foo = "foobar";
$bar = "barbaz";
print "foo is $foo"; // foo is foobar
// Using single quotes will print the variable name, not the value
print 'foo is $foo'; // foo is $foo
// If you are not using any other characters, you can just print variables
print $foo; // foobar
print <<<END
This uses the "here document" syntax to output
multiple lines with $variable interpolation. Note
that the here document terminator must appear on a
line with just a semicolon no extra whitespace!
END;
?>
]]>
</programlisting>
</example>
<simpara>
See also <function>echo</function>, <function>printf</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>void</type><methodname>printf</methodname>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>args</parameter></methodparam>
</methodsynopsis>
<simpara>
Produces output according to <parameter>format</parameter>, which
is described in the documentation for <function>sprintf</function>.
</simpara>
<simpara>
See also: <function>print</function>, <function>sprintf</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. 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>
</para>
<simpara>
See also <function>addslashes</function>,
<function>htmlentities</function>,
<function>htmlspecialchars</function>,
<function>nl2br</function>, and
<function>stripslashes</function>.
</simpara>
</refsect1>
</refentry>
<refentry id='function.str-rot13'>
<refnamediv>
<refname>str_rot13</refname>
<refpurpose>Perform the rot13 transform on a string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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>
</refsect1>
</refentry>
<!-- this section is nearly-identical to trim, ltrim and rtrim -->
<refentry id="function.rtrim">
<refnamediv>
<refname>rtrim</refname>
<refpurpose>
Strip whitespace 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:
<!-- sorted by importance. Printed 3 times: trim, ltrim, rtrim -->
<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> <!-- not \v, since not supported by PHP -->
"\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>
<para>
<programlisting role="php">
<![CDATA[
<?php
$text = "\t\tThese are a few words :) ... ";
$trimmed = rtrim($text);
// $trimmed = "\t\tThese are a few words :) ..."
$trimmed = rtrim($text," \t.");
// $trimmed = "\t\tThese are a few words :)"
$clean = rtrim($binary,"\0x00..\0x1F");
// trim the ASCII control characters at the end of $binary
// (from 0 to 31 inclusive)
?>
]]>
</programlisting>
</para>
</example>
<para>
See also <function>trim</function> and <function>ltrim</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.sscanf">
<refnamediv>
<refname>sscanf</refname>
<refpurpose>
Parses input from a string according to a format
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>mixed</type><methodname>sscanf</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>var1</parameter></methodparam>
</methodsynopsis>
<para>
The function <function>sscanf</function> is the input analog of
<function>printf</function>. <function>sscanf</function> reads
from the string <parameter>str</parameter> and interprets it
according to the specified <parameter>format</parameter>. If only
two parameters were passed to this function, the values parsed
will be returned as an array.
<example>
<title><function>sscanf</function> Example</title>
<programlisting role="php">
<![CDATA[
// getting the serial number
$serial = sscanf("SN/2350001","SN/%d");
// and the date of manufacturing
$mandate = "January 01 2000";
list($month, $day, $year) = sscanf($mandate,"%s %d %d");
echo "Item $serial was manufactured on: $year-".substr($month,0,3)."-$day\n";
]]>
</programlisting>
</example>
If optional parameters are passed, the function will return the
number of assigned values. The optional parameters must be passed
by reference.
<example>
<title><function>sscanf</function> - using optional parameters</title>
<programlisting role="php">
<![CDATA[
// get author info and generate DocBook entry
$auth = "24\tLewis Carroll";
$n = sscanf($auth,"%d\t%s %s", &$id, &$first, &$last);
echo "<author id='$id'>
<firstname>$first</firstname>
<surname>$last</surname>
</author>\n";
]]>
</programlisting>
</example>
</para>
<para>
See also: <function>fscanf</function>, <function>printf</function>,
and <function>sprintf</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.setlocale">
<refnamediv>
<refname>setlocale</refname>
<refpurpose>Set locale information</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>setlocale</methodname>
<methodparam><type>mixed</type><parameter>category</parameter></methodparam>
<methodparam><type>string</type><parameter>locale</parameter></methodparam>
</methodsynopsis>
<para>
<parameter>Category</parameter> is a named constant (or string)
specifying the category of the functions affected by the locale
setting:
<itemizedlist>
<listitem>
<simpara>
LC_ALL for all of the below
</simpara>
</listitem>
<listitem>
<simpara>
LC_COLLATE for string comparison, see
<function>strcoll</function>
</simpara>
</listitem>
<listitem>
<simpara>
LC_CTYPE for character classification and conversion, for
example <function>strtoupper</function>
</simpara>
</listitem>
<listitem>
<simpara>
LC_MONETARY for <function>localeconv</function>
</simpara>
</listitem>
<listitem>
<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>
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
If <parameter>locale</parameter> is the empty string
<literal>""</literal>, the locale names will be set from the
values of environment variables with the same names as the above
categories, or from "LANG".
</para>
<para>
If locale is zero or <literal>"0"</literal>, the locale setting
is not affected, only the current setting is returned.
</para>
<para>
Setlocale returns the new current locale, or &false; if the locale
functionality is not implemented in the platform, the specified
locale does not exist or the category name is invalid.
An invalid category name also causes a warning message.
</para>
<para>
<example>
<title><function>setlocale</function> Examples</title>
<programlisting role="php">
<![CDATA[
<?php
/* Set locale to Dutch */
setlocale (LC_ALL, 'nl_NL');
/* Output: vrijdag 22 december 1978 */
echo strftime ("%A %e %B %Y", mktime (0, 0, 0, 12, 22, 1978));
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.similar-text">
<refnamediv>
<refname>similar_text</refname>
<refpurpose>
Calculate the similarity between two strings
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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>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>
</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">
<![CDATA[
soundex("Euler") == soundex("Ellery") == 'E460';
soundex("Gauss") == soundex("Ghosh") == 'G200';
soundex("Hilbert") == soundex("Heilbronn") == 'H416';
soundex("Knuth") == soundex("Kant") == 'K530';
soundex("Lloyd") == soundex("Ladd") == 'L300';
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>
<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>
</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>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. This option has no effect for other types than
<type>float</type>. (Another function useful for formatting numbers is
<function>number_format</function>.)
</simpara>
</listitem>
<listitem>
<para>
A <emphasis>type specifier</emphasis> that says what type the
argument data should be treated as. Possible types:
<simplelist>
<member>
<literal>%</literal> - a literal percent character. No
argument is required.
</member>
<member>
<literal>b</literal> - the argument is treated as an
integer, and presented as a binary number.
</member>
<member>
<literal>c</literal> - the argument is treated as an
integer, and presented as the character with that ASCII
value.
</member>
<member>
<literal>d</literal> - the argument is treated as an
integer, and presented as a (signed) decimal number.
</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
<type>float</type>, and presented as a floating-point number.
</member>
<member>
<literal>o</literal> - the argument is treated as an
integer, and presented as an octal number.
</member>
<member>
<literal>s</literal> - the argument is treated as and
presented as a string.
</member>
<member>
<literal>x</literal> - the argument is treated as an integer
and presented as a hexadecimal number (with lowercase
letters).
</member>
<member>
<literal>X</literal> - the argument is treated as an integer
and presented as a hexadecimal number (with uppercase
letters).
</member>
</simplelist>
</para>
</listitem>
</orderedlist>
</para>
<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">
<![CDATA[
$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">
<![CDATA[
$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">
<![CDATA[
$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">
<![CDATA[
$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>.
</simpara>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
<example>
<title><function>sprintf</function>: zero-padded integers</title>
<programlisting role="php">
<![CDATA[
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
]]>
</programlisting>
</example>
<example>
<title><function>sprintf</function>: formatting currency</title>
<programlisting role="php">
<![CDATA[
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
// echo $money will output "123.1";
$formatted = sprintf("%01.2f", $money);
// echo $formatted will output "123.10"
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.strncasecmp">
<refnamediv>
<refname>strncasecmp</refname>
<refpurpose>
Binary safe case-insensitive string comparison of the first n
characters
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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. If any of the strings is
shorter than <parameter>len</parameter>, then the length of that
string will be used for the comparison.
</para>
<simpara>
Returns &lt; 0 if <parameter>str1</parameter> is less than
<parameter>str2</parameter>; &gt; 0 if <parameter>str1</parameter>
is greater than <parameter>str2</parameter>, and 0 if they are
equal.
</simpara>
<simpara>
See also <function>ereg</function>, <function>strcasecmp</function>,
<function>strcmp</function>, <function>substr</function>,
<function>stristr</function>, and <function>strstr</function>.
</simpara>
</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 &lt; 0 if <parameter>str1</parameter> is less than
<parameter>str2</parameter>; &gt; 0 if <parameter>str1</parameter>
is greater than <parameter>str2</parameter>, and 0 if they are
equal.
<example>
<title><function>strcasecmp</function> example</title>
<programlisting role="php">
<![CDATA[
$var1 = "Hello";
$var2 = "hello";
if (!strcasecmp($var1, $var2)) {
echo '$var1 is equal to $var2 in a case-insensitive string comparison';
}
]]>
</programlisting>
</example>
</para>
<simpara>
See also <function>ereg</function>, <function>strcmp</function>,
<function>substr</function>, <function>stristr</function>,
<function>strncasecmp</function>, and
<function>strstr</function>.
</simpara>
</refsect1>
</refentry>
<refentry id="function.strchr">
<refnamediv>
<refname>strchr</refname>
<refpurpose>
Find the first occurrence of a character
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>strchr</methodname>
<methodparam><type>string</type><parameter>haystack</parameter></methodparam>
<methodparam><type>string</type><parameter>needle</parameter></methodparam>
</methodsynopsis>
<para>
This function is an alias for <function>strstr</function>, and is
identical in every way.
</para>
</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 &lt; 0 if <parameter>str1</parameter> is less than
<parameter>str2</parameter>; &gt; 0 if <parameter>str1</parameter>
is greater than <parameter>str2</parameter>, and 0 if they are
equal.
</simpara>
<simpara>
Note that this comparison is case sensitive.
</simpara>
<simpara>
See also <function>ereg</function>,
<function>strcasecmp</function>, <function>substr</function>,
<function>stristr</function>, <function>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 &lt; 0 if <parameter>str1</parameter> is less than
<parameter>str2</parameter>; &gt; 0 if
<parameter>str1</parameter> is greater than
<parameter>str2</parameter>, and 0 if they are equal.
<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>
<simpara>
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>.
</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>
</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>
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>
<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.
</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.0b3.
</para>
</note>
</para>
<para>
<example>
<title><function>strip_tags</function> example</title>
<programlisting role="php">
<![CDATA[
$string = strip_tags($string, '<a><b><i><u>');
]]>
</programlisting>
</example>
</para>
<warning>
<para>
This function does not modify any attributes on the tags that you allow
using <parameter>allowable_tags</parameter>, including the
<literal>style</literal> and <literal>onmouseover</literal> attributes
that a mischievous user may abuse when posting text that will be shown
to other users.
</para>
</warning>
</refsect1>
</refentry>
<refentry id="function.stripcslashes">
<refnamediv>
<refname>stripcslashes</refname>
<refpurpose>
Un-quote string quoted with <function>addcslashes</function>
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>stripcslashes</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
</methodsynopsis>
<para>
Returns a string with backslashes stripped off. Recognizes
C-like <literal>\n</literal>, <literal>\r</literal> ..., octal
and hexadecimal representation.
</para>
<simpara>
See also <function>addcslashes</function>.
</simpara>
</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 are made into a single backslash.
</para>
<simpara>
See also <function>addslashes</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>
See also <function>strchr</function>,
<function>strrchr</function>, <function>substr</function>, and
<function>ereg</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.strlen">
<refnamediv>
<refname>strlen</refname>
<refpurpose>Get string length</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>strlen</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
</methodsynopsis>
<para>
Returns the length of <parameter>string</parameter>.
</para>
</refsect1>
</refentry>
<refentry id="function.strnatcmp">
<refnamediv>
<refname>strnatcmp</refname>
<refpurpose>
String comparisons using a "natural order" algorithm
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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>
<![CDATA[
$arr1 = $arr2 = array("img12.png","img10.png","img2.png","img1.png");
echo "Standard string comparison\n";
usort($arr1,"strcmp");
print_r($arr1);
echo "\nNatural order string comparison\n";
usort($arr2,"strnatcmp");
print_r($arr2);
]]>
</programlisting>
</informalexample>
The code above will generate the following output:
<informalexample>
<screen>
<![CDATA[
Standard string comparison
Array
(
[0] => img1.png
[1] => img10.png
[2] => img12.png
[3] => img2.png
)
Natural order string comparison
Array
(
[0] => img1.png
[1] => img2.png
[2] => img10.png
[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
&lt; 0 if <parameter>str1</parameter> is less than
<parameter>str2</parameter>; &gt; 0 if
<parameter>str1</parameter> is greater than
<parameter>str2</parameter>, and 0 if they are equal.
</simpara>
<simpara>
Note that this comparison is case sensitive.
</simpara>
<simpara>
See also <function>ereg</function>,
<function>strcasecmp</function>, <function>substr</function>,
<function>stristr</function>, <function>strcmp</function>,
<function>strncmp</function>, <function>strncasecmp</function>,
<function>strnatcasecmp</function>, <function>strstr</function>,
<function>natsort</function> and <function>natcasesort</function>.
</simpara>
</refsect1>
</refentry>
<refentry id="function.strnatcasecmp">
<refnamediv>
<refname>strnatcasecmp</refname>
<refpurpose>
Case insensitive string comparisons using a "natural order"
algorithm
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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 infomation see: Martin Pool's <ulink
url="&url.strnatcmp;">Natural Order String Comparison</ulink>
page.
</para>
<simpara>
Similar to other string comparison functions, this one returns
&lt; 0 if <parameter>str1</parameter> is less than
<parameter>str2</parameter>; &gt; 0 if
<parameter>str1</parameter> is greater than
<parameter>str2</parameter>, and 0 if they are equal.
</simpara>
<simpara>
See also <function>ereg</function>,
<function>strcasecmp</function>, <function>substr</function>,
<function>stristr</function>, <function>strcmp</function>,
<function>strncmp</function>, <function>strncasecmp</function>,
<function>strnatcmp</function>, and <function>strstr</function>.
</simpara>
</refsect1>
</refentry>
<refentry id="function.strncmp">
<refnamediv>
<refname>strncmp</refname>
<refpurpose>
Binary safe string comparison of the first n characters
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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. If any of the strings is shorter than
<parameter>len</parameter>, then the length of that string will
be used for the comparison.
</para>
<simpara>
Returns &lt; 0 if <parameter>str1</parameter> is less than
<parameter>str2</parameter>; &gt; 0 if <parameter>str1</parameter>
is greater than <parameter>str2</parameter>, and 0 if they are
equal.
</simpara>
<simpara>
Note that this comparison is case sensitive.
</simpara>
<simpara>
See also <function>ereg</function>,
<function>strncasecmp</function>,
<function>strcasecmp</function>, <function>substr</function>,
<function>stristr</function>, <function>strcmp</function>, and
<function>strstr</function>.
</simpara>
</refsect1>
</refentry>
<refentry id="function.str-pad">
<refnamediv>
<refname>str_pad</refname>
<refpurpose>
Pad a string to a certain length with another string
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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
STR_PAD_RIGHT, STR_PAD_LEFT, or STR_PAD_BOTH. If
<parameter>pad_type</parameter> is not specified it is assumed to
be STR_PAD_RIGHT.
</para>
<para>
If the value of <parameter>pad_length</parameter> is negative or
less than the length of the input string, no padding takes place.
</para>
<para>
<example>
<title><function>str_pad</function> example</title>
<programlisting role="php">
<![CDATA[
$input = "Alien";
print str_pad($input, 10); // produces "Alien "
print str_pad($input, 10, "-=", STR_PAD_LEFT); // produces "-=-=-Alien"
print str_pad($input, 10, "_", STR_PAD_BOTH); // produces "__Alien___"
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.strpos">
<refnamediv>
<refname>strpos</refname>
<refpurpose>
Find position of first occurrence of a string
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>strpos</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> string. Unlike the
<function>strrpos</function>, 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, returns &false;.
<note>
<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[
// in PHP 4.0b3 and newer:
$pos = strpos($mystring, "b");
if ($pos === false) { // note: three equal signs
// not found...
}
// in versions older than 4.0b3:
$pos = strpos($mystring, "b");
if (!is_integer($pos)) {
// not found...
}
]]>
</programlisting>
</informalexample>
</para>
</note>
</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
the beginning of <parameter>haystack</parameter>.
</para>
<para>
See also <function>strrpos</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, the first is used.
</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[
// get last directory in $PATH
$dir = substr(strrchr($PATH, ":"), 1);
// get everything after last newline
$text = "Line 1\nLine 2\nLine 3";
$last = substr(strrchr($text, 10), 1 );
]]>
</programlisting>
</example>
</para>
<para>
See also <function>strchr</function>, <function>substr</function>,
<function>stristr</function>, and <function>strstr</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.str-repeat">
<refnamediv>
<refname>str_repeat</refname>
<refpurpose>Repeat a string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>str_repeat</methodname>
<methodparam><type>string</type><parameter>input</parameter></methodparam>
<methodparam><type>int</type><parameter>multiplier</parameter></methodparam>
</methodsynopsis>
<para>
Returns <parameter>input_str</parameter> repeated
<parameter>multiplier</parameter> times.
<parameter>multiplier</parameter> has to be greater than 0.
</para>
<example>
<title><function>str_repeat</function> example</title>
<programlisting role="php">
<![CDATA[
echo str_repeat("-=", 10);
]]>
</programlisting>
</example>
<para>
This will output "-=-=-=-=-=-=-=-=-=-=".
</para>
<para>
See also <function>substr_count</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.strrev">
<refnamediv>
<refname>strrev</refname>
<refpurpose>Reverse a string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>strrev</methodname>
<methodparam><type>string</type><parameter>string</parameter></methodparam>
</methodsynopsis>
<para>
Returns <parameter>string</parameter>, reversed.
<example>
<title>Reversing a string with <function>strrev</function></title>
<programlisting role="php">
<![CDATA[
<php
echo strrev("Hello world!"); // outputs "!dlrow olleH"
?>
]]>
</programlisting>
</example>
</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>char</type><parameter>needle</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. 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;.
<note>
<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[
// in PHP 4.0b3 and newer:
$pos = strrpos($mystring, "b");
if ($pos === false) { // note: three equal signs
// not found...
}
// in versions older than 4.0b3:
$pos = strrpos($mystring, "b");
if (is_string($pos) && !$pos) {
// not found...
}
]]>
</programlisting>
</informalexample>
</para>
</note>
</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>
See also <function>strpos</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>
</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[
$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>
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">
<![CDATA[
$email = 'user@example.com';
$domain = strstr($email, '@');
print $domain; // prints @example.com
]]>
</programlisting>
</example>
</para>
<para>
See also <function>ereg</function>, <function>preg_match</function>,
<function>strchr</function>, <function>stristr</function>,
<function>strpos</function>, <function>strrchr</function>, and
<function>substr</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.strtok">
<refnamediv>
<refname>strtok</refname>
<refpurpose>Tokenize string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>strtok</methodname>
<methodparam><type>string</type><parameter>arg1</parameter></methodparam>
<methodparam><type>string</type><parameter>arg2</parameter></methodparam>
</methodsynopsis>
<para>
<function>strtok</function> splits a string (<parameter>arg1</parameter>)
into smaller strings (tokens), with each token being delimited by any
character from <parameter>arg2</parameter>.
That is, if you have a string like "This is an example string" you
could tokenize this string into its individual words by using the
space character as the token.
<example>
<title><function>strtok</function> example</title>
<programlisting role="php">
<![CDATA[
$string = "This is\tan example\nstring";
/* Use tab and newline as tokenizing characters as well */
$tok = strtok($string," \n\t");
while ($tok) {
echo "Word=$tok<br>";
$tok = strtok(" \n\t");
}
]]>
</programlisting>
</example>
</para>
<para>
Note that only the first call to strtok uses the string argument.
Every subsequent call to strtok only needs the token to use, as
it keeps track of where it is in the current string. To start
over, or to tokenize a new string you simply call strtok with the
string argument again to initialize it. Note that you may put
multiple tokens in the token parameter. The string will be
tokenized when any one of the characters in the argument are
found.
</para>
<para>
The behavior when an empty part was found changed with PHP 4.1.0. The old
behavior returned an empty string, while the new, correct, behavior
simply skips the part of the string:
<example>
<title>Old <function>strtok</function> behavior</title>
<programlisting role="php">
<![CDATA[
$first_token = strtok('/something', '/');
$second_token = strtok('/');
var_dump ($first_token, $second_token);
/* Output:
string(0) ""
string(9) "something"
*/
]]>
</programlisting>
</example>
<example>
<title>New <function>strtok</function> behavior</title>
<programlisting role="php">
<![CDATA[
$first_token = strtok('/something', '/');
$second_token = strtok('/');
var_dump ($first_token, $second_token);
/* Output:
string(9) "something"
bool(false)
*/
]]>
</programlisting>
</example>
</para>
<para>
Also be careful that your tokens may be equal to "0". This
evaluates to &false; in conditional expressions.
</para>
<para>
See also <function>split</function> and
<function>explode</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 (&Auml;) will not be converted.
</para>
<example>
<title><function>strtolower</function> example</title>
<programlisting role="php">
<![CDATA[
$str = "Mary Had A Little Lamb and She LOVED It So";
$str = strtolower($str);
print $str; # Prints mary had a little lamb and she loved it so
]]>
</programlisting>
</example>
<para>
See also <function>strtoupper</function>,
<function>ucfirst</function>,
and <function>ucwords</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
(<28>) will not be converted.
</para>
<example>
<title><function>strtoupper</function> example</title>
<programlisting role="php">
<![CDATA[
$str = "Mary Had A Little Lamb and She LOVED It So";
$str = strtoupper($str);
print $str; # Prints MARY HAD A LITTLE LAMB AND SHE LOVED IT SO
]]>
</programlisting>
</example>
<para>
See also <function>strtolower</function>,
<function>ucfirst</function>,
and <function>ucwords</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.str-replace">
<refnamediv>
<refname>str_replace</refname>
<refpurpose>
Replace all occurrences of the search string with the replacement string
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>mixed</type><methodname>str_replace</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>
</methodsynopsis>
<para>
This function returns a string or an array with all occurences of
<parameter>search</parameter> in <parameter>subject</parameter>
replaced with the given <parameter>replace</parameter> value. If
you don't need fancy replacing rules, you should always use this
function instead of <function>ereg_replace</function> or
<function>preg_replace</function>.
</para>
<para>
In PHP 4.0.5 and later, every parameter to
<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>.
</para>
<para>
<example>
<title><function>str_replace</function> example</title>
<programlisting role="php">
<![CDATA[
$bodytag = str_replace("%body%", "black", "<body text=%body%>");
]]>
</programlisting>
</example>
</para>
<para>
This function is binary safe.
</para>
<note>
<para>
<function>str_replace</function> was added in PHP 3.0.6, but was
buggy up until PHP 3.0.8.
</para>
</note>
<para>
See also <function>ereg_replace</function>,
<function>preg_replace</function>, and <function>strtr</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.strtr">
<refnamediv>
<refname>strtr</refname>
<refpurpose>Translate certain characters</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>strtr</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
<methodparam><type>string</type><parameter>from</parameter></methodparam>
<methodparam><type>string</type><parameter>to</parameter></methodparam>
</methodsynopsis>
<methodsynopsis>
<type>string</type><methodname>strtr</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
<methodparam><type>array</type><parameter>replace_pairs</parameter></methodparam>
</methodsynopsis>
<para>
This function returns a copy of <parameter>str</parameter>,
translating all occurrences of each character in
<parameter>from</parameter> to the corresponding character in
<parameter>to</parameter> and returning the result.
</para>
<para>
If <parameter>from</parameter> and <parameter>to</parameter> are
different lengths, the extra characters in the longer of the two
are ignored.
<example>
<title><function>strtr</function> example</title>
<programlisting role="php">
<![CDATA[
$addr = strtr($addr, "<22><><EFBFBD>", "aao");
]]>
</programlisting>
</example>
</para>
<para>
<function>strtr</function> can be called with only two
arguments. If called with two arguments it behaves in a new way:
<parameter>from</parameter> then has to be an array that contains
string -> string pairs that will be replaced in the source
string. <function>strtr</function> will always look for the
longest possible match first and will *NOT* try to replace stuff
that it has already worked on.
</para>
<para>
Examples:
<informalexample>
<programlisting role="php">
<![CDATA[
$trans = array("hello" => "hi", "hi" => "hello");
echo strtr("hi all, I said hello", $trans) . "\n";
]]>
</programlisting>
</informalexample>
This will show: "hello all, I said hi",
</para>
<note>
<simpara>
This optional <parameter>to</parameter> and
<parameter>from</parameter> parameters were added in PHP 4.0.0
</simpara>
</note>
<para>
See also <function>ereg_replace</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>
Substr 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 positive, 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[
$rest = substr("abcdef", 1); // returns "bcdef"
$rest = substr("abcdef", 1, 3); // returns "bcd"
$rest = substr("abcdef", 0, 4); // returns "abcd"
$rest = substr("abcdef", 0, 8); // returns "abcdef"
]]>
</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[
$rest = substr("abcdef", -1); // returns "f"
$rest = substr("abcdef", -2); // returns "ef"
$rest = substr("abcdef", -3, 1); // returns "d"
]]>
</programlisting>
</example>
<para>
If <parameter>length</parameter> is given and is positive, the string
returned will contain at most <parameter>length</parameter> characters
beginning from <parameter>start</parameter> (depending on the length of
<parameter>string</parameter>. If <parameter>string</parameter> is less
than <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[
$rest = substr("abcdef", 0, -1); // returns "abcde"
$rest = substr("abcdef", 2, -1); // returns "cde"
$rest = substr("abcdef", 4, -4); // returns ""
$rest = substr("abcdef", -3, -1); // returns "de"
]]>
</programlisting>
</example>
<para>
See also <function>strrchr</function> and
<function>ereg</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.substr-count">
<refnamediv>
<refname>substr_count</refname>
<refpurpose>Count the number of substring occurrences</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>substr_count</methodname>
<methodparam><type>string</type><parameter>haystack</parameter></methodparam>
<methodparam><type>string</type><parameter>needle</parameter></methodparam>
</methodsynopsis>
<para>
<function>substr_count</function> returns the number of times the
<parameter>needle</parameter> substring occurs in the
<parameter>haystack</parameter> string.
</para>
<para>
<example>
<title><function>substr_count</function> example</title>
<programlisting>
<![CDATA[
print substr_count("This is a test", "is"); // prints out 2
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.substr-replace">
<refnamediv>
<refname>substr_replace</refname>
<refpurpose>Replace text within a portion of a string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>substr_replace</methodname>
<methodparam><type>string</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 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>.
</para>
<para>
<example>
<title><function>substr_replace</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$var = 'ABCDEFGH:/MNRPQR/';
echo "Original: $var<hr>\n";
/* These two examples replace all of $var with 'bob'. */
echo substr_replace($var, 'bob', 0) . "<br>\n";
echo substr_replace($var, 'bob', 0, strlen($var)) . "<br>\n";
/* Insert 'bob' right at the beginning of $var. */
echo substr_replace($var, 'bob', 0, 0) . "<br>\n";
/* These next two replace 'MNRPQR' in $var with 'bob'. */
echo substr_replace($var, 'bob', 10, -1) . "<br>\n";
echo substr_replace($var, 'bob', -7, -1) . "<br>\n";
/* Delete 'MNRPQR' from $var. */
echo substr_replace($var, '', 10, -1) . "<br>\n";
?>
]]>
</programlisting>
</example>
</para>
<para>
See also <function>str_replace</function> and
<function>substr</function>.
</para>
</refsect1>
</refentry>
<!-- this section is nearly-identical to trim, ltrim and rtrim -->
<refentry id="function.trim">
<refnamediv>
<refname>trim</refname>
<refpurpose>
Strip whitespace from the beginning and end of a string
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>trim</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>charlist</parameter></methodparam>
</methodsynopsis>
<note>
<simpara>
The optional <parameter>charlist</parameter> parameter was
added in PHP 4.1.0
</simpara>
</note>
<para>
This function returns a string with whitespace stripped from the
beginning and end of <parameter>str</parameter>.
Without the second parameter,
<function>trim</function> will strip these characters:
<!-- sorted by importance. Printed 3 times: trim, ltrim, rtrim -->
<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> <!-- not \v, since not supported by PHP -->
"\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>trim</function></title>
<para>
<programlisting role="php">
<![CDATA[
<?php
$text = "\t\tThese are a few words :) ... ";
$trimmed = trim($text);
// $trimmed = "These are a few words :) ..."
$trimmed = trim($text," \t.");
// $trimmed = "These are a few words :)"
$clean = trim($binary,"\0x00..\0x1F");
// trim the ASCII control characters at the beginning and end of $binary
// (from 0 to 31 inclusive)
?>
]]>
</programlisting>
</para>
</example>
<para>
See also <function>ltrim</function> and <function>rtrim</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.ucfirst">
<refnamediv>
<refname>ucfirst</refname>
<refpurpose>Make a string's first character uppercase</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>ucfirst</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
</methodsynopsis>
<para>
Returns a string with the first character of
<parameter>str</parameter> capitalized, if that character is
alphabetic.
</para>
<para>
Note that 'alphabetic' is determined by the current locale. For
instance, in the default "C" locale characters such as umlaut-a
(&auml;) will not be converted.
<example>
<title><function>ucfirst</function> example</title>
<programlisting role="php">
<![CDATA[
$foo = 'hello world!';
$foo = ucfirst($foo); // Hello world!
$bar = 'HELLO WORLD!';
$bar = ucfirst($bar); // HELLO WORLD!
$bar = ucfirst(strtolower($bar)); // Hello world!
]]>
</programlisting>
</example>
</para>
<para>
See also <function>strtolower</function>, <function>strtoupper</function>,
and <function>ucwords</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.
<example>
<title><function>ucwords</function> example</title>
<programlisting role="php">
<![CDATA[
$foo = 'hello world!';
$foo = ucwords($foo); // Hello World!
$bar = 'HELLO WORLD!';
$bar = ucwords($bar); // HELLO WORLD!
$bar = ucwords(strtolower($bar)); // Hello World!
]]>
</programlisting>
</example>
<note>
<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>
</note>
</para>
<para>
See also <function>strtoupper</function>,
<function>strtolower</function> and <function>ucfirst</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.vprintf">
<refnamediv>
<refname>vprintf</refname>
<refpurpose>Output a formatted string</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>void</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>
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>, <function>vsprintf</function>,
<function>vprintf</function>
</simpara>
</refsect1>
</refentry>
<refentry id="function.wordwrap">
<refnamediv>
<refname>wordwrap</refname>
<refpurpose>
Wraps a string to a given number of characters using a string
break character.
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>wordwrap</methodname>
<methodparam><type>string</type><parameter>str</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>width</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>break</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>cut</parameter></methodparam>
</methodsynopsis>
<para>
Returns a string with <parameter>str</parameter> wrapped
at the column number specified by the (optional)
<parameter>width</parameter> parameter. The line is broken
using the (optional) <parameter>break</parameter> parameter.
</para>
<para>
<function>wordwrap</function> will automatically wrap at column
75 and break using '\n' (newline) if <parameter>width</parameter>
or <parameter>break</parameter> are not given.
</para>
<para>
If the <parameter>cut</parameter> is set to 1, the string is
always wrapped at the specified width. So if you have a word
that is larger than the given width, it is broken apart.
(See second example).
<note>
<para>
The optional <parameter>cut</parameter> parameter was added in PHP 4.0.3
</para>
</note>
</para>
<para>
<example>
<title><function>wordwrap</function> example</title>
<programlisting role="php">
<![CDATA[
$text = "The quick brown fox jumped over the lazy dog.";
$newtext = wordwrap( $text, 20 );
echo "$newtext\n";
]]>
</programlisting>
</example>
</para>
<para>
This example would display:
</para>
<para>
<informalexample>
<screen>
<![CDATA[
The quick brown fox
jumped over the lazy dog.
]]>
</screen>
</informalexample>
</para>
<para>
<example>
<title><function>wordwrap</function> example</title>
<programlisting role="php">
<![CDATA[
$text = "A very long woooooooooooord.";
$newtext = wordwrap( $text, 8, "\n", 1);
echo "$newtext\n";
]]>
</programlisting>
</example>
</para>
<para>
This example would display:
</para>
<para>
<informalexample>
<screen>
<![CDATA[
A very
long
wooooooo
ooooord.
]]>
</screen>
</informalexample>
</para>
<para>
See also <function>nl2br</function>.
</para>
</refsect1>
</refentry>
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Reference in a new issue View git blame Copy permalink