Unicorn Documentation Release 1.0.0
Total Page：16
File Type：pdf, Size：1020Kb
unicorn Documentation Release 1.0.0 Philipp Bräutigam, Steffen Brand February 23, 2017 Contents 1 User Guide 3 1.1 Requirements...............................................3 1.2 Installation................................................3 1.3 ConvertibleValue and Unit........................................3 1.3.1 Unit...............................................3 1.3.2 ConvertibleValue........................................4 1.4 Converters................................................4 1.4.1 Converting...........................................4 1.4.2 Mathematical operations....................................5 1.4.3 Nesting.............................................5 1.4.4 Adding your own units.....................................6 1.4.5 Extending converters......................................6 1.4.6 Converter Registry.......................................8 1.4.7 Converter Implementations...................................9 1.5 Contribute................................................ 14 1.6 License.................................................. 15 i ii unicorn Documentation, Release 1.0.0 A framework agnostic library to convert between several units. Contents 1 unicorn Documentation, Release 1.0.0 2 Contents CHAPTER 1 User Guide Requirements • PHP 7.0 or higher • BCMath extension installed and enabled Installation The recommended way to install Unicorn is using Composer. Run the following command in your project directory: composer require xynnn/unicorn This requires you to have Composer installed globally, as explained in the installation chapter of the Composer docu- mentation. ConvertibleValue and Unit This section will provide you general information on Unit and how to use the ConvertibleValue, which is unicorns general data transfer object. Unit It consists of three properties: • name: the full name of the unit, f.e. centimeter • abbreviation: the abbreviation of the unit, f.e cm • factor: the factor to normalize this unit to the converters base unit It is important to understand how the factor is used in the internal process. Especially, if you want to add your own units to a converter. The factor is used to normalize a value or convert a value. Let’s say you want to normalize 1 kilometer to meter, as meter is the base unit of the LengthConverter. The 1 meter is 0.001 kilometer, so the factor of the unit kilometer is 0.001. This example is taken directly from the LengthConverter constructor, where the Unit kilometer is already set up. 3 unicorn Documentation, Release 1.0.0 <?php new Unit('kilometer', 'km', '0.001'); All converters already provide a number of units ready to use as static variables. Have a look at the corresponding converters documentation to see which units are already provided. <?php $converter= new LengthConverter(); $converter::$kilometer; // the unit "meter" already set up and ready to use ConvertibleValue A ConvertibleValue is the general data transfer object of Unicorn. Before you start converting or performing mathematical operations, you have to wrap your data in a ConvertibleValue. It consists of two properties: • value: the actual value • unit: the unit in which the value is represented If you want to represent 1000 meters as a ConvertibleValue, it will look like this: <?php $converter= new LengthConverter(); new ConvertibleValue('1000', $converter::$meter); The value is supposed to be a string representation, since it allows endless decimals, while float is limited to 14 decimals. Since php loves type juggling and is able to cast almost anything to string, you might use int or float as well. <?php $converter= new LengthConverter(); new ConvertibleValue(1000.12345678901234, $converter::$meter); Converters This section will provide you general information on how to use converters. Converting To convert a ConvertibleValue to another Unit, you have to call the convert method. The method works as follows: convert X of Unit Y to Unit Z. The convert method returns a ConvertibleValue, that you can use for further operations. Let’s have a look at the convert methods signature: <?php /** * @param ConvertibleValue $from * @param Unit $to * @return ConvertibleValue */ public function convert(ConvertibleValue $from, Unit $to): ConvertibleValue; Here is a quick example that shows how to convert 110 centimeters to meters: 4 Chapter 1. User Guide unicorn Documentation, Release 1.0.0 <?php $converter= new LengthConverter(); $result= $converter->convert( new ConvertibleValue('110', $converter::$centimeter), $converter::$meter); $result->getValue(); // '1.10...' with 999 decimals $result->getFloatValue(); // 1.1 $result->getUnit()->getAbbreviation(); // 'm' $result->getUnit()->getName(); // 'meter' Mathematical operations Most converters extend the AbstractMathematicalConverter, which provides some basic mathematical op- erations. These are examples for adding and subtracting values, even if they are provided in different units. Mathe- matical operations keep the Unit of the first ConvertibleValue. <?php $converter= new LengthConverter(); // addition $resultAdd= $converter->add( new ConvertibleValue('1', $converter::$meter), new ConvertibleValue('200', $converter::$centimeter) ); $resultAdd->getValue(); // '3.0' with 999 decimals $resultAdd->getFloatValue(); // 3 $resultAdd->getUnit()->getAbbreviation(); // 'm' $resultAdd->getUnit()->getName(); // 'meter' // subtraction $resultSub= $converter->sub( new ConvertibleValue('500', $converter::$centimeter), new ConvertibleValue('3', $converter::$meter) ); $resultSub->getValue(); // '800.0' with 999 decimals $resultSub->getFloatValue(); // 800 $resultSub->getUnit()->getAbbreviation(); // 'cm' $resultSub->getUnit()->getName(); // 'centimeter' Nesting Feel free to nest mathematical operations and conversions as you like, as they all work on ConvertibleValue, which is the return type of all operations. <?php $converter= new LengthConverter(); try { $result= $converter->convert( $converter->add( $converter->add( new ConvertibleValue('10000', $converter::$nanometer), new ConvertibleValue('10', $converter::$micrometer) 1.4. Converters 5 unicorn Documentation, Release 1.0.0 ), new ConvertibleValue('30000', $converter::$nanometer) ), $converter::$micrometer ); } catch (UnsupportedUnitException $e){ // Unit might not be present in the converters units array } catch (InvalidArgumentException $e){ // Something is wrong with the provided ConvertibleValue or Unit } Adding your own units All converters already provide a lot of units that you can use for conversions. However, if you are missing a Unit, you can add it to the converter and start using it. To add a Unit to the converter, just use the addUnit or setUnits method. Make sure to read about Unit_, before you start adding your own units. <?php $converter= new LengthConverter(); $myUnit= new Unit('myUnit', 'mu', '5'); $converter->addUnit($myUnit); try { $result= $converter->convert( new ConvertibleValue('1', $converter::$meter), $myUnit); $result->getValue(); // '5.0' with 999 decimals $result->getFloatValue(); // 5 $result->getUnit()->getAbbreviation(); // 'mu' $result->getUnit()->getName(); // 'myUnit' } catch (UnsupportedUnitException $e){ // Unit might not be present in the converters units array } catch (InvalidArgumentException $e){ // Something is wrong with the provided ConvertibleValue or Unit } Note: Not all converters are factor-based converters. Some converters, like the TemperatureConverter, convert based on formulas, so they don’t provide a addUnit oder setUnits method. If you want to add your own units, you need to extend the converter. See Extending converters for further information. Extending converters Not all converters are factor-based converters. Some converters, like the TemperatureConverter, convert based on formulas, so they don’t provide a addUnit oder setUnits method. If you want to add your own units, you need to extend the converter. This example shows you how to extend the TemperatureConverter and how you add your own unit myUnit. The steps are: • Extend the TemperatureConverter • Add your own Unit as static member variable myUnit • Call the parent constructor and afterwards initialize your own unit myUnit and add it to the units array. • Override the getName method and return your own name mytemperature 6 Chapter 1. User Guide unicorn Documentation, Release 1.0.0 • Override the normalize method and add a case for your own unit myUnit • Override the convertTo method and add a case for your own unit myUnit <?php namespace Xynnn\Unicorn\Converter; use Xynnn\Unicorn\Model\Unit; use Xynnn\Unicorn\Model\ConvertibleValue; class MyOwnTemperatureConverter extends TemperatureConverter { /** * @var Unit $myUnit Static instance for conversions */ public static $myUnit; /** * LengthConverter constructor. */ public function __construct() { parent::__construct(); $this->units[]= self::$myUnit= new Unit('MyUnit ', 'mu'); } /** * @return string Name of the converter */ public function getName(): string { return 'unicorn.converter.mytemperature'; } /** * @param ConvertibleValue $cv The Convertible to be normalized */ protected function normalize(ConvertibleValue $cv) { switch ($cv->getUnit()) { case self::$fahrenheit: $value= bcdiv(bcmul(bcsub($cv->getValue(), '32', self::MAX_DECIMALS), '5', self::MAX_DECIMALS), '9', self::MAX_DECIMALS); break; case self::$kelvin: $value= bcsub($cv->getValue(), '273.15', self::MAX_DECIMALS); break; case self::$myUnit: $value=1 * 1; // add your own formula break; default: $value= $cv->getValue(); } 1.4. Converters 7 unicorn Documentation, Release 1.0.0 $cv->setValue($value);