std.datetime.sys_time.roll - multiple declarations

The difference between rolling and adding is that rolling does not affect larger units. Rolling a SysTime 12 months gets the exact same SysTime. However, the days can still be affected due to the differing number of days in each month.

Because there are no units larger than years, there is no difference between adding and rolling years.

Prototype

ref SysTime roll(string units)(
  long value,
  AllowDayOverflow allowOverflow = AllowDayOverflow.yes
) nothrow @safe
if (units == "years");

Parameters

Example

auto st1 = SysTime(DateTime(2010, 1, 1, 12, 33, 33));
st1.roll!"months"(1);
assert(st1 == SysTime(DateTime(2010, 2, 1, 12, 33, 33)));

auto st2 = SysTime(DateTime(2010, 1, 1, 12, 33, 33));
st2.roll!"months"(-1);
assert(st2 == SysTime(DateTime(2010, 12, 1, 12, 33, 33)));

auto st3 = SysTime(DateTime(1999, 1, 29, 12, 33, 33));
st3.roll!"months"(1);
assert(st3 == SysTime(DateTime(1999, 3, 1, 12, 33, 33)));

auto st4 = SysTime(DateTime(1999, 1, 29, 12, 33, 33));
st4.roll!"months"(1, AllowDayOverflow.no);
assert(st4 == SysTime(DateTime(1999, 2, 28, 12, 33, 33)));

auto st5 = SysTime(DateTime(2000, 2, 29, 12, 30, 33));
st5.roll!"years"(1);
assert(st5 == SysTime(DateTime(2001, 3, 1, 12, 30, 33)));

auto st6 = SysTime(DateTime(2000, 2, 29, 12, 30, 33));
st6.roll!"years"(1, AllowDayOverflow.no);
assert(st6 == SysTime(DateTime(2001, 2, 28, 12, 30, 33)));

The difference between rolling and adding is that rolling does not affect larger units. For instance, rolling a SysTime one year's worth of days gets the exact same SysTime.

Accepted units are "days", "minutes", "hours", "minutes", "seconds", "msecs", "usecs", and "hnsecs".

Note that when rolling msecs, usecs or hnsecs, they all add up to a second. So, for example, rolling 1000 msecs is exactly the same as rolling 100,000 usecs.

Prototype

ref SysTime roll(string units)(
  long value
) nothrow @safe
if (units == "days");

Parameters

Example

auto st1 = SysTime(DateTime(2010, 1, 1, 11, 23, 12));
st1.roll!"days"(1);
assert(st1 == SysTime(DateTime(2010, 1, 2, 11, 23, 12)));
st1.roll!"days"(365);
assert(st1 == SysTime(DateTime(2010, 1, 26, 11, 23, 12)));
st1.roll!"days"(-32);
assert(st1 == SysTime(DateTime(2010, 1, 25, 11, 23, 12)));

auto st2 = SysTime(DateTime(2010, 7, 4, 12, 0, 0));
st2.roll!"hours"(1);
assert(st2 == SysTime(DateTime(2010, 7, 4, 13, 0, 0)));

auto st3 = SysTime(DateTime(2010, 2, 12, 12, 0, 0));
st3.roll!"hours"(-1);
assert(st3 == SysTime(DateTime(2010, 2, 12, 11, 0, 0)));

auto st4 = SysTime(DateTime(2009, 12, 31, 0, 0, 0));
st4.roll!"minutes"(1);
assert(st4 == SysTime(DateTime(2009, 12, 31, 0, 1, 0)));

auto st5 = SysTime(DateTime(2010, 1, 1, 0, 0, 0));
st5.roll!"minutes"(-1);
assert(st5 == SysTime(DateTime(2010, 1, 1, 0, 59, 0)));

auto st6 = SysTime(DateTime(2009, 12, 31, 0, 0, 0));
st6.roll!"seconds"(1);
assert(st6 == SysTime(DateTime(2009, 12, 31, 0, 0, 1)));

auto st7 = SysTime(DateTime(2010, 1, 1, 0, 0, 0));
st7.roll!"seconds"(-1);
assert(st7 == SysTime(DateTime(2010, 1, 1, 0, 0, 59)));

auto dt = DateTime(2010, 1, 1, 0, 0, 0);
auto st8 = SysTime(dt);
st8.roll!"msecs"(1);
assert(st8 == SysTime(dt, msecs(1)));

auto st9 = SysTime(dt);
st9.roll!"msecs"(-1);
assert(st9 == SysTime(dt, msecs(999)));

auto st10 = SysTime(dt);
st10.roll!"hnsecs"(1);
assert(st10 == SysTime(dt, hnsecs(1)));

auto st11 = SysTime(dt);
st11.roll!"hnsecs"(-1);
assert(st11 == SysTime(dt, hnsecs(9_999_999)));