diff options
Diffstat (limited to 'user_guide_src')
| -rw-r--r-- | user_guide_src/source/database/results.rst | 276 |
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 |