QuantityValue::newFromDecimal() - Code Metrics - Inspection of "[WIP] Factor BoundedQuantityValue out of QuantityV..." - DataValues/Number - Measure and Improve Code Quality continuously with Scrutinizer

Completed

Pull Request — master (#66)

by Daniel

created 2016-06-24 15:38 UTC

QuantityValue::newFromDecimal() A

↳ Parent: QuantityValue

Complexity

Conditions	1
Paths	1

Size

Total Lines	3
Code Lines	2

Duplication

Lines	0
Ratio	0 %

Importance

Changes	2
Bugs	0	Features	0

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

<?php

namespace DataValues;

use InvalidArgumentException;
use LogicException;

/**
 * Class representing a quantity with associated unit.
 * The amount is stored as a @see DecimalValue object.
 *
 * @see BoundedQuantityValue for quantities with a known uncertainty interval.
 * For simple numeric amounts use @see NumberValue.
 *
 * @note BoundedQuantityValue and plain QuantityValue both use the value type ID "quantity".
 * The fact that we use subclassing to model the bounded vs the unbounded case should be
 * considered an implementation detail.
 *
 * @since 0.1
 *
 * @license GPL-2.0+
 * @author Daniel Kinzler
 */
class QuantityValue extends DataValueObject {

	/**
	 * The quantity's amount
	 *
	 * @var DecimalValue
	 */
	protected $amount;

	/**
	 * The quantity's unit identifier (use "1" for unitless quantities).
	 *
	 * @var string
	 */
	protected $unit;

	/**
	 * Constructs a new QuantityValue object, representing the given value.
	 *
	 * @since 0.1
	 *
	 * @param DecimalValue $amount
	 * @param string $unit A unit identifier. Must not be empty, use "1" for unit-less quantities.
	 *
	 * @throws IllegalValueException
	 */
	public function __construct( DecimalValue $amount, $unit, $unused = 'nothing' ) {
		if ( $unused !== 'nothing' ) {
			throw new LogicException( 'Constructor called with old signature. '
				. 'Perhaps you want to construct a BoundedQuantityValue instead.' );
		}

		if ( !is_string( $unit ) ) {
			throw new IllegalValueException( '$unit needs to be a string, not ' . gettype( $unit ) );
		}

		if ( $unit === '' ) {
			throw new IllegalValueException( '$unit can not be an empty string (use "1" for unit-less quantities)' );
		}

		$this->amount = $amount;
		$this->unit = $unit;
	}

	/**
	 * Returns a QuantityValue representing the given amount.
	 *
	 * This is a convenience wrapper around the constructor that accepts native values
	 * instead of DecimalValue objects.
	 *
	 * @note: if the amount or a bound is given as a string, the string must conform
	 * to the rules defined by @see DecimalValue.
	 *
	 * @since 0.1
	 *
	 * @param string|int|float|DecimalValue $number
	 * @param string $unit A unit identifier. Must not be empty, use "1" for unit-less quantities.
	 *
	 * @return self
	 * @throws IllegalValueException
	 */
	public static function newFromNumber( $number, $unit = '1' ) {
		$number = self::asDecimalValue( 'amount', $number );

		return new self( $number, $unit );
	}

	/**
	 * @see newFromNumber
	 *
	 * @deprecated since 0.1, use newFromNumber instead
	 *
	 * @param string|int|float|DecimalValue $number
	 * @param string $unit
	 * @param string|int|float|DecimalValue|null $upperBound
/**
 * @param array $germany
 * @param array $island
 * @param array $italy
 */
function finale($germany, $island) {
    return "2:1";
}
	 * @param string|int|float|DecimalValue|null $lowerBound
/**
 * @param array $germany
 * @param array $island
 * @param array $italy
 */
function finale($germany, $island) {
    return "2:1";
}
	 *
	 * @return self
	 */
	public static function newFromDecimal( $number, $unit = '1' ) {
		return self::newFromNumber( $number, $unit );
	}

	/**
	 * Converts $number to a DecimalValue if possible and necessary.
	 *
	 * @note: if the $number is given as a string, it must conform to the rules
	 *        defined by @see DecimalValue.
	 *
	 * @param string $name The variable name to use in exception messages
	 * @param string|int|float|DecimalValue|null $number
	 * @param DecimalValue|null $default
	 *
	 * @throws IllegalValueException
	 * @throws InvalidArgumentException
	 * @return DecimalValue
	 */
	protected static function asDecimalValue( $name, $number, DecimalValue $default = null ) {
		if ( !is_string( $name ) ) {
			throw new InvalidArgumentException( '$name must be a string' );
		}

		if ( $number === null ) {
			if ( $default === null ) {
				throw new InvalidArgumentException( '$' . $name . ' must not be null' );
			}

			$number = $default;
		}

		if ( $number instanceof DecimalValue ) {
if (rand(1, 6) > 3) {
//print "Check failed";
} else {
    print "Check succeeded";
}
			// nothing to do
		} elseif ( is_int( $number ) || is_float( $number ) || is_string( $number ) ) {
			$number = new DecimalValue( $number );
		} else {
			throw new IllegalValueException( '$' . $name . '  must be a string, int, or float' );
		}

		return $number;
	}

	/**
	 * @see Serializable::serialize
	 *
	 * @since 0.1
	 *
	 * @return string
	 */
	public function serialize() {
		return serialize( array_values( $this->getArrayValue() ) );
	}

	/**
	 * @see Serializable::unserialize
	 *
	 * @since 0.1
	 *
	 * @param string $data
	 */
	public function unserialize( $data ) {
		list( $amount, $unit ) = unserialize( $data );
		$amount = DecimalValue::newFromArray( $amount );
		$this->__construct( $amount, $unit );
	}

	/**
	 * @see DataValue::getType
	 *
	 * @since 0.1
	 *
	 * @return string
	 */
	public static function getType() {
		return 'quantity';
	}

	/**
	 * @see DataValue::getSortKey
	 *
	 * @since 0.1
	 *
	 * @return float
	 */
	public function getSortKey() {
		return $this->amount->getValueFloat();
	}

	/**
	 * Returns the quantity object.
	 * @see DataValue::getValue
	 *
	 * @since 0.1
	 *
	 * @return self
	 */
	public function getValue() {
		return $this;
	}

	/**
	 * Returns the amount represented by this quantity.
	 *
	 * @since 0.1
	 *
	 * @return DecimalValue
	 */
	public function getAmount() {
		return $this->amount;
	}

	/**
	 * Returns the unit held by this quantity.
	 * Unit-less quantities should use "1" as their unit.
	 *
	 * @since 0.1
	 *
	 * @return string
	 */
	public function getUnit() {
		return $this->unit;
	}

	/**
	 * Returns a transformed value derived from this QuantityValue by applying
	 * the given transformation to the amount and the upper and lower bounds.
	 * The resulting amount and bounds are rounded to the significant number of
	 * digits. Note that for exact quantities (with at least one bound equal to
	 * the amount), no rounding is applied (since they are considered to have
	 * infinite precision).
	 *
	 * The transformation is provided as a callback, which must implement a
	 * monotonously increasing, fully differentiable function mapping a DecimalValue
	 * to a DecimalValue. Typically, it will be a linear transformation applying a
	 * factor and an offset.
	 *
	 * @param string $newUnit The unit of the transformed quantity.
	 *
	 * @param callable $transformation A callback that implements the desired transformation.
	 *        The transformation will be called three times, once for the amount, once
	 *        for the lower bound, and once for the upper bound. It must return a DecimalValue.
	 *        The first parameter passed to $transformation is the DecimalValue to transform
	 *        In addition, any extra parameters passed to transform() will be passed through
	 *        to the transformation callback.
	 *
	 * @param mixed ... Any extra parameters will be passed to the $transformation function.
	 *
	 * @throws InvalidArgumentException
	 * @return self
	 */
	public function transform( $newUnit, $transformation ) {
		if ( !is_callable( $transformation ) ) {
			throw new InvalidArgumentException( '$transformation must be callable.' );
		}

		if ( !is_string( $newUnit ) ) {
			throw new InvalidArgumentException( '$newUnit must be a string. Use "1" as the unit for unit-less quantities.' );
		}

		if ( $newUnit === '' ) {
			throw new InvalidArgumentException( '$newUnit must not be empty. Use "1" as the unit for unit-less quantities.' );
		}

		$oldUnit = $this->unit;

		if ( $newUnit === null ) {
			$newUnit = $oldUnit;
		}

		// Apply transformation by calling the $transform callback.
		// The first argument for the callback is the DataValue to transform. In addition,
		// any extra arguments given for transform() are passed through.
		$args = func_get_args();
		array_shift( $args );

		$args[0] = $this->amount;
		$amount = call_user_func_array( $transformation, $args );

		// use a preliminary QuantityValue to determine the significant number of digits
		return new self( $amount, $newUnit );
	}

	public function __toString() {
		return $this->amount->getValue()
			. ( $this->unit === '1' ? '' : $this->unit );
	}

	/**
	 * @see DataValue::getArrayValue
	 *
	 * @since 0.1
	 *
	 * @return array
	 */
	public function getArrayValue() {
		return array(
			'amount' => $this->amount->getArrayValue(),
			'unit' => $this->unit,
		);
	}

	/**
	 * Constructs a new instance of the DataValue from the provided data.
	 * This can round-trip with @see getArrayValue
	 *
	 * @since 0.1
	 *
	 * @param mixed $data
	 *
	 * @return self
	 * @throws IllegalValueException
	 */
	public static function newFromArray( $data ) {
		self::requireArrayFields( $data, array( 'amount', 'unit' ) );

		return new static(
			DecimalValue::newFromArray( $data['amount'] ),
			$data['unit']
		);
	}

	/**
	 * @see Comparable::equals
	 *
	 * @since 0.1
	 *
	 * @param mixed $target
	 *
	 * @return bool
	 */
	public function equals( $target ) {
		if ( $this === $target ) {
			return true;
		}

		return $target instanceof self
			&& $this->toArray() === $target->toArray();
	}

}


1			<?php
2
3			namespace DataValues;
4
5			use InvalidArgumentException;
6			use LogicException;
7
8			/**
9			* Class representing a quantity with associated unit.
10			* The amount is stored as a @see DecimalValue object.
11			*
12			* @see BoundedQuantityValue for quantities with a known uncertainty interval.
13			* For simple numeric amounts use @see NumberValue.
14			*
15			* @note BoundedQuantityValue and plain QuantityValue both use the value type ID "quantity".
16			* The fact that we use subclassing to model the bounded vs the unbounded case should be
17			* considered an implementation detail.
18			*
19			* @since 0.1
20			*
21			* @license GPL-2.0+
22			* @author Daniel Kinzler
23			*/
24			class QuantityValue extends DataValueObject {
25
26			/**
27			* The quantity's amount
28			*
29			* @var DecimalValue
30			*/
31			protected $amount;
32
33			/**
34			* The quantity's unit identifier (use "1" for unitless quantities).
35			*
36			* @var string
37			*/
38			protected $unit;
39
40			/**
41			* Constructs a new QuantityValue object, representing the given value.
42			*
43			* @since 0.1
44			*
45			* @param DecimalValue $amount
46			* @param string $unit A unit identifier. Must not be empty, use "1" for unit-less quantities.
47			*
48			* @throws IllegalValueException
49			*/
50			public function __construct( DecimalValue $amount, $unit, $unused = 'nothing' ) {
51			if ( $unused !== 'nothing' ) {
52			throw new LogicException( 'Constructor called with old signature. '
53			. 'Perhaps you want to construct a BoundedQuantityValue instead.' );
54			}
55
56			if ( !is_string( $unit ) ) {
57			throw new IllegalValueException( '$unit needs to be a string, not ' . gettype( $unit ) );
58			}
59
60			if ( $unit === '' ) {
61			throw new IllegalValueException( '$unit can not be an empty string (use "1" for unit-less quantities)' );
62			}
63
64			$this->amount = $amount;
65			$this->unit = $unit;
66			}
67
68			/**
69			* Returns a QuantityValue representing the given amount.
70			*
71			* This is a convenience wrapper around the constructor that accepts native values
72			* instead of DecimalValue objects.
73			*
74			* @note: if the amount or a bound is given as a string, the string must conform
75			* to the rules defined by @see DecimalValue.
76			*
77			* @since 0.1
78			*
79			* @param string\|int\|float\|DecimalValue $number
80			* @param string $unit A unit identifier. Must not be empty, use "1" for unit-less quantities.
81			*
82			* @return self
83			* @throws IllegalValueException
84			*/
85			public static function newFromNumber( $number, $unit = '1' ) {
86			$number = self::asDecimalValue( 'amount', $number );
87
88			return new self( $number, $unit );
89			}
90
91			/**
92			* @see newFromNumber
93			*
94			* @deprecated since 0.1, use newFromNumber instead
95			*
96			* @param string\|int\|float\|DecimalValue $number
97			* @param string $unit
98			* @param string\|int\|float\|DecimalValue\|null $upperBound
			0 ignored issues – show Bug introduced 2016-06-23 15:23 UTC by Report Bug Copy Issue Report There is no parameter named `$upperBound`. Was it maybe removed? This check looks for PHPDoc comments describing methods or function parameters that do not exist on the corresponding method or function. Consider the following example. The parameter `$italy` is not defined by the method `finale(...)`. /** * @param array $germany * @param array $island * @param array $italy */ function finale($germany, $island) { return "2:1"; } The most likely cause is that the parameter was removed, but the annotation was not. Loading history...
99			* @param string\|int\|float\|DecimalValue\|null $lowerBound
			0 ignored issues – show Bug introduced 2016-06-23 15:23 UTC by Report Bug Copy Issue Report There is no parameter named `$lowerBound`. Was it maybe removed? This check looks for PHPDoc comments describing methods or function parameters that do not exist on the corresponding method or function. Consider the following example. The parameter `$italy` is not defined by the method `finale(...)`. /** * @param array $germany * @param array $island * @param array $italy */ function finale($germany, $island) { return "2:1"; } The most likely cause is that the parameter was removed, but the annotation was not. Loading history...
100			*
101			* @return self
102			*/
103			public static function newFromDecimal( $number, $unit = '1' ) {
104			return self::newFromNumber( $number, $unit );
105			}
106
107			/**
108			* Converts $number to a DecimalValue if possible and necessary.
109			*
110			* @note: if the $number is given as a string, it must conform to the rules
111			* defined by @see DecimalValue.
112			*
113			* @param string $name The variable name to use in exception messages
114			* @param string\|int\|float\|DecimalValue\|null $number
115			* @param DecimalValue\|null $default
116			*
117			* @throws IllegalValueException
118			* @throws InvalidArgumentException
119			* @return DecimalValue
120			*/
121			protected static function asDecimalValue( $name, $number, DecimalValue $default = null ) {
122			if ( !is_string( $name ) ) {
123			throw new InvalidArgumentException( '$name must be a string' );
124			}
125
126			if ( $number === null ) {
127			if ( $default === null ) {
128			throw new InvalidArgumentException( '$' . $name . ' must not be null' );
129			}
130
131			$number = $default;
132			}
133
134			if ( $number instanceof DecimalValue ) {
			0 ignored issues – show Unused Code introduced 2015-12-12 11:58 UTC by Report Bug Copy Issue Report This `if` statement is empty and can be removed. This check looks for the bodies of `if` statements that have no statements or where all statements have been commented out. This may be the result of changes for debugging or the code may simply be obsolete. These `if` bodies can be removed. If you have an empty if but statements in the `else` branch, consider inverting the condition. if (rand(1, 6) > 3) { //print "Check failed"; } else { print "Check succeeded"; } could be turned into if (rand(1, 6) <= 3) { print "Check succeeded"; } This is much more concise to read. Loading history...
135			// nothing to do
136			} elseif ( is_int( $number ) \|\| is_float( $number ) \|\| is_string( $number ) ) {
137			$number = new DecimalValue( $number );
138			} else {
139			throw new IllegalValueException( '$' . $name . ' must be a string, int, or float' );
140			}
141
142			return $number;
143			}
144
145			/**
146			* @see Serializable::serialize
147			*
148			* @since 0.1
149			*
150			* @return string
151			*/
152			public function serialize() {
153			return serialize( array_values( $this->getArrayValue() ) );
154			}
155
156			/**
157			* @see Serializable::unserialize
158			*
159			* @since 0.1
160			*
161			* @param string $data
162			*/
163			public function unserialize( $data ) {
164			list( $amount, $unit ) = unserialize( $data );
165			$amount = DecimalValue::newFromArray( $amount );
166			$this->__construct( $amount, $unit );
167			}
168
169			/**
170			* @see DataValue::getType
171			*
172			* @since 0.1
173			*
174			* @return string
175			*/
176			public static function getType() {
177			return 'quantity';
178			}
179
180			/**
181			* @see DataValue::getSortKey
182			*
183			* @since 0.1
184			*
185			* @return float
186			*/
187			public function getSortKey() {
188			return $this->amount->getValueFloat();
189			}
190
191			/**
192			* Returns the quantity object.
193			* @see DataValue::getValue
194			*
195			* @since 0.1
196			*
197			* @return self
198			*/
199			public function getValue() {
200			return $this;
201			}
202
203			/**
204			* Returns the amount represented by this quantity.
205			*
206			* @since 0.1
207			*
208			* @return DecimalValue
209			*/
210			public function getAmount() {
211			return $this->amount;
212			}
213
214			/**
215			* Returns the unit held by this quantity.
216			* Unit-less quantities should use "1" as their unit.
217			*
218			* @since 0.1
219			*
220			* @return string
221			*/
222			public function getUnit() {
223			return $this->unit;
224			}
225
226			/**
227			* Returns a transformed value derived from this QuantityValue by applying
228			* the given transformation to the amount and the upper and lower bounds.
229			* The resulting amount and bounds are rounded to the significant number of
230			* digits. Note that for exact quantities (with at least one bound equal to
231			* the amount), no rounding is applied (since they are considered to have
232			* infinite precision).
233			*
234			* The transformation is provided as a callback, which must implement a
235			* monotonously increasing, fully differentiable function mapping a DecimalValue
236			* to a DecimalValue. Typically, it will be a linear transformation applying a
237			* factor and an offset.
238			*
239			* @param string $newUnit The unit of the transformed quantity.
240			*
241			* @param callable $transformation A callback that implements the desired transformation.
242			* The transformation will be called three times, once for the amount, once
243			* for the lower bound, and once for the upper bound. It must return a DecimalValue.
244			* The first parameter passed to $transformation is the DecimalValue to transform
245			* In addition, any extra parameters passed to transform() will be passed through
246			* to the transformation callback.
247			*
248			* @param mixed ... Any extra parameters will be passed to the $transformation function.
249			*
250			* @throws InvalidArgumentException
251			* @return self
252			*/
253			public function transform( $newUnit, $transformation ) {
254			if ( !is_callable( $transformation ) ) {
255			throw new InvalidArgumentException( '$transformation must be callable.' );
256			}
257
258			if ( !is_string( $newUnit ) ) {
259			throw new InvalidArgumentException( '$newUnit must be a string. Use "1" as the unit for unit-less quantities.' );
260			}
261
262			if ( $newUnit === '' ) {
263			throw new InvalidArgumentException( '$newUnit must not be empty. Use "1" as the unit for unit-less quantities.' );
264			}
265
266			$oldUnit = $this->unit;
267
268			if ( $newUnit === null ) {
269			$newUnit = $oldUnit;
270			}
271
272			// Apply transformation by calling the $transform callback.
273			// The first argument for the callback is the DataValue to transform. In addition,
274			// any extra arguments given for transform() are passed through.
275			$args = func_get_args();
276			array_shift( $args );
277
278			$args[0] = $this->amount;
279			$amount = call_user_func_array( $transformation, $args );
280
281			// use a preliminary QuantityValue to determine the significant number of digits
282			return new self( $amount, $newUnit );
283			}
284
285			public function __toString() {
286			return $this->amount->getValue()
287			. ( $this->unit === '1' ? '' : $this->unit );
288			}
289
290			/**
291			* @see DataValue::getArrayValue
292			*
293			* @since 0.1
294			*
295			* @return array
296			*/
297			public function getArrayValue() {
298			return array(
299			'amount' => $this->amount->getArrayValue(),
300			'unit' => $this->unit,
301			);
302			}
303
304			/**
305			* Constructs a new instance of the DataValue from the provided data.
306			* This can round-trip with @see getArrayValue
307			*
308			* @since 0.1
309			*
310			* @param mixed $data
311			*
312			* @return self
313			* @throws IllegalValueException
314			*/
315			public static function newFromArray( $data ) {
316			self::requireArrayFields( $data, array( 'amount', 'unit' ) );
317
318			return new static(
319			DecimalValue::newFromArray( $data['amount'] ),
320			$data['unit']
321			);
322			}
323
324			/**
325			* @see Comparable::equals
326			*
327			* @since 0.1
328			*
329			* @param mixed $target
330			*
331			* @return bool
332			*/
333			public function equals( $target ) {
334			if ( $this === $target ) {
335			return true;
336			}
337
338			return $target instanceof self
339			&& $this->toArray() === $target->toArray();
340			}
341
342			}
343

DataValues / Number

Pull Request — master (#66)

QuantityValue::newFromDecimal() A

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like