summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/database/results.rst
diff options
context:
space:
mode:
authorAndrey Andreev <narf@devilix.net>2014-12-11 17:31:51 +0100
committerAndrey Andreev <narf@devilix.net>2014-12-11 17:31:51 +0100
commitab0034bb8a72fc397609ff541182a1819580d761 (patch)
tree0574a6d7c44e1c33a92a23dcd3f266e55030714a /user_guide_src/source/database/results.rst
parent4fce5c482f5168886f99d9849848f0b54d256670 (diff)
[ci skip] Update DB result docs
Related: #3395
Diffstat (limited to 'user_guide_src/source/database/results.rst')
-rw-r--r--user_guide_src/source/database/results.rst276
1 files changed, 143 insertions, 133 deletions
diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst
index 044360ebb..ae81998c7 100644
--- a/user_guide_src/source/database/results.rst
+++ b/user_guide_src/source/database/results.rst
@@ -12,8 +12,7 @@ There are several ways to generate query results:
Result Arrays
*************
-result()
-========
+**result()**
This method returns the query result as an array of **objects**, or
**an empty array** on failure. Typically you'll use this in a foreach
@@ -28,7 +27,7 @@ loop, like this::
echo $row->body;
}
-The above method is an alias of result_object().
+The above method is an alias of ``result_object()``.
If you run queries that might **not** produce a result, you are
encouraged to test the result first::
@@ -54,12 +53,11 @@ instantiate for each result object (note: this class must be loaded)
foreach ($query->result('User') as $user)
{
- echo $user->name; // call attributes
- echo $user->reverse_name(); // or methods defined on the 'User' class
+ echo $user->name; // access attributes
+ echo $user->reverse_name(); // or methods defined on the 'User' class
}
-result_array()
-===============
+**result_array()**
This method returns the query result as a pure array, or an empty
array when no result is produced. Typically you'll use this in a foreach
@@ -78,8 +76,7 @@ loop, like this::
Result Rows
***********
-row()
-=====
+**row()**
This method returns a single result row. If your query has more than
one row, it returns only the first row. The result is returned as an
@@ -107,13 +104,12 @@ to instantiate the row with::
$query = $this->db->query("SELECT * FROM users LIMIT 1;");
$query->row(0, 'User');
- echo $row->name; // call attributes
+ echo $row->name; // access attributes
echo $row->reverse_name(); // or methods defined on the 'User' class
-row_array()
-===========
+**row_array()**
-Identical to the above row() method, except it returns an array.
+Identical to the above ``row()`` method, except it returns an array.
Example::
$query = $this->db->query("YOUR QUERY");
@@ -148,11 +144,11 @@ parameter:
| **$row = $query->next_row('array')**
| **$row = $query->previous_row('array')**
-.. note:: all the methods above will load the whole result into memory
- (prefetching) use unbuffered_row() for processing large result sets.
+.. note:: All the methods above will load the whole result into memory
+ (prefetching). Use ``unbuffered_row()`` for processing large
+ result sets.
-unbuffered_row()
-================
+**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,
@@ -180,7 +176,7 @@ the returned value's type::
Result Helper Methods
*********************
-**$query->num_rows()**
+**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::
@@ -189,13 +185,12 @@ is the variable that the query result object is assigned to::
echo $query->num_rows();
-.. note::
- Not all database drivers have a native way of getting the total
+.. note:: Not all database drivers have a native way of getting the total
number of rows for a result set. When this is the case, all of
- the data is prefetched and count() is manually called on the
- resulting array in order to achieve the same methodality.
+ the data is prefetched and ``count()`` is manually called on the
+ resulting array in order to achieve the same result.
-**$query->num_fields()**
+**num_fields()**
The number of FIELDS (columns) returned by the query. Make sure to call
the method using your query result object::
@@ -204,13 +199,14 @@ the method using your query result object::
echo $query->num_fields();
-**$query->free_result()**
+**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
script execution. However, if you are running a lot of queries in a
particular script you might want to free the result after each query
-result has been generated in order to cut down on memory consumptions.
+result has been generated in order to cut down on memory consumption.
+
Example::
$query = $this->db->query('SELECT title FROM my_table');
@@ -219,6 +215,7 @@ Example::
{
echo $row->title;
}
+
$query->free_result(); // The $query result object will no longer be available
$query2 = $this->db->query('SELECT name FROM some_table');
@@ -250,175 +247,188 @@ Class Reference
.. class:: CI_DB_result
- .. method:: custom_result_object($class_name)
-
- :param string $class_name: Class name for the results
- :returns: Array of objects of type $class_name
- :rtype: array of $class_name
+ .. method:: result([$type = 'object'])
- Return the query results as an array of the specified class.
+ :param string $type: Type of requested results - array, object, or class name
+ :returns: Array containing the fetched rows
+ :rtype: array
- .. method:: custom_row_object($n, $type)
+ A wrapper for the ``result_array()``, ``result_object()``
+ and ``custom_result_object()`` methods.
- :param int $n: Index of the results row to return
- :param string $class_name: Class name for the results
- :returns: Object of type $type
- :rtype: $type
+ Usage: see `Result Arrays`_.
- Return a specific row from the query results as an object of
- the specified class.
+ .. method:: result_array()
- .. method:: data_seek([$n = 0])
+ :returns: Array containing the fetched rows
+ :rtype: array
- :param int $n: Index of the results row to be returned next
- :returns: TRUE on success, FALSE otherwise
- :rtype: bool
+ Returns the query results as an array of rows, where each
+ row is itself an associative array.
- Moves the internal results row pointer to the desired offset.
- Usage: see `Result Helper Methods`_.
+ Usage: see `Result Arrays`_.
- .. method:: field_data()
+ .. method:: result_object()
- :returns: Array of objects containing field meta-data.
+ :returns: Array containing the fetched rows
:rtype: array
- Generates an array of objects containing field meta-data.
+ Returns the query results as an array of rows, where each
+ row is an object of type ``stdClass``.
- .. method:: first_row([$type = 'object'])
+ Usage: see `Result Arrays`_.
- :param string $type: Type of result requested - array, object, or class name
- :returns: First row of result set
- :rtype: mixed
+ .. method:: custom_result_object($class_name)
- Returns the "first" row, as an array, generic object, or
- object of a specific class
+ :param string $class_name: Class name for the resulting rows
+ :returns: Array containing the fetched rows
+ :rtype: array
- .. method:: free_result()
+ Returns the query results as an array of rows, where each
+ row is an instance of the specified class.
- :rtype: void
+ .. method:: row([$n = 0[, $type = 'object']])
- Free the result.
- Usage: see `Result Helper Methods`_.
+ :param int $n: Index of the query results row to be returned
+ :param string $type: Type of the requested result - array, object, or class name
+ :returns: The requested row or NULL if it doesn't exist
+ :rtype: mixed
- .. method:: last_row([$type = 'object'])
+ A wrapper for the ``row_array()``, ``row_object() and
+ ``custom_row_object()`` methods.
+
+ Usage: see `Result Rows`_.
- :param string $type: Type of result requested - array, object, or class name
- :returns: Last row of result set
+ .. method:: unbuffered_row([$type = 'object'])
+
+ :param string $type: Type of the requested result - array, object, or class name
+ :returns: Next row from the result set or NULL if it doesn't exist
:rtype: mixed
- Returns the "last" row, as an array, generic object, or
- object of a specific class
+ Fetches the next result row and returns it in the
+ requested form.
- .. method:: list_fields()
+ Usage: see `Result Rows`_.
- :returns: Array of column names
+ .. method:: row_array([$n = 0])
+
+ :param int $n: Index of the query results row to be returned
+ :returns: The requested row or NULL if it doesn't exist
:rtype: array
- Fetch Field Names
+ Returns the requested result row as an associative array.
- .. method:: next_row([$type = 'object'])
+ Usage: see `Result Rows`_.
- :param string $type: Type of result requested - array, object, or class name
- :returns: "Next" row of result set, NULL if there isn't one
- :rtype: mixed
+ .. method:: row_object([$n = 0])
- Returns the "next" row, as an array, generic object, or
- object of a specific class
+ :param int $n: Index of the query results row to be returned
+ :returns: The requested row or NULL if it doesn't exist
+ :rtype: stdClass
- .. method:: num_fields()
+ Returns the requested result row as an object of type
+ ``stdClass``.
- :returns: Number of fields in the result set
- :rtype: integer
+ Usage: see `Result Rows`_.
- Number of fields in the result set.
- Usage: see `Result Helper Methods`_.
+ .. method:: custom_row_object($n, $type)
- .. method:: num_rows()
+ :param int $n: Index of the results row to return
+ :param string $class_name: Class name for the resulting row
+ :returns: The requested row or NULL if it doesn't exist
+ :rtype: $type
- :returns: Number of rows in the result set
- :rtype: integer
+ Returns the requested result row as an instance of the
+ requested class.
- Number of rows in the result set.
- Usage: see `Result Helper Methods`_.
+ .. method:: data_seek([$n = 0])
- .. method:: previous_row([$type = 'object'])
+ :param int $n: Index of the results row to be returned next
+ :returns: TRUE on success, FALSE on failure
+ :rtype: bool
- :param string $type: Type of result requested - array, object, or class name
- :returns: "Previous" row of result set, NULL if there isn't one
- :rtype: mixed
+ Moves the internal results row pointer to the desired offset.
- Returns the "previous" row, as an array, generic object, or
- object of a specific class
+ Usage: see `Result Helper Methods`_.
- .. method:: result([$type = 'object'])
+ .. method:: set_row($key[, $value = NULL])
+
+ :param mixed $key: Column name or array of key/value pairs
+ :param mixed $value: Value to assign to the column, $key is a single field name
+ :rtype: void
+
+ Assigns a value to a particular column.
+
+ .. method:: next_row([$type = 'object'])
- :param string $type: Type of result requested - array, object, or class name
- :returns: Query results as the specified type
+ :param string $type: Type of the requested result - array, object, or class name
+ :returns: Next row of result set, or NULL if it doesn't exist
:rtype: mixed
- Query result. Acts as a wrapper function for the result_array,
- result_object and custom_result_object methods.
- Usage: see `Result Arrays`_.
+ Returns the next row from the result set.
- .. method:: result_array()
+ .. method:: previous_row([$type = 'object'])
- :returns: Query results as an associative array
- :rtype: array
+ :param string $type: Type of the requested result - array, object, or class name
+ :returns: Previous row of result set, or NULL if it doesn't exist
+ :rtype: mixed
- Returns the query results as an array of rows, where each
- row is itself an associative array.
- Usage: see `Result Arrays`_.
+ Returns the previous row from the result set.
- .. method:: result_object()
+ .. method:: first_row([$type = 'object'])
- :returns: Query results as an array of objects
- :rtype: array
+ :param string $type: Type of the requested result - array, object, or class name
+ :returns: First row of result set, or NULL if it doesn't exist
+ :rtype: mixed
- Returns the query results as an array of rows, where each
- row is an object
+ Returns the first row from the result set.
- .. method:: row([$n = 0[, $type = 'object']])
+ .. method:: last_row([$type = 'object'])
- :param integer $n: Index of the query results row to be returned
- :param string $type: Type of result requested - array, object, or class name
- :returns: Requested row of result set
+ :param string $type: Type of the requested result - array, object, or class name
+ :returns: Last row of result set, or NULL if it doesn't exist
:rtype: mixed
- Wrapper for result_row_array, result_row_object, and
- custom_row_object.
- Usage: see `Result Rows`_.
+ Returns the last row from the result set.
- .. method:: row_array([$n = 0])
+ .. method:: num_rows()
- :param integer $n: Index of the query results row to be returned
- :returns: Requested row of result set
- :rtype: array
+ :returns: Number of rows in the result set
+ :rtype: int
- Returns requested result row as an associative array.
- Usage: see `Result Rows`_.
+ Returns the number of rows in the result set.
- .. method:: row_object([$n = 0])
+ Usage: see `Result Helper Methods`_.
- :param integer $n: Index of the query results row to be returned
- :returns: Requested row of result set
- :rtype: object
+ .. method:: num_fields()
- Returns requested result row as an object
+ :returns: Number of fields in the result set
+ :rtype: int
- .. method:: set_row($key[, $value = NULL])
+ Returns the number of fields in the result set.
+
+ Usage: see `Result Helper Methods`_.
+
+ .. method:: field_data()
+
+ :returns: Array containing field meta-data
+ :rtype: array
+
+ Generates an array of ``stdClass`` objects containing
+ field meta-data.
+
+ .. method:: free_result()
- :param mixed $key: Column index or array of key/value pairs
- :param mixed $value: Result to assign to a column if the key is an index
:rtype: void
- Assigns an item into a particular column slot
+ Frees a result set.
- .. method:: unbuffered_row([$type = 'object'])
+ Usage: see `Result Helper Methods`_.
- :param string $type: Type of result requested - array, object, or class name
- :returns: Requested row of result set
- :rtype: mixed
+ .. method:: list_fields()
+
+ :returns: Array of column names
+ :rtype: array
- Fetches the next result row and returns it in the requested
- form.
- Usage: see `Result Rows`_. \ No newline at end of file
+ Returns an array containing the field names in the
+ result set. \ No newline at end of file