Vault
4.1
|
A VDuration is a length of time. More...
#include <vinstant.h>
Public Member Functions | |
VDuration () | |
Constructs a duration equal to ZERO, or zero milliseconds. | |
VDuration (const VDuration &d) | |
Copy constructor. | |
VDuration (const VInstant &sinceWhen) | |
Constructs a duration that is the difference from the specified instant to now. | |
~VDuration () | |
Non-virtual destructor. | |
VDuration & | operator= (const VDuration &d) |
Assignment operator. | |
VDuration & | operator+= (const VDuration &forwardOffset) |
Increment operator. | |
VDuration & | operator-= (const VDuration &backwardOffset) |
Decrement operator. | |
VDuration & | operator*= (Vs64 multiplier) |
In-place multiplication operator. | |
VDuration & | operator/= (int divisor) |
In-place division operator. | |
VDuration & | operator%= (const VDuration &divisor) |
In-place modulo operator. | |
VDuration | operator- () const |
Unary negation operator. | |
Vs64 | getDurationMilliseconds () const |
Returns the duration in milliseconds. | |
int | getDurationSeconds () const |
Returns the duration in whole seconds, using simple truncating division of milliseconds. | |
int | getDurationMinutes () const |
Returns the duration in whole minutes, using simple truncating division of milliseconds. | |
int | getDurationHours () const |
Returns the duration in whole hours, using simple truncating division of milliseconds. | |
int | getDurationDays () const |
Returns the duration in whole days, using simple truncating division of milliseconds. | |
VString | getDurationString () const |
Returns a string formatted as in the simplest integer+suffix possible as described in setDurationString() docs below. | |
VString | getDurationStringFractionalSeconds () const |
Returns a string formatted as s.uuu, the number of seconds and milliseconds. | |
void | setDurationMilliseconds (Vs64 durationMilliseconds) |
Sets the duration in milliseconds. | |
void | setDurationSeconds (int durationSeconds) |
Sets the duration in seconds. | |
void | setDurationMinutes (int durationMinutes) |
Sets the duration in minutes. | |
void | setDurationHours (int durationHours) |
Sets the duration in hours. | |
void | setDurationDays (int durationDays) |
Sets the duration in 24-hour days (no DST calculations are done). | |
void | setDurationString (const VString &s) |
Sets the duration via a simple human-readable format that indicates value and magnitude. | |
bool | isComparable () const |
Returns true if the duration can be legitimately compared using comparison operators such as <, <=, >, >=. | |
bool | isSpecific () const |
Returns true if the duration has a specific value (not infinite) and therefore its internal duration value can be tested and used in simple math calculations. | |
Static Public Member Functions | |
static const VDuration & | ZERO () |
Duration constant of zero milliseconds. | |
static const VDuration & | MILLISECOND () |
Duration constant of 1 millisecond. | |
static const VDuration & | SECOND () |
Duration constant of 1 second (1000 milliseconds). | |
static const VDuration & | MINUTE () |
Duration constant of 1 minute (60 seconds). | |
static const VDuration & | HOUR () |
Duration constant of 1 hour (60 minutes). | |
static const VDuration & | DAY () |
Duration constant of 1 day (24 hours). | |
static const VDuration & | UNSPECIFIED () |
Special duration constant that is unequal to any other duration value. | |
static const VDuration & | NEGATIVE_INFINITY () |
Special duration constant that is "less than" all specific durations. | |
static const VDuration & | POSITIVE_INFINITY () |
Special duration constant that is "greater than" all specific durations. | |
static VDuration | createFromDurationString (const VString &s) |
Rather than have a constructor that takes a string, and risk unintended overloading, we define a static helper if you want to construct a VDuration from a duration string. | |
static VDuration | min (const VDuration &d1, const VDuration &d2) |
Returns a duration that is the lesser of d1 and d2. | |
static VDuration | max (const VDuration &d1, const VDuration &d2) |
Returns a duration that is the greater of d1 and d2. | |
static VDuration | abs (const VDuration &d) |
Returns a duration that is equal to d if d is > ZERO, and -d if d is < ZERO. | |
static bool | areValuesSpecific (const VDuration &d1, const VDuration &d2) |
Returns true if d1 and d2 can be compared using simple value comparison. | |
Friends | |
bool | operator== (const VDuration &lhs, const VDuration &rhs) |
Compares durations for equality in milliseconds using ==. | |
bool | operator!= (const VDuration &lhs, const VDuration &rhs) |
Compares durations for equality in milliseconds using !=. | |
bool | operator< (const VDuration &lhs, const VDuration &rhs) |
Compares durations for equality in milliseconds using <. | |
bool | operator<= (const VDuration &lhs, const VDuration &rhs) |
Compares durations for equality in milliseconds using <=. | |
bool | operator>= (const VDuration &lhs, const VDuration &rhs) |
Compares durations for equality in milliseconds using >=. | |
bool | operator> (const VDuration &lhs, const VDuration &rhs) |
Compares durations for equality in milliseconds using >. | |
VDuration | operator+ (const VDuration &d1, const VDuration &d2) |
Adds d1 + d2 and returns their total duration. | |
VDuration | operator- (const VDuration &d1, const VDuration &d2) |
Subtracts d2 from d1 and returns the difference in duration. | |
VDuration | operator* (Vs64 multiplier, const VDuration &d1) |
Multiplies d1 by a number and returns the resulting duration; uses Vs64 for VInstant delta compatibility. | |
VDuration | operator* (const VDuration &d1, Vs64 multiplier) |
Multiplies d1 by a number and returns the resulting duration; uses Vs64 for VInstant delta compatibility. | |
VDuration | operator/ (const VDuration &d, int divisor) |
Divides d1 by a number and returns the resulting duration. | |
VDuration | operator% (const VDuration &d, const VDuration &divisor) |
Returns d modulo the divisor. Does nothing if the divisor is zero or not specific. |
A VDuration is a length of time.
It is most useful in conjunction with VInstant as the proper type to use when adding or subtracting an amount of time to a VInstant, or when subtracting two VInstants to find out the length of time between them.
Several constant values are defined, and by applying the multiplication operator, you can create your own values describing particular lengths of time. For example, to declare a constant for the duration of 1.5 hours, you could do any of the following: VDuration d1 = 90 * VDuration::MINUTE(); VDuration d2 = VDuration::HOUR() + (30 * VDuration::MINUTE()); assert(d1 == d2);
To get a VInstant describing a point in time 15 minutes in the future, you could do the following: VInstant x; // constructs to the current time x += (15 * VDuration::MINUTE());
The only unusual behavior within VDuration is the existence of the UNSPECIFIED duration constant. This is provided for cases where, due to backward compatibility, you need to initialize a duration to a special value that a normal value will never equal. It's a much better practice to let durations initialize to ZERO by default. Some behavior is not meaningful if you perform operations on an UNSPECIFIED duration. You should only test them for equality.
Negative durations are perfectly OK. They behave just as you'd expect; for example, if you subtract a later VInstant from an earlier VInstant, the resulting VDuration will be negative.
The NEGATIVE_INFINITY and POSITIVE_INFINITY constants are provided primarily so that the VInstant math operations can provide reasonable results when the instant values are INFINITE_PAST or INFINITE_FUTURE. In addition, VDuration's own math operations provide logical results when using these infinity values.
Strict Weak Ordering: Sorting functions require a strict weak ordering to be defined. This is implemented by the comparision operators. It is defined as follows: NEGATIVE_INFINITY < negative durations < ZERO < positive durations < POSITIVE_INFINITY < UNSPECIFIED
Definition at line 68 of file vinstant.h.
VDuration::VDuration | ( | ) | [inline] |
Constructs a duration equal to ZERO, or zero milliseconds.
Definition at line 83 of file vinstant.h.
VDuration::VDuration | ( | const VDuration & | d | ) | [inline] |
VDuration::VDuration | ( | const VInstant & | sinceWhen | ) |
Constructs a duration that is the difference from the specified instant to now.
sinceWhen | the start time to measure from |
Definition at line 79 of file vinstant.cpp.
VDuration::~VDuration | ( | ) | [inline] |
Non-virtual destructor.
This class is not intended to be subclassed.
Definition at line 89 of file vinstant.h.
Rather than have a constructor that takes a string, and risk unintended overloading, we define a static helper if you want to construct a VDuration from a duration string.
It uses setDurationString internally to do the work.
s | the string indicating the duration |
Definition at line 84 of file vinstant.cpp.
References setDurationString().
Assignment operator.
d | a duration to assign from |
Definition at line 102 of file vinstant.h.
References getDurationMilliseconds().
Increment operator.
forwardOffset | a duration to add |
Definition at line 90 of file vinstant.cpp.
References getDurationMilliseconds(), isSpecific(), NEGATIVE_INFINITY(), POSITIVE_INFINITY(), and ZERO().
Decrement operator.
backwardOffset | a duration to subtract |
Definition at line 114 of file vinstant.cpp.
References getDurationMilliseconds(), isSpecific(), NEGATIVE_INFINITY(), POSITIVE_INFINITY(), and ZERO().
In-place multiplication operator.
multiplier | a number to multiply the duration by |
Definition at line 138 of file vinstant.cpp.
References isSpecific(), NEGATIVE_INFINITY(), POSITIVE_INFINITY(), and ZERO().
VDuration & VDuration::operator/= | ( | int | divisor | ) |
In-place division operator.
divisor | a number to divide the duration by |
does | nothing if the divisor is zero |
Definition at line 159 of file vinstant.cpp.
References isSpecific(), NEGATIVE_INFINITY(), and POSITIVE_INFINITY().
In-place modulo operator.
divisor | a duration to modulo the duration by |
does | nothing if the divisor is zero or not specific |
Definition at line 179 of file vinstant.cpp.
References isSpecific(), and ZERO().
VDuration VDuration::operator- | ( | ) | const |
Unary negation operator.
Definition at line 192 of file vinstant.cpp.
References isSpecific(), NEGATIVE_INFINITY(), POSITIVE_INFINITY(), and VDuration().
Vs64 VDuration::getDurationMilliseconds | ( | ) | const [inline] |
int VDuration::getDurationSeconds | ( | ) | const [inline] |
Returns the duration in whole seconds, using simple truncating division of milliseconds.
Definition at line 119 of file vinstant.h.
int VDuration::getDurationMinutes | ( | ) | const [inline] |
Returns the duration in whole minutes, using simple truncating division of milliseconds.
Definition at line 121 of file vinstant.h.
int VDuration::getDurationHours | ( | ) | const [inline] |
Returns the duration in whole hours, using simple truncating division of milliseconds.
Definition at line 123 of file vinstant.h.
int VDuration::getDurationDays | ( | ) | const [inline] |
Returns the duration in whole days, using simple truncating division of milliseconds.
Definition at line 125 of file vinstant.h.
VString VDuration::getDurationString | ( | ) | const |
Returns a string formatted as in the simplest integer+suffix possible as described in setDurationString() docs below.
Definition at line 220 of file vinstant.cpp.
References getDurationDays(), getDurationHours(), getDurationMinutes(), getDurationSeconds(), NEGATIVE_INFINITY(), POSITIVE_INFINITY(), and UNSPECIFIED().
VString VDuration::getDurationStringFractionalSeconds | ( | ) | const |
Returns a string formatted as s.uuu, the number of seconds and milliseconds.
Definition at line 242 of file vinstant.cpp.
References getDurationMilliseconds(), and getDurationSeconds().
void VDuration::setDurationMilliseconds | ( | Vs64 | durationMilliseconds | ) | [inline] |
Sets the duration in milliseconds.
durationMilliseconds | the duration to set, in milliseconds |
Definition at line 132 of file vinstant.h.
void VDuration::setDurationSeconds | ( | int | durationSeconds | ) | [inline] |
Sets the duration in seconds.
durationSeconds | the duration to set, in seconds |
Definition at line 134 of file vinstant.h.
void VDuration::setDurationMinutes | ( | int | durationMinutes | ) | [inline] |
Sets the duration in minutes.
durationMinutes | the duration to set, in minutes |
Definition at line 136 of file vinstant.h.
void VDuration::setDurationHours | ( | int | durationHours | ) | [inline] |
Sets the duration in hours.
durationHours | the duration to set, in hours |
Definition at line 138 of file vinstant.h.
void VDuration::setDurationDays | ( | int | durationDays | ) | [inline] |
Sets the duration in 24-hour days (no DST calculations are done).
durationDays | the duration to set, in 24-hour days |
Definition at line 140 of file vinstant.h.
void VDuration::setDurationString | ( | const VString & | s | ) |
Sets the duration via a simple human-readable format that indicates value and magnitude.
Please note that because this requires string parsing, it is less efficient than using VDuration constants and multiplication. If present, the suffix of s must be one of: ms | s | m | h | d The prefix is an integer (leading minus sign allowed). If the suffix is omitted the string must be in the form s.mmm just like what getDurationString() returns. This is to allow get/set symmetry. Whitespace between the prefix and suffix is allowed but not preferred. Here are examples with each allowed suffix and the (obvious) meaning: 27ms 23472ms (meaning 23.472 seconds) 5s 107s (meaning 1 minute 47 seconds) 8m 152m (meaning 2 hours 32 minutes) 3h 7d 5.273 (meaning 5.273 seconds) The prefix value is simply multiplied out to get the raw number of milliseconds to store in the object. No calendar-like operations are done, which is why "weeks", "months", etc. are not supported.
For symmetry of getDurationString/setDurationString, the following strings are used for the special durations. (They are case-insensitive on input, and written as upper case on output.) "INFINITY" <-> VDuration::POSITIVE_INFINITY() "-INFINITY" <-> VDuration::NEGATIVE_INFINITY() "UNSPECIFIED" <-> VDuration::UNSPECIFIED()
s | the string indicating the duration |
VRangeException | if the string is malformed |
Definition at line 249 of file vinstant.cpp.
References VString::endsWith(), VString::equalsIgnoreCase(), VString::length(), NEGATIVE_INFINITY(), VString::parseDouble(), VString::parseS64(), POSITIVE_INFINITY(), VString::truncateLength(), and UNSPECIFIED().
bool VDuration::isComparable | ( | ) | const [inline] |
Returns true if the duration can be legitimately compared using comparison operators such as <, <=, >, >=.
This is the case for specific durations as well as the infinite durations. It is not the case for unspecified durations.
Definition at line 198 of file vinstant.h.
References UNSPECIFIED().
static bool VDuration::areValuesSpecific | ( | const VDuration & | d1, |
const VDuration & | d2 | ||
) | [inline, static] |
Returns true if d1 and d2 can be compared using simple value comparison.
In other words, both d1 and d2 have specific values. It's false if either one is not specific.
Definition at line 209 of file vinstant.h.
References isSpecific().
Divides d1 by a number and returns the resulting duration.
VException | if the divisor is zero |
Definition at line 206 of file vinstant.cpp.