Skip to content

Commit 4580f22

Browse files
hughgrigghughgrigg
committed
Fill out readme
1 parent c5fbb88 commit 4580f22

File tree

1 file changed

+245
-1
lines changed

1 file changed

+245
-1
lines changed

‎README.md

Lines changed: 245 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,255 @@
22

33
[![Build Status](https://travis-ci.org/hughgrigg/php-fraction.svg?branch=master)](https://travis-ci.org/hughgrigg/php-fraction)
44
[![Coverage Status](https://coveralls.io/repos/github/hughgrigg/php-fraction/badge.svg)](https://coveralls.io/github/hughgrigg/php-fraction)
5-
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/ef5b774bce624ab2b1f3632e9307a909)](https://app.codacy.com/app/hugh_2/php-fraction?utm_source=github.com&utm_medium=referral&utm_content=hughgrigg/php-fraction&utm_campaign=badger)
5+
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/4fb0b395bf914b5a8abe589210b26bcb)](https://app.codacy.com/app/hugh_2/php-fraction?utm_source=github.com&utm_medium=referral&utm_content=hughgrigg/php-fraction&utm_campaign=badger)
66
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/hughgrigg/php-fraction/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/hughgrigg/php-fraction/?branch=master)
77
[![StyleCI](https://styleci.io/repos/154997973/shield?branch=master)](https://styleci.io/repos/154997973)
88
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
99

1010
PHP fraction library with fraction simplification and float to fraction
1111
conversion.
1212

13+
## Installation
14+
15+
Install via Composer:
16+
17+
```bash
18+
composer require hughgrigg/php-fraction
19+
```
20+
21+
## Usage
22+
23+
Import the fraction class:
24+
25+
```php
26+
use Fraction\Fraction;
27+
```
28+
29+
### Creating fractions
30+
31+
Create fractions with the numerator and denominator:
32+
33+
```php
34+
$half = new Fraction(1, 2);
35+
$third = new Fraction(1, 3);
36+
$threeFifths = new Fraction(3, 5);
37+
$oneAndAQuarter = new Fraction(5, 4);
38+
```
39+
40+
### Simplifying fractions
41+
42+
Simplify fractions with the `simplified()` method:
43+
44+
```php
45+
$fiveTenths = new Fraction(5, 10);
46+
$simplified = $fiveTenths->simplified();
47+
// = new Fraction(1, 2)
48+
```
49+
50+
The fraction object is immutable, so the original instance is unchanged.
51+
52+
### Converting floats to fractions
53+
54+
Get a fraction from a float with the `FloatConversion` class:
55+
56+
```php
57+
use Fraction\FloatConversion;
58+
59+
$half = (new FloatConversion(0.5))->fraction();
60+
// = new Fraction(1, 2);
61+
```
62+
63+
#### Float conversion precision
64+
65+
You might not want arbitrary precision when converting a float to a fraction.
66+
For example, you might prefer that 0.249 is converted to 1/4, and not 249/1000.
67+
68+
You can do this by setting the precision on the float conversion. This sets the
69+
tolerance to use when finding the closest fraction for the float:
70+
71+
```php
72+
$almostAQuarter = (new FloatConversion(0.249))->withPrecision(0.1)->fraction();
73+
// = new Fraction(1, 4);
74+
75+
$almostAQuarter->withPrecision(0.01)->fraction();
76+
// = new Fraction(24, 100);
77+
78+
$almostAQuarter->withPrecision(0.001)->fraction();
79+
// = new Fraction(249, 1000);
80+
```
81+
82+
Again, the `FloatConversion` object is immutable, so the original instance is
83+
unchanged when doing this.
84+
85+
The default precision is 0.001 (one thousandth).
86+
87+
### Converting fractions to floats
88+
89+
You can get the float equivalent of a fraction with the `asFloat()` method:
90+
91+
```php
92+
$threeFifths = new Fraction(3, 5);
93+
$threeFifths->asFloat();
94+
// = 0.6
95+
96+
$oneThird = new Fraction(1, 3);
97+
$oneThird->asFloat();
98+
// = 0.33333333333333
99+
```
100+
101+
### Converting fractions to percentages
102+
103+
You can get the percentage equivalent of a fraction with the `float()` method:
104+
105+
```php
106+
$threeFifths = new Fraction(3, 5);
107+
$threeFifths->asPercentage();
108+
// = 60
109+
110+
$oneThird = new Fraction(1, 3);
111+
$oneThird->asPercentage();
112+
// = 33.333333333333
113+
```
114+
115+
### Fraction operations
116+
117+
You can apply various arithmetic operations to fractions. Note that the results
118+
are not simplified automatically, so you will need to use the `simplified()`
119+
method at the end of your calculations to get the simplified form of the result.
120+
121+
#### Addition
122+
123+
```php
124+
$half = new Fraction(1, 2);
125+
$third = new Fraction(1, 3);
126+
$sum = $half->add($third);
127+
// = new Fraction(5, 6)
128+
129+
$tenth = new Fraction(1, 10);
130+
$fifth = new Fraction(1, 5);
131+
$sum = $tenth->add($fifth);
132+
// = new Fraction(15,50)
133+
$sum->simplified();
134+
// = new Fraction(3, 10)
135+
```
136+
137+
#### Subtraction
138+
139+
```php
140+
$half = new Fraction(1, 2);
141+
$third = new Fraction(1, 3);
142+
$difference = $half->subtract($third);
143+
// = new Fraction(1,6)
144+
145+
$fifth = new Fraction(1, 5);
146+
$tenth = new Fraction(1, 10);
147+
$difference = $fifth->subtract($tenth)
148+
// = new Fraction(5, 50)
149+
$difference->simplified();
150+
// = new Fraction(1, 10)
151+
```
152+
153+
#### Multiplication
154+
155+
```php
156+
$half = new Fraction(1, 2);
157+
$third = new Fraction(1, 3);
158+
$product = $half->multiplyBy($third);
159+
// = new Fraction(1,6)
160+
161+
$twoFifths = new Fraction(2, 5);
162+
$tenth = new Fraction(1, 10);
163+
$product = $twoFifths->multiplyBy($tenth)
164+
// = new Fraction(2, 50)
165+
$product->simplified();
166+
// = new Fraction(1, 25)
167+
```
168+
169+
#### Division
170+
171+
```php
172+
$half = new Fraction(1, 2);
173+
$third = new Fraction(1, 3);
174+
$quotient = $half->divideBy($third);
175+
// = new Fraction(3,2)
176+
177+
$twoFifths = new Fraction(2, 5);
178+
$tenth = new Fraction(1, 10);
179+
$product = $twoFifths->multiply($tenth)
180+
// = new Fraction(2, 50)
181+
$difference->simplified();
182+
// = new Fraction(1, 25)
183+
```
184+
185+
#### Comparison
186+
187+
You can check strict equality of fractions with the `equals()` method:
188+
189+
```php
190+
$half = new Fraction(1, 2);
191+
$threeSixths = new Fraction(3, 6);
192+
$half->equals($threeSixths);
193+
// = true
194+
195+
$twoSixths = new Fraction(2, 6);
196+
$half->equals($twoSixths);
197+
// = false
198+
```
199+
200+
If you want to check with a loose precision, you can use the `equalsWithin()`
201+
method, which takes the other fraction and the precision to compare in:
202+
203+
```php
204+
$half = new Fraction(1, 2);
205+
$threeEights = new Fraction(3, 8);
206+
$half->equalsWithin($threeEights, 0.25);
207+
// = true
208+
```
209+
210+
### Fraction string conversion
211+
212+
The `__toString()` method on the `Fraction` class prints out the fraction using
213+
a slash for the divider:
214+
215+
```php
216+
$fraction = new Fraction(1, 3);
217+
$useInString = "The fraction is {$fraction}";
218+
// = 'The fraction is 1/3'
219+
220+
$fraction = new Fraction(8, 5);
221+
$useInString = "The fraction is {$fraction}";
222+
// = 'The fraction is 1 3/5'
223+
```
224+
225+
#### String conversion with unicode fractions
226+
227+
Unicode provides some entities for representing fractions directly as a single
228+
character. You can use these in string conversion with the `unicodeChars()` method:
229+
230+
```php
231+
$fraction = new Fraction(1, 3);
232+
$useInString = "The fraction is {$fraction->unicodeChars()}";
233+
// = 'The fraction is ⅓'
234+
235+
$fraction = new Fraction(8, 5);
236+
$useInString = "The fraction is {$fraction->unicodeChars()}";
237+
// = 'The fraction is 1 ⅗'
238+
```
239+
240+
There are not many of these fraction characters in Unicode. However, you can
241+
go further and build any fraction you want using Unicode subscripts and
242+
superscripts. These allow any arbitrary fraction, but are less likely to render
243+
as expected in different situations.
244+
245+
To convert to a string with Unicode superscripts and subscripts, use the
246+
`unicodeScripts()` method:
247+
248+
```php
249+
$fraction = new Fraction(1, 6);
250+
$useInString = "The fraction is {$fraction->unicodeScripts()}";
251+
// = 'The fraction is ¹⁄₆'
252+
253+
$fraction = new Fraction(10, 6);
254+
$useInString = "The fraction is {$fraction->unicodeChars()}";
255+
// = 'The fraction is 1 ⁴⁄₆'
256+
```

0 commit comments

Comments
 (0)