Skip to content
First-class Roman numeral support for Swift.
Swift Other
  1. Swift 99.8%
  2. Other 0.2%
Branch: mainline
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
RomanNumeralKit.xcodeproj Initial commit Aug 29, 2019
Sources/RomanNumeralKit Initial commit Aug 29, 2019
Tests/RomanNumeralKitTests Initial commit Aug 29, 2019
.gitignore Initial commit Aug 29, 2019
.swift-version Initial commit Aug 29, 2019
.swiftformat Initial commit Aug 29, 2019
.swiftlint.yml Initial commit Aug 29, 2019
.travis.yml Initial commit Aug 29, 2019
CHANGELOG.md Initial commit Aug 29, 2019
LICENSE Initial commit Aug 29, 2019
Package.resolved Initial commit Aug 29, 2019
Package.swift Initial commit Aug 29, 2019
README.md
RomanNumeralKit.podspec Initial commit Aug 29, 2019
codecov.yml Initial commit Aug 29, 2019

README.md

RomanNumeralKit

CocoaPods Version Languages Platform

Build Status codecov

Twitter

First-class Roman numeral support for Swift.

When in Rome, code as the Romans code.

Introduction

Meaningful usage of this framework requires understanding what Roman numerals are. Background information can be found on Wikipedia.

Features

  • Constants provided for all 3,999 standard Roman numerals.
  • Support for subtractive and additive notations.
  • Arithmetic using Roman-numeral-oriented algorithms - no integer calculations!
  • Conversions to-and-from popular types (e.g. String, Int).
  • Extensions for real-world usage (e.g. copyright text).
  • Conformance to all applicable numeric protocols.

Limitations

Fixed Numerical Range

Standard Roman numerals as we understand them were limited to values from 1 to 3,999. There is no concept of 0. Modern scholars have proposed extensions of the numeric system to support values greater than 3,999 but we do not recognize any of these extensions and decry the proposers to be heretics.

Most programs do not deal with numbers higher than 3,999, and the world won't exist past the year 3,999 in the Gregorian calendar, so there is no need to worry.

iPhone Model Names

RomanNumeralKit does not support conversions to-and-from recent iPhone model names such as "Xs".

Requirements

  • iOS 10.0+ / macOS 10.12+ / tvOS 10.0+ / watchOS 3.0+
  • Xcode 10.2+
  • Swift 5+

Installation

CocoaPods

Add RomanNumeralKit to your Podfile:

pod 'RomanNumeralKit', '~> 1.0.0`

Please visit the CocoaPods website for general CocoaPods usage and installation instructions.

Swift Package Manager

Add RomanNumeralKit to the dependencies value of your Package.swift:

dependencies: [
    .package(url: "https://github.com/kylehughes/RomanNumeralKit.git", from: "1.0.0")
]

Usage

Import RomanNumeralKit at the top of the Swift file you want to use it in.

import RomanNumeralKit

Constants

Constants are provided for all valid Roman numerals, from 1 to 3,999. You should never need to use an initializer unless you are doing conversions from other types.

All constants can be accessed directly by their using their uppercase Unicode characters.

print(MMCDIX)           // Prints "MMCDIX"
print(MMCDIX.symbols)   // Prints "[M, M, C, D, I, X]"

XCTAssertEqual(MMCDIX, RomanNumeral(.M, .M, .C, .D, .I, .X))    // True

Conversions

We provide convenient mechanisms to convert RomanNumerals to-and-from popular types.

It should be noted that these are true conversions: the backing values of RomanNumeral instances are groups of tally marks. We do not hold Intreferences because it would not be in the spirit of the framework.

Constructors

Constructors are provided to convert Ints and Strings to RomanNumerals.

print(RomanNumeral(from: 2409))     // Prints "MMCDIX"
print(RomanNumeral(from: "MMCDIX")) // Prints "MMCDIX"

We also support conversions from Int and String literals when the RomanNumeral type can be inferred.

let numeralFromInt: RomanNumeral = 2409
let numeralFromString: RomanNumeral = "MMCDIX"

print(numeralFromInt)       // Prints "MMCDIX"
print(numeralFromString)    // Prints "MMCDIX"

Properties

Instance-level properties are provided to convert RomanNumerals into Int and String values.

print(MMCDIX.intValue)      // Prints "2409"
print(MMCDIX.stringValue)   // Prints "MMCDIX"

We also provide various *Convertible protocols to allow types to return different RomanNumeral and RomanNumeralSymbol representations of themselves.

Arithmetic

Addition, subtraction, and multiplication operations are supported (and required) thanks to our conformance to the Numeric protocol. We use algorithms that allow us to directly manipulate the Roman numeral symbols as opposed to doing conversions to-and-from Ints.

XCTAssertEqual(MD + CMIX, MMCDIX)
XCTAssertEqual(MMM - DXCI, MMCDIX)
XCTAssertEqual(XI * CCXIX, MMCDIX)

Performance

Our committment to authenticity does have implications.

The following table compares the performance Int arithmetic operations to Roman numeral arithmetic operations on a new MacBook Pro.

Operation (100x) Int RomanNumeral % Slower
Addition 0.00000127s 0.151s 11,889,663.78%
Subtraction 0.00000151s 0.0761s 5,992,025.98%
Multiplication 0.00000204s 0.0575s 4,527,459.06%

It should be noted that this is much faster than any person from Ancient Rome could do arithmetic. Who can take issue with progress?

Copyright Text

The most useful feature we provide is automatic formatting of Copyright text.

print(MDCCLXXVI.copyrightText)  // Prints "Copyright © MDCCLXXVI"

Additive Notation

The default notation for this framework is subtractive notation - that is what instances of RomanNumerals represent. We provide the AdditiveRomanNumeral struct for initialization of numerals using additive notation. We also support conversions between the notations.

Both notations implement the RomanNumeralProtocol protocol and support the same general interface.

let additiveNumeral = AdditiveNotation(.M, .M, .C, .C, .C, .C, .V, .I, .I, .I, .I)

print(additiveNumeral)              // Prints "MMCCCCVIIII"
print(additiveNumeral.intValue)     // Prints "2409"

XCTAssertEqual(additiveRomanNumeral.romanNumeral, MMCDIX)           // True
XCTAssertEqual(MMCDIX.additiveRomanNumeral, additiveRomanNumeral)   // True

Extensions

We provide a variety of extensions on existing Swift types to make common operations easier.

Calendar & DateComponent Extensions

Calendar objects, and the DateComponents they produce, are able to convert years into RomanNumerals.

if let currentYear = Calendar.current.currentYearAsRomanNumeral {
    print(currentYear)                  // Prints "MMXIX"
    print(currentYear.intValue)         // Prints "2019"
    print(currentYear.copyrightText)    // Prints "Copyright © MMXIX"
}

if let americasBirthYear = Calendar.current.yearAsRomanNumeral(fromDate: americasBirthDate) {
    print(americasBirthYear)            // Prints "MDCCLXXVI"
    print(americasBirthYear.intValue)   // Prints "1776"
    print(americasBirthYear.copyrightText)    // Prints "Copyright © MDCCLXXVI"
}

Int & String Extensions

We conform Int and String to the *RomanNumeralConvertible protocols to complete the ouroboros with these foundational types.

print(2409.romanNumeral)                    // Prints "MMCDIX"
print(2409.additiveRomanNumeral)            // Prints "MMCCCCVIIII"
print("MMCDIX".romanNumeral)                // Prints "MMCDIX"
print("MMCCCCVIIII".additiveRomanNumeral)   // Prints "MMCCCCVIIII"

Development

Pre-Commit Hooks

We use Komondor to install pre-commit hooks to run formatting and linting. The following command should be run once after cloning the repository.

swift run komondor install

License

RomanNumeralKit is available under the MIT License.

Authors

Kyle Hughes

my twitter

You can’t perform that action at this time.