tango.time.Time

License:

BSD style: see license.txt

Version:

mid 2005: Initial release Apr 2007: heavily reshaped Dec 2007: moved to tango.time

Author:

John Chapman, Kris, scheivguy
struct TimeSpan
This struct represents a length of time. The underlying representation is in units of 100ns. This allows the length of time to span to roughly +/- 10000 years. Notably missing from this is a representation of weeks, months and years. This is because weeks, months, and years vary according to local calendars. Use tango.time.chrono.* to deal with these concepts.

Note:

nobody should change this struct without really good reason as it is required to be a part of some interfaces. It should be treated as a builtin type. Also note that there is deliberately no opCall constructor here, since it tends to produce too much overhead. If you wish to build a TimeSpan struct from a ticks value, use D's builtin ability to create a struct with given member values (See the description of ticks() for an example of how to do this).

Example:

1
2
3

Time start = Clock.now;
Thread.sleep(0.150);
Stdout.formatln("slept for {} ms", (Clock.now-start).millis);

See Also:

tango.core.Thread, tango.time.Clock
TimeSpan min [manifest]
Minimum TimeSpan
TimeSpan max [manifest]
Maximum TimeSpan
TimeSpan zero [manifest]
Zero TimeSpan. Useful for comparisons.
long ticks() [@property, const]
Get the number of ticks that this timespan represents. This can be used to construct another TimeSpan:
1
2

long ticks = myTimeSpan.ticks;
TimeSpan copyOfMyTimeSpan = TimeSpan(ticks);
bool opEquals(const(TimeSpan) t) [const]
Determines whether two TimeSpan values are equal
int opCmp(const ref TimeSpan t) [const]
Compares this object against another TimeSpan value.
TimeSpan opBinary(immutable(char)[] o : "+")(const(TimeSpan) t) [const]
Add the TimeSpan given to this TimeSpan returning a new TimeSpan.

Parameters:

tA TimeSpan value to add

Returns:

A TimeSpan value that is the sum of this instance and t.
TimeSpan opOpAssign(immutable(char)[] o : "+")(const(TimeSpan) t)
Add the specified TimeSpan to this TimeSpan, assigning the result to this instance.

Parameters:

tA TimeSpan value to add

Returns:

a copy of this instance after adding t.
TimeSpan opBinary(immutable(char)[] o : "-")(const(TimeSpan) t) [const]
Subtract the specified TimeSpan from this TimeSpan.

Parameters:

tA TimeSpan to subtract

Returns:

A new timespan which is the difference between this instance and t
TimeSpan opOpAssign(immutable(char)[] o : "-")(const(TimeSpan) t)
Subtract the specified TimeSpan from this TimeSpan and assign the

Parameters:

tA TimeSpan to subtract

Returns:

A copy of this instance after subtracting t.
TimeSpan opBinary(immutable(char)[] o : "*")(long v) [const]
Scale the TimeSpan by the specified amount. This should not be used to convert to a different unit. Use the unit accessors instead. This should only be used as a scaling mechanism. For example, if you have a timeout and you want to sleep for twice the timeout, you would use timeout * 2.

Parameters:

vA multiplier to use for scaling this time span.

Returns:

A new TimeSpan that is scaled by v
TimeSpan opOpAssign(immutable(char)[] o : "*")(long v)
Scales this TimeSpan and assigns the result to this instance.

Parameters:

vA multipler to use for scaling

Returns:

A copy of this instance after scaling
TimeSpan opBinary(immutable(char)[] o : "/")(long v) [const]
Divide the TimeSpan by the specified amount. This should not be used to convert to a different unit. Use the unit accessors instead. This should only be used as a scaling mechanism. For example, if you have a timeout and you want to sleep for half the timeout, you would use timeout / 2.

Parameters:

vA divisor to use for scaling this time span.

Returns:

A new TimeSpan that is divided by v
TimeSpan opOpAssign(immutable(char)[] o : "/")(long v)
Divides this TimeSpan and assigns the result to this instance.

Parameters:

vA multipler to use for dividing

Returns:

A copy of this instance after dividing
long opBinary(immutable(char)[] o : "/")(const(TimeSpan) t) [const]
Perform integer division with the given time span.

Parameters:

tA divisor used for dividing

Returns:

The result of integer division between this instance and t.
TimeSpan opUnary(immutable(char)[] o : "-")() [const]
Negate a time span

Returns:

The negative equivalent to this time span
long nanos() [@property, const]
Convert to nanoseconds

Note:

this may incur loss of data because nanoseconds cannot represent the range of data a TimeSpan can represent.

