Awesome
Percentage
Percentage calculations made easy.
Installation
Add Percentage to your Gradle build script:
repositories {
mavenCentral()
}
dependencies {
implementation("com.eriksencosta.math:percentage:0.2.0")
}
If you're using Maven, add to your POM xml file:
<dependency>
<groupId>com.eriksencosta.math</groupId>
<artifactId>percentage</artifactId>
<version>0.2.0</version>
</dependency>
Percentage is not compatible with the Android SDK at the moment.
Usage
The library provides the Percentage type: an immutable and thread-safe class that makes percentage calculations easy.
150 * 5.5.percent() // 8.25
150 decreaseBy 5.5.percent() // 141.75
150 increaseBy 5.5.percent() // 158.25
Under the hood, all calculations are done by the immutable and thread-safe Percentage class. You can always query for
the percentage's original value, and its decimal representation (i.e., its value divided by 100):
val percentage = 5.5.percent()
percentage.decimal // 0.055
percentage.value // 5.5
Rounding
If you need to round the resulting calculations using a Percentage, just pass an instance of the Rounding class to
the percent() method. Use the Rounding.to() factory method to create the object, passing the number of decimal
places and the desired rounding mode:
val percentage = 11.603773.percent()
val roundsFloor = 11.603773.percent(Rounding.to(2, RoundingMode.FLOOR))
val value = 127
value * percentage // 14.73679171
value * roundsFloor // 14.73
The rounding mode to use is defined by one of RoundingMode enum values. If you need to use HALF_EVEN, just pass the
number of desired decimal places:
val roundsHalfUp = 11.603773.percent(2)
value * roundsHalfUp // 14.74
Other utilities
Create a Percentage based on a ratio
To create a Percentage based on a ratio (e.g. 1/2, 1/3, 1/4, and so on), use the ratioOf() function:
1 ratioOf 4 // 25%
1 ratioOf 3 // 33.33%
The function also has overloaded versions to control the rounding strategy of the returned Percentage object:
// rounds using 2 decimal places and with RoundingMode.HALF_EVEN
1.ratioOf(3, 2)
// rounds using 2 decimal places and with RoundingMode.UP
1.ratioOf(3, Rounding.to(2, RoundingMode.UP))
Calculate the relative change as a Percentage for two numbers
To calculate the relative change between two numbers, use the relativeChange() function:
1 relativeChange 3 // 200%
3 relativeChange 1 // -66.67%
The function also has overloaded versions to control the rounding strategy of the returned Percentage object:
// rounds using 2 decimal places and with RoundingMode.HALF_EVEN
3.relativeChange(1, 2)
// rounds using 2 decimal places and with RoundingMode.UP
3.relativeChange(1, Rounding.to(2, RoundingMode.UP))
Calculate the base value of a number when it's a given Percentage
To calculate the base value of a number when it's a given Percentage, use the valueWhen() function:
5 valueWhen 20.percent() // 25.0
In other words, the function helps to answer the question "5 is 20% of what number?"
Code examples
The UsageExamples file has more examples of calculations using the Percentage library.
API documentation
Read the API documentation for further details.