documentation/manual/en/module_specs/Zend_Measure-Creation.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.measure.creation">
   4     <title>Creation of Measurements</title>
   5
   6     <para>
   7         When creating a measurement object, <classname>Zend_Measure_*</classname> methods expect the
   8         input/original measurement data value as the first parameter. This can be a
   9         <link linkend="zend.measure.creation.number"><code>numeric argument</code></link>, a
  10         <link linkend="zend.measure.creation.string"><type>String</type></link> without units, or a
  11         <link linkend="zend.measure.creation.localized"><code>localized string</code> with unit(s)
  12             specified.</link> The second parameter defines the type of the measurement. Both
  13         parameters are mandatory. The language may optionally be specified as the third parameter.
  14     </para>
  15
  16     <sect2 id="zend.measure.creation.number">
  17         <title>Creating measurements from integers and floats</title>
  18
  19         <para>
  20             In addition to integer data values, floating point types may be used, but
  21             <ulink url="http://www.php.net/float">"simple decimal fractions like 0.1 or 0.7 cannot
  22                 be converted into their internal binary counterparts without a little loss of
  23                 precision,"</ulink> sometimes giving surprising results. Also, do not compare two
  24             "float" type numbers for equality.
  25         </para>
  26
  27         <example id="zend.measure.creation.number.example-1">
  28             <title>Creation using integer and floating values</title>
  29
  30             <programlisting language="php"><![CDATA[
  31 $measurement = 1234.7;
  32 $unit = new Zend_Measure_Length((integer)$measurement,
  33                                 Zend_Measure_Length::STANDARD);
  34 echo $unit;
  35 // outputs '1234 m' (meters)
  36
  37 $unit = new Zend_Measure_Length($measurement, Zend_Measure_Length::STANDARD);
  38 echo $unit;
  39 // outputs '1234.7 m' (meters)
  40 ]]></programlisting>
  41         </example>
  42     </sect2>
  43
  44     <sect2 id="zend.measure.creation.string">
  45         <title>Creating measurements from strings</title>
  46
  47         <para>
  48             Many measurements received as input to Zend Framework applications can only be passed
  49             to <classname>Zend_Measure_*</classname> classes as strings, such as numbers written
  50             using <ulink url="http://en.wikipedia.org/wiki/Roman_numerals">roman numerals</ulink>
  51             or extremely large binary values that exceed the precision of <acronym>PHP</acronym>'s
  52             native integer and float types. Since integers can be denoted using strings, if there is
  53             any risk of losing precision due to limitations of <acronym>PHP</acronym>'s native
  54             integer and float types, using strings instead.
  55             <classname>Zend_Measure_Number</classname> uses the BCMath extension to support
  56             arbitrary precision, as shown in the example below, to avoid limitations in many
  57             <acronym>PHP</acronym> functions, such as <ulink
  58                 url="http://php.net/bin2dec"><methodname>bin2dec()</methodname></ulink>.
  59         </para>
  60
  61         <example id="zend.measure.creation.string.example-1">
  62             <title>Creation using strings</title>
  63
  64             <programlisting language="php"><![CDATA[
  65 $mystring = "10010100111010111010100001011011101010001";
  66 $unit = new Zend_Measure_Number($mystring, Zend_Measure_Number::BINARY);
  67
  68 echo $unit;
  69 ]]></programlisting>
  70         </example>
  71     </sect2>
  72
  73     <sect2 id="zend.measure.creation.localized">
  74         <title>Measurements from localized strings</title>
  75
  76         <para>
  77             When a string is entered in a localized notation, the correct interpretation can not be
  78             determined without knowing the intended locale. The division of decimal digits with "."
  79             and grouping of thousands with "," is common in the English language, but not so in
  80             other languages. For example, the English number "1,234.50" would be interpreted as
  81             meaning "1.2345" in German. To deal with such problems, the locale-aware
  82             <classname>Zend_Measure_*</classname> family of classes offer the possibility to specify
  83             a language or region to disambiguate the input data and properly interpret the intended
  84             semantic value.
  85         </para>
  86
  87         <example id="zend.measure.creation.localized.example-1">
  88             <title>Localized string</title>
  89
  90             <programlisting language="php"><![CDATA[
  91 $locale = new Zend_Locale('de');
  92 $mystring = "1,234.50";
  93 $unit = new Zend_Measure_Length($mystring,
  94                                 Zend_Measure_Length::STANDARD,
  95                                 $locale);
  96 echo $unit; // outputs "1.234 m"
  97
  98 $mystring = "1,234.50";
  99 $unit = new Zend_Measure_Length($mystring,
 100                                 Zend_Measure_Length::STANDARD,
 101                                 'en_US');
 102 echo $unit; // outputs "1234.50 m"
 103 ]]></programlisting>
 104         </example>
 105
 106         <para>
 107             Since Zend Framework 1.7.0 <classname>Zend_Measure</classname> does also support the
 108             usage of an application wide locale. You can simply set a
 109             <classname>Zend_Locale</classname> instance to the registry like shown below. With this
 110             notation you can forget about setting the locale manually with each instance when you
 111             want to use the same locale multiple times.
 112         </para>
 113
 114         <programlisting language="php"><![CDATA[
 115 // in your bootstrap file
 116 $locale = new Zend_Locale('de_AT');
 117 Zend_Registry::set('Zend_Locale', $locale);
 118
 119 // somewhere in your application
 120 $length = new Zend_Measure_Length(Zend_Measure_Length::METER();
 121 ]]></programlisting>
 122     </sect2>
 123 </sect1>
 124 <!--
 125 vim:se ts=4 sw=4 et:
 126 -->