core.time.duration.split - multiple declarations

split takes the list of time units to split out as template arguments. The time unit strings must be given in decreasing order. How it returns the values for those units depends on the overload used.

The overload which accepts function arguments takes integral types in the order that the time unit strings were given, and those integers are passed by ref. split assigns the values for the units to each corresponding integer. Any integral type may be used, but no attempt is made to prevent integer overflow, so don't use small integral types in circumstances where the values for those units aren't likely to fit in an integral type that small.

The overload with no arguments returns the values for the units in a struct with members whose names are the same as the given time unit strings. The members are all longs. This overload will also work with no time strings being given, in which case all of the time units from weeks through hnsecs will be provided (but no nsecs, since it would always be 0).

For both overloads, the entire value of the Duration is split among the units (rather than splitting the Duration across all units and then only providing the values for the requested units), so if only one unit is given, the result is equivalent to total.

"nsecs" is accepted by split, but "years" and "months" are not.

For negative durations, all of the split values will be negative.

Prototype

auto const split(units...)() nothrow @nogc
if (allAreAcceptedUnits!("weeks", "days", "hours", "minutes", "seconds", "msecs", "usecs", "hnsecs", "nsecs")(units) && unitsAreInDescendingOrder(units));

Example

{
    auto d = dur!"days"(12) + dur!"minutes"(7) + dur!"usecs"(501223);
    long days;
    int seconds;
    short msecs;
    d.split!("days", "seconds", "msecs")(days, seconds, msecs);
    assert(days == 12);
    assert(seconds == 7 * 60);
    assert(msecs == 501);

    auto splitStruct = d.split!("days", "seconds", "msecs")();
    assert(splitStruct.days == 12);
    assert(splitStruct.seconds == 7 * 60);
    assert(splitStruct.msecs == 501);

    auto fullSplitStruct = d.split();
    assert(fullSplitStruct.weeks == 1);
    assert(fullSplitStruct.days == 5);
    assert(fullSplitStruct.hours == 0);
    assert(fullSplitStruct.minutes == 7);
    assert(fullSplitStruct.seconds == 0);
    assert(fullSplitStruct.msecs == 501);
    assert(fullSplitStruct.usecs == 223);
    assert(fullSplitStruct.hnsecs == 0);

    assert(d.split!"minutes"().minutes == d.total!"minutes");
}

{
    auto d = dur!"days"(12);
    assert(d.split!"weeks"().weeks == 1);
    assert(d.split!"days"().days == 12);

    assert(d.split().weeks == 1);
    assert(d.split().days == 5);
}

{
    auto d = dur!"days"(7) + dur!"hnsecs"(42);
    assert(d.split!("seconds", "nsecs")().nsecs == 4200);
}

{
    auto d = dur!"days"(-7) + dur!"hours"(-9);
    auto result = d.split!("days", "hours")();
    assert(result.days == -7);
    assert(result.hours == -9);
}

split takes the list of time units to split out as template arguments. The time unit strings must be given in decreasing order. How it returns the values for those units depends on the overload used.

The overload which accepts function arguments takes integral types in the order that the time unit strings were given, and those integers are passed by ref. split assigns the values for the units to each corresponding integer. Any integral type may be used, but no attempt is made to prevent integer overflow, so don't use small integral types in circumstances where the values for those units aren't likely to fit in an integral type that small.

The overload with no arguments returns the values for the units in a struct with members whose names are the same as the given time unit strings. The members are all longs. This overload will also work with no time strings being given, in which case all of the time units from weeks through hnsecs will be provided (but no nsecs, since it would always be 0).

For both overloads, the entire value of the Duration is split among the units (rather than splitting the Duration across all units and then only providing the values for the requested units), so if only one unit is given, the result is equivalent to total.

"nsecs" is accepted by split, but "years" and "months" are not.

For negative durations, all of the split values will be negative.

Arguments

template split(units...);

Functions

Example

{
    auto d = dur!"days"(12) + dur!"minutes"(7) + dur!"usecs"(501223);
    long days;
    int seconds;
    short msecs;
    d.split!("days", "seconds", "msecs")(days, seconds, msecs);
    assert(days == 12);
    assert(seconds == 7 * 60);
    assert(msecs == 501);

    auto splitStruct = d.split!("days", "seconds", "msecs")();
    assert(splitStruct.days == 12);
    assert(splitStruct.seconds == 7 * 60);
    assert(splitStruct.msecs == 501);

    auto fullSplitStruct = d.split();
    assert(fullSplitStruct.weeks == 1);
    assert(fullSplitStruct.days == 5);
    assert(fullSplitStruct.hours == 0);
    assert(fullSplitStruct.minutes == 7);
    assert(fullSplitStruct.seconds == 0);
    assert(fullSplitStruct.msecs == 501);
    assert(fullSplitStruct.usecs == 223);
    assert(fullSplitStruct.hnsecs == 0);

    assert(d.split!"minutes"().minutes == d.total!"minutes");
}

{
    auto d = dur!"days"(12);
    assert(d.split!"weeks"().weeks == 1);
    assert(d.split!"days"().days == 12);

    assert(d.split().weeks == 1);
    assert(d.split().days == 5);
}

{
    auto d = dur!"days"(7) + dur!"hnsecs"(42);
    assert(d.split!("seconds", "nsecs")().nsecs == 4200);
}

{
    auto d = dur!"days"(-7) + dur!"hours"(-9);
    auto result = d.split!("days", "hours")();
    assert(result.days == -7);
    assert(result.hours == -9);
}