Open-sourcing our Swift Time package
We've open-sourced our module for handling date and time on iOS.
Today we’ve open-sourced our Time library which we use across our iOS and macOS codebase. Time is a cross-platform Swift package which simplifies calendar, date and time handling.
You can find our code along with documentation on all its features and how to use it on GitHub.
Introducing Time
Time was built to make working with date and time simple and to avoid the common mistakes made when using the standard Date object in Swift.
The Swift Foundation library provides a Date object which represents a single point in time, independent of any calendar or time zone. This object needs to be used in conjunction with a DateFormatter, TimeZone, Locale, DateComponents and Calendar in order to perform calendar arithmetic and create meaningful representations of dates and times.
The API provided by Foundation is very powerful however it has shortfalls which make it difficult and error prone to use. Firstly it’s API is verbose, requires using many of the objects listed above, and requires many lines of code to do something simple like calendar arithmetic or converting a date to a meaningful string.
The only way to represent components of a date (such as the calendar date, day of the week, time of day etc.) is to use a DateComponents. This object is a collection of over a dozen mutable properties, and it’s not clear when it’s passed in code what it’s trying to represent. It’s also very easy to create a DateComponents instance which is invalid and converting it to meaningful representations, or doing any calendar arithmetic has a large performance overhead.
Another issue with the Foundation API is that it is easy to forget to include important properties such as the time zone and locale, which will default to the system’s current value when forgotten, producing no warnings.
Time uses these tools and provides a simple API to allow our developers to represent a CalendarDate, TimeOfDay, Timestamp, CalendarDateRange, TimeRange and more.
Key features
- Provides types which accurately represents the information we want to store, and semantically conveys what is being stored to the reader of the code.
- Makes performing calendar arithmetic fast and simple.
- Simplifies serialising and parsing date and time information.
- Provides an easy way to stub the time for writing unit tests.
Example usage
As you might expect, reading the time is done using a Clock:
You can also create specific dates and times:
Calendar arithmetic is trivial:
Combining and converting units of date and time is also easy and type safe:
Finally, creating localised strings is a breeze:
The importance of open source
Open sourcing our code means publishing it publically, and providing a license which allows any other developers to freely modify and use our work to suit their own needs.
Open source software allows technology to move forward. It allows common software problems to be solved once and reused in many applications allowing the developers to concerntrate on what makes their application unique. It also allows developers to share knowledge, learn from one another, and collaborate on problems to improve and build out software.
At Fora Health we rely heavily on open source projects to build all of the software we do. Fora Health (our flagship mobile app) uses open source software for generating state machines, creating custom DSLs for our chat scripts, writing automated tests, and so much more. Even the programming language Swift is an open source project that we rely on to develop on Apple platforms.
Open sourcing Time is one way we want to give back to the developer community and we hope that other Apple platform developers will be able to benefit and enjoy using it as much as we have.