Integer

Whole numbers of any size that never overflow: arithmetic, parsing, testing and printing.

Taught on: Method calls, Numbers and Checked refinements.

At a glance

Declared: namespace Integer for Integer
Conforms to: Equatable
Printable
Orderable
Refinements: type NonZeroInteger = Integer where @::isNot(0)The Integers that are not zero, as a checked refinement of Integer.
type NonNegativeInteger = Integer where @::isGreaterThanOrEqualTo(0)The Integers from zero upward, as a checked refinement of Integer.
type PositiveInteger = Integer where @::isPositive()The Integers above zero, as a checked refinement of Integer.
Modes: DivisionHow a division pairs its quotient with its remainder.

Creating

parse

on Integer

Reads an Integer from its text form.

The text form is the notation the language writes an Integer in, and a leading sign in front of it. It is digits, with an optional underscore between two digits. A leading + is read for text a Program was handed rather than wrote. Text of any other shape answers empty, and the defaultingTo: entry answers the given Integer instead.

Example

expect Integer.parse("-42")::is(-42)
expect Integer.parse("+1_000")::is(1000)
expect Integer.parse("1_")::isEmpty()

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

NameTypeDescription

_Stringthe text to read

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

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

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

NameTypeDescription

_Stringthe text to read

defaultingToIntegerthe value to answer with when the text is no Integer

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

Example

expect Integer.parse("42", defaultingTo 0)::is(42)
expect Integer.parse("forty-two", defaultingTo 0)::is(0)

static parse(_ text: String, inBase base: Integer) -> Optional<Integer>

Reads an Integer from its text form in the given base.

The text form is the one the entries above read, in digits of that base: a leading sign, and an optional underscore between two digits. A digit above nine is a letter, and a capital letter reads as its lowercase. Text of any other shape answers empty. A base below two is read as two, and a base above thirty-six as thirty-six.

NameTypeDescription

_Stringthe text to read

inBaseIntegerthe base the digits are written in

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

Example

expect Integer.parse("ff", inBase 16)::is(255)
expect Integer.parse("-1010", inBase 2)::is(-10)
expect Integer.parse("12", inBase 2)::isEmpty()

static parse(
	_ text: String,
	inBase base: Integer,
	defaultingTo fallback: Integer,
) -> Integer

Reads an Integer from its text form in the given base, with a value to answer when the text has another shape.

NameTypeDescription

_Stringthe text to read

inBaseIntegerthe base the digits are written in

defaultingToIntegerthe value to answer with when the text is no Integer

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

Example

expect Integer.parse("FF", inBase 16, defaultingTo 0)::is(255)
expect Integer.parse("0x1F", inBase 16, defaultingTo 0)::is(0)

Equality, ordering and printing

is

on Integer

Answers whether this Integer has the same value as a number.

An Integer equals a Rational when that Rational is whole and its numerator is this Integer.

is(_ other: Integer) -> Boolean

Answers whether this Integer has the same value as another Integer.

NameTypeDescription

_Integerthe Integer to compare against

Returns true when both are equal.

Example

expect 3::is(3)
expect 3::is(-3)::negate()

is(_ other: Rational) -> Boolean

Answers whether this Integer has the same value as a Rational.

NameTypeDescription

_Rationalthe Rational to compare against

Returns true when both are equal.

Example

expect 2::is(4/2)
expect 2::is(5/2)::negate()

isNot

on Integer

Answers whether this Integer differs from a number.

Every Integer differs from a Rational that is not whole.

isNot(_ other: Integer) -> Boolean

Answers whether this Integer differs from another Integer.

NameTypeDescription

_Integerthe Integer to compare against

Returns true when the two differ.

Example

expect 3::isNot(4)
expect 3::isNot(3)::negate()

isNot(_ other: Rational) -> Boolean

Answers whether this Integer differs from a Rational.

NameTypeDescription

_Rationalthe Rational to compare against

Returns true when the two differ.

Example

expect 2::isNot(5/2)
expect 2::isNot(4/2)::negate()

compare

on Integer

compare(to other: Integer) -> Ordering

Orders the Integer against another Integer.

NameTypeDescription

toIntegerthe Integer to order against

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

Example

