libfilezilla
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros
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 ()=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 const &s, zone z)
 Construct from string, looks for YYYYmmDD[[[[HH]MM]SS]sss]. More...
 
 datetime (std::wstring 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
 
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 const &str, zone z)
 Set from string, looks for YYYYmmDD[[[[HH]MM]SS]sss]. More...
 
bool set (std::wstring 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.
 
FILETIME get_filetime () const
 Windows-only: Get timestamp as FILETIME.
 
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
 
Adding/subtracting duration intervals

Adding or subracting 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 plaform 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 ( std::string const &  s,
zone  z 
)
explicit

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

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

Member Function Documentation

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.
bool empty ( ) const
Returns
true if no timestamp has been set
Examples:
list.cpp.
std::string format ( std::string const &  format,
zone  z 
) const

Format time as string

Parameters
formatis a format string as understood by ::strftime
Examples:
list.cpp.
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.
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
bool set ( std::string 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
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.
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

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: