Skip to content

Latest commit

 

History

History
98 lines (66 loc) · 4.34 KB

6.TimeInterval_Formatting.md

File metadata and controls

98 lines (66 loc) · 4.34 KB
Raw

Time Interval Formatting

The following methods are part of the TimeInterval extension provided by SwiftDate.

6.0 - Format Interval as String

Formatting a time interval as a string is pretty simple, you just need to call the .toString() function of the TimeInterval. It allows you to pick the right formatting options to represent the interval as a valid string.

func toString(options callback: ((inout ComponentsFormatterOptions) -> Void)? = nil) -> String

Using a callback function you can configure the formatter as you need.

  • options: ComponentsFormatterOptions: allows to define the formatting options of the string.

ComponentsFormatterOptions is a struct with the following properties:

  • allowsFractionalUnits | Bool: Fractional units may be used when a value cannot be exactly represented using the available units. For example, if minutes are not allowed, the value “1h 30m” could be formatted as “1.5h”. The default value of this property is false.
  • allowedUnits | NSCalendar.Unit: Specify the units that can be used in the output. By default [.year, .month, .weekOfMonth, .day, .hour, .minute, .second] are used.
  • collapsesLargestUnit | Bool: A Boolean value indicating whether to collapse the largest unit into smaller units when a certain threshold is met. By default is false.
  • maximumUnitCount | Int: The maximum number of time units to include in the output string. The default value of this property is 0, which does not cause the elimination of any units.
  • zeroFormattingBehavior | DateComponentsFormatter.ZeroFormattingBehavior: The formatting style for units whose value is 0. By default is .default
  • unitsStyle | DateComponentsFormatter.UnitsStyle: The preferred style for units. By default is .abbreviated.

Examples:

// "2 hours, 5 minutes, 32 seconds"
let _ = (2.hours + 5.minutes + 32.seconds).timeInterval.toString {
  $0.unitsStyle = .full
  $0.collapsesLargestUnit = false
  $0.allowsFractionalUnits = true
}
// "2d 5h"
let _ = (5.hours + 2.days).timeInterval.toString {
  $0.unitsStyle = .abbreviated
}

^ Top

6.1 - Format Interval as Clock

SwiftDate allows to format a TimeInterval in the form of a clock or a countdown timer. (ie. 57:00:00). To format an interval using this style use .toClock() function.

func toClock(zero: DateComponentsFormatter.ZeroFormattingBehavior)

takes one argument:

  • zero | DateComponentsFormatter.ZeroFormattingBehavior: define the representation of the zero values into the destination string. By default is set to .pad.

Example:

let _ = (2.hours + 5.minutes).timeInterval.toClock() // "2:05:00"
let _ = (4.minutes + 50.minutes).timeInterval.toClock(zero: .dropAll) // "54:00"

^ Top

6.2 - Convert TimeInterval to Time Units

While SwiftDate allows to carefully evaluate the differences between two dates and express them with the requested time unit (see "Get Intervals Between Two Dates", sometimes you may need to calculate this value from an absolute - calendar/locale indipendent - value expressed as TimeInterval.

The methods used to convert a an absolute amount of seconds is toUnits() (for multiple extraction) and toUnit() for single component extraction.

func toUnits(_ units: Set<Calendar.Component>, to refDate: DateInRegion? = nil) -> [Calendar.Component: Int] func toUnit(_ unit: Calendar.Component, to refDate: DateInRegion? = nil) -> Int?

takes two arguments:

  • units | Set<Calendar.Component>: units to extract
  • refDate | DateInRegion: ending reference date, nil means now() in the context of the default region set. If refDate is nil evaluation is made from now() and now() - interval in the context of the SwiftDate.defaultRegion set.
  • calendar | CalendarConvertible: reference calendar; uses

Example:

// "[.day: 10, .hour: 12]"
let _ = (36.hours + 2.days + 1.weeks).timeInterval.toUnits([.day, .hour])

^ Top