<?php
/*
 *  $Id: ResultSet.php,v 1.28 2006/01/17 19:44:38 hlellelid Exp $
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * This software consists of voluntary contributions made by many individuals
 * and is licensed under the LGPL. For more information please see
 * <http://creole.phpdb.org>.
 */

/**
 * This is the interface for classes the wrap db results.
 * 
 * The get*() methods in this interface will format values before returning them. Note
 * that if they will return null if the database returned NULL.  If the requested column does
 * not exist than an exception (SQLException) will be thrown.
 * 
 * <code>
 * $rs = $conn->executeQuery("SELECT MAX(stamp) FROM event", ResultSet::FETCHMODE_NUM);
 * $rs->next();
 * 
 * $max_stamp = $rs->getTimestamp(1, "d/m/Y H:i:s");
 * // $max_stamp will be date string or null if no MAX(stamp) was found
 * 
 * $max_stamp = $rs->getTimestamp("max(stamp)", "d/m/Y H:i:s");
 * // will THROW EXCEPTION, because the resultset was fetched using numeric indexing
 * // SQLException: Invalid resultset column: max(stamp)
 * </code>
 * 
 * This class implements SPL IteratorAggregate, so you may iterate over the database results
 * using foreach():
 * <code>
 * foreach($rs as $row) {
 *   print_r($row); // row is assoc array returned by getRow()
 * }
 * </code>
 * 
 * @author    Hans Lellelid <hans@xmpl.org>
 * @version   $Revision: 1.28 $
 * @package   creole
 */
interface ResultSet extends IteratorAggregate {
        
    /**
     * Index result set by field name.
     */
    const FETCHMODE_ASSOC = 1;

    /**
     * Index result set numerically.
     */
    const FETCHMODE_NUM = 2;
    
    /**
     * Get the PHP native resource for the result.
     * Arguably this should not be part of the interface: i.e. every driver should implement
     * it if they have a result resource, but conceivably drivers could be created that do
     * not.  For now every single driver does have a "dblink" resource property, and other
     * classes (e.g. ResultSet) need this info in order to get correct native errors.  We'll
     * leave it in for now, as it helps with driver development, with the caveat that it 
     * could be removed from the interface at a later point.
     * @return resource Query result or NULL if not not applicable.
     */
    public function getResource();
        
    /**
     * Sets the fetchmode used to retrieve results.
     * Changing fetchmodes mid-result retrieval is supported (haven't encountered any drivers 
     * that don't support that yet).
     * @param int $mode ResultSet::FETCHMODE_NUM or  ResultSet::FETCHMODE_ASSOC (default).
     * @return void
     */
    public function setFetchmode($mode);
    
    /**
     * Gets the fetchmode used to retrieve results.
     * @return int ResultSet::FETCHMODE_NUM or ResultSet::FETCHMODE_ASSOC (default).
     */
    public function getFetchmode();       
    
    /**
     * Whether assoc result keys get converted to lowercase for compatibility.
     * 
     * This defaults to FALSE unless Creole::COMPAT_ASSOC_LOWER flag has been passed to connection.
     * This property is read-only since it must be set when connection is created.  The
     * reason for this behavior is some drivers (e.g. SQLite) do the case conversions internally
     * based on a PHP ini value; it would not be possible to change the behavior from the ResultSet
     * (since query has already been executed).
	 * 
     * @return boolean
     */
    public function isLowerAssocCase();
        
    /**
     * Moves the internal cursor to the next position and fetches the row at that position.
     * 
     * @return boolean <tt>true</tt> if success, <tt>false</tt> if no next record.
     * @throws SQLException on any driver-level errors.
     */
    public function next();

    /**
     * Moves the internal cursor to the previous position and fetches the
     * row at that position.
     * 
     * @return boolean <tt>true</tt> if success, <tt>false</tt> if no previous record.
     * @throws SQLException - if unable to move to previous position
     *                      - if ResultSet doesn't support reverse scrolling
     */
    public function previous();

