Location: PHPKode > projects > Sierra-php PHP Application Framework > sierra/lib/sql/SRA_ResultSet.php
<?php
// {{{ Header
/*
 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
 | SIERRA : PHP Application Framework  http://code.google.com/p/sierra-php |
 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
 | Copyright 2005 Jason Read                                               |
 |                                                                         |
 | Licensed under the Apache License, Version 2.0 (the "License");         |
 | you may not use this file except in compliance with the License.        |
 | You may obtain a copy of the License at                                 |
 |                                                                         |
 |     http://www.apache.org/licenses/LICENSE-2.0                          |
 |                                                                         |
 | Unless required by applicable law or agreed to in writing, software     |
 | distributed under the License is distributed on an "AS IS" BASIS,       |
 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.|
 | See the License for the specific language governing permissions and     |
 | limitations under the License.                                          |
 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
 */
// }}}

// {{{ Constants
// }}}

// {{{ Includes
// }}}

// {{{ SRA_ResultSet

/**
 * Represents the results from performing a database query
 *
 * @author	Jason Read <hide@address.com>
 * @package sierra.sql
 */
class SRA_ResultSet {
    // {{{ Properties
    /**
     * the query that produced this result set without any limit or offset constraints
     * @type string
     * @access private
     */
    var $_baseQuery;
		
    /**
     * the SRA_Database that produced this result set
     * @type   SRA_Database
     * @access private
     */
    var $_db;
		
    /**
     * the limit applied to this query (if any)
     * @type   int
     * @access private
     */
    var $_limit;
    
    /**
     * the offset applied to this query (if any)
     * @type   int
     * @access private
     */
    var $_offset;
		
    /**
     * Holds the current position in the _records array.
     * @type   int
     * @access private
     */
    var $_position;

    /**
     * Holds the array of current records.
     * @type   string[]
     * @access private
     */
    var $_records;
		
		/**
		 * Stores the column names from the query
		 * @type string[]
		 * @access private
		 */
		var $_columnNames;
		
		/**
		 * the # of records to return by the count() method. if not specfied, 
		 * count($this->_records) will be returned
		 * @type int
		 * @access package
		 */
		var $_numRecords = FALSE;
		
    /**
     * the query that produced this result set
     * @type   string
     * @access private
     */
    var $_query;
		
    // }}}

    // {{{ SRA_ResultSet()
    /**
     * Constructor. Used to instantiate a new SRA_ResultSet object.
     *
		 * @param SRA_Database $db the SRA_Database instance that produced this result set
     * @param string $query the query that this object will represent. this 
     * 			parameter is used to provides associative row arrays in the next method
		 * @param string $baseQuery the query without any limit or offset parameters
     * @param array $records the records to set to the _records instance variable.
     * 			The default for this parameter is false and it is not required.
     * @access  public
     * @return  void
     */
    function SRA_ResultSet(& $db, $query, $baseQuery, $limit, $offset, $records=FALSE)
    {
				$this->_db =& $db;
				$this->_query = $query;
				$this->_baseQuery = $baseQuery;
				$this->_limit = $limit;
        $this->_offset = $offset;
        $this->_position = 0;

        if (FALSE !== $records)
        {
            $this->_records = $records;
        }
				$data = SRA_Database::parseQuery($query);
				$this->_columnNames = array_values($data['select']);
    }
    // }}}

    // {{{ add()
    /**
     * Add a record to the end of the record array.
     *
     * @param array record record to add.
     * @access  public
     * @return  void
     */
    function add($record)
    {
        $this->_records[] = $record;
    }
    // }}}
		
    // {{{ count()
    /**
     * Same as getCount
     *
     * @access  public
     * @return  int
     */
    function count()
    {
			return(count($this->_records));
    }
    // }}}
    
    // {{{ eof
    /**
     * returns TRUE if the record pointer is currently at the end of the result
     * set
     * @access  public
     * @return  boolean
     */
    function eof() {
      return $this->_position == $this->count();
    }
    // }}}

    // {{{ getCount()
    /**
     * Returns the # of records in this result set
     *
     * @access  public
     * @return  int
     */
    function getCount()
    {
			return(count($this->_records));
    }
    // }}}
    
