Skip to content

Commit

Permalink
Updates README with examples
Browse files Browse the repository at this point in the history
  • Loading branch information
@elliotjreed
elliotjreed committed Dec 3, 2023
1 parent 8450c6c commit 816ce73
Showing 1 changed file with 310 additions and 13 deletions.
323 changes: 310 additions & 13 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,313 @@
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](code-of-conduct.md)

# maths
# Maths

## Getting Started
This PHP package provides an object-oriented wrapper for `bcmath` functionality and other common operations for dealing with numbers.

One aim of this project is to provide a greater degree of accuracy when dealing with floating point numbers.

## Usage

There are two base classes, `Number` and `NumberImmutable`.

Both can take any numeric value in the constructor (i.e. a numeric string such as `'1.5'`, an integer such as `150`, a float such as `1.33`, or a scientific notation string such as `'8.431e-05'`).

The result can be returned as a string, integer, or float.

For an example of the differences between `Number` and `NumberImmutable`:

```php
use ElliotJReed\Maths\NumberImmutable;
use ElliotJReed\Maths\Number;

$numberImmutable = new NumberImmutable(10);
$newNumberImmutable = $number->multiply(3);
$numberImmutable->asFloat(); // 10.0
$newNumberImmutable->asFloat(); // 30.0

$number = new Number(15);
$newNumber = $number->multiply(3);
$number->asFloat(); // 45.0
$newNumber->asFloat(); // 45.0
```

### Number

The `Number` object is mutable.

Examples:

```php
use ElliotJReed\Maths\Number;

$number = new Number('123.5');

$number->multiply(2);
$number->add(3);
$number->divide(10);
$number->subtract(20);

$number->asFloat(); // 25.0
$number->asInteger(); // 25
$number->asString(); // '25'
$number->asString(1); // '25.0'
$number->asString(2); // '25.00'
$number->asString(3); // '25.000'

$number->isEqualTo(25); // true
$number->isLessThan(30); // true
$number->isGreaterThan(20); // true
$number->isGreaterThanOrEqualTo(25); // true
$number->isLessThanOrEqualTo(25); // true
$number->isZero(); // false
```

```php
use ElliotJReed\Maths\Number;

$number = new Number(123.5);

$number->multiply(2)->add(3)->divide(10)->subtract(20);

$number->asFloat(); // 25.0
$number->asInteger(); // 25
$number->asString(); // '25'
```

Numbers can be `int`, `float`, `string`, or instances of Number`.

```php
use ElliotJReed\Maths\Number;

$number = new Number(123.5);

$number->multiply(new Number(2));
$number->add('3');
$number->divide(10.0);
$number->subtract(20);

$number->asFloat(); // 25.0
$number->asInteger(); // 25
$number->asString(); // '25'
```

```php
use ElliotJReed\Maths\Number;

$number = new Number(1.125);

$number->roundToDecimalPlaces(2);

$number->asFloat(); // 1.13
$number->asInteger(); // 1
$number->asString(); // '1.13'
```

```php
use ElliotJReed\Maths\Number;

$number = new Number(25);

$number->squareRoot();

$number->asFloat(); // 5.0
$number->asInteger(); // 5
$number->asString(); // '5'
```

```php
use ElliotJReed\Maths\Number;

$number = new Number(5);

$number->raiseToPower(2);

$number->asFloat(); // 5.0
$number->asInteger(); // 5
$number->asString(); // '5'
```

```php
use ElliotJReed\Maths\Number;

$number = new Number('25');

$number->increaseByPercentage(10);

$number->asFloat(); // 27.5
$number->asInteger(); // 28
$number->asInteger(PHP_ROUND_HALF_DOWN); // 27
$number->asString(); // '27.5'
$number->asString(2); // '27.50'
```

```php
use ElliotJReed\Maths\Number;

$number = new Number(5.5);

$number->modulus(2.5);

$number->asFloat(); // 0.5
$number->asInteger(); // 1
$number->asInteger(PHP_ROUND_HALF_DOWN); // 0
$number->asString(); // '0.5'
$number->asString(2); // '0.50'
```

```php
use ElliotJReed\Maths\Number;

$number = new Number('8.431e-05');

$number->asFloat(); // 0.00008431
$number->asString(); // '0.00008431'
```

### NumberImmutable

The `NumberImmutable` class is immutable.

Examples:

```php
use ElliotJReed\Maths\NumberImmutable;

$number = new NumberImmutable('123.5');

$number = $number->multiply(2);
$number = $number->add(3);
$number = $number->divide(10);
$number = $number->subtract(20);

$number->asFloat(); // 25.0
$number->asInteger(); // 25
$number->asString(); // '25'
$number->asString(1); // '25.0'
$number->asString(2); // '25.00'
$number->asString(3); // '25.000'

