<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
 <reference id="ref.mbstring">
  <title>Multi-Byte String Functions</title> 
  <titleabbrev>
   Multi-Byte String
  </titleabbrev>
  <partintro>
   &warn.experimental;
   <sect1 id="mb-intro">
    <title>Introduction</title>
    <warning>
     <simpara>
      This module is EXPERIMENTAL. Function name/API is subject to
      change. Current conversion filter supports Japanese only.
     </simpara>
    </warning>
    <para>
     There are many languages in which all characters can be expressed
     by single byte. Multi-byte character codes are used to express
     many characters for many languages.  <literal>mbstring</literal>
     is developed to handle Japanese characters. However, many
     <literal>mbstring</literal> functions are able to handle
     character encoding other than Japanese.
    </para>
    <para>
     A multi-byte character encoding represents single character with
     consecutive bytes. Some character encoding has shift(escape)
     sequences to start/end multi-byte character strings. Therefore, a
     multi-byte character string may be destroyed when it is divided
     and/or counted unless multi-byte character encoding safe method
     is used. This module provides multi-byte character safe string
     functions and other utility functions such as conversion
     functions.
    </para>
    <para>
     Since PHP is basically designed for ISO-8859-1, some multi-byte
     character encoding does not work well with PHP. Therefore, it is
     important to set <literal>mbstring.internal_encoding</literal> to
     a character encoding that works with PHP.
    </para>
    <para>
     PHP4 Character Encoding Requirements 
    </para>
    <para>
     <itemizedlist>
      <listitem>
       <simpara>
        Per byte encoding
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Single byte characters in range of <literal>00h-7fh</literal>
        which is compatible with <literal>ASCII</literal>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        Multi-byte characters without <literal>00h-7fh</literal>
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     These are examples of internal character encoding that works with
     PHP and does NOT work with PHP.
     <informalexample>
      <programlisting>
