Contents

eneko/datetemplates

DateTemplates is a library that provides a simple way to generate date formatting templates

Declarative Syntax

DateTemplates uses a declarative syntax so you can simply state which elements should be included in the formatted date string. For example, you can write that you want a date consisting of full week day, and time, without having to worry about template symbols, localization discrepancies, or clock-format.

let template = DateTemplate().dayOfWeek(.full).time()
print(template.localizedString(from: Date()))

This template will render dates as follows:

| Locale | Formatted String | | -------- | ------------------- | | "en_US" | "Thursday 12:00 AM" | | "es_ES" | "jueves, 0:00" | | "ja_JP" | "木曜日 0:00" | | "ru_RU" | "четверг 00:00" | | "ar_EG" | "الخميس ١٢:٠٠ ص" |

Examples

The following examples assume "America/Los_Angeles" time-zone and "en_US" locale:

| Template | Formatted String | | ---------- | --------------------| | DateTemplate().time().timeZone() | "12:00 AM PST" | | DateTemplate().dayOfWeek().day().month(.abbreviated).year() | "Thu, Jan 1, 1970" | | DateTemplate().day().month(.abbreviated).year(length: 2).era() | "Mar 15, 44 BC" |

Under the Hood

A DateTemplate instance provides a declarative way to composing date formatting template strings. These are regular, standard templates that can be used with DateFormatter.

let dateTemplate = DateTemplate().year().month().day().hours().minutes()
print(dateTemplate.template) // "yMdjmm"

These template strings can be used to generate a localized date format:

let template = DateTemplate().year().month().day().hours().minutes().template
let format = DateFormatter.dateFormat(fromTemplate: template, options: 0, locale: nil) ?? template
print(format) // "M/d/y, h:mm a" (assuming en_US locale)

For convenience, DateTemplate provides a localizedFormat method:

let template = DateTemplate().year().month().day().hours().minutes()
let format = template.localizedFormat()
print(format) // "M/d/y, h:mm a" (assuming en_US locale)

Localized format strings can be used with DateFormatter to convert dates to strings (and viceversa):

let formatter = DateFormatter()
formatter.locale = Locale(identifier: "en_US")
formatter.dateFormat = format // "M/d/y, h:mm a" 
formatter.timeZone = TimeZone(secondsFromGMT: 0)
let string = formatter.string(from: Date(timeIntervalSince1970: 0))
print(string) // "1/1/1970, 12:00 AM"

For convenience, DateTemplate provides a localizedString method:

let template = DateTemplate().year().month().day().hours().minutes()
let string = template.localizedString(from: Date(timeIntervalSince1970: 0),
                                      locale: Locale("en_US"), 
                                      timeZone: TimeZone(secondsFromGMT: 0))
print(string) // "1/1/1970, 12:00 AM"

Benefits of Using DateTemplates

These are some benefits:

  • Easily composition of custom localized formats: specify which

elements to include, and don't worry about the rest.

  • Bug prevention:

- Ever heard of the difference between "YYYY" and "yyyy"? - How about the difference between "MM" and "mm"? - 12hr vs. 24 hr clock - etc.

Installation

For Xcode projects 🛠

Add Swift Package to Xcode via File -> Swift Packages -> Add Package Dependency...

For Swift Packages 📦

Add DateTemplates dependency to Packages.swift

dependencies: [
    // other dependencies
    .package(url: "https://github.com/eneko/DateTemplates", from: "0.1.0")
],
targets: [
    .target(name: "YourPackage", dependencies: [
        // other dependencies
        "DateTemplates"
    ]),
    // other targets
]

License

MIT License

Copyright (c) 2020 Eneko Alonso

Package Metadata

Repository: eneko/datetemplates

Default branch: main

README: README.md