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
	Ordinal-date offset used to encode 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 and swmm_output_get_period_time. Elapsed-time APIs and callback arguments use their separately documented time units rather than this calendar encoding.

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

Apache-2.0

Macro Definition Documentation

SWMM_DATETIME_DATE_DELTA

#define SWMM_DATETIME_DATE_DELTA   693594

Ordinal-date offset used to encode the SWMM DateTime epoch.

Exposed so bindings can validate against the same reference value the engine uses internally: ordinal day 1 for 0001-01-01 is converted to SWMM days by subtracting this offset. A value 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

[in]	value	Finite input SWMM DateTime in days.
[in]	seconds	Finite seconds to add (may be negative or fractional).
[out]	out	Caller-owned slot for resulting SWMM days; not retained.

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

[in]	value	Finite SWMM days; floor(value) and its sum with SWMM_DATETIME_DATE_DELTA must fit in int.
[out]	year	Year (>= 0). May be NULL.
[out]	month	Month (1..12). May be NULL.
[out]	day	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

[in]	value	Finite SWMM days; the whole-day portion is ignored.
[out]	hour	Hour (0..23). May be NULL.
[out]	minute	Minute (0..59). May be NULL.
[out]	second	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)), with results clamped to 23:59:59 when rounding would reach the next day. Subsecond input precision is discarded, matching legacy SWMM.

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

[in]	year	Year in the range 1..9999.
[in]	month	Month in the range 1..12.
[in]	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

[in]	hour	Nonnegative hours; values above 23 are accepted.
[in]	minute	Nonnegative minutes; values above 59 are accepted.
[in]	second	Nonnegative seconds; values above 59 are accepted.
[out]	out	Elapsed days; can be >= 1.0 for components totaling a day or more.

Returns

0 on success; -1 if out is NULL or any input is negative. The component sum in seconds must fit in int. 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

[in]	value1	Finite SWMM minuend; may be earlier than value2.
[in]	value2	Finite SWMM subtrahend.
[out]	out	Signed seconds after rounding each input time independently.

Returns

0 on success; -1 if out is NULL.

Precondition

The whole-day difference in seconds and final result fit in long.

Note

Output storage is borrowed for this call and is not retained.

Here is the call graph for this function: