QuantityParser::newQuantityFromExponent() - Code Metrics - Inspection of "Factor UnboundedQuantityValue out of QuantityValue" - DataValues/Number - Measure and Improve Code Quality continuously with Scrutinizer

Completed

Pull Request — master (#66)

by Daniel

created 2016-07-11 12:41 UTC

QuantityParser::newQuantityFromExponent() A

↳ Parent: QuantityParser

Complexity

Conditions	2
Paths	2

Size

Total Lines	17
Code Lines	12

Duplication

Lines	0
Ratio	0 %

Importance

Changes	1
Bugs	0	Features	0

Metric	Value
c	1
b	0
f	0
dl	0
loc	17
rs	9.4285
cc	2
eloc	12
nc	2
nop	3

<?php

namespace ValueParsers;

use DataValues\QuantityValue;
use DataValues\DecimalMath;
use DataValues\DecimalValue;
use DataValues\IllegalValueException;
use DataValues\UnboundedQuantityValue;
use InvalidArgumentException;

/**
 * ValueParser that parses the string representation of a quantity.
 *
 * @since 0.1
 *
 * @license GPL-2.0+
 * @author Daniel Kinzler
 */
class QuantityParser extends StringValueParser {

	const FORMAT_NAME = 'quantity';

	/**
	 * The unit of the value to parse. If this option is given, it's illegal to also specify
	 * a unit in the input string.
	 *
	 * @since 0.5
	 */
	const OPT_UNIT = 'unit';

	/**
	 * @var DecimalParser
	 */
	private $decimalParser;

	/**
	 * @var NumberUnlocalizer
	 */
	private $unlocalizer;

	/**
	 * @since 0.1
	 *
	 * @param ParserOptions|null $options
	 * @param NumberUnlocalizer|null $unlocalizer
	 */
	public function __construct( ParserOptions $options = null, NumberUnlocalizer $unlocalizer = null ) {
		parent::__construct( $options );

		$this->defaultOption( self::OPT_UNIT, null );

		$this->unlocalizer = $unlocalizer ?: new BasicNumberUnlocalizer();
		$this->decimalParser = new DecimalParser( $this->options, $this->unlocalizer );
	}

	/**
	 * @see StringValueParser::stringParse
	 *
	 * @since 0.1
	 *
	 * @param string $value
	 *
	 * @return UnboundedQuantityValue
	 * @throws ParseException
	 */
	protected function stringParse( $value ) {
		list( $amount, $exactness, $margin, $unit ) = $this->splitQuantityString( $value );

		$unitOption = $this->getUnitFromOptions();

		if ( $unit === null ) {
			$unit = $unitOption !== null ? $unitOption : '1';
		} elseif ( $unitOption !== null && $unit !== $unitOption ) {
			throw new ParseException( 'Cannot specify a unit in input if a unit was fixed via options.' );
		}

		try {
			$quantity = $this->newQuantityFromParts( $amount, $exactness, $margin, $unit );
			return $quantity;
		} catch ( IllegalValueException $ex ) {
			throw new ParseException( $ex->getMessage(), $value, self::FORMAT_NAME );
		}
	}

	/**
	 * @return string|null
	 */
	private function getUnitFromOptions() {
		$unit = $this->getOption( self::OPT_UNIT );
		return $unit === null ? null : trim( $unit );
	}

	/**
	 * Constructs a QuantityValue from the given parts.
	 *
	 * @see splitQuantityString
	 *
	 * @param string $amount decimal representation of the amount
	 * @param string|null $exactness either '!' to indicate an exact value,
	 *        or '~' for "automatic", or null if $margin should be used.
	 * @param string|null $margin decimal representation of the uncertainty margin
	 * @param string $unit the unit identifier (use "1" for unitless quantities).
	 *
	 * @throws ParseException if one of the decimals could not be parsed.
	 * @throws IllegalValueException if the QuantityValue could not be constructed
	 * @return UnboundedQuantityValue
	 */
	private function newQuantityFromParts( $amount, $exactness, $margin, $unit ) {
		list( $amount, $exponent ) = $this->decimalParser->splitDecimalExponent( $amount );
		$amountValue = $this->decimalParser->parse( $amount );

		if ( $exactness === '!' ) {
			// the amount is an exact number
			$amountValue = $this->decimalParser->applyDecimalExponent( $amountValue, $exponent );
			$quantity = $this->newExactQuantity( $amountValue, $unit );
		} elseif ( $margin !== null ) {
			// uncertainty margin given
			// NOTE: the pattern for scientific notation is 2e3 +/- 1e2, so the exponents are treated separately.
			$marginValue = $this->decimalParser->parse( $margin );
			$amountValue = $this->decimalParser->applyDecimalExponent( $amountValue, $exponent );
			$quantity = $this->newUncertainQuantityFromMargin( $amountValue, $unit, $marginValue );
		} elseif ( $exponent !== 0 ) {
			// Scientific notation. Uncertainty is given by the exponent.
			$quantity = $this->newQuantityFromExponent( $amountValue, $unit, $exponent );
		} else {
			// uncertainty is uncertain
			$quantity = $this->newUnboundedQuantityFromDigits( $amountValue, $unit );
		}

		return $quantity;
	}

	/**
	 * Splits a quantity string into its syntactic parts.
	 *
	 * @see newQuantityFromParts
	 *
	 * @param string $value
	 *
	 * @throws InvalidArgumentException If $value is not a string
	 * @throws ParseException If $value does not match the expected pattern
	 * @return array list( $amount, $exactness, $margin, $unit ).
	 *         Parts not present in $value will be null
	 */
	private function splitQuantityString( $value ) {
		if ( !is_string( $value ) ) {
			throw new InvalidArgumentException( '$value must be a string' );
		}

		//TODO: allow explicitly specifying the number of significant figures
		//TODO: allow explicitly specifying the uncertainty interval

		$numberPattern = $this->unlocalizer->getNumberRegex( '@' );
		$unitPattern = $this->unlocalizer->getUnitRegex( '@' );

		$pattern = '@^'
			. '\s*(' . $numberPattern . ')' // $1: amount
			. '\s*(?:'
				. '([~!])'  // $2: '!' for "exact", '~' for "approx", or nothing
				. '|(?:\+/?-|±)\s*(' . $numberPattern . ')' // $3: plus/minus offset (uncertainty margin)
				. '|' // or nothing
			. ')'
			. '\s*(' . $unitPattern . ')?' // $4: unit
			. '\s*$@u';

		if ( !preg_match( $pattern, $value, $groups ) ) {
			throw new ParseException( 'Malformed quantity', $value, self::FORMAT_NAME );
		}

		// Remove $0.
		array_shift( $groups );

		array_walk( $groups, function( &$element ) {
			if ( $element === '' ) {
				$element = null;
			}
		} );

		return array_pad( $groups, 4, null );
	}

	/**
	 * Returns a QuantityValue representing the given amount.
	 * The amount is assumed to be absolutely exact, that is,
	 * the upper and lower bound will be the same as the amount.
	 *
	 * @param DecimalValue $amount
	 * @param string $unit The quantity's unit (use "1" for unit-less quantities)
	 *
	 * @return UnboundedQuantityValue
	 */
	private function newExactQuantity( DecimalValue $amount, $unit = '1' ) {
		return new QuantityValue( $amount, $unit, $amount, $amount );
	}

	/**
	 * Returns a QuantityValue representing the given amount, automatically assuming
	 * a level of uncertainty based on the digits given.
	 *
	 * The upper and lower bounds are determined automatically from the given
	 * digits by increasing resp. decreasing the least significant digit.
	 * E.g. "+0.01" would have upperBound "+0.02" and lowerBound "+0.01",
	 * while "-100" would have upperBound "-99" and lowerBound "-101".
	 *
	 * @param DecimalValue $amount The quantity
	 * @param string $unit The quantity's unit (use "1" for unit-less quantities)
	 * @param DecimalValue $margin
	 *
	 * @return UnboundedQuantityValue
	 */
	private function newUncertainQuantityFromMargin( DecimalValue $amount, $unit = '1', DecimalValue $margin ) {
		$decimalMath = new DecimalMath();
		$margin = $margin->computeAbsolute();

		$lowerBound = $decimalMath->sum( $amount, $margin->computeComplement() );
		$upperBound = $decimalMath->sum( $amount, $margin );

		return new QuantityValue( $amount, $unit, $upperBound, $lowerBound );
	}

	/**
	 * Returns a QuantityValue representing the given amount, automatically assuming
	 * a level of uncertainty based on the given exponent, following the conventions
	 * for scientific notation of decimal numbers: 12e3 is interpreted as 12000 with
	 * two significant digits, represented as 12000 with a lower bound of 12000
	 * and an upper bound of 12999.
	 *
	 * @param DecimalValue $amount The quantity
	 * @param string $unit The quantity's unit (use "1" for unit-less quantities)
	 * @param int $exponent Decimal exponent to apply
	 *
	 * @return UnboundedQuantityValue
	 */
	private function newQuantityFromExponent( DecimalValue $amount, $unit = '1', $exponent = 0 ) {
		$math = new DecimalMath();

		if ( $amount->getSign() === '+' ) {
			$upperBound = $math->bump( $amount );
			$lowerBound = $math->slump( $amount );
		} else {
			$upperBound = $math->slump( $amount );
			$lowerBound = $math->bump( $amount );
		}

		$amount = $this->decimalParser->applyDecimalExponent( $amount, $exponent );
		$lowerBound = $this->decimalParser->applyDecimalExponent( $lowerBound, $exponent );
		$upperBound = $this->decimalParser->applyDecimalExponent( $upperBound, $exponent );

		return new QuantityValue( $amount, $unit, $upperBound, $lowerBound );
	}

	/**
	 * @param DecimalValue $amount
	 * @param string $unit
	 *
	 * @return UnboundedQuantityValue
	 */
	private function newUnboundedQuantityFromDigits( DecimalValue $amount, $unit = '1' ) {
		return new UnboundedQuantityValue( $amount, $unit );
	}

}


1			<?php
2
3			namespace ValueParsers;
4
5			use DataValues\QuantityValue;
6			use DataValues\DecimalMath;
7			use DataValues\DecimalValue;
8			use DataValues\IllegalValueException;
9			use DataValues\UnboundedQuantityValue;
10			use InvalidArgumentException;
11
12			/**
13			* ValueParser that parses the string representation of a quantity.
14			*
15			* @since 0.1
16			*
17			* @license GPL-2.0+
18			* @author Daniel Kinzler
19			*/
20			class QuantityParser extends StringValueParser {
21
22			const FORMAT_NAME = 'quantity';
23
24			/**
25			* The unit of the value to parse. If this option is given, it's illegal to also specify
26			* a unit in the input string.
27			*
28			* @since 0.5
29			*/
30			const OPT_UNIT = 'unit';
31
32			/**
33			* @var DecimalParser
34			*/
35			private $decimalParser;
36
37			/**
38			* @var NumberUnlocalizer
39			*/
40			private $unlocalizer;
41
42			/**
43			* @since 0.1
44			*
45			* @param ParserOptions\|null $options
46			* @param NumberUnlocalizer\|null $unlocalizer
47			*/
48			public function __construct( ParserOptions $options = null, NumberUnlocalizer $unlocalizer = null ) {
49			parent::__construct( $options );
50
51			$this->defaultOption( self::OPT_UNIT, null );
52
53			$this->unlocalizer = $unlocalizer ?: new BasicNumberUnlocalizer();
54			$this->decimalParser = new DecimalParser( $this->options, $this->unlocalizer );
55			}
56
57			/**
58			* @see StringValueParser::stringParse
59			*
60			* @since 0.1
61			*
62			* @param string $value
63			*
64			* @return UnboundedQuantityValue
65			* @throws ParseException
66			*/
67			protected function stringParse( $value ) {
68			list( $amount, $exactness, $margin, $unit ) = $this->splitQuantityString( $value );
69
70			$unitOption = $this->getUnitFromOptions();
71
72			if ( $unit === null ) {
73			$unit = $unitOption !== null ? $unitOption : '1';
74			} elseif ( $unitOption !== null && $unit !== $unitOption ) {
75			throw new ParseException( 'Cannot specify a unit in input if a unit was fixed via options.' );
76			}
77
78			try {
79			$quantity = $this->newQuantityFromParts( $amount, $exactness, $margin, $unit );
80			return $quantity;
81			} catch ( IllegalValueException $ex ) {
82			throw new ParseException( $ex->getMessage(), $value, self::FORMAT_NAME );
83			}
84			}
85
86			/**
87			* @return string\|null
88			*/
89			private function getUnitFromOptions() {
90			$unit = $this->getOption( self::OPT_UNIT );
91			return $unit === null ? null : trim( $unit );
92			}
93
94			/**
95			* Constructs a QuantityValue from the given parts.
96			*
97			* @see splitQuantityString
98			*
99			* @param string $amount decimal representation of the amount
100			* @param string\|null $exactness either '!' to indicate an exact value,
101			* or '~' for "automatic", or null if $margin should be used.
102			* @param string\|null $margin decimal representation of the uncertainty margin
103			* @param string $unit the unit identifier (use "1" for unitless quantities).
104			*
105			* @throws ParseException if one of the decimals could not be parsed.
106			* @throws IllegalValueException if the QuantityValue could not be constructed
107			* @return UnboundedQuantityValue
108			*/
109			private function newQuantityFromParts( $amount, $exactness, $margin, $unit ) {
110			list( $amount, $exponent ) = $this->decimalParser->splitDecimalExponent( $amount );
111			$amountValue = $this->decimalParser->parse( $amount );
112
113			if ( $exactness === '!' ) {
114			// the amount is an exact number
115			$amountValue = $this->decimalParser->applyDecimalExponent( $amountValue, $exponent );
116			$quantity = $this->newExactQuantity( $amountValue, $unit );
117			} elseif ( $margin !== null ) {
118			// uncertainty margin given
119			// NOTE: the pattern for scientific notation is 2e3 +/- 1e2, so the exponents are treated separately.
120			$marginValue = $this->decimalParser->parse( $margin );
121			$amountValue = $this->decimalParser->applyDecimalExponent( $amountValue, $exponent );
122			$quantity = $this->newUncertainQuantityFromMargin( $amountValue, $unit, $marginValue );
123			} elseif ( $exponent !== 0 ) {
124			// Scientific notation. Uncertainty is given by the exponent.
125			$quantity = $this->newQuantityFromExponent( $amountValue, $unit, $exponent );
126			} else {
127			// uncertainty is uncertain
128			$quantity = $this->newUnboundedQuantityFromDigits( $amountValue, $unit );
129			}
130
131			return $quantity;
132			}
133
134			/**
135			* Splits a quantity string into its syntactic parts.
136			*
137			* @see newQuantityFromParts
138			*
139			* @param string $value
140			*
141			* @throws InvalidArgumentException If $value is not a string
142			* @throws ParseException If $value does not match the expected pattern
143			* @return array list( $amount, $exactness, $margin, $unit ).
144			* Parts not present in $value will be null
145			*/
146			private function splitQuantityString( $value ) {
147			if ( !is_string( $value ) ) {
148			throw new InvalidArgumentException( '$value must be a string' );
149			}
150
151			//TODO: allow explicitly specifying the number of significant figures
152			//TODO: allow explicitly specifying the uncertainty interval
153
154			$numberPattern = $this->unlocalizer->getNumberRegex( '@' );
155			$unitPattern = $this->unlocalizer->getUnitRegex( '@' );
156
157			$pattern = '@^'
158			. '\s*(' . $numberPattern . ')' // $1: amount
159			. '\s*(?:'
160			. '([~!])' // $2: '!' for "exact", '~' for "approx", or nothing
161			. '\|(?:\+/?-\|±)\s*(' . $numberPattern . ')' // $3: plus/minus offset (uncertainty margin)
162			. '\|' // or nothing
163			. ')'
164			. '\s*(' . $unitPattern . ')?' // $4: unit
165			. '\s*$@u';
166
167			if ( !preg_match( $pattern, $value, $groups ) ) {
168			throw new ParseException( 'Malformed quantity', $value, self::FORMAT_NAME );
169			}
170
171			// Remove $0.
172			array_shift( $groups );
173
174			array_walk( $groups, function( &$element ) {
175			if ( $element === '' ) {
176			$element = null;
177			}
178			} );
179
180			return array_pad( $groups, 4, null );
181			}
182
183			/**
184			* Returns a QuantityValue representing the given amount.
185			* The amount is assumed to be absolutely exact, that is,
186			* the upper and lower bound will be the same as the amount.
187			*
188			* @param DecimalValue $amount
189			* @param string $unit The quantity's unit (use "1" for unit-less quantities)
190			*
191			* @return UnboundedQuantityValue
192			*/
193			private function newExactQuantity( DecimalValue $amount, $unit = '1' ) {
194			return new QuantityValue( $amount, $unit, $amount, $amount );
195			}
196
197			/**
198			* Returns a QuantityValue representing the given amount, automatically assuming
199			* a level of uncertainty based on the digits given.
200			*
201			* The upper and lower bounds are determined automatically from the given
202			* digits by increasing resp. decreasing the least significant digit.
203			* E.g. "+0.01" would have upperBound "+0.02" and lowerBound "+0.01",
204			* while "-100" would have upperBound "-99" and lowerBound "-101".
205			*
206			* @param DecimalValue $amount The quantity
207			* @param string $unit The quantity's unit (use "1" for unit-less quantities)
208			* @param DecimalValue $margin
209			*
210			* @return UnboundedQuantityValue
211			*/
212			private function newUncertainQuantityFromMargin( DecimalValue $amount, $unit = '1', DecimalValue $margin ) {
213			$decimalMath = new DecimalMath();
214			$margin = $margin->computeAbsolute();
215
216			$lowerBound = $decimalMath->sum( $amount, $margin->computeComplement() );
217			$upperBound = $decimalMath->sum( $amount, $margin );
218
219			return new QuantityValue( $amount, $unit, $upperBound, $lowerBound );
220			}
221
222			/**
223			* Returns a QuantityValue representing the given amount, automatically assuming
224			* a level of uncertainty based on the given exponent, following the conventions
225			* for scientific notation of decimal numbers: 12e3 is interpreted as 12000 with
226			* two significant digits, represented as 12000 with a lower bound of 12000
227			* and an upper bound of 12999.
228			*
229			* @param DecimalValue $amount The quantity
230			* @param string $unit The quantity's unit (use "1" for unit-less quantities)
231			* @param int $exponent Decimal exponent to apply
232			*
233			* @return UnboundedQuantityValue
234			*/
235			private function newQuantityFromExponent( DecimalValue $amount, $unit = '1', $exponent = 0 ) {
236			$math = new DecimalMath();
237
238			if ( $amount->getSign() === '+' ) {
239			$upperBound = $math->bump( $amount );
240			$lowerBound = $math->slump( $amount );
241			} else {
242			$upperBound = $math->slump( $amount );
243			$lowerBound = $math->bump( $amount );
244			}
245
246			$amount = $this->decimalParser->applyDecimalExponent( $amount, $exponent );
247			$lowerBound = $this->decimalParser->applyDecimalExponent( $lowerBound, $exponent );
248			$upperBound = $this->decimalParser->applyDecimalExponent( $upperBound, $exponent );
249
250			return new QuantityValue( $amount, $unit, $upperBound, $lowerBound );
251			}
252
253			/**
254			* @param DecimalValue $amount
255			* @param string $unit
256			*
257			* @return UnboundedQuantityValue
258			*/
259			private function newUnboundedQuantityFromDigits( DecimalValue $amount, $unit = '1' ) {
260			return new UnboundedQuantityValue( $amount, $unit );
261			}
262
263			}
264

DataValues / Number

Pull Request — master (#66)

QuantityParser::newQuantityFromExponent() A

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like