Rename DB_result _data_seek() to data_seek() and make it publicly available
(as requested in #2050)
diff --git a/system/database/DB_result.php b/system/database/DB_result.php
index 9d19075..e1ef341 100644
--- a/system/database/DB_result.php
+++ b/system/database/DB_result.php
@@ -203,7 +203,7 @@
return $this->custom_result_object[$class_name];
}
- $this->_data_seek(0);
+ $this->data_seek(0);
$this->custom_result_object[$class_name] = array();
while ($row = $this->_fetch_object($class_name))
@@ -246,7 +246,7 @@
return $this->result_object;
}
- $this->_data_seek(0);
+ $this->data_seek(0);
while ($row = $this->_fetch_object())
{
$this->result_object[] = $row;
@@ -287,7 +287,7 @@
return $this->result_array;
}
- $this->_data_seek(0);
+ $this->data_seek(0);
while ($row = $this->_fetch_assoc())
{
$this->result_array[] = $row;
@@ -617,7 +617,7 @@
* @param int $n
* @return bool
*/
- protected function _data_seek($n = 0)
+ public function data_seek($n = 0)
{
return FALSE;
}
diff --git a/system/database/drivers/cubrid/cubrid_result.php b/system/database/drivers/cubrid/cubrid_result.php
index 130eea2..793b35b 100644
--- a/system/database/drivers/cubrid/cubrid_result.php
+++ b/system/database/drivers/cubrid/cubrid_result.php
@@ -130,7 +130,7 @@
* @param int $n
* @return bool
*/
- protected function _data_seek($n = 0)
+ public function data_seek($n = 0)
{
return cubrid_data_seek($this->result_id, $n);
}
diff --git a/system/database/drivers/mssql/mssql_result.php b/system/database/drivers/mssql/mssql_result.php
index a8f850d..ca222ae 100644
--- a/system/database/drivers/mssql/mssql_result.php
+++ b/system/database/drivers/mssql/mssql_result.php
@@ -135,7 +135,7 @@
* @param int $n
* @return bool
*/
- protected function _data_seek($n = 0)
+ public function data_seek($n = 0)
{
return mssql_data_seek($this->result_id, $n);
}
diff --git a/system/database/drivers/mysql/mysql_result.php b/system/database/drivers/mysql/mysql_result.php
index a6dcde4..293980e 100644
--- a/system/database/drivers/mysql/mysql_result.php
+++ b/system/database/drivers/mysql/mysql_result.php
@@ -149,7 +149,7 @@
* @param int $n
* @return bool
*/
- protected function _data_seek($n = 0)
+ public function data_seek($n = 0)
{
return $this->num_rows
? @mysql_data_seek($this->result_id, $n)
diff --git a/system/database/drivers/mysqli/mysqli_result.php b/system/database/drivers/mysqli/mysqli_result.php
index d55188e..ac0f1a8 100644
--- a/system/database/drivers/mysqli/mysqli_result.php
+++ b/system/database/drivers/mysqli/mysqli_result.php
@@ -136,7 +136,7 @@
* @param int $n
* @return bool
*/
- protected function _data_seek($n = 0)
+ public function data_seek($n = 0)
{
return $this->result_id->data_seek($n);
}
diff --git a/system/database/drivers/oci8/oci8_result.php b/system/database/drivers/oci8/oci8_result.php
index 7d5bf51..661ea49 100644
--- a/system/database/drivers/oci8/oci8_result.php
+++ b/system/database/drivers/oci8/oci8_result.php
@@ -240,8 +240,13 @@
* @param int $n (ignored)
* @return bool
*/
- protected function _data_seek($n = 0)
+ public function data_seek($n = 0)
{
+ if ($n > 0)
+ {
+ return FALSE;
+ }
+
/* The PHP manual says that if OCI_NO_AUTO_COMMIT mode
* is used, and oci_rollback() and/or oci_commit() are
* not subsequently called - this will cause an unnecessary
diff --git a/system/database/drivers/postgre/postgre_result.php b/system/database/drivers/postgre/postgre_result.php
index 3a4e57c..fdaeaef 100644
--- a/system/database/drivers/postgre/postgre_result.php
+++ b/system/database/drivers/postgre/postgre_result.php
@@ -133,7 +133,7 @@
* @param int $n
* @return bool
*/
- protected function _data_seek($n = 0)
+ public function data_seek($n = 0)
{
return pg_result_seek($this->result_id, $n);
}
diff --git a/system/database/drivers/sqlite/sqlite_result.php b/system/database/drivers/sqlite/sqlite_result.php
index 24f02a8b..889757d 100644
--- a/system/database/drivers/sqlite/sqlite_result.php
+++ b/system/database/drivers/sqlite/sqlite_result.php
@@ -117,7 +117,7 @@
* @param int $n
* @return bool
*/
- protected function _data_seek($n = 0)
+ public function data_seek($n = 0)
{
return sqlite_seek($this->result_id, $n);
}
diff --git a/system/database/drivers/sqlite3/sqlite3_result.php b/system/database/drivers/sqlite3/sqlite3_result.php
index 44fef89..69c4200 100644
--- a/system/database/drivers/sqlite3/sqlite3_result.php
+++ b/system/database/drivers/sqlite3/sqlite3_result.php
@@ -175,10 +175,10 @@
* @param int $n (ignored)
* @return array
*/
- protected function _data_seek($n = 0)
+ public function data_seek($n = 0)
{
// Only resetting to the start of the result set is supported
- return $this->result_id->reset();
+ return ($n > 0) ? FALSE : $this->result_id->reset();
}
}
diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index 9b0ea53..c2606f3 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -106,7 +106,6 @@
- Added **schema** configuration setting (defaults to *public*) for drivers that might need it (currently used by PostgreSQL and ODBC).
- Added subdrivers support (currently only used by PDO).
- Added an optional database name parameter to ``db_select()``.
- - Added a constructor to the ``DB_result`` class and moved all driver-specific properties and logic out of the base ``DB_driver`` class to allow better abstraction.
- Removed ``protect_identifiers()`` and renamed internal method ``_protect_identifiers()`` to it instead - it was just an alias.
- Renamed internal method ``_escape_identifiers()`` to ``escape_identifiers()``.
- Updated ``escape_identifiers()`` to accept an array of fields as well as strings.
@@ -114,8 +113,7 @@
- ``db_set_charset()`` now only requires one parameter (collation was only needed due to legacy support for MySQL versions prior to 5.1).
- Replaced the ``_error_message()`` and ``_error_number()`` methods with ``error()``, which returns an array containing the last database error code and message.
- Improved ``version()`` implementation so that drivers that have a native function to get the version number don't have to be defined in the core ``DB_driver`` class.
- - Added ``unbuffered_row()`` method for getting a row without prefetching whole result (consume less memory).
- - Added capability for packages to hold *database.php* config files.
+ - Added capability for packages to hold *config/database.php* config files.
- Added MySQL client compression support.
- Added encrypted connections support (for *mysql*, *sqlsrv* and PDO with *sqlsrv*).
- Removed :doc:`Loader Class <libraries/loader>` from Database error tracing to better find the likely culprit.
@@ -133,6 +131,10 @@
- Changed ``limit()`` to ignore NULL values instead of always casting to integer.
- Changed ``offset()`` to ignore empty values instead of always casting to integer.
- Methods ``insert_batch()`` and ``update_batch()`` now return an integer representing the number of rows affected by them.
+ - :doc:`Database Results <database/results>` changes include:
+ - Added a constructor to the ``DB_result`` class and moved all driver-specific properties and logic out of the base ``DB_driver`` class to allow better abstraction.
+ - Added method ``unbuffered_row()`` for fetching a row without prefetching the whole result (consume less memory).
+ - Renamed former method ``_data_seek()`` to ``data_seek()`` and made it public.
- Improved support for the MySQLi driver, including:
- OOP style of the PHP extension is now used, instead of the procedural aliases.
- Server version checking is now done via ``mysqli::$server_info`` instead of running an SQL query.
diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst
index d032f73..e0a87a8 100644
--- a/user_guide_src/source/database/results.rst
+++ b/user_guide_src/source/database/results.rst
@@ -99,7 +99,7 @@
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::
@@ -138,12 +138,12 @@
.. note:: all the functions above will load the whole result into memory (prefetching) use unbuffered_row() for processing large result sets.
-unbuffered_row($type)
-=====================
+unbuffered_row()
+================
-This function 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.
-The result is returned as $type could be 'object' (default) or 'array' that will return an associative array.
+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.
::
@@ -156,12 +156,19 @@
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::
@@ -177,7 +184,7 @@
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::
@@ -187,7 +194,7 @@
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
@@ -209,3 +216,21 @@
$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