<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="function.unpack" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>unpack</refname>

<refpurpose>バイナリ文字列からデータを切り出す</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>array</type><type>false</type></type><methodname>unpack</methodname>

<methodparam><type>string</type><parameter>format</parameter></methodparam>

<methodparam><type>string</type><parameter>string</parameter></methodparam>

<methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>

</methodsynopsis>

<para>

<parameter>format</parameter> に基づき、バイナリ文字列から配列に分解します。

</para>

<para>

分解した結果は連想配列に格納されます。

このようにするために、それぞれの書式コードに名前をつけ、それらを

スラッシュ / で区切る必要があります。

反復指定用引数が含まれる場合の配列のキー名は、

指定した名前の後に連番がついたものとなります。

</para>

<para>

Perl の関数に動きを近づけるために、以下の変更が行われています:

<simplelist>

<member>

"a" は末尾の NULL バイトを維持します。

</member>

<member>

"A" は末尾の ASCII 空白文字 (スペース、タブ、改行、キャリッジリターン、

NULL バイト) をすべて取り除きます。

</member>

<member>

NULL 埋め文字列用に "Z" が追加されました。

これは末尾の NULL バイトを取り除きます。

</member>

</simplelist>

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>format</parameter></term>

<listitem>

<para>

書式コードの説明は <function>pack</function> を参照ください。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>string</parameter></term>

<listitem>

<para>

パックされたデータ。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>offset</parameter></term>

<listitem>

<para>

データ切り出しを開始するオフセット。

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

バイナリ文字列を切り出した要素を含む連想配列を返します。&return.falseforfailure;

</para>

</refsect1>

<refsect1 role="changelog"><!-- {{{ -->

&reftitle.changelog;

<para>

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>7.2.0</entry>

<entry>

<type>float</type> および <type>double</type> 型は、

ビッグエンディアンとリトルエンディアンの両方をサポートします。

</entry>

</row>

<row>

<entry>7.1.0</entry>

<entry>

オプションの <parameter>offset</parameter> が追加されました。

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1><!-- }}} -->

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title><function>unpack</function> の例</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

</para>

<para>

<example>

<title><function>unpack</function> でのリピータの例</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<caution>

<para>

PHP は内部的に整数を符号付きで保持することに注意しましょう。

大きな値の unsigned long を切り出した場合、PHP の内部で保持された値は、

同じ大きさの符号付き整数となり、符号無しを指定して切出された場合でも

結果は負の数となります。

</para>

</caution>

<caution>

<para>

要素に名前をつけなければ、<literal>1</literal> から始まる数値インデックスを用います。

名前をつけない要素が複数ある場合は、データが上書きされてしまうかもしれないことに注意しましょう。

それぞれの要素について、数値インデックスが <literal>1</literal> から割りあてられるからです。

</para>

<para>

<example>

<title><function>unpack</function> で名前のないキーを扱う例</title>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

<para>

<literal>c</literal> で指定した最初の値が

<literal>n</literal> で指定した値で上書きされることに注意しましょう。

</para>

</example>

</para>

</caution>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>pack</function></member>

</simplelist>

</para>

</refsect1>

</refentry>