Correct names of parameters in wxAffineMatrix2D documentation.

[wxWidgets.git] / interface / wx / datetime.h

diff --git a/interface/wx/datetime.h b/interface/wx/datetime.h
index f0751079373fb244f24755fc9add289b48a20720..e7ebd8d9470958101b95b9e29bac16b95f8e19e1 100644 (file)
--- a/interface/wx/datetime.h
+++ b/interface/wx/datetime.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxDateTime
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxDateTime
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -50,7 +50,7 @@
     ParseFormat() which can parse any date in the given (rigid) format.
     ParseRfc822Date() is another function for parsing dates in predefined
     format -- the one of RFC 822 which (still...) defines the format of email
     ParseFormat() which can parse any date in the given (rigid) format.
     ParseRfc822Date() is another function for parsing dates in predefined
     format -- the one of RFC 822 which (still...) defines the format of email

-    messages on the Internet. This format can not be described with
+    messages on the Internet. This format cannot be described with

     @c strptime(3)-like format strings used by Format(), hence the need for a
     separate function.
 
     @c strptime(3)-like format strings used by Format(), hence the need for a
     separate function.
 


@@ -59,7 +59,7 @@
     in 'free' format, i.e. allow them to be specified in any of possible ways.
     These functions will usually be used to parse the (interactive) user input
     which is not bound to be in any predefined format. As an example,
     in 'free' format, i.e. allow them to be specified in any of possible ways.
     These functions will usually be used to parse the (interactive) user input
     which is not bound to be in any predefined format. As an example,

-    ParseDateTime() can parse the strings such as "tomorrow", "March first" and
+    ParseDate() can parse the strings such as "tomorrow", "March first" and

     even "next Sunday".
 
     Finally notice that each of the parsing functions is available in several
     even "next Sunday".
 
     Finally notice that each of the parsing functions is available in several


@@ -102,7 +102,7 @@ public:
         Local,
 
         //@{
         Local,
 
         //@{

-        /// zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
+        /// zones from GMT (= Greenwich Mean Time): they're guaranteed to be

         /// consequent numbers, so writing something like `GMT0 + offset' is
         /// safe if abs(offset) <= 12
 
         /// consequent numbers, so writing something like `GMT0 + offset' is
         /// safe if abs(offset) <= 12
 


@@ -233,7 +233,7 @@ public:
         in the functions whose result depends on it (GetWeekOfYear() and
         GetWeekOfMonth()).
 
         in the functions whose result depends on it (GetWeekOfYear() and
         GetWeekOfMonth()).
 

-        The desired behvaiour may be specified by giving one of the following
+        The desired behaviour may be specified by giving one of the following

         constants as argument to these functions.
     */
     enum WeekFlags
         constants as argument to these functions.
     */
     enum WeekFlags


@@ -244,13 +244,49 @@ public:
     };
 
 
     };
 
 

+    /**
+        Contains broken down date-time representation.
+
+        This struct is analogous to standard C <code>struct tm</code> and uses
+        the same, not always immediately obvious, conventions for its members:
+        notably its mon and mday fields count from 0 while yday counts from 1.
+     */
+    struct Tm
+    {
+        wxDateTime_t msec,  ///< Number of milliseconds.
+                     sec,   ///< Seconds in 0..59 (60 with leap seconds) range.
+                     min,   ///< Minutes in 0..59 range.
+                     hour,  ///< Hours since midnight in 0..23 range.
+                     mday,  ///< Day of the month in 1..31 range.
+                     yday;  ///< Day of the year in 0..365 range.
+        Month mon;          ///< Month, as an enumerated constant.
+        int year;           ///< Year.
+
+        /**
+            Check if the given date/time is valid (in Gregorian calendar).
+
+            Return @false if the components don't correspond to a correct date.
+         */
+        bool IsValid() const;
+
+        /**
+            Return the week day corresponding to this date.
+
+            Unlike the other fields, the week day is not always available and
+            so must be accessed using this method as it is computed on demand
+            when it is called.
+         */
+        WeekDay GetWeekDay();
+    };
+
+

     /**
         @name Constructors, Assignment Operators and Setters
 
         Constructors and various Set() methods are collected here. If you
         construct a date object from separate values for day, month and year,
         you should use IsValid() method to check that the values were correct
     /**
         @name Constructors, Assignment Operators and Setters
 
         Constructors and various Set() methods are collected here. If you
         construct a date object from separate values for day, month and year,
         you should use IsValid() method to check that the values were correct

-        as constructors can not return an error code.
+        as constructors cannot return an error code.

     */
     //@{
 
     */
     //@{
 


@@ -775,7 +811,7 @@ public:
         Returns the combined date-time representation in the ISO 8601 format
         @c "YYYY-MM-DDTHH:MM:SS". The @a sep parameter default value produces
         the result exactly corresponding to the ISO standard, but it can also
         Returns the combined date-time representation in the ISO 8601 format
         @c "YYYY-MM-DDTHH:MM:SS". The @a sep parameter default value produces
         the result exactly corresponding to the ISO standard, but it can also

-        be useful to use a space as seprator if a more human-readable combined
+        be useful to use a space as separator if a more human-readable combined

         date-time representation is needed.
 
         @see FormatISODate(), FormatISOTime(), ParseISOCombined()
         date-time representation is needed.
 
         @see FormatISODate(), FormatISOTime(), ParseISOCombined()


@@ -812,8 +848,7 @@ public:
 
         @see Format()
     */
 
         @see Format()
     */

-    const char* ParseDate(const wxString& date,
-                          wxString::const_iterator* end = NULL);
+    bool ParseDate(const wxString& date, wxString::const_iterator *end);

 
     /**
         Parses the string @a datetime containing the date and time in free
 
     /**
         Parses the string @a datetime containing the date and time in free


@@ -821,14 +856,15 @@ public:
 
         This function tries as hard as it can to interpret the given string as
         date and time. Unlike ParseRfc822Date(), it will accept anything that
 
         This function tries as hard as it can to interpret the given string as
         date and time. Unlike ParseRfc822Date(), it will accept anything that

-        may be accepted and will only reject strings which can not be parsed in
-        any way at all.
+        may be accepted and will only reject strings which cannot be parsed in
+        any way at all. Notice that the function will fail if either date or
+        time part is present but not both, use ParseDate() or ParseTime() to
+        parse strings containing just the date or time component.

 
         See ParseFormat() for the description of function parameters and return
         value.
     */
 
         See ParseFormat() for the description of function parameters and return
         value.
     */

-    const char* ParseDateTime(const wxString& datetime,
-                              wxString::const_iterator* end = NULL);
+    bool ParseDateTime(const wxString& datetime, wxString::const_iterator *end);

 
     /**
         This function parses the string @a date according to the given
 
     /**
         This function parses the string @a date according to the given


@@ -849,12 +885,7 @@ public:
         @a dateDef. If it is not specified, Today() is used as the default
         date.
 
         @a dateDef. If it is not specified, Today() is used as the default
         date.
 

-        Notice that the return value of this method is not actually a pointer
-        but rather an object of a special proxy class which is convertible to
-        either @c char* or @c wchar_t* pointer. This is needed for
-        compatibility with the existing code but the new code should use @a end
-        parameter instead and just test whether the return value is @NULL or
-        not, e.g.:
+        Example of using this function:

         @code
             wxDateTime dt;
             wxString str = "...";
         @code
             wxDateTime dt;
             wxString str = "...";


@@ -875,26 +906,32 @@ public:
             Used to fill in the date components not specified in the @a date
             string.
         @param end
             Used to fill in the date components not specified in the @a date
             string.
         @param end

-            If non-@NULL, will be filled with the iterator pointing to the
-            location where the parsing stopped. If the entire string was
-            consumed, it is set to @c date.end().
+            Will be filled with the iterator pointing to the location where the
+            parsing stopped if the function returns @true. If the entire string
+            was consumed, it is set to @c date.end(). Notice that this argument
+            must be non-@NULL.

         @return
         @return

-            Pointer-like object indicating the location where the scan stopped
-            if parsing was successful or @NULL-like otherwise.
+            @true if at least part of the string was parsed successfully,
+            @false otherwise.

 
         @see Format()
     */
 
         @see Format()
     */

-    const char* ParseFormat(const wxString& date,
-                            const wxString& format = wxDefaultDateTimeFormat,
-                            const wxDateTime& dateDef = wxDefaultDateTime,
-                            wxString::const_iterator* end = NULL);
+    bool ParseFormat(const wxString& date,
+                     const wxString& format,
+                     const wxDateTime& dateDef,
+                     wxString::const_iterator *end);
+
+    /**
+        @overload
+    */
+    bool ParseFormat(const wxString& date,
+                     const wxString& format,
+                     wxString::const_iterator *end);

 
     /**
         @overload
     */
 
     /**
         @overload
     */

-    const char* ParseFormat(const wxString& date,
-                            const wxString& format = wxDefaultDateTimeFormat,
-                            wxString::const_iterator* end = NULL);
+    bool ParseFormat(const wxString& date, wxString::const_iterator *end);

 
     /**
         This function parses the string containing the date and time in ISO
 
     /**
         This function parses the string containing the date and time in ISO


@@ -944,8 +981,7 @@ public:
         See ParseFormat() for the description of function parameters and return
         value.
     */
         See ParseFormat() for the description of function parameters and return
         value.
     */

-    const char* ParseRfc822Date(const wxString& date,
-                                wxString::const_iterator* end = NULL);
+    bool ParseRfc822Date(const wxString& date, wxString::const_iterator *end);

 
     /**
         This functions is like ParseDateTime(), but only allows the time to be
 
     /**
         This functions is like ParseDateTime(), but only allows the time to be


@@ -954,8 +990,7 @@ public:
         See ParseFormat() for the description of function parameters and return
         value.
     */
         See ParseFormat() for the description of function parameters and return
         value.
     */

-    const char* ParseTime(const wxString& time,
-                          wxString::const_iterator* end = NULL);
+    bool ParseTime(const wxString& time, wxString::const_iterator *end);

 
     //@}
 
 
     //@}
 


@@ -1350,7 +1385,7 @@ public:
     static time_t GetTimeNow();
 
     /**
     static time_t GetTimeNow();
 
     /**

-        Returns the current time broken down using the buffer whose adress is
+        Returns the current time broken down using the buffer whose address is

         passed to the function with @a tm to store the result.
     */
     static tm* GetTmNow(struct tm *tm);
         passed to the function with @a tm to store the result.
     */
     static tm* GetTmNow(struct tm *tm);


@@ -1464,6 +1499,10 @@ public:
 */
 const wxDateTime wxDefaultDateTime;
 
 */
 const wxDateTime wxDefaultDateTime;
 

+/*
+    wxInvalidDateTime is an alias for wxDefaultDateTime.
+*/
+#define wxInvalidDateTime wxDefaultDateTime

 
 
 /**
 
 
 /**