TSDuck Version 3.15-964 (TSDuck - The MPEG Transport Stream Toolkit)
ts::Time Class Reference

The Time class implements a basic representation of time. More...

Collaboration diagram for ts::Time:

Classes

struct  Fields
 Broken-down fields of a time value. More...
 
class  TimeError
 Fatal low-level time error. More...
 

Public Types

enum  FieldMask {
  YEAR = 0x01,
  MONTH = 0x02,
  DAY = 0x04,
  DATE = YEAR | MONTH | DAY,
  HOUR = 0x08,
  MINUTE = 0x10,
  SECOND = 0x20,
  TIME = HOUR | MINUTE | SECOND,
  MILLISECOND = 0x40,
  ALL = DATE | TIME | MILLISECOND
}
 Flags indicating the list of time fields to display. More...
 

Public Member Functions

 Time ()
 Default constructor. More...
 
 Time (int year, int month, int day, int hour, int minute, int second=0, int millisecond=0)
 Constructor from broken-down date fields. More...
 
 Time (const Fields &fields)
 Constructor from broken-down date fields in one single object. More...
 
bool decode (const UString &str, int fields=DATE|TIME)
 Decode a time from a string. More...
 
UString format (int fields=ALL) const
 Format a string representation of a time. More...
 
Time localToUTC () const
 Convert a local time to UTC time. More...
 
Time nextDay () const
 Get the beginning of the next day. More...
 
Time nextHour () const
 Get the beginning of the next hour. More...
 
Time nextMonth () const
 Get the beginning of the next month. More...
 
Time nextYear () const
 Get the beginning of the next year. More...
 
 operator Fields () const
 Conversion operator from Time to Time::Fields. More...
 
 operator UString () const
 Conversion operator from Time to UString. More...
 
bool operator!= (const Time &other) const
 Unequality operator. More...
 
Time operator+ (const MilliSecond &duration) const
 Operator Time + MilliSecond => Time. More...
 
Timeoperator+= (const MilliSecond &duration)
 Operator Time += MilliSecond. More...
 
Time operator- (const MilliSecond &duration) const
 Operator Time - MilliSecond => Time. More...
 
MilliSecond operator- (const Time &other) const
 Operator: Time - Time => MilliSecond. More...
 
Timeoperator-= (const MilliSecond &duration)
 Operator Time -= MilliSecond. More...
 
bool operator< (const Time &other) const
 Lower operator. More...
 
bool operator<= (const Time &other) const
 Lower or equal operator. More...
 
bool operator== (const Time &other) const
 Equality operator. More...
 
bool operator> (const Time &other) const
 Greater operator. More...
 
bool operator>= (const Time &other) const
 Greater or equal operator. More...
 
Time thisDay () const
 Get the beginning of the current day. More...
 
Time thisHour () const
 Get the beginning of the current hour. More...
 
Time thisMonth () const
 Get the beginning of the current month. More...
 
Time thisYear () const
 Get the beginning of the current year. More...
 
Time UTCToLocal () const
 Convert a UTC time to local time. More...
 

Static Public Member Functions

static Time CurrentLocalTime ()
 Static method returning the current local time. More...
 
static Time CurrentUTC ()
 Static method returning the current UTC time. More...
 
static void GetUnixClock (::timespec &result, clockid_t clock, const MilliSecond &delay=0)
 This static routine gets a system clock and adds a delay in milliseconds (UNIX systems only). More...
 
static bool IsLeapYear (int year)
 Check if a year is a leap year (29 days in February). More...
 
static Time NextHourLocalTime ()
 Get the beginning of the next hour, local time. More...
 
static Time NextHourUTC ()
 Get the beginning of the next hour, UTC. More...
 
static Time NextMonthLocalTime ()
 Get the beginning of the next month, local time. More...
 
static Time NextMonthUTC ()
 Get the beginning of the next month, UTC. More...
 
static Time NextYearLocalTime ()
 Get the beginning of the next year, local time. More...
 
static Time NextYearUTC ()
 Get the beginning of the next year, UTC. More...
 
static Time ThisHourLocalTime ()
 Get the beginning of the current hour, local time. More...
 
static Time ThisHourUTC ()
 Get the beginning of the current hour, UTC. More...
 
static Time ThisMonthLocalTime ()
 Get the beginning of the current month, local time. More...
 
static Time ThisMonthUTC ()
 Get the beginning of the current month, UTC. More...
 