Returns:

The number of nanoseconds that this TimeSpan represents.
long micros() [@property, const]
Convert to microseconds

Returns:

The number of microseconds that this TimeSpan represents.
long millis() [@property, const]
Convert to milliseconds

Returns:

The number of milliseconds that this TimeSpan represents.
long seconds() [@property, const]
Convert to seconds

Returns:

The number of seconds that this TimeSpan represents.
long minutes() [@property, const]
Convert to minutes

Returns:

The number of minutes that this TimeSpan represents.
long hours() [@property, const]
Convert to hours

Returns:

The number of hours that this TimeSpan represents.
long days() [@property, const]
Convert to days

Returns:

The number of days that this TimeSpan represents.
double interval() [@property, const]
Convert to a floating point interval representing seconds.

Note:

This may cause a loss of precision as a double cannot exactly represent some fractional values.

Returns:

An interval representing the seconds and fractional seconds that this TimeSpan represents.
TimeOfDay time() [@property, const]
Convert to TimeOfDay

Returns:

the TimeOfDay this TimeSpan represents.
TimeSpan fromNanos(long value) [static]
Construct a TimeSpan from the given number of nanoseconds

Note:

This may cause a loss of data since a TimeSpan's resolution is in 100ns increments.

Parameters:

valueThe number of nanoseconds.

Returns:

A TimeSpan representing the given number of nanoseconds.
TimeSpan fromMicros(long value) [static]
Construct a TimeSpan from the given number of microseconds

Parameters:

valueThe number of microseconds.

Returns:

A TimeSpan representing the given number of microseconds.
TimeSpan fromMillis(long value) [static]
Construct a TimeSpan from the given number of milliseconds

Parameters:

valueThe number of milliseconds.

Returns:

A TimeSpan representing the given number of milliseconds.
TimeSpan fromSeconds(long value) [static]
Construct a TimeSpan from the given number of seconds

Parameters:

valueThe number of seconds.

Returns:

A TimeSpan representing the given number of seconds.
TimeSpan fromMinutes(long value) [static]
Construct a TimeSpan from the given number of minutes

Parameters:

valueThe number of minutes.

Returns:

A TimeSpan representing the given number of minutes.
TimeSpan fromHours(long value) [static]
Construct a TimeSpan from the given number of hours

Parameters:

valueThe number of hours.

Returns:

A TimeSpan representing the given number of hours.
TimeSpan fromDays(long value) [static]
Construct a TimeSpan from the given number of days

Parameters:

valueThe number of days.

Returns:

A TimeSpan representing the given number of days.
TimeSpan fromInterval(double sec) [static]
Construct a TimeSpan from the given interval. The interval represents seconds as a double. This allows both whole and fractional seconds to be passed in.

Parameters:

valueThe interval to convert in seconds.

Returns:

A TimeSpan representing the given interval.
struct Time
Represents a point in time.

Remarks:

Time represents dates and times between 12:00:00 midnight on January 1, 10000 BC and 11:59:59 PM on December 31, 9999 AD.

Time values are measured in 100-nanosecond intervals, or ticks. A date value is the number of ticks that have elapsed since 12:00:00 midnight on January 1, 0001 AD in the Gregorian calendar. Negative Time values are offsets from that same reference point, but backwards in history. Time values are not specific to any calendar, but for an example, the beginning of December 31, 1 BC in the Gregorian calendar is Time.epoch - TimeSpan.days(1).
Time min [manifest]
Time max [manifest]
Represents the smallest and largest Time value.
Time epoch [manifest]
Represents the epoch (1/1/0001)
Time epoch1601 [manifest]
Represents the epoch of 1/1/1601 (Commonly used in Windows systems)
Time epoch1970 [manifest]
Represents the epoch of 1/1/1970 (Commonly used in Unix systems)
long ticks() [@property, const]
Property. Retrieves the number of ticks for this Time. This value can be used to construct another Time struct by

writing:

1
2

long ticks = myTime.ticks;
Time copyOfMyTime = Time(ticks);

Returns:

A long represented by the time of this instance.
bool opEquals(const(Time) t) [const]
Determines whether two Time values are equal.

Parameters:

valueA Time _value.

Returns:

true if both instances are equal; otherwise, false
int opCmp(const ref Time t) [const]
Compares two Time values.
Time opBinary(immutable(char)[] o : "+")(const(TimeSpan) t) [const]
Adds the specified time span to the time, returning a new time.

Parameters:

tA TimeSpan value.

Returns:

