VInstant Class Reference

A VInstant is an object that represents an instant in time regardless of the location (and time zone) of where code is running. More...

#include <vinstant.h>

List of all members.

Public Member Functions
	VInstant ()
	Creates an instant to represent the current time.
	VInstant (const VInstant &i)
	Creates an instant by copying an existing instant.
	~VInstant ()
	Destructor.
VInstant &	operator= (const VInstant &i)
	Copy constructor.
VInstant &	operator+= (const VDuration &forwardOffsetDuration)
	Increments (or decrements) the instant in time from its current value by the specified VDuration if the kind is kActualValue.
VInstant &	operator-= (const VDuration &backwardOffsetDuration)
	Decrements (or increments) the instant in time from its current value by the specified VDuration if the kind is kActualValue.
void	setNow ()
	Sets the instant to the current time.
void	setTrueNow ()
	Sets the instant to the actual current time not offset by simulation or frozen time.
VInstantStruct	getUTCInstantFields () const
	Returns an object holding the broken-down fields that this instant represents in UTC.
VInstantStruct	getLocalInstantFields () const
	Returns an object holding the broken-down fields that this instant represents in the current time zone.
VString	getUTCString () const
	Returns a string for this instant in UTC time in the format "y-MM-dd HH:mm:ss.SSS UTC", or one of the special time value strings "PAST", "FUTURE", or "NEVER".
VString	getUTCString (const VInstantFormatter &formatter) const
	Returns a string for this instant in UTC time in the specified format, or one of the special time value strings "PAST", "FUTURE", or "NEVER".
VString	getLocalString () const
	Returns a string for this instant in local time in the format "y-MM-dd HH:mm:ss.SSS", or one of the special time value strings "PAST", "FUTURE", or "NEVER".
VString	getLocalString (const VInstantFormatter &formatter) const
	Returns a string for this instant in local time in the specified format, or one of the special time value strings "PAST", "FUTURE", or "NEVER".
void	getUTCString (VString &s, bool fileNameSafe=false, bool wantMilliseconds=true) const
	Returns a string for this instant in UTC time, or one of the special time value strings "PAST", "FUTURE", or "NEVER".
void	getLocalString (VString &s, bool fileNameSafe=false, bool wantMilliseconds=true) const
	Returns a string for this instant in local time, or one of the special time value strings "PAST", "FUTURE", or "NEVER".
void	setUTCString (const VString &s)
	Sets the instant from a UTC string representation.
void	setLocalString (const VString &s)
	Sets the instant from a local string representation.
bool	isSpecific () const
	Returns true if the instance has a specific time value, indicating that it is not one of the special time constants NEVER_OCCURRED, INFINITE_PAST, or INFINITE_FUTURE.
bool	isComparable () const
	Returns true if the instance kind is comparable, indicating that it can be compared against another time along the timeline; in particular, instants with kind kNeverOccurred are not comparable.
Vs64	getValue () const
	Returns the raw time value of the instant, defined as milliseconds since UTC 1970 00:00:00.000.
void	setValue (Vs64 value)
	Sets the raw time value of the instant, defined as milliseconds since UTC 1970 00:00:00.000.
VDate	getLocalDate () const
	Returns a VDate to represent the instant's date, just as would be returned in the date value returned by getValues() if you specified the local time zone.
VDate	getDate (const VString &timeZoneID) const
	Returns a VDate to represent the instant's date, just as would be returned in the date value returned by getValues().
VTimeOfDay	getLocalTimeOfDay () const
	Returns a VTimeOfDay to represent the instant's time, just as would be returned in the timeOfDay value returned by getValues() if you specified the local time zone.
VTimeOfDay	getTimeOfDay (const VString &timeZoneID) const
	Returns a VTimeOfDay to represent the instant's time, just as would be returned in the timeOfDay value returned by getValues().
VDateAndTime	getLocalDateAndTime () const
	Returns a VDateAndTime to represent the instant's time, just as would be returned in the values returned by getValues(), using the local time zone.
VDateAndTime	getDateAndTime (const VString &timeZoneID) const
	Returns a VDateAndTime to represent the instant's time, just as would be returned in the values returned by getValues().
void	setLocalDateAndTime (const VDateAndTime &dt)
	Sets the instant to represent the specified time, just as would be done by setValues(), using the local time zone.
