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üfung Prü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üfung Prüfung", $preferences);
+$preferences["scheme"] = "B";
+// This yields "Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?="
+echo iconv_mime_encode("Subject", "Prüfung Prü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>
