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