Document behavior of double precision outputs in ESMF_TimeGet and ESMF_TimeIntervalGet

[billsacks]

As discussed in https://github.com/esmf-org/esmf-support/issues/494, behavior differs for double precision outputs compared with integer outputs, and this wasn't documented.

This PR adds some unit tests to better characterize / demonstrate this behavior, and improves the documentation of this behavior.

Resolves https://github.com/esmf-org/esmf-support/issues/494

[billsacks]

In addition to the tests added in this PR, I ran some additional unit tests of both ESMF_TimeGet and ESMF_TimeIntervalGet:

(1) Additional tests of ESMF_TimeGet: These test the example given in the documentation (I wanted to confirm that I was getting things right in the documentation!), but I felt like these didn't add any meaningful code coverage beyond existing tests, so I didn't keep them in place:

diff --git a/src/Infrastructure/TimeMgr/tests/ESMF_TimeUTest.F90 b/src/Infrastructure/TimeMgr/tests/ESMF_TimeUTest.F90
index 90c8520781..05157114f8 100644
--- a/src/Infrastructure/TimeMgr/tests/ESMF_TimeUTest.F90
+++ b/src/Infrastructure/TimeMgr/tests/ESMF_TimeUTest.F90
@@ -64,7 +64,7 @@ program ESMF_TimeUTest
       character(18) :: timeString18
 
       ! instantiate start time
-      type(ESMF_Time) :: startTime
+      type(ESMF_Time) :: startTime, testTime
       type(ESMF_Calendar) :: gregorianCalendar, julianCalendar, &
                              julianDayCalendar, modifiedJulianDayCalendar, &
                              noLeapCalendar, day360Calendar
@@ -213,6 +213,32 @@ program ESMF_TimeUTest
                       M==737 .and. S==58 .and. &
                       rc==ESMF_SUCCESS), name, failMsg, result, ESMF_SRCLINE)
 
+      ! ----------------------------------------------------------------------------
+      !NEX_UTest
+      write(name, *) "Get Time Test from documentation"
+      write(failMsg, *) " Did not return correct time values or ESMF_SUCCESS"
+      call ESMF_TimeSet(testTime, yy=2004, mm=2, dd=2, h=2, m=0, s=0, &
+                                   calendar=gregorianCalendar, rc=rc)
+      call ESMF_TimeGet(testTime, dd=DD, h=H, s=S, rc=rc)
+      print *, 'WJS: DD, H, S = ', DD, H, S
+      call ESMF_Test((DD==2 .and. H==2 .and. S==0 .and. rc==ESMF_SUCCESS), name, failMsg, result, ESMF_SRCLINE)
+
+      ! ----------------------------------------------------------------------------
+      !NEX_UTest
+      write(name, *) "Get Time Test from documentation: h_r8"
+      write(failMsg, *) " Did not return correct time values or ESMF_SUCCESS"
+      call ESMF_TimeGet(testTime, dd=DD, h_r8=H_r8, s=S, rc=rc)
+      print *, 'WJS: DD, H_r8, S = ', DD, H_r8, S
+      call ESMF_Test((DD==2 .and. H_r8==2.d0 .and. S==7200 .and. rc==ESMF_SUCCESS), name, failMsg, result, ESMF_SRCLINE)
+
+      ! ----------------------------------------------------------------------------
+      !NEX_UTest
+      write(name, *) "Get Time Test from documentation: s_r8"
+      write(failMsg, *) " Did not return correct time values or ESMF_SUCCESS"
+      call ESMF_TimeGet(testTime, dd=DD, h=H, s_r8=S_r8, rc=rc)
+      print *, 'WJS: DD, H, S_r8 = ', DD, H, S_r8
+      call ESMF_Test((DD==2 .and. H==2 .and. S_r8==7200.d0 .and. rc==ESMF_SUCCESS), name, failMsg, result, ESMF_SRCLINE)
+
       ! ----------------------------------------------------------------------------
       !NEX_UTest
 

(2) Additional tests of ESMF_TimeIntervalGet: These tests are similar to the tests I added for ESMF_TimeGet. I think this exercises the same underlying code as the ESMF_TimeGet tests, so I felt these tests weren't worth keeping (because I don't think they actually improve code coverage significantly), but I wanted to double-check that my understanding was right that the ESMF_TimeIntervalGet logic is the same as ESMF_TimeGet in this respect:

