prefix-units-0.1.0.1: A basic library for SI/binary prefix units

Data.Prefix.Units

Description

Definitions and functions for parsing and formatting prefix units.

This module defines the type `Unit` and associated functions for parsing numbers containing a prefix unit (e.g. `100M`) into corespondingly scaled values (for the above example, `100000000`), and for formatting numbers.

The units definition is taken from the man page `units(7)` and the web sites http://physics.nist.gov/cuu/Units/prefixes.html and http://physics.nist.gov/cuu/Units/binary.html.

Since a give prefix unit (e.g. `m`) can be interpreted in different ways, the module offers various ways to interpret this:

• in a binary context (e.g. when talking about memory), this will be interpreted as 2^20 (see `ParseBinary`)
• in a SI context dealing with multiples, this will be intepreted as 10^3 (see `ParseKMGT`)
• in an exact parsing mode, this will be interpreded as the "milli" prefix, i.e. 10^-3 (see `ParseExact`)

The different parsing mode are offered as different contexts will have different "natural" units, and always forcing precise parsing (which also implies case-sensitivity) will lead to confusing user interfaces.

The internal calculations when converting values are done via the `Rational` type (with arbitrary precision), and precision loss happens only at the last step of converting to the target type; for float/doubles this is `fromRational`, for integral types this is `round`.

A few examples are given below:

````>>> ````showValue (Left FormatBinary) 2048
```"2.0Ki"
`>>> ````showValue (Left FormatSiAll) 0.0001
```"100.0u"
`>>> ````showValue (Right Mebi) 1048576
```"1Mi"
`>>> ````parseValue ParseExact "2.5Ki"::Either String Double
```Right 2560.0
`>>> ````parseValue ParseBinary "2M"::Either String Int
```Right 2097152
`>>> ````parseValue ParseExact "2ki"
```Left "Unrecognised unit 'ki'"
```

The failure in the last example is due to the fact that `ParseExact` is case-sensitive.

Synopsis

# Basic definitions

## Types

data Unit Source

The unit type.

Constructors

 Yocto Zepto Atto Femto Pico Nano Micro Milli Centi Deci Deka Hecto Kilo Kibi Mega Mebi Giga Gibi Tera Tebi Peta Pebi Exa Exbi Zetta Yotta

Instances

 Bounded Unit Enum Unit Eq Unit Ord Unit Show Unit

class Real a => RationalConvertible a whereSource

Typeclass for handling values that can be converted to/from `Rational`.

Methods

Converts the value from Ratioal

siUnits :: [Unit]Source

List of all SI units.

List of units which are supraunitary (their multiplier is greater than one).

siKMGT :: [Unit]Source

List of SI units which are greater or equal to `Kilo`.

List of binary units.

## Unit-related functions

Returns the unit scaling "multiplier" (which can be either supra- or sub-unitary):

````>>> ````unitMultiplier Micro
```1 % 1000000
`>>> ````unitMultiplier Mebi
```1048576 % 1
```

Returns the unit full name.

Returns the unit ASCII symbol.

Returns the unit symbol, which for the `Micro` unit is not ASCII.

# Formatting functions

data FormatMode Source

Defines the formatting modes.

Constructors

 FormatSiAll Formats the value using any SI unit. FormatSiSupraunitary Formats the value using supraunitary SI units only (which means that e.g. `0.001` will remain as such instead of being formatted as `1m`) FormatSiKMGT Formats the value using units greater or equal to `Kilo`. FormatBinary Formats the value using binary units.

Instances

 Bounded FormatMode Enum FormatMode Show FormatMode

recommendedUnit :: Real a => FormatMode -> a -> Maybe UnitSource

Computes the recommended unit for displaying a given value. The simple algorithm uses the first unit for which we have a supraunitary representation. In case we don't find any such value (e.g. for a zero value), then `Nothing` is returned.

Arguments

 :: RationalConvertible a => FormatOption The desired `FormatMode` or `Unit` -> a The value to format -> (a, Maybe Unit) Scaled value and optional unit

Computes the scaled value and unit for a given value

Arguments

 :: (RationalConvertible a, Show a) => FormatOption The desired format mode, either as a `Left` `FormatMode` value which computes the unit automatically, or as a `Right` `Unit`, which will use the specified unit -> a The value to show -> String Resulting string

Generates a final string representation of a value.

# Parsing functions

data ParseMode Source

Defines available parse modes.

Constructors

 ParseExact Exact parser mode. This mode is fully case-sensitive. ParseKMGT Parses only units bigger than `Kilo`, respectively `Kibi` (for binary units). This allows the parser to be case-insensitive. ParseBinary Parses binary units only. In this mode, both the exact and shortened forms are accepted (e.g. both "k" and "ki" will be converted into `Kibi`). Furthermore, the parsing is case-insensitive.

Instances

 Bounded ParseMode Enum ParseMode Show ParseMode

Parses a unit from a string. The exact parsing mode determines the rules for parsing and the range of possible units.

Arguments

 :: (Read a, RationalConvertible a) => ParseMode The desired parse mode -> String String to be parsed -> Either String a Either a Left error message, or a Right parsed value

Main parse routine.

# Low-level generic functions

The available units range for various format modes.

## Parsing

Defines unit handling mode on parse.

Constructors

 UnitRequired Requires that the input string has a unit. UnitDefault Unit If unit is missing, use a default one. UnitOptional The unit is optional, a missing one means the value is not scaled.

Instances

 Show ParseOptions

Parses a symbol in the exact mode. See `ParseExact` for details.

Parses a binary symbol. See `ParseBinary` for details.

Parses the given symbol as one of the "big" units (kilo/kibi and above). This allows the parsing to be case-insensitive.

Arguments

 :: (Read a, RationalConvertible a) => ParseOptions Unit options -> [Unit] Optional list of valid units -> ParseMode The desired parse mode -> String String to be parsed -> Either String a

Low-level parse routine. Takes two function arguments which fix the initial and final conversion, a parse mode and the string to be parsed.

## Formatting

Arguments

 :: (RationalConvertible a, Show a) => (Unit -> String) Function to convert the (optional) unit into a string, e.g. `unitSymbol` or `fancySymbol` -> FormatOption The desired format mode -> a The value to show -> String Resulting string

Simple helper to generate the full string representation of an integral value.