Improve units fluent interface

Author: olvlvl

MIGRATION.md

@@ -62,9 +62,29 @@ None
 
 - Removed the `localized()` method on entities that don't naturally require access to the
   repository: `NumberFormatter` and `ListFormatter`. You can use
-  `$repository->locales['fr']->localize($formatter)` to get a localized formatter, the
+  `$repository->locales['fr']->localize($formatter)` to get a localized formatter, or the
   `number_formatter` and `list_formater` properties of the `Locale` object.
 
+- The fluent interface of units is now more on par with the rest of the API.
+
+	```php
+	<?php
+
+	echo $units->duration_hour(23);
+	echo $units->duration_hour(23, $units::LENGTH_SHORT);
+	echo $units->volume_liter->per_unit(12.345, $units->duration_hour);
+	echo $units->volume_liter->per_unit(12.345, $units->duration_hour, $units::LENGTH_SHORT);
+	```
+
+	```php
+	<?php
+
+	echo $units->duration_hour(23);
+	echo $units->duration_hour(23)->as_short;
+	echo $units->volume_liter(12.345)->per($units->duration_hour);
+	echo $units->volume_liter(12.345)->per($units->duration_hour)->as_short;
+	```
+
 ### Deprecated Features
 
 - The localized currency formatter no longer supports a `$symbols` parameter. If you need to

README.md

@@ -7,7 +7,7 @@
 
 The __CLDR__ package provides means to internationalize your application by leveraging the data and
 conventions defined by the [Unicode Common Locale Data Repository](http://cldr.unicode.org/) (CLDR).
-It provides many useful locale information and data (such as locale names for territories,
+It offers many helpful locale information and data (such as locale names for territories,
 languages, days…) as well as formatters for numbers, currencies, dates and times, units, sequences,
 lists…
 
@@ -62,19 +62,19 @@ echo $fr_datetime->as_short;                        // 04/11/2013 20:21
 
 # You can format units
 $units = $repository->locales['en']->units;
-$units->duration_hour->name;                        // hours
-$units->duration_hour->short_name;                  // h
-$units->duration_hour(1);                           // 1 hour
-$units->duration_hour(23);                          // 23 hours
-$units->duration_hour(23, $units::LENGTH_SHORT);    // 23 hr
-$units->duration_hour(23, $units::LENGTH_NARROW);   // 23h
+echo $units->duration_hour->name;                   // hours
+echo $units->duration_hour->short_name;             // h
+echo $units->duration_hour(1);                      // 1 hour
+echo $units->duration_hour(23);                     // 23 hours
+echo $units->duration_hour(23)->as_short;           // 23 hr
+echo $units->duration_hour(23)->as_narrow;          // 23h
 
 # You can format a unit per another unit
-$units->volume_liter->per_unit(12.345, $units->duration_hour);
+echo $units->volume_liter(12.345)->per($units->duration_hour);
 // 12.345 liters per hour
-$units->volume_liter->per_unit(12.345, $units->duration_hour, $units::LENGTH_SHORT);
+echo $units->volume_liter(12.345)->per($units->duration_hour)->as_short;
 // 12.345 L/h
-$units->volume_liter->per_unit(12.345, $units->duration_hour, $units::LENGTH_NARROW);
+echo $units->volume_liter(12.345)->per($units->duration_hour)->as_narrow;
 // 12.345L/h
 
 # You can format sequences of units
@@ -694,15 +694,15 @@ units:
 /* @var $repository \ICanBoogie\CLDR\Repository */
 
 $units = $repository->locales['en']->units;
-$units->duration_hour->name;                      // hours
-$units->duration_hour->short_name;                // h
-$units->duration_hour(1);                         // 1 hour
-$units->duration_hour(23);                        // 23 hours
-$units->duration_hour(23, $units::LENGTH_SHORT);  // 23 hr
-$units->duration_hour(23, $units::LENGTH_NARROW); // 23h
+echo $units->duration_hour->name;                   // hours
+echo $units->duration_hour->short_name;             // h
+echo $units->duration_hour(1);                      // 1 hour
+echo $units->duration_hour(23);                     // 23 hours
+echo $units->duration_hour(23)->as_short;           // 23 hr
+echo $units->duration_hour(23)->as_narrow;          // 23h
 ```
 
-[Many units are available](http://unicode.org/reports/tr35/tr35-general.html#Unit_Elements).
+[Many units are available](https://www.unicode.org/reports/tr35/tr35-57/tr35-general.html#Unit_Elements).
 
 ### Per unit
 
@@ -716,14 +716,13 @@ be used in preference.
 /* @var $repository \ICanBoogie\CLDR\Repository */
 
 $units = $repository->locales['en']->units;
-$units->volume_liter->per_unit(12.345, $units->duration_hour);
-// 12.345 liters per hour
-$units->volume_liter->per_unit(12.345, $units->duration_hour, $units::LENGTH_SHORT);
-// 12.345 Lph
-$units->volume_liter->per_unit(12.345, $units->duration_hour, $units::LENGTH_NARROW);
-// 12.345l/h
+echo $units->volume_liter(12.345)->per($units->duration_hour);              // 12.345 liters per hour
+echo $units->volume_liter(12.345)->per($units->duration_hour)->as_short;    // 12.345 Lph
+echo $units->volume_liter(12.345)->per($units->duration_hour)->as_narrow;   // 12.345l/h
 ```
 
+
+
 ### Units in composed sequence
 
 Units may be used in composed sequences, such as **5° 30m** for 5 degrees 30 minutes, or **3 ft, 2