openswmm_datetime_impl.cpp File Reference

C API implementation — SWMM DateTime encode/decode utilities. More...

#include "DateTime.hpp"
#include "../../../include/openswmm/engine/openswmm_datetime.h"

Include dependency graph for openswmm_datetime_impl.cpp:

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

C API implementation — SWMM DateTime encode/decode utilities.

Thin wrappers around the inline routines in DateTime.hpp so the same numerics used inside the engine are reachable from C callers and language bindings.

See also

include/openswmm/engine/openswmm_datetime.h

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

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: