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:
-->