Ref/iconv-Phpdoc专题

参见 GNU Recode functions。

iconv_get_encoding

获取 iconv 扩展的内部配置变量

说明

mixed <span class="methodname">iconv_get_encoding ([ <span class="methodparam">string $type<span class="initializer"> = "all" ] )

获取 iconv 扩展的内部配置变量。

参数

type
选项 type 的值可以是：

• all
• input_encoding
• output_encoding
• internal_encoding

返回值

成功时返回当前内部配置变量的值， 或者在失败时返回 false。

如果省略了 type，或者设置为 "all"，<span class="function">iconv_get_encoding 返回包含所有这些变量的数组。

范例

示例 #1 iconv_get_encoding 例子

<pre>
<?php
iconv_set_encoding("internal_encoding", "UTF-8");
iconv_set_encoding("output_encoding", "ISO-8859-1");
var_dump(iconv_get_encoding('all'));
?>
</pre>

以上例程会输出：

Array
(
    [input_encoding] => ISO-8859-1
    [output_encoding] => ISO-8859-1
    [internal_encoding] => UTF-8
)

参见

• iconv_set_encoding
• ob_iconv_handler

iconv_mime_decode_headers

一次性解码多个 MIME 头字段

说明

array <span class="methodname">iconv_mime_decode_headers ( <span class="methodparam">string $encoded_headers [, <span class="type">int $mode = 0 [, <span class="type">string $charset = ini_get("iconv.internal_encoding") ]] )

一次性解码多个 MIME 头字段。

参数

encoded_headers
编码过的头，是一个字符串。

mode
mode 决定了 iconv_mime_decode_headers 遇到畸形 MIME 头字段时的行为。 你可以指定为以下位掩码的任意组合。

charset
可选参数 charset 指定了字符集结果的表现。 如果省略了，将使用 iconv.internal_encoding。

返回值

成功时返回 encoded_headers 指定的 MIME 头的整套关联数组，解码时出现错误则返回 false。

返回元素的每个键代表独立字段名，相应的元素代表一个字段值。 如果有多个同一名称的字段， <span class="function">iconv_mime_decode_headers 自动将他们按出现顺序结合成数字索引的数组。

范例

示例 #1 iconv_mime_decode_headers 例子

<?php
$headers_string = <<<EOF
Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=
To: [email protected]
Date: Thu, 1 Jan 1970 00:00:00 +0000
Message-Id: <[email protected]>
Received: from localhost (localhost [127.0.0.1]) by localhost
    with SMTP id example for <[email protected]>;
    Thu, 1 Jan 1970 00:00:00 +0000 (UTC)
    (envelope-from [email protected])
Received: (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000

EOF;

$headers =  iconv_mime_decode_headers($headers_string, 0, "ISO-8859-1");
print_r($headers);
?>

以上例程会输出：

Array
(
    [Subject] => Prüfung Prüfung
    [To] => [email protected]
    [Date] => Thu, 1 Jan 1970 00:00:00 +0000
    [Message-Id] => <[email protected]>
    [Received] => Array
        (
            [0] => from localhost (localhost [127.0.0.1]) by localhost with SMTP id example for <[email protected]>; Thu, 1 Jan 1970 00:00:00 +0000 (UTC) (envelope-from [email protected])
            [1] => (qmail 0 invoked by uid 65534); 1 Thu 2003 00:00:00 +0000
        )

)

参见

• iconv_mime_decode
• mb_decode_mimeheader
• imap_mime_header_decode
• imap_base64
• imap_qprint

iconv_mime_decode

解码一个MIME头字段

说明

string <span class="methodname">iconv_mime_decode ( <span class="methodparam">string $encoded_header [, <span class="type">int $mode = 0 [, <span class="type">string $charset = ini_get("iconv.internal_encoding") ]] )

解码一个MIME头字段.

参数

encoded_header
编码头,是一个字符串.

mode
模式决定了当<span class="function">iconv_mime_decode遇到一个不规则的 MIME头字段时,对这个事件作出的行为.你可以指定以下位掩码的任意组合.

charset
可选的字符集参数,用指定的字符集表示结果.如果省略, iconv.internal_encoding 将会被默认使用.

返回值

如果解码成功,返回一个被解码的MIME字段, 如果在解码过程中出现一个错误,将返回false .

范例

示例 #1 iconv_mime_decode实例

<?php
//返回结果: "Subject: Prüfung Prüfung"
echo iconv_mime_decode("Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=",
                       0, "ISO-8859-1");
?>

参见

• iconv_mime_decode_headers
• mb_decode_mimeheader
• imap_mime_header_decode
• imap_base64
• imap_qprint

iconv_mime_encode

Composes a MIME header field

说明

string<span class="type">false <span class="methodname">iconv_mime_encode ( <span class="methodparam">string $field_name , <span class="type">string $field_value [, <span class="methodparam">array $options<span class="initializer"> = [] ] )

Composes and returns a string that represents a valid MIME header field, which looks like the following:

Subject: =?ISO-8859-1?Q?Pr=FCfung_f=FCr?= Entwerfen von einer MIME kopfzeile

In the above example, "Subject" is the field name and the portion that begins with "=?ISO-8859-1?..." is the field value.

参数

field_name
The field name.

field_value
The field value.

options
You can control the behaviour of <span class="function">iconv_mime_encode by specifying an associative array that contains configuration items to the optional third parameter options. The items supported by <span class="function">iconv_mime_encode are listed below. Note that item names are treated case-sensitive.

返回值

Returns an encoded MIME field on success, or false if an error occurs during the encoding.

范例

示例 #1 iconv_mime_encode example

<?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=20Pr=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);
?>

