Vault  4.1
Public Member Functions | Static Public Member Functions | Friends
VDuration Class Reference

A VDuration is a length of time. More...

#include <vinstant.h>

List of all members.

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.
VDurationoperator= (const VDuration &d)
 Assignment operator.
VDurationoperator+= (const VDuration &forwardOffset)
 Increment operator.
VDurationoperator-= (const VDuration &backwardOffset)
 Decrement operator.
VDurationoperator*= (Vs64 multiplier)
 In-place multiplication operator.
VDurationoperator/= (int divisor)
 In-place division operator.
VDurationoperator%= (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 VDurationZERO ()
 Duration constant of zero milliseconds.
static const VDurationMILLISECOND ()
 Duration constant of 1 millisecond.
static const VDurationSECOND ()
 Duration constant of 1 second (1000 milliseconds).
static const VDurationMINUTE ()
 Duration constant of 1 minute (60 seconds).
static const VDurationHOUR ()
 Duration constant of 1 hour (60 minutes).
static const VDurationDAY ()
 Duration constant of 1 day (24 hours).
static const VDurationUNSPECIFIED ()
 Special duration constant that is unequal to any other duration value.
static const VDurationNEGATIVE_INFINITY ()
 Special duration constant that is "less than" all specific durations.
static const VDurationPOSITIVE_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.

Detailed Description

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.


Constructor & Destructor Documentation

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]

Copy constructor.

Parameters:
da duration to copy.

Definition at line 85 of file vinstant.h.

VDuration::VDuration ( const VInstant sinceWhen)

Constructs a duration that is the difference from the specified instant to now.

Parameters:
sinceWhenthe 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.


Member Function Documentation

VDuration VDuration::createFromDurationString ( const VString s) [static]

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.

See also:
setDurationString
Parameters:
sthe string indicating the duration
Returns:
the VDuration

Definition at line 84 of file vinstant.cpp.

References setDurationString().

VDuration& VDuration::operator= ( const VDuration d) [inline]

Assignment operator.

Parameters:
da duration to assign from

Definition at line 102 of file vinstant.h.

References getDurationMilliseconds().

VDuration & VDuration::operator+= ( const VDuration forwardOffset)

Increment operator.

Parameters:
forwardOffseta duration to add

Definition at line 90 of file vinstant.cpp.

References getDurationMilliseconds(), isSpecific(), NEGATIVE_INFINITY(), POSITIVE_INFINITY(), and ZERO().

VDuration & VDuration::operator-= ( const VDuration backwardOffset)

Decrement operator.

Parameters:
backwardOffseta duration to subtract

Definition at line 114 of file vinstant.cpp.

References getDurationMilliseconds(), isSpecific(), NEGATIVE_INFINITY(), POSITIVE_INFINITY(), and ZERO().

VDuration & VDuration::operator*= ( Vs64  multiplier)

In-place multiplication operator.

Parameters:
multipliera 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.

Parameters:
divisora number to divide the duration by
Exceptions:
doesnothing if the divisor is zero

Definition at line 159 of file vinstant.cpp.

References isSpecific(), NEGATIVE_INFINITY(), and POSITIVE_INFINITY().

VDuration & VDuration::operator%= ( const VDuration divisor)

In-place modulo operator.

Parameters:
divisora duration to modulo the duration by
Exceptions:
doesnothing 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.

Returns:
the negative of this duration

Definition at line 192 of file vinstant.cpp.

References isSpecific(), NEGATIVE_INFINITY(), POSITIVE_INFINITY(), and VDuration().

Vs64 VDuration::getDurationMilliseconds ( ) const [inline]

Returns the duration in milliseconds.

Returns:
obvious

Definition at line 117 of file vinstant.h.

int VDuration::getDurationSeconds ( ) const [inline]

Returns the duration in whole seconds, using simple truncating division of milliseconds.

Returns:
obvious

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.

Returns:
obvious

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.

Returns:
obvious

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.

Returns:
obvious

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.

Returns:
obvious

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.

Returns:
obvious

Definition at line 242 of file vinstant.cpp.

References getDurationMilliseconds(), and getDurationSeconds().

void VDuration::setDurationMilliseconds ( Vs64  durationMilliseconds) [inline]

Sets the duration in milliseconds.

Parameters:
durationMillisecondsthe duration to set, in milliseconds

Definition at line 132 of file vinstant.h.

void VDuration::setDurationSeconds ( int  durationSeconds) [inline]

Sets the duration in seconds.

Parameters:
durationSecondsthe duration to set, in seconds

Definition at line 134 of file vinstant.h.

void VDuration::setDurationMinutes ( int  durationMinutes) [inline]

Sets the duration in minutes.

Parameters:
durationMinutesthe duration to set, in minutes

Definition at line 136 of file vinstant.h.

void VDuration::setDurationHours ( int  durationHours) [inline]

Sets the duration in hours.

Parameters:
durationHoursthe 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).

Parameters:
durationDaysthe 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()

Parameters:
sthe string indicating the duration
Exceptions:
VRangeExceptionif 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().


Friends And Related Function Documentation

VDuration operator/ ( const VDuration d,
int  divisor 
) [friend]

Divides d1 by a number and returns the resulting duration.

Exceptions:
VExceptionif the divisor is zero

Definition at line 206 of file vinstant.cpp.


The documentation for this class was generated from the following files:

Copyright ©1997-2014 Trygve Isaacson. All rights reserved. This documentation was generated with Doxygen.