Skip to content

docs: improve database/results.rst #5986

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 10, 2022
Merged

docs: improve database/results.rst #5986

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0c8437f
docs: decorate sample code with '``'
kenjis May 10, 2022
f1767b3
docs: make method names linkable
kenjis May 10, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 32 additions & 20 deletions user_guide_src/source/database/results.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ There are several ways to generate query results:
Result Arrays
*************

**getResult()**
getResult()
===========

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
Expand All @@ -36,7 +37,8 @@ instantiate for each result object

The above method is an alias of ``getCustomResultObject()``.

**getResultArray()**
getResultArray()
================

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
Expand All @@ -48,7 +50,8 @@ loop, like this:
Result Rows
***********

**getRow()**
getRow()
========

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
Expand All @@ -66,7 +69,8 @@ to instantiate the row with:

.. literalinclude:: results/007.php

**getRowArray()**
getRowArray()
=============

Identical to the above ``row()`` method, except it returns an array.
Example:
Expand All @@ -81,24 +85,25 @@ digit in the first parameter:
In addition, you can walk forward/backwards/first/last through your
results using these variations:

| **$row = $query->getFirstRow()**
| **$row = $query->getLastRow()**
| **$row = $query->getNextRow()**
| **$row = $query->getPreviousRow()**
| ``$row = $query->getFirstRow()``
| ``$row = $query->getLastRow()``
| ``$row = $query->getNextRow()``
| ``$row = $query->getPreviousRow()``

By default they return an object unless you put the word "array" in the
parameter:

| **$row = $query->getFirstRow('array')**
| **$row = $query->getLastRow('array')**
| **$row = $query->getNextRow('array')**
| **$row = $query->getPreviousRow('array')**
| ``$row = $query->getFirstRow('array')``
| ``$row = $query->getLastRow('array')``
| ``$row = $query->getNextRow('array')``
| ``$row = $query->getPreviousRow('array')``

.. note:: All the methods above will load the whole result into memory
(prefetching). Use ``getUnbufferedRow()`` for processing large
result sets.

**getUnbufferedRow()**
getUnbufferedRow()
==================

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,
Expand Down Expand Up @@ -145,7 +150,8 @@ In addition to the two methods listed below, the following methods also can
take a class name to return the results as: ``getFirstRow()``, ``getLastRow()``,
``getNextRow()``, and ``getPreviousRow()``.

**getCustomResultObject()**
getCustomResultObject()
=======================

Returns the entire result set as an array of instances of the class requested.
The only parameter is the name of the class to instantiate.
Expand All @@ -154,7 +160,8 @@ Example:

.. literalinclude:: results/014.php

**getCustomRowObject()**
getCustomRowObject()
====================

Returns a single row from your query results. The first parameter is the row
number of the results. The second parameter is the class name to instantiate.
Expand All @@ -173,21 +180,24 @@ Example:
Result Helper Methods
*********************

**getFieldCount()**
getFieldCount()
===============

The number of FIELDS (columns) returned by the query. Make sure to call
the method using your query result object:

.. literalinclude:: results/017.php

**getFieldNames()**
getFieldNames()
===============

Returns an array with the names of the FIELDS (columns) returned by the query.
Make sure to call the method using your query result object:

.. literalinclude:: results/018.php

**getNumRows()**
getNumRows()
============

The number of records returned by the query. Make sure to call
the method using your query result object:
Expand All @@ -198,7 +208,8 @@ the method using your query result object:
CodeIgniter will fetch and buffer the query result records internally and
return a count of the resulting record array, which can be inefficient.

**freeResult()**
freeResult()
============

It frees the memory associated with the result and deletes the result
resource ID. Normally PHP frees its memory automatically at the end of
Expand All @@ -210,7 +221,8 @@ Example:

.. literalinclude:: results/020.php

**dataSeek()**
dataSeek()
==========

This method sets the internal pointer for the next result row to be
fetched. It is only useful in combination with ``getUnbufferedRow()``.
Expand Down