Header file for date and time functions. More...

This graph shows which files directly or indirectly include this file:

Macros
#define	Y_M_D 0
	Date format: year, month, day.

#define	M_D_Y 1
	Date format: month, day, year.

#define	D_M_Y 2
	Date format: day, month, year.

#define	NO_DATE -693594
	No date value.

#define	DATE_STR_SIZE 12
	Size of a date string.

#define	TIME_STR_SIZE 9
	Size of a time string.

#define	TIME_STAMP_SIZE 21
	Size of a time stamp string.

Typedefs
typedef double	DateTime
	Type for storing date and time values.

Functions
DateTime	datetime_encodeDate (int year, int month, int day)
	Encodes a date values from year, month, and day to a DateTime value.

DateTime	datetime_encodeTime (int hour, int minute, int second)
	Encodes a time value from hour, minute, and second to a DateTime value.

void	datetime_decodeDate (DateTime date, int year, int month, int *day)
	Decodes a DateTime value to year, month, and day.

void	datetime_decodeTime (DateTime time, int h, int m, int *s)
	Decodes a DateTime value to hour, minute, and second.

int	datetime_monthOfYear (DateTime date)
	Finds the month of the year for a date.

int	datetime_dayOfYear (DateTime date)
	Finds the day of the year for a date.

int	datetime_dayOfWeek (DateTime date)
	Finds the day of the week for a date.

int	datetime_hourOfDay (DateTime date)
	Finds the hour of the day for a time.

int	datetime_daysPerMonth (int year, int month)
	Finds the number of days in a month.

void	datetime_dateToStr (DateTime date, char *s)
	Converts a DateTime value to a string.

void	datetime_timeToStr (DateTime time, char *s)
	Converts a DateTime value to a string.

void	datetime_getTimeStamp (int fmt, DateTime aDate, int stampSize, char *timeStamp)
	Format a calendar date and whole-second clock time in caller storage.

int	datetime_findMonth (char *month)
	Finds the month of the year for a date.

int	datetime_strToDate (char s, DateTime d)
	Converts a string to a DateTime value.

int	datetime_strToTime (char s, DateTime t)
	Converts a string to a DateTime value.

void	datetime_setDateFormat (int fmt)
	Sets the date format.

DateTime	datetime_addSeconds (DateTime date1, double seconds)
	Adds seconds to a DateTime value.

DateTime	datetime_addDays (DateTime date1, DateTime date2)
	Adds days to a DateTime value.

long	datetime_timeDiff (DateTime date1, DateTime date2)
	Finds the difference in seconds between two DateTime values.

Detailed Description

Header file for date and time functions.

Author: L. Rossman

Date: Created: 2021-11-01; Last updated: 2024-12-30

Version: 5.3.0

The DateTime type is used to store date and time values. It is equivalent to a double floating point type.

The integral part of a DateTime value is the number of days that have passed since 12/31/1899. The fractional part of a DateTime value is the fraction of a 24 hour day that has elapsed.

Update History

Build 5.1.011:

New getTimeStamp function added.

Author: Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com (OpenSWMM maintenance and extensions)

Copyright: Copyright (c) 2026 Caleb Buahin. OpenSWMM contributions only; original EPA SWMM credits are retained.

License: Apache-2.0 for OpenSWMM contributions; original EPA SWMM provenance is retained.

Macro Definition Documentation

◆ D_M_Y

#define D_M_Y 2

Date format: day, month, year.

◆ DATE_STR_SIZE

#define DATE_STR_SIZE 12

Size of a date string.

◆ M_D_Y

#define M_D_Y 1

Date format: month, day, year.

◆ NO_DATE

#define NO_DATE -693594

No date value.

◆ TIME_STAMP_SIZE

#define TIME_STAMP_SIZE 21

Size of a time stamp string.

◆ TIME_STR_SIZE

#define TIME_STR_SIZE 9

Size of a time string.

◆ Y_M_D

#define Y_M_D 0

Date format: year, month, day.

Typedef Documentation

◆ DateTime

typedef double DateTime

Type for storing date and time values.

Function Documentation

◆ datetime_addDays()

DateTime datetime_addDays	(	DateTime	date1,
		DateTime	date2 )

Adds days to a DateTime value.

