diff --git a/chrono/datetime.cpp b/chrono/datetime.cpp index 911fcbd..4f573f5 100644 --- a/chrono/datetime.cpp +++ b/chrono/datetime.cpp @@ -46,8 +46,15 @@ template 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::fromIsoString(const char *str) { diff --git a/chrono/datetime.h b/chrono/datetime.h index 67c01c8..e461df7 100644 --- a/chrono/datetime.h +++ b/chrono/datetime.h @@ -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 { diff --git a/chrono/period.cpp b/chrono/period.cpp index 19e5036..9be51cb 100644 --- a/chrono/period.cpp +++ b/chrono/period.cpp @@ -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(); diff --git a/chrono/period.h b/chrono/period.h index df2a290..1829d28 100644 --- a/chrono/period.h +++ b/chrono/period.h @@ -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 { diff --git a/chrono/timespan.cpp b/chrono/timespan.cpp index 8d457f7..1c554f7 100644 --- a/chrono/timespan.cpp +++ b/chrono/timespan.cpp @@ -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) { diff --git a/chrono/timespan.h b/chrono/timespan.h index aa36928..04a2fc4 100644 --- a/chrono/timespan.h +++ b/chrono/timespan.h @@ -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 {