Martchus
/
cpp-utilities
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Improve documentation of chrono library

This commit is contained in:
Martchus 2017-12-03 01:45:11 +01:00
parent 602993aa05
commit a89f6f9ce4
6 changed files with 105 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
chrono/datetime.cpp
View File

@ -46,8 +46,15 @@ template <typename num1, typename num2, typename num3> constexpr bool inRangeExc
* 0001 A.D. (C.E.) in the GregorianCalendar calendar (excluding ticks that would
* be added by leap seconds).
* - There is no time zone information associated. Hence different time zones are
* not taken into account when comparing two instances. For instance the
* expression (DateTime::now() - DateTime::gmtNow()) returns one hour in Germany (instead of zero).
* not taken into account when comparing two instances. For instance, the
* expression (DateTime::now() - DateTime::gmtNow()) returns one hour in Germany during winter
* time (instead of zero).
* \todo
* - Add method for parsing custom string formats.
* - Add method for printing to custom string formats.
* - Allow to determine the date part for each compontent at once to prevent multiple
* invocations of getDatePart().
* - Make more methods constexpr.
*/
/*!
@ -74,6 +81,12 @@ DateTime DateTime::fromTimeStampGmt(time_t timeStamp)
/*!
* \brief Parses the given C-style string as DateTime.
* \throws Throws a ConversionException if the specified \a str does not match the expected time format.
*
* The expected format is something like "2012-02-29 15:34:20.033" or "2012/02/29 15:34:20.033". The
* delimiters '-', ':' and '/' are exchangeable.
*
* \sa DateTime::fromIsoString()
*/
DateTime DateTime::fromString(const char *str)
{
@ -110,8 +123,9 @@ DateTime DateTime::fromString(const char *str)
* \brief Parses the specified ISO date time denotation provided as C-style string.
* \returns Returns a pair where the first value is the parsed date time and the second value
* a time span which can be subtracted from the first value to get the UTC time.
* \remarks Not sure whether it is actually ISO conform, but it parses denotations like
* "2016-08-29T21:32:31.588539814+02:00".
*
* Not sure whether it is actually ISO conform, but the expected format is something like
* "2016-08-29T21:32:31.588539814+02:00".
*/
std::pair<DateTime, TimeSpan> DateTime::fromIsoString(const char *str)
{

40
chrono/datetime.h
View File

@ -146,6 +146,7 @@ constexpr inline DateTime::DateTime(uint64 ticks)
/*!
* \brief Constructs a DateTime to the specified \a year, \a month, and \a day.
* \throws Throws a ConversionException if the specified \a year, \a month or \a day is out-of-range.
*/
inline DateTime DateTime::fromDate(int year, int month, int day)
{
@ -154,6 +155,7 @@ inline DateTime DateTime::fromDate(int year, int month, int day)
/*!
* \brief Constructs a DateTime to the specified \a hour, \a minute, \a second and \a millisecond.
* \throws Throws a ConversionException if the specified \a hour, \a minute, \a second or \a millisecond is out-of-range.
*/
inline DateTime DateTime::fromTime(int hour, int minute, int second, double millisecond)
{
@ -162,6 +164,8 @@ inline DateTime DateTime::fromTime(int hour, int minute, int second, double mill
/*!
* \brief Constructs a DateTime to the specified \a year, \a month, \a day, \a hour, \a minute, \a second and \a millisecond.
* \throws Throws a ConversionException if the specified \a year, \a month, \a day, \a hour, \a minute, \a second or \a millisecond
* is out-of-range.
*/
inline DateTime DateTime::fromDateAndTime(int year, int month, int day, int hour, int minute, int second, double millisecond)
{
@ -173,6 +177,12 @@ inline DateTime DateTime::fromDateAndTime(int year, int month, int day, int hour
/*!
* \brief Parses the given std::string as DateTime.
* \throws Throws a ConversionException if the specified \a str does not match the expected time format.
*
* The expected format is something like "2012-02-29 15:34:20.033" or "2012/02/29 15:34:20.033". The
* delimiters '-', ':' and '/' are exchangeable.
*
* \sa DateTime::fromIsoString()
*/
inline DateTime DateTime::fromString(const std::string &str)
{
@ -182,6 +192,7 @@ inline DateTime DateTime::fromString(const std::string &str)
/*!
* \brief Parses the specified ISO date time denotation provided as C-style string.
* \returns Returns the parsed UTC time. That means a possibly denoted time zone delta is subtracted from the time stamp.
* \throws Throws a ConversionException if the specified \a str does not match the expected time format.
* \sa fromIsoString()
*/
inline DateTime DateTime::fromIsoStringGmt(const char *str)
@ -193,6 +204,7 @@ inline DateTime DateTime::fromIsoStringGmt(const char *str)
/*!
* \brief Parses the specified ISO date time denotation provided as C-style string.
* \returns Returns the parsed local time. That means a possibly denoted time zone delta is discarded.
* \throws Throws a ConversionException if the specified \a str does not match the expected time format.
* \sa fromIsoString()
*/
inline DateTime DateTime::fromIsoStringLocal(const char *str)
@ -201,7 +213,7 @@ inline DateTime DateTime::fromIsoStringLocal(const char *str)
}
/*!
* \brief Gets the number of ticks which represent the value of the current instance.
* \brief Returns the number of ticks which represent the value of the current instance.
*/
constexpr inline uint64 DateTime::totalTicks() const
{
@ -209,7 +221,7 @@ constexpr inline uint64 DateTime::totalTicks() const
}
/*!
* \brief Gets the year component of the date represented by this instance.
* \brief Returns the year component of the date represented by this instance.
*/
inline int DateTime::year() const
{
@ -217,7 +229,7 @@ inline int DateTime::year() const
}
/*!
* \brief Gets the month component of the date represented by this instance.
* \brief Returns the month component of the date represented by this instance.
*/
inline int DateTime::month() const
{
@ -225,7 +237,7 @@ inline int DateTime::month() const
}
/*!
* \brief Gets the day component of the date represented by this instance.
* \brief Returns the day component of the date represented by this instance.
*/
inline int DateTime::day() const
{
@ -233,7 +245,7 @@ inline int DateTime::day() const
}
/*!
* \brief Gets the day of the year represented by this instance.
* \brief Returns the day of the year represented by this instance.
*/
inline int DateTime::dayOfYear() const
{
@ -241,7 +253,7 @@ inline int DateTime::dayOfYear() const
}
/*!
* \brief Gets the day of the week represented by this instance.
* \brief Returns the day of the week represented by this instance.
* \sa DayOfWeek
*/
constexpr inline DayOfWeek DateTime::dayOfWeek() const
@ -250,7 +262,7 @@ constexpr inline DayOfWeek DateTime::dayOfWeek() const
}
/*!
* \brief Gets the hour component of the date represented by this instance.
* \brief Returns the hour component of the date represented by this instance.
*/
constexpr inline int DateTime::hour() const
{
@ -258,7 +270,7 @@ constexpr inline int DateTime::hour() const
}
/*!
*\brief Gets the minute component of the date represented by this instance.
*\brief Returns the minute component of the date represented by this instance.
*/
constexpr inline int DateTime::minute() const
{
@ -266,7 +278,7 @@ constexpr inline int DateTime::minute() const
}
/*!
* \brief Gets the second component of the date represented by this instance.
* \brief Returns the second component of the date represented by this instance.
*/
constexpr inline int DateTime::second() const
{
@ -274,7 +286,7 @@ constexpr inline int DateTime::second() const
}
/*!
* \brief Gets the millisecond component of the date represented by this instance.
* \brief Returns the millisecond component of the date represented by this instance.
*/
constexpr inline int DateTime::millisecond() const
{
@ -282,7 +294,7 @@ constexpr inline int DateTime::millisecond() const
}
/*!
* \brief Gets the microsecond component of the date represented by this instance.
* \brief Returns the microsecond component of the date represented by this instance.
*/
constexpr int DateTime::microsecond() const
{
@ -290,7 +302,7 @@ constexpr int DateTime::microsecond() const
}
/*!
* \brief Gets the nanosecond component of the date represented by this instance.
* \brief Returns the nanosecond component of the date represented by this instance.
* \remarks The accuracy of the DateTime class is 100-nanoseconds. Hence the returned value
* will always have two zeros at the end (in decimal representation).
*/
@ -309,7 +321,7 @@ constexpr inline bool DateTime::isNull() const
}
/*!
* \brief Gets the time of day as TimeSpan for this instance.
* \brief Returns the time of day as TimeSpan for this instance.
*/
constexpr inline TimeSpan DateTime::timeOfDay() const
{
@ -468,6 +480,8 @@ constexpr inline TimeSpan DateTime::operator+(const DateTime &other) const
/*!
* \brief Substracts two DateTime instances.
* \returns The result is a TimeSpan.
* \remarks For expressing the delta between two concrete DateTime instances in terms of
* years, month and days, use Period::Period instead.
*/
constexpr inline TimeSpan DateTime::operator-(const DateTime &other) const
{

25
chrono/period.cpp
View File

@ -5,12 +5,35 @@ namespace ChronoUtilities {
/*!
* \class ChronoUtilities::Period
* \brief Represents a period of time.
*
* In contrast to the TimeSpan class, a Period represents a duration between a concrete
* starting DateTime and end DateTime. Without that context, a Period instance is useless.
*
* Note the absence of the TimeSpan::totalYears() and TimeSpan::totalMonth() methods.
* The reason for this limitation of the TimeSpan class is that the TimeSpan is meant to express
* a duration independently of the concrete starting DateTime and end DateTime.
* However, the concrete calendar interval is neccassary for expressing a duration in terms of years
* and months because not all years and months have the same length.
*
* The Period class, on the other hand, expresses the duration between a *concrete* starting DateTime
* and end DateTime as the number of years, month and days which have been passed **in that particular
* order**. The accuracy is one day, so the DateTime::timeOfDay() is lost.
*
* \remarks The order really matters. For example, the Period between DateTime::fromDateAndTime(1994, 7, 18)
* and DateTime::fromDateAndTime(2017, 12, 2) is 23 years, 4 month and 14 days. That means
* 23 years have been passed, then 4 month and finally 14 days. Adding the 14 days first and then
* the 4 month would make a difference of one day because July has 31 days and November only 30.
*/
/*!
* \brief Constructs a new Period defined by a start DateTime and an end DateTime.
*
* The resulting Period will contain the number of years, month and days which have been passed
* between \a begin and \a end.
*
* \todo Pass DateTime objects by value in v5.
*/
Period::Period(const DateTime &beg, const DateTime &end)
Period::Period(const DateTime &begin, const DateTime &end)
{
m_years = end.year() - beg.year();
m_months = end.month() - beg.month();

8
chrono/period.h
View File

@ -7,7 +7,7 @@ namespace ChronoUtilities {
class CPP_UTILITIES_EXPORT Period {
public:
Period(const DateTime &beg, const DateTime &end);
Period(const DateTime &begin, const DateTime &end);
int years() const;
int months() const;
int days() const;
@ -19,7 +19,7 @@ private:
};
/*!
* \brief Gets the years component of the period represented by the current instance.
* \brief Returns the years component of the period represented by the current instance.
*/
inline int Period::years() const
{
@ -27,7 +27,7 @@ inline int Period::years() const
}
/*!
* \brief Gets the months component of the period represented by the current instance.
* \brief Returns the months component of the period represented by the current instance.
*/
inline int Period::months() const
{
@ -35,7 +35,7 @@ inline int Period::months() const
}
/*!
* \brief Gets the days component of the period represented by the current instance.
* \brief Returns the days component of the period represented by the current instance.
*/
inline int Period::days() const
{

13
chrono/timespan.cpp
View File

@ -14,11 +14,24 @@ using namespace ConversionUtilities;
/*!
* \class ChronoUtilities::TimeSpan
* \brief Represents a time interval.
*
* Note that the TimeSpan class is meant to express a time interval independently of the
* concrete starting DateTime and end DateTime and hence can not be expressed in years
* and month. For that use case, use the Period class instead.
*
* \remarks Time values are measured in 100-nanosecond units called ticks.
* \todo
* - Add method for parsing custom string formats.
* - Add method for printing to custom string formats.
*/
/*!
* \brief Parses the given C-style string as TimeSpan.
* \throws Throws a ConversionException if the specified \a str does not match the expected format.
*
* The expected format is "days:hours:minutes:seconds", eg. "5:31:4.521" for 5 hours, 31 minutes
* and 4.521 seconds. So parts at the front can be omitted and the parts can be fractions. The
* colon can be changed by specifying another \a separator.
*/
TimeSpan TimeSpan::fromString(const char *str, char separator)
{

33
chrono/timespan.h
View File

@ -154,6 +154,11 @@ constexpr inline TimeSpan TimeSpan::fromDays(double days)
/*!
* \brief Parses the given std::string as TimeSpan.
* \throws Throws a ConversionException if the specified \a str does not match the expected format.
*
* The expected format is "days:hours:minutes:seconds", eg. "5:31:4.521" for 5 hours, 31 minutes
* and 4.521 seconds. So parts at the front can be omitted and the parts can be fractions. The
* colon can be changed by specifying another \a separator.
*/
inline TimeSpan TimeSpan::fromString(const std::string &str, char separator)
{
@ -177,7 +182,7 @@ constexpr inline TimeSpan TimeSpan::infinity()
}
/*!
* \brief Gets the number of ticks that represent the value of the current TimeSpan class.
* \brief Returns the number of ticks that represent the value of the current TimeSpan class.
*/
constexpr inline int64 TimeSpan::totalTicks() const
{
@ -185,7 +190,7 @@ constexpr inline int64 TimeSpan::totalTicks() const
}
/*!
* \brief Gets the value of the current TimeSpan class expressed in whole and fractional microseconds.
* \brief Returns the value of the current TimeSpan class expressed in whole and fractional microseconds.
*/
constexpr double TimeSpan::totalMicroseconds() const
{
@ -193,7 +198,7 @@ constexpr double TimeSpan::totalMicroseconds() const
}
/*!
* \brief Gets the value of the current TimeSpan class expressed in whole and fractional milliseconds.
* \brief Returns the value of the current TimeSpan class expressed in whole and fractional milliseconds.
*/
constexpr inline double TimeSpan::totalMilliseconds() const
{
@ -201,7 +206,7 @@ constexpr inline double TimeSpan::totalMilliseconds() const
}
/*!
* \brief Gets the value of the current TimeSpan class expressed in whole and fractional seconds.
* \brief Returns the value of the current TimeSpan class expressed in whole and fractional seconds.
*/
constexpr inline double TimeSpan::totalSeconds() const
{
@ -209,7 +214,7 @@ constexpr inline double TimeSpan::totalSeconds() const
}
/*!
* \brief Gets the value of the current TimeSpan class expressed in whole and fractional minutes.
* \brief Returns the value of the current TimeSpan class expressed in whole and fractional minutes.
*/
constexpr inline double TimeSpan::totalMinutes() const
{
@ -217,7 +222,7 @@ constexpr inline double TimeSpan::totalMinutes() const
}
/*!
* \brief Gets the value of the current TimeSpan class expressed in whole and fractional hours.
* \brief Returns the value of the current TimeSpan class expressed in whole and fractional hours.
*/
constexpr inline double TimeSpan::totalHours() const
{
@ -225,7 +230,7 @@ constexpr inline double TimeSpan::totalHours() const
}
/*!
* \brief Gets the value of the current TimeSpan class expressed in whole and fractional days.
* \brief Returns the value of the current TimeSpan class expressed in whole and fractional days.
*/
constexpr inline double TimeSpan::totalDays() const
{
@ -233,7 +238,7 @@ constexpr inline double TimeSpan::totalDays() const
}
/*!
* \brief Gets the nanoseconds component of the time interval represented by the current TimeSpan class.
* \brief Returns the nanoseconds component of the time interval represented by the current TimeSpan class.
* \remarks The accuracy of the TimeSpan class is 100-nanoseconds. Hence the returned value
* will always have two zeros at the end (in decimal representation).
*/
@ -243,7 +248,7 @@ constexpr int TimeSpan::nanoseconds() const
}
/*!
* \brief Gets the microseconds component of the time interval represented by the current TimeSpan class.
* \brief Returns the microseconds component of the time interval represented by the current TimeSpan class.
*/
constexpr int TimeSpan::microseconds() const
{
@ -251,7 +256,7 @@ constexpr int TimeSpan::microseconds() const
}
/*!
* \brief Gets the miliseconds component of the time interval represented by the current TimeSpan class.
* \brief Returns the miliseconds component of the time interval represented by the current TimeSpan class.
*/
constexpr inline int TimeSpan::milliseconds() const
{
@ -259,7 +264,7 @@ constexpr inline int TimeSpan::milliseconds() const
}
/*!
* \brief Gets the seconds component of the time interval represented by the current TimeSpan class.
* \brief Returns the seconds component of the time interval represented by the current TimeSpan class.
*/
constexpr inline int TimeSpan::seconds() const
{
@ -267,7 +272,7 @@ constexpr inline int TimeSpan::seconds() const
}
/*!
* \brief Gets the minutes component of the time interval represented by the current TimeSpan class.
* \brief Returns the minutes component of the time interval represented by the current TimeSpan class.
*/
constexpr inline int TimeSpan::minutes() const
{
@ -275,7 +280,7 @@ constexpr inline int TimeSpan::minutes() const
}
/*!
* \brief Gets the hours component of the time interval represented by the current TimeSpan class.
* \brief Returns the hours component of the time interval represented by the current TimeSpan class.
*/
constexpr inline int TimeSpan::hours() const
{
@ -283,7 +288,7 @@ constexpr inline int TimeSpan::hours() const
}
/*!
* \brief Gets the days component of the time interval represented by the current TimeSpan class.
* \brief Returns the days component of the time interval represented by the current TimeSpan class.
*/
constexpr inline int TimeSpan::days() const
{