Parameters

[in]	date1	Date value
[in]	date2	Number of days to add

Returns: New DateTime value

Adds days to a DateTime value.

Implementation arguments

date1 (in): Finite SWMM calendar date/time in days.
date2 (in): Finite signed elapsed-day offset; floor supplies the integer part and datetime_decodeTime() rounds its positive day fraction.

Returns: Sum of integer-day parts and encoded component seconds.

Note: This preserves legacy decompose/recompose rounding rather than performing a direct floating-point addition.

Here is the call graph for this function:

◆ datetime_addSeconds()

DateTime datetime_addSeconds	(	DateTime	date1,
		double	seconds )

Adds seconds to a DateTime value.

Parameters

[in]	date1	Date value
[in]	seconds	Number of seconds to add

Returns: New DateTime value

Adds seconds to a DateTime value.

Implementation arguments

date1 (in): Finite SWMM calendar days since 1899-12-30.
seconds (in): Finite signed or fractional seconds to add.

Returns: Recombined SWMM days; offsets can cross day boundaries. Subsecond precision already in date1 is discarded by datetime_decodeTime().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ datetime_dateToStr()

void datetime_dateToStr	(	DateTime	date,
		char *	s )

Converts a DateTime value to a string.

Parameters

[in]	date	Date value
[out]	s	String to store the date

Converts a DateTime value to a string.

Implementation arguments

date (in): Finite SWMM days satisfying datetime_decodeDate()'s integer limits.
s (out): Non-null caller-owned buffer of at least DATE_STR_SIZE bytes; receives a null-terminated date string, possibly truncated to fit.

Note: Reads the shared format without modifying it; no storage is retained.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ datetime_dayOfWeek()

int datetime_dayOfWeek ( DateTime date )

Finds the day of the week for a date.

Parameters

[in] date Date value

Returns: Day of week (0 = Sunday, 1 = Monday, ..., 6 = Saturday)

Finds the day of the week for a date.

Implementation arguments

date (in): Finite SWMM calendar days for a date in [0001-01-01, 9999-12-31].

Returns: Sunday = 1 through Saturday = 7 for supported Gregorian dates.

Note: Uses legacy floor/whole-second decoding conventions; no state is changed.

Here is the caller graph for this function:

◆ datetime_dayOfYear()

int datetime_dayOfYear ( DateTime date )

Finds the day of the year for a date.

Parameters

[in] date Date value

Returns: Day of year

Finds the day of the year for a date.

Implementation arguments

date (in): Finite SWMM calendar days for a date in [0001-01-01, 9999-12-31].

Returns: One-based day in [1, 365] or [1, 366] for leap years.

Note: Uses legacy floor/whole-second decoding conventions; no state is changed.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ datetime_daysPerMonth()

int datetime_daysPerMonth	(	int	year,
		int	month )

Finds the number of days in a month.

Parameters

[in]	year	Year
[in]	month	Month

Returns: Number of days in the month

Finds the number of days in a month.

Implementation arguments

year (in): Calendar year to classify for leap-year behavior.
month (in): One-based month in [1, 12].

Returns: Month length in days, or zero for an out-of-range month.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ datetime_decodeDate()

void datetime_decodeDate	(	DateTime	date,
		int *	year,
		int *	month,
		int *	day )

Decodes a DateTime value to year, month, and day.

Parameters

[in]	date	Date value
[out]	year	Year
[out]	month	Month
[out]	day	Day

Decodes a DateTime value to year, month, and day.

Implementation arguments

date (in): Finite SWMM calendar days; floor(date) is used, including for negative values. Its conversion and sum with DateDelta must fit in int.
year (out): Non-null caller-owned year slot.
month (out): Non-null caller-owned month slot in [1, 12].
day (out): Non-null caller-owned day-of-month slot in [1, 31].

Note: Dates before 0001-01-01 decode as year zero, month one, day one. All three output slots must be distinct and are not retained.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ datetime_decodeTime()

void datetime_decodeTime	(	DateTime	time,
		int *	h,
		int *	m,
		int *	s )

Decodes a DateTime value to hour, minute, and second.

Parameters

[in]	time	Time value
[out]	h	Hour
[out]	m	Minute
[out]	s	Second

Decodes a DateTime value to hour, minute, and second.

