Unicorn Documentation Release 1.0.0

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 documentation.

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

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.

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:

The value is supposed to be a string representation, since it allows endless decimals, while ﬂoat is limited to 14 decimals. Since php loves type juggling and is able to cast almost anything to string, you might use int or ﬂoat as well.

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:

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

$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 operations. These are examples for adding and subtracting values, even if they are provided in different units. Mathe- matical operations keep the Unit of the ﬁrst ConvertibleValue.

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

/** * @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); $cv->setUnit($this->getBaseUnit()); }

/** * @param ConvertibleValue $from The convertible to be converted * @param Unit $to Unit to which is to be converted */ protected function convertTo(ConvertibleValue $from, Unit $to) { switch ($to){

case self::$fahrenheit: $value= bcadd(bcdiv(bcmul($from->getValue(), '9', self::MAX_DECIMALS), '5', self::MAX_DECIMALS), '32', self::MAX_DECIMALS); break;

case self::$kelvin: $value= bcadd($from->getValue(), '273.15', self::MAX_DECIMALS); break;

case self::$myUnit: $value=1 * 1; // add your own formula break;

default: $value= $from->getValue();

}

$from->setValue($value); $from->setUnit($to); }

}

Note: If you’re using a factor-based converter, normally there is no reason to extend a converter. Better use the addUnit oder setUnits methods instead. See Adding your own units for further information.

Converter Registry

If you need to use more than one converter in your project, but you don’t want to inject every single converter, you can add a set of converters to the ConverterRegistry and inject the registry instead. The ConverterRegistry can be instantiated with an array of converters:

You can also add converters using the add method:

8 Chapter 1. User Guide unicorn Documentation, Release 1.0.0

add(new LengthConverter());

To get a converter instance from the ConverterRegistry, use the get method with the name of the converter:

