Rogue Wave web site:  Home Page  |  Main Documentation Page

rwsf::TimeSpan Class Reference
[Core Date/Time Manipulation]

Provides constructors to create a timespan instance, and convenience methods to access its different parts. More...

#include <rwsf/core/TimeSpan.h>

List of all members.

Public Member Functions
	TimeSpan (unsigned long years=0, unsigned long months=0, unsigned long days=0, unsigned long hours=0, unsigned long minutes=0, double seconds=0.0)
	TimeSpan (const std::string &duration)
	TimeSpan (const TimeSpan &other)
virtual	~TimeSpan ()
virtual bool	isEqual (const TimeSpan &rhs)
virtual int	compareTo (const TimeSpan &rhs)
virtual void	extract (const std::string &duration)
virtual std::string	asString () const
bool	isValid () const
bool	isNegative () const
void	setYears (unsigned long years)
unsigned long	getYears () const
void	setMonths (unsigned long yemonthsars)
unsigned long	getMonths () const
void	setDays (unsigned long days)
unsigned long	getDays () const
void	setHours (unsigned long hours)
unsigned long	getHours () const
void	setMinutes (unsigned long minutes)
unsigned long	getMinutes () const
void	setSeconds (double seconds)
double	getSeconds () const
DateTime	operator+ (const rwsf::DateTime &aDateTime) const
TimeSpan &	operator= (const TimeSpan &rhs)
TimeSpan &	operator- ()
Private Member Functions
void	clear ()
Related Functions
(Note that these are not member functions.)
bool	operator== (const TimeSpan &lhs, const TimeSpan &rhs)
bool	operator!= (const TimeSpan &lhs, const TimeSpan &rhs)
bool	operator< (const TimeSpan &lhs, const TimeSpan &rhs)

---

Detailed Description

rwsf::TimeSpan represents a period as defined by ISO8601. The serialized version of this type takes the format PnYnMnDTnHnMnS, where:

• P the letter 'P' (This indicates the start of a ISO8601 time span period)
• nY represents the number of years
• nM the number of months
• nD the number of days
• T is the date/time separator
• nH the number of hours
• nM the number of minutes
• nS the number of seconds

The number of seconds can include decimal digits.

This class provides constructors to create a timespan instance, and convenience methods to access its different parts. An instance of this class can be constructed either from a valid duration string, or by providing values for each of the parts of a duration. This class also provides operators and methods to add a duration to an rwsf::DateTime instance, and to determine the ordering relationship between two durations.

An instance of this class validates the data it contains whenever the data changes. If the string is valid, the object marks itself valid. If the string is invalid, the object marks itself invalid. See isValid() for more information on invalid objects.

---

Constructor & Destructor Documentation

rwsf::TimeSpan::TimeSpan	(	unsigned long	years = 0,
		unsigned long	months = 0,
		unsigned long	days = 0,
		unsigned long	hours = 0,
		unsigned long	minutes = 0,
		double	seconds = 0.0
	)

Constructs an instance of rwsf::TimeSpan based on the values given. The default constructor creates a valid object representing a duration of 0.

rwsf::TimeSpan::TimeSpan

(

const std::string &

duration

)

Constructs an instance of rwsf::TimeSpan representing the string duration. Calls extract() to extract the contents. If the string provided is not in the format PnYnMnDTnHnMnS, constructs an invalid object.

rwsf::TimeSpan::TimeSpan

(

const TimeSpan &

other

)

Copy constructor. Constructs a deep copy of other.

virtual rwsf::TimeSpan::~TimeSpan

(

)

[virtual]

Destructor.

---

Member Function Documentation

virtual std::string rwsf::TimeSpan::asString

(

)

const [virtual]

Returns a string representation of self, formatted according to the XML Schema specification for the duration simple type. Returns an empty string if self is invalid.

void rwsf::TimeSpan::clear

(

)

[private]

Sets all duration data to 0 and sets this object as invalid. See isValid() for details.

virtual int rwsf::TimeSpan::compareTo

(

const TimeSpan &

rhs

)

[virtual]

Returns -1, 0, or 1 depending on whether self is less than, equal to, or greater than rhs, respectively. The comparison is based on value semantics. The duration is converted into a single unit to determine equality, based on the fixed mapping scheme:

 1Y == 12M == 365D
 1M == 365/12 days
 1D == 24H
 1H == 60M
 1M == 60Seconds

virtual void rwsf::TimeSpan::extract

(

const std::string &

duration

)

[virtual]

