<?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>

Код «Z» добавили для NULL-дополненных строк и удаления конечных 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>