expect 1::compare(to 2)::is(#Less)
expect 2::compare(to 2)::is(#Equal)
expect 3::compare(to 2)::is(#Greater)

toString

on Integer

Answers the Integer as a String.

The plain entry writes the decimal digits, and the as: entries write what Rational writes for the same value.

toString() -> String

Answers the Integer as a String, in decimal digits.

Returns the String representation of the Integer.

Example

expect 42::toString()::is("42")
expect -7::toString()::is("-7")

toString(as format: NumberFormat) -> String

Answers the Integer in the named format.

The #Decimal and #Fraction formats both write the digits alone, since an Integer is whole. The #Percent format writes one hundred times the value, with a % after it. The #Scientific format writes one digit before the point, and the power of ten after an e.

NameTypeDescription

asNumberFormatthe form to represent the Integer in

Returns the String representation of the Integer.

Example

expect 42::toString(as #Fraction)::is("42")
expect 3::toString(as #Percent)::is("300%")
expect 1500::toString(as #Scientific)::is("1.5e3")

toString(
	as format: NumberFormat,
	toPlaces count: Integer,
	toward direction: Rounding = #Nearest,
) -> String

Answers the Integer in the named format, with exactly that many places.

The places are written as zeroes for the #Decimal format, so 5 over two places is 5.00. The #Fraction format ignores both the count and the direction. The count and the direction reach the other two formats as they reach Rational.

NameTypeDescription

asNumberFormatthe form to represent the Integer in

toPlacesIntegerhow many digits to write after the point

towardRounding = #Nearestthe direction to round the last digit in, #Nearest when it is left out

Returns the String representation of the Integer.

Example

expect 5::toString(as #Decimal, toPlaces 2)::is("5.00")
expect 5::toString(as #Fraction, toPlaces 2)::is("5")
expect 1234::toString(as #Scientific, toPlaces 1)::is("1.2e3")

toString(
	as format: NumberFormat,
	groupingWith separator: String,
) -> String

Answers the Integer in the named format, with a separator between the digit groups.

The separator goes between every three digits, counted from the right, so 1234567 is 1,234,567 under a comma.

NameTypeDescription

asNumberFormatthe form to represent the Integer in

groupingWithStringthe text to write between the digit groups

Returns the String representation of the Integer.

Example

constant written = 1234567::toString(as #Decimal, groupingWith ",")

expect written::is("1,234,567")

toString(
	as format: NumberFormat,
	toPlaces count: Integer,
	groupingWith separator: String,
	toward direction: Rounding = #Nearest,
) -> String

Answers the Integer in the named format, with that many places and a separator between the digit groups.

Only the digits before the point are grouped, so 1234567 over two places is 1,234,567.00 under a comma.

NameTypeDescription

asNumberFormatthe form to represent the Integer in

toPlacesIntegerhow many digits to write after the point

groupingWithStringthe text to write between the digit groups

towardRounding = #Nearestthe direction to round the last digit in, #Nearest when it is left out

Returns the String representation of the Integer.

Example

constant total = 1234567::toString(
	as #Decimal,
	toPlaces 2,
	groupingWith ",",
)

expect total::is("1,234,567.00")

toString(scaledBy places: NonNegativeInteger) -> String

Answers the Integer as a decimal scaled down by that many places.

The receiver is read as a count of the last place, so 1234 scaled by two places is 12.34. A count of zero writes the digits alone. The sign is written in front, so -1234 scaled by two places is -12.34.

NameTypeDescription

scaledByNonNegativeIntegerhow many decimal places to scale the Integer down by

Returns the String representation of the scaled Integer.

Example

expect 1234::toString(scaledBy 2)::is("12.34")
expect -1234::toString(scaledBy 2)::is("-12.34")
expect 1234::toString(scaledBy 0)::is("1234")

toString(showingSign style: SignStyle) -> String

Answers the Integer with its sign written in the named style.

The #Always Case writes a + in front of a value that is not negative, so 3 is +3 and zero is +0. The #Negative Case writes what the plain toString() writes.

NameTypeDescription

showingSignSignStylewhether to write a sign in front of a value that is not negative

Returns the String representation of the Integer.

Example

expect 3::toString(showingSign #Always)::is("+3")
expect 0::toString(showingSign #Always)::is("+0")
expect -3::toString(showingSign #Always)::is("-3")

toString(inBase base: Integer) -> String

Answers the Integer in the given base.

A digit above nine is written as a lowercase letter, so 255 in base sixteen is ff. The sign is written in front. A base below two is read as two, and a base above thirty-six as thirty-six. Integer.parse(_ , inBase:) reads back what this writes.

NameTypeDescription

inBaseIntegerthe base to write the digits in

Returns the String representation of the Integer.

Example

expect 255::toString(inBase 16)::is("ff")
expect -5::toString(inBase 2)::is("-101")

Arithmetic

add

on Integer

Adds a number to this Integer.

add(_ other: Integer) -> Integer

Adds an Integer to this Integer.

The sum is an Integer.

NameTypeDescription

_Integerthe Integer to add

Returns the sum.

Example

expect 2::add(3)::is(5)
expect 2::add(-5)::is(-3)

add(_ other: Rational) -> Rational

Adds a Rational to this Integer.

The sum is a Rational, since it need not be whole.

NameTypeDescription

_Rationalthe Rational to add

Returns the sum.

Example

expect 1::add(1/2)::is(3/2)

add(_ other: Algebraic) -> Algebraic

Adds an Algebraic to this Integer.

The sum stays exact. Shifting the rational part of a + b·√d leaves the radical untouched.

NameTypeDescription

_Algebraicthe Algebraic to add

Returns the exact sum.

Example

match 2::squareRoot() -> {} {
	case Algebraic { expect 1::add(@)::toString()::is("1 + √2") }
	case Integer { expect false }
}

add(_ other: Transcendental) -> Transcendental

Adds a Transcendental to this Integer.

The sum stays exact. Shifting the rational part of a + b·π + c·e leaves the base terms untouched.

NameTypeDescription

_Transcendentalthe Transcendental to add

Returns the exact sum.

on NonNegativeInteger

Adds an Integer proven not to be negative to this NonNegativeInteger.

A sum of two non-negative Integers is never negative, and a positive summand makes it positive.

add(_ other: PositiveInteger) -> PositiveInteger

Adds an Integer proven to be positive.

The receiver is not negative and the other summand is above zero, so the sum is above zero.

NameTypeDescription

_PositiveIntegerthe PositiveInteger to add

Returns the sum, which is above zero.

Example

expect 0::add(5)::is(5)

add(_ other: NonNegativeInteger) -> NonNegativeInteger

Adds an Integer proven not to be negative.

Neither summand is negative, so the sum is not negative either.

NameTypeDescription

_NonNegativeIntegerthe NonNegativeInteger to add

Returns the sum, which is never negative.

Example

constant finished: NonNegativeInteger = 3
constant remaining: NonNegativeInteger = 4

expect finished::add(remaining)::is(7)

on PositiveInteger

add(_ other: NonNegativeInteger) -> PositiveInteger

Adds an Integer proven not to be negative to this PositiveInteger.

The receiver is above zero and the other summand is not below it, so the sum is above zero.

NameTypeDescription

_NonNegativeIntegerthe NonNegativeInteger to add

Returns the sum, which is above zero.

Example

expect 2::add(3)::is(5)
expect 2::add(0)::is(2)

subtract

on Integer

Subtracts a number from this Integer, staying exact for every member of the numeric tower.

subtract(_ other: Integer) -> Integer

Subtracts an Integer from this Integer.

The difference is an Integer.

NameTypeDescription

_Integerthe Integer to subtract

Returns the difference.

Example

expect 5::subtract(8)::is(-3)

subtract(_ other: Rational) -> Rational

Subtracts a Rational from this Integer.

The difference is a Rational, since it need not be whole.

NameTypeDescription

_Rationalthe Rational to subtract

Returns the difference.

Example

expect 1::subtract(1/4)::is(3/4)

subtract(_ other: Algebraic) -> Algebraic

Subtracts an Algebraic from this Integer.

The difference stays exact. Negating a + b·√d flips both parts and leaves the radical itself in place.

NameTypeDescription

_Algebraicthe Algebraic to subtract

Returns the exact difference.

Example

match 2::squareRoot() -> {} {
	case Algebraic { expect 3::subtract(@)::toString()::is("3 − √2") }
	case Integer { expect false }
}

subtract(_ other: Transcendental) -> Transcendental

Subtracts a Transcendental from this Integer.

The difference stays exact. Negating a + b·π + c·e flips every part and leaves the base terms in place.

NameTypeDescription

_Transcendentalthe Transcendental to subtract

Returns the exact difference.

multiply

on Integer

Multiplies this Integer with a number, staying exact for every member of the numeric tower.

multiply(with other: Integer) -> Integer

Multiplies this Integer with another Integer.

The product is an Integer.

NameTypeDescription

withIntegerthe Integer to multiply with

Returns the product.

Example

expect 6::multiply(with 7)::is(42)
expect 6::multiply(with -7)::is(-42)

multiply(with other: Rational) -> Rational

Multiplies this Integer with a Rational.

The product is a Rational, since it need not be whole.

NameTypeDescription

withRationalthe Rational to multiply with

Returns the product.

Example

expect 3::multiply(with 1/2)::is(3/2)
expect 4::multiply(with 1/2)::is(2)

multiply(with other: Algebraic) -> Algebraic | Rational

Multiplies this Integer with an Algebraic.

The product stays exact. A zero factor collapses it to the Rational zero, so the answer is a Union of both kinds.

NameTypeDescription

withAlgebraicthe Algebraic to multiply with

Returns the exact product, an Algebraic or a Rational.

Example

match 2::squareRoot() -> {} {
	case Algebraic {
		expect 3::multiply(with @)::toString()::is("3·√2")
		expect 0::multiply(with @)::toString()::is("0")
	}

	case Integer { expect false }
}

multiply(with other: Transcendental) -> Transcendental | Rational

Multiplies this Integer with a Transcendental.

The product stays exact. A zero factor collapses it to the Rational zero, so the answer is a Union of both kinds.

NameTypeDescription

withTranscendentalthe Transcendental to multiply with

Returns the exact product, a Transcendental or a Rational.

on NonZeroInteger

Multiplies this NonZeroInteger with a number.

A product of two non-zero Integers is never zero. An irrational scaled by a non-zero Integer stays irrational, so those two entries answer the irrational kind itself.

multiply(with other: NonZeroInteger) -> NonZeroInteger

Multiplies this NonZeroInteger with another.

The product is never zero, so the answer is a NonZeroInteger too.

NameTypeDescription

withNonZeroIntegerthe NonZeroInteger to multiply with

Returns the product, which is not zero.

Example

expect -3::multiply(with 4)::is(-12)

multiply(with other: Algebraic) -> Algebraic

Multiplies this NonZeroInteger with an Algebraic.

The factor is proven, so the radical survives and the answer is an Algebraic rather than a Union.

NameTypeDescription

withAlgebraicthe Algebraic to multiply with

Returns the exact product.

Example

match 2::squareRoot() -> {} {
	case Algebraic {
		expect 3::multiply(with @)::toString()::is("3·√2")
	}

	case Integer { expect false }
}

multiply(with other: Transcendental) -> Transcendental

Multiplies this NonZeroInteger with a Transcendental.

The factor is proven, so every base term survives and the answer is a Transcendental rather than a Union.

NameTypeDescription

withTranscendentalthe Transcendental to multiply with

Returns the exact product.

on NonNegativeInteger

multiply(with other: NonNegativeInteger) -> NonNegativeInteger

Multiplies this NonNegativeInteger with an Integer proven not to be negative.

Neither factor is negative, so the product is not negative either.

NameTypeDescription

withNonNegativeIntegerthe NonNegativeInteger to multiply with

Returns the product, which is never negative.

Example

constant rows: NonNegativeInteger = 3

expect rows::multiply(with 4)::is(12)

on PositiveInteger

multiply(with other: PositiveInteger) -> PositiveInteger

Multiplies this PositiveInteger with another.

Both factors are above zero, so the product is above zero.

NameTypeDescription

withPositiveIntegerthe PositiveInteger to multiply with

Returns the product, which is above zero.

Example

expect 6::multiply(with 7)::is(42)

divide

on Integer

Divides this Integer by a number, exactly.

Dividing by an Integer or a Rational answers empty for a zero divisor. Dividing this Integer by a NonZeroInteger, by a NonZeroRational or by an Algebraic can not fail. The first two divisors are proven, and an Algebraic is irrational and so never zero. The defaultingTo: entries answer the given value in place of empty.

divide(by other: Integer) -> Optional<Rational>

Divides this Integer by an Integer.

The quotient is a Rational, since it need not be whole. A zero divisor answers empty.

NameTypeDescription

byIntegerthe divisor

Returns the exact quotient, or nothing when the divisor is zero.

Example

constant guests: Integer = 4

expect 10::divide(by guests)::is(5/2)
expect 10::divide(by 0)::isEmpty()

divide(by other: Rational) -> Optional<Rational>

Divides this Integer by a Rational.

The quotient is a Rational, since it need not be whole. A zero divisor answers empty.

NameTypeDescription

byRationalthe divisor

Returns the exact quotient, or nothing when the divisor is zero.

Example

constant share: Rational = 2/3

expect 1::divide(by share)::is(3/2)
expect 1::divide(by 0/1)::isEmpty()

divide(by other: Algebraic) -> Algebraic | Rational

Divides this Integer by an Algebraic.

An Algebraic is irrational, so it is never zero and the division can not fail. A zero receiver answers the Rational zero.

NameTypeDescription

byAlgebraicthe divisor

Returns the exact quotient, an Algebraic or a Rational.

Example

match 2::squareRoot() -> {} {
	case Algebraic {
		expect 2::divide(by @)::toString()::is("√2")
		expect 0::divide(by @)::toString()::is("0")
	}

	case Integer { expect false }
}

divide(by other: NonZeroInteger) -> Rational

Divides this Integer by a divisor proven not to be zero.

The division can not fail, so the answer is the quotient itself rather than an Optional.

NameTypeDescription

byNonZeroIntegerthe divisor, proven not to be zero

Returns the exact quotient.

Example

expect 7::divide(by 2)::is(7/2)
expect 6::divide(by -3)::is(-2)

divide(by other: Integer, defaultingTo fallback: Rational) -> Rational

Divides by an Integer, and answers the given value when the divisor is zero.

NameTypeDescription

byIntegerthe divisor

defaultingToRationalthe value to answer with when there is no quotient

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

Example

constant guests: Integer = 4

expect 10::divide(by guests, defaultingTo 0/1)::is(5/2)
expect 10::divide(by 0, defaultingTo 0/1)::is(0)

divide(by other: Rational, defaultingTo fallback: Rational) -> Rational

Divides by a Rational, and answers the given value when the divisor is zero.

NameTypeDescription

byRationalthe divisor

defaultingToRationalthe value to answer with when there is no quotient

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

Example

constant share: Rational = 2/3

expect 1::divide(by share, defaultingTo 0/1)::is(3/2)
expect 1::divide(by 0/1, defaultingTo 0/1)::is(0)

divide(by other: NonZeroRational) -> Rational

Divides this Integer by a Rational proven not to be zero.

The division can not fail, so the answer is the quotient itself rather than an Optional.

NameTypeDescription

byNonZeroRationalthe divisor, proven not to be zero

Returns the exact quotient.

Example

expect 3::divide(by 3/4)::is(4)
expect 1::divide(by 2/3)::is(3/2)

on NonZeroInteger

divide(by other: NonZeroInteger) -> NonZeroRational

Divides this NonZeroInteger by a divisor proven not to be zero.

Neither operand is zero, so the quotient is not zero either. So the answer is a NonZeroRational, and it reaches reciprocal without an Optional in between.

NameTypeDescription

byNonZeroIntegerthe divisor, proven not to be zero

Returns the exact quotient, which is not zero.

Example

expect 6::divide(by 4)::is(3/2)
expect 6::divide(by 4)::reciprocal()::is(2/3)

remainder

on Integer

Answers what is left over after taking out every whole divisor that fits.

The division is Euclidean, so the remainder is never negative and always below the divisor's magnitude. For example, 7::remainder(dividingBy 3) is 1, and -7::remainder(dividingBy 3) is 2 rather than the -1 truncating division leaves. A zero divisor answers empty, and the defaultingTo: entry answers the given Integer instead.

remainder(dividingBy divisor: Integer) -> Optional<Integer>

Answers the remainder over a divisor nothing is known about.

NameTypeDescription

dividingByIntegerthe divisor

Returns the remainder, or nothing when dividing by zero.

Example

constant teamSize: Integer = 3

expect 7::remainder(dividingBy teamSize)::is(1)
expect 7::remainder(dividingBy 0)::isEmpty()

remainder(dividingBy divisor: NonZeroInteger) -> Integer

Answers the remainder over a divisor proven not to be zero.

The division can not fail, so the answer is the remainder itself rather than an Optional.

NameTypeDescription

dividingByNonZeroIntegerthe divisor, proven not to be zero

Returns the remainder.

Example

expect 7::remainder(dividingBy 3)::is(1)
expect -7::remainder(dividingBy 3)::is(2)

remainder(
	dividingBy divisor: Integer,
	defaultingTo fallback: Integer,
) -> Integer

Answers the remainder, with a value to answer when the divisor is zero.

NameTypeDescription

dividingByIntegerthe divisor

defaultingToIntegerthe value to answer with when there is no remainder

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

Example

constant teamSize: Integer = 3

expect 7::remainder(dividingBy teamSize, defaultingTo 0)::is(1)
expect 7::remainder(dividingBy 0, defaultingTo 0)::is(0)

remainder(dividingBy divisor: NonZeroInteger, as kind: Division) -> Integer

Answers what is left over, paired with the quotient in the named way.

The entries above answer the #Euclidean pairing, which is why this one names no default. The #Truncating Case answers a remainder carrying the sign of the dividend, so -7::remainder(dividingBy 3, as #Truncating) is -1 rather than 2. The two agree wherever the dividend is not negative.

NameTypeDescription

dividingByNonZeroIntegerthe divisor, proven not to be zero

asDivisionthe pairing to read the remainder under

Returns the remainder.

Example

expect -7::remainder(dividingBy 3, as #Truncating)::is(-1)
expect -7::remainder(dividingBy 3, as #Euclidean)::is(2)

quotient

on Integer

Answers how many whole divisors fit.

This is the other half of the same Euclidean division as remainder, and the two agree: quotient · divisor + remainder is the original Integer. The remainder is never negative, so the quotient floors towards negative infinity rather than truncating towards zero. For example, 7::quotient(dividingBy 3) is 2, and -7::quotient(dividingBy 3) is -3, leaving a remainder of 2. A zero divisor answers empty, and the defaultingTo: entry answers the given Integer instead.

quotient(dividingBy divisor: Integer) -> Optional<Integer>

Answers the quotient over a divisor nothing is known about.

NameTypeDescription

dividingByIntegerthe divisor

Returns the quotient, or nothing when dividing by zero.

Example

constant teamSize: Integer = 3

expect 7::quotient(dividingBy teamSize)::is(2)
expect 7::quotient(dividingBy 0)::isEmpty()

quotient(dividingBy divisor: NonZeroInteger) -> Integer

Answers the quotient over a divisor proven not to be zero.

The division can not fail, so the answer is the quotient itself rather than an Optional.

NameTypeDescription

dividingByNonZeroIntegerthe divisor, proven not to be zero

Returns the quotient.

Example

expect 7::quotient(dividingBy 3)::is(2)
expect -7::quotient(dividingBy 3)::is(-3)

quotient(
	dividingBy divisor: Integer,
	defaultingTo fallback: Integer,
) -> Integer

Answers the quotient, with a value to answer when the divisor is zero.

NameTypeDescription

dividingByIntegerthe divisor

defaultingToIntegerthe value to answer with when there is no quotient

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

Example

constant teamSize: Integer = 3

expect 7::quotient(dividingBy teamSize, defaultingTo 0)::is(2)
expect 7::quotient(dividingBy 0, defaultingTo 0)::is(0)

quotient(
	dividingBy divisor: NonZeroInteger,
	toward direction: Rounding,
) -> Integer

Answers how many whole divisors fit, rounded in the named direction.

The answer is the exact quotient rounded in that direction, so 7::quotient(dividingBy 2, toward #Up) is 4. The entries above pair their quotient with a remainder that is never negative. That pairing is the floor for a positive divisor and the ceiling for a negative one. So #Down answers what they answer for every divisor above zero.

NameTypeDescription

dividingByNonZeroIntegerthe divisor, proven not to be zero

towardRoundingthe direction to round the quotient in

Returns the quotient.

Example

expect 7::quotient(dividingBy 2, toward #Up)::is(4)
expect -7::quotient(dividingBy 2, toward #TowardZero)::is(-3)

raise

on Integer

Raises the Integer to the given power.

A non-negative exponent answers an Integer, and a negative one answers the exact reciprocal as a Rational. Zero to the power of zero is one. Raising this Integer to an exponent proven not to be negative can not fail. A receiver proven not to be zero can not fail either, and answers through NonZeroInteger. Zero raised to a negative power answers empty, and the defaultingTo: entry answers the given value instead.

raise(to exponent: Integer) -> Optional<Integer | Rational>

NameTypeDescription

toIntegerthe exponent

Returns the power, or nothing when raising zero to a negative power.

Example

constant base: Integer = 10

expect base::raise(to 3)::is(1000)
expect base::raise(to -2)::is(1/100)
expect 0::raise(to -1)::isEmpty()

raise(
	to exponent: Integer,
	defaultingTo fallback: Integer | Rational,
) -> Integer | Rational

Raises the Integer to the given power, and answers the given value when there is no power.

NameTypeDescription

toIntegerthe exponent

defaultingToInteger | Rationalthe value to answer with when there is no power

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

Example

constant base: Integer = 10

expect base::raise(to -1, defaultingTo 0)::is(1/10)
expect 0::raise(to -1, defaultingTo 0)::is(0)

raise(to exponent: NonNegativeInteger) -> Integer

Raises the Integer to an exponent proven not to be negative.

Every Integer has such a power and every one of them is whole. So the answer is the power itself rather than an Optional, and it is an Integer rather than a Rational.

NameTypeDescription

toNonNegativeIntegerthe exponent, proven not to be negative

Returns the power.

Example

expect 3::raise(to 4)::is(81)
expect 0::raise(to 0)::is(1)

on NonZeroInteger

Raises this NonZeroInteger to the given power.

A base that is not zero has every power, so the answer is the power itself rather than an Optional. An exponent proven not to be negative narrows that answer to an Integer.

raise(to exponent: Integer) -> Integer | Rational

Raises this NonZeroInteger to the given power.

A non-negative exponent answers an Integer, and a negative one answers the exact reciprocal as a Rational.

NameTypeDescription

toIntegerthe exponent

Returns the power.

Example

expect 2::raise(to -2)::is(1/4)
expect -2::raise(to -1)::is(-1/2)

raise(to exponent: NonNegativeInteger) -> Integer

Raises this NonZeroInteger to an exponent proven not to be negative.

Every such power is whole, so the answer is an Integer rather than a Union. The entry is Integer's own, declared here as well, because a receiver carrying more proof must not answer wider than one carrying none.

NameTypeDescription

toNonNegativeIntegerthe exponent, proven not to be negative

Returns the power.

Example

expect -2::raise(to 3)::is(-8)
expect -2::raise(to 0)::is(1)

on PositiveInteger

raise(to exponent: NonNegativeInteger) -> PositiveInteger

Raises this PositiveInteger to an exponent proven not to be negative.

Every such power is whole and above zero. Zero as an exponent answers one.

NameTypeDescription

toNonNegativeIntegerthe exponent, proven not to be negative

Returns the power, which is above zero.

Example

expect 2::raise(to 10)::is(1024)
expect 5::raise(to 0)::is(1)

squareRoot

on Integer

Answers the exact square root.

A perfect square answers an Integer, and any other non-negative Integer answers an exact Algebraic. A negative Integer answers empty, and the defaultingTo: entry answers the given value instead. A receiver proven not to be negative answers the root itself, through NonNegativeInteger.

squareRoot() -> Optional<Integer | Algebraic>

Returns the root, or nothing for a negative Integer.

Example

constant area: Integer = 9

expect area::squareRoot()::is(3)
expect -4::squareRoot()::isEmpty()

squareRoot(
	defaultingTo fallback: Integer | Algebraic,
) -> Integer | Algebraic

Answers the exact square root, with a value to answer for a negative Integer.

NameTypeDescription

defaultingToInteger | Algebraicthe value to answer with when there is no root

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

Example

constant area: Integer = 9

expect area::squareRoot(defaultingTo 0)::is(3)
expect -4::squareRoot(defaultingTo 0)::is(0)

on NonNegativeInteger

squareRoot() -> Integer | Algebraic

Answers the exact square root of this NonNegativeInteger.

A negative Integer is the only one with no real root, and the receiver is proven not to be one. So the answer is the root itself rather than an Optional. A perfect square answers an Integer, and every other value answers an exact Algebraic.

Returns the root.

Example

constant area: NonNegativeInteger = 49

expect area::squareRoot()::is(7)
expect 0::squareRoot()::is(0)

on PositiveInteger

squareRoot() -> PositiveInteger | Algebraic

Answers the exact square root of this PositiveInteger.

A perfect square above zero has a root above zero, and every other value answers an exact Algebraic.

Returns the root.

Example

expect 49::squareRoot()::is(7)
expect 2::squareRoot()::toString()::is("√2")

Comparing

isLessThan

on Integer

Answers whether this Integer is strictly below the given number.

isLessThan(_ other: Integer) -> Boolean

Answers whether this Integer is strictly below another Integer.

NameTypeDescription

_Integerthe Integer to compare against

Returns true when this Integer is below the other.

Example

expect 1::isLessThan(2)
expect 2::isLessThan(2)::negate()

isLessThan(_ other: Rational) -> Boolean

Answers whether this Integer is strictly below a Rational.

NameTypeDescription

_Rationalthe Rational to compare against

Returns true when this Integer is below the Rational.

Example

expect 1::isLessThan(3/2)
expect 2::isLessThan(3/2)::negate()

isLessThanOrEqualTo

on Integer

Answers whether this Integer is below the given number, or equal to it.

isLessThanOrEqualTo(_ other: Integer) -> Boolean

Answers whether this Integer is below another Integer, or equal to it.

NameTypeDescription

_Integerthe Integer to compare against

Returns true when this Integer is not above the other.

Example

expect 2::isLessThanOrEqualTo(2)
expect 3::isLessThanOrEqualTo(2)::negate()

isLessThanOrEqualTo(_ other: Rational) -> Boolean

Answers whether this Integer is below a Rational, or equal to it.

An Integer equals a Rational only when that Rational is whole.

NameTypeDescription

_Rationalthe Rational to compare against

Returns true when this Integer is not above the Rational.

Example

expect 2::isLessThanOrEqualTo(4/2)
expect 2::isLessThanOrEqualTo(3/2)::negate()

isGreaterThan

on Integer

Answers whether this Integer is strictly above the given number.

isGreaterThan(_ other: Integer) -> Boolean

Answers whether this Integer is strictly above another Integer.

NameTypeDescription

_Integerthe Integer to compare against

Returns true when this Integer is above the other.

Example

expect 3::isGreaterThan(2)
expect 2::isGreaterThan(2)::negate()

isGreaterThan(_ other: Rational) -> Boolean

Answers whether this Integer is strictly above a Rational.

NameTypeDescription

_Rationalthe Rational to compare against

Returns true when this Integer is above the Rational.

Example

expect 2::isGreaterThan(3/2)
expect 1::isGreaterThan(3/2)::negate()

isGreaterThanOrEqualTo

on Integer

Answers whether this Integer is above the given number, or equal to it.

isGreaterThanOrEqualTo(_ other: Integer) -> Boolean

Answers whether this Integer is above another Integer, or equal to it.

NameTypeDescription

_Integerthe Integer to compare against

Returns true when this Integer is not below the other.

Example

expect 2::isGreaterThanOrEqualTo(2)
expect 1::isGreaterThanOrEqualTo(2)::negate()

isGreaterThanOrEqualTo(_ other: Rational) -> Boolean

Answers whether this Integer is above a Rational, or equal to it.

An Integer equals a Rational only when that Rational is whole.

NameTypeDescription

_Rationalthe Rational to compare against

Returns true when this Integer is not below the Rational.

Example

expect 2::isGreaterThanOrEqualTo(4/2)
expect 1::isGreaterThanOrEqualTo(3/2)::negate()

isBetween

on Integer · provided by Orderable

isBetween(_ lower: Integer, and upper: Integer) -> 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.

NameTypeDescription

_Integerone bound of the range, included

andIntegerthe other bound of the range, included

Returns true when the value is within the bounds.

Example

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

clamp

on Integer · provided by Orderable

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

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.

NameTypeDescription

betweenIntegerone bound of the range

andIntegerthe other bound of the range

Returns the clamped value.

Example

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)

Testing

isEven

on Integer

isEven() -> Boolean

Answers whether the Integer is divisible by two.

Zero is even.

Example

expect 4::isEven()
expect 0::isEven()
expect 7::isEven()::negate()

isOdd

on Integer

isOdd() -> Boolean

Answers whether the Integer is not divisible by two.

Example

expect 7::isOdd()
expect -3::isOdd()
expect 4::isOdd()::negate()

isPositive

on Integer

isPositive() -> Boolean

Answers whether the Integer is above zero.

Zero is neither positive nor negative.

Example

expect 5::isPositive()
expect 0::isPositive()::negate()

isNegative

on Integer

isNegative() -> Boolean

Answers whether the Integer is below zero.

Zero is neither positive nor negative.

Example

expect -5::isNegative()
expect 0::isNegative()::negate()

isZero

on Integer

isZero() -> Boolean

Answers whether the Integer is exactly zero.

Example

expect 0::isZero()
expect 3::isZero()::negate()

isWholeNumber

on Integer

isWholeNumber() -> Boolean

Answers whether the Integer is a whole number.

Every Integer is whole, so the answer is always true.

Example

expect 7::isWholeNumber()

isMultiple

on Integer

isMultiple(of divisor: Integer) -> Boolean

Answers whether the Integer is a whole multiple of the given divisor.

Zero is a multiple of every Integer. A zero divisor answers false: there is no remainder to read, and an empty answer is not zero.

NameTypeDescription

ofIntegerthe divisor

Returns true when the division leaves no remainder.

Example

expect 12::isMultiple(of 4)
expect 0::isMultiple(of 7)
expect 12::isMultiple(of 0)::negate()

isPrime

on Integer

isPrime() -> Boolean

Answers whether the Integer has exactly two whole divisors above zero.

Two is the lowest prime. Zero, one and every negative Integer are not prime. The test is a Miller-Rabin test over the first twelve primes as witnesses. It decides every Integer below 3317044064679887385961981 exactly. A larger Integer it accepts is a strong probable prime to those twelve witnesses.

Returns true when the Integer is prime.

Example

expect 97::isPrime()
expect 2::isPrime()
expect 1::isPrime()::negate()

Sign and rounding

absolute

on Integer

absolute() -> NonNegativeInteger

Answers the Integer without its sign, which is its distance from zero.

Returns the distance, which is never negative.

Example

expect -7::absolute()::is(7)
expect 0::absolute()::is(0)

on NonZeroInteger

absolute() -> PositiveInteger

Answers this NonZeroInteger without its sign, which is its distance from zero.

The receiver is not zero, so its distance from zero is above zero. So the answer is a PositiveInteger.

Returns the distance, which is above zero.

Example

expect -7::absolute()::is(7)

negate

on Integer

negate() -> Integer

Answers the Integer with its sign flipped.

Example

expect 7::negate()::is(-7)
expect -7::negate()::is(7)

on NonZeroInteger

negate() -> NonZeroInteger

Answers this NonZeroInteger with its sign flipped.

Negation keeps a value away from zero, so the answer is a NonZeroInteger too.

Returns the negation, which is not zero.

Example

expect 7::negate()::is(-7)
expect -7::negate()::is(7)

round

on Integer

Answers the Integer, rounded in the named direction.

An Integer is already whole and is on every decimal grid, so every entry here answers the receiver itself. The direction is #Nearest when a call names none.

round(toward direction: Rounding = #Nearest) -> Integer

Answers the Integer, rounded in the named direction.

NameTypeDescription

towardRounding = #Nearestthe direction to round in, #Nearest when it is left out

Returns the Integer itself.

Example

expect 7::round()::is(7)
expect 7::round(toward #Up)::is(7)

round(
	toPlaces places: Integer,
	toward direction: Rounding = #Nearest,
) -> Integer

Answers the Integer, rounded to a decimal grid of the given width.

NameTypeDescription

toPlacesIntegerhow many decimal places to keep

towardRounding = #Nearestthe direction to round in, #Nearest when it is left out

Returns the Integer itself.

Example

expect 1234::round(toPlaces 2)::is(1234)

approximate

on Integer

approximate(
	toPlaces places: NonNegativeInteger,
	toward direction: Rounding = #Nearest,
) -> Rational

Answers the Integer read off a decimal grid of the given width.

An Integer is on every decimal grid, so the answer is the receiver itself as a Rational. The entries of this name on Algebraic and on Transcendental are what make an irrational readable as a number. This one is what lets a Number receiver reach the family.

NameTypeDescription

toPlacesNonNegativeIntegerhow many decimal places to keep

towardRounding = #Nearestthe direction to round in, #Nearest when it is left out

Returns the Integer itself, as a Rational.

Example

expect 3::approximate(toPlaces 2)::is(3)

Number theory

greatestCommonDivisor

on Integer

greatestCommonDivisor(with other: Integer) -> NonNegativeInteger

Answers the largest Integer that divides both this Integer and the given one.

The sign of either Integer is ignored, so the answer is never negative. Zero is divided by every Integer, so the divisor of zero and an Integer is that Integer without its sign. The divisor of two zeroes is zero.

NameTypeDescription

withIntegerthe Integer to share a divisor with

Returns the greatest common divisor, which is never negative.

Example

expect 12::greatestCommonDivisor(with 18)::is(6)
expect -4::greatestCommonDivisor(with 6)::is(2)
expect 0::greatestCommonDivisor(with -5)::is(5)

leastCommonMultiple

on Integer

leastCommonMultiple(with other: Integer) -> NonNegativeInteger

Answers the smallest Integer above zero that both this Integer and the given one divide.

The sign of either Integer is ignored, so the answer is never negative. Zero has no multiple above zero, so a zero operand answers zero. The product of the two answers holds for every pair: leastCommonMultiple · greatestCommonDivisor is the product of the two Integers without its sign.

NameTypeDescription

withIntegerthe Integer to share a multiple with

Returns the least common multiple, which is never negative.

Example

expect 4::leastCommonMultiple(with 6)::is(12)
expect -4::leastCommonMultiple(with 6)::is(12)
expect 0::leastCommonMultiple(with 6)::is(0)

factorial

on Integer

Answers the product of every Integer from one up to this Integer.

The factorial of zero is one. A negative Integer has no factorial, and the defaultingTo: entry answers the given Integer instead. A receiver proven not to be negative answers the factorial itself, through NonNegativeInteger.

factorial() -> Optional<PositiveInteger>

Returns the factorial, or nothing for a negative Integer.

Example

constant guests: Integer = 4

expect guests::factorial()::is(24)
expect -1::factorial()::isEmpty()

factorial(defaultingTo fallback: Integer) -> Integer

Answers the factorial, with a value to answer for a negative Integer.

NameTypeDescription

defaultingToIntegerthe value to answer with when there is no factorial

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

Example

constant guests: Integer = 4

expect guests::factorial(defaultingTo 0)::is(24)
expect -1::factorial(defaultingTo 0)::is(0)

on NonNegativeInteger

factorial() -> PositiveInteger

Answers the product of every Integer from one up to this NonNegativeInteger.

A negative Integer is the one receiver with no factorial, and the receiver is proven not to be one. So the answer is the factorial itself rather than an Optional. The factorial of zero is one.

Returns the factorial, which is above zero.

Example

expect 5::factorial()::is(120)
expect 0::factorial()::is(1)

Converting

toRational

on Integer

toRational() -> Rational

Answers the Integer as a Rational.

Every Integer is a Rational over one, so the crossing never fails. The Rational is whole, and prints as the digits alone.

Returns the Rational holding this value.

Example

expect 3::toRational()::is(3/1)
expect 3::toRational()::toString()::is("3")

Each type below is a checked refinement: a type with a condition. A value has the type only once the compiler knows the condition holds, and Checked refinements shows how it finds out. Under each one, Tighter here lists the methods above that return a more precise type when called on it. Returned by lists the methods that return it.

NonZeroInteger

type NonZeroInteger = Integer where @::isNot(0)

The Integers that are not zero, as a checked refinement of Integer.

A value carries a proof of the predicate before it is one of these. The proof is what lets an operation say it can not fail. A division by one of these answers a Rational rather than an Optional, and negate and absolute stay within the proof.

Tighter here multiply, divide, raise, absolute, negate

Returned by NonZeroInteger::multiply(with:), NonZeroInteger::negate(), NonZeroRational::numerator()

NonNegativeInteger

type NonNegativeInteger = Integer where @::isGreaterThanOrEqualTo(0)

The Integers from zero upward, as a checked refinement of Integer.

An exponent proven to be one of these raises any Integer to a whole power. A receiver proven to be one has a real square root. Both operations answer an Optional without the proof.

Tighter here add, multiply, squareRoot, factorial

Returned by Dictionary::length(), Dictionary::count(where:), Integer::absolute(), Integer::greatestCommonDivisor(with:), Integer::leastCommonMultiple(with:), NonNegativeInteger::add(_:), NonNegativeInteger::multiply(with:), List::length(), List::count(of:), List::count(where:), Randomness::drawInteger(below:), String::length(), String::count(of:), String::count(of:comparing:)

PositiveInteger

type PositiveInteger = Integer where @::isPositive()

The Integers above zero, as a checked refinement of Integer.

A value above zero is neither zero nor below it, so one of these is accepted wherever a NonZeroInteger or a NonNegativeInteger is wanted. Addition, multiplication and raise answer one of these again.

Tighter here add, multiply, raise, squareRoot

Returned by NonEmptyDictionary::length(), GroupedList::tally(), GroupedNonEmptyList::tally(), Integer::factorial(), NonZeroInteger::absolute(), NonNegativeInteger::add(_:), NonNegativeInteger::factorial(), PositiveInteger::add(_:), PositiveInteger::multiply(with:), PositiveInteger::raise(to:), PositiveInteger::squareRoot(), NonEmptyList::length(), Rational::denominator(), NonEmptyString::length()

Modes

Each mode below is a choice whose cases carry no payload. You pass one to a method to choose how the method works. Every mode has is, isNot and toString, and cases() on its name lists its cases, as in Division.cases(). None of them is written out for a mode: Protocols says where each one comes from.

Division

choice Division {
	Euclidean,
	Truncating,
}

How a division pairs its quotient with its remainder.

Under #Euclidean the remainder is never negative, so it is always below the divisor's magnitude. Under #Truncating the remainder takes the sign of the dividend, which is what an algorithm ported from another language expects.

Cases #Euclidean, #Truncating

Taken by

Integer::remainder(dividingBy:as:)

At a glance

Creating

parse

Equality, ordering and printing

is

isNot

compare

toString

Arithmetic

add

subtract

multiply

divide

remainder

quotient

raise

squareRoot

Comparing

isLessThan

isLessThanOrEqualTo

isGreaterThan

isGreaterThanOrEqualTo

isBetween

clamp

Testing

isEven

isOdd

isPositive

isNegative

isZero

isWholeNumber

isMultiple

isPrime

Sign and rounding

absolute

negate

round

approximate

Number theory

greatestCommonDivisor

leastCommonMultiple

factorial

Converting

toRational

Refinements

NonZeroInteger

NonNegativeInteger

PositiveInteger

Modes

Division