# percentages

> Percentages: a JavaScript and PHP class for calculating percentages and rounding them through the largest remainder method

Latest version **3.0.0** (published 2019-11-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install percentages
pnpm add percentages
yarn add percentages
bun add percentages
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2019-11-21 |
| First published | 2019-11-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 990.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | FrisFruitig |
| Maintainers | frisfruitig |
| Keywords | percent, percentage, percentages, %, largest remainder, js, javascript, module, es6, php |

## Links

- npm: https://www.npmjs.com/package/percentages
- Repository: https://github.com/frisfruitig/Percentages
- Issues: https://github.com/frisfruitig/Percentages/issues
- npm.io page: https://npm.io/package/percentages

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 3.0.0 (latest) — 2019-11-21
- 2.1.1 — 2019-11-18
- 2.1.0 — 2019-11-18
- 2.0.1 — 2019-11-11
- 2.0.0 — 2019-11-11

## README

# Percentages

![NPM Version](https://img.shields.io/npm/v/percentages)

A small `JavaScript` and `PHP` class for calculating percentages that solves rounding issues.

## How does it work

Both `Percentages.js` and `class-percentages.php` use the principle of the [largest remainder method](https://en.wikipedia.org/wiki/Largest_remainder_method). Each percentage will be rounded down at first. After that, the script will add 1 percent to a rounded value if this value has the highest remainder. This process continues until a total of 100% is reached.

Both the JS and PHP classes return (1) absolute percentages, (2) rounded percentages and (3) the corrected percentages, as well as (4) the sum of the rounded percentages and (5) the sum of the corrected percentages, which should always be `100`.

_Note: because the scripts loop through remainders until a total of 100% is reached, a difference of 1% can occur between two of the same input values. See the last example below._

## Installation

### Install with NPM

```
$ npm install percentages
```

### Include files

Include the `JavaScript` or `PHP` file.

## Examples

### JavaScript example

```javascript
// For comparison reasons, the function returns more than the corrected percentages
const Percentages = require('percentages');
const votes = [12, 30, 2, 7, 15];
const percentages = new Percentages(votes);

// Most likely, you only want to use the corrected percentages
// Use this instead:
const Percentages = require('percentages');
const votes = [12, 30, 2, 7, 15],
const votesPercentages = new Percentages(votes).corrected;
```

### PHP example

```php
// For comparison reasons, the function returns more than the corrected percentages
require_once 'path/to/class-percentages.php';
use FrisFruitig\Percentages as Percentages;

$votes         = array( 12, 30, 2, 7, 15 );
$percentages   = new Percentages( $votes );
$everything    = $percentages->get();

// The class supports methods to get the absolute, rounded or corrected percentages values directly, too.
$corrected     = $percentages->get_corrected();

// Additionally, it can return the sum of the rounded and corrected percentages. Obviously, the latter is always `100`. For example:
$corrected_sum = $percentages->get_corrected_sum();
```

### Rounding issue example

As said above: because the scripts loop through remainders until a total of 100% is reached, a difference of 1% can occur between two of the same input values.

```php
// Note: `require_once` and `use` omitted in this example.
$votes       = array( 1, 1, 1, 1, 1, 1 );
$percentages = new Percentages();
$percentages = $percentages->get_corrected(); // output: array( 17, 17, 17, 17, 16, 16 )
```

### Bundled example

This project comes with an example that relies on both the PHP and JavaScript class. To run it, create a host through software like XAMPP or MAMP and run the following command:

```
npm run example
```

## Testing

Run automated tests with command line.

### JavaScript

_This requires [jasmine](https://github.com/jasmine/jasmine), which is installed as a devDependency._
```
$ npm run test
```

### PHP

_This requires [PHPUnit](https://github.com/sebastianbergmann/phpunit)._

```
$ cd tests
$ phpunit
```

---
_Source: https://npm.io/package/percentages · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._