mirror of
https://github.com/php/doc-pt_br.git
synced 2026-04-29 19:23:27 +02:00
André L F S Bacci
315 lines
10 KiB
XML
315 lines
10 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- EN-Revision: ad0f1eaa6510e1d11231f46515ca513d2cd097c4 Maintainer: leonardolara Status: ready -->
|
|
<refentry xml:id="function.pack" xmlns="http://docbook.org/ns/docbook">
|
|
<refnamediv>
|
|
<refname>pack</refname>
|
|
<refpurpose>Empacota dados em uma string binária</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>
|
|
Empacota os argumentos fornecidos em uma string binária de acordo com o formato
|
|
especificado em <parameter>format</parameter>.
|
|
</para>
|
|
<para>
|
|
A ideia para esta função foi tirada do Perl e todos os códigos de formatação
|
|
funcionam da mesma forma que no Perl. Entretanto, há alguns códigos de formatação que
|
|
não existem, como código "u" do Perl.
|
|
</para>
|
|
<para>
|
|
Observe que a distinção entre valores com e sem sinal somente
|
|
afeta a função <function>unpack</function>, enquanto que
|
|
a função <function>pack</function> fornece o mesmo resultado para
|
|
códigos de formato com e sem sinal.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>format</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
A string <parameter>format</parameter> consistem em códigos de formato
|
|
seguidos de um argumento repetidor opcional. O argumento repetidor pode
|
|
ser um valor inteiro ou <literal>*</literal> para repetir até
|
|
o final dos dados de entrada. Para a, A, h, H a contagem de repetição especifica
|
|
quantos caracteres de um argumento de dados são tomados, para @ é a
|
|
posição absoluta onde será colocado o próximo dado, para todo o restante a contagem
|
|
de repetição especifica quantos argumentos de dados são consumidos e empacotados
|
|
na string binária resultante.
|
|
</para>
|
|
<para>
|
|
Os formatos atualmente implementados são:
|
|
<table>
|
|
<title>Caracteres de formato de <function>pack</function></title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Código</entry>
|
|
<entry>Descrição</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>a</entry>
|
|
<entry>String com bytes NUL à esquerda</entry>
|
|
</row>
|
|
<row>
|
|
<entry>A</entry>
|
|
<entry>String com espaços à esquerda</entry></row>
|
|
<row>
|
|
<entry>h</entry>
|
|
<entry>String hexadecimal, nibble menos significativo primeiro</entry></row>
|
|
<row>
|
|
<entry>H</entry>
|
|
<entry>String hexadecimal, nibble mais significativo primeiro</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 (sempre 16 bits, ordem de bytes da máquina)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>S</entry>
|
|
<entry>unsigned short (sempre 16 bits, ordem de bytes da máquina)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>n</entry>
|
|
<entry>unsigned short (sempre 16 bits, ordem de bytes Big Endian)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>v</entry>
|
|
<entry>unsigned short (sempre 16 bits, ordem de bytes Little Endian)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>i</entry>
|
|
<entry>signed integer (tamanho e ordem de bytes dependentes da máquina)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>I</entry>
|
|
<entry>unsigned integer (tamanho e ordem de bytes dependentes da máquina)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>l</entry>
|
|
<entry>signed long (sempre 32 bits, ordem de bytes da máquina)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>L</entry>
|
|
<entry>unsigned long (sempre 32 bits, ordem de bytes da máquina)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>N</entry>
|
|
<entry>unsigned long (sempre 32 bits, ordem de bytes Big Endian)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>V</entry>
|
|
<entry>unsigned long (sempre 32 bits, ordem de bytes Little Endian)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>q</entry>
|
|
<entry>signed long long (sempre 64 bits, ordem de bytes da máquina)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Q</entry>
|
|
<entry>unsigned long long (sempre 64 bits, ordem de bytes da máquina)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>J</entry>
|
|
<entry>unsigned long long (sempre 64 bits, ordem de bytes Big Endian)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>P</entry>
|
|
<entry>unsigned long long (sempre 64 bits, ordem de bytes Little Endian)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>f</entry>
|
|
<entry>float (representação e tamanho dependentes da máquina)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>g</entry>
|
|
<entry>float (tamanho dependente da máquina, ordem de bytes Little Endian)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>G</entry>
|
|
<entry>float (tamanho dependente da máquina, ordem de bytes Big Endian)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>d</entry>
|
|
<entry>double (representação e tamanho dependentes da máquina)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>e</entry>
|
|
<entry>double (tamanho dependente da máquina, ordem de bytes Little Endian)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>E</entry>
|
|
<entry>double (tamanho dependente da máquina, ordem de bytes Big Endian)</entry>
|
|
</row>
|
|
<row>
|
|
<entry>x</entry>
|
|
<entry>byte NUL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>X</entry>
|
|
<entry>Volta um byte</entry>
|
|
</row>
|
|
<row>
|
|
<entry>Z</entry>
|
|
<entry>String terminada em NUL (ASCIIZ), preenchida com bytes NUL</entry>
|
|
</row>
|
|
<row>
|
|
<entry>@</entry>
|
|
<entry>Preenche com bytes NUL até a posição absoluta</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>
|
|
Retorna uma string binária contendo dados.
|
|
</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>
|
|
Esta função não mais retorna &false; em caso de falha.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>7.2.0</entry>
|
|
<entry>
|
|
Tipos <type>float</type> e <type>double</type> suportam tanto Big Endian quanto Little Endian.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>7.0.15, 7.1.1</entry>
|
|
<entry>
|
|
Os códigos "e", "E", "g" e "G" foram adicionados para habilitar suporte a ordem de byte para float e double.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1><!-- }}} -->
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title>Exemplo de <function>pack</function></title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$binarydata = pack("nvc*", 0x1234, 0x5678, 65, 66);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
A string binária resultante terá 6 bytes de comprimento e conterá
|
|
a sequência de bytes 0x12, 0x34, 0x78, 0x56, 0x41, 0x42.
|
|
</para>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
<caution>
|
|
<simpara>Os códigos de formato <literal>q</literal>, <literal>Q</literal>, <literal>J</literal> e <literal>P</literal> não estão disponíveis em versões do PHP de 32 bits.</simpara>
|
|
</caution>
|
|
<caution>
|
|
<para>Observe que, internamente, o PHP armazena valores <type>int</type> como
|
|
valores com sinal de tamanho dependente da máquina.
|
|
Literais inteiros e operações que resultam em números fora da faixa do tipo
|
|
<type>int</type> serão armazenados como <type>float</type>.
|
|
Ao empacotar estes floats como inteiros, eles primeiro são convertidos para o
|
|
tipo inteiro. Isto pode ou não resultar no padrão de bytes desejado.
|
|
</para>
|
|
<para>O caso mais relevante ocorre ao empacotar números sem sinal que poderiam
|
|
ser representáveis pelo tipo <type>int</type> se eles fossem sem sinal.
|
|
Em sistemas onde o tipo <type>int</type> tem 32 bits, a conversão
|
|
normalmente resulta no mesmo padrão de byte como se o <type>int</type> fosse
|
|
sem sinal (embora isso dependa das conversões de sem sinal para com sinal definidas
|
|
pela implementação, conforme o padrão C). Em sistemas onte o tipo
|
|
<type>int</type> tem 64 bits, o tipo <type>float</type> provavelmente
|
|
não terá a mantissa grande o suficiente para representar o valor sem
|
|
perda de precisão. Se estes sistemas também tiverem o tipo
|
|
<literal>int</literal> nativo de 64 bits (a maioria dos sistemas tipo UNIX não têm), a única maneira
|
|
de usar o formato <literal>I</literal> de empacotamento na faixa superior é criar
|
|
valores negativos <type>int</type> com a mesma representação de bytes
|
|
do valor sem sinal desejado.
|
|
</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
|
|
-->
|