{"id":16964994,"url":"https://github.com/propensive/hypotenuse","last_synced_at":"2025-04-11T23:02:57.371Z","repository":{"id":216658629,"uuid":"741929488","full_name":"propensive/hypotenuse","owner":"propensive","description":"A rigorous and consistent foundation for numerical and arithmetic programming","archived":false,"fork":false,"pushed_at":"2025-02-06T14:29:39.000Z","size":946,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-20T01:38:45.564Z","etag":null,"topics":["arithmetic","bitwise-operations","scala","typesafety","unsigned-integers"],"latest_commit_sha":null,"homepage":"https://soundness.dev/hypotenuse/","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/propensive.png","metadata":{"files":{"readme":".github/readme.md","changelog":null,"contributing":".github/contributing.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-11T12:04:42.000Z","updated_at":"2025-02-06T14:29:42.000Z","dependencies_parsed_at":"2024-03-07T08:48:13.016Z","dependency_job_id":"2c6a2e08-b40b-4644-b94b-0bc8470e6333","html_url":"https://github.com/propensive/hypotenuse","commit_stats":null,"previous_names":["propensive/hypotenuse"],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/propensive%2Fhypotenuse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/propensive%2Fhypotenuse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/propensive%2Fhypotenuse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/propensive%2Fhypotenuse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/propensive","download_url":"https://codeload.github.com/propensive/hypotenuse/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239805886,"owners_count":19700203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arithmetic","bitwise-operations","scala","typesafety","unsigned-integers"],"created_at":"2024-10-13T23:44:47.285Z","updated_at":"2025-02-20T08:31:38.707Z","avatar_url":"https://github.com/propensive.png","language":"Scala","readme":"[\u003cimg alt=\"GitHub Workflow\" src=\"https://img.shields.io/github/actions/workflow/status/propensive/hypotenuse/main.yml?style=for-the-badge\" height=\"24\"\u003e](https://github.com/propensive/hypotenuse/actions)\n[\u003cimg src=\"https://img.shields.io/discord/633198088311537684?color=8899f7\u0026label=DISCORD\u0026style=for-the-badge\" height=\"24\"\u003e](https://discord.com/invite/MBUrkTgMnA)\n\u003cimg src=\"/doc/images/github.png\" valign=\"middle\"\u003e\n\n# Hypotenuse\n\n__A rigorous and consistent foundation for numerical and arithmetic programming.__\n\n_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 *i*nteger, *u*nsigned integer, *f*loating-point number and *b*itmap—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 `NaN`s can be optionally checked.\n\n## Features\n\n- consistent representations of 8, 16, 32 and 64-bit signed and unsigned integers, and 32 and 64-bit floating point numbers\n- uses opaque types and method inlining for native performance\n- stricter typesafety over the standard Java/Scala primitive types\n- opt-in range checking (e.g. overflow)\n- distinct types for 8, 16, 32 and 64-bit bitmaps\n- integration with standard mathematical operations (from `java.lang.Math`) through extension methods\n- avoids implicit widening to `Int`\n\n\n## Availability\n\n\n\n\n\n\n\n## Getting Started\n\n### Philosophy\n\n_Hypotenuse_ adopts a philosophy of rigor and regularity to numerical\noperations in Scala. This includes consistent naming of types, methods and\noperators; accurate distinction in the typesystem between types with different\npurposes; and, accurate representation of exceptional numeric operations.\n\nThese enhancements are all implemented with minimal impact on performance,\nusing opaque type aliases and inlining.\n\n#### Consistent naming\n\nIn addition to 1-bit `Boolean`s, the JVM provides 8-bit, 16-bit, 32-bit and\n64-bit integers, called `Byte`, `Short`, `Int` and `Long`. Hypotenuse provides\nthese types with new names: `I8`, `I16`, `I32` and `I64`.\n\nAdditionally, the floating-point types, `Float` and `Double`, are provided as,\n`F32` and `F64`.\n\nIn itself, this provides only marginally better clarity, but it sets up a\nnaming scheme for other related types.\n\n#### Distinct types\n\nFor each of the `I` types, representing a two's-complement signed integer, a\n`U` type is also provided, representing an unsigned, non-negative integer with\na larger maximum value: `U8`, `U16`, `U32` and `U64`.\n\nThese types all define the standard arithmetic and related operations, but do\nnot define any bitwise operations like shifts, `AND` or `OR`. The collection of\nbits in a number is either intended for arithmetic or interpretation as a raw\nset of bits. So it is not logical for a single type to provide both bitwise\n_and_ arithmetic operations. Thus, the types `B8`, `B16`, `B32` and `B64` are\nprovided for bitwise operations.\n\nConversions between these different types are trivially available with methods\nsuch as `b8` and `u32` (which will compile to no-ops in bytecode, if possible).\n\n#### Strict Exceptions\n\nMany arithmetic operations on numeric types are inherently _unsafe_, yet\nunlikely to be problematic for the majority of use cases.\n\nFor example, adding two positive 32-bit integers may result in overflow, where\neach operand is small enough to be represented in 32 bits, but their sum is too\nlarge. Unless detected, the result will be a negative number, which might cause\nproblems in algorithms which rely, for example, on the invariant that the sum\nof two positive numbers is also positive.\n\nBut a 32-bit integer is so large that many applications would use only small\nintegers, and will not come remotely close to the limits where overflow can\noccur. In these cases, any checks to detect overflow would be redundant.\n\nOther operations, such as division by an integer, may fail if the divisor is\nzero. But it may also be known, from context, that the divisor is nonzero, and\nthat the division operation is safe. On the JVM, a division by zero is an\nunchecked exception, so the operation is _partial_.\n\nTherefore, it is sometimes appropriate to explicitly handle exceptional cases,\nand on other occasions, unnecessary and therefore not worth the effort.\nHypotenuse caters for both scenarios, with additional safety checks controlled\nby an import. For example, a division by zero will raise a `DivisionError` if,\n```scala\nimport arithmeticOptions.division.checked\n```\nis in scope, and the `DivisionError` must be handled (or explicitly ignored).\n\nEnabling this and other checks can ensure that all partial or undesirable\narithmetic operations will be checked, and the programmer will be forced to\nhandle each exceptional case.\n\n### Inequalities\n\nHypotenuse provides more elegant syntax for writing inequalities with both\nupper and lower bounds.\n\nTraditionally, a bounds predicate might be written,\n```scala\nlowerBound \u003c= x \u0026\u0026 x \u003c upperBound\n```\nbut Hypotenuse makes it possible to write this more intuitively as:\n```scala\nlowerBound \u003c= x \u003c upperBound\n```\n\nThis is semantically identical to the original, and compiles into it via a\nstraightforward rewrite.\n\n\n\n\n## Status\n\nHypotenuse is classified as __embryotic__. For reference, Soundness projects are\ncategorized into one of the following five stability levels:\n\n- _embryonic_: for experimental or demonstrative purposes only, without any guarantees of longevity\n- _fledgling_: of proven utility, seeking contributions, but liable to significant redesigns\n- _maturescent_: major design decisions broady settled, seeking probatory adoption and refinement\n- _dependable_: production-ready, subject to controlled ongoing maintenance and enhancement; tagged as version `1.0.0` or later\n- _adamantine_: proven, reliable and production-ready, with no further breaking changes ever anticipated\n\nProjects at any stability level, even _embryonic_ projects, can still be used,\nas long as caution is taken to avoid a mismatch between the project's stability\nlevel and the required stability and maintainability of your own project.\n\nHypotenuse is designed to be _small_. Its entire source code currently consists\nof 1687 lines of code.\n\n## Building\n\nHypotenuse will ultimately be built by Fury, when it is published. In the\nmeantime, two possibilities are offered, however they are acknowledged to be\nfragile, inadequately tested, and unsuitable for anything more than\nexperimentation. They are provided only for the necessity of providing _some_\nanswer to the question, \"how can I try Hypotenuse?\".\n\n1. *Copy the sources into your own project*\n   \n   Read the `fury` file in the repository root to understand Hypotenuse's build\n   structure, dependencies and source location; the file format should be short\n   and quite intuitive. Copy the sources into a source directory in your own\n   project, then repeat (recursively) for each of the dependencies.\n\n   The sources are compiled against the latest nightly release of Scala 3.\n   There should be no problem to compile the project together with all of its\n   dependencies in a single compilation.\n\n2. *Build with [Wrath](https://github.com/propensive/wrath/)*\n\n   Wrath is a bootstrapping script for building Hypotenuse and other projects in\n   the absence of a fully-featured build tool. It is designed to read the `fury`\n   file in the project directory, and produce a collection of JAR files which can\n   be added to a classpath, by compiling the project and all of its dependencies,\n   including the Scala compiler itself.\n   \n   Download the latest version of\n   [`wrath`](https://github.com/propensive/wrath/releases/latest), make it\n   executable, and add it to your path, for example by copying it to\n   `/usr/local/bin/`.\n\n   Clone this repository inside an empty directory, so that the build can\n   safely make clones of repositories it depends on as _peers_ of `hypotenuse`.\n   Run `wrath -F` in the repository root. This will download and compile the\n   latest version of Scala, as well as all of Hypotenuse's dependencies.\n\n   If the build was successful, the compiled JAR files can be found in the\n   `.wrath/dist` directory.\n\n## Contributing\n\nContributors to Hypotenuse are welcome and encouraged. New contributors may like\nto look for issues marked\n[beginner](https://github.com/propensive/hypotenuse/labels/beginner).\n\nWe suggest that all contributors read the [Contributing\nGuide](/contributing.md) to make the process of contributing to Hypotenuse\neasier.\n\nPlease __do not__ contact project maintainers privately with questions unless\nthere is a good reason to keep them private. While it can be tempting to\nrepsond to such questions, private answers cannot be shared with a wider\naudience, and it can result in duplication of effort.\n\n## Author\n\nHypotenuse was designed and developed by Jon Pretty, and commercial support and\ntraining on all aspects of Scala 3 is available from [Propensive\nO\u0026Uuml;](https://propensive.com/).\n\n\n\n## Name\n\nThe _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.\n\nIn general, Soundness project names are always chosen with some rationale,\nhowever it is usually frivolous. Each name is chosen for more for its\n_uniqueness_ and _intrigue_ than its concision or catchiness, and there is no\nbias towards names with positive or \"nice\" meanings—since many of the libraries\nperform some quite unpleasant tasks.\n\nNames should be English words, though many are obscure or archaic, and it\nshould be noted how willingly English adopts foreign words. Names are generally\nof Greek or Latin origin, and have often arrived in English via a romance\nlanguage.\n\n## Logo\n\nThe logo shows a right-angled triange, the longest side of which is its _hypotenuse_.\n\n## License\n\nHypotenuse is copyright \u0026copy; 2025 Jon Pretty \u0026 Propensive O\u0026Uuml;, and\nis made available under the [Apache 2.0 License](/license.md).\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpropensive%2Fhypotenuse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpropensive%2Fhypotenuse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpropensive%2Fhypotenuse/lists"}