diff options
Diffstat (limited to 'user_guide_src/source/database/results.rst')
| -rw-r--r-- | user_guide_src/source/database/results.rst | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst new file mode 100644 index 000000000..a85b89bef --- /dev/null +++ b/user_guide_src/source/database/results.rst @@ -0,0 +1,124 @@ +######################## +Generating Query Results +######################## + +There are several ways to generate query results: + +result() +======== + +This function returns the query result as an array of **objects**, or +**an empty array** on failure. Typically you'll use this in a foreach +loop, like this:: + + $query = $this->db->query("YOUR QUERY"); foreach ($query->result() as $row) { echo $row->title; echo $row->name; echo $row->body; } + +The above function is an alias of result_object(). + +If you run queries that might **not** produce a result, you are +encouraged to test the result first:: + + $query = $this->db->query("YOUR QUERY"); if ($query->num_rows() > 0) { foreach ($query->result() as $row) { echo $row->title; echo $row->name; echo $row->body; } } + +You can also pass a string to result() which represents a class to +instantiate for each result object (note: this class must be loaded) + +:: + + $query = $this->db->query("SELECT * FROM users;"); + + foreach ($query->result('User') as $user) + { + echo $user->name; // call attributes + echo $user->reverse_name(); // or methods defined on the 'User' class + } + +result_array() +=============== + +This function 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 +loop, like this:: + + $query = $this->db->query("YOUR QUERY"); foreach ($query->result_array() as $row) { echo $row['title']; echo $row['name']; echo $row['body']; } + +row() +===== + +This function 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 +**object**. Here's a usage example:: + + $query = $this->db->query("YOUR QUERY"); if ($query->num_rows() > 0) { $row = $query->row(); echo $row->title; echo $row->name; echo $row->body; } + +If you want a specific row returned you can submit the row number as a +digit in the first parameter:: + + $row = $query->row(5); + +You can also add a second String parameter, which is the name of a class +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->reverse_name(); // or methods defined on the 'User' class + +row_array() +============ + +Identical to the above row() function, except it returns an array. +Example:: + + $query = $this->db->query("YOUR QUERY"); if ($query->num_rows() > 0) { $row = $query->row_array(); echo $row['title']; echo $row['name']; echo $row['body']; } + +If you want a specific row returned you can submit the row number as a +digit in the first parameter:: + + $row = $query->row_array(5); + +In addition, you can walk forward/backwards/first/last through your +results using these variations: + +**$row = $query->first_row()** + **$row = $query->last_row()** + **$row = $query->next_row()** + **$row = $query->previous_row()** + +By default they return an object unless you put the word "array" in the +parameter: + +**$row = $query->first_row('array')** + **$row = $query->last_row('array')** + **$row = $query->next_row('array')** + **$row = $query->previous_row('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:: + + $query = $this->db->query('SELECT * FROM my_table'); echo $query->num_rows(); + +$query->num_fields() +===================== + +The number of FIELDS (columns) returned by the query. Make sure to call +the function using your query result object:: + + $query = $this->db->query('SELECT * FROM my_table'); 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 +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. +Example:: + + $query = $this->db->query('SELECT title FROM my_table'); foreach ($query->result() as $row) { echo $row->title; } $query->free_result(); // The $query result object will no longer be available $query2 = $this->db->query('SELECT name FROM some_table'); $row = $query2->row(); echo $row->name; $query2->free_result(); // The $query2 result object will no longer be available + |