libfilezilla
Public Types | Public Member Functions | Static Public Member Functions | Friends | List of all members
datetime Class Referencefinal

Represents a point of time in wallclock, tracking the timestamps accuracy/precision. More...

#include <time.hpp>

Public Types

enum  accuracy : char {
  days , hours , minutes , seconds ,
  milliseconds
}
 The datetime's accuracy.
 
enum  zone { utc , local }
 When importing or exporting a timestamp, zone is used to explicitly specify whether the conversion is to/from localtime or UTC.
 

Public Member Functions

 datetime () noexcept=default
 A default-constructed timestamp is empty()
 
 datetime (zone z, int year, int month, int day, int hour=-1, int minute=-1, int second=-1, int millisecond=-1)
 
 datetime (time_t, accuracy a)
 
 datetime (std::string_view const &s, zone z)
 Construct from string, looks for YYYYmmDD[[[[HH]MM]SS]sss]. More...
 
 datetime (std::wstring_view const &s, zone z)
 
 datetime (FILETIME const &ft, accuracy a)
 Windows-only: Construct from FILETIME.
 
 datetime (datetime const &op)=default
 
 datetime (datetime &&op) noexcept=default
 
datetimeoperator= (datetime const &op)=default
 
datetimeoperator= (datetime &&op) noexcept=default
 
bool empty () const
 
 operator bool () const
 
void clear ()
 Resulting timestamp is empty()
 
accuracy get_accuracy () const
 
int compare (datetime const &op) const
 Accuracy-aware comparison against another timestamp. More...
 
bool earlier_than (datetime const &op) const
 Equivalent to compare(op) < 0.
 
bool later_than (datetime const &op) const
 Equivalent to compare(op) > 0.
 
bool set (zone z, int year, int month, int day, int hour=-1, int minute=-1, int second=-1, int millisecond=-1)
 Sets the timestamp. More...
 
bool set (std::string_view const &str, zone z)
 Set from string, looks for YYYYmmDD[[[[HH]MM]SS]sss]. More...
 
bool set (std::wstring_view const &str, zone z)
 
bool set (FILETIME const &ft, accuracy a)
 Windows-only: Set timestamp from FILETIME.
 
bool set (SYSTEMTIME const &ft, accuracy a, zone z)
 Windows-only: Set timestamp from SYSTEMTIME.
 
bool set (tm &t, accuracy a, zone z)
 
bool imbue_time (int hour, int minute, int second=-1, int millisecond=-1)
 Adds time to timestamps that only have a day-accuracy. More...
 
std::string format (std::string const &format, zone z) const
 
std::wstring format (std::wstring const &format, zone z) const
 
int get_milliseconds () const
 Get millisecond part of timestamp.
 
time_t get_time_t () const
 Get timestamp as time_t, seconds since 1970-01-01 00:00:00.
 
tm get_tm (zone z) const
 Get timestamp as struct tm. More...
 
FILETIME get_filetime () const
 Windows-only: Get timestamp as FILETIME.
 
std::string get_rfc822 () const
 
bool set_rfc822 (std::string_view const &str)
 
bool set_rfc822 (std::wstring_view const &str)
 
bool set_rfc3339 (std::string_view const &str)
 
bool set_rfc3339 (std::wstring_view const &str)
 
Naive comparison operators

Naive operators compare the timestamp's internal representation first, with accuracy as secondary criterion.

See also
compare
bool operator== (datetime const &op) const
 
bool operator!= (datetime const &op) const
 
bool operator< (datetime const &op) const
 
bool operator<= (datetime const &op) const
 
bool operator> (datetime const &op) const
 
bool operator>= (datetime const &op) const
 
Adding/subtracting duration intervals

Adding or subtracting a duration interval is accuracy-aware, e.g. adding a single second to a datetime with minute-accuracy does not change the timestamp.

datetimeoperator+= (duration const &op)
 
datetime operator+ (duration const &op) const
 
datetimeoperator-= (duration const &op)
 
datetime operator- (duration const &op) const
 

Static Public Member Functions

static datetime now ()
 Returns the current date/time.
 
static bool verify_format (std::string const &fmt)
 
static bool verify_format (std::wstring const &fmt)
 

Friends

duration operator- (datetime const &a, datetime const &b)
 Gets the difference between two timestamps as duration. More...
 

Detailed Description

Represents a point of time in wallclock, tracking the timestamps accuracy/precision.

As time may come from different sources that have different accuracy/precision, this class keeps track of accuracy information.

For example, your local filesystem might store timestamps with milliseconds, whereas a given network protocol might only offer seconds. You can use compare to easily check whether the timestamp of a local file is equivalent to a timestamp received via the protocol.

