From: Jason Harris Date: Sun, 12 Mar 2006 07:10:28 +0000 (+0000) Subject: Ok, let' have some DOX, whaddya say? X-Git-Tag: v3.80.2~148 X-Git-Url: https://git.rmz.fi/?a=commitdiff_plain;h=0f9025cdc915606f8fd62e7f4c6fb3fdf40bd89b;p=libqmvoc.git Ok, let' have some DOX, whaddya say? svn path=/trunk/KDE/kdeedu/libkdeedu/; revision=517764 --- diff --git a/extdate/extdatetime.cpp b/extdate/extdatetime.cpp index 7dccf40..58d31c6 100644 --- a/extdate/extdatetime.cpp +++ b/extdate/extdatetime.cpp @@ -191,7 +191,8 @@ int ExtDate::weekNumber( int *yearNum ) const { // the year and week number are those of the next Sunday. ExtDate a_date( jd() - dayOfWeek() + 7); - *yearNum = a_date.year(); + if ( yearNum ) + *yearNum = a_date.year(); return 1 + int( a_date.dayOfYear()/7 ); } @@ -586,62 +587,16 @@ int ExtDate::dayOfYear(int y, int m, int d) \ingroup time - A ExtDateTime object contains a calendar date and a clock time (a - "datetime"). It is a combination of the ExtDate and QTime classes. - It can read the current datetime from the system clock. It - provides functions for comparing datetimes and for manipulating a - datetime by adding a number of seconds, days, months or years. - - A ExtDateTime object is typically created either by giving a date - and time explicitly in the constructor, or by using the static - function currentDateTime(), which returns a ExtDateTime object set - to the system clock's time. The date and time can be changed with - setDate() and setTime(). A datetime can also be set using the - setTime_t() function, which takes a POSIX-standard "number of - seconds since 00:00:00 on January 1, 1970" value. The fromString() - function returns a ExtDateTime given a string and a date format - which is used to interpret the date within the string. - - The date() and time() functions provide access to the date and - time parts of the datetime. The same information is provided in - textual format by the toString() function. - - ExtDateTime provides a full set of operators to compare two - ExtDateTime objects where smaller means earlier and larger means - later. - - You can increment (or decrement) a datetime by a given number of - seconds using addSecs() or days using addDays(). Similarly you can - use addMonths() and addYears(). The daysTo() function returns the - number of days between two datetimes, and secsTo() returns the - number of seconds between two datetimes. - - The range of a datetime object is constrained to the ranges of the - ExtDate and QTime objects which it embodies. - - Methods in this class are reentrant. \sa ExtDate QTime ExtDateTimeEdit */ - -/*! - \fn ExtDateTime::ExtDateTime() - - Constructs a null datetime (i.e. null date and null time). A null - datetime is invalid, since the date is invalid. - - \sa isValid() -*/ - - -/*! - Constructs a datetime with date \a date and null (but valid) time - (00:00:00.000). -*/ +ExtDateTime::ExtDateTime() { + ExtDateTime( ExtDate(), QTime() ); +} ExtDateTime::ExtDateTime( const ExtDate &date ) - : d(date) + : d(date), t(QTime(0,0,0) { } diff --git a/extdate/extdatetime.h b/extdate/extdatetime.h index c499a50..de281c3 100644 --- a/extdate/extdatetime.h +++ b/extdate/extdatetime.h @@ -1,17 +1,26 @@ -/************************************************************************* -** Definition of extended range date class -** (c) 2004 by Michel Guitel -** modifications by Jason Harris -** -** This file may be distributed and/or modified under the terms of the -** GNU General Public License version 2 as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL included in the -** packaging of this file. -** -** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE -** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. -** -**********************************************************************/ +/*************************************************************************** + + extdatetime.h + ------------- + Copyright (c) 2004 by Michel Guitel + Copyright (c) 2004-2006 by Jason Harris + + This code was adapted from the Qt classes QDate and QDateTime, + copyright Trolltech, Inc. andlicensed under the GNU GPL. + + If there is ever a need for an LGPL version of these classes, they + will need to be reimplemented from scratch to avoid violating + Trolltech's license. + + ***************************************************************************/ +/*************************************************************************** + * * + * This program is free software; you can redistribute it and/or modify * + * it under the terms of the GNU General Public License as published by * + * the Free Software Foundation; either version 2 of the License, or * + * (at your option) any later version. * + * * + ***************************************************************************/ #ifndef EXTDATETIME_H #define EXTDATETIME_H @@ -26,81 +35,367 @@ class ExtDateTime; -/***************************************************************************** - ExtDate class - *****************************************************************************/ - +/** + *@fn test2_unit + *@short A function used in the unit tests for this class + *@note there is no reason to use this function outside the unit tests + *@param y the year to be tested + *@param m the month to be tested + *@param d the day to be tested + */ extern void test2_unit(int y, int m, int d); -class ExtDateTime; - +/** + *@class ExtDate + *@short Extended-range date class + * + *ExtDate encapsulates the calendar date. It is functionally identical + *to the Qt class QDate, except that it allows for dates far outside the + *range of valid QDates (years 1752-8000). In fact, there is no limit + *to the range of dates posiible, but for practical reasons we limit + *the range of allowable years to -50000 to 50000. + * + *@author Michael Guitel, Jason Harris + */ class KDE_EXPORT ExtDate { -public: - ExtDate() : m_jd(INVALID_DAY), m_year(0), m_month(0), m_day(0) {} + public: + /** + *@short Default constructor + *Create an invalid date + */ + ExtDate() : m_jd(INVALID_DAY), m_year(0), m_month(0), m_day(0) {} + /** + *@short Constructor + *Create an ExtDate for the specified calendar date + *@p y The year of the date to be created + *@p m The month of the date to be created + *@p d The day of the date to be created + *@note The year must be in the range -50000 to 50000. + */ ExtDate( int y, int m, int d ); + /** + *@short Constructor + *Create an ExtDate from the specified QDate + *@p q The QDate representing the date to be created + *@note Of course, this will not work if you need a date outside the + *valid Qt range (years 1752-8000). + */ ExtDate( const QDate &q ) { ExtDate( q.year(), q.month(), q.day() ); } + /** + *@short Constructor + *Create an ExtDate for the specified Julian Day. + *@p jd the Julian Day of the date to be created + *@note The Julian Day is a simple count of the number of days + *elapsed since January 1st, in the year -4713. + */ ExtDate( long int jd ); + /** + *@return true if the ExtDate is an Null date + *@note a Null date is one that was created with the default + *constructor. Null dates are also invalid dates. + *@sa isValid() + */ bool isNull() const { return m_jd == INVALID_DAY; } + + /** + *@return true if the ExtDate is a valid date. + *@note A date may be invalid if it is a Null date, if + *its year value exceeds the valid range (-50000 to 50000), or + *if its month or day values are out of bounds. + */ bool isValid() const; + /** + *@return the ExtDate, converted to a QDate. + *@note If the ExtDate is invalid or falls outside the range + *of valid QDates (years 1752 to 8000), the QDate returned will + *be invalid. + */ QDate qdate() const; - + + /** + *@return the year of the ExtDate + */ int year() const { return m_year; } + /** + *@return the month of the ExtDate, as an integer between 1 and 12 + *@sa monthName() + *@sa longMonthName() + *@sa shortMonthName() + */ int month() const { return m_month; } + /** + *@return the day of the ExtDate, as an integer between 1 and 31 + */ int day() const { return m_day; } + /** + *@return the day-of-the week of the ExtDate, as an integer between 1 and 7 + *@sa dayName() + *@sa longDayName() + *@sa shortDayName() + */ int dayOfWeek() const; + /** + *@return the ExtDate's position within the current year, as an integer + *between 1 and 366. + */ int dayOfYear() const; + /** + *@return the number of days in the ExtDate's month, as an integer + *between 28 and 31. + */ int daysInMonth() const; + /** + *@return the number of days in the ExtDate's year. + *@note The returned value is either 365, or 366 if it is a leap year. + */ int daysInYear() const; - int weekNumber( int *yearNum = 0 ) const; + /** + *@return the position within the current year of the week containing + *the ExtDate. + *@p yearNum pointer integer, which is set to the year to which the week + *belongs + *@note It is possible for dates near the end of the year to belong to + *the first week of the following year. + */ + int weekNumber( int *yearNum=0 ) const; + /** + *@return the Julian Day representation of the ExtDate. + *@note The Julian Day is a simple count of the number of days + *elapsed since January 1st, in the year -4713. + */ long int jd() const { return m_jd; } #ifndef QT_NO_TEXTDATE #ifndef QT_NO_COMPAT + /** + *@return the short name of the ExtDate's month (for example, + "Aug", short for "August"). + *@note This function is identical to shortMonthName(), and is + *provided for convenience. + *@sa shortMonthName() + */ static QString monthName( int month ) { return shortMonthName( month ); } + /** + *@return the short name of the ExtDate's day-of-week (for example, + *"Thu", short for "Thursday"). + *@note This function is identical to shortDayName(), and is + *provided for convenience. + *@sa shortDayName() + */ static QString dayName( int weekday ) { return shortDayName( weekday ); } #endif + /** + *@return the short name of the ExtDate's month (for example, + "Aug", short for "August"). + */ static QString shortMonthName( int month ); + /** + *@return the short name of the ExtDate's day-of-week (for example, + *"Thu", short for "Thursday"). + */ static QString shortDayName( int weekday ); + /** + *@return the long name of the ExtDate's month (for example, "August"). + */ static QString longMonthName( int month ); + /** + *@return the long name of the ExtDate's day-of-week (for example, + *"Thursday"). + */ static QString longDayName( int weekday ); #endif //QT_NO_TEXTDATE #ifndef QT_NO_TEXTSTRING #if !defined(QT_NO_SPRINTF) + /** + *@return a string representation of the ExtDate according to + *the given date format. + *@p f the Qt::DateFormat describing the date string + *@see Qt::DateFormat + */ QString toString( Qt::DateFormat f = Qt::TextDate ) const; #endif + /** + *@return a string representation of the ExtDate according to + *the given date format. + *@p format a QString describing the date format according to + *a subset of the KDE date string specification: + * + *Any occurence of the following tokens in the format string + *are replaced with the corresponding value: + * + *@li %Y The year, including centuries prefix (e.g., "1984") + *@li %y The year, excluding centuries prefix (e.g., "84") + *@li %n Numerical month value (e.g., "3" for March) + *@li %m Numerical month value, two digits (e.g., "03" for March) + *@li %e Numerical day value (e.g., "3" on March 3rd) + *@li %d Numerical day value, two digits (e.g., "03" on March 3rd) + *@li %b Month name, short form (e.g., "Mar" for March) + *@li %B Month name, long form (e.g., "March") + *@li %a Weekday name, short form (e.g., "Wed" for Wednesday) + *@li %A Weekday name, long form (e.g., "Wednesday") + * + *All other characters in the format string are left as-is. + */ QString toString( const QString& format ) const; #endif + /** + *@short Set the ExtDate according to the given year, month and day. + *@p y the year of the date to be set + *@p m the month of the date to be set + *@p d the day of the date to be set + *@return true if the ExtDate is valid + */ bool setYMD( int y, int m, int d ); + /** + *@short Set the ExtDate acording to the given Julian Day. + *@p _jd the Julian Day of the date to be set + *@return true if the ExtDate is valid + *@note The Julian Day is a simple count of the number of days + *elapsed since January 1st, in the year -4713. + */ bool setJD( long int _jd ); + /** + *@return an ExtDate created by adding the given number of days + *to this ExtDate object. + *@p days the number of days to add to the current ExtDate. The + *numbers of days may be negative. + *@note The current ExtDate object is not affected by this function; + *the modified ExtDate is provided in the return value. + */ ExtDate addDays( int days ) const; + /** + *@return an ExtDate created by adding the given number of months + *to this ExtDate object. + *@p months the number of months to add to the current ExtDate. The + *numbers of months may be negative. + *@note The current ExtDate object is not affected by this function; + *the modified ExtDate is provided in the return value. + */ ExtDate addMonths( int months ) const; + /** + *@return an ExtDate created by adding the given number of years + *to this ExtDate object. + *@p years the number of years to add to the current ExtDate. The + *numbers of years may be negative. + *@note The current ExtDate object is not affected by this function; + *the modified ExtDate is provided in the return value. + */ ExtDate addYears( int years ) const; - int daysTo( const ExtDate & ) const; + /** + *@return The number of days between the current ExtDate and the + *ExtDate provided as an argument. For example, if the current + *ExtDate is March 15, 2006 and the ExtDate given as an argument + *represents March 18, 2006, then this function wuld return 3. + *@p d the target date to which the number of days will be counted + */ + int daysTo( const ExtDate &d ) const; + /** + *@return true if the two ExtDates are equal + */ bool operator==( const ExtDate &d ) const { return m_jd == d.jd(); }; + /** + *@return true if the two ExtDates are not equal + */ bool operator!=( const ExtDate &d ) const { return m_jd != d.jd(); }; + /** + *@return true if the left-hand ExtDate is earlier than the + *right-hand ExtDate + */ bool operator<( const ExtDate &d ) const { return m_jd < d.jd(); }; + /** + *@return true if the left-hand ExtDate is earlier than or equal to the + *right-hand ExtDate + */ bool operator<=( const ExtDate &d ) const { return m_jd <= d.jd(); }; + /** + *@return true if the left-hand ExtDate is later than the + *right-hand ExtDate + */ bool operator>( const ExtDate &d ) const { return m_jd > d.jd(); }; + /** + *@return true if the left-hand ExtDate is later than or equal to the + *right-hand ExtDate + */ bool operator>=( const ExtDate &d ) const { return m_jd >= d.jd(); }; + /** + *@return an ExtDate representing the current date, according to the + *computer's clock. + *@p ts a Qt::TimeSpec value that determines whether the date is + *computed from the Local Time or the Universal Time. + *@sa Qt::TimeSpec + */ static ExtDate currentDate( Qt::TimeSpec ts = Qt::LocalTime ); #ifndef QT_NO_DATESTRING + /** + *@return an ExtDate constructed from the string representation + *given as an argument. + *@p s The string representation of the date + *@note No sring format is specified, so this function will attempt + *both Qt::TextDate and Qt::ISODate formats. + */ static ExtDate fromString( const QString& s ); - static ExtDate fromString( const QString& s, Qt::DateFormat ); + /** + *@return an ExtDate constructed from the string representation + *given as an argument. + *@p s The string representation of the date + *@p f The Qt::DateFormat with which to interpret the date string + *@note This function only understands Qt::TextDate and Qt::ISODate + *formats. It does not handle Qt::LocalDate. + */ + static ExtDate fromString( const QString& s, Qt::DateFormat f); + /** + *@return an ExtDate constructed from the string representation + *given as an argument. + *@p s The string representation of the date + *@p format A string representing the date format, acording to + *the KDE date string specification. + *@see ExtDate::toString( const QString &format ) + */ static ExtDate fromString( const QString& s, const QString &format ); #endif + /** + *@return true if the date described by the arguments is valid + *@p y the year of the date to be tested + *@p m the month of the date to be tested + *@p d the day of the date to be tested + */ static bool isValid( int y, int m, int d ); + /** + *@return true if the given year is a leap year. + *@p year the year to be tested + */ static bool leapYear( int year ); + /** + *@return the Julian Day corresponding to the date described by + *the arguments + *@p y The year of the date to be converted + *@p m The month of the date to be converted + *@p d The day of the date to be converted + */ static long int GregorianToJD( int y, int m, int d ); + /** + *@return the year, month and day corresponding to the given Julian Day + *@p jd The Julian Day to be converted + *@p y The date's year is returned as a reference through this argument + *@p m The date's month is returned as a reference through this argument + *@p d The date's day is returned as a reference through this argument + */ static void JDToGregorian( long int jd, int &y, int &m, int &d ); private: + /** + *@return the position within the year of the date described by the arguments + *@p y the year of the date + *@p m the month of the date + *@p d the day of the date + */ static int dayOfYear(int y, int m, int d); long int m_jd; @@ -122,59 +417,212 @@ private: #endif }; -/***************************************************************************** - ExtDateTime class - *****************************************************************************/ - +/** + *@class ExtDateTime + *@short Extended-range date class + * + *ExtDateTime encapsulates the calendar date and time. It is functionally + *identical to the Qt class QDateTime, except that it allows for dates + *far outside the range of valid QDates (years 1752-8000). In fact, there + *is no limit to the range of dates posiible, but for practical reasons we + *limit the range of allowable years to -50000 to 50000. + * + *@author Michael Guitel, Jason Harris + */ class KDE_EXPORT ExtDateTime { public: - ExtDateTime() {} // set null date and null time - ExtDateTime( const ExtDate & ); - ExtDateTime( const ExtDate &, const QTime & ); - - bool isNull() const { return d.isNull() && t.isNull(); } - bool isValid() const { return d.isValid() && t.isValid(); } - - ExtDate date() const { return d; } - QTime time() const { return t; } - uint toTime_t() const; - void setDate( const ExtDate &date ) { d = date; } - void setTime( const QTime &time ) { t = time; } - void setTime_t( uint secsSince1Jan1970UTC ); - void setTime_t( uint secsSince1Jan1970UTC, Qt::TimeSpec ); + /** + *@short Default constructor. Creates a null ExtDateTime object. + */ + ExtDateTime(); + /** + *@short Constructor. Sets date according to the argument; + *the time is set to midnight. + *@p d The date to be set + */ + ExtDateTime( const ExtDate &d ); + /** + *@short Constructor. Sets date and time according to the argument; + *@p d The date to be set + *@p t The time to be set + */ + ExtDateTime( const ExtDate &d, const QTime &t ); + + /** + *@return true if the object specifies a null Date/Time. + *@note Null Date/Times are also invalid Date/Times + *@sa isValid() + */ + bool isNull() const { return d.isNull() && t.isNull(); } + /** + *@return true if the both the Date and Time specified in the + *object are valid + */ + bool isValid() const { return d.isValid() && t.isValid(); } + + /** + *@return The ExtDate component of the Date/Time + */ + ExtDate date() const { return d; } + /** + *@return The QTime component of the Date/Time + */ + QTime time() const { return t; } + /** + *@return unsigned int corresponding to the UNIX representation + *of the Date/Time. + */ + uint toTime_t() const; + /** + *@short set the ExtDate component to the given argument, leaving the + *QTime component at its current value + *@p date the ExtDate to be set + */ + void setDate( const ExtDate &date ) { d = date; } + /** + *@short set the QTime component to the given argument, leaving the + *ExtDate component at its current value + *@p time the QTimee to be set + */ + void setTime( const QTime &time ) { t = time; } + /** + *@short set the Date/Time by converting from the given + *UNIX time. + *@p secs the UNIX time to convert + *@note UNIX time is the number of seconds since 1970 Jan 1 00:00 + */ + void setTime_t( uint secs ); + /** + *@short set the Date/Time by converting from the given + *UNIX time. + *@p secs the UNIX time to convert + *@p ts Specifies whether Universal Time or Local Time should be set. + *@note UNIX time is the number of seconds since 1970 Jan 1 00:00 + */ + void setTime_t( uint secs, Qt::TimeSpec ts); #ifndef QT_NO_DATESTRING #ifndef QT_NO_SPRINTF - QString toString( Qt::DateFormat f = Qt::TextDate ) const; + /** + *@return a string representation of the Date/Time according to + *the given date format. + *@p f the Qt::DateFormat describing the date string + *@sa ExtDate::toString( Qt::DateFormat ) + */ + QString toString( Qt::DateFormat f = Qt::TextDate ) const; #endif - QString toString( const QString& format ) const; + /** + *@return a string representation of the Date/Time according to + *the given date format. + *@p format string representation of the date/time format, using + *the KDE date/time string specification: + * + *Any occurence of the following tokens in the format string + *are replaced with the corresponding value: + * + *@li %Y The year, including centuries prefix (e.g., "1984") + *@li %y The year, excluding centuries prefix (e.g., "84") + *@li %n Numerical month value (e.g., "3" for March) + *@li %m Numerical month value, two digits (e.g., "03" for March) + *@li %e Numerical day value (e.g., "3" on March 3rd) + *@li %d Numerical day value, two digits (e.g., "03" on March 3rd) + *@li %b Month name, short form (e.g., "Mar" for March) + *@li %B Month name, long form (e.g., "March") + *@li %a Weekday name, short form (e.g., "Wed" for Wednesday) + *@li %A Weekday name, long form (e.g., "Wednesday") + *@li %H Hour in 24h format, 2 digits + *@li %k Hour in 24h format, 1-2 digits + *@li %I Hour in 12h format, 2 digits + *@li %l Hour in 12h format, 1-2 digits + *@li %M Minute, 2 digits + *@li %S Seconds, 2 digits + *@li %p pm/am + * + *All other characters in the format string are left as-is. + * + *@sa ExtDate::toString( Qt::DateFormat ) + */ + QString toString( const QString& format ) const; #endif - ExtDateTime addDays( int days ) const; - ExtDateTime addMonths( int months ) const; - ExtDateTime addYears( int years ) const; - ExtDateTime addSecs( int secs ) const; - int daysTo( const ExtDateTime & ) const; - int secsTo( const ExtDateTime & ) const; - - bool operator==( const ExtDateTime &dt ) const; - bool operator!=( const ExtDateTime &dt ) const; - bool operator<( const ExtDateTime &dt ) const; - bool operator<=( const ExtDateTime &dt ) const; - bool operator>( const ExtDateTime &dt ) const; - bool operator>=( const ExtDateTime &dt ) const; - - static ExtDateTime currentDateTime(); - static ExtDateTime currentDateTime( Qt::TimeSpec ); + /** + *@return an ExtDateTime constructed by adding the given number + *of days to the current Date/Time. + *@p days the number of days to add to the current Date/Time. + *@note the number of days can be negative + */ + ExtDateTime addDays( int days ) const; + /** + *@return an ExtDateTime constructed by adding the given number + *of months to the current Date/Time. + *@p months the number of months to add to the current Date/Time. + *@note the number of months can be negative + */ + ExtDateTime addMonths( int months ) const; + /** + *@return an ExtDateTime constructed by adding the given number + *of years to the current Date/Time. + *@p years the number of years to add to the current Date/Time. + *@note the number of years can be negative + */ + ExtDateTime addYears( int years ) const; + /** + *@return an ExtDateTime constructed by adding the given number + *of seconds to the current Date/Time. + *@p seconds the number of days to add to the current Date/Time. + *@note the number of seconds can be negative + */ + ExtDateTime addSecs( int secs ) const; + /** + *@return the number of days between the current Date/Time and the + *target Date/Time given as the argument. + *@p dt the target Date/Time + */ + int daysTo( const ExtDateTime &dt ) const; + /** + *@return the number of seconds between the current Date/Time and the + *target Date/Time given as the argument. + *@p dt the target Date/Time + */ + int secsTo( const ExtDateTime &dt ) const; + + bool operator==( const ExtDateTime &dt ) const; + bool operator!=( const ExtDateTime &dt ) const; + bool operator<( const ExtDateTime &dt ) const; + bool operator<=( const ExtDateTime &dt ) const; + bool operator>( const ExtDateTime &dt ) const; + bool operator>=( const ExtDateTime &dt ) const; + + /** + *@return Date/Time constructed from the current date and time + *according to the compter's clock. + */ + static ExtDateTime currentDateTime(); + /** + *@return Date/Time constructed from the current date and time + *according to the compter's clock. + *@p ts Specifies whether to interpret the computer time as + *Universal Time or Local Time. + */ + static ExtDateTime currentDateTime( Qt::TimeSpec ts ); #ifndef QT_NO_DATESTRING - static ExtDateTime fromString( const QString& s ); - static ExtDateTime fromString( const QString& s, Qt::DateFormat f ); + /** + *@return ExtDateTime constructed from the given strng representation + *@p s String representation of the Date/Time + */ + static ExtDateTime fromString( const QString& s ); + /** + *@return ExtDateTime constructed from the given strng representation + *@p s String representation of the Date/Time + *@p f Specifies the Date format to use in interpretng the string. + */ + static ExtDateTime fromString( const QString& s, Qt::DateFormat f ); #endif -private: - ExtDate d; - QTime t; + private: + ExtDate d; + QTime t; #ifndef QT_NO_DATASTREAM - friend KDE_EXPORT QDataStream &operator<<( QDataStream &, const ExtDateTime &); - friend KDE_EXPORT QDataStream &operator>>( QDataStream &, ExtDateTime & ); + friend KDE_EXPORT QDataStream &operator<<( QDataStream &, const ExtDateTime &); + friend KDE_EXPORT QDataStream &operator>>( QDataStream &, ExtDateTime & ); #endif };