RWTime(3C++) RWTime(3C++)
NameRWTime - Rogue Wave library class
Synopsis
#include <rw/rwtime.h>
RWTime a; // Construct with current time
Description
Class RWTime represents a time, stored as the number of seconds since
00:00:00 January 1, 1901 UTC. See Section 8 for how to set the time zone
for your compiler. Failure to do this may result in UTC (GMT) times
being wrong. Output formatting is done using an RWLocale object. The
default locale formats according to U.S. conventions. Note that because
the default constructor for this class creates an instance holding the
current date and time, constructing a large array of RWTime may be slow.
RWTime v[5000]; // Figures out the current time 5000 times
Those with access to the C++ Standard Library-based versions of the
Tools.h++ template collections should consider the following:
// Figures out the current time just once:
RWTValOrderedVector<RWTime> v(5000, RWTime());
Thanks to the smart allocation scheme of the standard collections, the
above declaration will result in only one call to the default constructor
followed by 5000 invocations of the copy constructor. In the case of
RWTime, the copy constructor amounts to an assignment of one long to
another, resulting in faster creation than the simple array.
Persistence
Simple
Example
This example constructs a current time, and the time when Daylight-Saving
Time starts in the year 1990. It then prints them out.
Page 1
RWTime(3C++) RWTime(3C++)
#include <rw/rwtime.h>
#include <rw/rwdate.h>
#include <rw/rstream.h>
main(){
RWTime t; // Current time
RWTime d(RWTime::beginDST(1990, RWZone::local()));
cout << "Current time: " << RWDate(t) << " " << t <<
endl;
cout << "Start of DST, 1990: " << RWDate(d) << " " << d <<
endl;
}
Program output
Current time: 03/22/91 15:01:40
Start of DST, 1990: 05/01/90 02:00:00
Public ConstructorsRWTime();
Default constructor. Constructs a time with the present time.
RWTime(const RWTime&);
Copy constructor.
RWTime(unsigned long s);
Constructs a time with s seconds since 00:00:00 January 1, 1901 UTC. If
s==0, an invalid time is constructed. Note that for small s this may be
prior to January 1, 1901 in your time zone.
RWTime(unsigned hour, unsigned minute, unsigned second=0,
const RWZone& zone = RWZone::local());
Constructs a time with today's date, and the specified hour, minute, and
second, relative to the time zone zone, which defaults to local time.
RWTime(const RWDate& date, unsigned hour = 0,
unsigned minute = 0,unsigned second = 0,
const RWZone& = RWZone::local());
Page 2
RWTime(3C++) RWTime(3C++)
Constructs a time for a given date, hour, minute, and second, relative to
the time zone zone, which defaults to local time. Note that the maximum
RWTime is much sooner than maximum RWDate. (In fact, it is on Feb. 5,
2037 for platforms with 4-byte longs.) This is a consequence of the fact
that RWTime counts seconds while RWDate only deals with full days.
RWTime(const struct tm*, const RWZone& = RWZone::local());
Constructs a time from the tm_year, tm_mon, tm_mday, tm_hour, tm_min, and
tm_sec components of the struct tm argument. These components are
understood to be relative to the time zone zone, which defaults to local
time. Note that the numbering of months and years in a struct tm differs
from that used in RWTime arguments.
RWTime(const RWDate& date, const RWCString& str,
const RWZone& zone = RWZone::local(),
const RWLocale& locale = RWLocale::global());
Constructs a time for the given date, extracting the time from the string
str. The string str should contain only the time. The time is
understood to be relative to the time zone zone, which defaults to local
time. The specified locale is used for formatting information . Use
function isValid() to check the results. Note: not all time string
errors can be detected by this function.
Public Member Operators
RWTime&
operator=(const RWTime&);
Assignment operator.
RWTimeoperator++();
Prefix increment operator. Add one second to self, then return the
results.
RWTimeoperator--();
Prefix decrement operator. Subtract one second from self, then return
the results.
RWTimeoperator++(int);
Page 3
RWTime(3C++) RWTime(3C++)
Postfix increment operator. Add one second to self, returning the
initial value.
RWTimeoperator--(int);
Postfix decrement operator. Subtract one second from self, returning the
initial value.
RWTime&
operator+=(unsigned long s);
Add s seconds to self, returning self.
RWTime&
operator-=(unsigned long s);
Subtract s seconds from self, returning self.
Public Member Functions
RWCString
asString(char format = ' ',const RWZone& = RWZone::local(),
const RWLocale& = RWLocale::global()) const;
Returns self as a string, formatted by the RWLocale argument, with the
time zone adjusted according to the RWZone argument. Formats are as
defined by the standard C library function strftime(). The default
format is the date followed by the time: "%x %X". The exact format of
the date and time returned is dependent upon the implementation of
strftime() available. For more information, look under RWLocale.
RWCString
asString(char* format,const RWZone& = RWZone::local(),
const RWLocale& = RWLocale::global()) const;
Returns self as a string, formatted by the RWLocale argument, with the
time zone adjusted according to the RWZone argument. Formats are as
defined by the standard C library function strftime().
RWBoolean
between(const RWTime& a, const RWTime& b) const;
Returns TRUE if RWTime is between a and b, inclusive.
Page 4
RWTime(3C++) RWTime(3C++)
size_t
binaryStoreSize() const;
Returns the number of bytes necessary to store the object using the
global function
RWFile& operator<<(RWFile&, const RWTime&);
int
compareTo(const RWTime* t) const;
Comparison function, useful for sorting times. Compares self to the
RWTime pointed to by t and returns:
0 if self == *t;
1 if self > *t;
-1 if self < *t;
void
extract(struct tm*,const RWZone& = RWZone::local()) const;
Fills all members of the struct tm argument, adjusted to the time zone
specified by the RWZone argument. If the time is invalid, the struct tm
members are all set to -1. Note that the encoding of struct tm members
is different from that used in RWTime and RWDate functions.
unsigned
hash() const;
Returns a suitable hashing value.
unsigned
hour(const RWZone& zone = RWZone::local()) const;
Returns the hour, adjusted to the time zone specified.
unsigned
hourGMT() const;
Returns the hour in UTC (GMT).
Page 5
RWTime(3C++) RWTime(3C++)
RWBoolean
isDST(const RWZone& zone = RWZone::local()) const;
Returns TRUE if self is during Daylight-Saving Time in the time zone
given by zone, FALSE otherwise.
RWBoolean
isValid() const;
Returns TRUE if this is a valid time, FALSE otherwise.
RWTime
max(const RWTime& t) const;
Returns the later time of self or t.
RWTime
min(const RWTime& t) const;
Returns the earlier time of self or t.
unsigned
minute(const RWZone& zone = RWZone::local()) const;
Returns the minute, adjusted to the time zone specified.
unsigned
minuteGMT() const;
Returns the minute in UTC (GMT).
unsigned
second() const;
Returns the second; local time or UTC (GMT).
unsigned long
seconds() const;
Returns the number of seconds since 00:00:00 January 1, 1901 UTC.
Page 6
RWTime(3C++) RWTime(3C++)
Static Public Member Functions
static RWTime
beginDST(unsigned year,
const RWZone& zone = RWZone::local());
Return the start of Daylight-Saving Time (DST) for the given year, in the
given time zone. Returns an "invalid time" if DST is not observed in
that year and zone.
static RWTime
endDST(unsigned year, const RWZone& = RWZone::local());
Return the end of Daylight-Saving Time for the given year, in the given
time zone. Returns an "invalid time" if DST is not observed in that year
and zone.
static unsigned
hash(const RWTime& t);
Returns the hash value of t as returned by t.hash().
static RWTimenow();
Returns the present time.
Related Global OperatorsRWTime
operator+(const RWTime& t, unsigned long s);
RWTime
operator+(unsigned long s, const RWTime& t);
Returns an RWTime s seconds greater than t.
RWTime
operator-(const RWTime& t, unsigned long s);
Returns an RWTime s seconds less than t.
RWBoolean
operator<(const RWTime& t1, const RWTime& t2);
Returns TRUE if t1 is less than t2.
Page 7
RWTime(3C++) RWTime(3C++)
RWBoolean
operator<=(const RWTime& t1, const RWTime& t2);
Returns TRUE if t1 is less than or equal to t2.
RWBoolean
operator>(const RWTime& t1, const RWTime& t2);
Returns TRUE if t1 is greater than t2.
RWBoolean
operator>=(const RWTime& t1, const RWTime& t2);
Returns TRUE if t1 is greater than or equal to t2.
RWBoolean
operator==(const RWTime& t1, const RWTime& t2);
Returns TRUE if t1 is equal to t2.
RWBoolean
operator!=(const RWTime& t1, const RWTime& t2);
Returns TRUE if t1 is not equal to t2.
ostream&
operator<<(ostream& s, const RWTime& t);
Outputs the time t on ostream s, according to the locale imbued in the
stream (see class RWLocale), or by RWLocale::global() if none.
RWvostream&
operator<<(RWvostream&, const RWTime& t);
RWFile&
operator<<(RWFile&, const RWTime& t);
Saves RWTime t to a virtual stream or RWFile, respectively.
RWvistream&
operator>>(RWvistream&, RWTime& t);
RWFile&
operator>>(RWFile&, RWTime& t);
Restores an RWTime into t from a virtual stream or RWFile, respectively,
Page 8
RWTime(3C++) RWTime(3C++)
replacing the previous contents of t.
Page 9
