Number

static Pi: Transcendental

The ratio of a circle's circumference to its diameter, exactly.

expect Number.Pi::toString()::is("π")
expect Number.Pi::toString(as #Decimal, toPlaces 5)::is("3.14159")

static Tau: Transcendental

Twice Pi, which is the ratio of a circle's circumference to its radius.

expect Number.Tau::is(Number.Pi::multiply(with 2))
expect Number.Tau::toString()::is("2·π")

static E: Transcendental

Euler's number, the base of the natural logarithm, exactly.

expect Number.E::toString()::is("e")
expect Number.E::toString(as #Decimal, toPlaces 5)::is("2.71828")

static GoldenRatio: Algebraic

The golden ratio (1 + √5) / 2, the positive solution of x² = x + 1, exactly.

constant golden = Number.GoldenRatio

expect golden::toString()::is("1/2 + 1/2·√5")
expect golden::raise(to 2)::is(golden::add(1))

static sum(_ integers: List<Integer>) -> Integer

Adds up every Integer in the List.

The sum is an Integer, since whole numbers add to a whole number. The empty List sums to zero.

Returns the total.

constant noGoals: List<Integer> = []

expect Number.sum([3, 4, 5])::is(12)
expect Number.sum(noGoals)::is(0)

static sum(_ rationals: List<Rational>) -> Rational

Adds up every Rational in the List.

The sum is a Rational, since it need not be whole. A whole total stays a Rational here, so [1/2, 1/2]::sum() answers 1/1. The mixed entry below collapses one to an Integer. The empty List sums to zero.

Returns the total.

expect Number.sum([1/2, 1/4])::is(3/4)
expect Number.sum([1/2, 1/2])::is(1/1)

static sum(_ numbers: List<Scalar>) -> Scalar

Adds up a List holding both Integers and Rationals.

The sum is an Integer when the total is whole, and a Rational otherwise. The empty List sums to zero.

Returns the total.

expect Number.sum([1, 1/2, 1/2])::is(2)
expect Number.sum([1, 1/4])::is(5/4)

static product(_ integers: List<Integer>) -> Integer

Multiplies every Integer in the List together.

The product is an Integer, since whole numbers multiply to a whole number. The empty List multiplies to one.

Returns the product.

constant noFactors: List<Integer> = []

expect Number.product([2, 3, 4])::is(24)
expect Number.product(noFactors)::is(1)

static product(_ rationals: List<Rational>) -> Rational

Multiplies every Rational in the List together.

The product is a Rational, since it need not be whole. A whole product stays a Rational here, as a whole sum does. The mixed entry below collapses one to an Integer. The empty List multiplies to one.

Returns the product.

expect Number.product([1/2, 2/3])::is(1/3)
expect Number.product([3/2, 2/3])::is(1/1)

static product(_ numbers: List<Scalar>) -> Scalar

Multiplies a List holding both Integers and Rationals together.

The product is an Integer when it is whole, and a Rational otherwise. The empty List multiplies to one.

Returns the product.

expect Number.product([4, 3/2])::is(6)
expect Number.product([3, 1/2])::is(3/2)

static average(_ integers: List<Integer>) -> Optional<Rational>

The arithmetic mean of the Integers: their sum divided by their count.

The mean is a Rational, since it need not be whole. The empty List has no mean.

Returns the mean, or nothing for the empty List.

constant scores = [1, 2, 3, 4]
constant noScores: List<Integer> = []

expect Number.average(scores)::is(5/2)
expect Number.average(noScores)::isEmpty()

static average(_ rationals: List<Rational>) -> Optional<Rational>

The arithmetic mean of the Rationals: their sum divided by their count.

The mean is a Rational. The empty List has no mean.

Returns the mean, or nothing for the empty List.

constant shares = [1/2, 1/4]
constant noShares: List<Rational> = []

expect Number.average(shares)::is(3/8)
expect Number.average(noShares)::isEmpty()

static average(_ numbers: List<Scalar>) -> Optional<Rational>

The arithmetic mean of a List holding both Integers and Rationals.

The mean is a Rational, since it need not be whole. The empty List has no mean.

Returns the mean, or nothing for the empty List.

constant readings = [1, 1/2, 3]
constant noReadings: List<Scalar> = []

expect Number.average(readings)::is(3/2)
expect Number.average(noReadings)::isEmpty()

static average(
	_ integers: List<Integer>,
	defaultingTo fallback: Rational,
) -> Rational

The arithmetic mean of the Integers, with a value to answer for the empty List.

Returns the mean, or the given value in its place.

constant scores = [1, 2, 3, 4]
constant noScores: List<Integer> = []

expect Number.average(scores, defaultingTo 0/1)::is(5/2)
expect Number.average(noScores, defaultingTo 0/1)::is(0/1)

static average(
	_ rationals: List<Rational>,
	defaultingTo fallback: Rational,
) -> Rational

The arithmetic mean of the Rationals, with a value to answer for the empty List.

Returns the mean, or the given value in its place.

constant shares = [1/2, 1/4]
constant noShares: List<Rational> = []

expect Number.average(shares, defaultingTo 0/1)::is(3/8)
expect Number.average(noShares, defaultingTo 0/1)::is(0/1)

static average(
	_ numbers: List<Scalar>,
	defaultingTo fallback: Rational,
) -> Rational

The arithmetic mean of the Numbers, with a value to answer for the empty List.

Returns the mean, or the given value in its place.

constant readings = [1, 1/2, 3]
constant noReadings: List<Scalar> = []

expect Number.average(readings, defaultingTo 0/1)::is(3/2)
expect Number.average(noReadings, defaultingTo 0/1)::is(0/1)

static average(_ integers: NonEmptyList<Integer>) -> Rational

The arithmetic mean of the Integers in a List proven to have an item.

The count is above zero, so the answer is the mean itself rather than an Optional.

Returns the mean.

expect Number.average([1, 2, 3, 4])::is(5/2)
expect Number.average([7])::is(7)

static average(_ rationals: NonEmptyList<Rational>) -> Rational

The arithmetic mean of the Rationals in a List proven to have an item.

The count is above zero, so the answer is the mean itself rather than an Optional.

Returns the mean.

expect Number.average([1/2, 1/4])::is(3/8)

static average(_ numbers: NonEmptyList<Scalar>) -> Rational

The arithmetic mean of the Numbers in a List proven to have an item.

The count is above zero, so the answer is the mean itself rather than an Optional.

Returns the mean.

expect Number.average([1, 1/2, 3])::is(3/2)

static lowest(_ firstNumber: Integer, _ secondNumber: Integer) -> Integer

The lower of two Integers.

The answer is an Integer. Two equal Integers answer the first of them.

Returns the lower Integer.

expect Number.lowest(3, 7)::is(3)
expect Number.lowest(-2, 5)::is(-2)

static lowest(_ firstNumber: Rational, _ secondNumber: Rational) -> Rational

The lower of two Rationals.

The answer is a Rational. Two equal Rationals answer the first of them.

Returns the lower Rational.

expect Number.lowest(1/2, 1/3)::is(1/3)

static lowest(_ firstNumber: Integer, _ secondNumber: Rational) -> Scalar

The lower of an Integer and a Rational.

The answer keeps the kind of the Number it picks, so it is an Integer or a Rational. Two equal Numbers answer the Integer.

Returns the lower Number.

expect Number.lowest(1, 3/2)::is(1)
expect Number.lowest(2, 3/2)::is(3/2)

static lowest(_ firstNumber: Rational, _ secondNumber: Integer) -> Scalar

The lower of a Rational and an Integer.

The answer keeps the kind of the Number it picks, so it is an Integer or a Rational. Two equal Numbers answer the Rational.

Returns the lower Number.

expect Number.lowest(5/2, 3)::is(5/2)
expect Number.lowest(7/2, 3)::is(3)

static lowest(_ integers: List<Integer>) -> Optional<Integer>

The lowest of the Integers in the List.

The answer is the earliest of the lowest items. The empty List has none.

Returns the lowest Integer, or nothing for the empty List.

constant temperatures = [12, -3, 7]
constant noReadings: List<Integer> = []

expect Number.lowest(temperatures)::is(-3)
expect Number.lowest(noReadings)::isEmpty()

static lowest(_ rationals: List<Rational>) -> Optional<Rational>

The lowest of the Rationals in the List.

The answer is the earliest of the lowest items. The empty List has none.

Returns the lowest Rational, or nothing for the empty List.

constant shares = [1/2, 1/3, 3/4]
constant noShares: List<Rational> = []

expect Number.lowest(shares)::is(1/3)
expect Number.lowest(noShares)::isEmpty()

static lowest(_ numbers: List<Scalar>) -> Optional<Scalar>

The lowest Number in a List holding both Integers and Rationals.

The answer keeps the kind of the item it picks, and is the earliest of the lowest items. The empty List has none.

Returns the lowest Number, or nothing for the empty List.

constant prices = [3, 5/2, 4]
constant noPrices: List<Scalar> = []

expect Number.lowest(prices)::is(5/2)
expect Number.lowest(noPrices)::isEmpty()

static lowest(
	_ integers: List<Integer>,
	defaultingTo fallback: Integer,
) -> Integer

The lowest of the Integers, with a value to answer for the empty List.

Returns the lowest Integer, or the given value in its place.

constant temperatures = [12, -3, 7]
constant noReadings: List<Integer> = []

expect Number.lowest(temperatures, defaultingTo 0)::is(-3)
expect Number.lowest(noReadings, defaultingTo 0)::is(0)

static lowest(
	_ rationals: List<Rational>,
	defaultingTo fallback: Rational,
) -> Rational

The lowest of the Rationals, with a value to answer for the empty List.

Returns the lowest Rational, or the given value in its place.

constant shares = [1/2, 1/3]
constant noShares: List<Rational> = []

expect Number.lowest(shares, defaultingTo 0/1)::is(1/3)
expect Number.lowest(noShares, defaultingTo 0/1)::is(0/1)

static lowest(_ numbers: List<Scalar>, defaultingTo fallback: Scalar) -> Scalar

The lowest of the Numbers, with a value to answer for the empty List.

Returns the lowest Number, or the given value in its place.

constant prices = [3, 5/2, 4]
constant noPrices: List<Scalar> = []

expect Number.lowest(prices, defaultingTo 0)::is(5/2)
expect Number.lowest(noPrices, defaultingTo 0)::is(0)

static lowest(_ integers: NonEmptyList<Integer>) -> Integer

The lowest of the Integers in a List proven to have an item.

The List has a lowest item, so the answer is that item rather than an Optional.

Returns the lowest Integer.

expect Number.lowest([12, -3, 7])::is(-3)

static lowest(_ rationals: NonEmptyList<Rational>) -> Rational

The lowest of the Rationals in a List proven to have an item.

The List has a lowest item, so the answer is that item rather than an Optional.

Returns the lowest Rational.

expect Number.lowest([1/2, 1/3, 3/4])::is(1/3)

static lowest(_ numbers: NonEmptyList<Scalar>) -> Scalar

The lowest of the Numbers in a List proven to have an item.

The List has a lowest item, so the answer is that item rather than an Optional.

Returns the lowest Number.

expect Number.lowest([3, 5/2, 4])::is(5/2)

static lowest(_ firstNumber: Number, _ secondNumber: Number) -> Number

The lower of two Numbers, of any kind the tower holds.

The answer is a Number, since the two can be of different kinds. Two equal Numbers answer the first of them.

Returns the lower Number.

expect Number.lowest(Number.Pi, 22/7)::is(Number.Pi)
expect Number.lowest(Number.E, Number.Pi)::is(Number.E)

static highest(_ firstNumber: Integer, _ secondNumber: Integer) -> Integer

The higher of two Integers.

The answer is an Integer. Two equal Integers answer the first of them.

Returns the higher Integer.

expect Number.highest(3, 7)::is(7)
expect Number.highest(-2, -5)::is(-2)

static highest(_ firstNumber: Rational, _ secondNumber: Rational) -> Rational

The higher of two Rationals.

The answer is a Rational. Two equal Rationals answer the first of them.

Returns the higher Rational.

expect Number.highest(1/2, 1/3)::is(1/2)

static highest(_ firstNumber: Integer, _ secondNumber: Rational) -> Scalar

The higher of an Integer and a Rational.

The answer keeps the kind of the Number it picks, so it is an Integer or a Rational. Two equal Numbers answer the Integer.

Returns the higher Number.

expect Number.highest(1, 3/2)::is(3/2)
expect Number.highest(2, 3/2)::is(2)

static highest(_ firstNumber: Rational, _ secondNumber: Integer) -> Scalar

The higher of a Rational and an Integer.

The answer keeps the kind of the Number it picks, so it is an Integer or a Rational. Two equal Numbers answer the Rational.

Returns the higher Number.

expect Number.highest(5/2, 3)::is(3)
expect Number.highest(7/2, 3)::is(7/2)

static highest(_ integers: List<Integer>) -> Optional<Integer>

The highest of the Integers in the List.

The answer is the earliest of the highest items. The empty List has none.

Returns the highest Integer, or nothing for the empty List.

constant temperatures = [12, -3, 7]
constant noReadings: List<Integer> = []

expect Number.highest(temperatures)::is(12)
expect Number.highest(noReadings)::isEmpty()

static highest(_ rationals: List<Rational>) -> Optional<Rational>

The highest of the Rationals in the List.

The answer is the earliest of the highest items. The empty List has none.

Returns the highest Rational, or nothing for the empty List.

constant shares = [1/2, 1/3, 3/4]
constant noShares: List<Rational> = []

expect Number.highest(shares)::is(3/4)
expect Number.highest(noShares)::isEmpty()

static highest(_ numbers: List<Scalar>) -> Optional<Scalar>

The highest Number in a List holding both Integers and Rationals.

The answer keeps the kind of the item it picks, and is the earliest of the highest items. The empty List has none.

Returns the highest Number, or nothing for the empty List.

constant prices = [3, 5/2, 4]
constant noPrices: List<Scalar> = []

expect Number.highest(prices)::is(4)
expect Number.highest(noPrices)::isEmpty()

static highest(
	_ integers: List<Integer>,
	defaultingTo fallback: Integer,
) -> Integer

The highest of the Integers, with a value to answer for the empty List.

Returns the highest Integer, or the given value in its place.

constant temperatures = [12, -3, 7]
constant noReadings: List<Integer> = []

expect Number.highest(temperatures, defaultingTo 0)::is(12)
expect Number.highest(noReadings, defaultingTo 0)::is(0)

static highest(
	_ rationals: List<Rational>,
	defaultingTo fallback: Rational,
) -> Rational

The highest of the Rationals, with a value to answer for the empty List.

Returns the highest Rational, or the given value in its place.

constant shares = [1/2, 1/3]
constant noShares: List<Rational> = []

expect Number.highest(shares, defaultingTo 0/1)::is(1/2)
expect Number.highest(noShares, defaultingTo 0/1)::is(0/1)

static highest(_ numbers: List<Scalar>, defaultingTo fallback: Scalar) -> Scalar

The highest of the Numbers, with a value to answer for the empty List.

Returns the highest Number, or the given value in its place.

constant prices = [3, 5/2, 4]
constant noPrices: List<Scalar> = []

expect Number.highest(prices, defaultingTo 0)::is(4)
expect Number.highest(noPrices, defaultingTo 0)::is(0)

static highest(_ integers: NonEmptyList<Integer>) -> Integer

The highest of the Integers in a List proven to have an item.

The List has a highest item, so the answer is that item rather than an Optional.

Returns the highest Integer.

expect Number.highest([12, -3, 7])::is(12)

static highest(_ rationals: NonEmptyList<Rational>) -> Rational

The highest of the Rationals in a List proven to have an item.

The List has a highest item, so the answer is that item rather than an Optional.

Returns the highest Rational.

expect Number.highest([1/2, 1/3, 3/4])::is(3/4)

static highest(_ numbers: NonEmptyList<Scalar>) -> Scalar

The highest of the Numbers in a List proven to have an item.

The List has a highest item, so the answer is that item rather than an Optional.

Returns the highest Number.

expect Number.highest([3, 5/2, 4])::is(4)

static highest(_ firstNumber: Number, _ secondNumber: Number) -> Number

The higher of two Numbers, of any kind the tower holds.

The answer is a Number, since the two can be of different kinds. Two equal Numbers answer the first of them.

Returns the higher Number.

expect Number.highest(Number.Pi, 22/7)::is(22/7)
expect Number.highest(Number.E, Number.Pi)::is(Number.Pi)

static parse(_ text: String) -> Optional<Scalar>

Returns the Number, or nothing when the text has any other shape.

expect Number.parse("5")::is(5)
expect Number.parse("0.75")::is(3/4)
expect Number.parse("five")::isEmpty()

static parse(_ text: String, defaultingTo fallback: Scalar) -> Scalar

Reads a Number from its text form, with a value to answer when the text has another shape.

Returns the Number, or the given value in its place.

expect Number.parse("3/4", defaultingTo 0)::is(3/4)
expect Number.parse("", defaultingTo 0)::is(0)

is(_ other: Number) -> Boolean

Answers whether the Number has the same numeric value as another Number.

An Integer and a Rational are the same Number when their values are equal, so 1 is 1/1 holds. The answer is read off compare. So two Transcendentals that both carry π and e can stop the Program at the precision cutoff compare names.

Returns true when both Numbers have the same numeric value.

constant whole: Number = 1
constant angle: Number = Number.Tau

expect whole::is(1/1)
expect angle::is(Number.Pi::multiply(with 2))

compare(to other: Number) -> Ordering

Orders the Number against another Number by numeric value, across every member of the tower.

Every pair is ordered exactly, with one exception. A Transcendental carrying both π and e is ordered against another Number by refining enclosures, and the refinement stops at 32768 decimal places. A pair that still agrees there stops the Program with an error, since deciding it exactly is an open problem. The bounded form is Transcendental::compare(to:withPrecision:), which answers empty instead.

Returns Ordering#Less, Ordering#Equal or Ordering#Greater.

constant three: Number = 3

expect three::compare(to Number.Pi)::is(#Less)
expect three::compare(to 3/1)::is(#Equal)

toString() -> String

Answers the Number as a String, in the notation of the member Type it holds.

Returns the String representation of the Number.

constant share: Number = 1/2
constant angle: Number = Number.Tau

expect share::toString()::is("1/2")
expect angle::toString()::is("2·π")

isNot(_ other: Number) -> Boolean

Answers whether the values differ.

Returns true when the values differ.

expect "Ada"::isNot("Grace")
expect 3::isNot(3)::negate()

isLessThan(_ other: Number) -> Boolean

Answers whether the value is strictly below another.

Returns true when the value is below the given one.

expect 3::isLessThan(5)
expect 5::isLessThan(5)::negate()

isLessThanOrEqualTo(_ other: Number) -> Boolean

Answers whether the value is below another, or equal to it.

Returns true when the value is below the given one or equal to it.

expect 3::isLessThanOrEqualTo(5)
expect 5::isLessThanOrEqualTo(5)

isGreaterThan(_ other: Number) -> Boolean

Answers whether the value is strictly above another.

Returns true when the value is above the given one.

expect "pear"::isGreaterThan("apple")
expect "pear"::isGreaterThan("pear")::negate()

isGreaterThanOrEqualTo(_ other: Number) -> Boolean

Answers whether the value is above another, or equal to it.

Returns true when the value is above the given one or equal to it.

expect 5::isGreaterThanOrEqualTo(3)
expect 5::isGreaterThanOrEqualTo(5)

isBetween(_ lower: Number, and upper: Number) -> Boolean

Answers whether the value lies between the two given ones, both included.

The two bounds name the same range in either order: 7::isBetween(10, and 1) is true, and 15::isBetween(10, and 1) is false.

Returns true when the value is within the bounds.

expect 7::isBetween(1, and 10)
expect 7::isBetween(10, and 1)
expect 15::isBetween(10, and 1)::negate()

clamp(between lowest: Number, and highest: Number) -> Number

Answers the value, pulled into the given bounds.

The answer is the lower bound when the value is below it. It is the upper bound when the value is above it, and the value itself otherwise. The two bounds name the same range in either order: 7::clamp(between 10, and 1) is 7, and 15::clamp(between 10, and 1) is 10.

Returns the clamped value.

expect 7::clamp(between 1, and 10)::is(7)
expect 15::clamp(between 1, and 10)::is(10)
expect -4::clamp(between 10, and 1)::is(1)

add(_ other: Scalar) -> Scalar

Adds two Scalars.

The answer is an Integer for two Integers, and a Rational for every other pair.

Returns the exact sum.

constant price: Scalar = 3
constant tip: Scalar = 1/2

expect price::add(tip)::is(7/2)
expect price::add(price)::is(6)

multiply(with other: Scalar) -> Scalar

Multiplies two Scalars.

The answer is an Integer for two Integers, and a Rational for every other pair.

Returns the exact product.

constant price: Scalar = 4
constant share: Scalar = 3/4

expect price::multiply(with share)::is(3)
expect price::multiply(with price)::is(16)