libSBML C++ API  5.18.0
Date Class Reference

Detailed Description

A MIRIAM-compliant date representation.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

A Date object stores a reasonably complete representation of date and time. Its purpose is to serve as a way to store dates to be read and written in the W3C date format used in RDF Dublin Core annotations within SBML. The W3C date format is a restricted form of ISO 8601, the international standard for the representation of dates and times. A time and date value in this W3C format takes the form YYYY-MM-DDThh:mm:ssXHH:ZZ (e.g., 1997-07-16T19:20:30+01:00) where XHH:ZZ is the time zone offset. The libSBML Date object contains the following fields to represent these values:

  • year: an unsigned int representing the year. This should be a four-digit number such as 2011.
  • month: an unsigned int representing the month, with a range of values of 1–12. The value 1 represents January, and so on.
  • day: an unsigned int representing the day of the month, with a range of values of 1–31.
  • hour: an unsigned int representing the hour on a 24-hour clock, with a range of values of 0–23.
  • minute: an unsigned int representing the minute, with a range of 0–59.
  • second: an unsigned int representing the second, with a range of 0–59.
  • sign: an unsigned int representing the sign of the offset (0 signifying + and 1 signifying -). See the paragraph below for further explanations.
  • hours offset: an unsigned int representing the time zone's hour offset from GMT, with a range of 0–12.
  • minute offset: an unsigned int representing the time zone's minute offset from GMT, with a range of 0–59.

To illustrate the time zone offset, a value of -05:00 would correspond to USA Eastern Standard Time. In the Date object, this would require a value of 1 for the sign field, 5 for the hour offset and 0 for the minutes offset.

In the restricted RDF annotations used in SBML, described in Section 6 of the SBML Level 2 and Level 3 specification documents, date/time stamps can be used to indicate the time of creation and modification of a model. The following SBML model fragment illustrates this:

<model metaid="_180340" id="GMO" name="Goldbeter1991_MinMitOscil">
    <annotation>
        <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
                 xmlns:dc="http://purl.org/dc/elements/1.1/"
                 xmlns:dcterms="http://purl.org/dc/terms/"
                 xmlns:vCard="http://www.w3.org/2001/vcard-rdf/3.0#" >
            <rdf:Description rdf:about="#_180340">
                <dc:creator>
                    <rdf:Bag>
                        <rdf:li rdf:parseType="Resource">
                            <vCard:N rdf:parseType="Resource">
                                <vCard:Family>Shapiro</vCard:Family>
                                <vCard:Given>Bruce</vCard:Given>
                            </vCard:N>
                            <vCard:EMAIL>bshapiro@jpl.nasa.gov</vCard:EMAIL>
                            <vCard:ORG rdf:parseType="Resource">
                                <vCard:Orgname>NASA Jet Propulsion Laboratory</vCard:Orgname>
                            </vCard:ORG>
                        </rdf:li>
                    </rdf:Bag>
                </dc:creator>
                <dcterms:created rdf:parseType="Resource">
                    <dcterms:W3CDTF>2005-02-06T23:39:40+00:00</dcterms:W3CDTF>
                </dcterms:created>
                <dcterms:modified rdf:parseType="Resource">
                    <dcterms:W3CDTF>2005-09-13T13:24:56+00:00</dcterms:W3CDTF>
                </dcterms:modified>
            </rdf:Description>
        </rdf:RDF>
    </annotation>
</model>
Examples:
addModelHistory.cpp.

Public Member Functions

Dateclone () const
 Creates and returns a deep copy of this Date object. More...
 
 Date (unsigned int year=2000, unsigned int month=1, unsigned int day=1, unsigned int hour=0, unsigned int minute=0, unsigned int second=0, unsigned int sign=0, unsigned int hoursOffset=0, unsigned int minutesOffset=0)
 Creates a time and date representation for use in model annotations and elsewhere. More...
 
 Date (const std::string &date)
 Creates a Date object from a string expressing a date and time value. More...
 
 Date (const Date &orig)
 Copy constructor; creates a copy of this Date. More...
 
const std::string & getDateAsString ()
 Returns the current Date value in text-string form. More...
 
