{"id":20711114,"url":"https://github.com/cypherpoet/modulusoperandi","last_synced_at":"2025-03-11T06:21:51.532Z","repository":{"id":63907277,"uuid":"305217288","full_name":"CypherPoet/ModulusOperandi","owner":"CypherPoet","description":"Declarative modular arithmetic for Swift Integers and Floating-Point types that supports Euclidean, flooring, and truncating division algorithms.","archived":false,"fork":false,"pushed_at":"2020-11-15T16:56:09.000Z","size":5557,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-18T20:47:32.480Z","etag":null,"topics":["math","modulo-arithmetics","modulus","swift","swift-math","swift-modulus","swift-package-manager","swift-packages"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CypherPoet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":["https://tippin.me/@cypher_poet"]}},"created_at":"2020-10-18T23:39:59.000Z","updated_at":"2020-11-15T16:50:03.000Z","dependencies_parsed_at":"2022-11-28T22:50:54.636Z","dependency_job_id":null,"html_url":"https://github.com/CypherPoet/ModulusOperandi","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":"CypherPoet/swift-package-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CypherPoet%2FModulusOperandi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CypherPoet%2FModulusOperandi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CypherPoet%2FModulusOperandi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CypherPoet%2FModulusOperandi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CypherPoet","download_url":"https://codeload.github.com/CypherPoet/ModulusOperandi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242981927,"owners_count":20216503,"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":["math","modulo-arithmetics","modulus","swift","swift-math","swift-modulus","swift-package-manager","swift-packages"],"created_at":"2024-11-17T02:14:05.964Z","updated_at":"2025-03-11T06:21:51.511Z","avatar_url":"https://github.com/CypherPoet.png","language":"Swift","readme":"# ModulusOperandi\n\n\u003cp align=\"center\"\u003e\n   \u003cimg width=\"600px\" src=\"./Resources/Assets/banner-logo-2.png\" alt=\"Banner Logo\"\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Swift-5.3-F06C33.svg\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/iOS-13.0+-865EFC.svg\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/iPadOS-13.0+-F65EFC.svg\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/macOS-10.14+-179AC8.svg\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/tvOS-13.0+-41465B.svg\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/watchOS-6.0+-1FD67A.svg\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" /\u003e\n    \u003ca href=\"https://github.com/apple/swift-package-manager\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/spm-compatible-brightgreen.svg?style=flat\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://twitter.com/cypher_poet\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/Contact-@cypher_poet-lightgrey.svg?style=flat\" alt=\"Twitter: @cypher_poet\" /\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n\n_Declarative, multi-algorithm modular arithmetic for Swift Integers and Floating-Point types._\n\nModular arithmetic algorithms [come in variants that use either Euclidean, truncating, or flooring division](https://en.wikipedia.org/wiki/Modulo_operation#Variants_of_the_definition). Furthermore, Swift's built-in `%` operator \u0026mdash; while used as a modulus in some languages \u0026mdash; is [strictly used as a _remainder_ operator](https://docs.swift.org/swift-book/LanguageGuide/BasicOperators.html#ID64).\n\nThese nuances can lead modular arithmetic code that's ambiguous in both intent and correctness \u0026mdash; which is what `ModulusOperandi` attempts to solve.\n\n\u003cp /\u003e\n\n\n\n## Features\n\n- ✅ Declarative API that allows for choosing between [Euclidean](https://en.wikipedia.org/wiki/Euclidean_division#Division_theorem), [Truncating](https://developer.apple.com/documentation/swift/float/2886166-truncatingremainder), or [Flooring](https://www.sololearn.com/Discuss/1453039/floor-division-and-modulo-operator) Modular Arithmetic.\n- ✅ Euclidean by default.\n- ✅ Support for conformances to `BinaryInteger` and `FloatingPointInteger`.\n- ✅ Command Line tool for performing calculations in the Terminal.\n\n\n## Installation\n\n### Xcode Projects\n\nSelect `File` -\u003e `Swift Packages` -\u003e `Add Package Dependency` and enter `https://github.com/CypherPoet/ModulusOperandi`.\n\n\n### Swift Package Manager Projects\n\nYou can add `ModulusOperandi` as a dependency in your `Package.swift` file:\n\n```swift\nlet package = Package(\n    //...\n    dependencies: [\n        .package(url: \"https://github.com/CypherPoet/ModulusOperandi\", from: \"0.2.2\"),\n    ],\n    //...\n)\n```\n\nThen simply `import ModulusOperandi` wherever you’d like to use it.\n\n\n## Usage\n\nAfter importing `ModulusOperandi` in a file, types that conform to `BinaryInteger`  and  `FloatingPointInteger` will be extended with a `modulus` function.\n\nThis function treats its value as the `dividend` and takes a `divisor` of the same type. It also takes an optional `mode` argument to choose between Euclidean, Truncating, or Flooring Modular Arithmetic.\n\n**By default, the `mode` will be Euclidean**\n\n```swift\nimport ModulusOperandi\n\nlet dividend = 5\nlet divisor = 3\n\ndividend.modulo(divisor)   // 2\ndividend.modulo(-divisor)  // 2\n-dividend.modulo(divisor)  // -2\n-dividend.modulo(-divisor) // -2\n\n// Same as...\ndividend.modulo(divisor, mode: .euclidean)     // 2\ndividend.modulo(-divisor, mode: .euclidean)    // 2\n-dividend.modulo(divisor, mode: .euclidean)    // -2\n-dividend.modulo(-divisor, mode: .euclidean)   // -2\n```\n\n```swift\nimport ModulusOperandi\n\nlet dividend = 5\nlet divisor = 3\n\ndividend.modulo(3, mode: .flooring)    // 2\ndividend.modulo(-3, mode: .flooring)   // -1\n-dividend.modulo(3, mode: .flooring)   // -2\n-dividend.modulo(-3, mode: .flooring)  // 1\n```\n\n```swift\nimport ModulusOperandi\n\nlet dividend = 5\nlet divisor = 3\n\ndividend.modulo(3, mode: .truncating)    // 2\ndividend.modulo(-3, mode: .truncating)   // 2\n-dividend.modulo(3, mode: .truncating)   // -2\n-dividend.modulo(-3, mode: .truncating)  // -2\n```\n\n\n## Command Line Tool\n\n![ModulusOperandi CLI Examples](./Resources/Screenshots/cli-examples.png)\n\n`ModulusOperandi` also ships with a command line tool that lets you perform calculations directly from the command line.\n\nTo install it, clone the project and run `make`:\n\n```\n$ git clone git@github.com:CypherPoet/ModulusOperandi.git\n$ cd ModulusOperandiCLI\n$ make\n```\n\nThe command line tool will be installed as `modulo`, and running `modulo --help` will present some helpful usage instructions:\n\n\u003c/br\u003e\n\u003cdetails\u003e\n\u003csummary\u003eSee Help Menu\u003c/summary\u003e\n\n```sh\nmodulo --help\n```\n\n```sh\nOVERVIEW: Multi-algorithm modular arithmetic for Swift integers and\nfloating-Point types.\n\nModular arithmetic algorithms come in variants that use either Euclidean,\ntruncating, or flooring division.\n\nThis tool acts as a CLI for the `ModulusOperandi` Swift package -- which allows\nyou to perform modular arithmetic according to your desired algorithm.\n\n\n📝 Note on Negative Numbers\n----------------------------------------------\n\nTo use negative numbers, prefix the argument with `\\ ` (including the space).\n\nFor example, -5 mod 4 would be passed as:\n    modulo \\ -5 4\n\n-5 mod -4 would be passed as:\n    modulo \\ -5 \\ -4\n\n\n🔗 More Info On Modular Arithmetic\n----------------------------------------------\n    - https://en.wikipedia.org/wiki/Modulo_operation#Variants_of_the_definition\n\n\nUSAGE: modulo \u003cdividend\u003e \u003cdivisor\u003e [--euclidean] [--flooring] [--truncating]\n\nARGUMENTS:\n  \u003cdividend\u003e              The dividend to perform division against.\n  \u003cdivisor\u003e               The divisor to use as a \"modulus\".\n\nOPTIONS:\n  --euclidean/--flooring/--truncating\n                          The algorithm to use for computing results. (default:\n                          euclidean)\n  --version               Show the version.\n  -h, --help              Show help information.\n\n```\n\n\u003c/details\u003e\n\u003c/br\u003e\n\n### Negative Numbers\n\nDisambiguating negative numbers from argument flags is a notorious challenge for Command Line interfaces. Currently, support for this in Swift's Argument Parser appears to be an [ongoing area of development](https://github.com/apple/swift-argument-parser/issues/31). In the meantime, though, the `modulo` command can take negative-number arguments via some clever escape syntax.\n\n**Simply prefix any negative number with `\\ ` (including the space). Like so:**\n\n`-5 mod 4`:\n```sh\nmodulo \\ -5 4\n```\n\n`-5 mod -4`:\n```sh\nmodulo \\ -5 \\ -4\n```\n\n`5 mod -4`:\n```sh\nmodulo 5 \\ -4\n```\n\n## Contributing\n\nContributions to `ModulusOperandi` are most welcome. Check out some of the [issue templates](./.github/ISSUE_TEMPLATE/) for more info.\n\n\n## Developing\n\n### Requirements\n\n- Xcode 12.0+ (for developing)\n\n\n### Generating Documentation\n\nDocumentation is generated by [Jazzy](https://github.com/realm/jazzy). Installation instructions can be found [here](https://github.com/realm/jazzy#installation), and as soon as you have it set up, docs can be generated simply by running `jazzy` from the command line.\n\n📝 Note that this will only generate the `docs` folder for you to view locally. This folder is being ignored by `git`, as an [action](./.github/workflows/PublishDocumentation.yml) exists to automatically generate docs and serve them on the project's `gh-pages` branch.\n\n\n\n## License\n\n`ModulusOperandi` is available under the MIT license. See the [LICENSE file](./LICENSE) for more info.\n","funding_links":["https://tippin.me/@cypher_poet"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypherpoet%2Fmodulusoperandi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcypherpoet%2Fmodulusoperandi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypherpoet%2Fmodulusoperandi/lists"}