Práca s NumericValueAsString

Všetky číselné výsledky sú hodnotové objekty NumericValueAsString nad presným reťazcom bcmath. Vytvoríte ich pomenovaným konštruktorom ::of() — prehľadnejšie ako cez new:

use RoundlyConsulting\TradingAnalytics\DataTransferObjects\NumericValueAsString;

NumericValueAsString::of('1.005')->round(2)->toRawString();  // '1.01' — half away from zero
NumericValueAsString::of('1.005', scale: 2)->toRawString();  // '1.00' — the scale truncates
NumericValueAsString::of('1e-5')->toRawString();             // '0.0000100000'
NumericValueAsString::of(0.00001)->toRawString();            // '0.0000100000' — floats expand exactly

$value = NumericValueAsString::of('21', scale: 2);
(string) $value->withSuffix('USD');  // '21.00 USD'
$value->toFloat();                   // 21.0, when you explicitly want a float
$value->toInt();                     // 21

Vstup sa číta presne: číselné reťazce (aj s medzerami okolo), celé čísla, floaty aj exponenciálny zápis ('1.5e-3', 0.00001) sa pred výpočtom v bcmath rozvinú na obyčajné desatinné čísla.

Aritmetika a meniteľnosť

add(), subtract(), multiply(), divide(), pow() a abs() menia hodnotu na mieste a vracajú ju, takže sa dajú reťaziť. S immutable: true dostanete namiesto toho novú inštanciu — používajte to pri počítaní s výsledkami enginu, aby samotné výsledky zostali nedotknuté:

$a = NumericValueAsString::of('10.50', scale: 2);

$a->add(1)->subtract('0.5')->multiply(2);  // mutates $a in place and chains
$a->toRawString();                         // '22.00'

$b = $a->divide(4, immutable: true);       // a new instance; $a is unchanged
$b->toRawString();                         // '5.50'

$a->pow(2, immutable: true);               // '484.00' — integer exponents only
NumericValueAsString::of('-3.25', scale: 2)->abs()->toRawString(); // '3.25'

round($scale) zaokrúhľuje polovicu smerom od nuly (samotné bcmath len oreže) a prepne hodnotu na novú škálu.

Porovnania

$v = NumericValueAsString::of('0.75', scale: 4);

$v->isGreaterThan('0.5');       // true
$v->isLessThanOrEqualTo(1);     // true
$v->equals('0.7500');           // true
$v->isZero();                   // false
$v->isPositiveNonZero();        // true

Sadu dopĺňajú isGreaterThanOrEqualTo(), isLessThan() a isNonZero(). Každé porovnanie prijme reťazec, int, float alebo iný NumericValueAsString.

Formátovanie na zobrazenie

Výsledok naformátujete na zobrazenie bez zmeny uloženej hodnoty nemennými pomocníkmi withPrefix() / withSuffix(), ktoré vrátia novú inštanciu. toString() (aj pretypovanie (string)) spojí predponu, hodnotu a príponu medzerami; toRawString() je vždy holé číslo:

$fees = $analytics->commission->global->total->total;

$fees->withSuffix('USD')->toString();    // '19.00 USD' — a new instance
$fees->withPrefix('Fees:')->toString();  // 'Fees: 19.00'
$fees->toString();                       // '19.00' — the original is unchanged

$fees->toArray();
// ['value' => '19.00', 'scale' => 2, 'prefix' => '', 'suffix' => '', 'formatted' => '19.00']

Ktoré hodnoty sa riadia škálou behu a ktoré majú pevnú, nájdete v sekcii Presnosť.

Prehľad metód

• of($value, scale: 10, prefix: '', suffix: '') — pomenovaný konštruktor; new NumericValueAsString(...) prijíma rovnaké pomenované argumenty.
• set($value, ?scale) — nahradí hodnotu; scale() / getScale() — zmení alebo vráti škálu.
• clone() / cloneWithScale($scale) — kópie hodnoty bez predpony a prípony.
• wasChanged() — či hodnotu naposledy zmenila aritmetická operácia.
• toString(), toRawString(), toInt(), toFloat(), toArray(), toJson().

Delenie nulou vyhodí DivisionByZeroException; nečíselný vstup ('abc', INF, NAN), exponent nad 1000 alebo neceločíselný exponent v pow() vyhodí InvalidNumericOperationException; záporná škála vyhodí InvalidScaleException.