Percentage calculations made easy.

Add Percentage to your Gradle build script:

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.eriksencosta.math:percentage:0.3.0")
}

If you’re using Maven, add to your POM xml file:

<dependency>
    <groupId>com.eriksencosta.math</groupId>
    <artifactId>percentage</artifactId>
    <version>0.3.0</version>
</dependency>

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

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

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))

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))

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?”

The UsageExamples file has more examples of calculations using the Percentage library.

Read the API documentation for further details.

The Apache Software License, Version 2.0