cvs: phpdoc /en/reference/iconv configure.xml constants.xml /en/reference/iconv/functions iconv-mime-decode.xml iconv-mime-encode.xml
iconv-strlen.xml iconv-strpos.xml iconv-strrpos.xml iconv.xml

moriyoshi Sun Dec 21 23:38:16 2003 EDT Modified files: /phpdoc/en/reference/iconv configure.xml constants.xml /phpdoc/en/reference/iconv/functions iconv-mime-decode.xml iconv-mime-encode.xml iconv-strlen.xml iconv-strpos.xml iconv-strrpos.xml iconv.xml Log: Misc. updates and corrections.

Index: phpdoc/en/reference/iconv/configure.xml diff -u phpdoc/en/reference/iconv/configure.xml:1.2 phpdoc/en/reference/iconv/configure.xml:1.3 --- phpdoc/en/reference/iconv/configure.xml:1.2 Wed Dec 17 09:32:25 2003 +++ phpdoc/en/reference/iconv/configure.xml Sun Dec 21 23:38:15 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.2 $ --> +<!-- $Revision: 1.3 $ --> <section id="iconv.installation"> &reftitle.install; <para> @@ -10,11 +10,12 @@ <note> <title>Note to Win32 Users</title> <simpara> - In order to enable this module on a Windows environment, you must copy - <filename>iconv-1.3.dll</filename> from the DLL folder of the PHP/Win32 binary - package to the SYSTEM32 folder of your windows machine. (Ex: <filename>C:\WINNT\SYSTEM32</filename> - or <filename>C:\WINDOWS\SYSTEM32</filename>). Starting with PHP 4.2.1 the name changed to - <filename>iconv.dll</filename> + In order to enable this module on a Windows environment, you need to put + a DLL file named <emphasis>iconv.dll</emphasis> or + <emphasis>iconv-1.3.dll</emphasis> (prior to 4.2.1) + which is bundled with the PHP/Win32 binary package into a directory + that is specified by the PATH environment variable + or one of the system directories of your windows installation. </simpara> </note> </section> Index: phpdoc/en/reference/iconv/constants.xml diff -u phpdoc/en/reference/iconv/constants.xml:1.3 phpdoc/en/reference/iconv/constants.xml:1.4 --- phpdoc/en/reference/iconv/constants.xml:1.3 Wed May 28 19:03:07 2003 +++ phpdoc/en/reference/iconv/constants.xml Sun Dec 21 23:38:15 2003 @@ -1,18 +1,18 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <section id="iconv.constants"> &reftitle.constants; <para> - Since PHP 4.3.0 it is possible to identify at runtime which iconv - implementation is adopted by this extension. + Since <application>PHP</application> 4.3.0 it is possible to identify at + runtime which <literal>iconv</literal> implementation is adopted by this extension. <table> - <title>iconv constants</title> + <title><literal>iconv</literal> constants</title> <tgroup cols="3"> <thead> <row> - <entry>constant</entry> - <entry>type</entry> - <entry>description</entry> + <entry>Name</entry> + <entry>Type</entry> + <entry>Description</entry> </row> </thead> <tbody> @@ -32,10 +32,38 @@ </para> <note> <para> - Writing implementation-dependent scripts with these constants should be + Writing implementation-dependent scripts with these constants is strongly discouraged. </para> </note> + <para> + Since <application>PHP</application> 5.0.0, the following constants are + also available: + <table> + <title><literal>iconv</literal> constants available since PHP 5.0.0</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Name</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>ICONV_MIME_DECODE_STRICT</entry> + <entry><type>integer</type></entry> + <entry>A bitmask used for <function>iconv_mime_decode</function></entry> + </row> + <row> + <entry>ICONV_MIME_DECODE_CONTINUE_ON_ERROR</entry> + <entry><type>integer</type></entry> + <entry>A bitmask used for <function>iconv_mime_decode</function></entry> + </row> + </tbody> + </tgroup> + </table> + </para> </section> <!-- Keep this comment at the end of the file Index: phpdoc/en/reference/iconv/functions/iconv-mime-decode.xml diff -u phpdoc/en/reference/iconv/functions/iconv-mime-decode.xml:1.1 phpdoc/en/reference/iconv/functions/iconv-mime-decode.xml:1.2 --- phpdoc/en/reference/iconv/functions/iconv-mime-decode.xml:1.1 Sun Nov 2 11:53:20 2003 +++ phpdoc/en/reference/iconv/functions/iconv-mime-decode.xml Sun Dec 21 23:38:16 2003 @@ -1,11 +1,11 @@ <?xml version='1.0' encoding='iso-8859-1'?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. --> <refentry id="function.iconv-mime-decode"> <refnamediv> <refname>iconv_mime_decode</refname> <refpurpose> - Decodes a mime header field + Decodes a <literal>MIME</literal> header field </refpurpose> </refnamediv> <refsect1> @@ -13,11 +13,76 @@ <methodsynopsis> <type>string</type><methodname>iconv_mime_decode</methodname> <methodparam><type>string</type><parameter>encoded_string</parameter></methodparam> + <methodparam choice="opt"><type>int</type><parameter>mode</parameter></methodparam> <methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; + <para> + Returns a decoded <literal>MIME</literal> field on success, + or &false; if an error occurs during the decoding. + </para> + <para> + <parameter>mode</parameter> determines the behaviour in the event + <function>iconv_mime_decode</function> encounters a malformed + <literal>MIME</literal> header field. You can specify any combination + of the following bitmasks. + <table> + <title>Bitmasks acceptable to <function>iconv_mime_decode</function></title> + <tgroup cols="3"> + <thead> + <row> + <entry>Value</entry> + <entry>Constant</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>1</entry> + <entry>ICONV_MIME_DECODE_STRICT</entry> + <entry> + If set, the given header is decoded in full conformance with the + standards defined in <ulink url="&url.rfc;2047">RFC2047</ulink>. + This option is disabled by default because there are a lot of + broken mail user agents that don't follow the specification and don't + produce correct <literal>MIME</literal> headers. + </entry> + </row> + <row> + <entry>2</entry> + <entry>ICONV_MIME_DECODE_CONTINUE_ON_ERROR</entry> + <entry> + If set, <function>iconv_mime_decode</function> attempts to continue + to process the given header even though an error occurs. + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + + <para> + The optional <parameter>charset</parameter> parameter specifies the + character set to represent the result by. If omitted, + <link linkend="iconv.configuration">iconv.internal_charset</link> + will be used. + </para> + + <para> + <example> + <title><function>iconv_mime_decode</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +// This yields "Subject: Pr&uuml;fung Pr&uuml;fung" +echo iconv_mime_decode("Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=", + 0, "ISO-8859-1"); +?> +]]> + </programlisting> + </example> + </para> </refsect1> </refentry> Index: phpdoc/en/reference/iconv/functions/iconv-mime-encode.xml diff -u phpdoc/en/reference/iconv/functions/iconv-mime-encode.xml:1.1 phpdoc/en/reference/iconv/functions/iconv-mime-encode.xml:1.2 --- phpdoc/en/reference/iconv/functions/iconv-mime-encode.xml:1.1 Sun Nov 2 11:53:20 2003 +++ phpdoc/en/reference/iconv/functions/iconv-mime-encode.xml Sun Dec 21 23:38:16 2003 @@ -1,11 +1,11 @@ <?xml version='1.0' encoding='iso-8859-1'?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. --> <refentry id="function.iconv-mime-encode"> <refnamediv> <refname>iconv_mime_encode</refname> <refpurpose> - Composes a mime header field with field_name and field_value in a specified scheme + Composes a <literal>MIME</literal> header field </refpurpose> </refnamediv> <refsect1> @@ -14,11 +14,137 @@ <type>string</type><methodname>iconv_mime_encode</methodname> <methodparam><type>string</type><parameter>field_name</parameter></methodparam> <methodparam><type>string</type><parameter>field_value</parameter></methodparam> - <methodparam choice="opt"><type>array</type><parameter>preference</parameter></methodparam> + <methodparam choice="opt"><type>array</type><parameter>preferences</parameter></methodparam> </methodsynopsis> + <para> + Composes and returns a string that represents a valid <literal>MIME</literal> + header field, which looks like the following: + <screen> +<![CDATA[ +Subject: =?ISO-8859-1?Q?Pr=FCfung_f=FCr?= Entwerfen von einer MIME kopfzeile +]]> + </screen> + In the above example, "Subject" is the field name and the portion that + begins with "=?ISO-8859-1?..." is the field value. + </para> + <para> + You can control the behaviour of <function>iconv_mime_encode</function> + by specifying an associative array that contains configuration items + to the optional third parameter <parameter>preferences</parameter>. + The items supported by <function>iconv_mime_encode</function> are + listed below. Note that item names are treated case-sensitive. + <table> + <title>Configuration items supported by <function>iconv_mime_encode</function></title> + <tgroup cols="5"> + <thead> + <row> + <entry>Item</entry> + <entry>Type</entry> + <entry>Description</entry> + <entry>Default value</entry> + <entry>Example</entry> + </row> + </thead> + <tbody> + <row> + <entry>scheme</entry> + <entry><type>boolean</type></entry> + <entry> + Specifies the method to encode a field value by. The value of + this item may be either "B" or "Q", where "B" stands for + <literal>base64</literal> encoding scheme and "Q" stands for + <literal>quoted-printable</literal> encoding scheme. + </entry> + <entry>B</entry> + <entry>B</entry> + </row> + <row> + <entry>input-charset</entry> + <entry><type>string</type></entry> + <entry> + Specifies the character set in which the first parameter + <parameter>field_name</parameter> and the second parameter + <parameter>field_value</parameter> are presented. If not given, + <function>iconv_mime_encode</function> assumes those parameters + are presented to it in the + <link linkend="iconv.configuration">iconv.internal_charset</link> + ini setting. + </entry> + <entry> + <link linkend="iconv.configuration">iconv.internal_charset</link> + </entry> + <entry>ISO-8859-1</entry> + </row> + <row> + <entry>output-charset</entry> + <entry><type>string</type></entry> + <entry> + Specifies the character set to use to compose the + <literal>MIME</literal> header. If not given, the same value as + <literal>input-charset</literal> will be used. + </entry> + <entry> + the same value as <literal>input-charset</literal> + </entry> + <entry>UTF-8</entry> + </row> + <row> + <entry>line-length</entry> + <entry><type>integer</type></entry> + <entry> + Specifies the maximum length of the header lines. The resulting + header is "folded" to a set of multiple lines in case + the resulting header field would be longer than the value of this + parameter, according to + <ulink url="&url.rfc;2822">RFC2822 - Internet Message Format</ulink>. + If not given, the length will be limited to 76 characters. + </entry> + <entry>76</entry> + <entry>996</entry> + </row> + <row> + <entry>line-break-chars</entry> + <entry><type>string</type></entry> + <entry> + Specifies the sequence of characters to append to each line + as an end-of-line sign when "folding" is performed on a long header + field. If not given, this defaults to "\r\n" + (<literal>CR</literal> <literal>LF</literal>). Note that + this parameter is always treated as an ASCII string regardless + of the value of <literal>input-charset</literal>. + </entry> + <entry>\r\n</entry> + <entry>\n</entry> + </row> + </tbody> + </tgroup> + </table> + </para> - &warn.undocumented.func; + <para> + <example> + <title><function>iconv_mime_encode</function> example:</title> + <programlisting role="php"> +<![CDATA[ +<?php +$preferences = array( + "input-charset" => "ISO-8859-1", + "output-charset" => "UTF-8", + "line-length" => 76, + "line-break-chars" => "\n" +); +$preferences["scheme"] = "Q"; +// This yields "Subject: =?UTF-8?Q?Pr=C3=BCfung_Pr=C3=BCfung?=" +echo iconv_mime_encode("Subject", "Pr&uuml;fung Pr&uuml;fung", $preferences); +$preferences["scheme"] = "B"; +// This yields "Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=" +echo iconv_mime_encode("Subject", "Pr&uuml;fung Pr&uuml;fung", $preferences); +?> +]]> + </programlisting> + </example> + </para> </refsect1> </refentry> Index: phpdoc/en/reference/iconv/functions/iconv-strlen.xml diff -u phpdoc/en/reference/iconv/functions/iconv-strlen.xml:1.4 phpdoc/en/reference/iconv/functions/iconv-strlen.xml:1.5 --- phpdoc/en/reference/iconv/functions/iconv-strlen.xml:1.4 Mon Nov 3 04:31:57 2003 +++ phpdoc/en/reference/iconv/functions/iconv-strlen.xml Sun Dec 21 23:38:16 2003 @@ -1,5 +1,5 @@ <?xml version='1.0' encoding='iso-8859-1'?> -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. --> <refentry id="function.iconv-strlen"> <refnamediv> @@ -19,16 +19,21 @@ Returns the character count of <parameter>str</parameter>. </para> <para> - In contrast to <function>strlen</function>, the return value of - <function>iconv_strlen</function> is the number of characters that occur - in the given byte sequence <parameter>str</parameter>, which is not - necessarily the same as the byte length of the string. + In contrast to <function>strlen</function>, + <function>iconv_strlen</function> counts the occurrences of characters + in the given byte sequence <parameter>str</parameter> on the basis of + the specified character set, the result of which is not necessarily + identical to the length of the string in byte. </para> <para> If <parameter>charset</parameter> parameter is omitted, - <parameter>str</parameter> will be assumed to be encoded in + <parameter>str</parameter> is assumed to be encoded in <link linkend="iconv.configuration">iconv.internal_charset</link>. </para> + + <para> + See also <function>strlen</function> and <function>mb_strlen</function>. + </para> </refsect1> </refentry> Index: phpdoc/en/reference/iconv/functions/iconv-strpos.xml diff -u phpdoc/en/reference/iconv/functions/iconv-strpos.xml:1.3 phpdoc/en/reference/iconv/functions/iconv-strpos.xml:1.4 --- phpdoc/en/reference/iconv/functions/iconv-strpos.xml:1.3 Mon Nov 3 04:41:13 2003 +++ phpdoc/en/reference/iconv/functions/iconv-strpos.xml Sun Dec 21 23:38:16 2003 @@ -1,5 +1,5 @@ <?xml version='1.0' encoding='iso-8859-1'?> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. --> <refentry id="function.iconv-strpos"> <refnamediv> @@ -34,13 +34,27 @@ <para> If <parameter>haystack</parameter> or <parameter>needle</parameter> is - not a string, it is converted to an integer and applied as the ordinal + not a string, it is converted to a string and applied as the ordinal value of a character. </para> <para> - See also <function>strpos</function> and - <function>iconv_strrpos</function>. + In contrast to <function>strpos</function>, the return value of + <function>iconv_strpos</function> is the number of characters that + appear before the needle, rather than the offset in bytes to the + position where the needle has been found. The characters are counted + on the basis of the specified character set <parameter>charset</parameter>. + </para> + + <para> + If <parameter>charset</parameter> parameter is omitted, + <parameter>string</parameter> are assumed to be encoded in + <link linkend="iconv.configuration">iconv.internal_charset</link>. + </para> + + <para> + See also <function>strpos</function>, <function>iconv_strrpos</function>, + and <function>mb_strpos</function>. </para> </refsect1> </refentry> Index: phpdoc/en/reference/iconv/functions/iconv-strrpos.xml diff -u phpdoc/en/reference/iconv/functions/iconv-strrpos.xml:1.1 phpdoc/en/reference/iconv/functions/iconv-strrpos.xml:1.2 --- phpdoc/en/reference/iconv/functions/iconv-strrpos.xml:1.1 Sun Nov 2 11:53:20 2003 +++ phpdoc/en/reference/iconv/functions/iconv-strrpos.xml Sun Dec 21 23:38:16 2003 @@ -1,11 +1,11 @@ <?xml version='1.0' encoding='iso-8859-1'?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. --> <refentry id="function.iconv-strrpos"> <refnamediv> <refname>iconv_strrpos</refname> <refpurpose> - Finds position of last occurrence of needle within part of haystack beginning with offset + Finds the last occurrence of a needle within the specified range of haystack. </refpurpose> </refnamediv> <refsect1> @@ -16,9 +16,32 @@ <methodparam><type>string</type><parameter>needle</parameter></methodparam> <methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam> </methodsynopsis> + <para> + Returns the numeric position of the last occurrence of + <parameter>needle</parameter> in <parameter>haystack</parameter>. + </para> - &warn.undocumented.func; + <para> + If <parameter>needle</parameter> is not found, + <function>iconv_strrpos</function> will return &false;. + </para> + &return.falseproblem; + + <para> + If <parameter>haystack</parameter> or <parameter>needle</parameter> is + not a string, it is converted to a string and applied as the ordinal + value of a character. + </para> + + <para> + In contrast to <function>strpos</function>, the return value of + <function>iconv_strrpos</function> is the number of characters that + appear before the needle, rather than the offset in bytes to the + position where the needle has been found. The characters are counted + on the basis of the specified character set <parameter>charset</parameter>. + </para> + </refsect1> </refentry> Index: phpdoc/en/reference/iconv/functions/iconv.xml diff -u phpdoc/en/reference/iconv/functions/iconv.xml:1.7 phpdoc/en/reference/iconv/functions/iconv.xml:1.8 --- phpdoc/en/reference/iconv/functions/iconv.xml:1.7 Mon Dec 15 11:50:38 2003 +++ phpdoc/en/reference/iconv/functions/iconv.xml Sun Dec 21 23:38:16 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.7 $ --> +<!-- $Revision: 1.8 $ --> <!-- splitted from ./en/functions/iconv.xml, last change in rev 1.1 --> <refentry id="function.iconv"> <refnamediv> @@ -15,10 +15,10 @@ <methodparam><type>string</type><parameter>str</parameter></methodparam> </methodsynopsis> <para> - It converts the string <parameter>str</parameter> encoded in - <parameter>in_charset</parameter> to the string encoded in - <parameter>out_charset</parameter>. It returns the converted - string or &false;, if it fails. + Performs a character set conversion on the string + <parameter>str</parameter> from <parameter>in_charset</parameter> + to <parameter>out_charset</parameter>. Returns the converted + string or &false; on failure. </para> <para> <example>