Download the PHP package code-distortion/realnum without Composer

RealNum

code-distortion/realnum is a PHP library for arbitrary-precision floating-point maths with locale-aware formatting. It integrates with Laravel 5 - 9 but works stand-alone as well.

Here is an example of why you might want arbitrary precision calculations:

The Percent class is also available alongside the RealNum class to perform all of the same actions as RealNum but for percentage values. See the percentage values section below for more details.

If you would like to work with currency values, please consider the code-distortion/currency package.

Installation

Install the package via composer:

Usage

Instantiate a RealNum object and you can start performing calculations with it, perform comparisons, and render it as a readable string:

Setting values

You may set the value explicitly:

The types of values you can pass to RealNum are:

TIP: To maintain precision when passing values, pass them as strings instead of floating-point numbers:

You may also set other settings that RealNum uses:

Retrieving values

To retrieve the value contained in a RealNum you may read the val and cast properties. The val property maintains precision and in contrast, cast will loose some precision so use them depending on your needs:

You may also read other settings that RealNum uses:

Note: See the formatting output section below for more details about how to render the value as a readable string.

Calculations

The calculations available are:

The add(), sub(), div() and mul() methods accept multiple values:

Integer, float, numeric string and null values, as well as other RealNum objects may be passed:

Comparisons

You can compare numbers to other values with bound checking:

You may pass multiple values to these comparison methods. eg.

You can check if a RealNum's value is between given bounds:

And you can check if the value is null:

Formatting output

Use the format() method to generate a readable-string version of the current value:

You may alter the way format() renders the output by passing options. The options you can alter are:

null=x, trailZeros, decPl=x, thousands, showPlus, accountingNeg, locale=x and breaking.

Boolean options (those without an equals sign) can be negated by adding ! before it.

Note: format() options are processed using the code-distortion/options package so they may be passed as expressive strings or associative arrays.

Multiple settings can be used together:

Casting a RealNum to a string is equivalent to calling format() with no arguments:

NOTE: RealNum uses PHP's NumberFormatter to render the readable output, which currently has a limitation of being able to only show about 17 digits (including before the decimal place). So format()'s output will act a bit strangely if there are too many digits. The number stored inside will maintain its full accuracy, however. You may access the full number by reading the val property (see the retrieving values section above).

Default format settings

RealNum uses these default settings when format() is called: "null=null !trailZeros decPl=null thousands !showPlus !accountingNeg locale=en !breaking"

Note: When using Laravel you may change this in the package config file. See the Laravel section below.

Note: format() options are processed using the code-distortion/options package so they may be passed as expressive strings or associative arrays.

These can be adjusted per-object:

The default format-settings can be adjusted. All new RealNum objects will then start with this setting:

Locale

Note: When using Laravel this will be set automatically. See the Laravel section below.

RealNum's default locale is "en" (English) but you can choose which one to use.

You may choose the locale at the time of formatting:

You may change the locale per-object:

The default locale may be changed. All new RealNum objects will then start with this setting:

Precision (maximum decimal places)

Note: When using Laravel you may change this in the package config file. See the Laravel section below.

The maxDecPl precision setting is the maximum number of decimal places you would like RealNum to handle. A maxDecPl of 20 is used by default but you may change this per-object:

The default precision may be changed. All new RealNum objects will then start with this setting:

Immutability

Note: When using Laravel you may change this in the package config file. See the Laravel section below.

RealNum is immutable by default which means that once an object is created it won't change. Anything that changes its contents will return a new RealNum instead. This way you can pass a RealNum object to other parts of your code and be sure that it won't be changed unexpectedly:

Immutability may be turned off per-object:

Immutability may be turned off by default. All new RealNum objects will then start with this setting:

You can explicitly make a clone of a RealNum object:

Non-breaking whitespace

Some locales use spaces when rendering numbers (eg. Swedish uses spaces for the thousands separator). format() can return strings containing either non-breaking whitespace characters, or regular space characters.

An example of non-breaking whitespace is UTF-8's \xc2\xa0 character which is used instead of a regular \x20 space character. There are others like \xe2\x80\xaf which is a 'narrow no-break space'.

The \xc2\xa0 UTF-8 character will become the familiar   when turned into an html-entity.

Because format() is designed to produce readable numbers for humans, RealNum uses non-breaking whitespace by default, but you can instruct it to return regular spaces:

Tip: The non-breaking whitespace setting can be changed per-object and by default. See the default format settings sections above.

Chaining

The setting and calculation methods above may be chained together. eg.

Percentage values

Whilst the RealNum class is used for normal floating-point numbers, you may use the Percent class to perform all of the same actions as RealNum, but for percentage values. The difference is in the values you pass to Percent, and its format() output will show the percent symbol:

You can also use Percent objects with RealNums:

Laravel

The RealNum package is framework agnostic and works well on its own, but it also integrates with Laravel 5, 6, 7, 8 & 9.

Service-provider

RealNum integrates with Laravel 5.5+ automatically thanks to Laravel's package auto-detection.

Laravel's locale is registered with RealNum and Percent, and updated later if it changes.

Config

You may specify default max-dec-pl, immutability and format-settings by publishing the config/code-distortion.realnum.php config file and updating it:

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

SemVer

This library uses SemVer 2.0.0 versioning. This means that changes to X indicate a breaking change: 0.0.X, 0.X.y, X.y.z. When this library changes to version 1.0.0, 2.0.0 and so forth, it doesn't indicate that it's necessarily a notable release, it simply indicates that the changes were breaking.

Treeware

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Contributing

Please see CONTRIBUTING for details.

Code of Conduct

Please see CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Tim Chandler

License

The MIT License (MIT). Please see License File for more information.