try { $lengthConverter= $registry->get('unicorn.converter.length'); } catch (UnsupportedConverterException $e){ // converter might not be present }

Converter Implementations

LengthConverter

Use the LengthConverter to convert between different length units, f.e. from meters to miles.

Name

unicorn.converter.length

Base Unit

• meter

Features

• Conversion • Mathematical operations • Adding own units

1.4. Converters 9 unicorn Documentation, Release 1.0.0

Predeﬁned Units

Name Abbreviation Factor nanometer nm 1000000000 micrometer µm 1000000 millimeter mm 1000 centimeter cm 100 decimeter dm 10 meter m 1 kilometer km 0.001 inch in 1/0.0254 feet ft 1/0.3048 yard yd 1/0.9144 mile m 1/1609.344

CurrencyConverter

Use the CurrencyConverter to convert between different currencies, f.e. from EUR to USD.

Note: This converter loads the current exchange rates from the ECB via Webservice once you start converting or calculating. For more information check out https://github.com/steffenbrand/curr-curr

Name unicorn.converter.currency

Base Unit

• EUR

Features

• Conversion • Mathematical operations • Adding own units

Predeﬁned Units

Name Abbreviation Factor EUR C 1 USD $ dynamic JPY ¥ dynamic BGN dynamic CZK Kcˇ dynamic Continued on next page

10 Chapter 1. User Guide unicorn Documentation, Release 1.0.0

Table 1.1 – continued from previous page Name Abbreviation Factor DKK kr dynamic GBP £ dynamic HUF Ft dynamic PLN zł dynamic RON lei dynamic SEK kr dynamic CHF CHF dynamic NOK kr dynamic HRK kn dynamic RUB dynamic TRY dynamic AUD $ dynamic BRL R$ dynamic CAD $ dynamic CNY ¥ dynamic HKD $ dynamic IDR Rp dynamic ILS dynamic INR dynamic KRW dynamic MXN $ dynamic MYR RM dynamic NZD $ dynamic PHP dynamic SGD $ dynamic THB dynamic ZAR R dynamic

Note: Blank currency abbreviations do exist in the converter, but readthedocs is not able to parse them.

TemperatureConverter

Use the TemperatureConverter to convert between different temperature units, f.e. from Celsius to Kelvin.

Name unicorn.converter.temperature

Base Unit

• Celsius

Features

• Conversion

1.4. Converters 11 unicorn Documentation, Release 1.0.0

• Mathematical operations

Predeﬁned Units

Name Abbreviation Factor Celsius °C formula Fahrenheit °F formula Kelvin K formula

DataStorageConverter

Use the DataStorageConverter to convert between different temperature units, f.e. from Megabyte to Gigabyte.

Name unicorn.converter.datastorage

Base Unit

• Megabyte

Features

• Conversion • Mathematical operations • Adding own units

Predeﬁned Units

Name Abbreviation Factor Byte B 1000000 Kilobyte KB 1000 Megabyte MB 1 Gigabyte GB 0.001 Terabyte TB 0.000001 Petabyte PB 0.000000001 Exabyte EB 0.000000000001 Zettabyte ZB 0.000000000000001 Yottabyte YB 0.000000000000000001

12 Chapter 1. User Guide unicorn Documentation, Release 1.0.0

Name Abbreviation Factor Kibibyte KiB 976.5625 Mebibyte MiB KiB-Factor/1024 Gibibyte GiB MiB-Factor/1024 Tebibyte TiB GiB-Factor/1024 Pebibyte PiB TiB-Factor/1024 Exibyte EiB PiB-Factor/1024 Zebibyte ZiB EiB-Factor/1024 Yobibyte YiB ZiB-Factor/1024 Name Abbreviation Factor Bit bit 8000000 Kilobit Kbit 8000 Megabit Mbit 8 Gigabit Gbit 0.008 Terabit Tbit 0.000008 Petabit Pbit 0.000000008 Exabit Ebit 0.000000000008 Zettabit Zbit 0.000000000000008 Yottabit Ybit 0.000000000000000008 Name Abbreviation Factor Kibibit Kibit 7812.5 Mebibit Mibit Kibit-Factor/1024 Gibibit Gibit Mibit-Factor/1024 Tebibit Tibit Gibit-Factor/1024 Pebibit Pibit Tibit-Factor/1024 Exibit Eibit Pibit-Factor/1024 Zebibit Zibit Eibit-Factor/1024 Yobibit Yibit Zibit-Factor/1024

DataTransferConverter

Use the DataTransferConverter to convert between different temperature units, f.e. from Megabyte to Giga- byte.

Name unicorn.converter.datatransfer

Base Unit

• Megabit per second

Features

• Conversion • Mathematical operations • Adding own units

1.4. Converters 13 unicorn Documentation, Release 1.0.0

Predeﬁned Units

Name Abbreviation Factor Bit per second bit/s 1000000 Kilobit per second Kbit/s 1000 Megabit per second Mbit/s 1 Gigabit per second Gbit/s 0.001 Terabit per second Tbit/s 0.000001 Petabit per second Pbit/s 0.000000001 Exabit per second Ebit/s 0.000000000001 Zettabit per second Zbit/s 0.000000000000001 Yottabit per second Ybit/s 0.000000000000000001 Name Abbreviation Factor Kibibit per second Kibit/s 7812.5 Mebibit per second Mibit/s Kibit/s-Factor/1024 Gibibit per second Gibit/s Mibit/s-Factor/1024 Tebibit per second Tibit/s Gibit/s-Factor/1024 Pebibit per second Pibit/s Tibit/s-Factor/1024 Exibit per second Eibit/s Pibit/s-Factor/1024 Zebibit per second Zibit/s Eibit/s-Factor/1024 Yobibit per second Yibit/s Zibit/s-Factor/1024 Name Abbreviation Factor Byte per second B/s 125000 Kilobyte per second KB/s 125 Megabyte per second MB/s 0.125 Gigabyte per second GB/s 0.000125 Terabyte per second TB/s 0.000000125 Petabyte per second PB/s 0.000000000125 Exabyte per second EB/s 0.000000000000125 Zettabyte per second ZB/s 0.000000000000000125 Yottabyte per second YB/s 0.000000000000000000125 Name Abbreviation Factor Kibibyte per second KiB/s 122.07031296 Mebibyte per second MiB/s KiB/s-Factor/1024 Gibibyte per second GiB/s MiB/s-Factor/1024 Tebibyte per second TiB/s GiB/s-Factor/1024 Pebibyte per second PiB/s TiB/s-Factor/1024 Exibyte per second EiB/s PiB/s-Factor/1024 Zebibyte per second ZiB/s EiB/s-Factor/1024 Yobibyte per second YiB/s ZiB/s-Factor/1024

Contribute

• Issue Tracker: https://github.com/xyNNN/unicorn/issues • Source Code: https://github.com/xyNNN/unicorn

14 Chapter 1. User Guide unicorn Documentation, Release 1.0.0

License

Unicorn is released under the GNU LGPL v3.0 license. Read it here: LICENSE

1.6. License 15