libSBML C API  5.18.0
•All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Public Member Functions
Date_t Class Reference
Core libSBML

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_t 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_t 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_t 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.c.

Public Member Functions

Date_t * Date_clone (const Date_t *date)
 Creates a deep copy of the given Date_t structure. More...
 
Date_t * Date_createFromString (const char *date)
 Creates a date from a string. More...
 
Date_t * Date_createFromValues (unsigned int year, unsigned int month, unsigned int day, unsigned int hour, unsigned int minute, unsigned int second, unsigned int sign, unsigned int hoursOffset, unsigned int minutesOffset)
 Creates a date optionally from the individual fields entered as numbers. More...
 
void Date_free (Date_t *date)
 Destroys this Date_t. More...
 
const char * Date_getDateAsString (Date_t *date)
 Returns the Date_t as a string. More...
 
unsigned int Date_getDay (Date_t *date)
 Returns the day from this Date_t. More...
 
unsigned int Date_getHour (Date_t *date)
 Returns the hour from this Date_t. More...
 
unsigned int Date_getHoursOffset (Date_t *date)
 Returns the hours of the offset from this Date_t. More...
 
unsigned int Date_getMinute (Date_t *date)
 Returns the minute from this Date_t. More...
 
unsigned int Date_getMinutesOffset (Date_t *date)
 Returns the minutes of the offset from this Date_t. More...
 
unsigned int Date_getMonth (Date_t *date)
 Returns the month from this Date_t. More...
 
unsigned int Date_getSecond (Date_t *date)
 Returns the seconds from this Date_t. More...
 
unsigned int Date_getSignOffset (Date_t *date)
 Returns the sign of the offset from this Date_t. More...
 
unsigned int Date_getYear (Date_t *date)
 Returns the year from this Date_t. More...
 
int Date_representsValidDate (Date_t *date)
 Returns true or false depending on whether this date structure represents a valid date and time value. More...
 
int Date_setDateAsString (Date_t *date, const char *str)
 Sets the value of the date from a string. More...
 
int Date_setDay (Date_t *date, unsigned int value)
 Sets the value of the day, checking appropriateness. More...
 
int Date_setHour (Date_t *date, unsigned int value)
 Sets the value of the hour, checking appropriateness. More...
 
int Date_setHoursOffset (Date_t *date, unsigned int value)
 Sets the value of the offset hour, checking appropriateness. More...
 
int Date_setMinute (Date_t *date, unsigned int value)
 Sets the value of the minute, checking appropriateness. More...
 
int Date_setMinutesOffset (Date_t *date, unsigned int value)
 Sets the value of the offset minutes, checking appropriateness. More...
 
int Date_setMonth (Date_t *date, unsigned int value)
 Sets the value of the month, checking appropriateness. More...
 
int Date_setSecond (Date_t *date, unsigned int value)
 Sets the value of the second, checking appropriateness. More...
 
int Date_setSignOffset (Date_t *date, unsigned int value)
 Sets the value of the offset sign, checking appropriateness. More...
 
int Date_setYear (Date_t *date, unsigned int value)
 Sets the value of the year, checking appropriateness. More...
 

Member Function Documentation

Date_t * Date_clone ( const Date_t *  date)

Creates a deep copy of the given Date_t structure.

Parameters
datethe Date_t structure to be copied.
Returns
a (deep) copy of the given Date_t structure.
Date_t * Date_createFromString ( const char *  date)

Creates a date from a string.

Parameters
datea string representing the date.
Returns
pointer to the newly created Date_t structure.
Note
the string should be in W3CDTF format YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) where TZD is the time zone designator.
Examples:
addModelHistory.c.
Date_t * Date_createFromValues ( unsigned int  year,
unsigned int  month,
unsigned int  day,
unsigned int  hour,
unsigned int  minute,
unsigned int  second,
unsigned int  sign,
unsigned int  hoursOffset,
unsigned int  minutesOffset 
)

Creates a date optionally from the individual fields entered as numbers.

Parameters
yearan unsigned int representing the year.
monthan unsigned int representing the month.
dayan unsigned int representing the day.
houran unsigned int representing the hour.
minutean unsigned int representing the minute.
secondan unsigned int representing the second.
signan unsigned int representing the sign of the offset (0/1 equivalent to +/-).
hoursOffsetan unsigned int representing the hoursOffset.
minutesOffsetan unsigned int representing the minutesOffset.
Returns
pointer to the newly created Date_t structure.
void Date_free ( Date_t *  date)