A Time that is the sum of this instance and t.
Time opOpAssign(immutable(char)[] o : "+")(const(TimeSpan) t)
Adds the specified time span to the time, assigning the result to this instance.

Parameters:

tA TimeSpan value.

Returns:

The current Time instance, with t added to the time.
Time opBinary(immutable(char)[] o : "-")(const(TimeSpan) t) [const]
Subtracts the specified time span from the time, returning a new time.

Parameters:

tA TimeSpan value.

Returns:

A Time whose value is the value of this instance minus the value of t.
TimeSpan opBinary(immutable(char)[] o : "-")(const(Time) t) [const]
Returns a time span which represents the difference in time between this and the given Time.

Parameters:

tA Time value.

Returns:

A TimeSpan which represents the difference between this and t.
Time opOpAssign(immutable(char)[] o : "-")(const(TimeSpan) t)
Subtracts the specified time span from the time, assigning the result to this instance.

Parameters:

tA TimeSpan value.

Returns:

The current Time instance, with t subtracted from the time.
Time date() [@property, const]
Property. Retrieves the date component.

Returns:

A new Time instance with the same date as this instance, but with the time truncated.
TimeOfDay time() [@property, const]
Property. Retrieves the time of day.

Returns:

A TimeOfDay representing the fraction of the day elapsed since midnight.
TimeSpan span() [@property, const]
Property. Retrieves the equivalent TimeSpan.

Returns:

A TimeSpan representing this Time.
TimeSpan unix() [@property, const]
Property. Retrieves a TimeSpan that corresponds to Unix time (time since 1/1/1970). Use the TimeSpan accessors to get the time in seconds, milliseconds, etc.

Returns:

A TimeSpan representing this Time as Unix time. 

1
2

auto unixTime = Clock.now.unix.seconds;
auto javaTime = Clock.now.unix.millis;
struct TimeOfDay
Represents a time of day. This is different from TimeSpan in that each component is represented within the limits of everyday time, rather than from the start of the Epoch. Effectively, the TimeOfDay epoch is the first second of each day.
This is handy for dealing strictly with a 24-hour clock instead of potentially thousands of years. For example: 
1
2
3
4
5

auto time = Clock.now.time;
assert (time.millis < 1000);
assert (time.seconds < 60);
assert (time.minutes < 60);
assert (time.hours < 24);

You can create a TimeOfDay from an existing Time or TimeSpan instance via the respective time() method. To convert back to a TimeSpan, use the span() method
uint hours [public]
hours component of the time of day. This should be between 0 and 23, inclusive.
uint minutes [public]
minutes component of the time of day. This should be between 0 and 59, inclusive.
uint seconds [public]
seconds component of the time of day. This should be between 0 and 59, inclusive.
uint millis [public]
milliseconds component of the time of day. This should be between 0 and 999, inclusive.
TimeOfDay opCall(uint hours, uint minutes, uint seconds, uint millis = 0) [static]
constructor.

Parameters:

hoursnumber of hours since midnight
minutesnumber of minutes into the hour
secondsnumber of seconds into the minute
millisnumber of milliseconds into the second

Returns:

a TimeOfDay representing the given time fields.

Note:

There is no verification of the range of values, or normalization made. So if you pass in larger values than the maximum value for that field, they will be stored as that value.

example:

1
2
3
4
5

auto tod = TimeOfDay(100, 100, 100, 10000);
assert(tod.hours == 100);
assert(tod.minutes == 100);
assert(tod.seconds == 100);
assert(tod.millis == 10000);
TimeOfDay opCall(long ticks) [static]
constructor.

Parameters:

ticksticks representing a Time value. This is normalized so that it represent a time of day (modulo-24 etc)

Returns:

a TimeOfDay value that corresponds to the time of day of the given number of ticks.
TimeSpan span() [@property, const]
construct a TimeSpan from the current fields

Returns:

a TimeOfDay representing the field values.

Note:

that fields are not checked against a valid range, so setting 60 for minutes is allowed, and will just add 1 to the hour component, and set the minute component to 0. The result is normalized, so the hours wrap. If you pass in 25 hours, the resulting TimeOfDay will have a hour component of 1.
TimeSpan modulo24(long ticks) [package, static]
internal routine to adjust ticks by one day. Also adjusts for offsets in the BC era
struct Date
Generic Date representation
uint era [public]
uint day [public]
uint year [public]
uint month [public]
uint dow [public]
uint doy [public]
1 .. 366
struct DateTime
Combination of a Date and a TimeOfDay
Date date [public]
date representation
TimeOfDay time [public]
time representation