void	setDateAndTime (const VDateAndTime &dt, const VString &timeZoneID)
	Sets the instant to represent the specified time, just as would be done by setValues(), using the specified time zone.
void	getValues (VDate &date, VTimeOfDay &timeOfDay, const VString &timeZoneID) const
	Returns a VDate and VTimeOfDay to represent the instant, either in UTC or local time, or in a remote time zone (if an RTZ converter has been installed).
void	setValues (const VDate &date, const VTimeOfDay &timeOfDay, const VString &timeZoneID)
	Sets the instant from a VDate and VTimeOfDay, either in UTC or local time, or in a remote time zone (if an RTZ converter has been installed).
Vs64	getLocalOffsetMilliseconds () const
	Returns the local offset in milliseconds, of the local time zone, at the instant in time represented by this VInstant.
Static Public Member Functions
static const VInstant &	INFINITE_PAST ()
	Constant VInstant representing the kInfinitePast value.
static const VInstant &	INFINITE_FUTURE ()
	Constant VInstant representing the kInfiniteFuture value.
static const VInstant &	NEVER_OCCURRED ()
	Constant VInstant representing the kNeverOccurred value.
static const VString &	UTC_TIME_ZONE_ID ()
	Constant for use with functions that take a timeZoneID parameter, indicating the time conversion is for UTC.
static const VString &	LOCAL_TIME_ZONE_ID ()
	Constant for use with functions that take a timeZoneID parameter, indicating the time conversion is for the local time zone.
static VInstant	instantFromRawValue (Vs64 value)
	Returns an instant created from a raw 64-bit millisecond UTC epoch offset, of the same form as is returned by getValue() and can be passed to setValue().
static VInstant	instantFromPosixTime (time_t value)
	Returns an instant created from a POSIX time_t value, which is defined as the number of seconds since UTC 1970 00:00:00.000.
static VInstant	min (const VInstant &i1, const VInstant &i2)
	Returns the earlier of i1 and i2.
static VInstant	max (const VInstant &i1, const VInstant &i2)
	Returns the later of i1 and i2.
static Vs64	snapshot ()
	Returns a relatively high-resolution snapshot of the current time, for use with a subsequent call to VInstant::snapshotDelta().
static VDuration	snapshotDelta (Vs64 snapshotValue)
	Returns the delta between the current time and the supplied origin snapshot value.
static void	setRemoteTimeZoneConverter (IVRemoteTimeZoneConverter *converter)
	Installs a Remote Time Zone Converter, that VInstant will use for functions that take a timeZoneID, if that parameter is not UTC or the local time zone.
static IVRemoteTimeZoneConverter *	getRemoteTimeZoneConverter ()
	Returns the currently installed Remote Time Zone Converter, which may be NULL.
static void	incrementSimulatedClockOffset (const VDuration &delta)
	Adjusts the simulated clock offset.
static void	setSimulatedClockOffset (const VDuration &offset)
	Sets the simulated clock offset.
static void	setSimulatedClockValue (const VInstant &simulatedCurrentTime)
	Sets the simulated clock offset implied by the specified absolute time value.
static VDuration	getSimulatedClockOffset ()
	Returns the simulated clock offset.
static void	freezeTime (const VInstant &frozenTimeValue)
	Freezes the flow of time by specifying an absolute time that will be returned by any call to setNow(), as well as any use of snapshot() to track time deltas.
static void	shiftFrozenTime (const VDuration &delta)
	Shifts the frozen time value by the specified amount.
static void	unfreezeTime ()
	Unfreezes time and resumes real-time operation.
static bool	isTimeFrozen ()
	Returns true if time is currently frozen.
Friends
class	VDate
class	VInstantUnit
bool	operator== (const VInstant &lhs, const VInstant &rhs)
	Compares two instants.
bool	operator!= (const VInstant &lhs, const VInstant &rhs)
	Compares two instants.
bool	operator< (const VInstant &lhs, const VInstant &rhs)
	Compares two instants.
bool	operator<= (const VInstant &lhs, const VInstant &rhs)
	Compares two instants.
bool	operator>= (const VInstant &lhs, const VInstant &rhs)
	Compares two instants.
bool	operator> (const VInstant &lhs, const VInstant &rhs)
	Compares two instants.
