openswmm_datetime.h File Reference

OpenSWMM Engine — SWMM DateTime conversion utilities (C API). More...

#include "openswmm_engine_export.h"

Include dependency graph for openswmm_datetime.h:

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

Go to the source code of this file.

Macros
#define	SWMM_DATETIME_DATE_DELTA   693594
	Days from 0001-01-01 to 1899-12-30 (the SWMM DateTime epoch).

Functions
SWMM_ENGINE_API int	swmm_datetime_encode_date (int year, int month, int day, double *out)
	Encode a calendar date as a SWMM DateTime (date portion only).
SWMM_ENGINE_API int	swmm_datetime_encode_time (int hour, int minute, int second, double *out)
	Encode a wall-clock time as the fractional-day part of a SWMM DateTime.
SWMM_ENGINE_API int	swmm_datetime_decode_date (double value, int *year, int *month, int *day)
	Decode the date portion of a SWMM DateTime.
SWMM_ENGINE_API int	swmm_datetime_decode_time (double value, int *hour, int *minute, int *second)
	Decode the time-of-day portion of a SWMM DateTime.
SWMM_ENGINE_API int	swmm_datetime_add_seconds (double value, double seconds, double *out)
	Add a (possibly fractional) number of seconds to a SWMM DateTime.
SWMM_ENGINE_API int	swmm_datetime_time_diff (double value1, double value2, long *out)
	Compute the difference, in whole seconds, between two SWMM DateTimes.

Detailed Description

OpenSWMM Engine — SWMM DateTime conversion utilities (C API).

SWMM's native DateTime is a double. The integer part is the number of days since 1899-12-30 (the OLE Automation / Delphi TDateTime epoch) and the fractional part is the time-of-day fraction (0.0 = midnight, 0.5 = noon). This is the same representation produced and consumed by every other date or time value crossing the C API boundary — for example swmm_options_get_start_date, swmm_get_current_time, swmm_output_get_period_time and the sim_time argument passed to engine callbacks.

This header exposes the encode/decode primitives used inside the engine so language bindings (Python, .NET, etc.) can convert losslessly between the SWMM DateTime double and their native calendar/time types without re-implementing the epoch arithmetic.

The functions are pure (no engine handle required) and numerically identical to the legacy datetime.c routines.

Note

This is NOT an astronomical Julian Date. The epoch is 1899-12-30, matching Microsoft's OLE Automation date and Delphi's TDateTime — the format SWMM has always used.

Usage

#include <openswmm/engine/openswmm_datetime.h>
 
// Build a SWMM DateTime for 2024-06-15 13:30:00
double d, t, sim_t;
swmm_datetime_encode_date(2024, 6, 15, &d);
swmm_datetime_encode_time(13, 30, 0, &t);
sim_t = d + t;
 
// Decode a value returned by the engine
int y, m, day, h, mi, s;
swmm_datetime_decode_date(sim_t, &y, &m, &day);
swmm_datetime_decode_time(sim_t, &h, &mi, &s);

Author

Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright

Copyright (c) 2026 Caleb Buahin. All rights reserved.

License\n MIT License

Macro Definition Documentation

SWMM_DATETIME_DATE_DELTA

#define SWMM_DATETIME_DATE_DELTA   693594

Days from 0001-01-01 to 1899-12-30 (the SWMM DateTime epoch).

Exposed so bindings can validate against the same reference value the engine uses internally. A SWMM DateTime of 0.0 corresponds to 1899-12-30T00:00:00.

Function Documentation

swmm_datetime_add_seconds()

SWMM_ENGINE_API int swmm_datetime_add_seconds	(	double	value,
		double	seconds,
		double *	out )

Add a (possibly fractional) number of seconds to a SWMM DateTime.

Parameters

value	Input SWMM DateTime double.
seconds	Seconds to add (may be negative).
out	[out] Resulting SWMM DateTime double.

Returns

0 on success; -1 if out is NULL.

Note

Mirrors legacy datetime_addSeconds: decomposes the input to integer H:M:S, adds the offset, and recomposes — producing bit-identical results to a legacy SWMM run.

Here is the call graph for this function:

swmm_datetime_decode_date()

SWMM_ENGINE_API int swmm_datetime_decode_date	(	double	value,
		int *	year,
		int *	month,
		int *	day )

Decode the date portion of a SWMM DateTime.

Parameters

value	SWMM DateTime double.
year	[out] Year (>= 0). May be NULL.
month	[out] Month (1..12). May be NULL.
day	[out] Day of month (1..31). May be NULL.

Returns

0 on success; -1 if all output pointers are NULL.

Here is the call graph for this function:

swmm_datetime_decode_time()

SWMM_ENGINE_API int swmm_datetime_decode_time	(	double	value,
		int *	hour,
		int *	minute,
		int *	second )

Decode the time-of-day portion of a SWMM DateTime.

Parameters

value	SWMM DateTime double.
hour	[out] Hour (0..23). May be NULL.
minute	[out] Minute (0..59). May be NULL.
second	[out] Second (0..59). May be NULL.

Returns

0 on success; -1 if all output pointers are NULL.

Note

Uses the same integer second decomposition as the legacy engine (floor(fracDay * 86400 + 0.5)), so round-tripping through encode/decode is bit-identical to a legacy SWMM run.

Here is the call graph for this function:

swmm_datetime_encode_date()

SWMM_ENGINE_API int swmm_datetime_encode_date	(	int	year,
		int	month,
		int	day,
		double *	out )

Encode a calendar date as a SWMM DateTime (date portion only).

Parameters

year	Year in the range 1..9999.
month	Month in the range 1..12.
day	Day of month, valid for the given year/month.
out	[out] SWMM DateTime double (integer days since 1899-12-30).

Returns

0 on success; -1 if out is NULL or the date is out of range. On out-of-range input, *out is set to the sentinel -SWMM_DATETIME_DATE_DELTA (matching legacy datetime_encodeDate).

Here is the call graph for this function:

swmm_datetime_encode_time()

SWMM_ENGINE_API int swmm_datetime_encode_time	(	int	hour,
		int	minute,
		int	second,
		double *	out )

Encode a wall-clock time as the fractional-day part of a SWMM DateTime.

Parameters

hour	Hour [0..].
minute	Minute [0..].
second	Second [0..].
out	[out] Fractional-day value in [0.0, 1.0).

Returns

0 on success; -1 if out is NULL or any input is negative. On invalid input *out is set to 0.0 (matching legacy datetime_encodeTime).

Here is the call graph for this function:

swmm_datetime_time_diff()

SWMM_ENGINE_API int swmm_datetime_time_diff	(	double	value1,
		double	value2,
		long *	out )

Compute the difference, in whole seconds, between two SWMM DateTimes.

Parameters

value1	Later SWMM DateTime.
value2	Earlier SWMM DateTime.
out	[out] value1 - value2 rounded to the nearest second.

Returns

0 on success; -1 if out is NULL.

Here is the call graph for this function: