1package resource
 2
 3// Quantity is a fixed-point representation of a number. It provides convenient
 4// marshaling/unmarshaling in JSON and YAML, in addition to String() and
 5// AsInt64() accessors.
 6//
 7// The serialization format is:
 8//
 9// ``` <quantity> ::= <signedNumber><suffix>
10//
11// (Note that <suffix> may be empty, from the "" case in <decimalSI>.)
12//
13// <digit> ::= 0 | 1 | ... | 9 <digits> ::= <digit> | <digit><digits> <number>
14// ::= <digits> | <digits>.<digits> | <digits>. | .<digits> <sign> ::= "+" |
15// "-" <signedNumber> ::= <number> | <sign><number> <suffix> ::= <binarySI> |
16// <decimalExponent> | <decimalSI> <binarySI> ::= Ki | Mi | Gi | Ti | Pi | Ei
17//
18// (International System of units; See: http://physics.nist.gov/cuu/Units/binary.html)
19//
20// <decimalSI> ::= m | "" | k | M | G | T | P | E
21//
22// (Note that 1024 = 1Ki but 1000 = 1k; I didn't choose the capitalization.)
23//
24// <decimalExponent> ::= "e" <signedNumber> | "E" <signedNumber> ```
25//
26// No matter which of the three exponent forms is used, no quantity may
27// represent a number greater than 2^63-1 in magnitude, nor may it have more
28// than 3 decimal places. Numbers larger or more precise will be capped or
29// rounded up. (E.g.: 0.1m will rounded up to 1m.) This may be extended in the
30// future if we require larger or smaller quantities.
31//
32// When a Quantity is parsed from a string, it will remember the type of suffix
33// it had, and will use the same type again when it is serialized.
34//
35// Before serializing, Quantity will be put in "canonical form". This means that
36// Exponent/suffix will be adjusted up or down (with a corresponding increase
37// or decrease in Mantissa) such that:
38//
39// - No precision is lost - No fractional digits will be emitted - The exponent
40// (or suffix) is as large as possible.
41//
42// The sign will be omitted unless the number is negative.
43//
44// Examples:
45//
46// - 1.5 will be serialized as "1500m" - 1.5Gi will be serialized as "1536Mi"
47//
48// Note that the quantity will NEVER be internally represented by a floating
49// point number. That is the whole point of this exercise.
50//
51// Non-canonical values will still parse as long as they are well formed, but
52// will be re-emitted in their canonical form. (So always use canonical form,
53// or don't diff.)
54//
55// This format is intended to make it difficult to use these numbers without
56// writing some sort of special handling code in the hopes that that will cause
57// implementors to also use a fixed point implementation.
58#Quantity: number | string