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

date	the 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

date	a 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

year	an unsigned int representing the year.
month	an unsigned int representing the month.
day	an unsigned int representing the day.
hour	an unsigned int representing the hour.
minute	an unsigned int representing the minute.
second	an unsigned int representing the second.
sign	an unsigned int representing the sign of the offset (0/1 equivalent to +/-).
hoursOffset	an unsigned int representing the hoursOffset.
minutesOffset	an 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

date	Date_t structure to be freed.

const char * Date_getDateAsString ( Date_t * date )

Returns the Date_t as a string.

Parameters

date	the 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

date	the 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

date	the 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

date	the 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

date	the 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

date	the 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

date	the 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

date	the 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

date	the 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

date	the 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

date	the 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

date	the Date_t structure to be set.
str	string representing the date to set.

Returns