Today is Leap Day, so I'd like to introduce you to a new Swift package I've been working on for over 2 years:
Time is a package that makes date and time calculations more expressive and safe in Swift. It's built on the power of Foundation's APIs, but smooths away their many rough and ambiguous edges. It relies heavily on Swift's generics to guarantee that the calculations you're performing are calendrically correct. If you'd like an overview of how it works, be sure to check out the documentation.
I'm releasing it today as an 0.9.0 version. I hope you will clone it and use it in your apps!
now() is the same thing as thisInstant(). It has both because now() is the "proper" naming, but thisInstant() also helps it be consistent with thisDay(), thisMonth(), thisSecond(), etc.
Naming has been my #1 most difficult task with this framework. If you look on the "Roadmap" page, you'll see that I definitely want to rename Value, but only if I can find something better. I've spent weeks scouring sources for more definitive names for "a subset of calendrical values that may or may not be anchored to an actual calendrical point", but haven't come up with anything that really feels "better".
Difference used to be Delta; I renamed it in the hopes that Difference would be a bit clearer. Absolute (and the WIP Relative) used to be Anchored and Floating. AbsoluteValueSequence is basically just derived from Absolute.
I'm absolutely open to suggestions on better names. I'd prefer names that are terms-of-art, but I have yet to find such nomenclature.
Yeah, I don’t know what the types should be named, but I think the names should at least indicate that they have something to do with time. Spellings like Value, Difference, Anchored, and Delta seem too general-purpose, especially when used in an app that imports many different libraries.
From reading the documentation, I have one comment, and that’s that your usage of the term ”unsafe” seems to be at odds with how it’s generally used in Swift.
”Unsafe” in Swift generally refers to memory safety. For example, in the Standard Library unsafe in the name of a type, method or parameter means that Swift’s standard guarantee of memory safety no longer applies, and unless you know what you’re doing you might have memory leaks, memory corruption or even undefined behavior on your hands.
You seem to be using ”unsafe” to mean that an adjustment may throw. That’s not the same. To someone accustomed to the Standard Library’s usage of ”unsafe”, it makes these adjustments look much scarier than they actually are.
The name that comes to mind is FailableAdjustment, since that’s essentially what they are: adjustments that can fail. I guess you could argue that ”failable” also means that they should return nil instead of throw, since that’s what failable means when we talk about initializers. I don’t have enough experience with the API yet to know if that would make sense. Regardless, something ”failable” that doesn't return nil seems to me a lesser sin than something ”unsafe” that’s completely memory safe.