pack.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 7926717892c5129038097f8a1fa396e209837575 Maintainer: hirokawa Status: ready -->
<!-- CREDITS: takagi,mumumu -->
<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>
       フォーマット文字列は、
       フォーマットコードの後にオプションの反復指定用引数が続く形式と
       なっています。反復指定用引数として整数値、または入力データの最後まで
       反復を意味する <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>NUL で埋めた文字列</entry>
          </row>
          <row>
           <entry>A</entry>
           <entry>空白で埋めた文字列</entry></row>
          <row>
           <entry>h</entry>
           <entry>十六進文字列、下位ニブルが先</entry></row>
          <row>
           <entry>H</entry>
           <entry>十六進文字列、上位ニブルが先</entry></row>
          <row><entry>c</entry><entry>signed char</entry></row>
          <row>
           <entry>C</entry>
           <entry>unsigned char</entry></row>
          <row>
           <entry>s</entry>
           <entry>signed short (常に 16 ビット、マシンのバイトオーダー)</entry>
          </row>
          <row>
           <entry>S</entry>
           <entry>unsigned short (常に 16 ビット、マシンのバイトオーダー)</entry>
          </row>
          <row>
           <entry>n</entry>
           <entry>unsigned short (常に 16 ビット、ビッグエンディアンバイトオーダー)</entry>
          </row>
          <row>
           <entry>v</entry>
           <entry>unsigned short (常に 16 ビット、リトルエンディアンバイトオーダー)</entry>
          </row>
          <row>
           <entry>i</entry>
           <entry>signed integer (サイズおよびバイトオーダーはマシン依存)</entry>
          </row>
          <row>
           <entry>I</entry>
           <entry>unsigned integer (サイズおよびバイトオーダーはマシン依存)</entry>
          </row>
          <row>
           <entry>l</entry>
           <entry>signed long (常に 32 ビット、マシンのバイトオーダー)</entry>
          </row>
          <row>
           <entry>L</entry>
           <entry>unsigned long (常に 32 ビット、マシンのバイトオーダー)</entry>
          </row>
          <row>
           <entry>N</entry>
           <entry>unsigned long (常に 32 ビット、ビッグエンディアンバイトオーダー)</entry>
          </row>
          <row>
           <entry>V</entry>
           <entry>unsigned long (常に 32 ビット、リトルエンディアンバイトオーダー)</entry>
          </row>
          <row>
           <entry>q</entry>
           <entry>signed long long (常に 64 ビット、マシンのバイトオーダー)</entry>
          </row>
          <row>
           <entry>Q</entry>
           <entry>unsigned long long (常に 64 ビット、マシンのバイトオーダー)</entry>
          </row>
          <row>
           <entry>J</entry>
           <entry>unsigned long long (常に 64 ビット、ビッグエンディアンバイトオーダー)</entry>
          </row>
          <row>
           <entry>P</entry>
           <entry>unsigned 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>1 バイト戻る</entry>
          </row>
          <row>
           <entry>Z</entry>
           <entry>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>
   <para>
    PHP は、<type>int</type> 型の値を内部的に格納する際に
    サイズがマシン依存の符号付き値 (C の <literal>long</literal> 型)
    を使うことに注意しましょう。<type>int</type>
    型の範囲外の数値となる整数リテラルや演算結果は <type>float</type>
    として保持されます。この float 値を integer としてパックする際には
    まず最初に integer 型へのキャストを行います。
    その結果、できあがるバイトパターンは期待通りにはならないかもしれません。
   </para>
   <para>
    この問題にもっとも関連するのが、符号なしの数値で <type>int</type>
    型で表現できるものをパックする場合です。
    <type>int</type> 型のサイズが 32 ビットであるシステムでのキャスト結果は、
    (実装で定義されている標準 C の符号なし型から符号付き型への変換に依存しますが)
    まるで <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
-->