archived-doc-ru/reference/misc/functions/pack.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: ad0f1eaa6510e1d11231f46515ca513d2cd097c4 Maintainer: bfl Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.pack" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>pack</refname>
  <refpurpose>Упаковывает данные в двоичную строку</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>pack</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam rep="repeat"><type>mixed</type><parameter>values</parameter></methodparam>
  </methodsynopsis>
  <para>
   Функция упаковывает заданные аргументы в двоичную строку
   в соответствии с форматом в параметре
   <parameter>format</parameter>.
  </para>
  <para>
   Идею функции заимствовали из языка программирования Perl, поэтому работа кодов форматирования
   аналогична языку Perl. Однако функция не поддерживает часть кодов форматирования
   наподобие Perl-кода "u".
  </para>
  <para>
   Обратите внимание, что различия между знаковыми и беззнаковыми
   значениями влияют только на функцию <function>unpack</function>, тогда как
   функция <function>pack</function> даёт одинаковый результат для знаковых и
   беззнаковых кодов формата.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>format</parameter></term>
     <listitem>
      <para>
       Строка <parameter>format</parameter> состоит из кодов формата,
       за которыми идёт необязательный аргумент повторителя. Значение аргумента
       повторителя указывают как целое число или как символ <literal>*</literal> для повторения
       до конца входных данных. Для кодов a, A, h, H число повторений указывает, сколько символов
       одного аргумента данных возьмёт функция, для кода @ — абсолютную позицию, в которую
       функция поместит следующие данные. Для остальных кодов форматирования число повторений указывает,
       сколько аргументов данных функция обработает и упакует в результирующую двоичную строку.
      </para>
      <para>
       Доступные форматы:
       <table>
        <title>Символы формата функции <function>pack</function></title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Код</entry>
           <entry>Описание</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry>a</entry>
           <entry>Строка (string) с NUL-дополнением</entry>
          </row>
          <row>
           <entry>A</entry>
           <entry>Строка (string) со SPACE-дополнением</entry></row>
          <row>
           <entry>h</entry>
           <entry>Шестнадцатеричная строка (string), вначале младший полубайт</entry></row>
          <row>
           <entry>H</entry>
           <entry>Шестнадцатеричная строка (string), вначале старший полубайт</entry></row>
          <row>
           <entry>c</entry>
           <entry>Знаковый char</entry>
          </row>
          <row>
           <entry>C</entry>
           <entry>Беззнаковый char</entry>
          </row>
          <row>
           <entry>s</entry>
           <entry>Знаковый short (всегда 16 битов, машинный порядок байтов)</entry>
          </row>
          <row>
           <entry>S</entry>
           <entry>Беззнаковый short (всегда 16 битов, машинный порядок байтов)</entry>
          </row>
          <row>
           <entry>n</entry>
           <entry>Беззнаковый short (всегда 16 битов, порядок байтов от старшего к младшему)</entry>
          </row>
          <row>
           <entry>v</entry>
           <entry>Беззнаковый short (всегда 16 битов, порядок байтов от младшего к старшему)</entry>
          </row>
          <row>
           <entry>i</entry>
           <entry>Знаковый integer (машинно-зависимые размер и порядок байтов)</entry>
          </row>
          <row>
           <entry>I</entry>
           <entry>Беззнаковый integer (машинно-зависимые размер и порядок байтов)</entry>
          </row>
          <row>
           <entry>l</entry>
           <entry>Знаковый long (всегда 32 бита, машинный порядок байтов)</entry>
          </row>
          <row>
           <entry>L</entry>
           <entry>Беззнаковый long (всегда 32 бита, машинный порядок байтов)</entry>
          </row>
          <row>
           <entry>N</entry>
           <entry>Беззнаковый long (всегда 32 бита, порядок байтов от старшего к младшему)</entry>
          </row>
          <row>
           <entry>V</entry>
           <entry>Беззнаковый long (всегда 32 бита, порядок байтов от младшего к старшему)</entry>
          </row>
          <row>
           <entry>q</entry>
           <entry>Знаковый long long (всегда 64 бита, машинный порядок байтов)</entry>
          </row>
          <row>
           <entry>Q</entry>
           <entry>Беззнаковый long long (всегда 64 бита, машинный порядок байтов)</entry>
          </row>
          <row>
           <entry>J</entry>
           <entry>Беззнаковый long long (всегда 64 бита, порядок байтов от старшего к младшему)</entry>
          </row>
          <row>
           <entry>P</entry>
           <entry>Беззнаковый long long (всегда 64 бита, порядок байтов от младшего к старшему)</entry>
          </row>
          <row>
           <entry>f</entry>
           <entry>Число с плавающей точкой float (машинно-зависимые размер и представление)</entry>
          </row>
          <row>
           <entry>g</entry>
           <entry>Число с плавающей точкой float (машинно-зависимый размер, порядок байтов от младшего к старшему)</entry>
          </row>
          <row>
           <entry>G</entry>
           <entry>Число с плавающей точкой float (машинно-зависимый размер, порядок байтов от старшего к младшему)</entry>
          </row>
          <row>
           <entry>d</entry>
           <entry>Число double (машинно-зависимые размер и представление)</entry>
          </row>
          <row>
           <entry>e</entry>
           <entry>Число double (машинно-зависимый размер, порядок байтов от младшего к старшему)</entry>
          </row>
          <row>
           <entry>E</entry>
           <entry>Число double (машинно-зависимый размер, порядок байтов от старшего к младшему)</entry>
          </row>
          <row>
           <entry>x</entry>
           <entry>NUL-байт</entry>
          </row>
          <row>
           <entry>X</entry>
           <entry>Резервирование одного байта</entry>
          </row>
          <row>
           <entry>Z</entry>
           <entry>NUL-терминированная строка (string), или ASCIIZ-строка, дополненная NUL-символами</entry>
          </row>
          <row>
           <entry>@</entry>
           <entry>NUL-заполнение до абсолютной позиции</entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>values</parameter></term>
     <listitem>
      <para>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Функция возвращает двоичную строку, которая содержит данные.
  </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>8.0.0</entry>
       <entry>
        Функция больше не возвращает &false;, если возникла ошибка.
       </entry>
      </row>
      <row>
       <entry>7.2.0</entry>
       <entry>
        Типы <type>float</type> и <type>double</type> поддерживают
        как прямой, так и обратный порядок байтов.
       </entry>
      </row>
      <row>
       <entry>7.0.15, 7.1.1</entry>
       <entry>
        Добавили коды e, E, g и G для поддержки порядка байтов для типов float и double.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1><!-- }}} -->

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Пример использования функции <function>pack</function></title>
    <programlisting role="php">
