TSDuck v3.46-4930
MPEG Transport Stream Toolkit
Loading...
Searching...
No Matches

#include <tsTime.h>

Inheritance diagram for ts::Time:
Collaboration diagram for ts::Time:

Classes

struct  Fields
class  TimeError

Public Types

enum  FieldMask {
  YEAR = 0x01 ,
  MONTH = 0x02 ,
  DAY = 0x04 ,
  DATE = YEAR | MONTH | DAY ,
  HOUR = 0x08 ,
  MINUTE = 0x10 ,
  SECOND = 0x20 ,
  TIME = HOUR | MINUTE | SECOND ,
  DATETIME = DATE | TIME ,
  MILLISECOND = 0x40 ,
  ALL = DATE | TIME | MILLISECOND
}

Public Member Functions

 Time ()=default
 Time (const Fields &fields)
 Time (int year, int month, int day, int hour, int minute, int second=0, int millisecond=0)
void clear ()
bool decode (const UString &str, int fields=DATE|TIME)
UString format (int fields=ALL) const
Time JSTToUTC () const
cn::seconds leapSecondsTo (const Time &end) const
Time localToUTC () const
Time nextDay () const
Time nextHour () const
Time nextMonth () const
Time nextYear () const
 operator Fields () const
template<class Rep, class Period>
Time operator+ (cn::duration< Rep, Period > duration) const
template<class Rep, class Period>
Time & operator+= (cn::duration< Rep, Period > duration)
template<class Rep, class Period>
Time operator- (cn::duration< Rep, Period > duration) const
cn::milliseconds operator- (const Time &other) const
template<class Rep, class Period>
Time & operator-= (cn::duration< Rep, Period > duration)
bool operator< (const Time &other) const
bool operator<= (const Time &other) const
bool operator== (const Time &other) const
bool operator> (const Time &other) const
bool operator>= (const Time &other) const
void set (const Fields &fields)
void set (int year, int month, int day, int hour, int minute, int second=0, int millisecond=0)
Time thisDay () const
Time thisHour () const
Time thisMonth () const
Time thisYear () const
cn::seconds toGPSSeconds () const
virtual UString toString () const override
uint64_t toUnixTime () const
void toWin32FileTime (::FILETIME &fileTime) const
Time UTCToJST () const
Time UTCToLocal () const

Static Public Member Functions

static Time CurrentLocalTime ()
static Time CurrentUTC ()
static void GetUnixClock (::timespec &result, clockid_t clock, const cn::milliseconds &delay=cn::milliseconds::zero())
static Time GPSSecondsToUTC (cn::seconds gps)
static bool IsLeapYear (int year)
static Time NextHourLocalTime ()
static Time NextHourUTC ()
static Time NextMonthLocalTime ()
static Time NextMonthUTC ()
static Time NextYearLocalTime ()
static Time NextYearUTC ()
static Time ThisHourLocalTime ()
static Time ThisHourUTC ()
static Time ThisMonthLocalTime ()
static Time ThisMonthUTC ()
static Time ThisYearLocalTime ()
static Time ThisYearUTC ()
static Time TodayLocalTime ()
static Time TodayUTC ()
static Time TomorrowLocalTime ()
static Time TomorrowUTC ()
static cn::nanoseconds UnixClockNanoSeconds (clockid_t clock, const cn::milliseconds &delay=cn::milliseconds::zero())
static Time UnixTimeToUTC (uint64_t unixTime)
static cn::milliseconds Win32FileTimeToMilliSecond (const ::FILETIME &fileTime)
static Time Win32FileTimeToUTC (const ::FILETIME &fileTime)

Static Public Attributes

static const Time Apocalypse
static const Time Epoch
static constexpr int FirstSafeSystemYear = 1970
static const Time GPSEpoch
static constexpr cn::milliseconds JSTOffset = cn::hours(+9)
static const cn::milliseconds JulianEpochOffset
static const Time UnixEpoch
static constexpr cn::seconds UnixEpochToGPS = cn::seconds(315964800)