参见

• imap_binary
• mb_encode_mimeheader
• imap_8bit
• quoted_printable_encode

iconv_set_encoding

为字符编码转换设定当前设置

说明

bool <span class="methodname">iconv_set_encoding ( <span class="methodparam">string $type , string $charset )

将 type 设置的值从内部配置变量更改为 charset。

参数

type
type 的值可以是以下其中任意一个：

• input_encoding
• output_encoding
• internal_encoding

charset
字符集。

返回值

成功时返回 true， 或者在失败时返回 false。

范例

示例 #1 iconv_set_encoding 例子

<?php
iconv_set_encoding("internal_encoding", "UTF-8");
iconv_set_encoding("output_encoding", "ISO-8859-1");
?>

参见

• iconv_get_encoding
• ob_iconv_handler

iconv_strlen

返回字符串的字符数统计

说明

int <span class="methodname">iconv_strlen ( <span class="methodparam">string $str [, string $charset = ini_get("iconv.internal_encoding") ] )

和 strlen 不同的是，<span class="function">iconv_strlen 统计了给定的字节序列 str 中出现字符数的统计，基于指定的字符集，其产生的结果不一定和字符字节数相等。

参数

str
该字符串。

charset
如果省略了 charset 参数，假设 str 的编码为 iconv.internal_encoding。

返回值

返回 str 字符数的统计，是整型。

参见

• grapheme_strlen
• mb_strlen
• strlen

iconv_strpos

Finds position of first occurrence of a needle within a haystack

说明

int<span class="type">false <span class="methodname">iconv_strpos ( <span class="methodparam">string $haystack , string $needle [, <span class="type">int $offset = 0 [, <span class="type">stringnull $encoding = null ]] )

Finds position of first occurrence of a needle within a haystack.

In contrast to strpos, the return value of iconv_strpos 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 encoding.

参数

haystack
The entire string.

needle
The searched substring.

offset
The optional offset parameter specifies the position from which the search should be performed. If the offset is negative, it is counted from the end of the string.

encoding
If encoding parameter is omitted or null, string are assumed to be encoded in iconv.internal_encoding.

If haystack or needle is not a string, it is converted to a string and applied as the ordinal value of a character.

返回值

Returns the numeric position of the first occurrence of needle in haystack.

If needle is not found, iconv_strpos will return false.

Warning

此函数可能返回布尔值 false，但也可能返回等同于 false 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

更新日志

参见

• strpos
• iconv_strrpos
• mb_strpos

iconv_strrpos

Finds the last occurrence of a needle within a haystack

说明

int<span class="type">false <span class="methodname">iconv_strrpos ( <span class="methodparam">string $haystack , string $needle [, <span class="type">stringnull $encoding = null ] )

Finds the last occurrence of a needle within a haystack.

In contrast to strrpos, the return value of iconv_strrpos 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 encoding.

参数

haystack
The entire string.

needle
The searched substring.

encoding
If encoding parameter is omitted or null, string are assumed to be encoded in iconv.internal_encoding.

If haystack or needle is not a string, it is converted to a string and applied as the ordinal value of a character.

返回值

Returns the numeric position of the last occurrence of needle in haystack.

If needle is not found, iconv_strrpos will return false.

Warning

此函数可能返回布尔值 false，但也可能返回等同于 false 的非布尔值。请阅读 布尔类型章节以获取更多信息。应使用 === 运算符来测试此函数的返回值。

更新日志

参见

• strrpos
• iconv_strpos
• mb_strrpos

iconv_substr

截取字符串的部分

说明

string <span class="methodname">iconv_substr ( <span class="methodparam">string $str , int $offset [, int $length = iconv_strlen($str, $charset) [, <span class="type">string $charset = ini_get("iconv.internal_encoding") ]] )