    /**
     * Moves the cursor a relative number of rows, either positive or negative and fetches
     * the row at that position.
     * 
     * Attempting to move beyond the first/last row in the result set positions the cursor before/after 
     * the first/last row and issues a Warning. Calling relative(0) is valid, but does not change the cursor 
     * position. 
     * 
     * @param integer $offset
     * @return boolean <tt>true</tt> if cursor is on a row, <tt>false</tt> otherwise.
     * @throws SQLException - if unable to move to relative position
     *                      - if rel pos is negative & ResultSet doesn't support reverse scrolling
     */
    public function relative($offset);


    /**
     * Moves the cursor to an absolute cursor position and fetches the row at that position.
     * 
     * Attempting to move beyond the first/last row in the result set positions the cursor before/after 
     * the first/last row and issues a Warning.
     * 
     * @param integer $pos cursor position, first position is 1.
     * @return boolean <tt>true</tt> if cursor is on a row, <tt>false</tt> otherwise.
     * @throws SQLException - if unable to move to absolute position
     *                      - if position is before current pos & ResultSet doesn't support reverse scrolling
     */
    public function absolute($pos);

    /**
     * Moves cursor position WITHOUT FETCHING ROW AT THAT POSITION.
     * 
     * Generally this method is for internal driver stuff (e.g. other methods like
     * absolute() or relative() might call this and then call next() to get the row).
     * This method is public to facilitate more advanced ResultSet scrolling tools
     * -- e.g. cleaner implimentation of ResultSetIterator.
     * 
     * Some drivers will emulate seek() and not allow reverse seek (Oracle).
     * 
     * Seek is 0-based, but seek() is only for moving to the space _before_ the record
     * that you want to read.  I.e. if you seek(0) and then call next() you will have the 
     * first row (i.e. same as calling first() or absolute(1)).
     * 
     * <strong>IMPORTANT:  You cannot rely on the return value of this method to know whether a given
     * record exists for reading.  In some cases seek() will correctly return <code>false</code> if
     * the position doesn't exist, but in other drivers the seek is not performed until the
     * record is fetched. You can check the return value of absolute() if you need to know
     * whether a specific rec position is valid.</strong>
     * 
     * @param int $rownum The cursor pos to seek to.
     * @return boolean true on success, false if unable to seek to specified record.
     * @throws SQLException if trying to seek backwards with a driver that doesn't
     *                      support reverse-scrolling
     */
    public function seek($rownum);    
    
    /**
     * Move cursor to beginning of recordset.
     * @return boolean <tt>true</tt> on success or <tt>false</tt> if not found.
     * @throws SQLException - if unable to move to first position
     *                      - if not at first pos & ResultSet doesn't support reverse scrolling
     */
    public function first();

    /**
     * Move cursor to end of recordset.
     * @return boolean <tt>true</tt> on success or <tt>false</tt> if not found.
     * @throws SQLException - if unable to move to last position
     *                      - if unable to get num rows
     */
    public function last();
    
    /**
     * Sets cursort to before first record. This does not actually seek(), but
     * simply sets cursor pos to 0.
     * This is useful for inserting a record before the first in the set, etc.
     * @return void
     */
    public function beforeFirst();


    /**
     * Sets cursort to after the last record. This does not actually seek(), but
     * simply sets the cursor pos  to last + 1.
     * This [will be] useful for inserting a record after the last in the set,
     * when/if Creole supports updateable ResultSets.
     * @return void
     */
    public function afterLast();


    /**
     * Checks whether cursor is after the last record.
     * @return boolean
     * @throws SQLException on any driver-level error.
     */
    public function isAfterLast();

    /**
     * Checks whether cursor is before the first record.
     * @return boolean
     * @throws SQLException on any driver-level error.
     */
    public function isBeforeFirst();

    /**
     * Returns the current cursor position.
     * Cursor positions start at 0, but as soon as first row is fetched
     * cursor position is 1. (so first row is 1)
     * @return int
     */
    public function getCursorPos();

