Date Formatting

Overview

SwiftDate exposes several convenient functions to print (and parse, of course) dates and time intervals as strings:

as custom string defined by tr35-31 format; for example "yyyy-MM-dd" for "2015-01-05"
as ISO8601 strings with all available sub specs
as .NET datetime format
as AltRSS and RSS datetime format
as extended string with date and time
time intervals in other time units; for example (date2 - date1).in(.hours)
human readable / colloquial strings; for example "1 hour ago", "1m", "now" etc. (with locale support)
time components between two dates; for example the differences between two dates as "2h,5m,3s"

Date to Custom Format

You can convert an instance of DateInRegion or Date to a string with a custom specified string as format using .string() function. A table of the available format specifiers is available in this Unicode standard spec and it's the same commonly used in Cocoa.

Declaration

Using .dateFormat:


                  // with DateFormat set to .custom([format string])

                  func string(format: DateFormat) -> String

Using shortcut function:


                  // shortcut to pass directly the format of the string

                  func string(custom: String) -> String

Parameters

format: a DateFormat struct. To use custom strings pass .custom() and pass the value of the formatter

Example

Date to ISO8601 Format

SwiftDate supports a full featured ISO8601 DateTime formatter. It allows you to specify your custom configuration for any variant of the specs. You can use

Declaration


                  // with DateFormat set to .custom()
                  func string(format: DateFormat) -> String

Parameters

format: a DateFormat struct. To use custom strings pass .custom() and pass the value of the formatter

Example

Date to AltRSS Format

SwiftDate also supports RSS and AltRSS Date Time format (both for parse and as formatter).

Declaration


                  func string(format: DateFormat) -> String // with DateFormat set to .rss(alt: Bool)

Parameters

format: a DateFormat struct. To get RSS/AltRSS pass .rss(alt: Bool) and pass true or false to set the alt format.

Example

Date to .NET Format

SwiftDate also supports .NET Date Time format (both for parse and as formatter).

Declaration


                  func string(format: DateFormat) -> String // with DateFormat set to .dotNET

Parameters

format: a DateFormat struct. To get .NET formatted string pass .dotNET and pass true or false to set the alt format.

Example

Date to Extended Format

SwiftDate support extended date time format.

Declaration


                  func string(format: DateFormat) -> String // with DateFormat set to .extended

Parameters

format: a DateFormat struct. To get extended datetime formatted string pass .extended and pass true or false to set the alt format.

Example

Time Interval to string

It's pretty easy to convert an absolute time interval or a difference between two dates and express it as string in various time components. When possible lower time components are grouped at upper level (so, for example if you want to get .minutes and .seconds of 120secs you will get 0 seconds and 2 minutes.

However with an interval of 125 seconds you will get 2 minutes and 5 seconds.

Declaration

Multiple time components


                  public func `in`(_ components: [Calendar.Component], of calendar: CalendarName? = nil) -> [Calendar.Component : Int]

Single time components


                  public func `in`(_ component: Calendar.Component, of calendar: CalendarName? = nil) -> Int?

Parameters

component or components: specify the component or an array of compone .extended and pass true or false to set the alt format.

Example

Date & Time with Style

You can user standard's Foundation date formatting which allows you to specify a style for date and time.

Declaration


                  func string(dateStyle: DateFormatter.Style = .medium, timeStyle: DateFormatter.Style = .medium) -> String

Parameters

dateStyle: the style used to print a date as DateFormatter.Style. If not specified .medium is used.
timeStyle: the style used to print a time as DateFormatter.Style. If not specified .medium is used.

Example

Human Readable/Colloquial String

You can user standard's Foundation date formatting which allows you to specify a style for date and time.

Colloquial string represent an human readable format used to express time intervals like difference between dates.

Declaration

Difference between a date and now


                  func colloquialSinceNow() throws -> (date: String, time: String?)

Difference between two dates


                  func colloquial(toDate date: DateInRegion) throws -> (date: String, time: String?)

Exception

Raise an exception .DifferentCalendar if both date are in different calendars.

Raise an exception .FailedToCalculate if time interval cannot be evaluated

Parameters

date: reference date for comparisor

Example

Time Components

Using SwiftDate you can get the difference between two dates and express it as a string of time components.

You can configure the style in which each components will be displayed (ex. "y" or "years"), the number of max components will be displayed and how the formatter should treat zero values.

Declaration

Time components between a date and now


                  func timeComponentsSinceNow(options:,shared:) throws -> String

Time components between two dates


                  func timeComponents(to:options:shared:) throws -> String

Exception

Raise an exception .FailedToCalculate if time interval cannot be evaluated

Parameters

to: reference date for comparisor
options: struct ComponentsFormatterOptions which defines a list of options used to print time components