Implementation arguments

time (in): Finite SWMM days; only time - floor(time) is used.
h (out): Non-null distinct caller-owned hour slot in [0, 23].
m (out): Non-null distinct caller-owned minute slot in [0, 59].
s (out): Non-null distinct caller-owned second slot in [0, 59].

Note: Rounds with floor(fraction * 86400 + 0.5); a result reaching 86400 is clamped to 86399 rather than carried into the next date.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ datetime_encodeDate()

DateTime datetime_encodeDate	(	int	year,
		int	month,
		int	day )

Encodes a date values from year, month, and day to a DateTime value.

Parameters

[in]	year	Year
[in]	month	Month
[in]	day	Day

Returns: DateTime value

Encodes a date values from year, month, and day to a DateTime value.

Implementation arguments

year (in): Gregorian year in [1, 9999].
month (in): One-based month in [1, 12].
day (in): Valid one-based day for the month and leap year.

Returns: Integer-valued days since 1899-12-30; -DateDelta for invalid components.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ datetime_encodeTime()

DateTime datetime_encodeTime	(	int	hour,
		int	minute,
		int	second )

Encodes a time value from hour, minute, and second to a DateTime value.

Parameters

[in]	hour	Hour
[in]	minute	Minute
[in]	second	Second

Returns: DateTime value

Encodes a time value from hour, minute, and second to a DateTime value.

Implementation arguments

hour (in): Nonnegative hours; values above 23 are accepted.
minute (in): Nonnegative minutes; values above 59 are accepted.
second (in): Nonnegative seconds; values above 59 are accepted.

Returns: Total component seconds divided by 86400, or zero if a component is negative. The result may be one day or greater.

Precondition: The total component seconds are representable as int.

Here is the caller graph for this function:

◆ datetime_findMonth()

int datetime_findMonth ( char * month )

Finds the month of the year for a date.

Parameters

[in] month String date

Returns: Month of year

Finds the month of the year for a date.

Implementation arguments

month (in): Borrowed character storage with at least three readable characters; matching is ASCII case-insensitive and later text is ignored.

Returns: Month number 1..12, or zero when no three-letter name matches.

Here is the caller graph for this function:

◆ datetime_getTimeStamp()

void datetime_getTimeStamp	(	int	fmt,
		DateTime	aDate,
		int	stampSize,
		char *	timeStamp )

Format a calendar date and whole-second clock time in caller storage.

Parameters

[in]	fmt	Date format code accepted by datetime_setDateFormat().
[in]	aDate	SWMM calendar days relative to 1899-12-30.
[in]	stampSize	Writable byte capacity; below TIME_STAMP_SIZE leaves the buffer untouched.
[out]	timeStamp	Caller-owned buffer with stampSize writable bytes when formatting occurs.

Note: Temporarily selects and restores the global DateFormat. Output is null-terminated and storage is not retained; shared formatting is not thread-safe.

Format a calendar date and whole-second clock time in caller storage.

Implementation arguments

fmt (in): Date-format code accepted by datetime_setDateFormat().
aDate (in): SWMM DateTime in days relative to 1899-12-30.
stampSize (in): Writable capacity in bytes; values below TIME_STAMP_SIZE leave the destination unchanged.
timeStamp (out): Non-null caller-owned character buffer of stampSize bytes when formatting occurs; receives a null-terminated date/time string.

Note: Temporarily changes and then restores the global DateFormat. The shared date formatter is not safe for concurrent calls without coordination.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ datetime_hourOfDay()

int datetime_hourOfDay ( DateTime date )

Finds the hour of the day for a time.

Parameters

[in] date Time value

Returns: Hour of day

Finds the hour of the day for a time.

Implementation arguments

date (in): Finite SWMM calendar days for a date in [0001-01-01, 9999-12-31].

Returns: Whole-second decoded hour in [0, 23].

Note: Uses legacy floor/whole-second decoding conventions; no state is changed.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ datetime_monthOfYear()

int datetime_monthOfYear ( DateTime date )

Finds the month of the year for a date.

Parameters

[in] date Date value

Returns: Month of year

Finds the month of the year for a date.

Implementation arguments

date (in): Finite SWMM calendar days for a date in [0001-01-01, 9999-12-31].

