Added wxPGChoices::Copy(), tweaked related documentation

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

/////////////////////////////////////////////////////////////////////////////
// Name:        wx/datetime.h
// Purpose:     declarations of time/date related classes (wxDateTime,
//              wxTimeSpan)
// Author:      Vadim Zeitlin
// Modified by:
// Created:     10.02.99
// RCS-ID:      $Id$
// Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

#ifndef _WX_DATETIME_H
#define _WX_DATETIME_H

#include "wx/defs.h"

#if wxUSE_DATETIME

#ifdef __WXWINCE__
    #include "wx/msw/wince/time.h"
#elif !defined(__WXPALMOS5__)
    #include <time.h>
#endif // OS

#include <limits.h>             // for INT_MIN

#include "wx/longlong.h"

class WXDLLIMPEXP_FWD_BASE wxDateTime;
class WXDLLIMPEXP_FWD_BASE wxTimeSpan;
class WXDLLIMPEXP_FWD_BASE wxDateSpan;
#ifdef __WXMSW__
struct _SYSTEMTIME;
#endif

#include "wx/dynarray.h"

// not all c-runtimes are based on 1/1/1970 being (time_t) 0
// set this to the corresponding value in seconds 1/1/1970 has on your
// systems c-runtime

#define WX_TIME_BASE_OFFSET 0

/*
 * TODO
 *
 * + 1. Time zones with minutes (make TimeZone a class)
 * ? 2. getdate() function like under Solaris
 * + 3. text conversion for wxDateSpan
 * + 4. pluggable modules for the workdays calculations
 *   5. wxDateTimeHolidayAuthority for Easter and other christian feasts
 */

/* Two wrapper functions for thread safety */
#ifdef HAVE_LOCALTIME_R
#define wxLocaltime_r localtime_r
#else
WXDLLIMPEXP_BASE struct tm *wxLocaltime_r(const time_t*, struct tm*);
#if wxUSE_THREADS && !defined(__WINDOWS__) && !defined(__WATCOMC__)
     // On Windows, localtime _is_ threadsafe!
#warning using pseudo thread-safe wrapper for localtime to emulate localtime_r
#endif
#endif

#ifdef HAVE_GMTIME_R
#define wxGmtime_r gmtime_r
#else
WXDLLIMPEXP_BASE struct tm *wxGmtime_r(const time_t*, struct tm*);
#if wxUSE_THREADS && !defined(__WINDOWS__) && !defined(__WATCOMC__)
     // On Windows, gmtime _is_ threadsafe!
#warning using pseudo thread-safe wrapper for gmtime to emulate gmtime_r
#endif
#endif

/*
  The three (main) classes declared in this header represent:

  1. An absolute moment in the time (wxDateTime)
  2. A difference between two moments in the time, positive or negative
     (wxTimeSpan)
  3. A logical difference between two dates expressed in
     years/months/weeks/days (wxDateSpan)

  The following arithmetic operations are permitted (all others are not):

  addition
  --------

  wxDateTime + wxTimeSpan = wxDateTime
  wxDateTime + wxDateSpan = wxDateTime
  wxTimeSpan + wxTimeSpan = wxTimeSpan
  wxDateSpan + wxDateSpan = wxDateSpan

  subtraction
  ------------
  wxDateTime - wxDateTime = wxTimeSpan
  wxDateTime - wxTimeSpan = wxDateTime
  wxDateTime - wxDateSpan = wxDateTime
  wxTimeSpan - wxTimeSpan = wxTimeSpan
  wxDateSpan - wxDateSpan = wxDateSpan

  multiplication
  --------------
  wxTimeSpan * number = wxTimeSpan
  number * wxTimeSpan = wxTimeSpan
  wxDateSpan * number = wxDateSpan
  number * wxDateSpan = wxDateSpan

  unitary minus
  -------------
  -wxTimeSpan = wxTimeSpan
  -wxDateSpan = wxDateSpan

  For each binary operation OP (+, -, *) we have the following operatorOP=() as
  a method and the method with a symbolic name OPER (Add, Subtract, Multiply)
  as a synonym for it and another const method with the same name which returns
  the changed copy of the object and operatorOP() as a global function which is
  implemented in terms of the const version of OPEN. For the unary - we have
  operator-() as a method, Neg() as synonym for it and Negate() which returns
  the copy of the object with the changed sign.
*/