diff --git a/src/Infrastructure/TimeMgr/tests/ESMF_TimeIntervalUTest.F90 b/src/Infrastructure/TimeMgr/tests/ESMF_TimeIntervalUTest.F90
index ad2669cd28..[3618133257](tel:3618133257) 100644
--- a/src/Infrastructure/TimeMgr/tests/ESMF_TimeIntervalUTest.F90
+++ b/src/Infrastructure/TimeMgr/tests/ESMF_TimeIntervalUTest.F90
@@ -166,6 +166,44 @@ program ESMF_TimeIntervalUTest
       !print *,  "timeStep2.eq.timeStep = ", timeStep2.eq.timeStep
       !print *, "rc=", rc
       !print *, " yy,mm,d,h,m,s = ", YY, ",", MM, ",", D, ",", H, ",", M, ",", S
+
+      ! ----------------------------------------------------------------------------
+      !EX_UTest
+      write(name, *) "TimeInterval: real-valued time with int-valued date"
+      write(failMsg, *) "Did not return correct time values or ESMF_SUCCESS"
+      call ESMF_TimeIntervalGet(timeStep2, yy=YY, mm=MM, d=D, &
+                                h_r8=hr_out_r8, m_r8=min_out_r8, s_r8=sec_out_r8, rc=rc)
+      print *, 'WJS: real-valued time with int-valued date: YY, MM, D, hr, min, sec = ', YY, MM, D, hr_out_r8, min_out_r8, sec_out_r8
+      call ESMF_Test((YY==3 .and. MM==5 .and. D==30 .and. &
+                      abs(hr_out_r8 - 7.138333333333334d0) < 1d-14 .and. &
+                      abs(min_out_r8 - 428.3d0) < 1d-12 .and. &
+                      abs(sec_out_r8 - 25698.d0) < 1d-11 .and. &
+                      rc == ESMF_SUCCESS), name, failMsg, result, ESMF_SRCLINE)
+
+      ! ----------------------------------------------------------------------------
+      !EX_UTest
+      write(name, *) "TimeInterval: coarser int-valued and finer real-valued"
+      write(failMsg, *) "Did not return correct time values or ESMF_SUCCESS"
+      call ESMF_TimeIntervalGet(timeStep2, yy=YY, mm=MM, d=D, &
+                                h=H, m_r8=min_out_r8, s_r8=sec_out_r8, rc=rc)
+      call ESMF_Test((YY==3 .and. MM==5 .and. D==30 .and. &
+                      H == 7 .and. &
+                      abs(min_out_r8 - 428.3d0) < 1d-12 .and. &
+                      abs(sec_out_r8 - 25698.d0) < 1d-11 .and. &
+                      rc == ESMF_SUCCESS), name, failMsg, result, ESMF_SRCLINE)
+
+      ! ----------------------------------------------------------------------------
+      !EX_UTest
+      write(name, *) "TimeInterval: coarser real-valued and finer int-valued"
+      write(failMsg, *) "Did not return correct time values or ESMF_SUCCESS"
+      call ESMF_TimeIntervalGet(timeStep2, yy=YY, mm=MM, d=D, &
+                                h_r8=hr_out_r8, m=M, s=S, rc=rc)
+      call ESMF_Test((YY==3 .and. MM==5 .and. D==30 .and. &
+                      abs(hr_out_r8 - 7.138333333333334d0) < 1d-14 .and. &
+                      M == 428 .and. &
+                      S == 18 .and. &
+                      rc == ESMF_SUCCESS), name, failMsg, result, ESMF_SRCLINE)
+
       ! ----------------------------------------------------------------------------
       !EX_UTest
       ! Testing ESMF_TimeOperator(+)(time, timestep)

[billsacks]

To view the changes to the documentation in rendered form:

TimeGet: https://earthsystemmodeling.org/docs/nightly/document_timeget_reals/ESMF_refdoc/node6.html#SECTION060541100000000000000

TimeIntervalGet: https://earthsystemmodeling.org/docs/nightly/document_timeget_reals/ESMF_refdoc/node6.html#SECTION060641600000000000000