synopsis.
The string-time object, or stime_o, is a subclass of time_o. It adds string formatting capability to its parent class. You can set the format of the string, assign a time to the object as a string, and convert the time object to a string object.

Generally, it is much easier to work with stime_o over time_o. As with all components of the time group, time and date are considered to be the same thing, being generally referred to as time in this context.

The of text used to represent time and date for input parameters to this class is limited to a few common formats. The output format, to convert the stime object to a string, can be set to a variety of formats, including extra embeedded text. It works much the same was as printf() / sprintf(). Please see the 'description' section on this page for details.

description.
"stime" objects overload the comparison operators >, >=, <, <=, and == so that comparison with another stime_o instance or with strings can be easily done. The format of the text used by all string_o input parameters of the stime_o class is as follows:
The string can contain only a date, or date followed by time. Dates can be one of 2 types: (a) pure-numeric format: "mm/dd/yy" or "mm/dd/yyyy", or (b) as the month's name, followed by "dd, yyyy", ie: "September 17, 1942". Here mm = month, dd = day, yyyy or yy = year. [Unfortunately as of this writing] only American-style date format and English-language month names are supported. The [optional] time is appended to the [required] date. The syntax for the time-of-day component is " hh:mm:ss" or " hh:mm:ss?M", where '?M' is either "AM" or "PM". if the AM/PM part is omitted, the time is assumed to be based on a 24-hour ('military') clock. Usage of a 2-digit year is not recommended.
Here are some example formats (with notes):

01/17/91                -- a simple case with 2-digit year
01/17/2005              -- 4-digit year
Jan 17, 1991            -- the month can be spelled out
January 17, 1991        -- month spelled out completely
01/17/91 23:15:05       -- using a 24-hour clock; time part has 8 digits
01/17/91:11:15:05PM     -- adding an am/pm suffix
Jan 17, 1991  9:24AM
Jan 17, 1991:09:24PM    -- you can specify any (':') separator
Jan 17, 1991: 9:24      -- shortest version (5 digits)
Jan 17, 1991 9:24AM     -- here, the hours column is not fixed-width
January 17, 1991 10:01  -- 10am, unless > 12 or 'pm' spec.
11/17/2006 09:48PM      -- 4-digit year, w. time

The time format of the stime_o class, when converted to a string, is set by calling member function set_fmtstring() prior to getting its string representation. This function takes a single string_o argument that contains formatting instructions patterned after the printf() function. Characters starting with a '%' starts a control code for a time component (except "%%", which is a literal '%').
The control sequences:

%% - '%' char
%a - abbreviated day of the week (Mon, Tue, Wed, ..)
%A - full weekday name
%b - abbreviated month name (Jan, Feb, Mar, Apr, May, Jun, ..)
%B - full month name
%c - date and time
%d - day of the month (1-31)
%H - hour, [0..23]
%I - hour, [1..12]
%j - day of year, [1..366]
%m - month, as a number [1..12]
%M - minute, [0..59]
%p - am/pm
%P - AM/PM
%S - seconds [0..59]
%U - week number, [0..52]
%w - week day, [0..6]; sunday is 0
%W - week [0..52]
%x - date
%X - time
%y - 2-digit year (without the century)
%Y - 4-digit year
%Z - time zone name (NOT IMPLEMENTED)

Many of these codes can be preceded with a '0' to indicate 0-padding, and a number to indicate field width; ie, "%03H" prints 3 AM as "003". Control characters accepting these format modifications are: { d, H, j, m, M, S, U, W }.

member functions (primary)

stime_o()
SIGNATURE: stime_o ()
SYNOPSIS: Creates an empty instance of the string-time class. The object's time is not set.
 

destructor
SIGNATURE: ~stime_o ()
SYNOPSIS: virtual destructor. The instance, including its settings, is reset.
 

operator = (stime_o)
SIGNATURE: stime_o &operator = (const stime_o &rhs)
SYNOPSIS: copies exactly the [Right-Hand-Side] object "rhs". the object's time is set to exactly that of "rhs".
 

stime_o(stime_o)
SIGNATURE: stime_o (const stime_o &rhs)
SYNOPSIS: creates a a new stime object; the time is exact image of the copied object, "rhs".
 

stime_o(<args>)
SIGNATURE: stime_o (int month, int day, int year)
SYNOPSIS:
constructor: the object's date will be set to the month, day, and year as given by the input arguments with the same name. If any of the input parameters are invalid (eg, negative or out of range), the time-date will not be set.
PARAMETERS

• month: the month part of the date to set the time to. must be in the range [1..12]. Use 1 for the first month (January).
• day: the day to set the time-date object to. Use 1 for the first day, eg "stime_o s(6, 1, 2010);" will create an stime object set to June 1st of 2010.
• year: The year to set the object to. The value is the same as the value based on the Gregorian calendar. Use the full number, eg, "2012" not "12" for the year 2012.

 

stime_o(<args>)
SIGNATURE: stime_o &operator = (const time_o &rhs)
SYNOPSIS:
the time is set to that of "rhs". if the copied object's time is not set, the current object's time will likewise be not set.
 

stime_o(<args>)
SIGNATURE: stime_o (const string_o &s)
SYNOPSIS:
instantiates a new stime object. The object's time is set to the time based on the contents of input parameter "s". See the description section for valid text formats.
 

stime_o(stime_o)
SIGNATURE: stime_o &operator = (const string_o &s)
SYNOPSIS:
assignement operator: sets the object's time to that of "s". see the copy constructor (above) for valid formats of input parameter "s".
 

"equals" operator()
SIGNATURE: int operator == (const char *buf) const
SYNOPSIS: compares the object to the time represented by character array "buf". returns 1 if they are exactly the same
PARAMETERS

buf: a character buffer containing a time.

RETURNS:
1: the object's time matches that of 'buf'
0: the object's time is different from that of 'buf'
 

"<=" operator()
SIGNATURE: int operator <= (const char *buf) const
SYNOPSIS: compares the object to the time represented by character array "buf". returns 1 if object time is before that of 'buf'.
PARAMETERS

buf: a character buffer containing a time.

RETURNS:
1: the object's time is before or equal to that of 'buf'
0: the object's time is after that of 'buf'
 

">=" operator()
SIGNATURE: int operator >= (const char *buf) const
SYNOPSIS:
compares the object to the time represented by character array "buf". returns 1 if object time is on or after that of 'buf'.
PARAMETERS

buf: a character buffer containing a time.

RETURNS:
1: the object's time is after or equal to that of 'buf'
0: the object's time is before that of 'buf'
 

"less-than" operator()
SIGNATURE: int operator < (const char *buf) const
SYNOPSIS:
compares the object to the time represented by character array "buf". returns 1 if object time is before that of 'buf'.
RETURNS:
1: the object's time is before that of 'buf'
0: the object's time is on or after that of 'buf'
 

"greater-than" operator()
SIGNATURE: int operator > (const char *buf) const
SYNOPSIS:
compares the object to the time represented by character array "buf". returns 1 if object time is after that of 'buf'.
RETURNS:
1: the object's time is after that of 'buf'
0: the object's time is on or before that of 'buf'
 

"equals" operator()
SIGNATURE: int operator == (const string_o &s) const
SYNOPSIS:
compares the object to the time represented by string ss". Returns 1 if they are exactly the same. This function is analogous to the member function with parameter signiture "const char *".
PARAMETERS

s: string object, containing a time.

 

"<=" operator()
SIGNATURE: int operator <= (const string_o &s) const
SYNOPSIS:
compares the object to the time represented by string object "s". returns 1 if object time is before that of 's'. This function is analogous to the member function with parameter signiture "const char *".
PARAMETERS

s: a string object containing a time.

RETURNS:
1: the object's time is before or equal to that of 's'
0: the object's time is after that of 's'
 

">=" operator()
SIGNATURE: int operator >= (const string_o &s) const
SYNOPSIS:
compares the object to the time represented by string object "s". returns 1 if object time is on or after that of 's'. This function is analogous to the member function with parameter signiture "const char *".
PARAMETERS

s: a string object containing a time.

RETURNS:
1: the object's time is after or equal to that of 's'
0: the object's time is before that of 's'
 

"less-than" operator()
SIGNATURE: int operator < (const string_o &s) const
SYNOPSIS:
compares the object to the time represented by string "s". returns 1 if object time is before that of 's'. This function is analogous to the member function with parameter signiture "const char *".
RETURNS:
1: the object's time is before that of 's'
0: the object's time is on or after that of 's'
 

