documentation/manual/en/module_specs/Zend_Measure-Introduction.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.measure.introduction">
   4
   5     <title>Introduction</title>
   6
   7     <para>
   8         <classname>Zend_Measure_*</classname> classes provide a generic and easy way for working
   9         with measurements. Using <classname>Zend_Measure_*</classname> classes, you can convert
  10         measurements into different units of the same type. They can be added, subtracted and
  11         compared against each other. From a given input made in the user's native language, the unit
  12         of measurement can be automatically extracted. Numerous units of measurement are supported.
  13     </para>
  14
  15     <example id="zend.measure.introduction.example-1">
  16         <title>Converting measurements</title>
  17
  18         <para>
  19             The following introductory example shows automatic conversion of units of measurement.
  20             To convert a measurement, its value and its type have to be known. The value can be an
  21             integer, a float, or even a string containing a number. Conversions are only possible
  22             for units of the same type (mass, area, temperature, velocity, etc.), not between types.
  23         </para>
  24
  25         <programlisting language="php"><![CDATA[
  26 $locale = new Zend_Locale('en');
  27 $unit = new Zend_Measure_Length(100, Zend_Measure_Length::METER, $locale);
  28
  29 // Convert meters to yards
  30 echo $unit->convertTo(Zend_Measure_Length::YARD);
  31 ]]></programlisting>
  32     </example>
  33
  34     <para>
  35         <classname>Zend_Measure_*</classname> includes support for many different units of
  36         measurement. The units of measurement all have a unified notation:
  37         <classname>Zend_Measure_&lt;TYPE&gt;::NAME_OF_UNIT</classname>, where &lt;TYPE&gt;
  38         corresponds to a well-known physical or numerical property. . Every unit of measurement
  39         consists of a conversion factor and a display unit. A detailed list can be found in the
  40         chapter <link linkend="zend.measure.types"><code>Types of measurements</code></link>.
  41     </para>
  42
  43     <example id="zend.measure.introduction.example-2">
  44         <title>The meter measurement</title>
  45
  46         <para>
  47             The <code>meter</code> is used for measuring lengths, so its type constant can be found
  48             in the <code>Length</code> class. To refer to this unit of measurement, the notation
  49             <constant>Length::METER</constant> must be used. The display unit is <code>m</code>.
  50         </para>
  51
  52         <programlisting language="php"><![CDATA[
  53 echo Zend_Measure_Length::STANDARD;  // outputs 'Length::METER'
  54 echo Zend_Measure_Length::KILOMETER; // outputs 'Length::KILOMETER'
  55
  56 $unit = new Zend_Measure_Length(100,'METER');
  57 echo $unit;
  58 // outputs '100 m'
  59 ]]></programlisting>
  60     </example>
  61 </sect1>
  62 <!--
  63 vim:se ts=4 sw=4 et:
  64 -->