Detailed Description

The Time class implements a basic representation of time.

The implementation is based on the operating system representation of time. This means that the range of representable time values may vary from one system to another. You may use the constants Epoch and Apocalypse as first and last representable time values.

An instance of Time may be indifferently interpreted as a local time or UTC time value. Methods are provided to convert between local and UTC values. The accuracy of these conversions depend on the configuration of the operating system.

The implementation of the class is designed to be light and fast so that Time objects may be copied without overhead.

Member Enumeration Documentation

◆ FieldMask

Flags indicating the list of time fields to display.

Enumerator
YEAR 

Display the year.

MONTH 

Display the month.

DAY 

Display the day.

DATE 

Display the year, month and day.

HOUR 

Display the hours.

MINUTE 

Display the minutes.

SECOND 

Display the seconds.

TIME 

Display the hours, minutes and seconds.

DATETIME 

Display the year, month, day, hours, minutes and seconds.

MILLISECOND 

Display the milliseconds.

ALL 

Display all fields.

Constructor & Destructor Documentation

◆ Time() [1/3]

ts::Time::Time ( )
default

Default constructor. The initial value is the Epoch.

◆ Time() [2/3]

ts::Time::Time ( int year,
int month,
int day,
int hour,
int minute,
int second = 0,
int millisecond = 0 )

Constructor from broken-down date fields.

Parameters
[in]yearNumber of years.
[in]monthNumber of months (1 to 12).
[in]dayNumber of days (1 to 31).
[in]hourNumber of hours (0 to 23).
[in]minuteNumber of minutes (0 to 59).
[in]secondNumber of seconds (0 to 59).
[in]millisecondNumber of milliseconds (0 to 999).
Exceptions
ts::Time::TimeErrorIf any field is out of range or if the resulting time is outside the representable range for the local operating system.

◆ Time() [3/3]

ts::Time::Time ( const Fields & fields)

Constructor from broken-down date fields in one single object. Can be used as a conversion operator from Time::Fields to Time.

Parameters
[in]fieldsThe date fields.
Exceptions
ts::Time::TimeErrorIf any field is out of range or if the resulting time is outside the representable range for the local operating system.

Member Function Documentation

◆ clear()

void ts::Time::clear ( )
inline

Clear the time value. The time value becomes the Epoch.

◆ set() [1/2]

void ts::Time::set ( int year,
int month,
int day,
int hour,
int minute,
int second = 0,
int millisecond = 0 )

Set time from broken-down date fields.

Parameters
[in]yearNumber of years.
[in]monthNumber of months (1 to 12).
[in]dayNumber of days (1 to 31).
[in]hourNumber of hours (0 to 23).
[in]minuteNumber of minutes (0 to 59).
[in]secondNumber of seconds (0 to 59).
[in]millisecondNumber of milliseconds (0 to 999).
Exceptions
ts::Time::TimeErrorIf any field is out of range or if the resulting time is outside the representable range for the local operating system.

◆ operator+()

template<class Rep, class Period>
Time ts::Time::operator+ ( cn::duration< Rep, Period > duration) const
inline

Operator Time + std::chrono::duration => Time.

Parameters
[in]durationA duration.
Returns
A Time object representing this object plus the specified duration.

◆ operator-() [1/2]

template<class Rep, class Period>
Time ts::Time::operator- ( cn::duration< Rep, Period > duration) const
inline

Operator Time - std::chrono::duration => Time.

Parameters
[in]durationA duration.
Returns
A Time object representing this object minus the specified duration.

◆ operator+=()

template<class Rep, class Period>
Time & ts::Time::operator+= ( cn::duration< Rep, Period > duration)
inline

Operator Time += std::chrono::duration

Parameters
[in]durationA duration to add to this object.
Returns
A reference to this object.

◆ operator-=()

