Skip to content
Snippets Groups Projects
  • Timur Safin's avatar
    43e10ed3
    build, lua: built-in module datetime · 43e10ed3
    Timur Safin authored
    Introduce a new builtin Tarantool module `datetime.lua` for timestamp
    and interval types support.
    
    New third_party module - c-dt
    -----------------------------
    
    * Integrated chansen/c-dt parser as 3rd party module to the
      Tarantool cmake build process;
    * We use tarantool/c-dt instead of original chansen/c-dt to
      have an easier cmake build integration, as we have added some
      changes, which provide cmake support, and allow to rename symbols
      if necessary (this symbol renaming is similar to that we see
      with xxhash or icu).
    
    New built-in module `datetime`
    ------------------------------
    
    * created a new Tarantool built-in module `datetime`, which uses
      `struct datetime` data structure for keeping timestamp values;
    * Lua module uses a number of `dt_*` functions from `c-dt` library,
      but they were renamed to `tnt_dt_*` at the moment of exporting
      from executable - to avoid possible name clashes with external
      libraries.
    
    * At the moment we libc `strftime` for formatting of datetime
      values according to flags passed, i.e. `date:format('%FT%T%z')`
      will return something like '1970-01-01T00:00:00+0000', but
      `date:format('%A %d, %B %Y')` will return 'Thursday 01, January 1970'
    
    * if there is no format provided then we use default
      `tnt_datetime_to_string()` function, which converts datetime
      to their default ISO-8601 output format, i.e.
      `tostring(date)` will return string like "1970-01-01T00:00:00Z"
    
    * There are a number of simplified interfaces
      - totable() for exporting table with attributes names as provided
        by `os.date('*t')`
      - set() method provides unified interface to set values using
        the set of attributes as defined above in totable()
    
    Example,
    
    ```
    local dt = datetime.new {
    	nsec      = 123456789,
    
    	sec       = 19,
    	min       = 29,
    	hour      = 18,
    
    	day       = 20,
    	month     = 8,
    	year      = 2021,
    
    	tzoffset  = 180
    }
    
    local t = dt:totable()
    --[[
    {
    	sec = 19,
    	min = 29,
    	wday = 6,
    	day = 20,
    	nsec = 123456789,
    	isdst = false,
    	yday = 232,
    	tzoffset = 180,
    	month = 8,
    	year = 2021,
    	hour = 18
    }
    --]]
    
    dt:format()   -- 2021-08-21T14:53:34.032Z
    dt:format('%Y-%m-%dT%H:%M:%S')   -- 2021-08-21T14:53:34
    
    dt:set {
    	usec      = 123456,
    
    	sec       = 19,
    	min       = 29,
    	hour      = 18,
    
    	day       = 20,
    	month     = 8,
    	year      = 2021,
    
    	tzoffset  = 180,
    
    }
    dt:set {
    	timestamp = 1629476485.124,
    
    	tzoffset  = 180,
    }
    
    ```
    
    Coverage is
    
    File                 Hits Missed Coverage
    -----------------------------------------
    builtin/datetime.lua 299  23     92.86%
    -----------------------------------------
    Total                299  23     92.86%
    
    Part of #5941
    
    @TarantoolBot document
    Title: Introduced a new `datetime` module for timestamp and interval support
    
    Create `datetime` module for timestamp and interval types support.
    It allows to create date and timestamp values using either object interface,
    or via parsing of string values conforming to iso-8601 standard.
    One may manipulate (modify, subtract or add) timestamp and interval values.
    
    Please refer to https://hackmd.io/@Mons/S1Vfc_axK#Datetime-in-Tarantool
    for a more detailed description of module API.
    43e10ed3
    History
    build, lua: built-in module datetime
    Timur Safin authored
    Introduce a new builtin Tarantool module `datetime.lua` for timestamp
    and interval types support.
    
    New third_party module - c-dt
    -----------------------------
    
    * Integrated chansen/c-dt parser as 3rd party module to the
      Tarantool cmake build process;
    * We use tarantool/c-dt instead of original chansen/c-dt to
      have an easier cmake build integration, as we have added some
      changes, which provide cmake support, and allow to rename symbols
      if necessary (this symbol renaming is similar to that we see
      with xxhash or icu).
    
    New built-in module `datetime`
    ------------------------------
    
    * created a new Tarantool built-in module `datetime`, which uses
      `struct datetime` data structure for keeping timestamp values;
    * Lua module uses a number of `dt_*` functions from `c-dt` library,
      but they were renamed to `tnt_dt_*` at the moment of exporting
      from executable - to avoid possible name clashes with external
      libraries.
    
    * At the moment we libc `strftime` for formatting of datetime
      values according to flags passed, i.e. `date:format('%FT%T%z')`
      will return something like '1970-01-01T00:00:00+0000', but
      `date:format('%A %d, %B %Y')` will return 'Thursday 01, January 1970'
    
    * if there is no format provided then we use default
      `tnt_datetime_to_string()` function, which converts datetime
      to their default ISO-8601 output format, i.e.
      `tostring(date)` will return string like "1970-01-01T00:00:00Z"
    
    * There are a number of simplified interfaces
      - totable() for exporting table with attributes names as provided
        by `os.date('*t')`
      - set() method provides unified interface to set values using
        the set of attributes as defined above in totable()
    
    Example,
    
    ```
    local dt = datetime.new {
    	nsec      = 123456789,
    
    	sec       = 19,
    	min       = 29,
    	hour      = 18,
    
    	day       = 20,
    	month     = 8,
    	year      = 2021,
    
    	tzoffset  = 180
    }
    
    local t = dt:totable()
    --[[
    {
    	sec = 19,
    	min = 29,
    	wday = 6,
    	day = 20,
    	nsec = 123456789,
    	isdst = false,
    	yday = 232,
    	tzoffset = 180,
    	month = 8,
    	year = 2021,
    	hour = 18
    }
    --]]
    
    dt:format()   -- 2021-08-21T14:53:34.032Z
    dt:format('%Y-%m-%dT%H:%M:%S')   -- 2021-08-21T14:53:34
    
    dt:set {
    	usec      = 123456,
    
    	sec       = 19,
    	min       = 29,
    	hour      = 18,
    
    	day       = 20,
    	month     = 8,
    	year      = 2021,
    
    	tzoffset  = 180,
    
    }
    dt:set {
    	timestamp = 1629476485.124,
    
    	tzoffset  = 180,
    }
    
    ```
    
    Coverage is
    
    File                 Hits Missed Coverage
    -----------------------------------------
    builtin/datetime.lua 299  23     92.86%
    -----------------------------------------
    Total                299  23     92.86%
    
    Part of #5941
    
    @TarantoolBot document
    Title: Introduced a new `datetime` module for timestamp and interval support
    
    Create `datetime` module for timestamp and interval types support.
    It allows to create date and timestamp values using either object interface,
    or via parsing of string values conforming to iso-8601 standard.
    One may manipulate (modify, subtract or add) timestamp and interval values.
    
    Please refer to https://hackmd.io/@Mons/S1Vfc_axK#Datetime-in-Tarantool
    for a more detailed description of module API.