    /**
     * Gets current fields (assoc array).
     * @return array
     */
    public function getRow();

    /**
     * Get the number of rows in a result set.
     * @return int the number of rows
     * @throws SQLException - if unable to get a rowcount.
     */
    public function getRecordCount();
            
    /**
     * Frees the resources allocated for this result set.
     * Also empties any internal field array so that any calls to
     * get() method on closed ResultSet will result in "Invalid column" SQLException.
     * @return void
     */
    public function close();
    
    /**
     * A generic get method returns unformatted (=string) value.
     * This returns the raw results from the database.  Usually this will be a string, but some drivers
     * also can return objects (lob descriptors, etc) in certain cases.
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used) (if ResultSet::FETCHMODE_NUM was used).
     * @return mixed Usually expect a string.
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function get($column);
    
    /**
     * Reads a column as an array.
     * The value of the column is unserialized & returned as an array.  The generic case of this function is 
     * very PHP-specific.  Other drivers (e.g. Postgres) will format values into their native array format.
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @return array value or null if database returned null.
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getArray($column);

    /**
     * Returns value translated to boolean.
     * Default is to map 0 => false, 1 => true, but some database drivers may override this behavior.
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @return boolean value or null if database returned null.
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getBoolean($column);
            
    /**
     * Returns Blob with contents of column value.
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @return Blob New Blob with data from column or null if database returned null.
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getBlob($column);

    /**
     * Returns Clob with contents of column value.
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @return Clob New Clob object with data from column or null if database returned null.
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getClob($column);

    /**
     * Return a formatted date.
     * 
     * The default format for dates returned is preferred (in your locale, as specified using setlocale()) 
     * format w/o time (i.e. strftime("%x", $val)).  Override this by specifying a format second parameter.  You
     * can also specify a date()-style formatter; if you do, make sure there are no "%" symbols in your format string.
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @param string $format Date formatter for use w/ strftime() or date() (it will choose based on examination of format string)
     *                          If format is NULL, then the integer unix timestamp will be returned (no formatting performed).
     * @return mixed  Formatted date, or integer unix timestamp (using 00:00:00 for time) if $format was null. 
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getDate($column, $format = '%x');   

    /**
     * Returns value cast as a float (in PHP this is same as double).
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @return float value or null if database returned null
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getFloat($column);

    /**
     * Returns value cast as integer.
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @return int value or null if database returned null
     * @see getInteger()
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getInt($column);      

    /**
     * Returns value cast as string.
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @return string value or null if database returned null
     * @see get()
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getString($column);
    
    /**
     * Return a formatted time.
     * 
     * The default format for times returned is preferred (in your locale, as specified using setlocale()) 
     * format w/o date (i.e. strftime("%X", $val)).  Override this by specifying a format second parameter.  You
     * can also specify a date()-style formatter; if you do, make sure there are no "%" symbols in your format string.
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @param string $format Date formatter for use w/ strftime() or date() (it will choose based on examination of format string)
     *                          If format is NULL, then the integer unix timestamp will be returned (no formatting performed).
     * @return mixed  Formatted time, or integer unix timestamp (using today's date) if $format was null. 
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getTime($column, $format = '%X');

    /**
     * Return a formatted timestamp.
     * 
     * The default format for timestamp is ISO standard YYYY-MM-DD HH:MM:SS (i.e. date('Y-m-d H:i:s', $val).
     * Override this by specifying a format second parameter.  You can also specify a strftime()-style formatter.
     * 
     * Hint: if you want to get the unix timestamp use the "U" formatter string.
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @param string $format Date formatter for use w/ strftime() or date() (it will choose based on examination of format string)
     *                          If format is NULL, then the integer unix timestamp will be returned (no formatting performed).
     * @return mixed Formatted timestamp, or integer unix timestamp (if $format was null)
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getTimestamp($column, $format = 'Y-m-d H:i:s');
    
}