template<class Rep, class Period>
Time & ts::Time::operator-= ( cn::duration< Rep, Period > duration)
inline

Operator Time -= std::chrono::duration

Parameters
[in]durationA duration to substract from this object.
Returns
A reference to this object.

◆ operator-() [2/2]

cn::milliseconds ts::Time::operator- ( const Time & other) const
inline

Operator: Time - Time => cn::milliseconds.

Parameters
[in]otherAnother time to substract from this object.
Returns
The duration, in milliseconds, between this object and the other object.

◆ operator==()

bool ts::Time::operator== ( const Time & other) const
inline

Equality operator.

Parameters
[in]otherAnother time to compare with this object.
Returns
True is this object is equal to the other object, false otherwise.

◆ operator<()

bool ts::Time::operator< ( const Time & other) const
inline

Lower operator.

Parameters
[in]otherAnother time to compare with this object.
Returns
True is this time is before the other object time, false otherwise.

◆ operator<=()

bool ts::Time::operator<= ( const Time & other) const
inline

Lower or equal operator.

Parameters
[in]otherAnother time to compare with this object.
Returns
True is this time is before or equal to the other object time, false otherwise.

◆ operator>()

bool ts::Time::operator> ( const Time & other) const
inline

Greater operator.

Parameters
[in]otherAnother time to compare with this object.
Returns
True is this time is after the other object time, false otherwise.

◆ operator>=()

bool ts::Time::operator>= ( const Time & other) const
inline

Greater or equal operator.

Parameters
[in]otherAnother time to compare with this object.
Returns
True is this time is after or equal to the other object time, false otherwise.

◆ set() [2/2]

void ts::Time::set ( const Fields & fields)

Set time from broken-down date fields in one single object.

Parameters
[in]fieldsThe date fields.
Exceptions
ts::Time::TimeErrorIf any field is out of range or if the resulting time is outside the representable range for the local operating system.

◆ operator Fields()

ts::Time::operator Fields ( ) const

Conversion operator from Time to Time::Fields.

Returns
A Time::Fields object containing the broken-down time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ localToUTC()

Time ts::Time::localToUTC ( ) const

Convert a local time to UTC time.

Returns
A UTC time from this object time, interpreted as a local time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ UTCToLocal()

Time ts::Time::UTCToLocal ( ) const

Convert a UTC time to local time.

Returns
A local time from this object time, interpreted as a UTC time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ JSTToUTC()

Time ts::Time::JSTToUTC ( ) const

Convert a JST (Japan Standard Time) to UTC time.

Returns
A UTC time from this object time, interpreted as a JST time.

◆ UTCToJST()

Time ts::Time::UTCToJST ( ) const

Convert a UTC time to JST (Japan Standard Time).

Returns
A JST time from this object time, interpreted as a UTC time.

◆ format()

UString ts::Time::format ( int fields = ALL) const

Format a string representation of a time.

Parameters
[in]fieldsA combination of option flags indicating which fields should be included. This is typically the result of or'ed values from the enum type FieldMask.
Returns
A string containing the formatted date.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ toString()

virtual UString ts::Time::toString ( ) const
overridevirtual

Convert to a string object.

Returns
This object, converted as a string.

Implements ts::StringifyInterface.

◆ decode()

bool ts::Time::decode ( const UString & str,
int fields = DATE|TIME )

Decode a time from a string. The resulting decoded time is stored in this object.

Parameters
[in]strA string describing a date and time in a rudimentary format. The string shall contain integer values describing the various fields in descending order, from year to millisecond. The integer fields can be separated by any combination of non-digit characters. The list of expected fields is given by the parameter fields.
[in]fieldsA combination of option flags indicating which fields should be included. This is typically the result of or'ed values from the enum type FieldMask.
Returns
True on success, false if the string cannot be decoded.

◆ leapSecondsTo()

cn::seconds ts::Time::leapSecondsTo ( const Time & end) const

