ladvoc / BijectiveDictionary

A specialized dictionary structure offering bijective mapping and bidirectional O(1) access.
https://jacobgelman.com/posts/swift-bijective-dictionary
MIT License
4 stars 1 forks source link
bijective-maps collections data-structures dictionary sequence swift swift-testing

Swift Bijective Dictionary

Supported Swift versions Supported swift platforms

A bijective dictionary is a specialized dictionary that offers efficient bidirectional access in O(1) time, making it ideal for scenarios where the performance of reverse lookups is a key consideration. However, this comes at the cost of increased memory usage.

Documentation »

Basic Usage

Bijective dictionary closely mirrors the standard dictionary type from the standard library, sharing many of the same initializers, methods, and properties. The key distinction lies in its ability to access elements bidirectionally. In a bijective dictionary, keys and values are referred to as “left values” and “right values” respectively, to avoid confusion, since either can be used to access the other.

The following example demonstrates creating a bijective dictionary from a dictionary literal that maps IANA time zones to their corresponding UTC offsets (not considering daylight savings time):

var timeZones: BijectiveDictionary = [
    "America/Los_Angeles": -8,
    "Europe/London": 0
    "Europe/Kiev": 2,
    "Asia/Singapore": 8
]

With the dictionary constructed, an entry in timeZones can be accessed either by its left value (time zone) or right value (UTC offset):

print(timeZones[left: "America/Los_Angeles"]) // prints -8
print(timeZones[right: 2]) // prints "Europe/Kiev"

The same subscripts can also be used to set values when the dictionary is mutable:

timeZones[left: "Asia/Seoul"] = 9
timeZones[right: -9] = "America/Anchorage"

Installation

Add BijectiveDictionary as a package dependency in your project's package manifest:

// swift-tools-version:6.0
import PackageDescription

let package = Package(
    name: "MyPackage",
    dependencies: [
        .package(
            url: "https://github.com/ladvoc/BijectiveDictionary.git",
            .upToNextMinor(from: "0.1.0")
        )
    ],
    targets: [
        .target(
            name: "MyTarget",
            dependencies: [
                .product(name: "BijectiveDictionary", package: "BijectiveDictionary")
            ]
        )
    ]
)

Project Status

The project is in an early development phase, with the current version being 0.1.0. At this point, all basic functionality is implemented and tested. However, the following tasks should be completed prior to the v1.0 release:

Your contributions are welcome!

License

This project is licensed under the MIT License. See the LICENSE file for details.