Returns: One-based Gregorian month in [1, 12].

Note: Uses legacy floor/whole-second decoding conventions; no state is changed.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ datetime_setDateFormat()

void datetime_setDateFormat ( int fmt )

Sets the date format.

Parameters

[in] fmt Date format

Sets the date format.

Implementation arguments

fmt (in): Y_M_D, D_M_Y or M_D_Y; out-of-range codes leave the setting unchanged.

Note: Affects later date parsing/formatting and must not race other shared-format calls.

Here is the caller graph for this function:

◆ datetime_strToDate()

int datetime_strToDate	(	char *	s,
		DateTime *	d )

Converts a string to a DateTime value.

Parameters

[in]	s	String date
[out]	d	DateTime value

Returns: 1 if successful, 0 if not

Converts a string to a DateTime value.

Implementation arguments

s (in): Non-null borrowed null-terminated text with slash/hyphen-separated fields; accepts numeric months or three-letter English month names.
d (out): Non-null caller-owned date slot, initialized to -DateDelta and replaced with SWMM midnight days only for a valid encoded date.

Returns: One for successful conversion, zero otherwise.

Note: DateFormat controls field order; input storage is not changed or retained.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ datetime_strToTime()

int datetime_strToTime	(	char *	s,
		DateTime *	t )

Converts a string to a DateTime value.

Parameters

[in]	s	String time
[out]	t	DateTime value

Returns: 1 if successful, 0 if not

Converts a string to a DateTime value.

Implementation arguments

s (in): Non-null borrowed null-terminated time text; not modified or retained.
t (out): Non-null caller-owned result in elapsed days. Failed colon parsing leaves zero; successful decimal hours are divided by 24.

Returns: One when a complete strtod conversion succeeds, including signed decimal hours, or when parsed colon components are nonnegative; zero otherwise.

Note: Clock components are not capped at 23/59/59, and trailing colon-text validation is permissive. This routine does not validate finite numeric range.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ datetime_timeDiff()

long datetime_timeDiff	(	DateTime	date1,
		DateTime	date2 )

Finds the difference in seconds between two DateTime values.

Parameters

[in]	date1	First date value
[in]	date2	Second date value

Returns: Number of seconds

Finds the difference in seconds between two DateTime values.

Implementation arguments

date1 (in): Finite minuend in SWMM calendar days.
date2 (in): Finite subtrahend in SWMM calendar days.

Returns: Signed difference in seconds; negative when date1 is earlier.

Precondition: The whole-day difference times 86400 fits in int, because the legacy implementation casts that intermediate to int, and the final result fits in long.

Here is the call graph for this function:

◆ datetime_timeToStr()

void datetime_timeToStr	(	DateTime	time,
		char *	s )

Converts a DateTime value to a string.

Parameters

[in]	time	Time value
[out]	s	String to store the time

Converts a DateTime value to a string.

Implementation arguments

time (in): Finite SWMM calendar/elapsed days; only its day fraction is decoded.
s (out): Non-null caller-owned buffer of at least TIME_STR_SIZE bytes; receives a null-terminated clock string. The pointer is not retained.

Here is the call graph for this function:

Here is the caller graph for this function:

Macros

Typedefs

Functions

Detailed Description

Update History

Macro Definition Documentation

◆ D_M_Y

◆ DATE_STR_SIZE

◆ M_D_Y

◆ NO_DATE

◆ TIME_STAMP_SIZE

◆ TIME_STR_SIZE

◆ Y_M_D

Typedef Documentation

◆ DateTime

Function Documentation

◆ datetime_addDays()

◆ datetime_addSeconds()

◆ datetime_dateToStr()

◆ datetime_dayOfWeek()

◆ datetime_dayOfYear()

◆ datetime_daysPerMonth()

◆ datetime_decodeDate()

◆ datetime_decodeTime()

◆ datetime_encodeDate()

◆ datetime_encodeTime()

◆ datetime_findMonth()

◆ datetime_getTimeStamp()

◆ datetime_hourOfDay()

◆ datetime_monthOfYear()

◆ datetime_setDateFormat()

◆ datetime_strToDate()

◆ datetime_strToTime()

◆ datetime_timeDiff()

◆ datetime_timeToStr()