VDuration	operator- (const VInstant &i1, const VInstant &i2)
	Returns the time duration between i1 and i2.
VInstant	operator+ (const VInstant &i1, const VDuration &forwardDuration)
	Returns an instant incremented by a delta.
VInstant	operator- (const VInstant &i1, const VDuration &backwardDuration)
	Returns an instant decremented by a delta.

---

Detailed Description

A VInstant is an object that represents an instant in time regardless of the location (and time zone) of where code is running.

A key purpose of VInstant is to abstract the OS time-related APIs while retaining the ability to easily compare two instants that originated in code running in different time zones--internally, the value is stored in UTC time.

You can create a VInstant to represent the current instant in time, and you can convert to and from string representations in UTC or the current locale. A VInstant can also be created to represent instants infinitely far in the past or future, to indicate events that have not yet happened or should never happen.

Definition at line 431 of file vinstant.h.

---

Member Function Documentation

const VInstant & VInstant::INFINITE_PAST

(

)

[static]

Constant VInstant representing the kInfinitePast value.

Definition at line 537 of file vinstant.cpp.

const VInstant & VInstant::INFINITE_FUTURE

(

)

[static]

Constant VInstant representing the kInfiniteFuture value.

Definition at line 542 of file vinstant.cpp.

const VInstant & VInstant::NEVER_OCCURRED

(

)

[static]

Constant VInstant representing the kNeverOccurred value.

Definition at line 547 of file vinstant.cpp.

const VString & VInstant::UTC_TIME_ZONE_ID

(

)

[static]

Constant for use with functions that take a timeZoneID parameter, indicating the time conversion is for UTC.

Definition at line 552 of file vinstant.cpp.

const VString & VInstant::LOCAL_TIME_ZONE_ID

(

)

[static]

Constant for use with functions that take a timeZoneID parameter, indicating the time conversion is for the local time zone.

Definition at line 557 of file vinstant.cpp.

static VInstant VInstant::instantFromRawValue

(

Vs64

value

)

[inline, static]

Returns an instant created from a raw 64-bit millisecond UTC epoch offset, of the same form as is returned by getValue() and can be passed to setValue().

Parameters:

value

the time value in ms since UTC 1970 00:00:00.000 (negative values represent earlier instants in time)

Returns:

an instant representing the specified time

Definition at line 455 of file vinstant.h.

References VInstant().

static VInstant VInstant::instantFromPosixTime

(

time_t

value

)

[inline, static]

Returns an instant created from a POSIX time_t value, which is defined as the number of seconds since UTC 1970 00:00:00.000.

Parameters:

value

the POSIX time value (seconds since UTC 1970 00:00:00.000) (negative values represent earlier instants in time)

Returns:

an instant representing the specified time

Definition at line 464 of file vinstant.h.

References CONST_S64, and VInstant().

VInstant & VInstant::operator=

(

const VInstant &

i

)

Copy constructor.

Parameters:

i	the instant to copy

Definition at line 583 of file vinstant.cpp.

References getValue().

VInstant & VInstant::operator+=

(

const VDuration &

forwardOffsetDuration

)

Increments (or decrements) the instant in time from its current value by the specified VDuration if the kind is kActualValue.

If the kind is not kActualValue, this function has no effect.

Parameters:

forwardOffsetDuration

the duration offset in milliseconds to apply; positive values move the instant forward in time; negative values move it backward

Definition at line 591 of file vinstant.cpp.

References VDuration::getDurationMilliseconds(), INFINITE_FUTURE(), INFINITE_PAST(), VDuration::isSpecific(), isSpecific(), VDuration::NEGATIVE_INFINITY(), and VDuration::POSITIVE_INFINITY().

VInstant & VInstant::operator-=

(

const VDuration &

backwardOffsetDuration

)

Decrements (or increments) the instant in time from its current value by the specified VDuration if the kind is kActualValue.

If the kind is not kActualValue, this function has no effect.

Parameters:

backwardOffsetDuration

the offset in milliseconds to apply; positive values move the instant backward in time; negative values move it forward

Definition at line 602 of file vinstant.cpp.

References VDuration::getDurationMilliseconds(), INFINITE_FUTURE(), INFINITE_PAST(), VDuration::isSpecific(), isSpecific(), VDuration::NEGATIVE_INFINITY(), and VDuration::POSITIVE_INFINITY().

