<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.mysql-fetch-array" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>mysql_fetch_array</refname>
  <refpurpose>Fetch a result row as an associative array, a numeric array, or both</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <warning>
   &mysql.alternative.note;
   <simplelist role="alternatives">
    <member><function>mysqli_fetch_array</function></member>
    <member><methodname>PDOStatement::fetch</methodname></member>
   </simplelist>
  </warning>
 </refsynopsisdiv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>mysql_fetch_array</methodname>
   <methodparam><type>resource</type><parameter>result</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>result_type</parameter><initializer>MYSQL_BOTH</initializer></methodparam>
  </methodsynopsis>
  <para>
   Returns an array that corresponds to the fetched row
   and moves the internal data pointer ahead.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    &mysql.result.description;
    <varlistentry>
     <term><parameter>result_type</parameter></term>
     <listitem>
      <para>
       The type of array that is to be fetched. It's a constant and can
       take the following values: <constant>MYSQL_ASSOC</constant>, 
       <constant>MYSQL_NUM</constant>, and
       <constant>MYSQL_BOTH</constant>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an array of strings that corresponds to the fetched row, or &false;
   if there are no more rows. The type of returned array depends on
   how <parameter>result_type</parameter> is defined. By using 
   <constant>MYSQL_BOTH</constant> (default), you'll get an array with both 
   associative and number indices. Using <constant>MYSQL_ASSOC</constant>, you 
   only get associative indices (as <function>mysql_fetch_assoc</function> 
   works), using <constant>MYSQL_NUM</constant>, you only get number indices 
   (as <function>mysql_fetch_row</function> works).
  </para>
  <para>
   If two or more columns of the result have the same field names,
   the last column will take precedence. To access the other column(s)
   of the same name, you must use the numeric index of the column or
   make an alias for the column. For aliased columns, you cannot
   access the contents with the original column name.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Query with aliased duplicate field names</title>
    <programlisting role="sql">
<![CDATA[
SELECT table1.field AS foo, table2.field AS bar FROM table1, table2
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>mysql_fetch_array</function> with <constant>MYSQL_NUM</constant></title>
    <programlisting role="php">
<![CDATA[
<?php
mysql_connect("localhost", "mysql_user", "mysql_password") or
    die("Could not connect: " . mysql_error());
mysql_select_db("mydb");

$result = mysql_query("SELECT id, name FROM mytable");

while ($row = mysql_fetch_array($result, MYSQL_NUM)) {
    printf("ID: %s  Name: %s", $row[0], $row[1]);  
}

mysql_free_result($result);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>mysql_fetch_array</function> with <constant>MYSQL_ASSOC</constant></title>
    <programlisting role="php">
<![CDATA[
<?php
mysql_connect("localhost", "mysql_user", "mysql_password") or
    die("Could not connect: " . mysql_error());
mysql_select_db("mydb");

$result = mysql_query("SELECT id, name FROM mytable");

while ($row = mysql_fetch_array($result, MYSQL_ASSOC)) {
    printf("ID: %s  Name: %s", $row["id"], $row["name"]);
}

mysql_free_result($result);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>mysql_fetch_array</function> with <constant>MYSQL_BOTH</constant></title>
    <programlisting role="php">
<![CDATA[
<?php
mysql_connect("localhost", "mysql_user", "mysql_password") or
    die("Could not connect: " . mysql_error());
mysql_select_db("mydb");

$result = mysql_query("SELECT id, name FROM mytable");

while ($row = mysql_fetch_array($result, MYSQL_BOTH)) {
    printf ("ID: %s  Name: %s", $row[0], $row["name"]);
}

mysql_free_result($result);
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <title>Performance</title>
   <para>
    An important thing to note is that using 
    <function>mysql_fetch_array</function> is <emphasis>not 
    significantly</emphasis> slower than using
    <function>mysql_fetch_row</function>, while it provides
    a significant added value.
   </para>
  </note>
  &database.field-case;
  &database.fetch-null;
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mysql_fetch_row</function></member>
    <member><function>mysql_fetch_assoc</function></member>
    <member><function>mysql_data_seek</function></member>
    <member><function>mysql_query</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
-->