Get the number of leap seconds between two UTC dates.

Wikipedia: << A leap second is a one-second adjustment that is occasionally applied to Coordinated Universal Time (UTC), to accommodate the difference between precise time (as measured by atomic clocks) and imprecise observed solar time (known as UT1 and which varies due to irregularities and long-term slowdown in the Earth's rotation).

The UTC time standard, widely used for international timekeeping and as the reference for civil time in most countries, uses precise atomic time and consequently would run ahead of observed solar time unless it is reset to UT1 as needed. The leap second facility exists to provide this adjustment.

Because the Earth's rotation speed varies in response to climatic and geological events, UTC leap seconds are irregularly spaced and unpredictable. Insertion of each UTC leap second is usually decided about six months in advance by the International Earth Rotation and Reference Systems Service (IERS), to ensure that the difference between the UTC and UT1 readings will never exceed 0.9 seconds. >>

TSDuck uses a configuration file (tscore.time.xml) to define the list of known leap seconds.

The TAI (International Atomic Time) starts Jan 1st 1958. Before this date, there is no leap second. Between 1958 and 1972, there are globally 10 leap seconds but they are not precisely allocated. On June 30 1972, the first leap second was officially allocated at a precise date and time.

If start and end date are both before 1958 or both after 1972, this function returns a precise result. If one of the dates is between 1958 and 1972, the initial 10 leap seconds may be included (or not).

Parameters
[in]endEnd UTC date. The time is this object is used as start date.
Returns
The number of leap seconds between this object and end. Return zero if this object is after end.
See also
https://en.wikipedia.org/wiki/Leap_second
https://en.wikipedia.org/wiki/International_Atomic_Time

◆ CurrentUTC()

Time ts::Time::CurrentUTC ( )
static

Static method returning the current UTC time.

Returns
The current UTC time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ CurrentLocalTime()

Time ts::Time::CurrentLocalTime ( )
inlinestatic

Static method returning the current local time.

Returns
The current local time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ thisHour()

Time ts::Time::thisHour ( ) const

Get the beginning of the current hour.

Returns
The time for the beginning of the current hour from this object time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ nextHour()

Time ts::Time::nextHour ( ) const
inline

Get the beginning of the next hour.

Returns
The time for the beginning of the next hour from this object time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ thisDay()

Time ts::Time::thisDay ( ) const

Get the beginning of the current day.

Returns
The time for the beginning of the current day from this object time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ nextDay()

Time ts::Time::nextDay ( ) const
inline

Get the beginning of the next day.

Returns
The time for the beginning of the next day from this object time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ thisMonth()

Time ts::Time::thisMonth ( ) const

Get the beginning of the current month.

Returns
The time for the beginning of the current month from this object time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ nextMonth()

Time ts::Time::nextMonth ( ) const

Get the beginning of the next month.

Returns
The time for the beginning of the next month from this object time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ thisYear()

Time ts::Time::thisYear ( ) const

Get the beginning of the current year.

Returns
The time for the beginning of the current year from this object time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ nextYear()

Time ts::Time::nextYear ( ) const

Get the beginning of the next year.

Returns
The time for the beginning of the next year from this object time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ ThisHourUTC()

Time ts::Time::ThisHourUTC ( )
inlinestatic

Get the beginning of the current hour, UTC.

Returns
The time for the beginning of the current hour, UTC.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ ThisHourLocalTime()

Time ts::Time::ThisHourLocalTime ( )
inlinestatic

Get the beginning of the current hour, local time.

Returns
The time for the beginning of the current hour, local time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ NextHourUTC()

Time ts::Time::NextHourUTC ( )
inlinestatic

Get the beginning of the next hour, UTC.

Returns
The time for the beginning of the next hour, UTC.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ NextHourLocalTime()

Time ts::Time::NextHourLocalTime ( )
inlinestatic

Get the beginning of the next hour, local time.

Returns
The time for the beginning of the next hour, local time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ TodayUTC()

Time ts::Time::TodayUTC ( )
inlinestatic

Get the beginning of the current day, UTC.

Returns
The time for the beginning of the current day, UTC.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ TodayLocalTime()

Time ts::Time::TodayLocalTime ( )
inlinestatic

Get the beginning of the current day, local time.

Returns
The time for the beginning of the current day, local time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ TomorrowUTC()

Time ts::Time::TomorrowUTC ( )
inlinestatic

Get the beginning of the next day, UTC.

Returns
The time for the beginning of the next day, UTC.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ TomorrowLocalTime()

Time ts::Time::TomorrowLocalTime ( )
inlinestatic

Get the beginning of the next day, local time.

Returns
The time for the beginning of the next day, local time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ ThisMonthUTC()

Time ts::Time::ThisMonthUTC ( )
inlinestatic

Get the beginning of the current month, UTC.

Returns
The time for the beginning of the current month, UTC.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ ThisMonthLocalTime()

Time ts::Time::ThisMonthLocalTime ( )
inlinestatic

Get the beginning of the current month, local time.

Returns
The time for the beginning of the current month, local time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ NextMonthUTC()

Time ts::Time::NextMonthUTC ( )
inlinestatic

Get the beginning of the next month, UTC.

Returns
The time for the beginning of the next month, UTC.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ NextMonthLocalTime()

Time ts::Time::NextMonthLocalTime ( )
inlinestatic

Get the beginning of the next month, local time.

Returns
The time for the beginning of the next month, local time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ ThisYearUTC()

Time ts::Time::ThisYearUTC ( )
inlinestatic

Get the beginning of the current year, UTC.

Returns
The time for the beginning of the current year, UTC.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ ThisYearLocalTime()

Time ts::Time::ThisYearLocalTime ( )
inlinestatic

Get the beginning of the current year, local time.

Returns
The time for the beginning of the current year, local time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ NextYearUTC()

Time ts::Time::NextYearUTC ( )
inlinestatic

Get the beginning of the next year, UTC.

Returns
The time for the beginning of the next year, UTC.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ NextYearLocalTime()

Time ts::Time::NextYearLocalTime ( )
inlinestatic

Get the beginning of the next year, local time.

Returns
The time for the beginning of the next year, local time.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ IsLeapYear()

bool ts::Time::IsLeapYear ( int year)
static

Check if a year is a leap year (29 days in February).

Parameters
[in]yearThe year to check.
Returns
True if year is a leap year.

◆ UnixTimeToUTC()

Time ts::Time::UnixTimeToUTC ( uint64_t unixTime)
static

This static routine converts a UNIX time_t to a UTC time.

Parameters
[in]unixTimeA UNIX time_t value. Must be unsigned. Can be 32 or 64 bits.
Returns
The corresponding UTC time.

◆ toUnixTime()

uint64_t ts::Time::toUnixTime ( ) const

Convert this time in a UNIX time_t.

Returns
The corresponding Unix time on 64 bits.

◆ GPSSecondsToUTC()

Time ts::Time::GPSSecondsToUTC ( cn::seconds gps)
inlinestatic

This static routine converts a number of GPS seconds to a UTC time.

Parameters
[in]gpsThe number of seconds since the GPS Epoch (1980-01-06).
Returns
The corresponding UTC time.

◆ toGPSSeconds()

cn::seconds ts::Time::toGPSSeconds ( ) const

Convert this time to a number of seconds since 1980-01-06, the GPS epoch.

Returns
The corresponding number of secondss.

◆ Win32FileTimeToMilliSecond()

cn::milliseconds ts::Time::Win32FileTimeToMilliSecond ( const ::FILETIME & fileTime)
static

This static routine converts a Win32 FILETIME to cn::milliseconds (Microsoft Windows only).

This function is available on Microsoft Windows systems only and should not be used on portable software.

Parameters
[in]fileTimeA Win32 FILETIME value.
Returns
The corresponding number of milliseconds.

◆ Win32FileTimeToUTC()

Time ts::Time::Win32FileTimeToUTC ( const ::FILETIME & fileTime)
static

This static routine converts a Win32 FILETIME to a UTC time (Microsoft Windows only).

This function is available on Microsoft Windows systems only and should not be used on portable software.

Parameters
[in]fileTimeA Win32 FILETIME value.
Returns
The corresponding UTC time.

◆ toWin32FileTime()

void ts::Time::toWin32FileTime ( ::FILETIME & fileTime) const

Convert the time to a Win32 FILETIME (Microsoft Windows only).

This function is available on Microsoft Windows systems only and should not be used on portable software.

Parameters
[out]fileTimeThe corresponding Win32 FILETIME value.

◆ UnixClockNanoSeconds()

cn::nanoseconds ts::Time::UnixClockNanoSeconds ( clockid_t clock,
const cn::milliseconds & delay = cn::milliseconds::zero() )
static

This static routine gets a system clock and adds a delay in milliseconds (UNIX systems only).

This function ensures that no overflow is possible. This function is available on UNIX systems only and should not be used on portable software.

Parameters
[in]clockClock id, usually CLOCK_REALTIME or CLOCK_MONOTONIC.
[in]delayNumber of milliseconds to add to the current clock.
Returns
Absolute time in nanoseconds according to clock.

◆ GetUnixClock()

void ts::Time::GetUnixClock ( ::timespec & result,
clockid_t clock,
const cn::milliseconds & delay = cn::milliseconds::zero() )
static

This static routine gets a system clock and adds a delay in milliseconds (UNIX systems only).

This function ensures that no overflow is possible. This function is available on UNIX systems only and should not be used on portable software.

Parameters
[out]resultA returned UNIX timespec value.
[in]clockClock id, usually CLOCK_REALTIME or CLOCK_MONOTONIC.
[in]delayNumber of milliseconds to add to the current real time clock.

Member Data Documentation

◆ JSTOffset

cn::milliseconds ts::Time::JSTOffset = cn::hours(+9)
staticconstexpr

Offset of a JST (Japan Standard Time) value from UTC in milliseconds. JST is defined as UTC+9.

◆ Epoch

const Time ts::Time::Epoch
static

Constant representing the Epoch, ie the first representable time on this operating system.

◆ UnixEpoch

const Time ts::Time::UnixEpoch
static

Constant representing the Epoch on UNIX operating systems. The UNIX epoch is 1 Jan 1970 00:00:00. It is assumed to be representable in all operating systems.

◆ GPSEpoch

const Time ts::Time::GPSEpoch
static

Constant representing the GPS Epoch, 1980-01-06. It is assumed to be representable in all operating systems.

◆ Apocalypse

const Time ts::Time::Apocalypse
static

Constant representing the End Of Time (at least on this operating system).

◆ FirstSafeSystemYear

int ts::Time::FirstSafeSystemYear = 1970
staticconstexpr

First year which is safe to use on all operating systems.

◆ JulianEpochOffset

const cn::milliseconds ts::Time::JulianEpochOffset
static

Constant representing the offset of the Julian Epoch from the time Epoch of the operating system (Julian epoch - Time epoch) in milliseconds.

The Julian epoch is 17 Nov 1858 00:00:00. If this constant is negative, the Julian epoch if before the time epoch and cannot be represented as a Time object.

◆ UnixEpochToGPS

cn::seconds ts::Time::UnixEpochToGPS = cn::seconds(315964800)
staticconstexpr

Number of seconds between 1970-01-01 and 1980-01-06. This is the difference between ATSC time and Unix time. The ATSC system time is the number of GPS seconds since 00:00:00 UTC, January 6th, 1980. This value can be displayed on a Linux system using the command: date +s --date 1980-01-06utc


The documentation for this class was generated from the following file: