# Manipulating Measurements

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

- Convert

- Add and subtract

- Compare to boolean

- Compare to greater/smaller

- Manually change values

- Manually change types

## Convert

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 `convertTo()`. 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.

The `convertTo()` method accepts an optional parameter. With this parameter you can define an precision for the returned output. The standard precision is '2'.

### Convert

    $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);

## Add and subtract

Measurements can be added together using `add()` and subtracted using `sub()`. The result will use 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.

### Adding units

    // 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"

### Automatic conversion

Adding one object to another will automatically convert it to the correct unit. It is not necessary to call `convertTo()` before adding different units.

### Subtract

Subtraction of measurements works just like addition.

    // 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;

## Compare

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

### Different measurements

    // 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";
    }

### Identical measurements

    // 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";
    }

## Compare

To determine if a measurement is less than or greater than another, use `compare()`, 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.

### Difference

    $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);

## Manually change values

To change the value of a measurement explicitly, use `setValue()`. to overwrite the current value. The parameters are the same as the constructor.

### Changing a value

    $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;

## Manually change types

To change the type of a measurement without altering its value use `setType()`.

### Changing the type

    $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"