void VInstant::setNow

(

)

Sets the instant to the current time.

The time is affected by any simulated or frozen time state that has been set.

Definition at line 613 of file vinstant.cpp.

VInstantStruct VInstant::getUTCInstantFields

(

)

const

Returns an object holding the broken-down fields that this instant represents in UTC.

This is primarily for use by VInstantFormatter when formatting a string.

Returns:

the UTC y/m/d/h/m/s etc. values for this instant

Definition at line 626 of file vinstant.cpp.

References VInstantStruct::setUTCStructFromOffset().

VInstantStruct VInstant::getLocalInstantFields

(

)

const

Returns an object holding the broken-down fields that this instant represents in the current time zone.

This is primarily for use by VInstantFormatter when formatting a string.

Returns:

the current time zone y/m/d/h/m/s etc. values for this instant

Definition at line 632 of file vinstant.cpp.

References VInstantStruct::setLocalStructFromOffset().

VString VInstant::getUTCString

(

)

const

Returns a string for this instant in UTC time in the format "y-MM-dd HH:mm:ss.SSS UTC", or one of the special time value strings "PAST", "FUTURE", or "NEVER".

Returns:

obvious

Definition at line 665 of file vinstant.cpp.

VString VInstant::getUTCString

(

const VInstantFormatter &

formatter

)

const

Returns a string for this instant in UTC time in the specified format, or one of the special time value strings "PAST", "FUTURE", or "NEVER".

Parameters:

formatter

the formatter to use

Returns:

obvious

Definition at line 669 of file vinstant.cpp.

References VInstantFormatter::formatUTCString(), INFINITE_FUTURE(), INFINITE_PAST(), and isSpecific().

VString VInstant::getLocalString

(

)

const

Returns a string for this instant in local time in the format "y-MM-dd HH:mm:ss.SSS", or one of the special time value strings "PAST", "FUTURE", or "NEVER".

Returns:

obvious

Definition at line 685 of file vinstant.cpp.

VString VInstant::getLocalString

(

const VInstantFormatter &

formatter

)

const

Returns a string for this instant in local time in the specified format, or one of the special time value strings "PAST", "FUTURE", or "NEVER".

Parameters:

formatter

the formatter to use

Returns:

obvious

Definition at line 689 of file vinstant.cpp.

References VInstantFormatter::formatLocalString(), INFINITE_FUTURE(), INFINITE_PAST(), and isSpecific().

void VInstant::getUTCString	(	VString &	s,
		bool	fileNameSafe = false,
		bool	wantMilliseconds = true
	)		const

Returns a string for this instant in UTC time, or one of the special time value strings "PAST", "FUTURE", or "NEVER".

You can specify whether to use a format that is safe for use in a file system node name (no punctuation), and whether to include the milliseconds.

Parameters:

s	the string for format for return
fileNameSafe	if true, the format omits punctuation and the " UTC" suffix so it can be safely used in a file system node name
wantMilliseconds	if true, the milliseconds suffix is included; otherwise not

Definition at line 681 of file vinstant.cpp.

References getUTCString().

void VInstant::getLocalString	(	VString &	s,
		bool	fileNameSafe = false,
		bool	wantMilliseconds = true
	)		const

Returns a string for this instant in local time, or one of the special time value strings "PAST", "FUTURE", or "NEVER".

You can specify whether to use a format that is safe for use in a file system node name (no punctuation), and whether to include the milliseconds.

Parameters:

s	the string for format for return
fileNameSafe	if true, the format omits punctuation so it can be safely used in a file system node name
wantMilliseconds	if true, the milliseconds suffix is included; otherwise not

Definition at line 701 of file vinstant.cpp.

References getLocalString().

void VInstant::setUTCString

(

const VString &

s

)

Sets the instant from a UTC string representation.

You must use the same string format as returned by getUTCString(), that is "y-MM-dd HH:mm:ss.SSS UTC", or one of the special time value strings "PAST", "FUTURE", or "NEVER", or the special string "NOW".

Parameters:

s	the UTC string representation of the instant

See also:

VInstant::getUTCString()

Definition at line 707 of file vinstant.cpp.

