Algebraic

is(_ other: Algebraic) -> Boolean

Answers whether both Algebraics are the same number.

Normal forms decide the answer exactly. No approximation is consulted.

Returns true when the numbers are equal.

constant golden = Number.GoldenRatio
constant rootFive = golden::multiply(with 2)::subtract(1)

expect rootFive::is(golden::subtract(1/2)::multiply(with 2))
expect rootFive::is(golden)::negate()

compare(to other: Algebraic) -> Ordering

Orders the Algebraic against another Algebraic.

The comparison is symbolic, so it is exact.

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

constant golden = Number.GoldenRatio
constant rootFive = golden::multiply(with 2)::subtract(1)

expect golden::compare(to rootFive)::is(#Less)
expect rootFive::compare(to golden::add(1/2))::is(#Greater)

toString() -> String

Answers the Algebraic as a String, in the exact symbolic form: √2, 3·√2 or 1 + √2.

One radical has one printed form, with one exception. Normalisation divides out square factors up to 65536, so a radicand p²·q with both primes above that is printed as written. The equal p·√q prints in the normalised form.

expect 2::squareRoot()::toString()::is("√2")
expect 18::squareRoot()::toString()::is("3·√2")
expect Number.GoldenRatio::toString()::is("1/2 + 1/2·√5")

toString(as format: NumberFormat) -> String

Answers the Algebraic as a decimal, or in the exact symbolic form, in the named format.

The #Decimal format rounds the expansion at the eightieth digit and writes it. An irrational expansion never ends, so the cap is always reached. Trailing zeros the rounding leaves are dropped, as they are for any Rational. The #Percent format writes one hundred times that same reading, taken two digits deeper so that eighty still stand after the point. The #Scientific format writes eighty digits after the point of the mantissa, and the power of ten after an e. The reading is taken at the eightieth digit of the mantissa, wherever the value falls. A value below one is read deeper than eighty places. The #Fraction format writes the symbolic form, since no ratio of two Integers is this number.

Returns the String representation of the Algebraic.

constant root = 2::squareRoot()

expect root::toString(as #Decimal)::starts(with "1.41421356237")
expect root::toString(as #Decimal)::length()::is(82)
expect root::toString(as #Fraction)::is("√2")

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

Answers the Algebraic as a decimal with exactly that many places.

The digits are padded with zeroes where the rounded value is shorter. The last digit kept is rounded in the named direction, and #Nearest is what a call that names none is given. A count below one rounds to a whole number, and no point is written. The #Percent format takes the count the same way, on one hundred times the value. The #Scientific format counts the digits of the mantissa after the point, at every magnitude. The value is read as many digits past the count as its own power of ten falls below zero. The #Fraction format ignores both the count and the direction, and writes the symbolic form.

Returns the String representation of the Algebraic.

constant root = 2::squareRoot()

expect root::toString(as #Decimal, toPlaces 3)::is("1.414")
expect root::toString(as #Decimal, toPlaces 3, toward #Up)::is("1.415")
expect root::toString(as #Percent, toPlaces 1)::is("141.4%")

isNot(_ other: Algebraic) -> Boolean

Answers whether the values differ.

Returns true when the values differ.

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

add(_ other: Integer) -> Algebraic

Answers the exact sum of the Algebraic and an Integer.

An Integer shifts the rational part and leaves the radical in place, so the sum is again an Algebraic.

Returns the exact sum.

expect 2::squareRoot()::add(1)::toString()::is("1 + √2")
expect 2::squareRoot()::add(-1)::toString()::is("-1 + √2")

add(_ other: Rational) -> Algebraic

Answers the exact sum of the Algebraic and a Rational.

A Rational shifts the rational part and leaves the radical in place, so the sum is again an Algebraic.

Returns the exact sum.

expect 2::squareRoot()::add(1/2)::toString()::is("1/2 + √2")

add(_ other: Algebraic) -> Optional<Rational | Algebraic>

Answers the exact sum of the two Algebraics.

Over the same radical the sum stays in the slice, and can collapse to a Rational. Over different radicals the sum falls outside what an Algebraic holds, and the answer is empty.

Returns the sum, or nothing when the radicals differ.

constant golden = Number.GoldenRatio
constant conjugate = golden::negate()::add(1)

expect golden::add(golden)::is(golden::multiply(with 2))
expect golden::add(conjugate)::is(1/1)

add(
	_ other: Algebraic,
	defaultingTo fallback: Rational | Algebraic,
) -> Rational | Algebraic

Answers the exact sum of the two Algebraics.

Over different radicals there is no sum, and the answer is the given value.

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

constant golden = Number.GoldenRatio

expect golden::add(golden, defaultingTo 0/1)::toString()::is("1 + √5")

subtract(_ other: Integer) -> Algebraic

Answers the exact difference of the Algebraic and an Integer.

An Integer shifts the rational part and leaves the radical in place, so the difference is again an Algebraic.

Returns the exact difference.

expect 2::squareRoot()::subtract(1)::toString()::is("-1 + √2")

subtract(_ other: Rational) -> Algebraic

Answers the exact difference of the Algebraic and a Rational.

A Rational shifts the rational part and leaves the radical in place, so the difference is again an Algebraic.

Returns the exact difference.

expect 2::squareRoot()::subtract(1/2)::toString()::is("-1/2 + √2")

subtract(_ other: Algebraic) -> Optional<Rational | Algebraic>

Answers the exact difference of the two Algebraics.

Over the same radical the difference stays in the slice, and can collapse to a Rational. Over different radicals there is no difference, and the answer is empty.

Returns the difference, or nothing when the radicals differ.

constant golden = Number.GoldenRatio

expect golden::subtract(golden::multiply(with 2))::is(golden::negate())
expect golden::subtract(golden::subtract(1))::is(1/1)

subtract(
	_ other: Algebraic,
	defaultingTo fallback: Rational | Algebraic,
) -> Rational | Algebraic

Answers the exact difference of the two Algebraics.

Over different radicals there is no difference, and the answer is the given value.

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

constant golden = Number.GoldenRatio
constant smaller = golden::subtract(1)

expect golden::subtract(smaller, defaultingTo 0/1)::is(1)

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

Answers the exact product of the Algebraic and an Integer.

An Integer scales both parts and leaves the radical in place. A zero factor collapses the product to the Rational zero.

Returns the exact product, an Algebraic or a Rational.

constant root = 2::squareRoot()
constant copies = 3

expect root::multiply(with copies)::toString()::is("3·√2")
expect root::multiply(with 0)::is(0)

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

Answers the exact product of the Algebraic and a Rational.

A Rational scales both parts and leaves the radical in place. A zero factor collapses the product to the Rational zero.

Returns the exact product, an Algebraic or a Rational.

constant root = 2::squareRoot()
constant half = 1/2

expect root::multiply(with half)::toString()::is("1/2·√2")
expect root::multiply(with 0/1)::is(0)

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

Answers the exact product of the two Algebraics.

Over the same radical the product stays exact: √2 · √2 is 2. Two pure radicals combine across radicals: √2 · √3 is √6. Anything else is empty.

Returns the product, or nothing when there is none.

constant golden = Number.GoldenRatio

expect golden::multiply(with golden)::is(golden::add(1))
expect golden::multiply(with golden::subtract(1))::is(1/1)

multiply(
	with other: Algebraic,
	defaultingTo fallback: Rational | Algebraic,
) -> Rational | Algebraic

Answers the exact product of the two Algebraics.

Where there is no product, the answer is the given value.

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

constant golden = Number.GoldenRatio
constant squared = golden::multiply(with golden, defaultingTo 0/1)

expect squared::is(golden::add(1))

multiply(with other: NonZeroInteger) -> Algebraic

Answers the exact product of the Algebraic and a factor proven not to be zero.

A non-zero Integer scales both parts and leaves the radical in place. The answer is again an Algebraic rather than a Union.

Returns the exact product.

expect 2::squareRoot()::multiply(with 3)::toString()::is("3·√2")
expect Number.GoldenRatio::multiply(with 2)::toString()::is("1 + √5")

multiply(with other: NonZeroRational) -> Algebraic

Answers the exact product of the Algebraic and a Rational factor proven not to be zero.

A Rational that is not zero scales both parts and leaves the radical in place. The answer is again an Algebraic rather than a Union.

Returns the exact product.

expect 2::squareRoot()::multiply(with 1/2)::toString()::is("1/2·√2")

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

Answers the exact quotient of the Algebraic and an Integer.

A divisor that is not zero scales both parts and leaves the radical in place. A zero divisor answers empty.

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

constant golden = Number.GoldenRatio
constant divisor = 2

expect golden::divide(by divisor)::is(golden::multiply(with 1/2))
expect golden::divide(by 0)::isEmpty()

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

Answers the exact quotient of the Algebraic and a Rational.

A divisor that is not zero scales both parts and leaves the radical in place. A zero divisor answers empty.

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

constant golden = Number.GoldenRatio
constant half = 1/2

expect golden::divide(by half)::is(golden::multiply(with 2))
expect golden::divide(by 0/1)::isEmpty()

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

Answers the exact quotient of the two Algebraics.

The divisor's conjugate gives its reciprocal, and the quotient is that product. It is empty wherever the matching product is empty.

Returns the quotient, or nothing when there is none.

constant golden = Number.GoldenRatio

expect golden::divide(by golden)::is(1/1)
expect golden::divide(by golden::subtract(1))::is(golden::add(1))

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

Answers the exact quotient of the Algebraic and an Integer.

A zero divisor answers the given value.

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

constant golden = Number.GoldenRatio
constant halved = golden::multiply(with 1/2)
constant divisor = 2

expect golden::divide(by divisor, defaultingTo golden)::is(halved)
expect golden::divide(by 0, defaultingTo golden)::is(golden)

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

Answers the exact quotient of the Algebraic and a Rational.

A zero divisor answers the given value.

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

constant golden = Number.GoldenRatio
constant doubled = golden::multiply(with 2)
constant half = 1/2

expect golden::divide(by half, defaultingTo golden)::is(doubled)
expect golden::divide(by 0/1, defaultingTo golden)::is(golden)

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

Answers the exact quotient of the two Algebraics.

Where there is no quotient, the answer is the given value.

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

constant golden = Number.GoldenRatio

expect golden::divide(by golden, defaultingTo 0/1)::is(1)

divide(by other: NonZeroInteger) -> Algebraic

Answers the exact quotient of the Algebraic and a divisor proven not to be zero.

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

Returns the exact quotient.

expect 2::squareRoot()::divide(by 2)::toString()::is("1/2·√2")

divide(by other: NonZeroRational) -> Algebraic

Answers the exact quotient of the Algebraic and a Rational divisor proven not to be zero.

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

Returns the exact quotient.

expect 2::squareRoot()::divide(by 1/2)::toString()::is("2·√2")

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

Answers the Algebraic raised to the given power, exactly.

The slice is closed under Integer powers, so every power is exact. A power can cancel the radical, so 2::squareRoot() squared is the Rational 2. A negative exponent answers the power of the reciprocal, which always exists, since an Algebraic is never zero. A zero exponent answers 1.

Returns the exact power, an Algebraic or a Rational.

constant root = 2::squareRoot()

expect root::raise(to 2)::is(2)
expect root::raise(to 3)::toString()::is("2·√2")
expect root::raise(to -2)::is(1/2)

isLessThan(_ other: Algebraic) -> 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: Algebraic) -> 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: Algebraic) -> 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: Algebraic) -> 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: Algebraic, and upper: Algebraic) -> 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: Algebraic, and highest: Algebraic) -> Algebraic

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)

isPositive() -> Boolean

Answers whether the Algebraic is above zero.

The sign of a + b·√d is exactly decidable. No approximation is consulted.

constant root = 2::squareRoot()

expect root::subtract(1.4142)::isPositive()
expect root::subtract(1.4143)::isPositive()::negate()

isNegative() -> Boolean

Answers whether the Algebraic is below zero.

The sign of a + b·√d is exactly decidable. No approximation is consulted.

constant root = 2::squareRoot()

expect root::subtract(1.4143)::isNegative()
expect root::isNegative()::negate()

isZero() -> Boolean

Answers whether the Algebraic is exactly zero.

An Algebraic carries a radical with a coefficient that is not zero, so the answer is always false.

expect 2::squareRoot()::isZero()::negate()

isWholeNumber() -> Boolean

Answers whether the Algebraic is a whole number.

An Algebraic is irrational, so it is never whole and the answer is always false.

expect 2::squareRoot()::isWholeNumber()::negate()

absolute() -> Algebraic

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

The sign of a + b·√d is exactly decidable. No approximation is consulted.

constant root = 2::squareRoot()

expect root::negate()::absolute()::is(root)
expect root::subtract(2)::absolute()::is(root::negate()::add(2))

negate() -> Algebraic

Answers the Algebraic with its sign flipped.

Negating an irrational leaves it irrational, so the answer is again an Algebraic.

constant root = 2::squareRoot()

expect root::negate()::toString()::is("-√2")
expect root::negate()::negate()::is(root)

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

Answers the Algebraic as a Rational on a decimal grid of the given width.

Five places answer the value rounded to hundred-thousandths, so 2::squareRoot() over five places answers 141421/100000. This Method is where a Program asks for digits in place of the exact value. The answer is exact all the same: it is the step of that grid the value rounds to. A width of no places answers a whole number, as a Rational.

Returns the value on the grid the width names.

constant root = 2::squareRoot()

expect root::approximate(toPlaces 5)::is(1.41421)
expect root::approximate(toPlaces 2, toward #Up)::is(1.42)
expect root::approximate(toPlaces 0)::is(1/1)

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

Answers the Algebraic as an Integer, rounded in the named direction.

Returns the rounded Integer.

constant root = 2::squareRoot()

expect root::round()::is(1)
expect root::round(toward #Up)::is(2)

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

Answers the Algebraic rounded to a decimal grid of the given width.

Two places round to hundredths. The answer is what approximate(toPlaces:toward:) answers, and a count below one rounds to a whole number. The entry stands here so that a Number receiver reaches round at every width, whichever kind it holds.

Returns the rounded Rational.

constant root = 2::squareRoot()

expect root::round(toPlaces 2)::is(1.41)
expect root::round(toPlaces 2, toward #Up)::is(1.42)
expect root::round(toPlaces 0)::is(1/1)

decimalExponent() -> Integer

Answers the power of ten at or below the Algebraic's distance from zero.

This is the exponent the #Scientific format writes after the e. A value between one and ten answers zero, and a value between a tenth and one answers minus one. The enclosure widens until it falls inside one such power of ten. That always happens: an Algebraic is irrational, so it is never a power of ten itself.

Returns the exponent of the power of ten the value falls on.

constant golden = Number.GoldenRatio

expect golden::decimalExponent()::is(0)
expect golden::subtract(1)::decimalExponent()::is(-1)
expect golden::multiply(with 10)::decimalExponent()::is(1)