NumberFormat
type Integer
Implements Monoid, Group, Blankable, Truthyable.
Whole numbers, of arbitrary size.
Integer has no width limit: factorials and cryptographic moduli are ordinary values, not a special big-number type you have to opt into.
Integer and Float are one numeric tower: they compare and order across the boundary, so 0 == 0.0 is true and [1, 2.5, 3].sort works. What differs is the arithmetic. / on two integers is integer division, and sqrt answers a Float because a square root generally is one.
7 / 2 # => 3 (integer division)
7.0 / 2.0 # => 3.5
16.sqrt # => 4.0 (a Float, even from an Integer)
(-7).modulo(3) # => 2 (mathematical modulo, not C remainder)even?
even? : BoolReturns true when the integer is divisible by two. Zero is even, and negative numbers follow the same rule.
Returns true for an even integer
Examples
4.even? # => true
3.even? # => false
(-2).even? # => trueSplitting a list into evens and odds
[1, 2, 3, 4].partition { |n| n.even? } # => ([2, 4], [1, 3])odd?
odd? : BoolReturns true when the integer is not divisible by two. The opposite of even?.
Returns true for an odd integer
Examples
3.odd? # => true
4.odd? # => falseabs
abs : IntegerReturns the magnitude of the integer, discarding its sign.
Returns the absolute value
Examples
(-5).abs # => 5
5.abs # => 5Distance between two positions
(a - b).abssqrt
sqrt : FloatReturns the square root as a Float.
The result is a Float even when the root is exact, because in general it is not. Round or floor it when you need an integer back.
Returns the square root
Examples
16.sqrt # => 4.0
2.sqrt # => 1.4142135623730951
16.sqrt.round # => 4modulo
modulo(n: Integer) -> IntegerReturns this modulo n.
The result takes the sign of n, which is mathematical modulo rather than the C-style remainder other languages give. That is what makes it safe for wrapping an index that may have gone negative.
Parameters
n- the modulus
Returns the remainder, with the sign of n
Examples
7.modulo(3) # => 1
(-7).modulo(3) # => 2Wrapping an index around a list
let items = ["a", "b", "c"]
items.at((-1).modulo(items.count)) # => Just("c")in?
in?(range: Range<Integer>) -> BoolReturns true when the integer falls inside range, endpoints included.
Parameters
range- the inclusive range
Returns true when the integer is in range
Examples
5.in?(1..10) # => true
11.in?(1..10) # => falseValidating a port number
port.in?(1..65535)times
times(block: (Integer -> Void)) -> Void
times(block: Block<Void>) -> VoidCalls f exactly this times, passing the 0-based iteration index.
This is the counting loop. When you want the numbers themselves rather than a count of repetitions, (1..n).items.each often reads better.
Parameters
f- called once per iteration with the index
Examples
3.times { |i| IO.printLine(i) } # prints 0, then 1, then 2Repeating an action
retries.times { |_| attemptConnection }Repeating an action that needs no index
3.times do
IO.printLine("hi")
endfloor
floor : IntegerReturns the integer unchanged. Present so that code written against Number works whichever half of the tower it is handed.
Returns the same integer
Examples
7.floor # => 7ceil
ceil : IntegerReturns the integer unchanged. The Integer counterpart of Float.ceil.
Returns the same integer
Examples
7.ceil # => 7round
round : IntegerReturns the integer unchanged. The Integer counterpart of Float.round.
Returns the same integer
Examples
7.round # => 7From Monoid
repeat- Combines this value with itself
ntimes.
Defined in other modules
- Units.Data
<,>,<=,>=
type Float
Implements Blankable, Truthyable.
Double-precision floating-point numbers.
A Kex Float is always finite. An operation that would produce NaN or Infinity raises instead: the same rule the BEAM enforces, where those two values cannot exist at all. So a Float you are holding is always a real number, and there is no nan? to check for.
Float and Integer compare and order across the boundary; see Integer for the rest of the numeric tower.
3.7.floor # => 3
3.7.round # => 4
(-3.7).toInteger # => -3 (truncates toward zero)abs
abs : FloatReturns the magnitude of the float, discarding its sign.
Returns the absolute value
Examples
(-3.14).abs # => 3.14
3.14.abs # => 3.14An approximate-equality test
(a - b).abs < 0.0001sqrt
sqrt : FloatReturns the square root. Raises for a negative receiver, which has no real root.
Returns the square root
Examples
25.0.sqrt # => 5.0
2.0.sqrt # => 1.4142135623730951in?
in?(range: Range<Float>) -> BoolReturns true when the float falls inside range, endpoints included.
Parameters
range- the inclusive range
Returns true when the float is in range
Examples
Comparing directly is usually clearer for floats
let ratio = 0.75
ratio >= 0.0 && ratio <= 1.0 # => truefloor
floor : IntegerReturns the largest integer that is not greater than the float: it always rounds toward negative infinity, which is what separates it from toInteger for negative values.
Returns the floor
Examples
3.7.floor # => 3
3.2.floor # => 3
(-3.2).floor # => -4ceil
ceil : IntegerReturns the smallest integer that is not less than the float: it always rounds toward positive infinity.
Returns the ceiling
Examples
3.2.ceil # => 4
3.0.ceil # => 3
(-3.7).ceil # => -3How many pages of a fixed size a list needs
(items.count.to(Float).or(0.0) / 20.0).ceilround
round : IntegerReturns the nearest integer, with halves rounding away from zero.
Returns the rounded value
Examples
3.2.round # => 3
3.5.round # => 4
3.7.round # => 4toInteger
toInteger : IntegerTruncates toward zero and returns the result as an Integer: it drops the fractional part rather than rounding, so it differs from both floor and round for negative values.
Returns the truncated value
Examples
3.7.toInteger # => 3
(-3.7).toInteger # => -3 (floor would give -4)Defined in other modules
module Integer
Reading integers out of text.
Use parse when a failure needs explaining and "42".to(Integer) when it does not: to answers a plain Optional, parse answers a Result carrying a ParseError that says where it stopped and what it had read so far.
parse
parse(s: String) -> Result<Integer, ParseError>
parse(s: String, radix: Integer) -> Result<Integer, ParseError>Parses the whole string as a base-10 integer.
The string must be entirely consumed: leading or trailing characters make it an Error, with a ParseError describing where parsing stopped. Use parsePrefix when a trailing remainder is expected.
Parameters
s- the text to parse
Returns the integer, or a described failure
Examples
Integer.parse("42") # => Ok(42)
Integer.parse("-7") # => Ok(-7)
Integer.parse("4x") # => Error(ParseError { ... rest: "x" ... })Reading a setting with a fallback
let port = Integer.parse(raw).or(8080)Reporting why the input was rejected
match Integer.parse(raw) do
Ok(n) => IO.printLine("port ${n}")
Error(e) => IO.printError("bad port: ${e.message}")
endparsePrefix
parsePrefix(s: String) -> (Integer, String)?Parses an integer from the front of the string and returns it together with whatever text was left over.
This is the building block for hand-written scanners: parse a number, keep going from the remainder. Answers None when the string does not begin with a number at all.
Parameters
s- the text to parse from
Returns the value and the unconsumed remainder
Examples
Integer.parsePrefix("42abc") # => Just((42, "abc"))
Integer.parsePrefix("abc") # => NoneReading a leading count off a line
match Integer.parsePrefix("3 items") do
Just(pair) => do
let (count, rest) = pair
IO.printLine("${count} of${rest}") # prints: 3 of items
end
None => IO.printError("no leading count")
endmodule Float
Reading floating-point numbers out of text.
parse
parse(s: String) -> Result<Float, ParseError>Parses the whole string as a float.
The string must be entirely consumed; anything left over makes it an Error carrying a ParseError.
Parameters
s- the text to parse
Returns the float, or a described failure
Examples
Float.parse("3.5") # => Ok(3.5)
Float.parse("-0.25") # => Ok(-0.25)
Float.parse("3.5m") # => Error(ParseError { ... rest: "m" ... })Averaging a column of text values
rows.map { |r| Float.parse(r).or(0.0) }.sum / rows.count.to(Float).or(1.0)parsePrefix
parsePrefix(s: String) -> (Float, String)?Parses a float from the front of the string and returns it together with the unconsumed remainder. Answers None when the string does not begin with a number.
Parameters
s- the text to parse from
Returns the value and the remainder
Examples
Float.parsePrefix("3.5rest") # => Just((3.5, "rest"))
Float.parsePrefix("rest") # => NoneSplitting a measurement from its unit
Float.parsePrefix("12.5kg") # => Just((12.5, "kg"))module Float32
The bounds of the sized numeric types: Int8.MAX, UInt64.MAX, Float32.MIN and so on. Integer has none: it is arbitrary-precision. For a float type, MIN is the most negative finite value, not the smallest positive one.
The range of a 32-bit float.
module Float64
The range of a 64-bit float, the same as a Float.
module Int8
The range of a signed 8-bit integer.
module Int16
The range of a signed 16-bit integer.
module Int32
The range of a signed 32-bit integer.
module Int64
The range of a signed 64-bit integer.
module UInt8
The range of an unsigned 8-bit integer: UInt8 is another name for Byte.
module UInt16
The range of an unsigned 16-bit integer.
module UInt32
The range of an unsigned 32-bit integer.
module UInt64
The range of an unsigned 64-bit integer.
module Byte
The range of a Byte, Kex's unsigned 8-bit integer (also called UInt8).
module Number
Reading a number out of text without deciding in advance which half of the numeric tower it belongs to.
parse
parse(s: String) -> Result<Number, ParseError>Parses the whole string as an Integer or a Float, whichever the text describes.
Use it when the input's shape is not known ahead of time: a config value, a CSV column that may hold either.
Parameters
s- the text to parse
Returns the number, or a described failure
Examples
Number.parse("42") # => Ok(42)
Number.parse("3.5") # => Ok(3.5)
Number.parse("x") # => Error(ParseError { ... })format
format(parts: [String], values: [Any]) -> NumberFormatBuilds a NumberFormat from a digit pattern, for to(String, format).
The pattern is checked during compilation (by validateFormat), so a mistake in it fails the build instead of leaving text out at run time.
0is a required digit:000pads the integer part to three digits, and.00always writes two decimals.#is an optional digit:#.##writes at most two decimals and drops trailing zeros. Optional digits come before required ones in the integer part (#0) and after them in the decimals (.0#)..starts the decimals. The value is rounded to as many decimals as the pattern allows, with ties away from zero.
The integer part always has at least one digit, so #.00 writes 0.50, never .50. A value that rounds to zero has no minus sign.
Parameters
parts- the literal pieces of the tagged literal
values- the interpolated values
Returns the format
Examples
1.5.to(String, Number.format`#.00`) # => Just("1.50")
1.5.to(String, Number.format`#.##`) # => Just("1.5")
2.0.to(String, Number.format`#.##`) # => Just("2")
7.to(String, Number.format`000`) # => Just("007")validateFormat
validateFormat(source: String) -> [TaggedValidation.Issue]Checks a Number.format pattern during compilation, pointing at the first character that does not fit.
Parameters
source- the pattern
Returns the problem found, if any
record NumberFormat
How to(String, format) writes a number: a digit pattern such as "#.00", described at Number.format. Build one with Number.format, which checks the pattern during compilation, or with NumberFormat.parse for a pattern known only at run time.
Fields
patternString
module NumberFormat
parse
parse(pattern: String) -> Result<NumberFormat, ParseError>Checks a digit pattern known only at run time. Number.format describes the patterns.
Parameters
pattern- the pattern
Returns the format, or where the pattern goes wrong
Examples
NumberFormat.parse("#.00") # => Ok(NumberFormat { pattern: "#.00" })
NumberFormat.parse("#.#0") # => Error(ParseError { position: 3, ... })layout
layout(pattern: String) -> Result<(Integer, Integer, Integer), (Integer, String)>What a pattern writes: the fewest integer digits, the fewest decimals and the most decimals. Otherwise the index of its first problem, and what that problem is.
Parameters
pattern- the pattern
Returns the layout, or the problem
Examples
NumberFormat.layout("#0.0##") # => Ok((1, 1, 3))type Number
Implements Comparable.
to
to(String: Type, format: NumberFormat) -> String?Writes the number by a digit pattern, described at Number.format.
Parameters
String- the target type
format- the pattern
Returns the text, or None when the pattern is not valid
Examples
1234.5.to(String, Number.format`#.00`) # => Just("1234.50")
(-0.001).to(String, Number.format`#.#`) # => Just("0")
42.to(String, Number.format`0000.0`) # => Just("0042.0")leadingZeros
leadingZeros(text: String, width: Integer) -> Stringtext with leading zeros up to width characters.
trailingZeros
trailingZeros(text: String, width: Integer) -> Stringtext with exactly width characters if it is shorter, or with its trailing zeros dropped down to width characters if it is longer.
From Comparable
max- What every ordered type gets from
comparealone. min- Returns the smaller of this value and
other; this value when they are equal. clamp- Returns this value limited to the range
lowtohigh:lowwhen it is below,highwhen it is above, and itself otherwise. <- The ordering operators, from
comparealone: whatever isComparablecan be written with<and>, a record as much as a number.