unsigned int getDay ()
 Returns the day from this Date. More...
 
unsigned int getHour ()
 Returns the hour from this Date. More...
 
unsigned int getHoursOffset ()
 Returns the hours of the time zone offset from this Date. More...
 
unsigned int getMinute ()
 Returns the minute from this Date. More...
 
unsigned int getMinutesOffset ()
 Returns the minutes of the time zone offset from this Date. More...
 
unsigned int getMonth ()
 Returns the month from this Date. More...
 
unsigned int getSecond ()
 Returns the seconds from this Date. More...
 
unsigned int getSignOffset ()
 Returns the sign of the time zone offset from this Date. More...
 
unsigned int getYear ()
 Returns the year from this Date. More...
 
Dateoperator= (const Date &rhs)
 Assignment operator. More...
 
bool representsValidDate ()
 Returns true or false depending on whether this date object represents a valid date and time value. More...
 
int setDateAsString (const std::string &date)
 Sets the value of this Date object using a date and time value expressed as a text string. More...
 
int setDay (unsigned int day)
 Sets the value of the day of this Date object. More...
 
int setHour (unsigned int hour)
 Sets the value of the hour of this Date object. More...
 
int setHoursOffset (unsigned int hoursOffset)
 Sets the value of this Date object's time zone hour offset. More...
 
int setMinute (unsigned int minute)
 Sets the value of the minute of this Date object. More...
 
int setMinutesOffset (unsigned int minutesOffset)
 Sets the value of this Date object's time zone minutes offset. More...
 
int setMonth (unsigned int month)
 Sets the value of the month of this Date object. More...
 
int setSecond (unsigned int second)
 Sets the value of the second of the Date object. More...
 
int setSignOffset (unsigned int sign)
 Sets the value of the sign of the time zone offset of this Date object. More...
 
int setYear (unsigned int year)
 Sets the value of the year of this Date object. More...
 
 ~Date ()
 Destroys this Date. More...
 

Constructor & Destructor Documentation

Date::Date ( unsigned int  year = 2000,
unsigned int  month = 1,
unsigned int  day = 1,
unsigned int  hour = 0,
unsigned int  minute = 0,
unsigned int  second = 0,
unsigned int  sign = 0,
unsigned int  hoursOffset = 0,
unsigned int  minutesOffset = 0 
)

Creates a time and date representation for use in model annotations and elsewhere.

The following is the complete set of possible arguments to this constructor, with default values as indicated:

Parameters
yearan unsigned integer representing the year. This should be a four-digit number such as 2011. (Default value used if this argument is not given: 2000.)
monthan unsigned integer representing the month, with a range of values of 1–12. The value 1 represents January, and so on. (Default value used if this argument is not given: 1.)
dayan unsigned integer representing the day of the month, with a range of values of 1–31. (Default value used if this argument is not given: 1.)
houran unsigned integer representing the hour on a 24-hour clock, with a range of values of 0–23. (Default value used if this argument is not given: 0.)
minutean unsigned integer representing the minute, with a range of 0–59. (Default value used if this argument is not given: 0.)
secondan unsigned integer representing the second, with a range of 0–59. (Default value used if this argument is not given: 0.)
signan unsigned integer representing the sign of the offset (0 signifying + and 1 signifying -). See the paragraph below for further explanations. (Default value used if this argument is not given: 0.)
hoursOffsetan unsigned integer representing the time zone's hour offset from GMT. (Default value used if this argument is not given: 0.)
minutesOffsetan unsigned integer representing the time zone's minute offset from GMT. (Default value used if this argument is not given: 0.)

To illustrate the time zone offset, a value of -05:00 would correspond to USA Eastern Standard Time. In the Date object, this would require a value of 1 for the sign field, 5 for the hour offset and 0 for the minutes offset.

Date::Date ( const std::string &  date)

Creates a Date object from a string expressing a date and time value.

This constructor expects its argument to be in the W3C date format with time zone offset, used in RDF Dublin Core annotations within SBML.