$number->isEqualTo(25); // true
$number->isLessThan(30); // true
$number->isGreaterThan(20); // true
$number->isGreaterThanOrEqualTo(25); // true
$number->isLessThanOrEqualTo(25); // true
$number->isZero(); // false
```

```php
use ElliotJReed\Maths\NumberImmutable;

$number = new NumberImmutable(123.5);

$number = $number->multiply(2)->add(3)->divide(10)->subtract(20);

$number->asFloat(); // 25.0
$number->asInteger(); // 25
$number->asString(); // '25'
```

Numbers can be `int`, `float`, `string`, or instances of Number`.

```php
use ElliotJReed\Maths\Number;

$number = new Number(123.5);

$number->multiply(new Number(2));
$number->add('3');
$number->divide(10.0);
$number->subtract(20);

$number->asFloat(); // 25.0
$number->asInteger(); // 25
$number->asString(); // '25'
```

```php
use ElliotJReed\Maths\NumberImmutable;

$number = new NumberImmutable(1.125);

$number = $number->roundToDecimalPlaces(2);

$number->asFloat(); // 1.13
$number->asInteger(); // 1
$number->asString(); // '1.13'
```

```php
use ElliotJReed\Maths\NumberImmutable;

$number = new NumberImmutable(25);

$number = $number->squareRoot();

$number->asFloat(); // 5.0
$number->asInteger(); // 5
$number->asString(); // '5'
```

```php
use ElliotJReed\Maths\NumberImmutable;

$number = new NumberImmutable(5);

$number = $number->raiseToPower(2);

$number->asFloat(); // 5.0
$number->asInteger(); // 5
$number->asString(); // '5'
```

```php
use ElliotJReed\Maths\NumberImmutable;

$number = new NumberImmutable('25');

$number = $number->increaseByPercentage(10);

$number->asFloat(); // 27.5
$number->asInteger(); // 28
$number->asInteger(PHP_ROUND_HALF_DOWN); // 27
$number->asString(); // '27.5'
$number->asString(2); // '27.50'
```

```php
use ElliotJReed\Maths\NumberImmutable;

$number = new NumberImmutable(5.5);

$number = $number->modulus(2.5);

$number->asFloat(); // 0.5
$number->asInteger(); // 1
$number->asInteger(PHP_ROUND_HALF_DOWN); // 0
$number->asString(); // '0.5'
$number->asString(2); // '0.50'
```

```php
use ElliotJReed\Maths\NumberImmutable;

$number = new NumberImmutable('8.431e-05');

$number->asFloat(); // 0.00008431
$number->asString(); // '0.00008431'
```

## Development

### Getting Started

PHP 8.1 or above and Composer is expected to be installed.

### Installing Composer
#### Installing Composer

For instructions on how to install Composer visit [getcomposer.org](https://getcomposer.org/download/).

### Installing
#### Installing

After cloning this repository, change into the newly created directory and run:

Expand All @@ -28,9 +325,9 @@ This will install all dependencies needed for the project.

Henceforth, the rest of this README will assume `composer` is installed globally (ie. if you are using `composer.phar` you will need to use `composer.phar` instead of `composer` in your terminal / command-line).

## Running the Tests
### Running the Tests

### Unit tests
#### Unit tests

Unit testing in this project is via [PHPUnit](https://phpunit.de/).

Expand All @@ -40,15 +337,15 @@ All unit tests can be run by executing:
composer phpunit
```

#### Debugging
##### Debugging

To have PHPUnit stop and report on the first failing test encountered, run:

```bash
composer phpunit:debug
```

## Code formatting
### Code formatting

A standard for code style can be important when working in teams, as it means that less time is spent by developers processing what they are reading (as everything will be consistent).

Expand All @@ -61,7 +358,7 @@ These can be run by executing:
composer phpcs
```

### Running everything
#### Running everything

All of the tests can be run by executing:

Expand All @@ -77,15 +374,15 @@ Checking for outdated Composer dependencies can be performed by executing:
composer outdated
```

### Validating Composer configuration
#### Validating Composer configuration

Checking that the [composer.json](composer.json) is valid can be performed by executing:

```bash
composer validate --no-check-publish
```

### Running via GNU Make
#### Running via GNU Make

If GNU [Make](https://www.gnu.org/software/make/) is installed, you can replace the above `composer` command prefixes with `make`.

Expand All @@ -95,7 +392,7 @@ All of the tests can be run by executing:
make test
```

### Running the tests on a Continuous Integration platform (eg. Github Actions)
#### Running the tests on a Continuous Integration platform (eg. Github Actions)

Specific output formats better suited to CI platforms are included as Composer scripts.

Expand All @@ -111,7 +408,7 @@ To output PHP-CS-Fixer (dry run) and PHPCS results in checkstyle format (which G
composer phpcs:ci
```

#### Github Actions
##### Github Actions

Look at the example in [.github/workflows/main.yml](.github/workflows/main.yml).

Expand Down

0 comments on commit 816ce73

Please sign in to comment.