// an invalid/default date time object which may be used as the default
// argument for arguments of type wxDateTime; it is also returned by all
// functions returning wxDateTime on failure (this is why it is also called
// wxInvalidDateTime)
class WXDLLIMPEXP_FWD_BASE wxDateTime;

extern WXDLLIMPEXP_DATA_BASE(const char *) wxDefaultDateTimeFormat;
extern WXDLLIMPEXP_DATA_BASE(const char *) wxDefaultTimeSpanFormat;
extern WXDLLIMPEXP_DATA_BASE(const wxDateTime) wxDefaultDateTime;

#define wxInvalidDateTime wxDefaultDateTime

// ----------------------------------------------------------------------------
// wxDateTime represents an absolute moment in the time
// ----------------------------------------------------------------------------

class WXDLLIMPEXP_BASE wxDateTime
{
public:
    // types
    // ------------------------------------------------------------------------

        // a small unsigned integer type for storing things like minutes,
        // seconds &c. It should be at least short (i.e. not char) to contain
        // the number of milliseconds - it may also be 'int' because there is
        // no size penalty associated with it in our code, we don't store any
        // data in this format
    typedef unsigned short wxDateTime_t;

    // constants
    // ------------------------------------------------------------------------

        // the timezones
    enum TZ
    {
        // the time in the current time zone
        Local,

        // zones from GMT (= Greenwhich Mean Time): they're guaranteed to be
        // consequent numbers, so writing something like `GMT0 + offset' is
        // safe if abs(offset) <= 12

        // underscore stands for minus
        GMT_12, GMT_11, GMT_10, GMT_9, GMT_8, GMT_7,
        GMT_6, GMT_5, GMT_4, GMT_3, GMT_2, GMT_1,
        GMT0,
        GMT1, GMT2, GMT3, GMT4, GMT5, GMT6,
        GMT7, GMT8, GMT9, GMT10, GMT11, GMT12, GMT13,
        // Note that GMT12 and GMT_12 are not the same: there is a difference
        // of exactly one day between them

        // some symbolic names for TZ

        // Europe
        WET = GMT0,                         // Western Europe Time
        WEST = GMT1,                        // Western Europe Summer Time
        CET = GMT1,                         // Central Europe Time
        CEST = GMT2,                        // Central Europe Summer Time
        EET = GMT2,                         // Eastern Europe Time
        EEST = GMT3,                        // Eastern Europe Summer Time
        MSK = GMT3,                         // Moscow Time
        MSD = GMT4,                         // Moscow Summer Time

        // US and Canada
        AST = GMT_4,                        // Atlantic Standard Time
        ADT = GMT_3,                        // Atlantic Daylight Time
        EST = GMT_5,                        // Eastern Standard Time
        EDT = GMT_4,                        // Eastern Daylight Saving Time
        CST = GMT_6,                        // Central Standard Time
        CDT = GMT_5,                        // Central Daylight Saving Time
        MST = GMT_7,                        // Mountain Standard Time
        MDT = GMT_6,                        // Mountain Daylight Saving Time
        PST = GMT_8,                        // Pacific Standard Time
        PDT = GMT_7,                        // Pacific Daylight Saving Time
        HST = GMT_10,                       // Hawaiian Standard Time
        AKST = GMT_9,                       // Alaska Standard Time
        AKDT = GMT_8,                       // Alaska Daylight Saving Time

        // Australia

        A_WST = GMT8,                       // Western Standard Time
        A_CST = GMT13 + 1,                  // Central Standard Time (+9.5)
        A_EST = GMT10,                      // Eastern Standard Time
        A_ESST = GMT11,                     // Eastern Summer Time

        // New Zealand
        NZST = GMT12,                       // Standard Time
        NZDT = GMT13,                       // Daylight Saving Time

        // TODO add more symbolic timezone names here

        // Universal Coordinated Time = the new and politically correct name
        // for GMT
        UTC = GMT0
    };

        // the calendar systems we know about: notice that it's valid (for
        // this classes purpose anyhow) to work with any of these calendars
        // even with the dates before the historical appearance of the
        // calendar
    enum Calendar
    {
        Gregorian,  // current calendar
        Julian      // calendar in use since -45 until the 1582 (or later)

        // TODO Hebrew, Chinese, Maya, ... (just kidding) (or then may be not?)
    };

        // these values only are used to identify the different dates of
        // adoption of the Gregorian calendar (see IsGregorian())
        //
        // All data and comments taken verbatim from "The Calendar FAQ (v 2.0)"