Skip to content

Latest commit

 

History

History
169 lines (124 loc) · 6.92 KB

units.md

File metadata and controls

169 lines (124 loc) · 6.92 KB
Raw

Units of Measure

Beer has become an international interest. Additionally, brewing spans across the commercial and home environments. As a result, the systems of measure and scales of measure can very greatly between brewers. The BeerXML spec clearly delineates what units of measure are to be used to storing and transmitting data; however, they also allow users to pass display formats for values. These are used to translate uniform, machine-friendly systems into more appropriate systems and scales based on geographic region and user case.

The brewtility.units namespace contains functions to convert between different systems and units of measure across several different types of measurement. Additionally, this namespace may be used to render common display formats.

The names of these systems and units are frequently used in code, and shorthand symbolic references to these names may be found in brewtility.units.options

Basic Use

The majority of the functionality belongs to the functions convert and display. This provides a consistent interface to every system of measure, unit type, and more.

(:require [brewtility.units :as units]
          [brewtility.units.options :as options]
          [brewtility.units.volume :as volume])

;; You can use the keys in `brewtility.units.options` as arguments.
;; This guarantees you don't have typos in code, and can link to helpful documentation
(units/convert units/volume 1.0 options/liter options/litre)
;; => 1.0

;; Or, if you prefer, bare keywords are accepted too
(units/convert units/volume 20 :teaspoon :liter)
;; => 0.099

;; If you only plan on dealing with volumes,
;;   then you can import the `brewtility.units.volume` namespace
(volume/convert 9.99209 :imperial-pint :american-pint)
;; => 12.0

;; You can also render display values
(units/display :volume 1.5 :liter)
;; => \"1.5 l\"

;; The keys in `brewtility.units.options` are also acceptable
(units/display options/volume 1.5 options/liter)
;; => \"1.5 l\"

;; You may supply additional options, such as the default precision for rounding
;;   and the type of suffix to use
(units/display options/volume 1.45 options/liter {options/precision 1})
;; => \"1.5 l\"

(units/display options/volume 1.45 options/liter {options/suffix options/full})
;; => \"1.45 liter\"

;; Like `convert`, you can also call the measurement-type's functionality directly
(volume/display 1.45 options/liter {options/precision 1})
;; => \"1.5 l\"

;; And, of course, the symbolic keywords are ultimately plain keywords.
(volume/display 1.45 :liter {:suffix :full :precision 1})
;; => \"1.5 liter\"

Supported Systems

Brewtility supports four systems of measure:

These are the most commonly seen systems in brewing. There are measurement functions for the most common types of measurements within these systems:

Color

Currently, brewtility supports the following types of color:

The RGBa system is special, as it can only be used as an argument for the result of a unit conversion. Unfortunately, there is not a great deterministic way to cast the values back to the other systems. brewtility will thrown an exception in this case and explain the problem.

Pressure

Currently, brewtility supports the following types of pressure:

Specific Gravity

Currently, brewtility supports the following types of specific gravity:

While there is currently only one system, the same namespace and functionality exists as the other measurement types. This allows for progressive evolution, and provides a consistent interface to every measurement type encoded in the BeerXML specification.

Temperature

Currently, brewtility supports the following types of temperature measurements:

Given the prevalence of shorthand names in temperature measurements, brewtility also accepts c, k, and f.

Time

Currently, brewtility supports the following types of time measurements:

Volume

Currently, brewtility supports the following types of volume:

Given the prevalence of the French spellings in English recipes, both :litre and :liter can be passed as options.

Weight

Currently, brewtility supports the following types of weight: