First-class Roman numeral support for Swift

RomanNumeralKit

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

• [x] Constants provided for all 3,999 standard Roman numerals.
• [x] Support for subtractive and additive notations.
• [x] Arithmetic using Roman-numeral-oriented algorithms - no integer calculations!
• [x] Conversions to-and-from popular types (e.g. String, Int).
• [x] Extensions for real-world usage (e.g. copyright text).
• [x] 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)   // True
XCTAssertEqual(MMM - DXCI, MMCDIX)  // True
XCTAssertEqual(XI * CCXIX, MMCDIX)  // True

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.

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"

Authors

Kyle Hughes

GitHub