Sets the timespan data based on the ISO8601 string provided in duration. If duration is not in the format PnYnMnDTnHnMnS, this TimeSpan instance is marked invalid. See isValid() for more information on invalid objects.

unsigned long rwsf::TimeSpan::getDays

(

)

const

Returns the number of days represented by self. The return value is undefined if self is not valid. See isValid() for details.

unsigned long rwsf::TimeSpan::getHours

(

)

const

Returns the number of hours represented by self. The return value is undefined if self is not valid. See isValid() for details.

unsigned long rwsf::TimeSpan::getMinutes

(

)

const

Returns the number of minutes represented by self. The return value is undefined if self is not valid. See isValid() for details.

unsigned long rwsf::TimeSpan::getMonths

(

)

const

Returns the number of months represented by self. The return value is undefined if self is not valid. See isValid() for details.

double rwsf::TimeSpan::getSeconds

(

)

const

Returns the number of seconds represented by self. The return value is undefined if self is not valid. See isValid() for details.

unsigned long rwsf::TimeSpan::getYears

(

)

const

Returns the number of years represented by self. The return value is undefined if self is not valid. See isValid() for details.

virtual bool rwsf::TimeSpan::isEqual

(

const TimeSpan &

rhs

)

[virtual]

Equality based on value semantics. Returns true if compareTo(rhs) returns 0.

bool rwsf::TimeSpan::isNegative

(

)

const

Returns true if self is a negative duration. The return value is undefined if self is not valid. See isValid() for details.

bool rwsf::TimeSpan::isValid

(

)

const

Returns true if self is valid. Parsing an invalid duration string leads to an invalid rwsf::TimeSpan instance. The values for years, months, days, and so on are undefined for an invalid instance, as are the return values of all other methods.

DateTime rwsf::TimeSpan::operator+

(

const rwsf::DateTime &

aDateTime

)

const

Implements addition as defined by Appendix E of the XML Schema 1.0 - Part 2: Datatypes specification. Given an rwsf::DateTime aDateTime, the addition operator computes an rwsf::DateTime at the end of the time period with start aDateTime and duration represented by self.

Note:

According to the specified algorithm, the order of addition is significant. For example, there could be cases where:

 (( aDateTime + aTimespan1 ) + aTimespan2) !=
 (( aDateTime + aTimespan2 ) + aTimespan1 ));

TimeSpan& rwsf::TimeSpan::operator-

(

)

Unary negation of self. Changes self to a negative duration if self is positive. Self is changed to a positive duration if self is already a negative duration.

TimeSpan& rwsf::TimeSpan::operator=

(

const TimeSpan &

rhs

)

Assignment operator. Sets the TimeSpan data on this object instance equal to the data in rhs

void rwsf::TimeSpan::setDays

(

unsigned long

days

)

Sets the number of days represented by self to days.

void rwsf::TimeSpan::setHours

(

unsigned long

hours

)

Sets the number of hours represented by self to hours.

void rwsf::TimeSpan::setMinutes

(

unsigned long

minutes

)

Sets the number of minutes represented by self to minutes.

void rwsf::TimeSpan::setMonths

(

unsigned long

yemonthsars

)

Sets the number of months represented by self to months.

void rwsf::TimeSpan::setSeconds

(

double

seconds

)

Sets the number of seconds represented by self to seconds.

void rwsf::TimeSpan::setYears

(

unsigned long

years

)

Sets the number of years represented by self to years.

---

Friends And Related Function Documentation

bool operator!=	(	const TimeSpan &	lhs,
		const TimeSpan &	rhs
	)			[related]

Returns true if not equal, otherwise false. Inequality is based on identity. The asString() of both the durations should not match. Different number of years, months, and so forth.

bool operator<	(	const TimeSpan &	lhs,
		const TimeSpan &	rhs
	)			[related]

The order relation on duration is partial order since there is no determinate relationship between certain durations such as one month and 30 days.

This method is implemented based on the ordering algorithm defined in Section 3.2.6.2 of XML Schema 1.0 - Part 2: Datatypes specification. This algorithm determines ordering by adding (as per operator+(const rwsf::DateTime)) four specific time instances to the each of these durations and comparing the result.

As the ordering is partial, some comparisons are indeterminate. For example comparing P1M and P30D returns false for both P1M < P30D and P30D < P1M. Check the schema specification for all indeterminate margin values.

bool operator==	(	const TimeSpan &	lhs,
		const TimeSpan &	rhs
	)			[related]

Returns true if equal, otherwise false. Equality is based on identity. The asString() of both the durations should match. Same number of years, months, and so forth.