static Time ThisYearLocalTime ()
 Get the beginning of the current year, local time. More...
 
static Time ThisYearUTC ()
 Get the beginning of the current year, UTC. More...
 
static Time TodayLocalTime ()
 Get the beginning of the current day, local time. More...
 
static Time TodayUTC ()
 Get the beginning of the current day, UTC. More...
 
static Time TomorrowLocalTime ()
 Get the beginning of the next day, local time. More...
 
static Time TomorrowUTC ()
 Get the beginning of the next day, UTC. More...
 
static NanoSecond UnixClockNanoSeconds (clockid_t clock, const MilliSecond &delay=0)
 This static routine gets a system clock and adds a delay in milliseconds (UNIX systems only). More...
 
static Time UnixTimeToUTC (const uint32_t unixTime)
 This static routine converts a UNIX time_t to a UTC time. More...
 
static MilliSecond Win32FileTimeToMilliSecond (const ::FILETIME &fileTime)
 This static routine converts a Win32 FILETIME to MilliSecond (Microsoft Windows only). More...
 
static Time Win32FileTimeToUTC (const ::FILETIME &fileTime)
 This static routine converts a Win32 FILETIME to a UTC time (Microsoft Windows only). More...
 

Static Public Attributes

static const Time Apocalypse
 Constant representing the End Of Time (at least on this operating system).
 
static const Time Epoch
 Constant representing the Epoch, ie the first representable time on this operating system.
 
static const MilliSecond JulianEpochOffset
 Constant representing the offset of the Julian Epoch from the time Epoch of the operating system (Julian epoch - Time epoch) in milliseconds. More...
 
static const Time UnixEpoch
 Constant representing the Epoch on UNIX operating systems. More...
 

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. The class is not polymorphic, there is no virtual methods and no vtable. In fact, the actual representation is only a 64-bit integer.

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.

MILLISECOND 

Display the milliseconds.

ALL 

Display all fields.

Constructor & Destructor Documentation

◆ Time() [1/3]

ts::Time::Time ( )
inline

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

◆ operator+()

Time ts::Time::operator+ ( const MilliSecond duration) const
inline

Operator Time + MilliSecond => Time.

Parameters
[in]durationA number of milliseconds.
Returns
A Time object representing this object plus the specified number of milliseconds.

◆ operator-() [1/2]

Time ts::Time::operator- ( const MilliSecond duration) const
inline

Operator Time - MilliSecond => Time.

Parameters
[in]durationA number of milliseconds.
Returns
A Time object representing this object minus the specified number of milliseconds.

◆ operator+=()

Time& ts::Time::operator+= ( const MilliSecond duration)
inline

Operator Time += MilliSecond.

Parameters
[in]durationA number of milliseconds to add to this object.
Returns
A reference to this object.

◆ operator-=()

Time& ts::Time::operator-= ( const MilliSecond duration)
inline

Operator Time -= MilliSecond.

Parameters
[in]durationA number of milliseconds to substract from this object.
Returns
A reference to this object.

◆ operator-() [2/2]

MilliSecond ts::Time::operator- ( const Time other) const
inline

Operator: Time - Time => MilliSecond.

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

Unequality operator.

Parameters
[in]otherAnother time to compare with this object.
Returns
True is this object is different from 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.

◆ 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.

◆ 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.

◆ 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.

◆ operator UString()

ts::Time::operator UString ( ) const
inline

Conversion operator from Time to UString.

Equivalent to format (ALL).

Returns
A string containing the formatted date.
Exceptions
ts::Time::TimeErrorIn case of operating system time error.

◆ CurrentUTC()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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.

◆ Win32FileTimeToMilliSecond()

static MilliSecond ts::Time::Win32FileTimeToMilliSecond ( const ::FILETIME &  fileTime)
static

This static routine converts a Win32 FILETIME to MilliSecond (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()

static 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.

◆ UnixTimeToUTC()

static Time ts::Time::UnixTimeToUTC ( const uint32_t  unixTime)
static

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

Parameters
[in]unixTimeA UNIX time_t value.
Returns
The corresponding UTC time.

◆ UnixClockNanoSeconds()

static NanoSecond ts::Time::UnixClockNanoSeconds ( clockid_t  clock,
const MilliSecond delay = 0 
)
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()

static void ts::Time::GetUnixClock ( ::timespec &  result,
clockid_t  clock,
const MilliSecond delay = 0 
)
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

◆ 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.

◆ JulianEpochOffset

const MilliSecond 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.


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