rougeware/swift-contextuallyuniqueidentifier

Creating a new ID

To create a new ID, you must call .next(), for a new ID to be generated and returned:

struct Person: Identifiable, Codable {
    var id: COID = .next()
    let name: String
}


let person = Person(name: "Dax")

Encoding & Decoding an ID

COIDs are currently encoded as simple integers. One can expect the above Person instance to be encoded like this:

{
    "id": 7,
    "name": "Dax"
}

COID has built-in encoding and decoding, so nothing special need be done. Just use any Swift encoder/decoder, like this:

let jsonData = try JSONEncoder().encode(person)
let decodedPerson = try JSONDecoder().decode(Person.self, from: jsonData)
assert(person == decodedPerson)

The act of decoding an COID automatically assures that the ID is not used in any future calls to .next(). Encoding an COID, though, has no special behavior.

Stringification

To create a string form of a given ID, simply call .description, or pass it to String(describing:):

Text(verbatim: person.id.description)

If you have a string form of an ID already (e.g. one you got from calling .description), you may transform it back into an ContextuallyUniqueIdentifier with the .init(_:) initializer. Only valid ID strings will result in a new value; invalid ones result in nil. The subsystem will ensure that this ID is not returned by .next()

When you're done with an ID

If you no longer wish to use an ID (for example, the concept it was tracking has been deleted by the user), then you may pass it to ContextuallyUniqueIdentifier.recycle(id:):

mutating func remove(_ person: Person) {
    self.people.remove(person)
    COID.recycle(id: person.id)
}

Regions

Since version 1.1, App-Unique Identifiers are arranged into four groups, called "Regions":

1. ✅ General-use – A large amount of IDs which can be generated and registered. Though finite, it is a large enough range that client-side applications should not exceed its limit if using these APIs correctly. If your application is using enough IDs that this is too few, then this is not the package for you. I recommend using UUIDs insted. But seriously, if you use up all these IDs, that's Exbibytes of data; don't worry about it.
2. 🔒 Unused – A large amount of IDs which have not been allocated for any use. These cannot be used in any way. Future versions of COID might introduce usage of these. This blockage is to allow future changes to be nondestructive and backwards-compatible
3. *️⃣ Private-Use – A small amount of IDs which are manually and specifically requested. Like the Unicode private-use plane, this region of IDs has no specific intent/meaning, and allows the developer to ascribe specific meanings to each. The small size of this range means that there are no requests to generate a "next" one, and each specific one should be carefully chosen by the developer.
4. ❗️ Error – A single ID which signifies that an error has occurred

For a sense of how these are laid out, here's a not-to-scale diagram:

✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒
🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒
🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒
🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒 🔒
🔒 🔒 🔒 🔒 🔒 🔒 🔒 *️⃣ *️⃣ ❗️

This package comes with various APIs regarding these regions.

Package Metadata

Repository: rougeware/swift-contextuallyuniqueidentifier

Default branch: master

README: README.md