Manipulate Dates

Overview

SwiftDate allows you to manipulate date easily; you can add time components to date, get the difference between two dates (and express them in one or more time component) or compare two dates. All of these stuff are available both for Date and DateInRegion instances.

Math Operators

Add time components

You can sum or subtract time components to a date simply using classic math operations avaible in Swift.

A new DateInRegion or Date object is generated for your with the new date evaluated in the context of the region in which it was expressed.

Available time components are:

nanoseconds, seconds, minutes, hours, days, weeks, years

Below some examples of math operations in action:

Compare Dates

Description

Comparing Date instances is already part of the Swift 3 Foundation Library.

SwiftDate adds the same opportunity for DateInRegion and expand the library by adding several other functions which allows you to compare dates by specifing a granurality

Simple Date Compare

You can compare dates using >, >=, <, =< operators. So for example:

Start of time unit

Descritpion

With .startOf() you can get a new date from the receiver at the start of given time component unit.

Declaration

startOf(component: Calendar.Component) -> DateInRegion

                startOf(component: Calendar.Component) -> Date

Parameters

component: component to alter

Result

Return a new DateInRegion/Date where given component is set at it's start.

Example

End of time unit

Description

With .endOf() you can get a new date from the receiver at the end of given time component unit.

Declaration

endOf(component: Calendar.Component) -> DateInRegion

                endOf(component: Calendar.Component) -> Date

Parameters

component: component to alter

Result

Return a new DateInRegion/Date where given component is set at it's end.

Example

Date at Specific Time

Description

You can get a new date by setting only time units using .atTime(hour:minute:second) function. Note: time components are altered according to the calendar specified by the region of the DateInRegion or by .defaultRegion set in Date.

Exception

Function raise an .FailedToCalculate exception if date cannot be set at given time.

Declaration


                  func atTime(hour: Int, minute: Int, second: Int) throws -> DateInRegion

                  func atTime(hour: Int, minute: Int, second: Int) throws -> Date

Parameters

hour: hour(s) to set
minute: minute(s) to set
second: second(s) to set

Result

Return a new DateInRegion/Date where hour/minute/seconds are set to the specified time.
Keep in mind this function may alter other datetime components if needed.

Example

Date at Specific Time Unit

Description

Create a new instance calculated by setting a specific component of a given date to a given value, while trying to keep lower components the same.

Declaration


                func at(unit: Calendar.Component, value: Int) throws -> DateInRegion

                func at(unit: Calendar.Component, value: Int) throws -> Date

Parameters

unit: calendar component unit to alter

Exception

Function raise an .FailedToCalculate exception if date cannot be set at given time.

Result

Return a new DateInRegion/Date where given component is alter according to passed value. Where possible the function will try to keep lower components.

Example

Date at Specified Time Units

Description

Create a new instance calculated by setting a list of components of a given date to given values (components are evaluated serially - in order), while trying to keep lower components the same.

The order is .nanosecond, .second, .minute, .hour, .day, .month, .year, .yearForWeekOfYear, .weekOfYear, .weekday, .quarter, .weekdayOrdinal, .weekOfMonth.

Declaration


                func at(unitsWithValues dict: [Calendar.Component : Int]) throws -> DateInRegion

                func at(unitsWithValues dict: [Calendar.Component : Int]) throws -> Date

Parameters

unitsWithValues: calendar component units to alter

Exception

Function raise an .FailedToCalculate exception if date cannot be set at given components.

Result

Return a new DateInRegion/Date where given components are alter according to passed values. Where possible the function will try to keep lower components.

Example

Latest Date

Description

Returns a DateInRegion/Date object representing a date that is the earliest from a given range of dates.

The dates are compared in absolute time, i.e. time zones, locales and calendars have no effect on the comparison.

Declaration


                  (DateInRegion) static func latestDate(_ list: [DateInRegion]) -> DateInRegion

                  (Date) static func latestDate(_ list: [DateInRegion]) -> Date

Example

Earliest Date

Description

Returns a DateInRegion/Date object representing a date that is the latest from a given range of dates. The dates are compared in absolute time, i.e. time zones, locales and calendars have no effect on the comparison.

Declaration


                  (DateInRegion) static func earliestDate(_ list: [DateInRegion]) -> DateInRegion

                  (Date) static func earliestDate(_ list: [DateInRegion]) -> Date

Example

Compare (with Granurality)

Description

Returns a ComparisonResult value that indicates the ordering of two given dates based on their components down to a given unit granularity.

Declaration


                  func compare(to date: DateInRegion, granularity: Calendar.Component) -> ComparisonResult

                  func compare(to date: Date, granularity: Calendar.Component) -> ComparisonResult

Parameters

date: date to compare
granularity: The smallest unit that must, along with all larger units, be equal for the given dates to be considered the same.

Is Before Date (with granularity)

Description

Compares whether the receiver is before/before equal `date` based on their components down to a given unit granularity.

Declaration


                  func isBefore(date: DateInRegion, orEqual: Bool = false, granularity: Calendar.Component) -> Bool

                  func isBefore(date: Date, orEqual: Bool = false, granularity: Calendar.Component) -> Bool

Parameters

date: date to compare
orEqual: true to also check for equality
granularity: The smallest unit that must, along with all larger units, be less for the given dates.

Is After Date (with granularity)

Description

Compares whether the receiver is after date based on their components down to a given unit granularity.

Declaration


                  func isAfter(date: DateInRegion, orEqual: Bool = false, granularity: Calendar.Component) -> Bool
                  func compare(to date: Date, granularity: Calendar.Component) -> ComparisonResult

                  func isAfter(date: Date, orEqual: Bool = false, granularity: Calendar.Component) -> Bool

Parameters

date: date to compare
orEqual: true to also check for equality
granularity: The smallest unit that must, along with all larger units, be greater for the given dates

Is Equal

Description

Returns whether the given date is equal to the receiver.

Declaration


                  func isEqual(to compareDate: DateInRegion) -> Bool

Parameters

compareDate: a date to compare against

Enumerate Dates in Interval

Description

This method enumerates all dates between an interval, from starting date (included) to end date (maybe excluded depending of the increment factor).

Declaration


                  public static func dates(between startDate: Date, and endDate: Date, increment components: DateComponents) -> [Date]

Parameters

startDate: start interval
endDate: end interval
increment: increment expressed as DateComponents instance