archived-doc-zh/reference/array/functions/array.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 96c9d88bad9a7d7d44bfb7f26c226df7ee9ddf26 Maintainer: HonestQiao Status: ready -->
<!-- Reviewed: no Maintainer: HonestQiao -->
<refentry xml:id="function.array" xmlns="http://docbook.org/ns/docbook">
   <refnamediv>
    <refname>array</refname>
    <refpurpose>
     新建一个数组
    </refpurpose>
   </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
     <methodsynopsis>
      <type>array</type><methodname>array</methodname>
      <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
     </methodsynopsis>
    <para>
     返回根据参数建立的数组。参数可以用 <literal>=&gt;</literal>
     运算符给出索引。关于数组是什么的信息请阅读<link linkend="language.types.array">数组</link>一节。
    </para>
    <note>
     <para>
      <function>array</function> 是一个语言结构，用于字面上表示数组，不是常规的函数。
     </para>
    </note>
    <para>
     语法“index =&gt; values”，用逗号分开，定义了索引和值。索引可以是字符串或数字。如果省略了索引，会自动产生从
     0 开始的整数索引。如果索引是整数，则下一个产生的索引将是目前最大的整数索引
     + 1。注意如果定义了两个完全一样的索引，则后面一个会覆盖前一个。
    </para>
    <para>
     在最后一个定义的数组项目之后加一个逗号虽然不常见，却是合法的语法。
    </para>
    <para>
     下面的例子演示了怎样建立一个二维数组，怎样给相应的数组指定键名，以及怎样在普通数组中略过和继续数字索引。
     <example>
      <title><function>array</function> 例子</title>
      <programlisting role="php">
<![CDATA[
<?php
$fruits = array (
    "fruits"  => array("a" => "orange", "b" => "banana", "c" => "apple"),
    "numbers" => array(1, 2, 3, 4, 5, 6),
    "holes"   => array("first", 5 => "second", "third")
);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     <example>
      <title><function>array</function> 的自动索引</title>
      <programlisting role="php">
<![CDATA[
<?php
$array = array(1, 1, 1, 1,  1, 8 => 1,  4 => 1, 19, 3 => 13);
print_r($array);
?>
]]>
      </programlisting>
      &example.outputs;
      <screen role="php">
<![CDATA[
Array
(
    [0] => 1
    [1] => 1
    [2] => 1
    [3] => 13
    [4] => 1
    [8] => 1
    [9] => 19
)
]]>
      </screen>
     </example>
    </para>
    <para>
     注意索引 3 被定义了两次，保留了最后的值 13。索引 4 在 索引
     8 之后定义，下一个自动生成的索引（值为 19 那个）为 9，因为最大的索引是 8。
    </para>
    <para>
     本例建立了从 1 开始的数组。
     <example>
      <title>从 1 开始索引的 <function>array</function></title>
      <programlisting role="php">
<![CDATA[
<?php
$firstquarter = array(1 => 'January', 'February', 'March');
print_r($firstquarter);
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Array
(
    [1] => January
    [2] => February
    [3] => March
)
]]>
      </screen>
     </example>
    </para>
    <para>
     在 Perl 中，可以访问在双引号内的数组的值。但在 PHP
     中需要将数组用花括号括起来。
     <example>
      <title>访问双引号内的数组</title>
      <programlisting role="php">
<![CDATA[
<?php

$foo = array('bar' => 'baz');
echo "Hello {$foo['bar']}!"; // Hello baz!

?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     参见 <function>array_pad</function>，<function>list</function>，<function>count</function>，<link
     linkend="control-structures.foreach">foreach</link>
     和 <function>range</function>。
    </para>
   </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>...</parameter></term>
     <listitem>
      <para>
       Syntax "index =&gt; values", separated by commas, define index
       and values. index may be of type string or integer. When index is
       omitted, an integer index is automatically generated, starting
       at 0. If index is an integer, next generated index will
       be the biggest integer index + 1. Note that when two identical
       index are defined, the last overwrite the first.
      </para>
      <para>
       Having a trailing comma after the last defined array entry, while
       unusual, is a valid syntax.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an array of the parameters.  The parameters can be given
   an index with the <literal>=&gt;</literal> operator.  Read the section
   on the <link linkend="language.types.array">array type</link> for more
   information on what an array is.
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   The following example demonstrates how to create a
   two-dimensional array, how to specify keys for associative
   arrays, and how to skip-and-continue numeric indices in normal
   arrays.
   <example>
    <title><function>array</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$fruits = array (
    "fruits"  => array("a" => "orange", "b" => "banana", "c" => "apple"),
    "numbers" => array(1, 2, 3, 4, 5, 6),
    "holes"   => array("first", 5 => "second", "third")
);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Automatic index with <function>array</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$array = array(1, 1, 1, 1,  1, 8 => 1,  4 => 1, 19, 3 => 13);
print_r($array);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
Array
(
    [0] => 1
    [1] => 1
    [2] => 1
    [3] => 13
    [4] => 1
    [8] => 1
    [9] => 19
)
]]>
    </screen>
   </example>
  </para>
  <para>
   Note that index '3' is defined twice, and keep its final value of 13.
   Index 4 is defined after index 8, and next generated index (value 19)
   is 9, since biggest index was 8.
  </para>
  <para>
   This example creates a 1-based array.
   <example>
    <title>1-based index with <function>array</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$firstquarter = array(1 => 'January', 'February', 'March');
print_r($firstquarter);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Array
(
    [1] => January
    [2] => February
    [3] => March
)
]]>
    </screen>
   </example>
  </para>
  <para>
   As in Perl, you can access a value from the array inside double quotes.
   However, with PHP you'll need to enclose your array between curly braces.
   <example>
    <title>Accessing an array inside double quotes</title>
    <programlisting role="php">
<![CDATA[
<?php

$foo = array('bar' => 'baz');
echo "Hello {$foo['bar']}!"; // Hello baz!

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 <refsect1 role="notes">
  &reftitle.notes;
  <para>
   <note>
    <para>
     <function>array</function> is a language construct used to
     represent literal arrays, and not a regular function.
    </para>
   </note>
  </para>
 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>array_pad</function></member>
    <member><function>list</function></member>
    <member><function>count</function></member>
    <member><function>range</function></member>
    <member>&foreach;</member>
    <member>The <link linkend="language.types.array">array</link> type</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
-->