php-doc-en/reference/pgsql/functions/pg-fetch-array.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.pg-fetch-array" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>pg_fetch_array</refname>
  <refpurpose>Fetch a row as an array</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>pg_fetch_array</methodname>
   <methodparam><type>PgSql\Result</type><parameter>result</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>row</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer><constant>PGSQL_BOTH</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>pg_fetch_array</function> returns an array that
   corresponds to the fetched row (record).
  </para>
  <para>
   <function>pg_fetch_array</function> is an extended version of
   <function>pg_fetch_row</function>.  In addition to storing the
   data in the numeric indices (field number) to the result array, it
   can also store the data using associative indices (field name).
   It stores both indices by default.
  </para>
  &database.fetch-null;
  <para>
   <function>pg_fetch_array</function> is NOT significantly
   slower than using <function>pg_fetch_row</function>, and
   is significantly easier to use.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>result</parameter></term>
     <listitem>
      &pgsql.parameter.result;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>row</parameter></term>
     <listitem>
      <para>
       Row number in result to fetch. Rows are numbered from 0 upwards. If
       omitted or &null;, the next row is fetched.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
       An optional parameter that controls
       how the returned <type>array</type> is indexed.
       <parameter>mode</parameter> is a constant and can take the
       following values: <constant>PGSQL_ASSOC</constant>, 
       <constant>PGSQL_NUM</constant> and <constant>PGSQL_BOTH</constant>.
       Using <constant>PGSQL_NUM</constant>, <function>pg_fetch_array</function>
       will return an array with numerical indices, using
       <constant>PGSQL_ASSOC</constant> it will return only associative indices
       while <constant>PGSQL_BOTH</constant>, the default, will return both
       numerical and associative indices.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   An <type>array</type> indexed numerically (beginning with 0) or
   associatively (indexed by field name), or both.
   Each value in the <type>array</type> is represented as a 
   <type>string</type>.  Database <literal>NULL</literal>
   values are returned as &null;.
  </para>
  <para>
   &false; is returned if <parameter>row</parameter> exceeds the number
   of rows in the set, there are no more rows, or on any other error.
   Fetching from the result of a query other than SELECT will also return &false;.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     &pgsql.changelog.result-object;
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>pg_fetch_array</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php 

$conn = pg_pconnect("dbname=publisher");
if (!$conn) {
  echo "An error occurred.\n";
  exit;
}

$result = pg_query($conn, "SELECT author, email FROM authors");
if (!$result) {
  echo "An error occurred.\n";
  exit;
}

$arr = pg_fetch_array($result, 0, PGSQL_NUM);
echo $arr[0] . " <- Row 1 Author\n";
echo $arr[1] . " <- Row 1 E-mail\n";

// The row parameter is optional; NULL can be passed instead,
// to pass a result_type.  Successive calls to pg_fetch_array
// will return the next row.
$arr = pg_fetch_array($result, NULL, PGSQL_ASSOC);
echo $arr["author"] . " <- Row 2 Author\n";
echo $arr["email"] . " <- Row 2 E-mail\n";

$arr = pg_fetch_array($result);
echo $arr["author"] . " <- Row 3 Author\n";
echo $arr[1] . " <- Row 3 E-mail\n";

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>pg_fetch_row</function></member>
    <member><function>pg_fetch_object</function></member>
    <member><function>pg_fetch_result</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
-->