From 98b9b722e8bbcd3bb30e2c8b483a65f633434820 Mon Sep 17 00:00:00 2001
From: Dan Scott <dbs@php.net>
Date: Tue, 1 Mar 2005 00:37:59 +0000
Subject: [PATCH] Add an example for counting rows in SELECT statements.
 Probably still need to apply a <blink> tag to this.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@181049 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../pdo/functions/PDOStatement-rowCount.xml   | 88 +++++++++++++++++--
 1 file changed, 81 insertions(+), 7 deletions(-)

diff --git a/reference/pdo/functions/PDOStatement-rowCount.xml b/reference/pdo/functions/PDOStatement-rowCount.xml
index 74bd0703d6..1002d1e040 100644
--- a/reference/pdo/functions/PDOStatement-rowCount.xml
+++ b/reference/pdo/functions/PDOStatement-rowCount.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
   <refentry id="function.PDOStatement-rowCount">
    <refnamediv>
@@ -8,8 +8,8 @@
      Returns the number of rows affected by the last SQL statement
     </refpurpose>
    </refnamediv>
-   <refsect1>
-    <title>Description</title>
+   <refsect1 role="description">
+    &reftitle.description;
     <methodsynopsis>
      <type>int</type><methodname>PDOStatement::rowCount</methodname>
      <void/>
@@ -28,8 +28,17 @@
      behaviour is not guaranteed for all databases and should not be relied
      on for portable applications.
     </para>
-    <example><title>Return the number of deleted rows</title>
-     <programlisting role="php">
+   </refsect1>
+   <refsect1 role="examples">
+    &reftitle.examples;
+    <para>
+     <example>
+      <title>Return the number of deleted rows</title>
+      <para>
+       <function>PDOStatement::rowCount</function> returns the number of
+       rows affected by a DELETE, INSERT, or UPDATE statement.
+      </para>
+      <programlisting role="php">
 <![CDATA[
 <?php
 /* Delete all rows from the FRUIT table */
@@ -42,8 +51,73 @@ $count = $del->rowCount();
 print("Deleted $count rows.\n");
 ?>
 ]]>
-     </programlisting>
-    </example>
+      </programlisting>
+      &example.outputs;
+      <screen>
+<![CDATA[
+Deleted 9 rows.
+]]>
+      </screen>
+     </example>
+     <example>
+      <title>Counting rows returned by a SELECT statement</title>
+      <para>
+       For most databases, <function>PDOStatement::rowCount</function> does not
+       return the number of rows affected by a SELECT statement. Instead, use
+       <function>PDO::query</function> to issue a SELECT COUNT(*) statement
+       with the same predicates as your intended SELECT statement, then use
+       <function>PDOStatement::fetchSingle</function> to retrieve the number
+        of rows that will be returned. Your application can then perform the
+        correct action.
+      </para>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$sql = "SELECT COUNT(*) FROM fruit WHERE calories > 100";
+if ($res = $conn->query($sql)) {
+
+    // Check the number of rows that match the SELECT statement
+    if ($res->fetchSingle() > 0) {
+
+        // Issue the real SELECT statement and work with the results
+         $sql = "SELECT name FROM fruit WHERE calories > 100";
+         foreach ($conn->query($sql) as $row) {
+             print "Name: " .  $row['NAME'] . "\n";
+         }
+    }
+    // No rows matched -- do something else
+    else {
+        print "No rows matched the query.";
+    }
+}
+
+$res = null;
+$conn = null;
+?>
+]]>
+      </programlisting>
+      &example.outputs;
+      <screen>
+<![CDATA[
+apple
+banana
+orange
+pear
+]]>
+      </screen>
+     </example>
+
+    </para>
+   </refsect1>
+   <refsect1 role="seealso">
+    &reftitle.seealso;
+    <para>
+     <simplelist>
+      <member><function>PDOStatement::query</function></member>
+      <member><function>PDOStatement::fetchSingle</function></member>
+     </simplelist>
+    </para>
+
    </refsect1>
   </refentry>