more doc on db iterator

source/devapi/dbiterator.rst

@@ -9,7 +9,7 @@ Provide a simple request generator:
 * without having to write SQL
 * without having to quote table and field name
 * without having to take care of freeing resources
-* iteratable
+* iterable
 
 Basic usage
 ^^^^^^^^^^^
@@ -18,7 +18,12 @@ Basic usage
 
    <?php
    foreach ($DB->request(...) as $id => $row) {
-      //... work on 1 row ...
+      //... work on each row ...
+   }
+
+   $req = $DB->request(...);
+   if ($row = $req->next()) {
+     // ... work on a single row
    }
 
 Arguments
@@ -30,6 +35,12 @@ The ``request`` method takes two arguments:
 * `option(s)`: `array` of options
 
 
+Giving full SQL statement
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the only option is a full SQL statement, it will be used.
+This usage is deprecated, and should be avoid when possible.
+
 Without option
 ^^^^^^^^^^^^^^
 
@@ -103,6 +114,20 @@ Using the ``COUNT`` option:
    $DB->request('glpi_computers', ['COUNT' => 'cpt']);
    // => SELECT COUNT(*) AS cpt FROM `glpi_computers`
 
+Order
+^^^^^
+
+Using the ``ORDER`` option, with value a field or an array of field. Field name can also contains ASC or DESC suffix.
+
+.. code-block:: php
+
+   <?php
+   $DB->request('glpi_computers', ['ORDER' => 'name']);
+   // => SELECT * FROM `glpi_computers` ORDER BY `name`
+
+   $DB->request('glpi_computers', ['ORDER' => ['date_mod DESC', 'name ASC']]);
+   // => SELECT * FROM `glpi_computers` ORDER BY `date_mod` DESC, `name` ASC
+
 Request pager
 ^^^^^^^^^^^^^
 
@@ -117,7 +142,7 @@ Using the ``START`` and ``LIMIT`` options:
 Criteria
 ^^^^^^^^
 
-Other option are considered as an array of critiria (implicit logicical ``AND``)
+Other option are considered as an array of criteria (implicit logicical ``AND``)
 
 Simple criteria
 +++++++++++++++
@@ -148,3 +173,23 @@ Using the ``OR``, ``AND``, or ``NOT`` option with an array of criteria:
    $DB->request('glpi_computers', ['OR' => ['is_deleted' => 0,
                                             'name'       => 'foo']]);
    // => SELECT * FROM `glpi_computers` WHERE (`is_deleted` = 0 OR `name` = 'foo')"
+
+   $DB->request('glpi_computers', ['NOT' => ['id' => [1,2,7]]]);
+   // => SELECT * FROM `glpi_computers` WHERE NOT (`id` IN (1, 2, 7))
+
+Operators
++++++++++
+
+Default operator is =, but other operators can be used, by giving an array containing operator + value.
+
+.. code-block:: php
+
+   <?php
+   $DB->request('glpi_computers', ['date_mod' => ['>' , '2016-10-01']]);
+   // => SELECT * FROM `glpi_computers` WHERE `date_mod` > '2016-10-01'
+
+   $DB->request('glpi_computers', ['name' => ['LIKE' , 'pc00%']]);
+   // => SELECT * FROM `glpi_computers` WHERE `name` LIKE 'pc00%'
+
+Know operators are =, <, <=, >, >=, LIKE, REGEXP, NOT LIKE and NOT REGEX
+