"greater-than" operator()
SIGNATURE: int operator > (const string_o &s) const
SYNOPSIS:
compares the object to the time represented string 's'. returns 1 if object time is after that of 's'. This function is analogous to the member function with parameter signiture "const char *".
RETURNS:
1: the object's time is after that of 's'
0: the object's time is on or before that of 's'
 

"equals" operator()
SIGNATURE: int operator == (const stime_o &rhs) const
SYNOPSIS:
compares the object to the time represented by "rhs". Returns 1 if they are exactly the same. This function is analogous to the member function with parameter signiture "const char *" or "const string_o &".
PARAMETERS

rhs: an stime_o instance

 

"<=" operator()
SIGNATURE: int operator <= (const stime_o &rhs) const
SYNOPSIS:
compares the object to the time represented by stime object "rhs". returns 1 if object time is before that of 'rhs'. This function is analogous to the member function with parameter signiture "const char *" or "const string_o &".
PARAMETERS

rhs: an stime_o instance

RETURNS:
1: the object's time is before or equal to that of 'rhs'
0: the object's time is after that of 'rhs'
 

">=" operator()
SIGNATURE: int operator >= (const stime_o &rhs) const
SYNOPSIS:
compares the object to the time represented by stime object "rhs". returns 1 if object time is on or after that of 'rhs'. This function is analogous to the member function with parameter signiture "const char *" or "const string_o &".
PARAMETERS

rhs: a stime object containing a time.

RETURNS:
1: the object's time is after or equal to that of 'rhs'
0: the object's time is before that of 'rhs'
 

"less-than" operator()
SIGNATURE: int operator < (const stime_o &rhs) const
SYNOPSIS:
compares the object to the time of "rhs". returns 1 if object time is before that of 'rhs'. This function is analogous to the member function with parameter signiture "const char *" or "const string_o &".
RETURNS:
1: the object's time is before that of 'rhs'
0: the object's time is on or after that of 'rhs'
 

"greater-than" operator()
SIGNATURE: int operator > (const stime_o &rhs) const
SYNOPSIS:
compares the object to the time found in 'rhs'. array "rhs". returns 1 if object time is after that This function is analogous to the member function with parameter signiture "const char *" or "const string_o &".
RETURNS:
1: the object's time is after that of 'rhs'.
0: the object's time is on or before that of 'rhs'.
 

string object conversion operator()
SIGNATURE: operator string_o () const
SYNOPSIS:
provides for automatic conversion from stime_o to string_o. example:

    string_o s;
    stime_o t ("November 18, 1960");k
    t.set_fmtstring ("%02m/%02d/%y");
    s = t;          // 's' contains "11/18/60"

RETURNS: a string object, containing the time of the current object.
 

print()
SIGNATURE: string_o print () const
SYNOPSIS:
returns the time, as a string_o instance. The contents of the return variable is the time, formatted according to the object's current format settings. This function is provided where automatic string object conversion may be problematic.
 

get()
SIGNATURE: int get (string_o &s) const
SYNOPSIS:
sets the contents of "s" to the string representation of the object's time. This is yet another way to get the time as a string object.
PARAMETERS

s: output parameter. Any prior contents will be overwritten.

RETURNS:
0: success
-1: error occured (this is unusual).
 

str_is_valid_date()
SIGNATURE: boolean str_is_valid_date (const string_o &s)
SYNOPSIS: tests the string object "s" to see if it contains a valid, acceptable time (& date).
RETURNS:
TRUE: 's' time is acceptable
FALSE: 's' time is unacceptable
 

fmtstring()
SIGNATURE: string_o fmtstring () const
SYNOPSIS: returns the object's "time format string" (as a string object)
RETURNS: string_o [automatic] variable
 

set_fmtstring()
SIGNATURE: int set_fmtstring (const string_o &sfmt)
SYNOPSIS: assigns the object's internal format string.
PARAMETERS

sfmt: a string containing the format for the time to use.

RETURNS:
0: success; object format string set to that of 'sfmt'.
-1: input varialbe "sfmt" contains an invalid value, or error ocurred
 

ostream operator()
SIGNATURE: std::ostream &operator << (std::ostream &myostr, const stime_o &t)
SYNOPSIS: dumps the value of 't' to ostream 'myostr'. This will basically print out the value of 't'.