<![CDATA[
Character encodings work with PHP: 
ISO-8859-*, EUC-JP, UTF-8


Character encodings do NOT work with PHP:
JIS, SJIS
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     Character encoding, that does not work with PHP, may be converted
     with <literal>mbstring</literal>'s HTTP input/output conversion
     feature/function.
    </para>
    <note>
     <para>
      SJIS should not be used for internal encoding unless the reader
      is familiar with parser/compiler, character encoding and
      character encoding issues.
     </para>
    </note>
    <note>
     <para>
      If you use database with PHP, it is recommended that you use the
      same character encoding for both database and <literal>internal
      encoding</literal> for ease of use and better performance.
      </para>
     <para>
      If you are using PostgreSQL, it supports character
      encoding that is different from backend character encoding. See
      the PostgreSQL manual for details.
     </para>
    </note>

    <sect2 id="mb-enable">
     <title>How to Enable mbstring</title>
     <para>
      <literal>mbstring</literal> is an extended module. You must
      enable module with <literal>configure</literal> script. Refer
      to the <link linkend="installation">Install</link> section for
      details.
     </para>
     <simpara>
      The following configure options are related to
      <literal>mbstring</literal> module.
     </simpara>
     <para>
      <itemizedlist>
       <listitem>
        <para>
         <option role="configure">--enable-mbstring</option> : Enable
         <literal>mbstring</literal> functions. This option is
         required to use <literal>mbstring</literal> functions.
        </para>
       </listitem>
       <listitem>
        <para>
         <option role="configure">--enable-mbstr-enc-trans</option> :
         Enable HTTP input character encoding conversion using
         <literal>mbstring</literal> conversion engine. If this
         feature is enabled, HTTP input character encoding may be
         converted to <literal>mbstring.internal_encoding</literal>
         automatically.
        </para>
       </listitem>
      </itemizedlist>
     </para>
    </sect2>

    <sect2 id="mb-conv">
     <title>HTTP Input and Output</title>
     <para>
      HTTP input/output character encoding conversion may convert
      binary data also. Users are supposed to control character
      encoding conversion if binary data is used for HTTP
      input/output.
     </para>
     <para>
      If <literal>enctype</literal> for HTML form is set to
      <literal>multipart/form-data</literal>,
      <literal>mbstring</literal> does not convert character encoding
      in POST data. If it is the case, strings are needed to be
      converted to internal character encoding.
     </para>
     <para>
      <itemizedlist>
       <listitem>
        <simpara>
         HTTP Input
        </simpara>
        <para> There is no way to control HTTP input character
         conversion from PHP script. To disable HTTP input character
         conversion, it has to be done in <literal>php.ini</literal>.
         <example>
          <title>
           Disable HTTP input conversion in php.ini
          </title>
          <programlisting role="php">
<![CDATA[
;; Disable HTTP Input conversion
mbstring.http_input = pass
]]>
          </programlisting>
         </example>
        </para>
        <para>
         When using PHP as an Apache module, it is possible to
         override PHP ini setting per Virtual Host in
         <literal>httpd.conf</literal> or per directory with
         <literal>.htaccess</literal>. Refer to the <link
          linkend="configuration">Configuration</link> section and
         Apache Manual for details.
        </para>
       </listitem>
       <listitem>
        <simpara>
         HTTP Output
        </simpara>
        <para>
         There are several ways to enable output character encoding
         conversion. One is using <literal>php.ini</literal>, another
         is using <function>ob_start</function> with
         <function>mb_output_handler</function> as
         <literal>ob_start</literal> callback function.
        </para>
        <note>
         <para>
          For PHP3-i18n users, <literal>mbstring</literal>'s output
          conversion differs from PHP3-i18n. Character encoding is
          converted using output buffer.
         </para>
        </note>
       </listitem>
      </itemizedlist>
     </para>
     <para>
      <example>
       <title><literal>php.ini</literal> setting example</title>
       <programlisting role="php">
<![CDATA[
;; Enable output character encoding conversion for all PHP pages

;; Enable Output Buffering
output_buffering    = On

;; Set mb_output_handler to enable output conversion
output_handler      = mb_output_handler
]]>
       </programlisting>
      </example>
     </para>
     <para>
      <example>
       <title>Script example</title>
       <programlisting role="php">
<![CDATA[
<?php

// Enable output character encoding conversion only for this page

// Set HTTP output character encoding to SJIS
mb_http_output('SJIS');

// Start buffering and specify "mb_output_handler" as
// callback function
ob_start('mb_output_handler');

?>
]]>
       </programlisting>
      </example>
     </para>
    </sect2>

    <sect2 id="mb-code">
     <title>Supported Character Encoding</title>
     <simpara>
      Currently, the following character encoding is supported by
      <literal>mbstring</literal> module. Caracter encoding may
      be specified for <literal>mbstring</literal> functions'
      <literal>encoding</literal> parameter.  </simpara>
     <para>
      The following character encoding is supported in this PHP
      extension : 
     </para>
     <para>
      <literal>UCS-4</literal>, <literal>UCS-4BE</literal>,
      <literal>UCS-4LE</literal>, <literal>UCS-2</literal>,
      <literal>UCS-2BE</literal>, <literal>UCS-2LE</literal>,
      <literal>UTF-32</literal>, <literal>UTF-32BE</literal>,
      <literal>UTF-32LE</literal>, <literal>UCS-2LE</literal>,
      <literal>UTF-16</literal>, <literal>UTF-16BE</literal>,
      <literal>UTF-16LE</literal>, <literal>UTF-8</literal>,
      <literal>UTF-7</literal>, <literal>ASCII</literal>,
      <literal>EUC-JP</literal>, <literal>SJIS</literal>,
      <literal>eucJP-win</literal>, <literal>SJIS-win</literal>,
      <literal>ISO-2022-JP</literal>, <literal>JIS</literal>,
      <literal>ISO-8859-1</literal>, <literal>ISO-8859-2</literal>,
      <literal>ISO-8859-3</literal>, <literal>ISO-8859-4</literal>,
      <literal>ISO-8859-5</literal>, <literal>ISO-8859-6</literal>,
      <literal>ISO-8859-7</literal>, <literal>ISO-8859-8</literal>,
      <literal>ISO-8859-9</literal>, <literal>ISO-8859-10</literal>,
      <literal>ISO-8859-13</literal>, <literal>ISO-8859-14</literal>,
      <literal>ISO-8859-15</literal>, <literal>byte2be</literal>,
      <literal>byte2le</literal>, <literal>byte4be</literal>,
      <literal>byte4le</literal>, <literal>BASE64</literal>,
      <literal>7bit</literal>, <literal>8bit</literal> and
      <literal>UTF7-IMAP</literal>.
     </para>
     <para>
      <literal>php.ini</literal> entry, which accepts encoding name,
      accepts &quot;<literal>auto</literal>&quot; and
      &quot;<literal>pass</literal>&quot; also.
      <literal>mbstring</literal> functions, which accepts encoding
      name, and accepts &quot;<literal>auto</literal>&quot;.
     </para>
     <para>
      If &quot;<literal>pass</literal>&quot; is set, no character
      encoding conversion is performed.
     </para>
     <para>
      If &quot;<literal>auto</literal>&quot; is set, it is expanded to
      &quot;<literal>ASCII,JIS,UTF-8,EUC-JP,SJIS</literal>&quot;.
     </para>
     <para>
      See also <function>mb_detect_order</function>
     </para>
     <note>
      <para>
       &quot;Supported character encoding&quot; does not mean that it
       works as internal character code.
      </para>
     </note>
    </sect2>
    
    <sect2 id="mb-ini">
     <title>php.ini settings</title>
     <para>
      <itemizedlist>
       <listitem>
        <simpara>
         <literal>mbstring.internal_encoding</literal> defines default
         internal character encoding.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         <literal>mbstring.http_input</literal> defines default HTTP
         input character encoding.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         <literal>mbstring.http_output</literal> defines default HTTP
         output character encoding.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         <literal>mbstring.detect_order</literal> defines default
         character code detection order. See also
         <function>mb_detect_order</function>. 
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         <literal>mbstring.substitute_character</literal> defines
         character to substitute for invalid character encoding.
        </simpara>
       </listitem>
      </itemizedlist>
     </para>
     <para>
      Web Browsers are supposed to use the same character encoding
      when submitting form. However, browsers may not use the same
      character encoding. See <function>mb_http_input</function> to
      detect character encoding used by browsers.
     </para>
     <para>
      If <literal>enctype</literal> is set to
      <literal>multipart/form-data</literal> in HTML forms,
      <literal>mbstring</literal> does not convert character encoding
      in POST data. The user must convert them in the script, if
      conversion is needed.
     </para>
     <para>
      Although, browsers are smart enough to detect character encoding
      in HTML. <literal>charset</literal> is better to be set in HTTP
      header. Change <literal>default_charset</literal> according to
      character encoding.
     </para>
     <para>
      <example>
       <title><literal>php.ini</literal> setting example</title>
       <programlisting role="php">
<![CDATA[
;; Set default internal encoding
;; Note: Make sure to use character encoding works with PHP
mbstring.internal_encoding    = UTF-8  ; Set internal encoding to UTF-8

;; Set default HTTP input character encoding
;; Note: Script cannot change http_input setting.
mbstring.http_input           = pass    ; No conversion. 
mbstring.http_input           = auto    ; Set HTTP input to auto
                                ; "auto" is expanded to "ASCII,JIS,UTF-8,EUC-JP,SJIS"
mbstring.http_input           = SJIS    ; Set HTTP2 input to  SJIS
mbstring.http_input           = UTF-8,SJIS,EUC-JP ; Specify order

;; Set default HTTP output character encoding 
mbstring.http_output          = pass    ; No conversion
mbstring.http_output          = UTF-8   ; Set HTTP output encoding to UTF-8

;; Set default character encoding detection order
mbstring.detect_order         = auto    ; Set detect order to auto
mbstring.detect_order         = ASCII,JIS,UTF-8,SJIS,EUC-JP ; Specify order

;; Set default substitute character
mbstring.substitute_character = 12307   ; Specify Unicode value
mbstring.substitute_character = none    ; Do not print character
mbstring.substitute_character = long    ; Long Example: U+3000,JIS+7E7E
]]>
       </programlisting>
      </example>
     </para>
     <para>
      <example>
       <title><literal>php.ini</literal> setting for <literal>EUC-JP</literal> users</title>
       <programlisting role="php">
<![CDATA[
;; Disable Output Buffering
output_buffering      = Off

;; Set HTTP header charset
default_charset       = EUC-JP    

;; Set HTTP input encoding conversion to auto
mbstring.http_input   = auto 

;; Convert HTTP output to EUC-JP
mbstring.http_output  = EUC-JP    

;; Set internal encoding to EUC-JP
mbstring.internal_encoding = EUC-JP    

;; Do not print invalid characters
mbstring.substitute_character = none   
]]>
       </programlisting>
      </example>
     </para>
     <para>
      <example>
       <title><literal>php.ini</literal> setting for <literal>SJIS</literal> users</title>
       <programlisting role="php">
<![CDATA[
;; Enable Output Buffering
output_buffering     = On

;; Set mb_output_handler to enable output conversion
output_handler       = mb_output_handler

;; Set HTTP header charset
default_charset      = Shift_JIS

;; Set http input encoding conversion to auto
mbstring.http_input  = auto 

;; Convert to SJIS
mbstring.http_output = SJIS    

;; Set internal encoding to EUC-JP
mbstring.internal_encoding = EUC-JP    

;; Do not print invalid characters
mbstring.substitute_character = none   
]]>
       </programlisting>
      </example>
     </para>
    </sect2>

    <sect2 id="mb-ja-basic">
     <title>Basics for Japanese multi-byte character</title>
     <para>
      Most Japanese characters need more than 1 byte per character. In
      addition, several character encoding schemas are used under a
      Japanese environment. There are EUC-JP, Shift_JIS(SJIS) and
      ISO-2022-JP(JIS) character encoding. As Unicode becomes popular,
      UTF-8 is used also. To develop Web applications for a Japanese
      environment, it is important to use the character set for the
      task in hand, whether HTTP input/output, RDBMS and E-mail.
     </para>
     <para>
      <itemizedlist>
       <listitem>
        <simpara>Storage for a character can be up to six
         bytes</simpara>
       </listitem>
       <listitem>
        <simpara>
         A multi-byte character is usually twice of the width compared
         to single-byte characters. Wider characters are called
         "zen-kaku" - meaning full width, narrower characters are
         called "han-kaku" - meaning half width. "zen-kaku" characters
         are usually fixed width.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         Some character encoding defines shift(escape) sequence for
         entering/exiting multi-byte character strings.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
          ISO-2022-JP must be used for SMTP/NNTP.
        </simpara>
       </listitem>
       <listitem>
        <para>
         &quot;i-mode&quot; web site is supposed to use SJIS.
        </para>
       </listitem>
      </itemizedlist>
     </para>
    </sect2>

    <sect2 id="mb-ref">
     <title>References</title>
     <para>
      Multi-byte character encoding and its related issues are very
      complex. It is impossible to cover in sufficient detail
      here. Please refer to the following URLs and other resources for
      further readings.
      <itemizedlist>
       <listitem>
        <para>
         Unicode/UTF/UCS/etc
        </para>
        <para>
          <literal>http://www.unicode.org/</literal>
        </para>
       </listitem>
       <listitem>
        <para>
         Japanese/Korean/Chinese character
         information
        </para>
        <para>
         <literal>
         ftp://ftp.ora.com/pub/examples/nutshell/ujip/doc/cjk.inf
         </literal>
        </para>
       </listitem>
      </itemizedlist>
     </para>
    </sect2>

   </sect1>
  </partintro>

  <refentry id="function.mb-language">
   <refnamediv>
    <refname>mb_language</refname>
    <refpurpose>
     Set/Get current language
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_language</methodname>
      <methodparam choice="opt"><type>string</type><parameter>language</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_language</function> sets language. If
     <parameter>language</parameter> is omitted, it returns current
     language as string.
    </para>
    <para>
     <parameter>language</parameter> setting is used for encoding
     e-mail messages. Valid languages are "Japanese",
     "ja","English","en" and "uni"
     (UTF-8). <function>mb_send_mail</function> uses this setting to
     encode e-mail.
    </para>
    <para> Language and its setting is ISO-2022-JP/Base64 for
    Japanese, UTF-8/Base64 for uni, ISO-8859-1/quoted printable for
    English.
    </para>
    <para>
     Return Value: If <parameter>language</parameter> is set and
     <parameter>language</parameter> is valid, it returns
     &true;. Otherwise, it returns &false;. When
     <parameter>language</parameter> is omitted, it returns language
     name as string. If no language is set previously, it returns
     &false;.
    </para>
    <para>
     See also <function>mb_send_mail</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-parse-str">
   <refnamediv>
    <refname>mb_parse_str</refname>
    <refpurpose>
      Parse GET/POST/COOKIE data and set global variable
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>mb_parse_str</methodname>
      <methodparam><type>string</type><parameter>encoded_string</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_parse_str</function> parses GET/POST/COOKIE data and
     sets global variables. Since PHP does not provide raw POST/COOKIE
     data, it can only used for GET data for now. It preses URL
     encoded data, detects encoding, converts coding to internal
     encoding and set values to <parameter>result</parameter> array or
     global variables.
    </para>
    <para>
     <parameter>encoded_string</parameter>: URL encoded data.
    </para>
    <para>
     <parameter>result</parameter>: Array contains decoded and
     character encoding converted values.
    </para>
    <para>
     Return Value: It returns &true; for success or &false; for failure.
    </para>
    <para>
     See also <function>mb_detect_order</function>,
     <function>mb_internal_encoding</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-internal-encoding">
   <refnamediv>
    <refname>mb_internal_encoding</refname>
    <refpurpose>
     Set/Get internal character encoding
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_internal_encoding</methodname>
      <methodparam choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_internal_encoding</function> sets internal character
     encoding to <parameter>encoding</parameter> If parameter is
     omitted, it returns current internal encoding.
    </para>
    <para>
     <parameter>encoding</parameter> is used for HTTP input character
     encoding conversion, HTTP output character encoding conversion
     and default character encoding for string functions defined by
     mbstring module.
    </para>
    <para>
     <parameter>encoding</parameter>: Character encoding name
    </para>
    <para>
     Return Value: If <parameter>encoding</parameter> is
     set,<function>mb_internal_encoding</function> returns
     &true; for success, otherwise returns
     &false;. If <parameter>encoding</parameter> is
     omitted, it returns current character encoding name.
    </para>
    <para>
     <example>
      <title><function>mb_internal_encoding</function> example</title>
      <programlisting role="php">
<![CDATA[
/* Set internal character encoding to UTF-8 */
mb_internal_encoding("UTF-8");

/* Display current internal character encoding */
echo mb_internal_encoding();
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also <function>mb_http_input</function>,
     <function>mb_http_output</function>,
     <function>mb_detect_order</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-http-input">
   <refnamediv>
    <refname>mb_http_input</refname>
    <refpurpose>Detect HTTP input character encoding</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_http_input</methodname>
      <methodparam choice="opt"><type>string</type><parameter>type</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <simpara>
     <function>mb_http_input</function> returns result of HTTP input
     character encoding detection. 
    </simpara>
    <para>
     <parameter>type</parameter>: Input string specifies input
     type. &quot;G&quot; for GET, &quot;P&quot; for POST,
     &quot;C&quot; for COOKIE. If type is omitted, it returns last
     input type processed. 
    </para>
    <para>
     Return Value: Character encoding name.
     If <function>mb_http_input</function> does not process specified
     HTTP input, it returns &false;.
    </para>
    <para>
     See also <function>mb_internal_encoding</function>,
     <function>mb_http_output</function>,
     <function>mb_detect_order</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-http-output">
   <refnamediv>
    <refname>mb_http_output</refname>
    <refpurpose>Set/Get HTTP output character encoding</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_http_output</methodname>
      <methodparam choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     If <parameter>encoding</parameter> is set,
     <function>mb_http_output</function> sets HTTP output character
     encoding to <parameter>encoding</parameter>. Output after this
     function is converted to <parameter>encoding</parameter>.
     <function>mb_http_output</function> returns
     &true; for success and &false;
     for failure.
    </para>
    <para>
     If <parameter>encoding</parameter> is omitted,
     <function>mb_http_output</function> returns current HTTP output
     character encoding.
    </para>
    <para>
     See also <function>mb_internal_encoding</function>,
     <function>mb_http_input</function>,
     <function>mb_detect_order</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-detect-order">
   <refnamediv>
    <refname>mb_detect_order</refname>
    <refpurpose>
     Set/Get character encoding detection order
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>mb_detect_order</methodname>
      <methodparam choice="opt"><type>mixed</type><parameter>encoding-list</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_detect_order</function> sets automatic character
     encoding detection order to <parameter>encoding-list</parameter>.
     It returns &true; for success,
     &false; for failure.
    </para>
    <para>
     <parameter>encoding-list</parameter> is array or comma separated
     list of character encoding. ("auto" is expanded to
     "ASCII, JIS, UTF-8, EUC-JP, SJIS")
    </para>
    <para>
     If <parameter>encoding-list</parameter> is omitted, it returns
     current character encoding detection order as array.
    </para>
    <para>
     This setting affects <function>mb_detect_encoding</function> and
     <function>mb_send_mail</function>.
    </para>
    <note>
     <para>
      <literal>mbstring</literal> currently implements following
      encoding detection filters. If there is a invalid byte sequence
      for following encoding, encoding detection will fail.
     </para>
     <simpara>
       <literal>UTF-8</literal>, <literal>UTF-7</literal>,
       <literal>ASCII</literal>,
       <literal>EUC-JP</literal>,<literal>SJIS</literal>,
       <literal>eucJP-win</literal>, <literal>SJIS-win</literal>,
       <literal>JIS</literal>, <literal>ISO-2022-JP</literal> 
     </simpara>
     <para>
      For <literal>ISO-8859-*</literal>, <literal>mbstring</literal>
      always detects as <literal>ISO-8859-*</literal>.
     </para>
     <para>
      For <literal>UTF-16</literal>, <literal>UTF-32</literal>,
      <literal>UCS2</literal> and <literal>UCS4</literal>, encoding
      detection will fail always.
     </para>
     <para>
      <example>
       <title>Useless detect order example</title>
       <programlisting>
<![CDATA[
; Always detect as ISO-8859-1
detect_order = ISO-8859-1, UTF-8

; Always detect as UTF-8, since ASCII/UTF-7 values are 
; valid for UTF-8
detect_order = UTF-8, ASCII, UTF-7
]]>
       </programlisting>
      </example>
     </para>
    </note>
    <para>
     <example>
      <title><function>mb_detect_order</function> examples</title>
      <programlisting role="php">
<![CDATA[
/* Set detection order by enumerated list */
mb_detect_order("eucjp-win,sjis-win,UTF-8");

/* Set detection order by array */
$ary[] = "ASCII";
$ary[] = "JIS";
$ary[] = "EUC-JP";
mb_detect_order($ary);

/* Display current detection order */
echo implode(", ", mb_detect_order());
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also <function>mb_internal_encoding</function>,
     <function>mb_http_input</function>,
     <function>mb_http_output</function>
     <function>mb_send_mail</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-substitute-character">
   <refnamediv>
    <refname>mb_substitute_character</refname>
    <refpurpose>Set/Get substitution character</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>mixed</type><methodname>mb_substitute_character</methodname>
      <methodparam choice="opt"><type>mixed</type><parameter>substrchar</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_substitute_character</function> specifies
     substitution character when input character encoding is invalid
     or character code is not exist in output character
     encoding. Invalid characters may be substituted &null;(no output),
     string or integer value (Unicode character code value).
    </para>
    <para>
     This setting affects <function>mb_detect_encoding</function>
     and <function>mb_send_mail</function>.
    </para>
    <para>
     <parameter>substchar</parameter> : Specify Unicode value as
     integer or specify as string as follows
     <itemizedlist>
      <listitem>
       <simpara>
        &quot;none&quot; : no output
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        &quot;long&quot; : Output character code value (Example:
        U+3000,JIS+7E7E)
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     Return Value: If <parameter>substchar</parameter> is set, it
     returns &true; for success, otherwise returns
     &false;. If <parameter>substchar</parameter> is
     not set, it returns Unicode value or
     &quot;<literal>none</literal>&quot;/&quot;<literal>long</literal>&quot;.
    </para>
    <para>
     <example>
      <title><function>mb_substitute_character</function> example</title>
      <programlisting role="php">
<![CDATA[
/* Set with Unicode U+3013 (GETA MARK) */
mb_substitute_character(0x3013);

/* Set hex format */
mb_substitute_character("long");

/* Display current setting */
echo mb_substitute_character();
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-output-handler">
   <refnamediv>
    <refname>mb_output_handler</refname>
    <refpurpose>
     Callback function converts character encoding in output buffer
    </refpurpose> 
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_output_handler</methodname>
      <methodparam><type>string</type><parameter>contents</parameter></methodparam>
      <methodparam><type>int</type><parameter>status</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_output_handler</function> is
     <function>ob_start</function> callback
     function. <function>mb_output_handler</function> converts
     characters in output buffer from internal character encoding to
     HTTP output character encoding. 
     </para>
    <para>
     4.1.0 or later version, this hanlder adds charset HTTP header
     when following conditions are met:
    </para>
    <para>
     <itemizedlist>
      <listitem>
       <simpara>Does not set <literal>Content-Type</literal> by
       header()</simpara>
      </listitem>
      <listitem>
       <simpara>Default MIME type begins with
       <literal>text/</literal></simpara>
      </listitem>
      <listitem>
       <simpara><literal>http_output</literal> setting is other than
       pass</simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     <parameter>contents</parameter> : Output buffer contents
    </para>
    <para>
     <parameter>status</parameter> : Output buffer status
    </para>
    <para>
     Return Value: String converted
    </para>
    <para>
     <example>
      <title><function>mb_output_handler</function> example</title>
      <programlisting role="php">
<![CDATA[
mb_http_output("UTF-8");
ob_start("mb_output_handler");
]]>
      </programlisting>
     </example>
    </para>
    <note>
     <para>
      If you want to output some binary data such as image from PHP
      script, you must set output encoding to &quot;pass&quot; using
      <function>mb_http_output</function>.
     </para>
    </note>
    <para>
     See also <function>ob_start</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-preferred-mime-name">
   <refnamediv>
    <refname>mb_preferred_mime_name</refname>
    <refpurpose>Get MIME charset string</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_preferred_mime_name</methodname>
      <methodparam><type>string</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_preferred_mime_name</function> returns MIME
     <literal>charset</literal> string for character encoding
     <parameter>encoding</parameter>. It returns
     <literal>charset</literal> string.
    </para>
    <para>
     <example>
      <title><function>mb_preferred_mime_string</function> example</title>
      <programlisting role="php">
<![CDATA[
$outputenc = "sjis-win";
mb_http_output($outputenc);
ob_start("mb_output_handler");
header("Content-Type: text/html; charset=" . mb_preferred_mime_name($outputenc));
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-strlen">
   <refnamediv>
    <refname>mb_strlen</refname>
    <refpurpose>Get string length</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_strlen</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_strlen</function> returns number of characters in
     string <parameter>str</parameter> having character encoding
     <parameter>encoding</parameter>. A multi-byte character is
     counted as 1.
    </para>
    <para>
     <parameter>encoding</parameter> is character encoding for
     <parameter>str</parameter>. If <parameter>encoding</parameter> is
     omitted, internal character encoding is used.
    </para>
    <para>
     See also <function>mb_internal_encoding</function>, 
     <function>strlen</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-strpos">
   <refnamediv>
    <refname>mb_strpos</refname>
    <refpurpose>
     Find position of first occurrence of string in a string
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mb_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>
      <methodparam choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_strpos</function> returns the numeric position of
     the first occurrence of <parameter>needle</parameter> in the
     <parameter>haystack</parameter> string. If
     <parameter>needle</parameter> is not found, it returns &false;.
    </para>
    <para>
     <function>mb_strpos</function> performs multi-byte safe
     <function>strpos</function> operation based on number of
     characters. <parameter>needle</parameter> position is counted
     from the beginning of the <parameter>haystack</parameter>. First
     character's position is 0. Second character position is 1, and so
     on. 
    </para>
    <para>
     If <parameter>encoding</parameter> is omitted, internal
     character encoding is used. <function>mb_strrpos</function>
     accepts <literal>string</literal> for
     <parameter>needle</parameter> where <function>strrpos</function>
     accepts only character.
    </para>
    <para>
     <parameter>offset</parameter> is search offset. If it is not
     specified, 0 is used.
    </para>
    <para>
     <parameter>encoding</parameter> is character encoding name. If it
     is omitted, internal character encoding is used.
    </para>
    <para>
     See also <function>mb_strpos</function>,
     <function>mb_internal_encoding</function>, 
     <function>strpos</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-strrpos">
   <refnamediv>
    <refname>mb_strrpos</refname>
    <refpurpose>
     Find position of last occurrence of a string in a string
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mb_strrpos</methodname>
      <methodparam><type>string</type><parameter>haystack</parameter></methodparam>
      <methodparam><type>string</type><parameter>needle</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_strrpos</function> returns the numeric position of
     the last occurrence of <parameter>needle</parameter> in the
     <parameter>haystack</parameter> string. If
     <parameter>needle</parameter> is not found, it returns &false;.
    </para>
    <para>
     <function>mb_strrpos</function> performs multi-byte safe
     <function>strrpos</function> operation based on
     number of characters. <parameter>needle</parameter> position is
     counted from the beginning of
     <parameter>haystack</parameter>. First character's position is
     0. Second character position is 1. 
    </para>
    <para>
     If <parameter>encoding</parameter> is omitted, internal encoding
     is assumed. <function>mb_strrpos</function> accepts
     <literal>string</literal> for <parameter>needle</parameter> where
     <function>strrpos</function> accepts only character.
    </para>
    <para>
     <parameter>encoding</parameter> is character encoding. If it is
     not specified, internal character encoding is used.
    </para>
    <para>
     See also <function>mb_strpos</function>,
     <function>mb_internal_encoding</function>, 
     <function>strrpos</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-substr">
   <refnamediv>
    <refname>mb_substr</refname>
    <refpurpose>Get part of string</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_substr</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
      <methodparam><type>int</type><parameter>start</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_substr</function> returns the portion of
     <parameter>str</parameter> specified by the
     <parameter>start</parameter> and
     <parameter>length</parameter> parameters.
    </para>
    <para>
     <function>mb_substr</function> performs multi-byte safe
     <function>substr</function> operation based on
     number of characters. Position is
     counted from the beginning of
     <parameter>str</parameter>. First character's position is
     0. Second character position is 1, and so on. 
    </para>
    <para>
     If <parameter>encoding</parameter> is omitted, internal encoding
     is assumed.
    </para>
    <para>
     <parameter>encoding</parameter> is character encoding. If it is
     omitted, internal character encoding is used.
    </para>
    <para>
     See also <function>mb_strcut</function>, 
     <function>mb_internal_encoding</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-strcut">
   <refnamediv>
    <refname>mb_strcut</refname>
    <refpurpose>Get part of string</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_strcut</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
      <methodparam><type>int</type><parameter>start</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_strcut</function> returns the portion of
     <parameter>str</parameter> specified by the
     <parameter>start</parameter> and
     <parameter>length</parameter> parameters.
    </para>
    <para>
     <function>mb_strcut</function> performs equivalent operation as
     <function>mb_substr</function> with different method. If
     <parameter>start</parameter> position is multi-byte character's
     second byte or larger, it starts from first byte of multi-byte
     character. 
    </para>
    <para>
     It subtracts string from <parameter>str</parameter> that is
     shorter than <parameter>length</parameter> AND character that is
     not part of multi-byte string or not being middle of shift
     sequence. 
    </para>
    <para>
     <parameter>encoding</parameter> is character encoding. If it is
     not set, internal character encoding is used.
    </para>
    <para>
     See also <function>mb_substr</function>,
     <function>mb_internal_encoding</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-strwidth">
   <refnamediv>
    <refname>mb_strwidth</refname>
    <refpurpose>Return width of string</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>mb_strwidth</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_strwidth</function> returns width of string
     <parameter>str</parameter>.
    </para>
    <para>
     Multi-byte character usually twice of width compare to single
     byte character.
    </para>
    <para>
     <informalexample>
      <programlisting>
<![CDATA[
       Character width

       U+0000 - U+0019   0
       U+0020 - U+1FFF   1
       U+2000 - U+FF60   2
       U+FF61 - U+FF9F   1
       U+FFA0 -          2
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     <parameter>encoding</parameter> is character encoding. If it is
     omitted, internal encoding is used.
    </para>
    <para>
     See also: <function>mb_strimwidth</function>,
     <function>mb_internal_encoding</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-strimwidth">
   <refnamediv>
    <refname>mb_strimwidth</refname>
    <refpurpose>Get truncated string with specified width</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_strimwidth</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
      <methodparam><type>int</type><parameter>start</parameter></methodparam>
      <methodparam><type>int</type><parameter>width</parameter></methodparam>
      <methodparam><type>string</type><parameter>trimmarker</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_strimwidth</function> truncates string
     <parameter>str</parameter> to specified
     <parameter>width</parameter>. It returns truncated string.
    </para>
    <para>
     If <parameter>trimmarker</parameter> is set,
     <parameter>trimmarker</parameter> is appended to return value.
    </para>
    <para>
     <parameter>start</parameter> is start position offset. Number of
     characters from the beginning of string. (First character is 0)
    </para>
    <para>
     <parameter>trimmarker</parameter> is string that is added to the
     end of string when string is truncated.
    </para>
    <para>
     <parameter>encoding</parameter> is character encoding. If it is
     omitted, internal encoding is used.
    </para>
    <para>
     <example>
      <title><function>mb_strimwidth</function> example</title>
      <programlisting role="php">
<![CDATA[
$str = mb_strimwidth($str, 0, 40, "..>");
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also: <function>mb_strwidth</function>,
     <function>mb_internal_encoding</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-convert-encoding">
   <refnamediv>
    <refname>mb_convert_encoding</refname>
    <refpurpose>Convert character encoding</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_convert_encoding</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
      <methodparam><type>string</type><parameter>to-encoding</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>from-encoding</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_convert_encoding</function> converts 
     character encoding of string <parameter>str</parameter> from
     <parameter>from-encoding</parameter> to
     <parameter>to-encoding</parameter>.
    </para>
    <para>
     <parameter>str</parameter> : String to be converted.
    </para>
    <para>
     <parameter>from-encoding</parameter> is specified by character
     code name before conversion. it can be array or string - comma
     separated  enumerated list.
    </para>
    <para>
     <example>
      <title><function>mb_convert_encoding</function> example</title>
      <programlisting role="php">
<![CDATA[
/* Convert internal character encoding to SJIS */
$str = mb_convert_encoding($str, "SJIS");

/* Convert EUC-JP to UTF-7 */
$str = mb_convert_encoding($str, "UTF-7", "EUC-JP");

/* Auto detect encoding from JIS, eucjp-win, sjis-win, then convert str to UCS-2LE */
$str = mb_convert_encoding($str, "UCS-2LE", "JIS, eucjp-win, sjis-win");

/* "auto" is expanded to "ASCII,JIS,UTF-8,EUC-JP,SJIS" */
$str = mb_convert_encoding($str, "EUC-JP", "auto");
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also: <function>mb_detect_order</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-detect-encoding">
   <refnamediv>
    <refname>mb_detect_encoding</refname>
    <refpurpose>Detect character encoding</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_detect_encoding</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>encoding-list</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_detect_encoding</function> detects character
     encoding in string <parameter>str</parameter>. It returns
     detected character encoding.
    </para>
    <para>
     <parameter>encoding-list</parameter> is list of character
     encoding. Encoding order may be specified by array or comma
     separated list string.
    </para>
    <para>
     If <parameter>encoding_list</parameter> is omitted,
     detect_order is used.
    </para>
    <para>
     <example>
      <title><function>mb_detect_encoding</function> example</title>
      <programlisting role="php">
<![CDATA[
/* Detect character encoding with current detect_order */
echo mb_detect_encoding($str);

/* "auto" is expanded to "ASCII,JIS,UTF-8,EUC-JP,SJIS" */
echo mb_detect_encoding($str, "auto");

/* Specify encoding_list character encoding by comma separated list */
echo mb_detect_encoding($str, "JIS, eucjp-win, sjis-win");

/* Use array to specify encoding_list  */
$ary[] = "ASCII";
$ary[] = "JIS";
$ary[] = "EUC-JP";
echo mb_detect_encoding($str, $ary);
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also: <function>mb_detect_order</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-convert-kana">
   <refnamediv>
    <refname>mb_convert_kana</refname>
    <refpurpose>
     Convert "kana" one from another ("zen-kaku" ,"han-kaku" and more)
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_convert_kana</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
      <methodparam><type>string</type><parameter>option</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_convert_kana</function> performs "han-kaku" -
     "zen-kaku" conversion for string <parameter>str</parameter>. It
     returns converted string. This function is only useful for
     Japanese.
    </para>
    <para>
     <parameter>option</parameter> is conversion option. Default value
     is <literal>"KV"</literal>.
    </para>
    <para>
     <parameter>encoding</parameter> is character encoding. If it is
     omitted, internal character encoding is used.
    </para>
    <para>
     <informalexample>
      <programlisting>
<![CDATA[
       Applicable Conversion Options 

       option : Specify with conversion of following options. Default "KV"
       "r" :  Convert "zen-kaku" alphabets to "han-kaku"
       "R" :  Convert "han-kaku" alphabets to "zen-kaku"
       "n" :  Convert "zen-kaku" numbers to "han-kaku"
       "N" :  Convert "han-kaku" numbers to "zen-kaku"
       "a" :  Convert "zen-kaku" alphabets and numbers to "han-kaku"
       "A" :  Convert "zen-kaku" alphabets and numbers to "han-kaku"
       (Characters included in "a", "A" options are
       U+0021 - U+007E excluding U+0022, U+0027, U+005C, U+007E)
       "s" :  Convert "zen-kaku" space to "han-kaku" (U+3000 -> U+0020)
       "S" :  Convert "han-kaku" space to "zen-kaku" (U+0020 -> U+3000)
       "k" :  Convert "zen-kaku kata-kana" to "han-kaku kata-kana"
       "K" :  Convert "han-kaku kata-kana" to "zen-kaku kata-kana"
       "h" :  Convert "zen-kaku hira-gana" to "han-kaku kata-kana"
       "H" :  Convert "han-kaku kata-kana" to "zen-kaku hira-gana"
       "c" :  Convert "zen-kaku kata-kana" to "zen-kaku hira-gana"
       "C" :  Convert "zen-kaku hira-gana" to "zen-kaku kata-kana"
       "V" :  Collapse voiced sound notation and convert them into a character. Use with "K","H"
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     <example>
      <title><function>mb_convert_kana</function> example</title>
      <programlisting role="php">
<![CDATA[
/* Convert all "kana" to "zen-kaku" "kata-kana" */
$str = mb_convert_kana($str, "KVC");

/* Convert "han-kaku" "kata-kana" to "zen-kaku" "kata-kana" 
   and "zen-kaku" alpha-numeric to "han-kaku" */
$str = mb_convert_kana($str, "KVa");
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-encode-mimeheader">
   <refnamediv>
    <refname>mb_encode_mimeheader</refname>
    <refpurpose>Encode string for MIME header</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_encode_mimeheader</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>transfer-encoding</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>linefeed</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_encode_mimeheader</function> converts string
     <parameter>str</parameter> to encoded-word for header field.
     It returns converted string in ASCII encoding.
    </para>
    <para>
     <parameter>charset</parameter> is character encoding
     name. Default is <literal>ISO-2022-JP</literal>.
    </para>
    <para>
     <parameter>transfer-encoding</parameter> is transfer encoding. It
     should be one of <literal>"B"</literal> (Base64) or
     <literal>"Q"</literal> (Quoted-Printable). Default is
     <literal>"B"</literal>.
    </para>
    <para>
     <parameter>linefeed</parameter> is end of line marker. Default is
     <literal>"\r\n"</literal> (CRLF).
    </para>
    <para>
     <example>
      <title><function>mb_convert_kana</function> example</title>
      <programlisting role="php">
<![CDATA[
$name = ""; // kanji
$mbox = "kru";
$doma = "gtinn.mon";
$addr = mb_encode_mimeheader($name, "UTF-7", "Q") . " <" . $mbox . "@" . $doma . ">";
echo $addr;
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also <function>mb_decode_mimeheader</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-decode-mimeheader">
   <refnamediv>
    <refname>mb_decode_mimeheader</refname>
    <refpurpose>Decode string in MIME header field</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_decode_mimeheader</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_decode_mimeheader</function> decodes encoded-word
     string <parameter>str</parameter> in MIME header. 
    </para>
    <para>
     It returns decoded string in internal character encoding.
    </para>
    <para>
     See also <function>mb_encode_mimeheader</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-convert-variables">
   <refnamediv>
    <refname>mb_convert_variables</refname>
    <refpurpose>Convert character code in variable(s)</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_convert_variables</methodname>
      <methodparam><type>string</type><parameter>to-encoding</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>from-encoding</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>vars</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_convert_variables</function> convert 
     character encoding of variables <parameter>vars</parameter> in
     encoding <parameter>from-encoding</parameter> to encoding 
     <parameter>to-encoding</parameter>. It returns character encoding
     before conversion for success, &false; for failure.
    </para>
    <para>
     <function>mb_convert_variables</function> join strings in Array
     or Object to detect encoding, since encoding detection tends to
     fail for short strings. Therefore, it is impossible to mix
     encoding in single array or object.
    </para>
    <para>
     It <parameter>from-encoding</parameter> is specified by 
     array or comma separated string, it tries to detect encoding from
     <parameter>from-coding</parameter>. When
     <parameter>encoding</parameter> is omitted,
     <literal>detect_order</literal> is used.
    </para>
    <para>
     <parameter>vars (3rd and larger)</parameter> is reference to
     variable to be converted. String, Array and Object are accepted.
     <function>mb_convert_variables</function> assumes all parameters
     have the same encoding.
    </para>
    <para>
     <example>
      <title><function>mb_convert_variables</function> example</title>
      <programlisting role="php">
<![CDATA[
/* Convert variables $post1, $post2 to internal encoding */
$interenc = mb_internal_encoding();
$inputenc = mb_convert_variables($interenc, "ASCII,UTF-8,SJIS-win", $post1, $post2);
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-encode-numericentity">
   <refnamediv>
    <refname>mb_encode_numericentity</refname>
    <refpurpose>
     Encode character to HTML numeric string reference
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_encode_numericentity</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
      <methodparam><type>array</type><parameter>convmap</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_encode_numericentity</function> converts
     specified character codes in string <parameter>str</parameter>
     from HTML numeric character reference to character code. It
     returns converted string.
    </para>
    <para>
     <parameter>array</parameter> is array specifies code area to
     convert.
    </para>
    <para>
     <parameter>encoding</parameter> is character encoding.
    </para>
    <para>
     <example>
      <title><parameter>convmap</parameter> example</title>
      <programlisting role="php">
<![CDATA[
$convmap = array (
 int start_code1, int end_code1, int offset1, int mask1,
 int start_code2, int end_code2, int offset2, int mask2,
 ........
 int start_codeN, int end_codeN, int offsetN, int maskN );
// Specify Unicode value for start_codeN and end_codeN
// Add offsetN to value and take bit-wise 'AND' with maskN, then
// it converts value to numeric string reference.
]]>
      </programlisting>
     </example>
    </para>
    <para>
     <example>
      <title>
       <function>mb_encode_numericentity</function> example
      </title>
      <programlisting role="php">
<![CDATA[
/* Convert Left side of ISO-8859-1 to HTML numeric character reference */
$convmap = array(0x80, 0xff, 0, 0xff);
$str = mb_encode_numericentity($str, $convmap, "ISO-8859-1");

/* Convert user defined SJIS-win code in block 95-104 to numeric
   string reference */
$convmap = array(
       0xe000, 0xe03e, 0x1040, 0xffff,
       0xe03f, 0xe0bb, 0x1041, 0xffff,
       0xe0bc, 0xe0fa, 0x1084, 0xffff,
       0xe0fb, 0xe177, 0x1085, 0xffff,
       0xe178, 0xe1b6, 0x10c8, 0xffff,
       0xe1b7, 0xe233, 0x10c9, 0xffff,
       0xe234, 0xe272, 0x110c, 0xffff,
       0xe273, 0xe2ef, 0x110d, 0xffff,
       0xe2f0, 0xe32e, 0x1150, 0xffff,
       0xe32f, 0xe3ab, 0x1151, 0xffff );
$str = mb_encode_numericentity($str, $convmap, "sjis-win");
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also: <function>mb_decode_numericentity</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-decode-numericentity">
   <refnamediv>
    <refname>mb_decode_numericentity</refname>
    <refpurpose>
     Decode HTML numeric string reference to character
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>mb_decode_numericentity</methodname>
      <methodparam><type>string</type><parameter>str</parameter></methodparam>
      <methodparam><type>array</type><parameter>convmap</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     Convert numeric string reference of string
     <parameter>str</parameter> in specified block to character. It
     returns converted string.
    </para>
    <para>
     <parameter>array</parameter> is array to specifies code area to
     convert.
    </para>
    <para>
     <parameter>encoding</parameter> is character encoding. If it is
     omitted, internal character encoding is used.
    </para>
    <para>
     <example>
      <title><parameter>convmap</parameter> example</title>
      <programlisting>
<![CDATA[
$convmap = array (
   int start_code1, int end_code1, int offset1, int mask1,
   int start_code2, int end_code2, int offset2, int mask2,
   ........
   int start_codeN, int end_codeN, int offsetN, int maskN );
// Specify Unicode value for start_codeN and end_codeN
// Add offsetN to value and take bit-wise 'AND' with maskN, 
// then convert value to numeric string reference.
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also: <function>mb_encode_numericentity</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.mb-send-mail">
   <refnamediv>
    <refname>mb_send_mail</refname>
    <refpurpose>
     Send encoded mail.
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>mb_send_mail</methodname>
      <methodparam><type>string</type><parameter>to</parameter></methodparam>
      <methodparam><type>string</type><parameter>subject</parameter></methodparam>
      <methodparam><type>string</type><parameter>message</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>additional_headers</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>additional_parameter</parameter></methodparam>
     </methodsynopsis>
    &warn.experimental.func;
    <para>
     <function>mb_send_mail</function> sends email. Headers and
     message are converted and encoded according to
     <function>mb_language</function> setting. 
     <function>mb_send_mail</function> is wrapper
     function of <function>mail</function>. See
     <function>mail</function> for details.
    </para>
    <para>
     <parameter>to</parameter> is mail addresses send to. Multiple
     recipients can be specified by putting a comma between each
     address in to. This parameter is not automatically encoded.
    </para>
    <para>
     <parameter>subject</parameter> is subject of mail.
    </para>
    <para>
     <parameter>message</parameter> is mail message.
    </para>
    <para>
     <parameter>additional_headers</parameter> is inserted at
     the end of the header. This is typically used to add extra
     headers.  Multiple extra headers are separated with a
     newline ("\n").
    </para>
    <para>
     <parameter>additional_parameter</parameter> is a MTA command line
     parameter. It is useful when setting the correct Return-Path
     header when using sendmail.
    </para>
    <para>
     &return.success;
    </para>
    <para>
     See also <function>mail</function>,
     <function>mb_encode_mimeheader</function>, and
     <function>mb_language</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
-->