References VInstantStruct::getOffsetFromUTCStruct(), VString::isEmpty(), VInstantStruct::mDay, VInstantStruct::mDayOfWeek, VInstantStruct::mHour, VInstantStruct::mMillisecond, VInstantStruct::mMinute, VInstantStruct::mMonth, VInstantStruct::mSecond, VInstantStruct::mYear, and setNow().

void VInstant::setLocalString

(

const VString &

s

)

Sets the instant from a local string representation.

You must use the same string format as returned by getLocalString(), that is "y-MM-dd HH:mm:ss.SSS", or one of the special time value strings "PAST", "FUTURE", or "NEVER", or the special string "NOW".

Parameters:

s	the local string representation of the instant

See also:

VInstant::getLocalString()

Definition at line 728 of file vinstant.cpp.

References VInstantStruct::getOffsetFromLocalStruct(), VString::isEmpty(), VInstantStruct::mDay, VInstantStruct::mDayOfWeek, VInstantStruct::mHour, VInstantStruct::mMillisecond, VInstantStruct::mMinute, VInstantStruct::mMonth, VInstantStruct::mSecond, VInstantStruct::mYear, and setNow().

Vs64 VInstant::getValue

(

)

const [inline]

Returns the raw time value of the instant, defined as milliseconds since UTC 1970 00:00:00.000.

Actual resolution may only be seconds, depending on OS. You should generally avoid accessing this value since it is not abstract; you can use other functions and operators to shift forward and backward in time, to get streamable values, etc. You can use the value returned by this function to set into another VInstant using setValue(), but you must also synchronize the "kind" as well (see getKind(), setKind()) if you are using any kinds other than kActualValue.

Returns:

the time value in ms since UTC 1970 00:00:00.000 (negative values represent earlier instants in time)

Definition at line 631 of file vinstant.h.

void VInstant::setValue

(

Vs64

value

)

[inline]

Sets the raw time value of the instant, defined as milliseconds since UTC 1970 00:00:00.000.

Actual resolution may only be seconds, depending on OS. You should generally avoid accessing this value since it is not abstract; you can use other functions and operators to shift forward and backward in time, to set from streamed values, etc. You can use the value returned by getValue() to supply to this function, but you must also synchronize the "kind" as well (see getKind(), setKind()) if you are using any kinds other than kActualValue.

Parameters:

value

the time value in ms since UTC 1970 00:00:00.000 (negative values represent earlier instants in time)

Definition at line 644 of file vinstant.h.

VDate VInstant::getLocalDate

(

)

const

Returns a VDate to represent the instant's date, just as would be returned in the date value returned by getValues() if you specified the local time zone.

Returns:

the date of the instant in the local time zone

Definition at line 763 of file vinstant.cpp.

References getDate(), and LOCAL_TIME_ZONE_ID().

VDate VInstant::getDate

(

const VString &

timeZoneID

)

const

Returns a VDate to represent the instant's date, just as would be returned in the date value returned by getValues().

The difference is that this function only returns the date, as a convenience. If you need both date and time, it is more efficient to call getValues() than getDate() followed by getTimeOfDay(), because the underlying conversion must happen on each of those calls. Throws an exception if you specify RTZ conversion and there is no converter installed.

Parameters:

timeZoneID

specifies which time zone the result should be given in

Returns:

the date of the instant in the specified time zone

Definition at line 767 of file vinstant.cpp.

References VString::chars(), LOCAL_TIME_ZONE_ID(), VInstantStruct::mDay, VInstantStruct::mMonth, VInstantStruct::mYear, NULL, IVRemoteTimeZoneConverter::offsetToRTZStruct(), VInstantStruct::setLocalStructFromOffset(), VInstantStruct::setUTCStructFromOffset(), and UTC_TIME_ZONE_ID().

VTimeOfDay VInstant::getLocalTimeOfDay

(

)

const

Returns a VTimeOfDay to represent the instant's time, just as would be returned in the timeOfDay value returned by getValues() if you specified the local time zone.

Returns:

the time of day of the instant in the local time zone

Definition at line 782 of file vinstant.cpp.

References getTimeOfDay(), and LOCAL_TIME_ZONE_ID().

VTimeOfDay VInstant::getTimeOfDay

(

const VString &

timeZoneID

)

const

Returns a VTimeOfDay to represent the instant's time, just as would be returned in the timeOfDay value returned by getValues().

