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

Apache-2.0

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: