prefix-units: A basic library for SI/IEC prefix units

[ bsd3, data, library ] [ Propose Tags ] [ Report a vulnerability ]

This library deals with parsing values containing "prefix units" (both IEC/binary and SI). For example, it can parse 10M and 1G, and it can also format values for displaying with the "optimal" unit. For more details, see the man page units(7), http://physics.nist.gov/cuu/Units/prefixes.html and http://physics.nist.gov/cuu/Units/binary.html.


[Skip to Readme]

Modules

[Index] [Quick Jump]

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0, 0.1.0.1, 0.1.0.2, 0.2.0, 0.3.0.1
Change log CHANGES.md
Dependencies base (>=3 && <5) [details]
Tested with ghc ==8.0.2, ghc ==8.2.2, ghc ==8.4, ghc ==8.6, ghc ==8.8, ghc ==8.10, ghc ==9.0, ghc ==9.2, ghc ==9.4, ghc ==9.6
License BSD-3-Clause
Copyright (c) 2012, 2014, 2015 Google Inc.
Author Iustin Pop <iustin@google.com>
Maintainer Iustin Pop <iustin@google.com>
Revised Revision 1 made by IustinPop at 2023-04-26T22:25:13Z
Category Data
Home page https://github.com/iustin/prefix-units
Bug tracker https://github.com/iustin/prefix-units/issues
Source repo head: git clone https://github.com/iustin/prefix-units.git
this: git clone https://github.com/iustin/prefix-units.git(tag v0.3.0.1)
Uploaded by IustinPop at 2023-04-26T22:24:13Z
Distributions LTSHaskell:0.3.0.1, NixOS:0.3.0.1, Stackage:0.3.0.1
Reverse Dependencies 3 direct, 3 indirect [details]
Downloads 4544 total (28 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2023-04-27 [all 1 reports]

Readme for prefix-units-0.3.0.1

[back to package description]

prefix-units package

This package defines a datatype (Unit) and associated parsing/formatting functions so that command line applications can handle "nice" values like:

$ cmd create-file foo 100G
Done.
$ cmd ls-file foo
Size is 100Gi
$ cmd ls-files
foo 100Gi
bar  14Ki

And so on. For details on the API, look at the Haddock documentation for the Data.Prefix.Units module.

For building and installing, cabal configure and related commands are enough. Run cabal configure --enable-tests && cabal build && cabal test if you want to run the unit-tests.

The library is designed to have very few dependencies (only base and a few GHC extensions), so that it's trivial to use it in projects. Hence the use of some hand-coded conversions instead of using TemplateHaskell to generate them automatically.

GitHub Workflow Status Codecov

TODO

The current interface of the library works, but is not nicely composable. I'm still looking for a nicer way to expose the parsing functionality.

Currently, the IEC (binary) and SI units are mixed in the same data-type. This works, but at some level I think two separate types would be more "correct", at the expense of a more complex API.

The RationalConvertible type class has only a few instances; ideally we'd have instance Integral a => RationalConvertible a and similar for Fractional, but this doesn't work as such in Haskell, so we're stuck with the manual derivation.

The current behaviour is case-sensitive for all units in ParseExact mode, which means that one has to use (in this mode) Ki for the binary unit Kibi. This seems suboptimal, since the binary units are unique irrespective of casing.