summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/database/results.rst
diff options
context:
space:
mode:
Diffstat (limited to 'user_guide_src/source/database/results.rst')
-rw-r--r--user_guide_src/source/database/results.rst53
1 files changed, 49 insertions, 4 deletions
diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst
index 865345762..e0a87a851 100644
--- a/user_guide_src/source/database/results.rst
+++ b/user_guide_src/source/database/results.rst
@@ -99,7 +99,7 @@ to instantiate the row with::
echo $row->reverse_name(); // or methods defined on the 'User' class
row_array()
-============
+===========
Identical to the above row() function, except it returns an array.
Example::
@@ -136,12 +136,39 @@ parameter:
| **$row = $query->next_row('array')**
| **$row = $query->previous_row('array')**
+.. note:: all the functions above will load the whole result into memory (prefetching) use unbuffered_row() for processing large result sets.
+
+unbuffered_row()
+================
+
+This method returns a single result row without prefetching the whole
+result in memory as ``row()`` does. If your query has more than one row,
+it returns the current row and moves the internal data pointer ahead.
+
+::
+
+ $query = $this->db->query("YOUR QUERY");
+
+ while ($row = $query->unbuffered_row())
+ {
+ echo $row->title;
+ echo $row->name;
+ echo $row->body;
+ }
+
+You can optionally pass 'object' (default) or 'array' in order to specify
+the returned value's type::
+
+ $query->unbuffered_row(); // object
+ $query->unbuffered_row('object'); // object
+ $query->unbuffered_row('array'); // associative array
+
***********************
Result Helper Functions
***********************
$query->num_rows()
-===================
+==================
The number of rows returned by the query. Note: In this example, $query
is the variable that the query result object is assigned to::
@@ -157,7 +184,7 @@ is the variable that the query result object is assigned to::
resulting array in order to achieve the same functionality.
$query->num_fields()
-=====================
+====================
The number of FIELDS (columns) returned by the query. Make sure to call
the function using your query result object::
@@ -167,7 +194,7 @@ the function using your query result object::
echo $query->num_fields();
$query->free_result()
-======================
+=====================
It frees the memory associated with the result and deletes the result
resource ID. Normally PHP frees its memory automatically at the end of
@@ -189,3 +216,21 @@ Example::
$row = $query2->row();
echo $row->name;
$query2->free_result(); // The $query2 result object will no longer be available
+
+data_seek()
+===========
+
+This method sets the internal pointer for the next result row to be
+fetched. It is only useful in combination with ``unbuffered_row()``.
+
+It accepts a positive integer value, which defaults to 0 and returns
+TRUE on success or FALSE on failure.
+
+::
+
+ $query = $this->db->query('SELECT `field_name` FROM `table_name`');
+ $query->data_seek(5); // Skip the first 5 rows
+ $row = $query->unbuffered_row();
+
+.. note:: Not all database drivers support this feature and will return FALSE.
+ Most notably - you won't be able to use it with PDO. \ No newline at end of file