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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.measure.introduction">

    <title>Introduction</title>

    <para>
        <classname>Zend_Measure_*</classname> classes provide a generic and easy way for working
        with measurements. Using <classname>Zend_Measure_*</classname> classes, you can convert
        measurements into different units of the same type. They can be added, subtracted and
        compared against each other. From a given input made in the user's native language, the unit
        of measurement can be automatically extracted. Numerous units of measurement are supported.
    </para>

    <example id="zend.measure.introduction.example-1">
        <title>Converting measurements</title>

        <para>
            The following introductory example shows automatic conversion of units of measurement.
            To convert a measurement, its value and its type have to be known. The value can be an
            integer, a float, or even a string containing a number. Conversions are only possible
            for units of the same type (mass, area, temperature, velocity, etc.), not between types.
        </para>

        <programlisting language="php"><![CDATA[
$locale = new Zend_Locale('en');
$unit = new Zend_Measure_Length(100, Zend_Measure_Length::METER, $locale);

// Convert meters to yards
echo $unit->convertTo(Zend_Measure_Length::YARD);
]]></programlisting>
    </example>

    <para>
        <classname>Zend_Measure_*</classname> includes support for many different units of
        measurement. The units of measurement all have a unified notation:
        <classname>Zend_Measure_&lt;TYPE&gt;::NAME_OF_UNIT</classname>, where &lt;TYPE&gt;
        corresponds to a well-known physical or numerical property. . Every unit of measurement
        consists of a conversion factor and a display unit. A detailed list can be found in the
        chapter <link linkend="zend.measure.types"><code>Types of measurements</code></link>.
    </para>

    <example id="zend.measure.introduction.example-2">
        <title>The meter measurement</title>

        <para>
            The <code>meter</code> is used for measuring lengths, so its type constant can be found
            in the <code>Length</code> class. To refer to this unit of measurement, the notation
            <constant>Length::METER</constant> must be used. The display unit is <code>m</code>.
        </para>

        <programlisting language="php"><![CDATA[
echo Zend_Measure_Length::STANDARD;  // outputs 'Length::METER'
echo Zend_Measure_Length::KILOMETER; // outputs 'Length::KILOMETER'

$unit = new Zend_Measure_Length(100,'METER');
echo $unit;
// outputs '100 m'
]]></programlisting>
    </example>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->