std.datetime.date.DateTime.roll
- multiple declarations
Function DateTime.roll
Adds the given number of years or months to this DateTime
,
mutating it. A negative number will subtract.
ref DateTime roll(string units)
(
long value,
AllowDayOverflow allowOverflow = AllowDayOverflow .yes
) pure nothrow @nogc @safe
if (units == "years" || units == "months");
The difference between rolling and adding is that rolling does not
affect larger units. Rolling a DateTime
12 months
gets the exact same DateTime
. 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.
Parameters
Name | Description |
---|---|
units | The type of units to add ("years" or "months"). |
value | The number of months or years to add to this
DateTime . |
allowOverflow | Whether the days should be allowed to overflow, causing the month to increment. |
Returns
A reference to the DateTime
(this
).
Example
auto dt1 = DateTime(2010, 1, 1, 12, 33, 33);
dt1 .roll!"months"(1);
writeln(dt1); // DateTime(2010, 2, 1, 12, 33, 33)
auto dt2 = DateTime(2010, 1, 1, 12, 33, 33);
dt2 .roll!"months"(-1);
writeln(dt2); // DateTime(2010, 12, 1, 12, 33, 33)
auto dt3 = DateTime(1999, 1, 29, 12, 33, 33);
dt3 .roll!"months"(1);
writeln(dt3); // DateTime(1999, 3, 1, 12, 33, 33)
auto dt4 = DateTime(1999, 1, 29, 12, 33, 33);
dt4 .roll!"months"(1, AllowDayOverflow .no);
writeln(dt4); // DateTime(1999, 2, 28, 12, 33, 33)
auto dt5 = DateTime(2000, 2, 29, 12, 30, 33);
dt5 .roll!"years"(1);
writeln(dt5); // DateTime(2001, 3, 1, 12, 30, 33)
auto dt6 = DateTime(2000, 2, 29, 12, 30, 33);
dt6 .roll!"years"(1, AllowDayOverflow .no);
writeln(dt6); // DateTime(2001, 2, 28, 12, 30, 33)
Function DateTime.roll
Adds the given number of units to this DateTime
, mutating it. A
negative number will subtract.
The difference between rolling and adding is that rolling does not
affect larger units. For instance, rolling a DateTime
one
year's worth of days gets the exact same DateTime
.
Accepted units are "days"
, "minutes"
, "hours"
,
"minutes"
, and "seconds"
.
Parameters
Name | Description |
---|---|
units | The units to add. |
value | The number of units to add to this
DateTime . |
Returns
A reference to the DateTime
(this
).
Example
auto dt1 = DateTime(2010, 1, 1, 11, 23, 12);
dt1 .roll!"days"(1);
writeln(dt1); // DateTime(2010, 1, 2, 11, 23, 12)
dt1 .roll!"days"(365);
writeln(dt1); // DateTime(2010, 1, 26, 11, 23, 12)
dt1 .roll!"days"(-32);
writeln(dt1); // DateTime(2010, 1, 25, 11, 23, 12)
auto dt2 = DateTime(2010, 7, 4, 12, 0, 0);
dt2 .roll!"hours"(1);
writeln(dt2); // DateTime(2010, 7, 4, 13, 0, 0)
auto dt3 = DateTime(2010, 1, 1, 0, 0, 0);
dt3 .roll!"seconds"(-1);
writeln(dt3); // DateTime(2010, 1, 1, 0, 0, 59)