# Ptime

Introduction -- Header -- Construction -- Construct from String -- Construct from Clock -- Construct using Conversion functions -- Accessors -- Conversion To String -- Operators -- Struct tm, time_t, and FILETIME Functions

Introduction

The class boost::posix_time::ptime is the primary interface for time point manipulation. In general, the ptime class is immutable once constructed although it does allow assignment.

Class ptime is dependent on gregorian::date for the interface to the date portion of a time point.

Other techniques for creating times include time iterators.

Header

    #include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o
    or
    #include "boost/date_time/posix_time/posix_time_types.hpp" //no i/o just types

Construction

Syntax | Description
--- | ---
Example

    ptime(date,time_duration)

Construct from a date and offset

    ptime t1(date(2002,Jan,10),
             time_duration(1,2,3));
    ptime t2(date(2002,Jan,10),
             hours(1)+nanosec(5));

    ptime(ptime)

Copy constructor

    ptime t3(t1)

    ptime(special_values sv)

Constructor for infinities, not-a-date-time, max_date_time, and min_date_time

    ptime d1(neg_infin);
    ptime d2(pos_infin);
    ptime d3(not_a_date_time);
    ptime d4(max_date_time);
    ptime d5(min_date_time);

    ptime;

Default constructor. Creates a ptime object initialized to not_a_date_time. NOTE: this constructor can be disabled by defining DATE_TIME_NO_DEFAULT_CONSTRUCTOR (see compiler_config.hpp)

    ptime p; // p => not_a_date_time

Construct from String

Syntax | Description
--- | ---
Example

    ptime time_from_string(std::string)

