RomanNumeralKit

First-class Roman numeral support for Swift.

When in Rome, code as the Romans code.

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

• 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.

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.

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

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

Add RomanNumeralKit to your Podfile:

pod 'RomanNumeralKit', '~> 1.0.0`

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

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

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

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

import RomanNumeralKit

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

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 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"

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.

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

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?

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

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

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

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

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"
}

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"

Kyle Hughes

RomanNumeralKit is not accepting source contributions at this time.

RomanNumeralKit is available under the MIT License.