1<?php
2namespace PhpUnitsOfMeasure;
3
4/**
5 * Classes that implement this interface represent
6 * units of measure of physical quantities.  In addition
7 * to handling their names and various aliases, these
8 * objects are capable of converting values to and
9 * from an externally-agreed-upon native unit of measure.
10 *
11 * The native unit of measure can be any arbitrary
12 * unit compatible with the physical quantity to which
13 * this unit of measure belongs, however all the units of measure
14 * for a particular physical quantity must agree on the same
15 * native unit.
16 *
17 * For instance, all units of measure for Length must agree
18 * that the meter is the native unit to and from which all values are
19 * converted.
20 */
21interface UnitOfMeasureInterface
22{
23    /**
24     * Get the canonical name of this unit of measure.
25     *
26     * @return string The canonical name of this unit of measure.
27     */
28    public function getName();
29
30    /**
31     * Add a new alias for this unit of measure
32     *
33     * @param string $alias The new alias
34     *
35     * @throws \PhpUnitsOfMeasure\Exception\NonStringUnitName If The alias name is not a string.
36     */
37    public function addAlias($alias);
38
39    /**
40     * Get the list of alternate names for this unit
41     *
42     * @return string[] The collection of aliases
43     */
44    public function getAliases();
45
46    /**
47     * Is the given unit an alias of this unit of measure?
48     *
49     * @param  string $unit A string representation of a potential alias of this unit of measure
50     *
51     * @throws \PhpUnitsOfMeasure\Exception\NonStringUnitName If The unit name is not a string.
52     *
53     * @return boolean
54     */
55    public function isAliasOf($unit);
56
57    /**
58     * Convert the given value from the native unit of measure to
59     * this unit of measure.
60     *
61     * The native unit of measure can be anything, but all the
62     * units of measure for a given physical quantity must agree
63     * on what that unit is.
64     *
65     * @param  float $value The quantity to convert from this unit of measure
66     *
67     * @throws \PhpUnitsOfMeasure\Exception\NonNumericValue If The value is not numeric.
68     *
69     * @return float the new value in the native unit
70     */
71    public function convertValueFromNativeUnitOfMeasure($value);
72
73    /**
74     * Convert the given value from this unit of measure into the
75     * native unit of measure.
76     *
77     * The native unit of measure can be anything, but all the
78     * units of measure for a given physical quantity must agree
79     * on what that unit is.
80     *
81     * @param  float $value The quantity to convert from the native unit of measure
82     *
83     * @throws \PhpUnitsOfMeasure\Exception\NonNumericValue If The value is not numeric.
84     *
85     * @return float the new value in this unit of measure
86     */
87    public function convertValueToNativeUnitOfMeasure($value);
88}
89