Type-safe dimensional analysis and unit conversion in Kotlin.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
demo
plugin
.gitignore
.travis.yml
LICENSE
README.md

README.md

units-of-measure

A DSL for type-safe dimensional analysis and unit conversion in Kotlin.

Usage

Please look at this sample code for DSL usage. Configuration documentation can be found on the wiki.

Gradle Installation

In ./build.gradle:

buildscript {
    repositories {
        maven { url 'http://repo.kunalsheth.info/' }
    }
    dependencies {
        classpath 'info.kunalsheth.units:plugin:4.0.3'
    }
}
apply plugin: 'info.kunalsheth.units.gradle'

apply from: 'units-of-measure.gradle'

In ./units-of-measure.gradle:

generateUnitsOfMeasure {
    // do all configuration here
}
sourceSets.main.kotlin.srcDir generateUnitsOfMeasure.generatedSrcDir
compileKotlin.dependsOn(generateUnitsOfMeasure) // may vary

Background

Type-safe dimensional analysis and unit conversion can be extremely beneficial to a team. From personal experience, using type-safe calculations result in:

  • Faster Development — IDE autocomplete provides meaningful predictions, rather than just listing every number in scope.
  • Cleaner Code — Variable names will be of a reasonable length now that unit information is documented by the type.
  • Higher Confidence — All unit/dimension related bugs will show up at compile time. Debugging is less difficult and time-consuming.

units-of-measure's novel, metaprogramming approach to the problem makes it:

  1. Incredibly Extendable — Adding new functionality is as simple as adding a line to your build file. No tedious "hand-coding" is required.
  2. Small — You only generate what you need. You are not forced to bundle every conceivable unit, quantity, and dimension with your app.
  3. Bug Resistant — Programming by hand is error prone and time-consuming. Code generation can ensure correctness.

Todo List

  • Make it work.
  • Generate implicit relationships as well.
  • Make annotations easier to write and manage.
  • Add support for unit conversions.
  • Add docs. (wiki)
  • Add metric prefixes.
  • Multiplatform.
  • Stronger support for generic use (Quantity<This, IntegralOfThis, DerivativeOfThis>)
  • Generic reciprocal functions?
  • Optimize for faster compilation and runtime.
  • Benchmark performance hit in contrast to primitives. (Can someone help me with this?)