The difference is that this function only returns the time of day, as a convenience. If you need both date and time, it is more efficient to call getValues() than getDate() followed by getTimeOfDay(), because the underlying conversion must happen on each of those calls. Throws an exception if you specify RTZ conversion and there is no converter installed.

Parameters:

timeZoneID

specifies which time zone the result should be given in

Returns:

the time of day of the instant in the specified time zone

Definition at line 786 of file vinstant.cpp.

References VString::chars(), LOCAL_TIME_ZONE_ID(), VInstantStruct::mHour, VInstantStruct::mMillisecond, VInstantStruct::mMinute, VInstantStruct::mSecond, NULL, IVRemoteTimeZoneConverter::offsetToRTZStruct(), VInstantStruct::setLocalStructFromOffset(), VInstantStruct::setUTCStructFromOffset(), and UTC_TIME_ZONE_ID().

VDateAndTime VInstant::getLocalDateAndTime

(

)

const

Returns a VDateAndTime to represent the instant's time, just as would be returned in the values returned by getValues(), using the local time zone.

Returns:

the date and time of day of the instant in the local time zone

Definition at line 801 of file vinstant.cpp.

References getDateAndTime(), and LOCAL_TIME_ZONE_ID().

VDateAndTime VInstant::getDateAndTime

(

const VString &

timeZoneID

)

const

Returns a VDateAndTime to represent the instant's time, just as would be returned in the values returned by getValues().

Throws an exception if you specify RTZ conversion and there is no converter installed.

Parameters:

timeZoneID

specifies which time zone the result should be given in

Returns:

the date and time of day of the instant in the specified time zone

Definition at line 805 of file vinstant.cpp.

References VString::chars(), getLocalString(), INFINITE_FUTURE(), INFINITE_PAST(), LOCAL_TIME_ZONE_ID(), VInstantStruct::mDay, VInstantStruct::mHour, VInstantStruct::mMillisecond, VInstantStruct::mMinute, VInstantStruct::mMonth, VInstantStruct::mSecond, VInstantStruct::mYear, NEVER_OCCURRED(), NULL, IVRemoteTimeZoneConverter::offsetToRTZStruct(), VInstantStruct::setLocalStructFromOffset(), VInstantStruct::setUTCStructFromOffset(), and UTC_TIME_ZONE_ID().

void VInstant::setLocalDateAndTime

(

const VDateAndTime &

dt

)

Sets the instant to represent the specified time, just as would be done by setValues(), using the local time zone.

Parameters:

dt	the date and time of day to use

Definition at line 824 of file vinstant.cpp.

References LOCAL_TIME_ZONE_ID(), and setDateAndTime().

void VInstant::setDateAndTime	(	const VDateAndTime &	dt,
		const VString &	timeZoneID
	)

Sets the instant to represent the specified time, just as would be done by setValues(), using the specified time zone.

Throws an exception if you specify RTZ conversion and there is no converter installed.

Parameters:

dt	the date and time of day to use
timeZoneID	specifies which time zone the date and time is given in

Definition at line 828 of file vinstant.cpp.

References VString::chars(), VInstantStruct::getOffsetFromLocalStruct(), VInstantStruct::getOffsetFromUTCStruct(), LOCAL_TIME_ZONE_ID(), NULL, IVRemoteTimeZoneConverter::offsetFromRTZStruct(), and UTC_TIME_ZONE_ID().

void VInstant::getValues	(	VDate &	date,
		VTimeOfDay &	timeOfDay,
		const VString &	timeZoneID
	)		const

Returns a VDate and VTimeOfDay to represent the instant, either in UTC or local time, or in a remote time zone (if an RTZ converter has been installed).

Throws an exception if you specify RTZ conversion and there is no converter installed.

Parameters:

date	the VDate to set
timeOfDay	the VTimeOfDay to set
timeZoneID	specifies which time zone the result should be given in

Definition at line 747 of file vinstant.cpp.

References VString::chars(), LOCAL_TIME_ZONE_ID(), VInstantStruct::mDay, VInstantStruct::mHour, VInstantStruct::mMillisecond, VInstantStruct::mMinute, VInstantStruct::mMonth, VInstantStruct::mSecond, VInstantStruct::mYear, NULL, IVRemoteTimeZoneConverter::offsetToRTZStruct(), VDate::set(), VTimeOfDay::set(), VInstantStruct::setLocalStructFromOffset(), VInstantStruct::setUTCStructFromOffset(), and UTC_TIME_ZONE_ID().

