Processing of secondsSinceEpoch and its reverse processing routine. (#80)

* Added reverse processing of `secondsSinceEpoch`

- Fixed `secondsSinceEpoch` so that the result of `secondsSinceEpoch`
  is similar to the output of the C `mktime` function when the timezone
  is non-zero.
- Added procedures to converd the result of `secondsSinceEpoch` back to
  tm structure and datetime type.

* localtime and gmtime rewritten in fortran

To improve portability between operating systems, C language's localtime_r
and  gmtime_r functions were rewritten as fortran functions with the
same behavior.

* fix typo and improve thread-safety

Fixed spelling errors.
”function localtime" is revised to a "pure elemental function localtime"

* Added explanation of new code.

* Tidy up docs

* Remove unused code

* Bump minor version

* Update contributors list

---------

Co-authored-by: milancurcic <[email protected]>

Author: sakamoti

Diff for: .gitignore

@@ -24,3 +24,6 @@ src/tests/test-suite.log
 src/tests/tests-env.sh.log
 src/tests/tests-env.sh.trs
 test-driver
+
+docs
+clang

Diff for: CMakeLists.txt

@@ -6,7 +6,7 @@ endif()
 
 project(datetime-fortran
 LANGUAGES Fortran
-VERSION 1.7.0)
+VERSION 1.8.0)
 include(CTest)
 
 include(cmake/check_strptime.cmake)

Diff for: CONTRIBUTORS.md

