From dc26d4addb80863b8e1bee54a9b6d3cae1a561bd Mon Sep 17 00:00:00 2001 From: Ben Ramsey Date: Sat, 26 Sep 2015 18:06:02 -0500 Subject: [PATCH] Add docblocks for classes and interfaces in Ramsey\Uuid\Converter namespace --- src/Converter/Number/BigNumberConverter.php | 27 ++++++++++++++----- .../Number/DegradedNumberConverter.php | 19 +++++++++++++ src/Converter/NumberConverterInterface.php | 22 +++++++++++++++ src/Converter/Time/BigNumberTimeConverter.php | 21 ++++++++++++--- src/Converter/Time/DegradedTimeConverter.php | 13 +++++++++ src/Converter/Time/PhpTimeConverter.php | 14 ++++++++++ src/Converter/TimeConverterInterface.php | 11 +++++--- 7 files changed, 115 insertions(+), 12 deletions(-) diff --git a/src/Converter/Number/BigNumberConverter.php b/src/Converter/Number/BigNumberConverter.php index 7ab5c49..d235122 100644 --- a/src/Converter/Number/BigNumberConverter.php +++ b/src/Converter/Number/BigNumberConverter.php @@ -14,26 +14,41 @@ namespace Ramsey\Uuid\Converter\Number; +use Moontoast\Math\BigNumber; use Ramsey\Uuid\Converter\NumberConverterInterface; +/** + * BigNumberConverter converts UUIDs from hexadecimal characters into + * moontoast/math `BigNumber` representations of integers and vice versa + */ class BigNumberConverter implements NumberConverterInterface { /** - * @param string $hex + * Converts a hexadecimal number into a `Moontoast\Math\BigNumber` representation + * + * @param string $hex The hexadecimal string representation to convert + * @return BigNumber */ public function fromHex($hex) { - $number = \Moontoast\Math\BigNumber::convertToBase10($hex, 16); + $number = BigNumber::convertToBase10($hex, 16); - return new \Moontoast\Math\BigNumber($number); + return new BigNumber($number); } + /** + * Converts an integer or `Moontoast\Math\BigNumber` integer representation + * into a hexadecimal string representation + * + * @param int|string|BigNumber $integer An integer or `Moontoast\Math\BigNumber` + * @return string Hexadecimal string + */ public function toHex($integer) { - if (!$integer instanceof \Moontoast\Math\BigNumber) { - $integer = new \Moontoast\Math\BigNumber($integer); + if (!$integer instanceof BigNumber) { + $integer = new BigNumber($integer); } - return \Moontoast\Math\BigNumber::convertFromBase10($integer, 16); + return BigNumber::convertFromBase10($integer, 16); } } diff --git a/src/Converter/Number/DegradedNumberConverter.php b/src/Converter/Number/DegradedNumberConverter.php index 6437386..96a011c 100644 --- a/src/Converter/Number/DegradedNumberConverter.php +++ b/src/Converter/Number/DegradedNumberConverter.php @@ -17,8 +17,20 @@ namespace Ramsey\Uuid\Converter\Number; use Ramsey\Uuid\Exception\UnsatisfiedDependencyException; use Ramsey\Uuid\Converter\NumberConverterInterface; +/** + * DegradedNumberConverter throws `UnsatisfiedDependencyException` exceptions + * if attempting to use number conversion functionality in an environment that + * does not support large integers (i.e. when moontoast/math is not available) + */ class DegradedNumberConverter implements NumberConverterInterface { + /** + * Throws an `UnsatisfiedDependencyException` + * + * @param string $hex The hexadecimal string representation to convert + * @return void + * @throws UnsatisfiedDependencyException + */ public function fromHex($hex) { throw new UnsatisfiedDependencyException( @@ -28,6 +40,13 @@ class DegradedNumberConverter implements NumberConverterInterface ); } + /** + * Throws an `UnsatisfiedDependencyException` + * + * @param mixed $integer An integer representation to convert + * @return void + * @throws UnsatisfiedDependencyException + */ public function toHex($integer) { throw new UnsatisfiedDependencyException( diff --git a/src/Converter/NumberConverterInterface.php b/src/Converter/NumberConverterInterface.php index c722439..673c1df 100644 --- a/src/Converter/NumberConverterInterface.php +++ b/src/Converter/NumberConverterInterface.php @@ -14,9 +14,31 @@ namespace Ramsey\Uuid\Converter; +/** + * NumberConverterInterface converts UUIDs from hexadecimal characters into + * representations of integers and vice versa + */ interface NumberConverterInterface { + /** + * Converts a hexadecimal number into an integer representation of the number + * + * The integer representation returned may be an object or a string + * representation of the integer, depending on the implementation. + * + * @param string $hex The hexadecimal string representation to convert + * @return mixed + */ public function fromHex($hex); + /** + * Converts an integer representation into a hexadecimal string representation + * of the number + * + * @param mixed $integer An integer representation to convert; this may be + * a true integer, a string integer, or a object representation that + * this converter can understand + * @return string Hexadecimal string + */ public function toHex($integer); } diff --git a/src/Converter/Time/BigNumberTimeConverter.php b/src/Converter/Time/BigNumberTimeConverter.php index e0bd6e6..d47c801 100644 --- a/src/Converter/Time/BigNumberTimeConverter.php +++ b/src/Converter/Time/BigNumberTimeConverter.php @@ -14,18 +14,33 @@ namespace Ramsey\Uuid\Converter\Time; +use Moontoast\Math\BigNumber; use Ramsey\Uuid\Converter\TimeConverterInterface; +/** + * BigNumberTimeConverter uses the moontoast/math library's `BigNumber` to + * provide facilities for converting parts of time into representations that may + * be used in UUIDs + */ class BigNumberTimeConverter implements TimeConverterInterface { + /** + * Uses the provided seconds and micro-seconds to calculate the time_low, + * time_mid, and time_high fields used by RFC 4122 version 1 UUIDs + * + * @param string $seconds + * @param string $microSeconds + * @return string[] An array containing `low`, `mid`, and `high` keys + * @link http://tools.ietf.org/html/rfc4122#section-4.2.2 + */ public function calculateTime($seconds, $microSeconds) { - $uuidTime = new \Moontoast\Math\BigNumber('0'); + $uuidTime = new BigNumber('0'); - $sec = new \Moontoast\Math\BigNumber($seconds); + $sec = new BigNumber($seconds); $sec->multiply('10000000'); - $usec = new \Moontoast\Math\BigNumber($microSeconds); + $usec = new BigNumber($microSeconds); $usec->multiply('10'); $uuidTime->add($sec) diff --git a/src/Converter/Time/DegradedTimeConverter.php b/src/Converter/Time/DegradedTimeConverter.php index 84f4f2a..46edbe7 100644 --- a/src/Converter/Time/DegradedTimeConverter.php +++ b/src/Converter/Time/DegradedTimeConverter.php @@ -17,8 +17,21 @@ namespace Ramsey\Uuid\Converter\Time; use Ramsey\Uuid\Converter\TimeConverterInterface; use Ramsey\Uuid\Exception\UnsatisfiedDependencyException; +/** + * DegradedTimeConverter throws `UnsatisfiedDependencyException` exceptions + * if attempting to use time conversion functionality in an environment that + * does not support large integers (i.e. when moontoast/math is not available) + */ class DegradedTimeConverter implements TimeConverterInterface { + /** + * Throws an `UnsatisfiedDependencyException` + * + * @param string $seconds + * @param string $microSeconds + * @return void + * @throws UnsatisfiedDependencyException + */ public function calculateTime($seconds, $microSeconds) { throw new UnsatisfiedDependencyException( diff --git a/src/Converter/Time/PhpTimeConverter.php b/src/Converter/Time/PhpTimeConverter.php index 7571ca3..6a9da74 100644 --- a/src/Converter/Time/PhpTimeConverter.php +++ b/src/Converter/Time/PhpTimeConverter.php @@ -16,8 +16,22 @@ namespace Ramsey\Uuid\Converter\Time; use Ramsey\Uuid\Converter\TimeConverterInterface; +/** + * PhpTimeConverter uses built-in PHP functions and standard math operations + * available to the PHP programming language to provide facilities for + * converting parts of time into representations that may be used in UUIDs + */ class PhpTimeConverter implements TimeConverterInterface { + /** + * Uses the provided seconds and micro-seconds to calculate the time_low, + * time_mid, and time_high fields used by RFC 4122 version 1 UUIDs + * + * @param string $seconds + * @param string $microSeconds + * @return string[] An array containing `low`, `mid`, and `high` keys + * @link http://tools.ietf.org/html/rfc4122#section-4.2.2 + */ public function calculateTime($seconds, $microSeconds) { // 0x01b21dd213814000 is the number of 100-ns intervals between the diff --git a/src/Converter/TimeConverterInterface.php b/src/Converter/TimeConverterInterface.php index 2223a61..f068836 100644 --- a/src/Converter/TimeConverterInterface.php +++ b/src/Converter/TimeConverterInterface.php @@ -14,15 +14,20 @@ namespace Ramsey\Uuid\Converter; +/** + * TimeConverterInterface provides facilities for converting parts of time into + * representations that may be used in UUIDs + */ interface TimeConverterInterface { - /** - * Calculates low, mid, high time array. + * Uses the provided seconds and micro-seconds to calculate the time_low, + * time_mid, and time_high fields used by RFC 4122 version 1 UUIDs * * @param string $seconds * @param string $microSeconds - * @return string[] An array guaranteed to contain 'low', 'mid', and 'high' keys. + * @return string[] An array guaranteed to contain `low`, `mid`, and `high` keys + * @link http://tools.ietf.org/html/rfc4122#section-4.2.2 */ public function calculateTime($seconds, $microSeconds); }