    // {{{ getDelimitedResults
    /**
     * returns the results as a delimited string
     * @param string $delimiter the delimiter to user (default is a comma). if 
     * any of the values in the result set contains this delimiter, they will 
     * be enclosed with double quotes (with any embedded double quotes escaped)
     * @param boolean $includeHeader whether or not to include a header row 
     * containing the column names. default is FALSE
     * @param boolean $lineBreak the line break character(s). default is \n
     * @param string $finalLineBreak if you are using this method to 
     * construct a list such as "a, b, c, d" from a single column result set, 
     * and you wish the final value in that list to use a custom line break 
     * (such as ", and "), then this parameter may be used to specify that 
     * custom delimiter (where $delimiter is '' and $lineBreak is ', ')
     * @access public
     * @return string
     */
    function getDelimitedResults($delimiter = ',', $includeHeader=FALSE, $lineBreak="\n", $finalLineBreak='') {
      $delimited = '';
      $this->reset();
      $started = FALSE;
      while($row =& $this->next(TRUE)) {
        $delimited .= $started ? ($finalLineBreak && $this->eof() ? $finalLineBreak : $lineBreak) : '';
        $keys = array_keys($row);
        if (!$started && $includeHeader) {
          foreach($keys as $key) {
            $delimited .= $key != $keys[0] ? $delimiter : '';
            $delimited .= strpos($key, $delimiter) === FALSE ? $key : '"' . str_replace('"', '\"', $key) . '"';
          }
        }
        foreach($keys as $key) {
          $delimited .= $key != $keys[0] ? $delimiter : '';
          $delimited .= strpos($row[$key], $delimiter) === FALSE ? $row[$key] : '"' . str_replace('"', '\"', $row[$key]) . '"';
        }
        $started = TRUE;
      }
      return $delimited;
    }
    // }}}
		
    // {{{ getTotalCount()
    /**
     * Returns the total # of records in this result set. this is the total # of 
		 * records that would have been returned had not offset or limit been 
		 * applied
     *
     * @access  public
     * @return  int
     */
    function getTotalCount()
    {
			if ($this->_limit || $this->_offset) {
				if ($this->_numRecords === FALSE) {
          if ($this->getCount() == $this->_limit) {
            $this->_numRecords = SRA_Database::getRecordCount($this->_db, $this->_baseQuery);
          }
          else {
            $this->_numRecords = $this->getCount() + $this->_offset;
          }
				}
				return $this->_numRecords;
			}
			else {
				return $this->getCount();
			}
    }
    // }}}
	
    // {{{ isValid()
    /**
     * Static method that returns true if the object parameter references a
     * valid SRA_ResultSet object.
     *
     * @param object $object the object to validate.
     * @access  public
     * @return  boolean
     */
    function isValid($object)
    {
        return (is_object($object) && (!isset($object->err) || !SRA_Error::isError($object->err)) && strtolower(get_class($object)) == 'sra_resultset');
    }
    // }}}

    // {{{ next()
    /**
     * Get the next record field.
     *
     * @param boolean $associative optional parameter specifying whether the returned 
     * array should be associative based on the column name defined in the query. the 
     * default value for this parameter is FALSE, meaning the returned array will have 
     * a numerical index. In order for this functionality to work, the column names/aliases 
		 * must be explicitely defined in the query (i.e. * will not work)
     * @access  public
     * @return  array
     */
    function next($associative = FALSE)
    {
        // Check for next record.
        $r_cnt = count($this->_records);
        if ($this->_position < $r_cnt && $r_cnt > 0) {

            ++$this->_position;

            // note the -1.
            $record = $this->_records[$this->_position-1];
						if (!$associative) {
							return($record);
						}
						else {
							$newRecord = array();
							for($i=0; $i<count($record); $i++) {
								$newRecord[$this->_columnNames[$i]] = $record[$i];
							}
							return $newRecord;
						}
        }

        // No more records.
        return FALSE;

    }
    // }}}

    // {{{ reset()
    /**
     * Reset the SRA_ResultSet position to 0.
     *
     * @access  public
     * @return  void
     */
    function reset()
    {
        $this->_position = 0;
    }
    // }}}

    // {{{ seek()
    /**
     * Move the pointer to a certain record. Records start at 0.
     *
     * @param int $pos postion to goto.
     * @access  public
     * @return  void
     */
    function seek($pos)
    {
        $this->_position = $pos;
    }
    // }}}

}
// }}}

?>
Return current item: Sierra-php PHP Application Framework