@@ -12,3 +12,4 @@
 * [Stefano Zaghi](https://github.com/szaghi)
 * [Tom Canich](https://github.com/tcanich)
 * [Wadud Miah](https://github.com/wadudmiah)
+* [Yuichiro Sakamoto](https://github.com/sakamoti)

Diff for: README.md

@@ -139,6 +139,10 @@ See some basic examples [here](examples).
     * [*num2date*](#num2date)
     * [*strptime*](#strptime)
     * [*tm2date*](#tm2date)
+    * [*machinetimezone*](#machinetimezone)
+    * [*epochdatetime*](#epochdatetime)
+    * [*localtime*](#localtime)
+    * [*gmtime*](#gmtime)
 
 ## Derived Types<a id="derived-types"></a>
 
@@ -1654,6 +1658,7 @@ necessary steps.
 * [*tm2date*](#tm2date)
 
 [Back to top](#top)
+<hr>
 
 ### tm2date
 
@@ -1687,5 +1692,155 @@ See example usage for [*strptime*](#strptime).
 
 * [*strptime*](#strptime)
 
+### machinetimezone
+
+```fortran
+real(real64) function machinetimezone()
+```
+
+returns the machine's time zone in hours.
+
+#### Arguments
+
+None
+
+#### Return value
+
+`real(real64)` A `tz` value.
+
+#### Example usage
+
+Extracting your local machine's time zone information.
+
+```fortran
+type(datetime) :: date
+date = datetime(1970, 1, 1, tz=machinetimezone())
+```
+
+#### See also
+
+* [*datetime*](#datetime)
+
+* [*localtime*](#localtime)
+
+* [*gmtime*](#gmtime)
+
+[Back to top](#top)
+<hr>
+
+### epochdatetime
+
+```fortran
+pure elemental type(datetime) function epochdatetime()
+    epochdatetime = datetime(1970,1,1,0,0,0,0,tz=0.)
+```
+returns a `datetime` that corresponds to the UNIX epoch.
+
+#### Arguments
+
+None
+
+#### Return value
+
+`type(datetime)` A `datetime(1970,1,1,0,0,0,0,tz=0.0)` value.
+
+#### Example usage
+
+```fortran
+type(datetime) :: epochday
+epochday = epochdatetime()
+```
+
+#### See also
+
+* [*datetime*](#datetime)
+
+* [*localtime*](#localtime)
+
+* [*gmtime*](#gmtime)
+
+[Back to top](#top)
+<hr>
+
+### localtime
+
+```fortran
+  pure elemental type(datetime) function localtime(epoch, tz)
+    ! Returns a `datetime` instance from epoch.
+    ! tz can be obtained from `machinetimezone`
+    integer(int64),intent(in) :: epoch
+    real(real64),intent(in) :: tz !! local machine time zone information
+```
+Generating a *datetime* type from epoch and timezone.
+
+#### Arguments
+
+`epoch` A epoch time (second)
+
+`tz` A time zone (hour). This value can be generated by using [*machinetimezone*](#machinetimezone)
+
+#### Return value
+
+`type(datetime)` A `datetime` instance.
+
+#### Example usage
+
+Convert the epoch seconds to an expression in your machine's time zone.
+
+```fortran
+integer(int64), parameter :: epoch = 3600
+real(real64) :: tz
+type(datetime) :: date
+tz = machinetimezone()
+date = localtime(epoch, tz)
+```
+
+#### See also
+
+* [*datetime*](#datetime)
+
+* [*machinetimezone*](#machinetimezone)
+
+* [*gmtime*](#gmtime)
+
+[Back to top](#top)
+<hr>
+
+### gmtime
+
+```fortran
+  pure elemental type(datetime) function gmtime(epoch)
+    ! Returns a `datetime` instance from epoch.
+    integer(int64),intent(in) :: epoch
+```
+Generating a *datetime* type from epoch.
+
+#### Arguments
+
+`epoch` A epoch time (second)
+
+#### Return value
+
+`type(datetime)` A `datetime` instance.
+Result is represented with UTC time.
+
+#### Example usage
+
+Convert the epoch seconds to an expression in UTC time zone.
+
+```fortran
+integer(int64) :: epoch = 3600
+type(datetime) :: day
+day = gmtime(epoch)
+```
+
+#### See also
+
+* [*datetime*](#datetime)
+
+* [*machinetimezone*](#machinetimezone)
+
+* [*localtime*](#localtime)
+
 [Back to top](#top)
 <hr>

Diff for: VERSION

@@ -1 +1 @@
-1.7.1
+1.8.0

Diff for: fpm.toml

@@ -1,6 +1,6 @@
 name = "datetime"
-version = "1.7.1"
+version = "1.8.0"
 license = "MIT"
 author = "Milan Curcic"
 maintainer = "[email protected]"
-copyright = "2013-2020 datetime-fortran contributors"
+copyright = "2013-2023 datetime-fortran contributors"

Diff for: src/datetime_module.f90

@@ -2,7 +2,7 @@ module datetime_module
 
   use, intrinsic :: iso_fortran_env, only: int64, real32, real64, &
                                            stderr => error_unit
-  use, intrinsic :: iso_c_binding, only: c_char, c_int, c_null_char, c_associated, C_PTR
+  use, intrinsic :: iso_c_binding, only: c_char, c_int, c_int64_t, c_null_char, c_associated, C_PTR
 
   implicit none
 
@@ -15,7 +15,11 @@ module datetime_module
   public :: daysInYear
   public :: isLeapYear
   public :: num2date
+  public :: machinetimezone
   public :: strptime
+  public :: epochdatetime
+  public :: localtime
+  public :: gmtime
   public :: tm2date
   public :: tm_struct
   public :: c_strftime
@@ -178,7 +182,7 @@ module datetime_module
 
   interface
 
-    type(C_PTR) function c_strftime(str, slen, format, tm) bind(c, name='strftime')
+    type(c_ptr) function c_strftime(str, slen, format, tm) bind(c, name='strftime')
       ! Returns a formatted time string, given input time struct and format.
       ! See https://www.cplusplus.com/reference/ctime/strftime for reference.
       import :: c_char, c_int, tm_struct, C_PTR
@@ -644,13 +648,34 @@ integer(int64) function secondsSinceEpoch(self)
     class(datetime), intent(in) :: self
     type(timedelta) :: delta
     type(datetime) :: this_time, unix_time
+    integer :: sign, hours, minutes, tzsec
 
     this_time = datetime(self%year, self%month, self%day, &
                          self%hour, self%minute, self%second)
     unix_time = datetime(1970, 1, 1, 0, 0, 0)
     delta = this_time - unix_time
     secondsSinceEpoch = delta%total_seconds()
 
+    if(self % tz == 0_real64) return
+
+    ! affect timezone information
+    if(self % tz < 0_real64) then
+      sign = -1
+    else
+      sign =  1
+    end if
+
+    hours = int(abs(self % tz))
+    minutes = nint((abs(self % tz) - hours) * 60)
+
+    if (minutes == 60) then
+      minutes = 0
+      hours = hours + 1
+    end if
+
+    tzsec = sign * (hours * h2s + minutes)
+    secondsSinceEpoch = secondsSinceEpoch - tzsec
+
   end function secondsSinceEpoch
 
 
@@ -1098,25 +1123,88 @@ pure elemental type(datetime) function num2date(num)
   end function num2date
 
 
-  type(datetime) function strptime(str,format)
+  real(real64) function machinetimezone()
+    ! Return a real value instance of local machine's timezone.
+    character(len=5) :: zone
+    integer :: values(8)
+    integer :: hour, minute
+
+    ! Obtain local machine time zone information
+    call date_and_time(zone=zone, values=values)
+    read(zone(1:3), '(i3)') hour
+    read(zone(4:5), '(i2)') minute
+
+    if(hour<0)then
+      machinetimezone = real(hour, kind=real64) - real(minute, kind=real64) * m2h
+    else
+      machinetimezone = real(hour, kind=real64) + real(minute, kind=real64) * m2h
+    end if
+  end function machinetimezone
+
+
+  type(datetime) function strptime(str,format,tz)
     ! A wrapper function around C/C++ strptime function.
     ! Returns a `datetime` instance.
     character(*), intent(in) :: str, format
+    real(real64), intent(in), optional :: tz
     integer :: rc
     type(tm_struct) :: tm
     rc = c_strptime(trim(str) // c_null_char, trim(format) // c_null_char, tm)
     if (rc == 0) then
       write(stderr, *) "ERROR:datetime:strptime: failed to parse string: ", str
       return
     endif
-    strptime = tm2date(tm)
+    strptime = tm2date(tm,tz)
   end function strptime
 
 
-  pure elemental type(datetime) function tm2date(ctime)
+  pure elemental type(datetime) function epochdatetime()
+      epochdatetime = datetime(1970,1,1,0,0,0,0,tz=zero)
+  end function epochdatetime
+
+
+  pure elemental type(datetime) function localtime(epoch, tz)
+    ! Returns a `datetime` instance from epoch.
+    ! tz can be obtained from `machinetimezone`
+    integer(int64),intent(in) :: epoch
+    real(real64),intent(in) :: tz !! local machine time zone information
+    type(datetime) :: datetime_from_epoch
+    type(timedelta) :: td
+    integer :: day, sec
+    integer(int64) :: localseconds
+
+    datetime_from_epoch = epochdatetime()
+
+    localseconds = nint(tz * h2s) + epoch
+    !suppress overflow
+    day = floor(localseconds/d2s, kind=real32)
+    sec = localseconds - day * d2s
+    td = timedelta(days=day, seconds=sec)
+    datetime_from_epoch % tz = tz
+    localtime = datetime_from_epoch + td
+  end function localtime
+
+
+  pure elemental type(datetime) function gmtime(epoch)
+    ! Returns a `datetime` instance from epoch.
+    integer(int64),intent(in) :: epoch
+    type(datetime) :: datetime_from_epoch
+    type(timedelta) :: td
+    integer :: day, sec
+    datetime_from_epoch = epochdatetime()
+    !suppress overflow
+    day = floor(epoch/d2s, kind=real32)
+    sec = epoch - day * d2s
+    td = timedelta(days=day, seconds=sec)
+    gmtime = datetime_from_epoch + td
+  end function gmtime
+
+
+  pure elemental type(datetime) function tm2date(ctime, tz)
     ! Given a `tm_struct` instance, returns a corresponding `datetime`
     ! instance.
     type(tm_struct), intent(in) :: ctime
+    real(real64), intent(in), optional :: tz ! time zone
 
     tm2date % millisecond = 0
     tm2date % second      = ctime % tm_sec
@@ -1125,7 +1213,17 @@ pure elemental type(datetime) function tm2date(ctime)
     tm2date % day         = ctime % tm_mday
     tm2date % month       = ctime % tm_mon+1
     tm2date % year        = ctime % tm_year+1900
-    tm2date % tz          = 0
+
+    ! tm_struct have no information of timze zone.
+    ! but if you run this library with C language's time.h,
+    ! localtime function deals system's timezone.
+    ! So, if you want to similar way, you can set tz value with
+    ! this library's `machinetimezone` function.
+    if(present(tz))then
+      tm2date % tz        = tz
+    else
+      tm2date % tz        = 0.0_real64
+    end if
 
   end function tm2date