The internal representation of datetime is in milliseconds since 1970-01-01 00:00:00.000 UTC and can handle a range of several million years. While datetime supports negative times (i.e. earlier than 1970-01-01 00:00:00.000 UTC), the underlying platform may not support it.

Remarks
Some *nix systems base their time on TAI instead of UTC, though we pretend there is no difference, as the latter is the default on every modern distribution.
Examples
list.cpp.

Constructor & Destructor Documentation

◆ datetime()

datetime ( std::string_view const &  s,
zone  z 
)
explicit

Construct from string, looks for YYYYmmDD[[[[HH]MM]SS]sss].

See also
bool set(std::string_view const& str, zone z)

Member Function Documentation

◆ compare()

int compare ( datetime const &  op) const

Accuracy-aware comparison against another timestamp.

Conceptually it works as if naively comparing both timestamps after truncating/clamping them to the least common accuracy.

Returns
0 if timestamps are equivalent,
<0 if own timestamp is earlier than the argument,
>0 if own timestamp is late than the argument.

◆ empty()

bool empty ( ) const
Returns
true if no timestamp has been set
Examples
list.cpp.

◆ format()

std::string format ( std::string const &  format,
zone  z 
) const

Format time as string

Parameters
formatis a format string as understood by ::strftime

Note that some format specifiers are locale-dependent.

Examples
list.cpp.

◆ get_rfc822()

std::string get_rfc822 ( ) const

Returns date in the format specified in RFC 822, updated by RFC 1123.

Example:
  • Sun, 06 Nov 1994 08:49:37 GMT

◆ get_tm()

tm get_tm ( zone  z) const

Get timestamp as struct tm.

Undefined if datetime is empty.

Note: On Windows the tm_yday and tm_isdst fields are undefined.

◆ imbue_time()

bool imbue_time ( int  hour,
int  minute,
int  second = -1,
int  millisecond = -1 
)

Adds time to timestamps that only have a day-accuracy.

Changes accuracy based on given parameters. Use -1 in parameters that aren't used.

Returns
Whether the function succeeded. On failure object remains unchanged.

◆ set() [1/3]

bool set ( std::string_view const &  str,
zone  z 
)

Set from string, looks for YYYYmmDD[[[[HH]MM]SS]sss].

Ignores all non-digit characters between fields. For example 20140720T165432 is the same as 2014-07-20 16:54:32

accuracy is set according to the fields present in the string.

Returns
whether setting the timestamp succeeded. On failure object gets cleared

◆ set() [2/3]

bool set ( tm &  t,
accuracy  a,
zone  z 
)

Sets timestamp from struct tm.

Note
Not available on Windows.
Warning
modifies passed structure
Returns
true on success, false on failure. The object is empty after failure.

◆ set() [3/3]

bool set ( zone  z,
int  year,
int  month,
int  day,
int  hour = -1,
int  minute = -1,
int  second = -1,
int  millisecond = -1 
)

Sets the timestamp.

Parameters
month1-indexed as on a calender, e.g. February is 2
day1-indexed as on a calender
hour0-indexed as on a 24h clock
Returns
whether setting the timestamp succeeded. On failure object gets cleared

◆ set_rfc3339()

bool set_rfc3339 ( std::string_view const &  str)

Parses a date in the format specified in RFC 3339

On errors, object gets clears

Returns
whether setting the timestamp succeeded. On failure object gets cleared.
Examples:
1985-04-12T23:20:50.52Z 1996-12-19T16:39:57-08:00

◆ set_rfc822()

bool set_rfc822 ( std::string_view const &  str)

Parses a date in the format specified in RFC 822, either original or updated by RFC 1123. Also supports RFC 850 and ANSI C asctime formats.

Used timezone is always UTC.

On errors, object gets clears

Returns
whether setting the timestamp succeeded. On failure object gets cleared.
Examples:
Sun, 06 Nov 1994 08:49:37 GMT // RFC 822, updated by RFC 1123
Sun, 06-Nov-94 08:49:37 GMT // obsolete RFC 850
Sun Nov 6 08:49:37 1994 // ANSI C asctime

◆ verify_format()

static bool verify_format ( std::string const &  fmt)
static

Verify format strings

Parameters
fmtthe string that is to be tested
Returns
whether the passed string is a format string understood by ::strftime

Friends And Related Function Documentation

◆ operator-

duration operator- ( datetime const &  a,
datetime const &  b 
)
friend

Gets the difference between two timestamps as duration.

This function ignores accuracy, it treats both timestamps as if they had millisecond-accuracy.


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