Contents

units(allowed:width:maximumUnitCount:zeroValueUnits:valueLength:fractionalPart:)

Returns a style for formatting a duration that uses the specified units.

Declaration

static func units(allowed units: Set<Duration.UnitsFormatStyle.Unit> = [.hours, .minutes, .seconds], width: Duration.UnitsFormatStyle.UnitWidth = .abbreviated, maximumUnitCount: Int? = nil, zeroValueUnits: Duration.UnitsFormatStyle.ZeroValueUnitsDisplayStrategy = .hide, valueLength: Int? = nil, fractionalPart: Duration.UnitsFormatStyle.FractionalPartDisplayStrategy = .hide) -> Self

Parameters

  • units:

    The units that the formatted string may include.

  • width:

    The width of the unit and the spacing between the value and the unit.

  • maximumUnitCount:

    The maximum number of duration units, if any, to include in the output string.

  • zeroValueUnits:

    The strategy for handling leading units with zero values.

  • valueLength:

    The padding or truncating behavior of the unit value, as an Int. Defaults to nil, which applies no length limit.

  • fractionalPart:

    The strategy for displaying a duration if a formatted string can’t represent it exactly with the allowed units.

Return Value

A duration units format style that uses the specified units.

Discussion

Use the dot-notation form of this type method when the call point allows the use of Duration.UnitsFormatStyle. You typically do this when calling the formatted(_:) method of Duration.

The following example creates a duration to represent 1 hour, 10 minutes, 32 seconds, and 400 milliseconds. It then creates a Duration.UnitsFormatStyle to show the hours, minutes, seconds, and milliseconds parts, with a wide width that presents the full name of each unit.

let duration = Duration.seconds(70 * 60 + 32) + Duration.milliseconds(400)
let formatted = duration.formatted(
     .units(allowed: [.hours, .minutes, .seconds, .milliseconds],
            width: .wide))
// "1 hour, 10 minutes, 32 seconds, 400 milliseconds"

See Also

Applying duration styles