根据 offset 和 length 参数指定 str 截取的部分。

参数

str
原始字符串。

offset
如果 offset 是非负数，iconv_substr 从 str 开头第 offset 个字符开始截出部分，从 0 开始计数。

如果 offset 是负数，iconv_substr 从 str 末尾向前 offset 个字符开始截取。

length
如果指定了 length 并且是正数，返回的值从 offset 截取部分，最多包含 length 个字符（取决于 string 的长度）。

如果传入了负数的 length， iconv_substr 将从第 offset 个字符到离末尾 length 个字符截出 str 的部分。 如果 offset 也是负数，则开始位置计算规则的解释见以上。

charset
如果省略了参数 charset，string 的编码被认定为 iconv.internal_encoding。

注意，offset 和 length 参数总是被认为字符表现的偏移，基于 charset 检测到的字符集进行统计计算，而相对应的 <span class="function">substr 则是基于字节的位移来计算。

返回值

返回 offset 和 length 参数指定的 str 的部分。

如果 str 比 offset 字符数更短，将会返回 false。 如果 str 是 offset 个字符的长度，将返回空字符串。

更新日志

参见

• substr
• mb_substr
• mb_strcut

iconv

字符串按要求的字符编码来转换

说明

string iconv ( string $in_charset , <span class="type">string $out_charset , <span class="methodparam">string $str )

将字符串 str 从 in_charset 转换编码到 out_charset。

参数

in_charset
输入的字符集。

out_charset
输出的字符集。

如果你在 out_charset 后添加了字符串 //TRANSLIT，将启用转写（transliteration）功能。这个意思是，当一个字符不能被目标字符集所表示时，它可以通过一个或多个形似的字符来近似表达。 如果你添加了字符串 //IGNORE，不能以目标字符集表达的字符将被默默丢弃。 否则，会导致一个 E_NOTICE并返回 false。

Caution //TRANSLIT 运行细节高度依赖于系统的 iconv() 实现（参见 ICONV_IMPL）。 据悉，某些系统上的实现会直接忽略 //TRANSLIT，所以转换也有可能失败，out_charset 会是不合格的。

str
要转换的字符串。

返回值

返回转换后的字符串， 或者在失败时返回 false。

更新日志

范例

示例 #1 iconv 例子

<?php
$text = "This is the Euro symbol '€'.";

echo 'Original : ', $text, PHP_EOL;
echo 'TRANSLIT : ', iconv("UTF-8", "ISO-8859-1//TRANSLIT", $text), PHP_EOL;
echo 'IGNORE   : ', iconv("UTF-8", "ISO-8859-1//IGNORE", $text), PHP_EOL;
echo 'Plain    : ', iconv("UTF-8", "ISO-8859-1", $text), PHP_EOL;

?>

以上例程的输出类似于：

Original : This is the Euro symbol '€'.
TRANSLIT : This is the Euro symbol 'EUR'.
IGNORE   : This is the Euro symbol ''.
Plain    :
Notice: iconv(): Detected an illegal character in input string in .\iconv-example.php on line 7

ob_iconv_handler

以输出缓冲处理程序转换字符编码

说明

string <span class="methodname">ob_iconv_handler ( <span class="methodparam">string $contents , int $status )

将字符编码从 internal_encoding 转换到 output_encoding。

internal_encoding 和 output_encoding 应当在 php.ini 文件或 <span class="function">iconv_set_encoding 中定义。

参数

关于处理程序参数的信息，参见 ob_start。

返回值

关于处理程序返回值的信息，参见 ob_start。

范例

示例 #1 ob_iconv_handler 例子：

<?php
iconv_set_encoding("internal_encoding", "UTF-8");
iconv_set_encoding("output_encoding", "ISO-8859-1");
ob_start("ob_iconv_handler"); // 开始输出缓冲
?>

参见

• iconv_get_encoding
• iconv_set_encoding
• 输出控制函数

目录

• iconv_get_encoding — 获取 iconv 扩展的内部配置变量
• iconv_mime_decode_headers — 一次性解码多个 MIME 头字段
• iconv_mime_decode — 解码一个MIME头字段
• iconv_mime_encode — Composes a MIME header field
• iconv_set_encoding — 为字符编码转换设定当前设置
• iconv_strlen — 返回字符串的字符数统计
• iconv_strpos — Finds position of first occurrence of a needle within a haystack
• iconv_strrpos — Finds the last occurrence of a needle within a haystack
• iconv_substr — 截取字符串的部分
• iconv — 字符串按要求的字符编码来转换
• ob_iconv_handler — 以输出缓冲处理程序转换字符编码