eosiolib extension type: Time

The EOS white paper says that he wants to build a distributed system similar to an operating system. And our contract is like software running on the operating system. So what is the
most commonly used time element when we write programs ?

Look at time.hpp in eosiolib.

Get Time

You need to look at the file "system.h" before looking at time.hpp. Two functions for obtaining time are defined in this file:

uint64_t  current_time();

/**
*  Returns the time in seconds from 1970 of the block including this action
*  @brief Get time (rounded down to the nearest second) of the current block (i.e. the block including this action)
*  @return time in seconds from 1970 of the current block
*/
uint32_t  now() {
  return (uint32_t)( current_time() / 1000000 );
}

Used to get the current timestamp (the time in the past from the 1970 Unix epoch to the present). The unit of the former is milliseconds and the unit of the latter is seconds.

Time unit representation

The time obtained above is represented by uint64 and uint32. If you have read the article on floating point and currency units discussed above, you will naturally think that a unified quantity is needed to represent time, otherwise it
will change when calculating time very complicated. In the EOS system, time_point is used to indicate milliseconds, and time_point_sec is used to indicate seconds.

microseconds

First look at a definition:

class microseconds {

    int64_t _count;
    EOSLIB_SERIALIZE( microseconds, (_count) )
}

The millisecond is actually an int64. It's just that this int64 has been overloaded with n operators to realize its time calculation. There is no difference between the overloaded operator and int64 itself. The only addition is the conversion to seconds:

    int64_t to_seconds()const { return _count/1000000; }  

time_point

Conventional class:

  class time_point {
          microseconds elapsed;
        EOSLIB_SERIALIZE( time_point, (elapsed) )
  };          

It can be considered as a redefinition of milliseconds. If milliseconds are used in EOS contracts, this class is generally used, which is essentially an int64. But more than microseconds:

    const microseconds& time_since_epoch()const { return elapsed; }
    uint32_t            sec_since_epoch()const  { return uint32_t(elapsed.count() / 1000000); }

To get the unit epoch time mentioned above.

In addition, there is a tool for converting time from standard strings:

    operator std::string()const;
    static time_point from_iso_string( const std::string& s );  

A unified time string format is specified in ISO-8601 . similar:

"2009-W01-1"
2007-03-01T13:00:00Z/2008-05-11T15:30:00Z
P1Y2M10DT2H30M/2008-05-11T15:30:00Z

Wait, we often see "2018-08-21T11:31:36.000" in Block. So if you need to pass the time in the cloes command, this format is generally used.

time_point_sec

It can also be deduced from the literal meaning: time_point_sec is the structure of time_point representing seconds:

class time_point_sec
{
    uint32_t utc_seconds;

    EOSLIB_SERIALIZE( time_point_sec, (utc_seconds) )
}；

Operation

In addition to the above definitions, these two time_points mainly define the arithmetic operations between each other. So we don't need to manually go to *1000 or /1000.

//time_point
    time_point&  operator += ( const microseconds& m)                           { elapsed+=m; return *this;                 }
    time_point&  operator -= ( const microseconds& m)                           { elapsed-=m; return *this;                 }
    time_point   operator + (const microseconds& m) const { return time_point(elapsed+m); }
    time_point   operator + (const time_point& m) const { return time_point(elapsed+m.elapsed); }
    time_point   operator - (const microseconds& m) const { return time_point(elapsed-m); }
    microseconds operator - (const time_point& m) const { return microseconds(elapsed.count() - m.elapsed.count()); }

//time_point_sec
    friend time_point   operator + ( const time_point_sec& t, const microseconds& m )   { return time_point(t) + m;             }
    friend time_point   operator - ( const time_point_sec& t, const microseconds& m )   { return time_point(t) - m;             }
    friend microseconds operator - ( const time_point_sec& t, const time_point_sec& m ) { return time_point(t) - time_point(m); }
    friend microseconds operator - ( const time_point& t, const time_point_sec& m ) { return time_point(t) - time_point(m); }

The conversion between the two functions in the addition type realizes the addition and subtraction operation between the three data types.

block_timestamp

Except for the time above. We know that there is a time when querying block information, because the block is generated in 500ms, so the idx of the block also represents the time. Therefore, the block time is defined:

class block_timestamp {
    public:
        uint32_t slot;
        static constexpr int32_t block_interval_ms = 500;
        static constexpr int64_t block_timestamp_epoch = 946684800000ll;  // epoch is year 2000

        EOSLIB_SERIALIZE( block_timestamp, (slot) )
}  

In fact, it is the current number of blocks based on Unix epoch time.

Actual combat:

Time comparison

uint64_t starttime = "unit时间戳";
eosio::time_point_sec(starttime) > eosio::time_point_sec(now();

 Time addition and subtraction

uint64_t starttime = "unit时间戳";
#结果单位为秒
uint64_t t= (eosio::time_point_sec(starttime)-eosio::time_point_sec(now())).to_seconds();