diff --git a/doc/libmtime.dox b/doc/libmtime.dox
index af65f5273ddfdba5f31fdc3ca13a79abd031aa3c..f4a9214a7f305e3874767fb378634bbab1934c0e 100644
--- a/doc/libmtime.dox
+++ b/doc/libmtime.dox
@@ -5,13 +5,13 @@
* This project aims to provide time, calenendar, and event handling
* for model applications.
*
- * libmtime provides the following simple and well documented data structures of
+ * libmtime provides the following simple and well documented data structures forq
* common use:
*
* @arg calendar: The base calendar; either proleptic Gregorian,
* 365 day years, or 360 day years calendar.
* @arg date: A calendars date.
- * @arg time: A time at a day.
+ * @arg time: A time on a day.
* @arg datetime: Date and time combined.
* @arg timedelta: A difference in datetime.
* @arg julianday: The Julian day to define the base time axis.
@@ -35,7 +35,7 @@
* @section Usage
*
* The doxygen documentation you are reading is pretty rich. You
- * are still recomended to take a look at the libmtime/test directory,
+ * are still recomended to take a look at the libmtime/examples directory,
* which contains some usage examples.
*
* @section License
@@ -64,7 +64,7 @@
*
* @section Dependency
*
- * The library should work correctly without any dependency under any
+ * The library should work correctly without any dependencies under any
* Posix-compliant operating system. If you experience some issue
* please contact me. The AUTHORS file provided with the software
* distribution contain developers contacts.
diff --git a/src/libmtime.f90 b/src/libmtime.f90
index cd65243551281e50ab0c597d9a81bf62879fd192..5c198a9e5b44f3922e700fb2e927606072afea99 100644
--- a/src/libmtime.f90
+++ b/src/libmtime.f90
@@ -417,7 +417,7 @@ contains
!!
!! @param[in] src a pointer of type(date)
!! @param[out] dest a pointer of type(date)
- !! @param[out] errno optional, error message
+ !! @param[out] errno optional, error message
subroutine replaceDate(dest, src, errno) !OK-TESTED.
type(date), target, intent(inout) :: dest
type(date), target, intent(in) :: src
@@ -427,8 +427,19 @@ contains
dummy_ptr = my_replacedate(c_loc(src), c_loc(dest))
if ((.not. c_associated(dummy_ptr)) .and. present(errno)) errno = 2 * 100 + 6
end subroutine replaceDate
- !
- !! @param[out] errno optional, error message
+ !>
+ !! @brief Get Date as an extended string.
+ !!
+ !! DateToString returns a string in IS08601 compliant (and extended) format.
+ !!
+ !! @param[in] my_date
+ !! A pointer to type date. The date to be converted to string.
+ !!
+ !! @param[out] string
+ !! String where date is to be written.
+ !!
+ !! @param[out] errno
+ !! Optional, error message
subroutine dateToString(my_date, string, errno) !OK-TESTED.
type(date), pointer :: my_date
character(len=max_date_str_len) :: string
@@ -443,7 +454,20 @@ contains
end do char_loop
string(i:len(string)) = ' '
end subroutine dateToString
- !
+ !>
+ !! @brief Get date and return as a string.
+ !!
+ !! Only dates between and including 1582-10-15 TO 9999-12-31 supported.
+ !!
+ !! @param[in] my_date
+ !! A pointer to type date. The date to be converted to string.
+ !!
+ !! @param[out] string
+ !! String where date is to be written.
+ !!
+ !! @param[in] fmtstr
+ !! Desired Format string. CRITICAL: Inappropriate fmt string will cause dump.
+ !!
!! @param[out] errno optional, error message
subroutine dateToPosixString(my_date, string, fmtstr, errno) !OK-TESTED.
type(date), pointer :: my_date
@@ -591,13 +615,27 @@ contains
if ((.not.c_associated(c_pointer)) .and. present(errno)) errno = 3 * 100 + 3
call c_f_pointer(c_pointer, dest)
end function newtimefromconstructandcopy
- !
+ !>
+ !! @brief Destructor of Time.
+ !!
+ !! @param my_time
+ !! A pointer to type time. my_time is deallocated.
subroutine deallocateTime(my_time) !OK-TESTED.
type(time), pointer :: my_time
call my_deallocatetime(c_loc(my_time))
my_time => null()
end subroutine deallocateTime
- !
+ !>
+ !! @brief COPY a time object.
+ !!
+ !! Routine replaceTime copies the contents of source Time into a Destination Time object.
+ !!
+ !! @param[in] src
+ !! A pointer to type time. Copy "FROM" time object.
+ !!
+ !! @param[out] dest
+ !! A pointer to type time. Copy "TO" time object.
+ !!
!! @param[out] errno optional, error message
subroutine replaceTime(dest,src,errno) !OK-TESTED.
type(time), target, intent(in) :: src
@@ -608,7 +646,17 @@ contains
dummy_ptr = my_replacetime(c_loc(src), c_loc(dest))
if ((.not.c_associated(dummy_ptr)) .and. present(errno)) errno = 3 * 100 + 5
end subroutine replaceTime
- !
+ !>
+ !! @brief Get time as an extended string.
+ !!
+ !! timetoString returns a string in IS08601 compliant (and extended) format.
+ !!
+ !! @param[in] my_time
+ !! A pointer to type time. The time to be converted to string.
+ !!
+ !! @param[out] string
+ !! String where time is to be written.
+ !!
!! @param[out] errno optional, error message
subroutine timeToString(my_time, string, errno) !OK-TESTED.
type(time), pointer :: my_time
@@ -624,7 +672,18 @@ contains
end do char_loop
string(i:len(string)) = ' '
end subroutine timeToString
- !
+ !>
+ !! @brief Get time as a Posix formated string.
+ !!
+ !! @param[in] my_time
+ !! A pointer to type time. The time to be converted to string.
+ !!
+ !! @param[out] string
+ !! String where time is to be written.
+ !!
+ !! @param[in] fmtstr
+ !! Desired Format string. CRITICAL: Inappropriate fmt string will cause dump.
+ !!
!! @param[out] errno optional, error message
subroutine timeToPosixString(my_time, string, fmtstr, errno) !OK-TESTED.
type(time), pointer :: my_time
@@ -926,13 +985,27 @@ contains
end if
end function datetime_max
- !
+ !>
+ !! @brief Destructor of DateTime.
+ !!
+ !! @param my_datetime
+ !! A pointer to type datetime. my_datetime is deallocated.
subroutine deallocateDatetime(my_datetime) !OK-TESTED.
type(datetime), pointer :: my_datetime
call my_deallocatedatetime(c_loc(my_datetime))
nullify(my_datetime)
end subroutine deallocateDatetime
- !
+ !>
+ !! @brief Get DateTime as a string.
+ !!
+ !! datetimeToString returns a string in IS08601 compliant (and extended) format.
+ !!
+ !! @param[in] my_datetime
+ !! A pointer to struct _datetime. The datetime to be converted to string.
+ !!
+ !! @param[out] string
+ !! String where datetime is to be written.
+ !!
!! @param[out] errno optional, error message
subroutine datetimeToString(my_datetime, string, errno) !OK-TESTED
type(datetime), pointer :: my_datetime
@@ -948,7 +1021,20 @@ contains
end do char_loop
string(i:len(string)) = ' '
end subroutine datetimeToString
- !
+ !>
+ !! @brief Get DateTime in 'struct tm' format and return as a string.
+ !!
+ !! Only dates between and including 1582-10-15 TO 9999-12-31 supported.
+ !!
+ !! @param my_datetime
+ !! A pointer to type datetime. The datetime to be converted to string.
+ !!
+ !! @param string
+ !! String where datetime is to be written.
+ !!
+ !! @param fmtstr
+ !! Desired Format string. CRITICAL: Inappropriate fmt string will cause dump.
+ !!
!! @param[out] errno optional, error message
subroutine datetimeToPosixString(my_datetime, string, fmtstr, errno) !OK-TESTED.
type(datetime), pointer :: my_datetime
@@ -1051,7 +1137,21 @@ contains
ne = .false.
endif
end function datetime_ne
- !
+ !>
+ !! @brief Get nod (number of Days) in the month of DateTime.
+ !!
+ !! Routine getNoOfDaysInMonthDateTime returns number of days in the month of DateTime. This routine
+ !! supports all calendar types.
+ !!
+ !! For eg. the number of days for 2001-10-15T00:00:00.000 will be 31 for Gregorian Calendar.
+ !! Similarly, this value will be 30 for Calendar of type 360 day-Calendar.
+ !!
+ !! @param[in] dt
+ !! A pointer to type datetime.
+ !!
+ !! @return nod
+ !! Integer value of nod. The value depends on the month and the calendar type. Zero indicates error.
+ !!
!! @param[out] errno optional, error message
function getNoOfDaysInMonthDateTime(dt, errno) !OK-TESTED.
type(datetime), target :: dt
@@ -1061,7 +1161,20 @@ contains
getNoOfDaysInMonthDateTime = my_getnoofdaysinmonthdatetime(c_loc(dt))
if (getNoOfDaysInMonthDateTime == 0 .and. present(errno)) errno = 4 * 100 + 15
end function getNoOfDaysInMonthDateTime
- !
+ !>
+ !! @brief Get number of days in the Year of DateTime.
+ !!
+ !! Routine getNoOfDaysInYearDateTime returns number of days in the Year of DateTime. This routine
+ !! supports all calendar types.
+ !!
+ !! Number of days returned will depend on the calendar type and if applicable, leap v/s non leap year.
+ !!
+ !! @param[in] dt
+ !! A pointer to type datetime.
+ !!
+ !! @return nod
+ !! Integer value of nod. The value depends on the year and the calendar type. Zero indicates error.
+ !!
!! @param[out] errno optional, error message
function getNoOfDaysInYearDateTime(dt, errno) !OK-TESTED.
type(datetime), target :: dt
@@ -1071,7 +1184,21 @@ contains
getNoOfDaysInYearDateTime = my_getnoofdaysinyeardatetime(c_loc(dt))
if (getNoOfDaysInYearDateTime == 0 .and. present(errno)) errno = 4 * 100 + 16
end function getNoOfDaysInYearDateTime
- !
+ !>
+ !! @brief Get the 'day-of-year' value of a DateTime.
+ !!
+ !! Routine getDayOfYearFromDateTime returns Day of Year for the DateTime. This routine supports
+ !! all Calendar types.
+ !!
+ !! For eg. the day of year value for 2001-10-15T00:00:00.000 will be 288 for Gregorian Calendar.
+ !! Similarly, this value will be 285 for Calendar of type 360 day-Calendar.
+ !!
+ !! @param[in] dt
+ !! A pointer to type datetime. Retrieve the 'day-of-year' from this DT object.
+ !!
+ !! @return doy
+ !! Integer value of doy. The value depends on the calendar type. Zero indicates error.
+ !!
!! @param[out] errno optional, error message
function getDayOfYearFromDateTime(dt, errno) !OK-TESTED.
type(datetime), target :: dt
@@ -1081,7 +1208,15 @@ contains
getDayOfYearFromDateTime = my_getdayofyearfromdatetime(c_loc(dt))
if (getDayOfYearFromDateTime == 0 .and. present(errno)) errno = 4 * 100 + 17
end function getDayOfYearFromDateTime
- !
+ !>
+ !! @brief Get number of seconds elapsed in the month of DateTime.
+ !!
+ !! @param[in] dt
+ !! A pointer to type datetime.
+ !!
+ !! @return no_of_seconds
+ !! int(i8) value of no_of_seconds. -1 indicates error.
+ !!
!! @param[out] errno optional, error message
function getNoOfSecondsElapsedInMonthDateTime(dt, errno) !OK-TESTED.
type(datetime), target :: dt
@@ -1091,7 +1226,15 @@ contains
getNoOfSecondsElapsedInMonthDateTime = my_getnoofsecondselapsedinmonthdatetime(c_loc(dt))
if (getNoOfSecondsElapsedInMonthDateTime == -1 .and. present(errno)) errno = 4 * 100 + 18
end function getNoOfSecondsElapsedInMonthDateTime
- !
+ !>
+ !! @brief Get number of seconds elapsed in the day of DateTime.
+ !!
+ !! @param[in] dt
+ !! A pointer to type datetime.
+ !!
+ !! @return no_of_seconds
+ !! int value of no_of_seconds. -1 indicates error.
+ !!
!! @param[out] errno optional, error message
function getNoOfSecondsElapsedInDayDateTime(dt, errno) !OK-TESTED.
type(datetime), target :: dt
@@ -1101,7 +1244,18 @@ contains
getNoOfSecondsElapsedInDayDateTime = my_getnoofsecondselapsedindaydatetime(c_loc(dt))
if (getNoOfSecondsElapsedInDayDateTime == -1 .and. present(errno)) errno = 4 * 100 + 19
end function getNoOfSecondsElapsedInDayDateTime
- !
+ !>
+ !! @brief Get the Julian Day from DateTime.
+ !!
+ !! The routine getJulianDayFromDateTime returns the equivalent Julian date to DateTime. Internally
+ !! it calls translation routines based on Calendar type.
+ !!
+ !! @param[in] dt
+ !! A pointer to type datetime. The DT's value is converted to julian day value.
+ !!
+ !! @param[out] jd
+ !! A pointer to type julianday. JD where the converted value is stored.
+ !!
!! @param[out] errno optional, error message
subroutine getJulianDayFromDatetime(dt, jd, errno) !OK-TESTED.
type(datetime), target :: dt
@@ -1112,7 +1266,18 @@ contains
dummy_ptr = my_getjuliandayfromdatetime(c_loc(dt), c_loc(jd))
if ((.not.c_associated(dummy_ptr)) .and. present(errno)) errno = 4 * 100 + 20
end subroutine getJulianDayFromDatetime
- !
+ !>
+ !! @brief Get the DateTime from Julian Day.
+ !!
+ !! The routine getDateTimeFromJulianDay returns the equivalent DateTime to Julian date. Internally
+ !! it calls translation routines based on Calendar type.
+ !!
+ !! @param[in] jd
+ !! A pointer to type julianday. The JD's value is converted to julian day value.
+ !!
+ !! @param[out] dt
+ !! A pointer to type datetime. The DT where the converted value is stored.
+ !!
!! @param[out] errno optional, error message
subroutine getDatetimeFromJulianDay(jd, dt, errno)
type(julianday), target :: jd
@@ -1485,7 +1650,11 @@ contains
if ((.not. c_associated(c_pointer)) .and. present(errno)) errno = 5 * 100 + 4
call c_f_pointer(c_pointer, dest)
end function newtimedeltafromconstructandcopy
- !
+ !>
+ !! @brief Destructor of TimeDelta.
+ !!
+ !! @param my_timedelta
+ !! A pointer to typetimedelta. my_timedelta is deallocated.
subroutine deallocateTimedelta(my_timedelta) !OK-TESTED.
type(timedelta), pointer :: my_timedelta
call my_deallocatetimedelta(c_loc(my_timedelta))
@@ -1569,23 +1738,82 @@ contains
ne = .false.
endif
end function timedelta_ne
- !
+ !>
+ !! @brief Get the TimeDelta between two Dates op1 and op2 as (op1-op22).
+ !!
+ !! Routine getTimeDeltaFromDate 'substracts' two Dates and returns the TimeDelta between
+ !! them. Internally, Dates are converted to DateTimes and then delta is calculated using
+ !! getTimeDeltaFromDateTime().
+ !!
+ !! This routine handles all supported Calendar types; i.e. the translation from Calendar date
+ !! to Julian date and conversion from Julian Delta to normal TimeDetla is Calendar-type dependent.
+ !! For eg. for Calendar type Gregorian, the TimeDelta between 2001-02-01 and 2001-01-01 will be 1 month.
+ !! Similarly, for Calendar of type 360-Day-Calendar, the TimeDelta will be 1 month. It must be noted
+ !! however, that the two dates differ by 31 and 30 days respectively.
+ !!
+ !! @param op1
+ !! A pointer to type date.
+ !!
+ !! @param op2
+ !! A pointer to type date.
+ !!
+ !! @return ret
+ !! A pointer to TimeDelta containing the result of substraction.
function getTimeDeltaFromDate(op1,op2) result(ret) !OK-TESTED.
type(timedelta), target :: ret
type(date), target, intent(in) :: op1, op2
type(c_ptr) :: dummy_ptr
dummy_ptr = my_gettimedeltafromdate(c_loc(op1),c_loc(op2),c_loc(ret))
end function getTimeDeltaFromDate
- !
+ !>
+ !! @brief Get the TimeDelta between two DateTimes op1 and op2 as (op1-op2).
+ !!
+ !! Routine getTimeDeltaFromDateTime 'substracts' two DateTime's and returns the TimeDelta between
+ !! them. Each datetime is converted to an equivalent Julian Date. Substraction is then performed
+ !! on Julian axis. The "Julian delta" is finally converted back to normal calendar delta.
+ !!
+ !! This routine handles all supported Calendar types; i.e. the translation from Calendar date
+ !! to Julian date and conversion from Julian Delta to normal TimeDetla is Calendar-type dependent.
+ !! For eg. for Calendar type Gregorian, the TimeDelta between 2001-02-01T00:00:00.000 and
+ !! 2001-01-01T00:00:00.000 will be 1 month. Similarly, for Calendar of type 360-Day-Calendar,
+ !! the TimeDelta will be 1 month. It must be noted however, that the two dates differ by 31 and
+ !! 30 days respectively.
+ !!
+ !! @param op1
+ !! A pointer to type datetime.
+ !!
+ !! @param op2
+ !! A pointer to type datetime.
+ !!
+ !! @return ret
+ !! A pointer to TimeDelta containing the result of substraction.
function getTimeDeltaFromDateTime(op1,op2) result(ret) !OK-TESTED.
type(timedelta), target :: ret
type(datetime), target, intent(in) :: op1, op2
type(c_ptr) :: dummy_ptr
dummy_ptr = my_gettimedeltafromdatetime(c_loc(op1),c_loc(op2),c_loc(ret))
end function getTimeDeltaFromDateTime
- !
- !WARNING: TD 0 is error. If you know your TD is 0, ignore the error flag.
- !! @param[out] errno optional, error message
+ !>
+ !! @brief Get total number of milliseconds in timedelta.
+ !!
+ !! Routine getTotalMilliSecondsTimeDelta returns the total number of milliseconds in TimeDelta.
+ !! Notice that TimeDelta is not uniquely defined but depends on the definition of corresponding
+ !! DateTime. TimeDelta is first converted to corresponding delta on the Julian axis. Julian delta
+ !! is finally converted to the correct millisecond value.
+ !!
+ !! @param[in] td
+ !! A pointer to type timedelta. Retrieve the number of milliseconds in this TD object.
+ !!
+ !! @param[in] dt
+ !! A pointer to type datetime. Reference Datetime for the TD.
+ !!
+ !! @param[out] errno
+ !! Optional, error message
+ !!
+ !! @return totalmilliSeconds
+ !! Integer value of totalmilliSeconds. 0 indicates error.
+ !!
+ !! WARNING: TD 0 is error. If you know your TD is 0, ignore the error flag.
function getTotalMilliSecondsTimeDelta(td, dt, errno) !OK-TESTED.
integer(c_int64_t) :: getTotalMilliSecondsTimeDelta
type(timedelta), target, intent(in):: td
@@ -1595,9 +1823,27 @@ contains
getTotalMilliSecondsTimeDelta = my_gettotalmillisecondstimedelta(c_loc(td), c_loc(dt))
if ((getTotalMilliSecondsTimeDelta == 0) .and. present(errno)) errno = 5 * 100 + 8
end function getTotalMilliSecondsTimeDelta
- !
- !WARNING: TD 0 is error. If you know your TD is 0, ignore the error flag.
- !! @param[out] errno optional, error message
+ !>
+ !! @brief Get total number of seconds in timedelta.
+ !!
+ !! Routine getTotalSecondsTimeDelta returns the total number of seconds in TimeDelta. Notice that TimeDelta
+ !! is not uniquely defined but depends on the definition of corresponding DateTime. Internally, number of seconds
+ !! is calculated by calling the routine getTotalMilliSecondsTimeDelta() and then converting the millisecond value
+ !! to seconds by dividing it by 1000.
+ !!
+ !! @param[in] td
+ !! A pointer to struct _timedelta. Retrieve the number of seconds in this TD object.
+ !!
+ !! @param[in] dt
+ !! A pointer to struct _datetime. Reference Datetime for the TD.
+ !!
+ !! @param[out] errno
+ !! Optional, error message
+ !!
+ !! @return totalSeconds
+ !! Integer value of totalSeconds. 0 indicates error.
+ !!
+ !! WARNING: TD 0 is error. If you know your TD is 0, ignore the error flag.
function getTotalSecondsTimeDelta(td, dt, errno) !OK-TESTED.
integer(c_int64_t) :: getTotalSecondsTimeDelta
type(timedelta), pointer :: td
@@ -1607,7 +1853,17 @@ contains
getTotalSecondsTimeDelta = my_gettotalsecondstimedelta(c_loc(td), c_loc(dt))
if ((getTotalSecondsTimeDelta == 0) .and. present(errno)) errno = 5 * 100 + 9
end function getTotalSecondsTimeDelta
- !
+ !>
+ !! @brief Get TimeDelta as an extended string.
+ !!
+ !! timedeltaToString returns a string in IS08601 compliant (and extended) format.
+ !!
+ !! @param[in] my_timedelta
+ !! A pointer to type timedelta. The timedelta to be converted to string.
+ !!
+ !! @param[out] string
+ !! String where timedelta is to be written.
+ !!
!! @param[out] errno optional, error message
subroutine timedeltaToString(my_timedelta, string, errno) !OK-TESTED.
type(timedelta), pointer :: my_timedelta
@@ -1693,13 +1949,13 @@ contains
dummy_ptr = my_elementwisescalarmultiplytimedelta(c_loc(base_td), lambda, c_loc(scaled_td))
end function elementwiseScalarMultiplyTimeDeltaInv_long
!
- FUNCTION elementwiseScalarMultiplyTimeDelta_real(base_td, lambda) RESULT(scaled_td) !OK-TESTED.
+ function elementwisescalarmultiplytimedelta_real(base_td, lambda) result(scaled_td) !OK-TESTED.
type(timedelta), target :: scaled_td
- REAL(c_double), INTENT(in) :: lambda
+ real(c_double), intent(in) :: lambda
type(timedelta), target, intent(in) :: base_td
type(c_ptr) :: dummy_ptr
dummy_ptr = my_elementwisescalarmultiplytimedeltadp(c_loc(base_td), lambda, c_loc(scaled_td))
- END FUNCTION elementwiseScalarMultiplyTimeDelta_real
+ end function elementwisescalarmultiplytimedelta_real
!
function elementwiseAddTimeDeltatoTimeDelta(td1, td2) result(added_td) !OK-TESTED.
type(timedelta), target :: added_td
@@ -1707,7 +1963,20 @@ contains
type(c_ptr) :: dummy_ptr
dummy_ptr = my_elementwiseaddtimedeltatotimedelta(c_loc(td1), c_loc(td2), c_loc(added_td))
end function elementwiseAddTimeDeltatoTimeDelta
- !
+ !>
+ !! @brief Returns modulo(a,p) and the quotient.
+ !!
+ !! @param[in] a
+ !! A pointer to type timedelta.
+ !!
+ !! @param[in] p
+ !! A pointer to type timedelta.
+ !!
+ !! @param[out] quot
+ !! The quotient of a divided by p.
+ !!
+ !! @return rem
+ !! modulo(a, p)
function moduloTimedelta(a, p, quot) result(rem)
type(timedelta), target, intent(in) :: a
type(timedelta), target, intent(in) :: p
@@ -1715,7 +1984,18 @@ contains
integer(c_int64_t) :: rem
rem = my_modulotimedelta(c_loc(a), c_loc(p), c_loc(quot))
end function moduloTimedelta
- !
+ !>
+ !! @brief Return a PT String corresponding to arbitrary number of milliseconds.
+ !!
+ !! getPTStringFromMS() translates ms values to ISO 8601 compliant timedelta string.
+ !! Conversion of ms >= 86400000 and ms <= -86400000 not supported.
+ !!
+ !! @param[in] ms
+ !! An int64_t value to be translated.
+ !!
+ !! @param[out] string
+ !! Translated string is written here.
+ !!
subroutine getPTStringFromMS(ms, string) !OK-TESTED.
integer(c_int64_t), intent(in) :: ms
character(len=max_timedelta_str_len) :: string
@@ -1764,7 +2044,18 @@ contains
end do char_loop
string(i:len(string)) = ' '
end subroutine getPTStringFromSecondsDouble
- !
+ !>
+ !! @brief Return a PT String corresponding to arbitrary number of minutes.
+ !!
+ !! getPTStringFromMinutes() translates minutes values to ISO 8601 compliant timedelta string.
+ !! Conversion of m >= 1440 and m <= -1440 not supported.
+ !!
+ !! @param[in] m
+ !! An int64_t value to be translated.
+ !!
+ !! @param[out] string
+ !! Translated string is written here.
+ !!
subroutine getPTStringFromMinutes(m, string) !OK-TESTED.
integer(c_int64_t) :: m
character(len=max_timedelta_str_len) :: string
@@ -1776,7 +2067,18 @@ contains
end do char_loop
string(i:len(string)) = ' '
end subroutine getPTStringFromMinutes
- !
+ !>
+ !! @brief Return a PT String corresponding to arbitrary number of Hours.
+ !!
+ !! getPTStringFromHours() translates hour values to ISO 8601 compliant timedelta string.
+ !! Conversion of h >= 24 and ms <= -24 not supported.
+ !!
+ !! @param[in] h
+ !! An int64_t value to be translated.
+ !!
+ !! @param[out] string
+ !! Translated string is written here.
+ !!
subroutine getPTStringFromHours(h, string) !OK-TESTED.
integer(c_int64_t) :: h
character(len=max_timedelta_str_len) :: string
@@ -1788,7 +2090,18 @@ contains
end do char_loop
string(i:len(string)) = ' '
end subroutine getPTStringFromHours
- !
+ !>
+ !! @brief division by seconds.
+ !!
+ !! @param[in] dividend
+ !! A pointer to type timedelta
+ !!
+ !! @param[in] divisor
+ !! A pointer to type timedelta
+ !!
+ !! @param[out] quotient
+ !! A pointer to type divisionquotienttimespan
+ !!
subroutine divideTimeDeltaInSeconds(dividend, divisor, quotient)
type(timedelta), target, intent(in) :: dividend
type(timedelta), target, intent(in) :: divisor
@@ -1796,7 +2109,23 @@ contains
type(c_ptr) :: dummy_ptr
dummy_ptr = my_dividetimedeltainseconds(c_loc(dividend), c_loc(divisor), c_loc(quotient))
end subroutine divideTimeDeltaInSeconds
- !
+ !>
+ !! @brief division of an datetime interval by seconds.
+ !!
+ !! the datetime interval is calculated by dt1-dt2.
+ !!
+ !! @param[in] dt1
+ !! A pointer to type datetime
+ !!
+ !! @param[in] dt2
+ !! A pointer to type datetime
+ !!
+ !! @param[in] divisor
+ !! A pointer to type timedelta
+ !!
+ !! @param[out] quotient
+ !! A pointer to type divisionquotienttimespan
+ !!
subroutine divideDatetimeDifferenceInSeconds(dt1, dt2, divisor, quotient)
type(datetime), target, intent(in) :: dt1
type(datetime), target, intent(in) :: dt2
@@ -2071,15 +2400,28 @@ contains
if ((.not. c_associated(c_pointer)) .and. present(errno)) errno = 6 * 100 + 1
call c_f_pointer(c_pointer, ret_event)
end function newEventWithDataTypes
- !
- ! WARNING: If my_event was added to a group, this should never be called;
- ! use removeEventFromEventGroup instead.
+ !>
+ !! @brief Destructor of Event.
+ !!
+ !! @param my_event
+ !! A pointer to type event. my_event is deallocated.
+ !!
+ !! WARNING: If my_event was added to a group, this should never be called;
+ !! use removeEventFromEventGroup instead.
subroutine deallocateEvent(my_event)
type(event), pointer :: my_event
call my_deallocateevent(c_loc(my_event))
my_event => null()
end subroutine deallocateEvent
- !
+ !>
+ !! @brief Get Event as a string.
+ !!
+ !! @param[in] my_event
+ !! A pointer to type event. The event to be converted to string.
+ !!
+ !! @param[out] string
+ !! String where event is to be written.
+ !!
!! @param[out] errno optional, error message
subroutine eventToString(my_event, string, errno) !TODO:C code still incomplete.
type(event), pointer :: my_event
@@ -2095,7 +2437,35 @@ contains
end do char_loop
string(i:len(string)) = ' '
end subroutine eventToString
- !
+ !>
+ !! @brief Check if this event is active by comparing event's trigger time with current_dt.
+ !!
+ !! The current_dt must lie in event's trigger time
+ !!
+ !! (subject to optional specified slack: [Trigger_time -
+ !! minus_slack, Trigger_time + plus_slack]. Slacks can be
+ !! NULL. Always inclusive.)
+ !!
+ !! The lib has no built-in clock but relies on
+ !! isCurrentEventActive(.) being called (polled) from the
+ !! application at fixed intervals.
+ !!
+ !! @param my_event
+ !! A pointer to type event. This is the event being tested.
+ !!
+ !! @param my_datetime
+ !! A pointer to type datetime. This is the 'current' datetime of the system.
+ !!
+ !! @param plus_slack
+ !! A pointer to type timedelta. Events are triggered between [actual_trigger_time, actual_trigger_time + plus_slack].
+ !! Sign MUST be '+'
+ !!
+ !! @param minus_slack
+ !! A pointer to type timedelta. Events are triggered between [actual_trigger_time - minus_slack, actual_trigger_time].
+ !! Sign MUST be '+'
+ !!
+ !! @return ret
+ !! true/false indicating if the event is active.
function isCurrentEventActive(my_event, my_datetime, plus_slack, minus_slack) result(ret)
type(event), pointer :: my_event
type(datetime), target :: my_datetime
@@ -2120,25 +2490,61 @@ contains
end if
end function isCurrentEventActive
- !
+ !>
+ !! @brief Checks, if next event is on a new day
+ !!
+ !! @param[in] my_event
+ !! A pointer to a type event
+ !!
+ !! @returns ret
+ !! Logical: true if next event is on new day
function iseventNextInNextDays(my_event) result(ret)
type(event), pointer :: my_event
logical(c_bool) :: ret
ret = my_iseventnextinnextdays(c_loc(my_event))
end function iseventNextInNextDays
- !
+ !>
+ !! @brief Checks, if next event is in a new month
+ !!
+ !! @param[in] my_event
+ !! A pointer to a type event
+ !!
+ !! @returns ret
+ !! Logical: true if next event is in a new month
function iseventNextInNextMonths(my_event) result(ret)
type(event), pointer :: my_event
logical(c_bool) :: ret
ret = my_iseventnextinnextmonths(c_loc(my_event))
end function iseventNextInNextMonths
- !
+ !>
+ !! @brief Checks, if next event is in a new year
+ !!
+ !! @param[in] my_event
+ !! A pointer to a type event
+ !!
+ !! @returns ret
+ !! Logical: true if next event is in a new year
function iseventNextInNextYears(my_event) result(ret)
type(event), pointer :: my_event
logical(c_bool) :: ret
ret = my_iseventnextinnextyears(c_loc(my_event))
end function iseventNextInNextYears
- !
+ !>
+ !! @brief Get the Datetime when 'this' event will be triggered next.
+ !!
+ !! WARNING: The value returned is with-respect-to current_dt and not
+ !! a true copy of triggerNextEventDateTime in the event
+ !! data structure.
+ !!
+ !! @param[in] my_event
+ !! A pointer to type event. This is the event being queried.
+ !!
+ !! @param[in] my_currentdatetime
+ !! A pointer to type datetime. The next trigger datetime is copied here.
+ !!
+ !! @param[out] my_datetime
+ !! A pointer to type datetime with next-trigger datetime.
+ !!
!! @param[out] errno optional, error message
subroutine getTriggerNextEventAtDateTime(my_event,my_currentdatetime,my_datetime, errno)
type(event), target, intent(in) :: my_event
@@ -2150,7 +2556,18 @@ contains
dummy_ptr = my_gettriggernexteventatdatetime(c_loc(my_event),c_loc(my_currentdatetime),c_loc(my_datetime))
if ((.not.c_associated(dummy_ptr)) .and. present(errno)) errno = 6 * 100 + 8
end subroutine getTriggerNextEventAtDateTime
- !
+ !>
+ !! @brief Get the Datetime when 'this' event will be triggered last.
+ !!
+ !! NOTE: If the event was never tiggered, default value of
+ !! 0-01-01T00:00:00.000 is returned.
+ !!
+ !! @param[in] my_event
+ !! A pointer to type event. This is the event being queried.
+ !!
+ !! @param[out] my_datetime
+ !! A pointer to type datetime with last-trigger datetime.
+ !!
!! @param[out] errno optional, error message
subroutine getTriggeredPreviousEventAtDateTime(my_event,my_datetime,errno)
type(event), target, intent(in) :: my_event
@@ -2161,13 +2578,28 @@ contains
dummy_ptr = my_gettriggeredpreviouseventatdatetime(c_loc(my_event),c_loc(my_datetime))
if ((.not.c_associated(dummy_ptr)) .and. present(errno)) errno = 6 * 100 + 9
end subroutine getTriggeredPreviousEventAtDateTime
- !
+ !>
+ !! @brief get the event id
+ !!
+ !! @param[in] my_event
+ !! A pointer of type event.
+ !!
+ !! @returns ret_evtid
+ !! the event id
+ !!
function getEventId(my_event) result(ret_evtid) !OK-TESTED.
integer(c_int64_t) :: ret_evtid
type(event), pointer :: my_event
ret_evtid = my_event%eventId
end function getEventId
- !
+ !>
+ !! @brief get the event name
+ !!
+ !! @param[in] my_event
+ !! A pointer of type event.
+ !!
+ !! @param[out] string the name of the event
+ !!
!! @param[out] errno optional, error message
subroutine getEventName(my_event, string, errno) !OK-TESTED.
type(event), pointer :: my_event
@@ -2183,7 +2615,15 @@ contains
end do char_loop
string(i:len(string)) = ' '
end subroutine getEventName
- !
+ !>
+ !! @brief get the event reference date
+ !!
+ !! @param[in] my_event
+ !! A pointer of type event.
+ !!
+ !! @returns ret_referenceDateTime
+ !! A pointer of type datetime. The event's reference date.
+ !!
function getEventReferenceDateTime(my_event) result(ret_referenceDateTime) !OK-TESTED.
type(datetime), pointer :: ret_referenceDateTime
type(event), pointer :: my_event
@@ -2195,7 +2635,15 @@ contains
ret_referenceDateTime => null()
endif
end function getEventReferenceDateTime
- !
+ !>
+ !! @brief get the event first date
+ !!
+ !! @param[in] my_event
+ !! A pointer of type event.
+ !!
+ !! @returns ret_eventFirstDateTime
+ !! A pointer of type datetime. The event's first date.
+ !!
function getEventFirstDateTime(my_event) result(ret_eventFirstDateTime) !OK-TESTED.
type(datetime), pointer :: ret_eventFirstDateTime
type(event), pointer :: my_event
@@ -2207,7 +2655,15 @@ contains
ret_eventFirstDateTime => null()
endif
end function getEventFirstDateTime
- !
+ !>
+ !! @brief get the event last date
+ !!
+ !! @param[in] my_event
+ !! A pointer of type event.
+ !!
+ !! @returns ret_eventLastDateTime
+ !! A pointer of type datetime. The event's last date.
+ !!
function getEventLastDateTime(my_event) result(ret_eventLastDateTime) !OK-TESTED.
type(datetime), pointer :: ret_eventLastDateTime
type(event), pointer :: my_event
@@ -2219,7 +2675,15 @@ contains
ret_eventLastDateTime => null()
endif
end function getEventLastDateTime
- !
+ !>
+ !! @brief get the event interval
+ !!
+ !! @param[in] my_event
+ !! A pointer of type event.
+ !!
+ !! @returns ret_eventInterval
+ !! A pointer of type timedelta. The event's last date.
+ !!
function getEventInterval(my_event) result(ret_eventInterval) !OK-TESTED.
type(timedelta), pointer :: ret_eventInterval
type(event), pointer :: my_event
@@ -2231,43 +2695,100 @@ contains
ret_eventInterval => null()
endif
end function getEventInterval
- !
+ !>
+ !! @brief Check if event is first
+ !!
+ !! @param[in] my_event
+ !! A pointer of type event.
+ !!
+ !! @returns ret
+ !! Logical: true if event is first
+ !!
function getNextEventIsFirst(my_event) result(ret)
type(event), target, intent(in) :: my_event
logical(c_bool) :: ret
ret = my_getnexteventisfirst(c_loc(my_event))
end function getNextEventIsFirst
- !
+ !>
+ !! @brief Check if event is first in day
+ !!
+ !! @param[in] my_event
+ !! A pointer of type event.
+ !!
+ !! @returns ret
+ !! Logical: true if event is first in day
+ !!
function getEventisFirstInDay(my_event) result(ret)
type(event), target, intent(in) :: my_event
logical(c_bool) :: ret
ret = my_geteventisfirstinday(c_loc(my_event))
end function getEventisFirstInDay
- !
+ !>
+ !! @brief Check if event is first in month
+ !!
+ !! @param[in] my_event
+ !! A pointer of type event.
+ !!
+ !! @returns ret
+ !! Logical: true if event is first in month
+ !!
function getEventisFirstInMonth(my_event) result(ret)
type(event), target, intent(in) :: my_event
logical(c_bool) :: ret
ret = my_geteventisfirstinmonth(c_loc(my_event))
end function getEventisFirstInMonth
- !
+ !>
+ !! @brief Check if event is first in year
+ !!
+ !! @param[in] my_event
+ !! A pointer of type event.
+ !!
+ !! @returns ret
+ !! Logical: true if event is first in year
+ !!
function getEventisFirstInYear(my_event) result(ret)
type(event), target, intent(in) :: my_event
logical(c_bool) :: ret
ret = my_geteventisfirstinyear(c_loc(my_event))
end function getEventisFirstInYear
- !
+ !>
+ !! @brief Check if event is last in day
+ !!
+ !! @param[in] my_event
+ !! A pointer of type event.
+ !!
+ !! @returns ret
+ !! Logical: true if event is last in day
+ !!
+
function getEventisLastInDay(my_event) result(ret)
type(event), target, intent(in) :: my_event
logical(c_bool) :: ret
ret = my_geteventislastinday(c_loc(my_event))
end function getEventisLastInDay
- !
+ !>
+ !! @brief Check if event is last in month
+ !!
+ !! @param[in] my_event
+ !! A pointer of type event.
+ !!
+ !! @returns ret
+ !! Logical: true if event is last in month
+ !!
function getEventisLastInMonth(my_event) result(ret)
type(event), target, intent(in) :: my_event
logical(c_bool) :: ret
ret = my_geteventislastinmonth(c_loc(my_event))
end function getEventisLastInMonth
- !
+ !>
+ !! @brief Check if event is last in year
+ !!
+ !! @param[in] my_event
+ !! A pointer of type event.
+ !!
+ !! @returns ret
+ !! Logical: true if event is last in year
+ !!
function getEventisLastInYear(my_event) result(ret)
type(event), target, intent(in) :: my_event
logical(c_bool) :: ret
@@ -2354,8 +2875,17 @@ module mtime_eventgroups
!> @endcond DOXYGEN_IGNORE_THIS
!
contains
- !
- !! @param[out] errno optional, error message
+ !>
+ !! @brief Construct new event-Group using a string.
+ !!
+ !! @param[in] name
+ !! This string contains the name of event group.
+ !!
+ !! @param[out] errno optional, error message
+ !!
+ !! @return ret_eventgroup
+ !! A pointer to an initialized event-Group.
+ !!
function newEventGroup(name, errno) result(ret_eventgroup) !OK-TESTED.
type(eventgroup), pointer :: ret_eventgroup
character(len=*), intent(in) :: name
@@ -2366,34 +2896,73 @@ contains
if ((.not. c_associated(c_pointer)) .and. present(errno)) errno = 7 * 100 + 1
call c_f_pointer(c_pointer, ret_eventgroup)
end function newEventGroup
- !
+ !>
+ !! @brief Destructor of EventGroup.
+ !!
+ !! @param[in] my_eventgroup
+ !! A pointer to type eventGroup. my_eventgroup is deallocated.
+ !!
subroutine deallocateEventGroup(my_eventgroup) !OK-TESTED.
type(eventgroup), pointer :: my_eventgroup
call my_deallocateeventgroup(c_loc(my_eventgroup))
my_eventgroup => null()
end subroutine deallocateEventGroup
- !
- function addEventToEventGroup(my_event, my_eventGroup) result(ret) !OK-TESTED.
+ !>
+ !! @brief Add new event to an eventgroup.
+ !!
+ !! @param my_event
+ !! A pointer to type event. The event to be added.
+ !!
+ !! @param my_eventgroup
+ !! A pointer to type eventgroup. The eventgroup where the event is added.
+ !!
+ !! @return ret
+ !! true/false indicating success or failure of addition.
+ function addEventToEventGroup(my_event, my_eventgroup) result(ret) !OK-TESTED.
logical :: ret
type(event), pointer :: my_event
type(eventgroup), pointer :: my_eventgroup
ret = my_addeventtoeventgroup(c_loc(my_event), c_loc(my_eventgroup))
end function addEventToEventGroup
- !
- function removeEventfromEventGroup(my_name, my_eventGroup) result(ret) !OK-TESTED.
+ !>
+ !! @brief Remove event from eventgroup. CRITICAL: Also, deallocate the event.
+ !!
+ !! @param my_name
+ !! The name of event to be removed.
+ !!
+ !! @param my_eventgroup
+ !! A pointer to type eventgroup. The eventgroup to which this event belongs.
+ !!
+ !! @return ret
+ !! true/false indicating success or failure of removal.
+ function removeEventfromEventGroup(my_name, my_eventgroup) result(ret) !OK-TESTED.
logical :: ret
character(len=*), intent(in) :: my_name
type(eventgroup), pointer :: my_eventgroup
ret = my_removeeventfromeventgroup(trim(adjustl(my_name))//c_null_char, c_loc(my_eventgroup))
end function removeEventFromEventGroup
- !
+ !>
+ !! @brief Get event group id
+ !!
+ !! @param[in] my_eventgroup
+ !! A pointer to type eventgroup.
+ !!
+ !! @return ret_grpid
+ !! The event group id
function getEventGroupId(my_eventgroup) result(ret_grpid) !OK-TESTED.
integer(c_int64_t) :: ret_grpid
type(eventgroup), pointer :: my_eventgroup
ret_grpid = my_eventgroup%eventGroupId
end function getEventGroupId
- !
- !! @param[out] errno optional, error message
+ !>
+ !! @brief get the event group name
+ !!
+ !! @param[in] my_eventgroup
+ !! A pointer of type event.
+ !!
+ !! @param[out] string the name of the event group
+ !!
+ !! @param[out] errno optional, error message
subroutine getEventGroupName(my_eventgroup, string, errno) !TESTED-OK.
type(eventgroup), pointer :: my_eventgroup
character(len=max_groupname_str_len) :: string
@@ -2408,7 +2977,14 @@ contains
end do char_loop
string(i:len(string)) = ' '
end subroutine getEventGroupName
- !
+ !>
+ !! @brief get the first event in event group
+ !!
+ !! @param[in] my_eventgroup
+ !! A pointer of type eventgroup.
+ !!
+ !! @returns ret_event
+ !! A pointer of type event. The first event in eventgroup
function getFirstEventFromEventGroup(my_eventgroup) result(ret_event) !OK-TESTED.
type(event), pointer :: ret_event
type(eventgroup), pointer :: my_eventgroup
@@ -2420,7 +2996,14 @@ contains
ret_event => null()
endif
end function getFirstEventFromEventGroup
- !
+ !>
+ !! @brief get the next event in an event group an event belongs to
+ !!
+ !! @param[in] my_event
+ !! A pointer of type event.
+ !!
+ !! @returns ret_event
+ !! A pointer of type event. The next event in eventgroup
function getNextEventFromEventGroup(my_event) result(ret_event) !OK-TESTED.
type(event), pointer :: ret_event
type(event), pointer :: my_event
@@ -2481,13 +3064,45 @@ module mtime_utilities
!> @endcond DOXYGEN_IGNORE_THIS
!
contains
- !
+ !>
+ !! @brief Extract number of repetitions from repetition string part.
+ !!
+ !! @param[in] repetitionString
+ !! A repetition string starting with 'R'.
+ !! A string literal can be accepted.
+ !!
+ !! @return r
+ !! An int representing the number of repetitions.
+ !!
function getRepetitions(repetitionString) RESULT(r)
integer :: r
character(len=*), intent(in) :: repetitionString
r = my_getRepetitions(trim(adjustl(repetitionString))//c_null_char)
end function getRepetitions
- !
+ !>
+ !! @brief Split ISO 8601:2004 repeated time interval strings into base components
+ !!
+ !! @param[in] recurringTimeInterval
+ !! The string should contain an ISO 8601:2004 repeated time
+ !! interval string.
+ !! A string literal can be accepted.
+ !! @param[out] repetitor
+ !! Contains the repetitor part of the input string.
+ !! @param[out] start
+ !! Contains the start date part of the input string.
+ !! @param[out] end
+ !! Contains the end date part of the input string.
+ !! @param[out] duration
+ !! Contains the duration part of the input string.
+ !! @param[out] lrepetitor
+ !! Logical: true, if repetion is available
+ !! @param[out] lstart
+ !! Logical: true, if start is available
+ !! @param[out] lend
+ !! Logical: true, if end is available
+ !! @param[out] lduration
+ !! Logical: true, if duration is available
+ !!
subroutine splitRepetitionString(recurringTimeInterval, repetitor, start, end, duration, lrepetitor, lstart, lend, lduration)
character(len=*), intent(in) :: recurringTimeInterval
character(len=*), intent(out) :: repetitor
@@ -2648,8 +3263,11 @@ module mtime
!> @endcond DOXYGEN_IGNORE_THIS
!
contains
- !
+ !>
+ !! @brief returns error emssage associated to error number of mtime
+ !!
!! @param[in] errno error message number
+ !!
!! @param[out] error_message associated error message
subroutine mtime_strerror(errno, error_message)
integer, intent(in) :: errno