void VInstant::setValues	(	const VDate &	date,
		const VTimeOfDay &	timeOfDay,
		const VString &	timeZoneID
	)

Sets the instant from a VDate and VTimeOfDay, either in UTC or local time, or in a remote time zone (if an RTZ converter has been installed).

Throws an exception if you specify RTZ conversion and there is no converter installed.

Parameters:

date	the date to use
timeOfDay	the time of day to use
timeZoneID	specifies which time zone in which the supplied date and time are given in

Definition at line 841 of file vinstant.cpp.

References VString::chars(), VInstantStruct::getOffsetFromLocalStruct(), VInstantStruct::getOffsetFromUTCStruct(), LOCAL_TIME_ZONE_ID(), NULL, IVRemoteTimeZoneConverter::offsetFromRTZStruct(), and UTC_TIME_ZONE_ID().

Vs64 VInstant::getLocalOffsetMilliseconds

(

)

const

Returns the local offset in milliseconds, of the local time zone, at the instant in time represented by this VInstant.

For locales west of GMT, this value is negative (e.g., -8 hours or -7 hours in California, depending on daylight time), and for locales east of GMT, this value is positive.

Definition at line 856 of file vinstant.cpp.

References VInstantStruct::mDay, VInstantStruct::mHour, VInstantStruct::mMinute, VInstantStruct::mSecond, VInstantStruct::setLocalStructFromOffset(), and VInstantStruct::setUTCStructFromOffset().

VInstant VInstant::min	(	const VInstant &	i1,
		const VInstant &	i2
	)		[inline, static]

Returns the earlier of i1 and i2.

Parameters:

i1	an instant
i2	an instant

Returns:

i1 if i1 < i2

Definition at line 941 of file vinstant.h.

VInstant VInstant::max	(	const VInstant &	i1,
		const VInstant &	i2
	)		[inline, static]

Returns the later of i1 and i2.

Parameters:

i1	an instant
i2	an instant

Returns:

i1 if i1 > i2

Definition at line 942 of file vinstant.h.

Vs64 VInstant::snapshot

(

)

[static]

Returns a relatively high-resolution snapshot of the current time, for use with a subsequent call to VInstant::snapshotDelta().

You should not assume that the snapshot value remains valid across system starts; if you need to get the difference in times across reboots, use normal VInstant operator minus.

Returns:

the current system clock snapshot

Definition at line 993 of file vinstant.cpp.

VDuration VInstant::snapshotDelta

(

Vs64

snapshotValue

)

[static]

Returns the delta between the current time and the supplied origin snapshot value.

As noted in the VInstant::snapshot() docs, the delta may not work across reboots.

Parameters:

snapshotValue

a snapshot value from VInstant::snapshot()

Returns:

the time delta from the snapshot to now

Definition at line 1001 of file vinstant.cpp.

References VDuration::MILLISECOND(), and snapshot().

void VInstant::setRemoteTimeZoneConverter

(

IVRemoteTimeZoneConverter *

converter

)

[static]

Installs a Remote Time Zone Converter, that VInstant will use for functions that take a timeZoneID, if that parameter is not UTC or the local time zone.

The caller still owns the converter; VInstant will not delete it. You can pass NULL to disable use of RTZ conversion (by default, no converter is installed).

Definition at line 568 of file vinstant.cpp.

IVRemoteTimeZoneConverter * VInstant::getRemoteTimeZoneConverter

(

)

[static]

Returns the currently installed Remote Time Zone Converter, which may be NULL.

You might use this to delete the old converter if you are installing a new one. VInstant uses whatever converter is installed (if it's not NULL) at the time it needs it.

Definition at line 573 of file vinstant.cpp.

void VInstant::incrementSimulatedClockOffset

(

const VDuration &

delta

)

[static]

Adjusts the simulated clock offset.

The simulated clock offset is applied by _platform_now() and _platform_snapshot() to the values they return. This can be used to simulate a faster passing of time, by adjusting the clock forward. It may be impractical to adjust the clock backwards, because some code constructs may behave badly if time flows backwards. However, you may be able to apply an initial backwards offset if you wish to start your program running in a simulated time in the past.

Parameters:

delta

the amount of offset to add/delete

Definition at line 1006 of file vinstant.cpp.

References VDuration::getDurationMilliseconds().

void VInstant::setSimulatedClockOffset

(

const VDuration &

offset

)

[static]

Sets the simulated clock offset.

The simulated clock offset is applied by setNow() and snapshot() to the values they return. This can be used to simulate a faster passing of time, by adjusting the clock forward. It may be impractical to adjust the clock backwards, because some code constructs may behave badly if time flows backwards. However, you may be able to apply an initial backwards offset if you wish to start your program running in a simulated time in the past.

Parameters:

offset

the simulated clock offset

Definition at line 1011 of file vinstant.cpp.

References VDuration::getDurationMilliseconds().

void VInstant::setSimulatedClockValue

(

const VInstant &

simulatedCurrentTime

)

[static]

Sets the simulated clock offset implied by the specified absolute time value.

The simulated clock offset is applied by setNow() and snapshot() to the values they return. This can be used to simulate a faster passing of time, by adjusting the clock forward. It may be impractical to adjust the clock backwards, because some code constructs may behave badly if time flows backwards. However, you may be able to apply an initial backwards offset if you wish to start your program running in a simulated time in the past.

Parameters:

simulatedCurrentTime

the simulated time from which to calculate the offset

Definition at line 1016 of file vinstant.cpp.

References setSimulatedClockOffset().

VDuration VInstant::getSimulatedClockOffset

(

)

[static]

Returns the simulated clock offset.

The simulated clock offset is applied by _platform_now() and _platform_snapshot() to the values they return. This can be used to simulate a faster passing of time, by adjusting the clock forward. It may be impractical to adjust the clock backwards, because some code constructs may behave badly if time flows backwards. However, you may be able to apply an initial backwards offset if you wish to start your program running in a simulated time in the past.

Definition at line 1023 of file vinstant.cpp.

References VDuration::MILLISECOND().

void VInstant::freezeTime

(

const VInstant &

frozenTimeValue

)

[static]

Freezes the flow of time by specifying an absolute time that will be returned by any call to setNow(), as well as any use of snapshot() to track time deltas.

Parameters:

frozenTimeValue

the time value that is frozen

Definition at line 1028 of file vinstant.cpp.

References getValue().

void VInstant::shiftFrozenTime

(

const VDuration &

delta

)

[static]

Shifts the frozen time value by the specified amount.

This can be used to freeze time and then cause it to flow slowly or quickly by manually rolling time forward at the desired rate.

Parameters:

delta

the duration by which to offset the frozen time; negative values may have strange effects

Definition at line 1033 of file vinstant.cpp.

References VDuration::getDurationMilliseconds().

void VInstant::unfreezeTime

(

)

[static]

Unfreezes time and resumes real-time operation.

If you previously used a future time for freezing, you should probably install a clock offset value before unfreezing, to ensure that time proceeds forward; otherwise you will unfreeze and end up in an earlier time (now).

Definition at line 1038 of file vinstant.cpp.

bool VInstant::isTimeFrozen

(

)

[static]

Returns true if time is currently frozen.

Returns:

true if time is frozen

Definition at line 1043 of file vinstant.cpp.

---

Friends And Related Function Documentation

VDuration operator-	(	const VInstant &	i1,
		const VInstant &	i2
	)		[friend]

Returns the time duration between i1 and i2.

Parameters:

i1	an instant
i2	an instant

Returns:

i1 - i2 as a VDuration

Definition at line 938 of file vinstant.h.

VInstant operator+	(	const VInstant &	i1,
		const VDuration &	forwardDuration
	)		[friend]

Returns an instant incremented by a delta.

Parameters:

i1	an instant
forwardDuration	the duration to add

Returns:

the result of i1+forwardDuration

Definition at line 939 of file vinstant.h.

VInstant operator-	(	const VInstant &	i1,
		const VDuration &	backwardDuration
	)		[friend]

Returns an instant decremented by a delta.

Parameters:

i1	an instant
backwardDuration	the duration to subtract to add

Returns:

the result of i1-backwardDuration

Definition at line 940 of file vinstant.h.

---

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

• vinstant.h
• _unix/vinstant_platform.cpp
• _win/vinstant_platform.cpp
• vinstant.cpp