The date format expresses a date and time value as a string of the form YYYY-MM-DDThh:mm:ssXHH:ZZ, where
  • YYYY is a four-digit integer representing the year. This should be a four-digit number such as 2011.
  • MM is a two-digit integer representing the month, with a range of values of 01–12. The value 1 represents January, and so on.
  • DD is a two-digit integer representing the day of the month, with a range of values of 01–31.
  • T is the literal character T.
  • hh is a two-digit integer representing the hour on a 24-hour clock, with a range of values of 00–23.
  • mm is a two-digit integer representing the minute, with a range of 00–59.
  • ss is a two-digit integer representing the second, with a range of 0–59.
  • X is the the sign of the time zone offset, either + or -.
  • HH is a two-digit integer representing the hour of the time zone offset, with a range of 00–23.
  • ZZ is a two-digit integer representing the minutes of the time zone offset, with a range of 00–59.

In the string format above, it is important not to forget the literal character T in the string. Here is an example date/time string: 1997-07-16T19:20:30+01:00, which would represent July 16, 1997, at 19:20:30 in Central European Time (which is UTC +1:00).

If this constructor is given a NULL argument or a string of length zero, it constructs a Date object with the value of January 1, 2000, at time 00:00 UTC. Otherwise, the argument must be in the complete format described above, or unpredictable results will happen.

Parameters
datea string representing the date.
Date::~Date ( )

Destroys this Date.

Date::Date ( const Date orig)

Copy constructor; creates a copy of this Date.

Parameters
origthe object to copy.

Member Function Documentation

Date * Date::clone ( ) const

Creates and returns a deep copy of this Date object.

Returns
the (deep) copy of this Date object.
const std::string& Date::getDateAsString ( )
inline

Returns the current Date value in text-string form.

The string returned will be in the W3C date format with time zone offset, used in RDF Dublin Core annotations within SBML.

The date format expresses a date and time value as a string of the form YYYY-MM-DDThh:mm:ssXHH:ZZ, where
  • YYYY is a four-digit integer representing the year. This should be a four-digit number such as 2011.
  • MM is a two-digit integer representing the month, with a range of values of 01–12. The value 1 represents January, and so on.
  • DD is a two-digit integer representing the day of the month, with a range of values of 01–31.
  • T is the literal character T.
  • hh is a two-digit integer representing the hour on a 24-hour clock, with a range of values of 00–23.
  • mm is a two-digit integer representing the minute, with a range of 00–59.
  • ss is a two-digit integer representing the second, with a range of 0–59.
  • X is the the sign of the time zone offset, either + or -.
  • HH is a two-digit integer representing the hour of the time zone offset, with a range of 00–23.
  • ZZ is a two-digit integer representing the minutes of the time zone offset, with a range of 00–59.

In the string format above, it is important not to forget the literal character T in the string. Here is an example date/time string: 1997-07-16T19:20:30+01:00, which would represent July 16, 1997, at 19:20:30 in Central European Time (which is UTC +1:00).

Returns
the date as a string.
unsigned int Date::getDay ( )
inline

Returns the day from this Date.

Returns
the day from this Date.
unsigned int Date::getHour ( )
inline

Returns the hour from this Date.

Returns
the hour from this Date.
unsigned int Date::getHoursOffset ( )
inline

Returns the hours of the time zone offset from this Date.

Returns
the hours of the offset from this Date.
unsigned int Date::getMinute ( )
inline

Returns the minute from this Date.

Returns
the minute from this Date.
unsigned int Date::getMinutesOffset ( )
inline

Returns the minutes of the time zone offset from this Date.

Returns
the minutes of the offset from this Date.
unsigned int Date::getMonth ( )
inline

Returns the month from this Date.

Returns
the month from this Date.
unsigned int Date::getSecond ( )
inline

Returns the seconds from this Date.

Returns
the seconds from this Date.
unsigned int Date::getSignOffset ( )
inline

Returns the sign of the time zone offset from this Date.

Returns
the sign of the offset from this Date.
unsigned int Date::getYear ( )
inline

Returns the year from this Date.

Returns
the year from this Date.
Date & Date::operator= ( const Date rhs)

Assignment operator.

Parameters
rhsthe object whose values are used as the basis of the assignment.
bool Date::representsValidDate ( )

Returns true or false depending on whether this date object represents a valid date and time value.

