HydraExpress™ C++ API Reference Guide

Product Documentation:
   HydraExpress C++
Documentation Home
List of all members | Public Member Functions | Private Member Functions | Related Functions
rwsf::TimeSpan Class Reference

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

#include <rwsf/core/TimeSpan.h>

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 std::string asString () const
 
virtual int compareTo (const TimeSpan &rhs)
 
virtual void extract (const std::string &duration)
 
unsigned long getDays () const
 
unsigned long getHours () const
 
unsigned long getMinutes () const
 
unsigned long getMonths () const
 
double getSeconds () const
 
unsigned long getYears () const
 
virtual bool isEqual (const TimeSpan &rhs)
 
bool isNegative () const
 
bool isValid () const
 
DateTime operator+ (const rwsf::DateTime &aDateTime) const
 
TimeSpanoperator- ()
 
TimeSpanoperator= (const TimeSpan &rhs)
 
void setDays (unsigned long days)
 
void setHours (unsigned long hours)
 
void setMinutes (unsigned long minutes)
 
void setMonths (unsigned long yemonthsars)
 
void setSeconds (double seconds)
 
void setYears (unsigned long years)
 

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:

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.

Copyright © 2019 Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is registered trademark of Rogue Wave Software, Inc. in the United States and other countries, and HydraExpress is a trademark of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.