Displaying numbers with singular or plural units

README.md

Display numbers with units in singular or plural form

fun Int.units(singular: String, plural: String): String

fun Long.units(singular: String, plural: String): String

These extension functions can be used to display a number with its units. The functions take the singular form of the unit (required) and an optional plural form.

@param - singular (required)

The singular form of the unit of measure.

Examples: "inch", "foot", "yard", "meter", "watt", "mile", "hertz"

@param - plural (optional)

The plural form of the unit of measure. This is an optional parameter and will default to the singular form with an 's' added to the end.

Alternative, you may use any of the shorthand notations described below.

Examples: "inches", "feet", "yards", "meters", "watts", "miles", "hertz", "+es", "-ies", "*"

Shorthand notations for plural form

"*" - Use this shorthand when the plural is the same as the singular, as with "elk" and "moose", for example.

"+suffix" - Use this shorthand to get the plural form by appending the given suffix to the singular form. For example, "+es" will add "es" to the singular form "inch" to get "inches". The default value for plural is "+s".

"-suffix" - Use this shorthand to get the plural form by dropping the last letter of the singular form then appending the given suffix. For example, "-ies" will first drop the last 'y' from "royalty" then append "ies" to get the plural "royalties".

Examples

Specifying plural form explicitly

for (i in 1..3) println("""${i.units("inch", "inches")}""")
// 1 inch
// 2 inches
// 3 inches

for (i in 1..3) println("""${i.units("ox", "oxen")}""")
// 1 ox
// 2 oxen
// 3 oxen

for (i in 1..3) println("""${i.units("man", "men")}""")
// 1 man
// 2 men
// 3 men

for (i in 1..3) println("""${i.units("deer", "deer")}""")
// 1 deer
// 2 deer
// 3 deer

for (i in 1..3) println("""${i.units("moose", "moose")}""")
// 1 moose
// 2 moose
// 3 moose

Default plural form adds 's' suffix to singular form

for (i in 1..3) println("""${i.units("parsec")}""")
// 1 parsec
// 2 parsecs
// 3 parsecs

for (i in 1..3) println("""${i.units("meter")}""")
// 1 meter
// 2 meters
// 3 meters

Use "+" shorthand to specify a suffix to the singular form

for (i in 1..3) println("""${i.units("inch", "+es")}""")
// 1 inch
// 2 inches
// 3 inches

for (i in 1..3) println("""${i.units("ox", "+en")}""")
// 1 ox
// 2 oxen
// 3 oxen

Use "-" shorthand to specify a suffix after dropping last letter of the singular form

for (i in 1..3) println("""${i.units("frequency", "-ies")}""")
// 1 frequency
// 2 frequencies
// 3 frequencies

for (i in 1..3) println("""${i.units("berry", "-ies")}""")
// 1 berry
// 2 berries
// 3 berries

for (i in 1..3) println("""${i.units("agency", "-ies")}""")
// 1 agency
// 2 agencies
// 3 agencies

Use "*" shorthand to specify same singular and plural form

for (i in 1..3) println("""${i.units("deer", "*")}""")
// 1 deer
// 2 deer
// 3 deer

for (i in 1..3) println("""${i.units("moose", "*")}""")
// 1 moose
// 2 moose
// 3 moose

Some other possible uses

for (i in 1..3) println("""Generate cards with ${i.units("randomly-chosen pick")}""")
// Generate cards with 1 randomly-chosen pick
// Generate cards with 2 randomly-chosen picks
// Generate cards with 3 randomly-chosen picks

for (1 in 1..3) println("""${i.units("randomly-selected card with 5 picks.", "randomly-selected cards with 5 picks each.")}""")
// 1 randomly-selected card with 5 picks.
// 2 randomly-selected cards with 5 picks each.
// 3 randomly-selected cards with 5 picks each.

DisplayNumbers.kt

/*
   MIT License

   Copyright (c) 2024 Junilu Lacar
   
   Full license text: https://spdx.org/licenses/MIT.html
*/
 
private fun plural(value: String, singular: String, plural: String) =
    when {
        plural == "*" -> "$value $singular"
        plural.startsWith("+") -> "$value ${singular}${plural.drop(1)}"
        plural.startsWith("-") -> "$value ${singular.dropLast(1)}${plural.drop(1)}
        else -> "$value $plural"
    }
    
fun Int.units(singular: String, plural: String = "+s") = 
    when (this) {
        1 -> "$this $singular"
        else -> plural("$this", singular, plural)
    }

fun Long.units(singular: String, plural: String = "+s") = 
    when (this) {
        1L -> "$this $singular"
        else -> plural("$this", singular, plural)
    }

DisplayNumbersTest.kt

/*
   MIT License
   Copyright (c) 2024 Junilu Lacar
   
   Full license text: https://spdx.org/licenses/MIT.html
*/

import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.DisplayName
import org.junit.jupiter.api.Test
import org.junit.jupiter.params.ParameterizedTest
import org.junit.jupiter.params.provider.CsvSource

@DisplayName("The units() extension functions")
class DisplayNumberUnitsTest {

    @ParameterizedTest
    @CsvSource(useHeadersInDisplayName = true, textBlock =
        """
        singular,    plural,    display1,   display2
        inch,        inches,    1 inch,     2 inches
        elk,         elk,       1 elk,      2 elk
        mouse,       mice,      1 mouse,    2 mice
        moose,       moose,     1 moose,    2 moose"""
    )
    fun `display correct singular and plural forms`(singular: String, plural: String, display1: String, display2: String) {
        assertEquals(display1, 1.units(singular, plural))
        assertEquals(display2, 2.units(singular, plural))
    }

    @Test
    fun `by default adds s to singular for plural form`() {
        assertEquals("1 sec", 1.units("sec"))
        assertEquals("2 secs", 2.units("sec"))
    }

    @Test
    fun `recognize plus as shorthand to append suffix for plural form`() {
        assertEquals("1 inch", 1.units("inch", "+es"))
        assertEquals("2 inches", 2.units("inch", "+es"))
    }

    @Test
    fun `recognize minus as shorthand to append suffix after dropping last letter of singular form`() {
        assertEquals("1 berry", 1.units("berry", "-ies"))
        assertEquals("2 berries", 2.units("berry", "-ies"))
    }

    @Test
    fun `recognize asterisk as shorthand to use same unit for singular and plural forms`() {
        assertEquals("1 elk", 1.units("elk", "*"))
        assertEquals("2 elk", 2.units("elk", "*"))
    }
}

LICENSE

MIT License

Copyright (c) 2024 Junilu Lacar

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.