This method verifies that the date/time value stored in this object is well-formed and represents plausible values. A time and date value in the W3C format takes the form YYYY-MM-DDThh:mm:ssXHH:ZZ (e.g., 1997-07-16T19:20:30+01:00) where XHH:ZZ is the time zone offset. This method checks such things as whether the value of the month number is less than or equal to 12, whether the value of the minutes number is less than or equal to 59, whether a time zone offset is set, etc.

Returns
true if the date is valid, false otherwise.
int Date::setDateAsString ( const std::string &  date)

Sets the value of this Date object using a date and time value expressed as a text string.

This method expects its argument to be in the W3C date format with time zone offset, used in RDF Dublin Core annotations within SBML.

The date format expresses a date and time value as a string of the form YYYY-MM-DDThh:mm:ssXHH:ZZ, where
  • YYYY is a four-digit integer representing the year. This should be a four-digit number such as 2011.
  • MM is a two-digit integer representing the month, with a range of values of 01–12. The value 1 represents January, and so on.
  • DD is a two-digit integer representing the day of the month, with a range of values of 01–31.
  • T is the literal character T.
  • hh is a two-digit integer representing the hour on a 24-hour clock, with a range of values of 00–23.
  • mm is a two-digit integer representing the minute, with a range of 00–59.
  • ss is a two-digit integer representing the second, with a range of 0–59.
  • X is the the sign of the time zone offset, either + or -.
  • HH is a two-digit integer representing the hour of the time zone offset, with a range of 00–23.
  • ZZ is a two-digit integer representing the minutes of the time zone offset, with a range of 00–59.

In the string format above, it is important not to forget the literal character T in the string. Here is an example date/time string: 1997-07-16T19:20:30+01:00, which would represent July 16, 1997, at 19:20:30 in Central European Time (which is UTC +1:00).

If this method is given a NULL argument or a string of length zero, it constructs a Date object with the value of January 1, 2000, at time 00:00 UTC. Otherwise, the argument must be in the complete format described above, or unpredictable results will happen.

Parameters
datea string representing the date.
Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:
int Date::setDay ( unsigned int  day)

Sets the value of the day of this Date object.

Parameters
dayan unsigned int representing the day; it must be in the range 0–31 or an error will be signaled.
Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:
int Date::setHour ( unsigned int  hour)

Sets the value of the hour of this Date object.

Parameters
houran unsigned int representing the hour to set; it must be in the range 0–23 or an error will be signaled.
Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:
int Date::setHoursOffset ( unsigned int  hoursOffset)

Sets the value of this Date object's time zone hour offset.

Parameters
hoursOffsetan unsigned int representing the hours of the offset; it must be in the range 0–12 or an error will be signaled.
Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:
int Date::setMinute ( unsigned int  minute)

Sets the value of the minute of this Date object.

Parameters
minutean unsigned int representing the minute to set; it must be in the range 0–59 or an error will be signaled.
Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:
int Date::setMinutesOffset ( unsigned int  minutesOffset)

Sets the value of this Date object's time zone minutes offset.

Parameters
minutesOffsetan unsigned int representing the minutes of the offset; it must be in the range 0–59 or an error will be signaled.
Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:
int Date::setMonth ( unsigned int  month)

Sets the value of the month of this Date object.

Parameters
monthan unsigned int representing the month; it must be in the range 1–12 or an error will be signaled.
Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:
int Date::setSecond ( unsigned int  second)

Sets the value of the second of the Date object.

Parameters
secondan unsigned int representing the seconds; it must be in the range 0–59 or an error will be signaled.
Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:
int Date::setSignOffset ( unsigned int  sign)

Sets the value of the sign of the time zone offset of this Date object.

The only permissible values are 0 and 1.

Parameters
signan unsigned int representing the sign of the offset, with 0 signifying + and 1 signifying -.
Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:
int Date::setYear ( unsigned int  year)

Sets the value of the year of this Date object.

The value given as argument must be between 1000 and 9999 inclusive. (In the millennium during which this libSBML documentation is being written, a typical value is 2011, but we hope that SBML will continue to be used for a long time.)

Parameters
yearan unsigned int representing the year.
Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are: