Legacy SWMM date and time representation and arithmetic. More...

#include <math.h>
#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include "datetime.h"

Include dependency graph for datetime.c:

Macros
#define	_CRT_SECURE_NO_DEPRECATE

#define	UCHAR(x)

Functions
void	divMod (int n, int d, int result, int remainder)
	Divide two integers with legacy zero-divisor handling.

int	isLeapYear (int year)
	Apply the Gregorian divisible-by-four/century/400-year leap rule.

int	datetime_findMonth (char *month)
	Match the first three letters of an English month name.

DateTime	datetime_encodeDate (int year, int month, int day)
	Encode a Gregorian date as midnight in SWMM calendar days.

DateTime	datetime_encodeTime (int hour, int minute, int second)
	Convert nonnegative hour/minute/second components to elapsed days.

void	datetime_decodeDate (DateTime date, int year, int month, int *day)
	Decode a SWMM whole-day value into Gregorian date components.

void	datetime_decodeTime (DateTime time, int h, int m, int *s)
	Round a SWMM day fraction to whole-second clock components.

void	datetime_dateToStr (DateTime date, char *s)
	Format the date portion of a SWMM DateTime with the shared DateFormat.

void	datetime_timeToStr (DateTime time, char *s)
	Format the rounded time-of-day portion as HH:MM:SS.

int	datetime_strToDate (char s, DateTime d)
	Parse a calendar date using the shared date-format setting.

int	datetime_strToTime (char s, DateTime t)
	Parse decimal hours or nonnegative colon-separated clock components.

void	datetime_setDateFormat (int fmt)
	Select the shared calendar text field order.

DateTime	datetime_addSeconds (DateTime date1, double seconds)
	Add seconds after rounding the input time to the legacy whole-second clock.

DateTime	datetime_addDays (DateTime date1, DateTime date2)
	Add two day values after rounding each fractional part to whole seconds.

long	datetime_timeDiff (DateTime date1, DateTime date2)
	Subtract two dates using separately rounded whole-second clock values.

int	datetime_monthOfYear (DateTime date)
	Extract the month from a SWMM DateTime.

int	datetime_dayOfYear (DateTime date)
	Extract the day of year from a SWMM DateTime.

int	datetime_dayOfWeek (DateTime date)
	Extract the day of week from a SWMM DateTime.

int	datetime_hourOfDay (DateTime date)
	Extract the hour from a SWMM DateTime.

int	datetime_daysPerMonth (int year, int month)
	Find a Gregorian month's length using the leap-year rule.

void	datetime_getTimeStamp (int fmt, DateTime aDate, int stampSize, char *timeStamp)
	Format SWMM calendar days as a date and whole-second time stamp.

Detailed Description

Legacy SWMM date and time representation and arithmetic.

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

◆ _CRT_SECURE_NO_DEPRECATE

#define _CRT_SECURE_NO_DEPRECATE

◆ UCHAR

#define UCHAR ( x )

Value:

(((x) >= 'a' && (x) <= 'z') ? ((x) & ~32) : (x))

Function Documentation

◆ datetime_addDays()

DateTime datetime_addDays	(	DateTime	date1,
		DateTime	date2 )

Add two day values after rounding each fractional part to whole seconds.

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 )

Add seconds after rounding the input time to the legacy whole-second clock.

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 )

Format the date portion of a SWMM DateTime with the shared DateFormat.

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 )

Extract the day of week from a SWMM DateTime.

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 )

Extract the day of year from a SWMM DateTime.

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 )

Find a Gregorian month's length using the leap-year rule.

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 )

Decode a SWMM whole-day value into Gregorian date components.

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 )

Round a SWMM day fraction to whole-second clock components.

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 )

Encode a Gregorian date as midnight in SWMM calendar days.

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 )

Convert nonnegative hour/minute/second components to elapsed days.

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 )

Match the first three letters of an English month name.

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 SWMM calendar days as a date and whole-second time stamp.

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 )

Extract the hour from a SWMM DateTime.

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 )

Extract the month from a SWMM DateTime.

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 )

Select the shared calendar text field order.

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 )

Parse a calendar date using the shared date-format setting.

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 )

Parse decimal hours or nonnegative colon-separated clock components.

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 )

Subtract two dates using separately rounded whole-second clock values.

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 )

Format the rounded time-of-day portion as HH:MM:SS.

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:

◆ divMod()

void divMod	(	int	n,
		int	d,
		int *	result,
		int *	remainder )

Divide two integers with legacy zero-divisor handling.

Parameters

[in]	n	Dividend; n / d must be representable as int when d is nonzero.
[in]	d	Divisor; zero requests zero quotient and remainder.
[out]	result	Non-null distinct caller-owned quotient slot, truncated toward zero.
[out]	remainder	Non-null distinct caller-owned remainder slot, n - d * quotient.

Note: Both output values are zero when d is zero; pointers are not retained.

Here is the caller graph for this function:

◆ isLeapYear()

int isLeapYear ( int year )

Apply the Gregorian divisible-by-four/century/400-year leap rule.

Parameters

[in] year Calendar year; the arithmetic rule also accepts year zero.

Returns: One for a leap year, zero otherwise.

Here is the caller graph for this function:

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ _CRT_SECURE_NO_DEPRECATE

◆ UCHAR

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()

◆ divMod()

◆ isLeapYear()