From delimited string. NOTE: Excess digits in fractional seconds will be dropped. Ex: "1:02:03.123456999" => 1:02:03.123456. This behavior is affected by the precision the library is compiled with (see Build-Compiler Information.

    std::string ts("2002-01-20 23:59:59.000");
    ptime t(time_from_string(ts))

    ptime from_iso_string(std::string)

From non delimited ISO 8601 form string.

    std::string ts("20020131T235959");
    ptime t(from_iso_string(ts))

    ptime from_iso_extended_string(std::string)

From delimited ISO 8601 form string.

    std::string ts("2020-01-31T23:59:59.123");
    ptime t(from_iso_extended_string(ts))

Construct from Clock

Syntax | Description
--- | ---
Example

    ptime second_clock::local_time()

Get the local time, second level resolution, based on the time zone settings of the computer.

    ptime t(second_clock::local_time());

    ptime second_clock::universal_time()

Get the UTC time.

    ptime t(second_clock::universal_time())

    ptime microsec_clock::local_time()

Get the local time using a sub second resolution clock. On Unix systems this is implemented using gettimeofday. On most Win32 platforms it is implemented using ftime. Win32 systems often do not achieve microsecond resolution via this API. If higher resolution is critical to your application test your platform to see the achieved resolution.

    ptime t(microsec_clock::local_time());

    ptime microsec_clock::universal_time()

Get the UTC time using a sub second resolution clock. On Unix systems this is implemented using gettimeofday. On most Win32 platforms it is implemented using ftime. Win32 systems often do not achieve microsecond resolution via this API. If higher resolution is critical to your application test your platform to see the achieved resolution.

    ptime t(microsec_clock::universal_time());

Construct using Conversion Functions

Syntax | Description
--- | ---
Example

    ptime from_time_t(time_t t);

Converts a time_t into a ptime.

    ptime t = from_time_t(tt);

    ptime from_ftime<ptime>(FILETIME ft);

Creates a ptime object from a FILETIME structure.

    ptime t = from_ftime<ptime>(ft);

Accessors

Syntax | Description
--- | ---
Example

    date date()

Get the date part of a time.

    date d(2002,Jan,10);
    ptime t(d, hour(1));
    t.date() --> 2002-Jan-10;

    time_duration time_of_day()

Get the time offset in the day.

    date d(2002,Jan,10);
    ptime t(d, hour(1));
    t.time_of_day() --> 01:00:00;

    bool is_infinity() const

Returns true if ptime is either positive or negative infinity

    ptime pt(pos_infin);
    pt.is_infinity(); // --> true

    bool is_neg_infinity() const

Returns true if ptime is negative infinity

    ptime pt(neg_infin);
    pt.is_neg_infinity(); // --> true

    bool is_pos_infinity() const

Returns true if ptime is positive infinity

    ptime pt(neg_infin);
    pt.is_pos_infinity(); // --> true

    bool is_not_a_date_time() const

Returns true if value is not a ptime

    ptime pt(not_a_date_time);
    pt.is_not_a_date_time(); // --> true

    bool is_special() const

Returns true if ptime is any `special_value`

    ptime pt(pos_infin);
    ptime pt2(not_a_date_time);
    ptime pt3(date(2005,Mar,1), hours(10));
    pt.is_special(); // --> true
    pt2.is_special(); // --> true
    pt3.is_special(); // --> false

Conversion to String

Syntax | Description
--- | ---
Example

    std::string to_simple_string(ptime)

To `YYYY-mmm-DD HH:MM:SS.fffffffff` string where `mmm` 3 char month name and the fractional seconds are only included if non-zero.

    2002-Jan-01 10:00:01.123456789

    std::string to_iso_string(ptime)

Convert to form `YYYYMMDDTHHMMSS.fffffffff` where `T` is the date-time separator and the fractional seconds are only included if non-zero.

    20020131T100001.123456789

    std::string to_iso_extended_string(ptime)

Convert to form `YYYY-MM-DDTHH:MM:SS.fffffffff` where `T` is the date-time separator and the fractional seconds are only included if non-zero.

    2002-01-31T10:00:01.123456789

Operators

Syntax | Description
--- | ---
Example

    operator<<, operator>>

Streaming operators. Note: As of version 1.33, streaming operations have been greatly improved. See Date Time IO System for more details (including exceptions and error conditions).

    ptime pt(not_a_date_time);
    stringstream ss("2002-Jan-01 14:23:11");
    ss >> pt;
    std::cout << pt; // "2002-Jan-01 14:23:11"

    operator==, operator!=,
    operator>, operator<,
    operator>=, operator<=

A full complement of comparison operators

    t1 == t2, etc

    ptime operator+(days)

Return a ptime adding a day offset

    date d(2002,Jan,1);
    ptime t(d,minutes(5));
    days dd(1);
    ptime t2 = t + dd;

    ptime operator-(days)

Return a ptime subtracting a day offset

    date d(2002,Jan,1);
    ptime t(d,minutes(5));
    days dd(1);
    ptime t2 = t - dd;

    ptime operator+(time_duration)

Return a ptime adding a time duration

    date d(2002,Jan,1);
    ptime t(d,minutes(5));
    ptime t2 = t + hours(1) + minutes(2);

    ptime operator-(time_duration)

Return a ptime subtracting a time duration

    date d(2002,Jan,1);
    ptime t(d,minutes(5));
    ptime t2 = t - minutes(2);

    time_duration operator-(ptime)

Take the difference between two times.

    date d(2002,Jan,1);
    ptime t1(d,minutes(5));
    ptime t2(d,seconds(5));
    time_duration t3 = t2 - t1;//negative result

Struct tm, time_t, and FILETIME Functions

Functions for converting posix_time objects to, and from, `tm` structs are provided as well as conversion from `time_t` and `FILETIME`.

Syntax | Description
--- | ---
Example

    tm to_tm(ptime)

A function for converting a `ptime` object to a `tm` struct. The `tm_isdst` field is set to -1.

    ptime pt(date(2005,Jan,1), time_duration(1,2,3));
    tm pt_tm = to_tm(pt);
    /* tm_year => 105
       tm_mon  => 0
       tm_mday => 1
       tm_wday => 6 (Saturday)
       tm_yday => 0
       tm_hour => 1
       tm_min  => 2
       tm_sec  => 3
       tm_isdst => -1 */

    ptime ptime_from_tm(tm timetm)

A function for converting a `tm` struct to a `ptime` object. The fields: `tm_wday` , `tm_yday` , and `tm_isdst` are ignored.

    tm pt_tm;
    pt_tm.tm_year = 105;
    pt_tm.tm_mon  = 0;
    pt_tm.tm_mday = 1;
    pt_tm.tm_hour = 1;
    pt_tm.tm_min  = 2;
    pt_tm.tm_sec  = 3;
    ptime pt = ptime_from_tm(pt_tm);
    // pt => 2005-Jan-01 01:02:03

    tm to_tm(time_duration)

A function for converting a `time_duration` object to a `tm` struct. The fields: `tm_year`, `tm_mon`, `tm_mday`, `tm_wday`, `tm_yday` are set to zero. The `tm_isdst` field is set to -1.

    time_duration td(1,2,3);
    tm td_tm = to_tm(td);
    /* tm_year => 0
       tm_mon  => 0
       tm_mday => 0
       tm_wday => 0
       tm_yday => 0
       tm_hour => 1
       tm_min  => 2
       tm_sec  => 3
       tm_isdst => -1 */

    ptime from_time_t(std::time_t)

Creates a `ptime` from the time_t parameter. The seconds held in the time_t are added to a time point of 1970-Jan-01.

    ptime pt(not_a_date_time);
    std::time_t t;
    t = 1118158776;
    pt = from_time_t(t);
    // pt => 2005-Jun-07 15:39:36

    ptime from_ftime<ptime>(FILETIME)

A template function that constructs a `ptime` from a FILETIME struct.

    FILETIME ft;
    ft.dwHighDateTime = 29715317;
    ft.dwLowDateTime = 3865122988UL;
    ptime pt = from_ftime<ptime>(ft);
    // pt => 2005-Jun-07 15:30:57.039582000