<![CDATA[
<?php

$binarydata = pack("nvc*", 0x1234, 0x5678, 65, 66);

?>
]]>
    </programlisting>
    <para>
     Длина результирующей двоичной строки будет составлять 6 байтов,
     и строка будет содержать последовательность байтов: 0x12, 0x34, 0x78, 0x56, 0x41, 0x42.
    </para>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <caution>
    <simpara>Коды форматирования <literal>q</literal>, <literal>Q</literal>, <literal>J</literal> и <literal>P</literal> недоступны в 32-разрядных сборках интерпретатора PHP.</simpara>
  </caution>
  <caution>
   <para>
    Обратите внимание, что внутренне PHP хранит значения с типом <type>int</type>
    как знаковые значения машинно-зависимого размера.
    Целочисленные литералы и операции, которые возвращают числа за пределами типа <type>int</type>,
    будут храниться как <type>float</type>.
    При упаковке чисел с плавающей точкой как целых чисел
    числа с плавающей точкой сначала приводятся к целочисленному типу.
    Поэтому результат или будет совпадать с заданной структурой байтов, или нет.
   </para>
   <para>
    Нагляднее остальных это показывает пример с упаковкой беззнаковых чисел, которые можно было бы представить
    типом <type>int</type>, если бы этот тип был беззнаковым. В системах, в которых размер
    <type>int</type> составляет 32 бита, приведение обычно даёт ту же структуру байтов,
    как если бы тип <type>int</type> был беззнаковым (хотя, это зависит от определяемых реализацией
    преобразований по правилам стандарта языка С беззнаковых чисел в числа со знаком).
    В системах, в которых размер типа <type>int</type> составляет 64 бита,
    у типа <type>float</type>, скорее всего, нет мантиссы необходимого размера, чтобы удерживать
    значение без потери точности.
    Если в этих системах также есть собственный 64-разрядный тип C <literal>int</literal>
    (в большей части UNIX-систем такого типа нет), то единственный способ
    использовать формат упаковки <literal>I</literal> в верхнем диапазоне — создать
    отрицательные значения с типом <type>int</type> с тем же байтовым представлением,
    что и у беззнакового значения, которое требуется получить.
   </para>
  </caution>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>unpack</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- 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:"~/.phpdoc/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
-->