Source for file PelEntryNumber.php

Documentation is available at PelEntryNumber.php

  1. <?php
  2.  
  3. /*  PEL: PHP Exif Library.  A library with support for reading and
  4.  *  writing all Exif headers in JPEG and TIFF images using PHP.
  5.  *
  6.  *  Copyright (C) 2004, 2005, 2006  Martin Geisler.
  7.  *
  8.  *  This program is free software; you can redistribute it and/or modify
  9.  *  it under the terms of the GNU General Public License as published by
  10.  *  the Free Software Foundation; either version 2 of the License, or
  11.  *  (at your option) any later version.
  12.  *
  13.  *  This program is distributed in the hope that it will be useful,
  14.  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15.  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16.  *  GNU General Public License for more details.
  17.  *
  18.  *  You should have received a copy of the GNU General Public License
  19.  *  along with this program in the file COPYING; if not, write to the
  20.  *  Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  21.  *  Boston, MA 02110-1301 USA
  22.  */
  23.  
  24. /* $Id: PelEntryNumber.php 419 2006-02-20 16:22:36Z mgeisler $ */
  25.  
  26.  
  27. /**
  28.  * Abstract class for numbers.
  29.  *
  30.  * @author Martin Geisler <mgeisler@users.sourceforge.net>
  31.  * @version $Revision: 419 $
  32.  * @date $Date: 2006-02-20 17:22:36 +0100 (Mon, 20 Feb 2006) $
  33.  * @license http://www.gnu.org/licenses/gpl.html GNU General Public
  34.  *  License (GPL)
  35.  * @package PEL
  36.  */
  37.  
  38. /**#@+ Required class definitions. */
  39. require_once('PelException.php');
  40. require_once('PelEntry.php');
  41. /**#@-*/
  42.  
  43.  
  44.  * Exception cast when numbers overflow.
  45.  *
  46.  * @author Martin Geisler <mgeisler@users.sourceforge.net>
  47.  * @package PEL
  48.  * @subpackage Exception
  49.  */
  50. class PelOverflowException extends PelException {
  51.   
  52.   /**
  53.    * Construct a new overflow exception.
  54.    *
  55.    * @param int the value that is out of range.
  56.    *
  57.    * @param int the minimum allowed value.
  58.    *
  59.    * @param int the maximum allowed value.
  60.    */
  61.   function __construct($v, $min, $max) {
  62.     parent::__construct('Value %.0f out of range [%.0f, %.0f]',
  63.                         $v, $min, $max);
  64.   }
  65. }
  66.  
  67.  
  68. /**
  69.  * Class for holding numbers.
  70.  *
  71.  * This class can hold numbers, with range checks.
  72.  *
  73.  * @author Martin Geisler <mgeisler@users.sourceforge.net>
  74.  * @package PEL
  75.  */
  76. abstract class PelEntryNumber extends PelEntry {
  77.  
  78.   /**
  79.    * The value held by this entry.
  80.    *
  81.    * @var array 
  82.    */
  83.   protected $value = array();
  84.  
  85.   /**
  86.    * The minimum allowed value.
  87.    *
  88.    * Any attempt to change the value below this variable will result
  89.    * in a {@link PelOverflowException} being thrown.
  90.    *
  91.    * @var int 
  92.    */
  93.   protected $min;
  94.  
  95.   /**
  96.    * The maximum allowed value.
  97.    *
  98.    * Any attempt to change the value over this variable will result in
  99.    * a {@link PelOverflowException} being thrown.
  100.    *
  101.    * @var int 
  102.    */
  103.   protected $max;
  104.   
  105.   /**
  106.    * The dimension of the number held.
  107.    *
  108.    * Normal numbers have a dimension of one, pairs have a dimension of
  109.    * two, etc.
  110.    *
  111.    * @var int 
  112.    */
  113.   protected $dimension = 1;
  114.  
  115.  
  116.   /**
  117.    * Change the value.
  118.    *
  119.    * This method can change both the number of components and the
  120.    * value of the components.  Range checks will be made on the new
  121.    * value, and a {@link PelOverflowException} will be thrown if the
  122.    * value is found to be outside the legal range.
  123.    *
  124.    * The method accept several number arguments.  The {@link getValue}
  125.    * method will always return an array except for when a single
  126.    * number is given here.
  127.    *
  128.    * @param int|array$value... the new value(s).  This can be zero or
  129.    *  more numbers, that is, either integers or arrays.  The input will
  130.    *  be checked to ensure that the numbers are within the valid range.
  131.    *  If not, then a {@link PelOverflowException} will be thrown.
  132.    *
  133.    * @see getValue
  134.    */
  135.   function setValue(/* $value... */) {
  136.     $value = func_get_args();
  137.     $this->setValueArray($value);
  138.   }
  139.  
  140.  
  141.   /**
  142.    * Change the value.
  143.    *
  144.    * This method can change both the number of components and the
  145.    * value of the components.  Range checks will be made on the new
  146.    * value, and a {@link PelOverflowException} will be thrown if the
  147.    * value is found to be outside the legal range.
  148.    *
  149.    * @param array the new values.  The array must contain the new
  150.    *  numbers.
  151.    *
  152.    * @see getValue
  153.    */
  154.   function setValueArray($value) {
  155.     foreach ($value as $v)
  156.       $this->validateNumber($v);
  157.     
  158.     $this->components = count($value);
  159.     $this->value      = $value;
  160.   }
  161.  
  162.  
  163.   /**
  164.    * Return the numeric value held.
  165.    *
  166.    * @return int|arraythis will either be a single number if there is
  167.    *  only one component, or an array of numbers otherwise.
  168.    */
  169.   function getValue() {
  170.     if ($this->components == 1)
  171.       return $this->value[0];
  172.     else
  173.       return $this->value;
  174.   }
  175.  
  176.  
  177.   /**
  178.    * Validate a number.
  179.    *
  180.    * This method will check that the number given is within the range
  181.    * given my {@link getMin()} and {@link getMax()}, inclusive.  If
  182.    * not, then a {@link PelOverflowException} is thrown.
  183.    *
  184.    * @param int|arraythe number in question.
  185.    *
  186.    * @return void nothing, but will throw a {@link }
  187.    *  PelOverflowException} if the number is found to be outside the
  188.    *  legal range and {@link Pel::$strict} is true.
  189.    */
  190.   function validateNumber($n) {
  191.     if ($this->dimension == 1) {
  192.       if ($n < $this->min || $n > $this->max)
  193.         Pel::maybeThrow(new PelOverflowException($n,
  194.                                                  $this->min,
  195.                                                  $this->max));
  196.     } else {
  197.       for ($i = 0; $i < $this->dimension; $i++)
  198.         if ($n[$i] < $this->min || $n[$i] > $this->max)
  199.           Pel::maybeThrow(new PelOverflowException($n[$i],
  200.                                                    $this->min,
  201.                                                    $this->max));
  202.     }
  203.   }
  204.  
  205.  
  206.   /**
  207.    * Add a number.
  208.    *
  209.    * This appends a number to the numbers already held by this entry,
  210.    * thereby increasing the number of components by one.
  211.    *
  212.    * @param int|arraythe number to be added.
  213.    */
  214.   function addNumber($n) {
  215.     $this->validateNumber($n);
  216.     $this->value[] = $n;
  217.     $this->components++;
  218.   }
  219.  
  220.  
  221.   /**
  222.    * Convert a number into bytes.
  223.    *
  224.    * The concrete subclasses will have to implement this method so
  225.    * that the numbers represented can be turned into bytes.
  226.    *
  227.    * The method will be called once for each number held by the entry.
  228.    *
  229.    * @param int the number that should be converted.
  230.    *
  231.    * @param PelByteOrder one of {@link PelConvert::LITTLE_ENDIAN} and
  232.    *  {@link PelConvert::BIG_ENDIAN}, specifying the target byte order.
  233.    *
  234.    * @return string bytes representing the number given.
  235.    */
  236.   abstract function numberToBytes($number, $order);
  237.  
  238.   
  239.   /**
  240.    * Turn this entry into bytes.
  241.    *
  242.    * @param PelByteOrder the desired byte order, which must be either
  243.    *  {@link PelConvert::LITTLE_ENDIAN} or {@link }
  244.    *  PelConvert::BIG_ENDIAN}.
  245.    *
  246.    * @return string bytes representing this entry.
  247.    */
  248.   function getBytes($o) {
  249.     $bytes = '';
  250.     for ($i = 0; $i < $this->components; $i++) {
  251.       if ($this->dimension == 1) {
  252.         $bytes .= $this->numberToBytes($this->value[$i], $o);
  253.       } else {
  254.         for ($j = 0; $j < $this->dimension; $j++) {
  255.           $bytes .= $this->numberToBytes($this->value[$i][$j], $o);
  256.         }
  257.       }
  258.     }
  259.     return $bytes;
  260.   }
  261.  
  262.  
  263.   /**
  264.    * Format a number.
  265.    *
  266.    * This method is called by {@link getText} to format numbers.
  267.    * Subclasses should override this method if they need more
  268.    * sophisticated behavior than the default, which is to just return
  269.    * the number as is.
  270.    *
  271.    * @param int the number which will be formatted.
  272.    *
  273.    * @param boolean it could be that there is both a verbose and a
  274.    *  brief formatting available, and this argument controls that.
  275.    *
  276.    * @return string the number formatted as a string suitable for
  277.    *  display.
  278.    */
  279.   function formatNumber($number, $brief = false) {
  280.     return $number;
  281.   }
  282.  
  283.  
  284.   /**
  285.    * Get the numeric value of this entry as text.
  286.    *
  287.    * @param boolean use brief output?  The numbers will be separated
  288.    *  by a single space if brief output is requested, otherwise a space
  289.    *  and a comma will be used.
  290.    *
  291.    * @return string the numbers(s) held by this entry.
  292.    */
  293.   function getText($brief = false) {
  294.     if ($this->components == 0)
  295.       return '';
  296.  
  297.     $str = $this->formatNumber($this->value[0]);
  298.     for ($i = 1; $i < $this->components; $i++) {
  299.       $str .= ($brief ? ' ' : ', ');
  300.       $str .= $this->formatNumber($this->value[$i]);
  301.     }
  302.  
  303.     return $str;
  304.   }
  305.  
  306. }
  307.  
  308. ?>

Documentation generated on Tue, 19 Dec 2006 01:08:20 +0100 by phpDocumentor 1.3.0 SourceForge.net Logo