Destroys this Date_t.

Parameters
dateDate_t structure to be freed.
const char * Date_getDateAsString ( Date_t *  date)

Returns the Date_t as a string.

Parameters
datethe Date_t structure to be queried.
Returns
the date as a string.
unsigned int Date_getDay ( Date_t *  date)

Returns the day from this Date_t.

Parameters
datethe Date_t structure to be queried.
Returns
the day from this Date_t.
unsigned int Date_getHour ( Date_t *  date)

Returns the hour from this Date_t.

Parameters
datethe Date_t structure to be queried.
Returns
the hour from this Date_t.
unsigned int Date_getHoursOffset ( Date_t *  date)

Returns the hours of the offset from this Date_t.

Parameters
datethe Date_t structure to be queried.
Returns
the hours of the offset from this Date_t.
unsigned int Date_getMinute ( Date_t *  date)

Returns the minute from this Date_t.

Parameters
datethe Date_t structure to be queried.
Returns
the minute from this Date_t.
unsigned int Date_getMinutesOffset ( Date_t *  date)

Returns the minutes of the offset from this Date_t.

Parameters
datethe Date_t structure to be queried.
Returns
the minutes of the offset from this Date_t.
unsigned int Date_getMonth ( Date_t *  date)

Returns the month from this Date_t.

Parameters
datethe Date_t structure to be queried.
Returns
the month from this Date_t.
unsigned int Date_getSecond ( Date_t *  date)

Returns the seconds from this Date_t.

Parameters
datethe Date_t structure to be queried.
Returns
the seconds from this Date_t.
unsigned int Date_getSignOffset ( Date_t *  date)

Returns the sign of the offset from this Date_t.

Parameters
datethe Date_t structure to be queried.
Returns
the sign of the offset from this Date_t.
unsigned int Date_getYear ( Date_t *  date)

Returns the year from this Date_t.

Parameters
datethe Date_t structure to be queried.
Returns
the year from this Date_t.
int Date_representsValidDate ( Date_t *  date)

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

This method verifies that the date/time value stored in this structure 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.

Parameters
datethe Date_t structure to be checked.
Returns
1 (true) if the date is valid, 0 (false) otherwise.
int Date_setDateAsString ( Date_t *  date,
const char *  str 
)

Sets the value of the date from a string.

Parameters
datethe Date_t structure to be set.
strstring representing the date to set.
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 ( Date_t *  date,
unsigned int  value 
)

Sets the value of the day, checking appropriateness.

Parameters
datethe Date_t structure to be set.
valuean unsigned int representing the day to set.
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 ( Date_t *  date,
unsigned int  value 
)

Sets the value of the hour, checking appropriateness.

Parameters
datethe Date_t structure to be set.
valuean unsigned int representing the hour to set.
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 ( Date_t *  date,
unsigned int  value 
)

Sets the value of the offset hour, checking appropriateness.

Parameters
datethe Date_t structure to be set.
valuean unsigned int representing the hours of the offset to set.
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 ( Date_t *  date,
unsigned int  value 
)

Sets the value of the minute, checking appropriateness.

Parameters
datethe Date_t structure to be set.
valuean unsigned int representing the minute to set.
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 ( Date_t *  date,
unsigned int  value 
)

Sets the value of the offset minutes, checking appropriateness.

Parameters
datethe Date_t structure to be set.
valuean unsigned int representing the minutes of the offset to set.
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 ( Date_t *  date,
unsigned int  value 
)

Sets the value of the month, checking appropriateness.

Parameters
datethe Date_t structure to be set.
valuean unsigned int representing the month to set.
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 ( Date_t *  date,
unsigned int  value 
)

Sets the value of the second, checking appropriateness.

Parameters
datethe Date_t structure to be set.
valuean unsigned int representing the second to set.
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 ( Date_t *  date,
unsigned int  value 
)

Sets the value of the offset sign, checking appropriateness.

Parameters
datethe Date_t structure to be set.
valuean unsigned int representing the sign of the offset to set.
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 ( Date_t *  date,
unsigned int  value 
)

Sets the value of the year, checking appropriateness.

Parameters
datethe Date_t structure to be set.
valuean unsigned int representing the year to set.
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: