repo_zf1Php7/documentation/manual/en/module_specs/Zend_Measure-Edit.xml

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

    <title>Manipulating Measurements</title>

    <para>
        Parsing and normalization of input, combined with output to localized notations makes data accessible to users
        in different locales. Many additional methods exist in <classname>Zend_Measure_*</classname> components to manipulate and
        work with this data, after it has been normalized.
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <link linkend="zend.measure.edit.convert"><code>Convert</code>
                </link>
            </para>
        </listitem>
        <listitem>
            <para>
                <link linkend="zend.measure.edit.add"><code>Add and subtract</code>
                </link>
            </para>
        </listitem>
        <listitem>
            <para>
                <link linkend="zend.measure.edit.equal"><code>Compare to boolean</code>
                </link>
            </para>
        </listitem>
        <listitem>
            <para>
                <link linkend="zend.measure.edit.compare"><code>Compare to greater/smaller</code>
                </link>
            </para>
        </listitem>
        <listitem>
            <para>
                <link linkend="zend.measure.edit.changevalue"><code>Manually change values</code>
                </link>
            </para>
        </listitem>
        <listitem>
            <para>
                <link linkend="zend.measure.edit.changetype"><code>Manually change types</code>
                </link>
            </para>
        </listitem>
    </itemizedlist>

    <sect2 id="zend.measure.edit.convert">

        <title>Convert</title>

        <para>
            Probably the most important feature is the conversion into different units of measurement. The conversion of
            a unit can be done any number of times using the method <code>convertTo()</code>. Units of measurement can
            only be converted to other units of the same type (class). Therefore, it is not possible to convert (e.g.) a
            length into a weight, which would might encourage poor programming practices and allow errors to propagate
            without exceptions.
        </para>

        <para>
            The <code>convertTo</code> method accepts an optional parameter. With this parameter you can define
            an precision for the returned output. The standard precision is '<code>2</code>'.
        </para>

        <example id="zend.measure.edit.convert.example-1">
            <title>Convert</title>
            <programlisting language="php"><![CDATA[
$locale = new Zend_Locale('de');
$mystring = "1.234.567,89";
$unit = new Zend_Measure_Weight($mystring,'POND', $locale);

print "Kilo:".$unit->convertTo('KILOGRAM');

// constants are considered "better practice" than strings
print "Ton:".$unit->convertTo(Zend_Measure_Weight::TON);

// define a precision for the output
print "Ton:".$unit->convertTo(Zend_Measure_Weight::TON, 3);
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.measure.edit.add">

        <title>Add and subtract</title>

        <para>
            Measurements can be added together using <code>add()</code> and subtracted using <code>sub()</code>. Each
            addition will create a new object for the result. The actual object will never be changed by the class. The
            new object will be of the same type as the originating object. Dynamic objects support a fluid style of
            programming, where complex sequences of operations can be nested without risk of side-effects altering the
            input objects.
        </para>

        <para>
            <example id="zend.measure.edit.add.example-1">
                <title>Adding units</title>
                <programlisting language="php"><![CDATA[
// Define objects
$unit = new Zend_Measure_Length(200, Zend_Measure_Length::CENTIMETER);
$unit2 = new Zend_Measure_Length(1, Zend_Measure_Length::METER);

// Add $unit2 to $unit
$sum = $unit->add($unit2);

echo $sum; // outputs "300 cm"
]]></programlisting>
            </example>
        </para>

        <note>
            <title>Automatic conversion</title>
            <para>
                Adding one object to another will automatically convert it to the correct unit. It is not necessary to
                call
                <link linkend="zend.measure.edit.convert"><code>convertTo()</code>
                </link>
                before adding different units.
            </para>
        </note>

        <para>
            <example id="zend.measure.edit.add.example-2">
                <title>Subtract</title>
                <para>
                    Subtraction of measurements works just like addition.
                </para>
                <programlisting language="php"><![CDATA[
// Define objects
$unit = new Zend_Measure_Length(200, Zend_Measure_Length::CENTIMETER);
$unit2 = new Zend_Measure_Length(1, Zend_Measure_Length::METER);

// Subtract $unit2 from $unit
$sum = $unit->sub($unit2);

echo $sum;
]]></programlisting>
            </example>
        </para>

    </sect2>

    <sect2 id="zend.measure.edit.equal">

        <title>Compare</title>

        <para>
            Measurements can also be compared, but without automatic unit conversion. Thus, <code>equals()</code>
            returns <constant>TRUE</constant>, only if both the value and the unit of measure are identical.
        </para>

        <para>
            <example id="zend.measure.edit.equal.example-1">
                <title>Different measurements</title>
                <programlisting language="php"><![CDATA[
// Define measurements
$unit = new Zend_Measure_Length(100, Zend_Measure_Length::CENTIMETER);
$unit2 = new Zend_Measure_Length(1, Zend_Measure_Length::METER);

if ($unit->equals($unit2)) {
    print "Both measurements are identical";
} else {
    print "These are different measurements";
}
]]></programlisting>
            </example>
            <example id="zend.measure.edit.equal.example-2">
                <title>Identical measurements</title>
                <programlisting language="php"><![CDATA[
// Define measurements
$unit = new Zend_Measure_Length(100, Zend_Measure_Length::CENTIMETER);
$unit2 = new Zend_Measure_Length(1, Zend_Measure_Length::METER);

$unit2->setType(Zend_Measure_Length::CENTIMETER);

if ($unit->equals($unit2)) {
    print "Both measurements are identical";
} else {
    print "These are different measurements";
}
]]></programlisting>
            </example>
        </para>

    </sect2>

    <sect2 id="zend.measure.edit.compare">

        <title>Compare</title>

        <para>
            To determine if a measurement is less than or greater than another, use <code>compare()</code>, which
            returns 0, -1 or 1 depending on the difference between the two objects. Identical measurements will return
            0. Lesser ones will return a negative, greater ones a positive value.
        </para>

        <para>
            <example id="zend.measure.edit.compare.example-1">
                <title>Difference</title>
                <programlisting language="php"><![CDATA[
$unit = new Zend_Measure_Length(100, Zend_Measure_Length::CENTIMETER);
$unit2 = new Zend_Measure_Length(1, Zend_Measure_Length::METER);
$unit3 = new Zend_Measure_Length(1.2, Zend_Measure_Length::METER);

print "Equal:".$unit2->compare($unit);
print "Lesser:".$unit2->compare($unit3);
print "Greater:".$unit3->compare($unit2);
]]></programlisting>
            </example>
        </para>

    </sect2>

    <sect2 id="zend.measure.edit.changevalue">

        <title>Manually change values</title>

        <para>
            To change the value of a measurement explicitly, use <code>setValue()</code>. to overwrite the current
            value. The parameters are the same as the constructor.
        </para>

        <para>
            <example id="zend.measure.edit.changevalue.example-1">
                <title>Changing a value</title>
                <programlisting language="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
$unit = new Zend_Measure_Length(1,Zend_Measure_Length::METER);

$unit->setValue(1.2);
echo $unit;

$unit->setValue(1.2, Zend_Measure_Length::KILOMETER);
echo $unit;

$unit->setValue("1.234,56", Zend_Measure_Length::MILLIMETER,$locale);
echo $unit;
]]></programlisting>
            </example>
        </para>

    </sect2>

    <sect2 id="zend.measure.edit.changetype">

        <title>Manually change types</title>

        <para>
            To change the type of a measurement without altering its value use <code>setType()</code>.
        </para>

        <example id="zend.measure.edit.changetype.example-1">
            <title>Changing the type</title>
            <programlisting language="php"><![CDATA[
$unit = new Zend_Measure_Length(1,Zend_Measure_Length::METER);
echo $unit; // outputs "1 m"

$unit->setType(Zend_Measure_Length::KILOMETER);
echo $unit; // outputs "1000 km"
]]></programlisting>
        </example>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->