Hypotenuse

A rigorous and consistent foundation for numerical and arithmetic programming.

Hypotenuse has the goal of improving the safety and aesthetics of working with numbers in Scala, without compromising on performance. It achieves this by several means. Numeric types have a consistent naming scheme of a letter—U, I, F or B for integer, unsigned integer, floating-point number and bitmap—and a number of bits, from 8 to 64. Unsigned and signed (two's complement) numbers have different types, and both are distinct from bitmap types which are used for bitwise operations; though conversions between them are easy (and free in terms of performance). Associated mathematical methods that were provided through the java.lang.Math class are made available, more consistently, as extension methods on each type. And operations such as division by zero on an integer, overflow or production of NaNs can be optionally checked.

Features

• consistent representations of 8, 16, 32 and 64-bit signed and unsigned integers, and 32 and 64-bit floating point numbers
• uses opaque types and method inlining for native performance
• stricter typesafety over the standard Java/Scala primitive types
• opt-in range checking (e.g. overflow)
• distinct types for 8, 16, 32 and 64-bit bitmaps
• integration with standard mathematical operations (from java.lang.Math) through extension methods
• avoids implicit widening to Int

Availability

Getting Started

Philosophy

Hypotenuse adopts a philosophy of rigor and regularity to numerical operations in Scala. This includes consistent naming of types, methods and operators; accurate distinction in the typesystem between types with different purposes; and, accurate representation of exceptional numeric operations.

These enhancements are all implemented with minimal impact on performance, using opaque type aliases and inlining.

Consistent naming

In addition to 1-bit Booleans, the JVM provides 8-bit, 16-bit, 32-bit and 64-bit integers, called Byte, Short, Int and Long. Hypotenuse provides these types with new names: I8, I16, I32 and I64.

Additionally, the floating-point types, Float and Double, are provided as, F32 and F64.

In itself, this provides only marginally better clarity, but it sets up a naming scheme for other related types.

Distinct types

For each of the I types, representing a two's-complement signed integer, a U type is also provided, representing an unsigned, non-negative integer with a larger maximum value: U8, U16, U32 and U64.

These types all define the standard arithmetic and related operations, but do not define any bitwise operations like shifts, AND or OR. The collection of bits in a number is either intended for arithmetic or interpretation as a raw set of bits. So it is not logical for a single type to provide both bitwise and arithmetic operations. Thus, the types B8, B16, B32 and B64 are provided for bitwise operations.

Conversions between these different types are trivially available with methods such as b8 and u32 (which will compile to no-ops in bytecode, if possible).

Strict Exceptions

Many arithmetic operations on numeric types are inherently unsafe, yet unlikely to be problematic for the majority of use cases.

For example, adding two positive 32-bit integers may result in overflow, where each operand is small enough to be represented in 32 bits, but their sum is too large. Unless detected, the result will be a negative number, which might cause problems in algorithms which rely, for example, on the invariant that the sum of two positive numbers is also positive.

But a 32-bit integer is so large that many applications would use only small integers, and will not come remotely close to the limits where overflow can occur. In these cases, any checks to detect overflow would be redundant.

Other operations, such as division by an integer, may fail if the divisor is zero. But it may also be known, from context, that the divisor is nonzero, and that the division operation is safe. On the JVM, a division by zero is an unchecked exception, so the operation is partial.

Therefore, it is sometimes appropriate to explicitly handle exceptional cases, and on other occasions, unnecessary and therefore not worth the effort. Hypotenuse caters for both scenarios, with additional safety checks controlled by an import. For example, a division by zero will raise a DivisionError if,

import arithmeticOptions.division.checked

is in scope, and the DivisionError must be handled (or explicitly ignored).

Enabling this and other checks can ensure that all partial or undesirable arithmetic operations will be checked, and the programmer will be forced to handle each exceptional case.

Inequalities

Hypotenuse provides more elegant syntax for writing inequalities with both upper and lower bounds.

Traditionally, a bounds predicate might be written,

lowerBound <= x && x < upperBound

but Hypotenuse makes it possible to write this more intuitively as:

lowerBound <= x < upperBound

This is semantically identical to the original, and compiles into it via a straightforward rewrite.

Status

Hypotenuse is classified as embryotic. For reference, Soundness projects are categorized into one of the following five stability levels:

• embryonic: for experimental or demonstrative purposes only, without any guarantees of longevity
• fledgling: of proven utility, seeking contributions, but liable to significant redesigns
• maturescent: major design decisions broady settled, seeking probatory adoption and refinement
• dependable: production-ready, subject to controlled ongoing maintenance and enhancement; tagged as version 1.0.0 or later
• adamantine: proven, reliable and production-ready, with no further breaking changes ever anticipated

Projects at any stability level, even embryonic projects, can still be used, as long as caution is taken to avoid a mismatch between the project's stability level and the required stability and maintainability of your own project.

Hypotenuse is designed to be small. Its entire source code currently consists of 1579 lines of code.

Building

Hypotenuse will ultimately be built by Fury, when it is published. In the meantime, two possibilities are offered, however they are acknowledged to be fragile, inadequately tested, and unsuitable for anything more than experimentation. They are provided only for the necessity of providing some answer to the question, "how can I try Hypotenuse?".

1. Copy the sources into your own project

   Read the fury file in the repository root to understand Hypotenuse's build structure, dependencies and source location; the file format should be short and quite intuitive. Copy the sources into a source directory in your own project, then repeat (recursively) for each of the dependencies.

   The sources are compiled against the latest nightly release of Scala 3. There should be no problem to compile the project together with all of its dependencies in a single compilation.

2. Build with Wrath

   Wrath is a bootstrapping script for building Hypotenuse and other projects in the absence of a fully-featured build tool. It is designed to read the fury file in the project directory, and produce a collection of JAR files which can be added to a classpath, by compiling the project and all of its dependencies, including the Scala compiler itself.

   Download the latest version of wrath, make it executable, and add it to your path, for example by copying it to /usr/local/bin/.

   Clone this repository inside an empty directory, so that the build can safely make clones of repositories it depends on as peers of hypotenuse. Run wrath -F in the repository root. This will download and compile the latest version of Scala, as well as all of Hypotenuse's dependencies.

   If the build was successful, the compiled JAR files can be found in the .wrath/dist directory.

Contributing

Contributors to Hypotenuse are welcome and encouraged. New contributors may like to look for issues marked beginner.

We suggest that all contributors read the Contributing Guide to make the process of contributing to Hypotenuse easier.

Please do not contact project maintainers privately with questions unless there is a good reason to keep them private. While it can be tempting to repsond to such questions, private answers cannot be shared with a wider audience, and it can result in duplication of effort.

Author

Hypotenuse was designed and developed by Jon Pretty, and commercial support and training on all aspects of Scala 3 is available from Propensive OÜ.

Name

The hypotenuse is the longest edge of a right-angled triangle, whose length, according to Pythagoras' Theorem, is the square root of the sum of the squares of the other two sides. Pythagoras founded the school known as the Pythagorean Brotherhood, and it is to this school of mathematics that Hypotenuse alludes.

In general, Soundness project names are always chosen with some rationale, however it is usually frivolous. Each name is chosen for more for its uniqueness and intrigue than its concision or catchiness, and there is no bias towards names with positive or "nice" meanings—since many of the libraries perform some quite unpleasant tasks.

Names should be English words, though many are obscure or archaic, and it should be noted how willingly English adopts foreign words. Names are generally of Greek or Latin origin, and have often arrived in English via a romance language.

Logo

The logo shows a right-angled triange, the longest side of which is its hypotenuse.

License

Hypotenuse is copyright © 2024 Jon Pretty & Propensive OÜ, and is made available under the Apache 2.0 License.