wydate.3wy

一个不错

.\"
.\" Edited by I.J.Wang, 2004
.\"
.TH WyDate 3wy "libwy v0.31"
.SH NAME
WyDate \- class of calendar time
.SH SYNOPSIS
.B #include <wydate.h>
.PP
WyDate deals with the calendar \fBdate\fP (year, month, day,...) of given time
zone and the mapping relationship with UTC time (Universal Coordinated Time,
linear time of time zone "UTC")

WyDate interprets the time and date via the underlying system provided functions
(localtime_r,mktime), object state is dependent on system time zone data.

Applications can also get the system time by Wy::now(), or set the system time
by Wy::set_systime(...), or get the local time zone name by Wy::local_tzname() 

Warning: Class implement uses TZ heavily, concurrent use of system time 
functions (mktime, localtime,..) through other than this library
and TZ environment variable can corrupt programs at times.

Note: Object equivalence includes exact match of time zone string.
      Comparing object's utc_time() may be really wanted.
.SH "PUBLIC MEMBERS"
 class \fBReply\fP : public WyRet
 \fBWyDate\fP() throw(Reply)
 \fBWyDate\fP(const WyDate&) throw(Reply)
 \fBWyDate\fP(const char*,const WyTimeSpec&)
 \fBWyDate\fP(const char*,int,int,int,int,int,int)
 \fBWyDate\fP(const WyStr&,const WyTimeSpec&)
 \fBWyDate\fP(const WyStr&,int,int,int,int,int,int)
 \fBWyDate\fP(WyDate&, Wy::ByMove_t) throw()
 \fB~WyDate\fP() throw()
 bool \fBis_default\fP(void) const throw()
 void \fBreset\fP(void) throw()
 WyRet \fBreset\fP(const WyDate&) throw()
 WyRet \fBreset\fP(const char*,const WyTimeSpec&)
 WyRet \fBreset\fP(const char*,int,int,int,int,int,int)
 WyRet \fBreset\fP(const WyStr&,const WyTimeSpec&)
 WyRet \fBreset\fP(const WyStr&,int,int,int,int,int,int)
 void \fBswap\fP(WyDate&) throw()
 const WyStr& \fBtime_zone\fP(void) const throw()
 int \fByear\fP(void) const throw()
 int \fBmonth\fP(void) const throw()
 int \fBmday\fP(void) const throw()
 int \fBhour\fP(void) const throw()
 int \fBmin\fP(void) const throw()
 int \fBsec\fP(void) const throw()
 int \fBwday\fP(void) const throw()
 int \fByday\fP(void) const throw()
 int \fBisdst\fP(void) const throw()
 WyTimeSpec \fButc_time\fP(void) const throw()
 WyRet \fBset_utc\fP(const WyTimeSpec&)
 WyRet \fBset_date\fP(int,int,int,int,int,int)
 WyRet \fBadd\fP(const WyTimeSpec&)
 const WyDate& \fBoperator =\fP(const WyDate&) throw(Reply)
 const WyDate& \fBoperator +=\fP(const WyTimeSpec&)
 bool \fBoperator ==\fP(const WyDate&) const throw()
 bool \fBoperator !=\fP(const WyDate&) const throw()
.SH "AUXILIARY FUNCTIONS"
 WyDate \fBoperator +\fP(const WyDate&,const WyTimeSpec&)
 WyDate \fBoperator +\fP(const WyTimeSpec&,const WyDate&)
.SH "DESCRIPTION"
.\"--------------------------------------------
.PP
.BI "class Reply : public WyRet
.PP
    Class specific throw type
.\"--------------------------------------------
.PP
.BI "WyDate() throw(Reply)"
.PP
    Construct default object. 

     time_zone() = "UTC"   Time zone of UTC's clock
      utc_time() = WyTimeSpec(0,0)
          year() = 1970 (1970 A.D.)
         month() = 1    (January)  [1-12]
          mday() = 1    (1st)      [1-31]
          hour() = 0               [0-23]
           min() = 0               [0-59]
           sec() = 0               [0-61]
          wday() = 4    (Thursday) [0-6]
          yday() = 0
         isdst() = 0
.PP
    [\fBThrow\fP] Reply
            Wym_ENOMEM      Not enough memory
.\"--------------------------------------------
.PP
.BI "WyDate(const WyDate& " "date" ") throw(Reply)"
.PP
    Construct object by copy from \fIdate\fP.

     time_zone() = copy from \fIdate\fP
      utc_time() = ditto
          year() = ditto
         month() = ditto
          mday() = ditto
          hour() = ditto
           min() = ditto
           sec() = ditto
          wday() = ditto
          yday() = ditto
         isdst() = ditto
.PP
    [\fBThrow\fP] Reply
            Wym_ENOMEM      Not enough memory
.\"--------------------------------------------
.PP
.BI "WyDate(const char* " "tzval" ", const WyTimeSpec& " "ucs" ")"
.PP
.BI "WyDate(const WyStr& " "tzval" ", const WyTimeSpec& " "ucs" ")"
.PP
    Construct object for the time zone \fItzval\fP, of which the date
    corresponds to UTC linear time \fIucs\fP

     time_zone() = \fItzval\fP   Time zone string
      utc_time() = \fIucs\fP
          year() = computed
         month() = computed
          mday() = computed
          hour() = computed
           min() = computed
           sec() = computed
          wday() = computed
          yday() = computed
         isdst() = computed

    \fItzval\fP may be used to set environment variable \fBTZ\fP temporarily
    for the underlying C function call. 

    Warning: Unrecognized \fItzval\fP may be taken as if it were "UTC"
.PP
    [\fBThrow\fP] Reply
            Wym_EFAULT      Inaccessible address
            Wym_EINVAL      Unrecognized \fItzval\fP
            Wym_ERANGE      Argument overrange
            Wym_ENOMEM      Not enough memory
.PP 
    [\fBRefer\fP] ::localtime_r
.\"--------------------------------------------
.PP
.BI "WyDate(const char* " "tzval" ",int " "year" ",int " "month" ",int " "mday" ",int " "hour" ",int " "min" ",int " "sec" ")"
.PP
.BI "WyDate(const WyStr& " "tzval" ",int " "year" ",int " "month" ",int " "mday" ",int " "hour" ",int " "min" ",int " "sec" ")"
.PP
    Construct object for the time zone \fItzval\fP, the date is given as the
    arguments indicate.

     time_zone() = \fItzval\fP   Time zone string
      utc_time() = computed
          year() = \fIyear\fP   [A.D. year]
         month() = \fImonth\fP  [1-12]
          mday() = \fImday\fP   [1-31]
          hour() = \fIhour\fP   [0-23]
           min() = \fImin\fP    [0-59]
           sec() = \fIsec\fP    [0-61]
          wday() = computed
          yday() = computed
         isdst() = computed

    \fItzval\fP may be used to set environment variable \fBTZ\fP temporarily
    for the underlying C function call

    Warning: Unrecognized \fItzval\fP may be taken as if it were "UTC"
.PP
    [\fBThrow\fP] Reply
            Wym_EFAULT      Inaccessible address
            Wym_EINVAL      Unrecognized \fItzval\fP
            Wym_ERANGE      Argument overrange
            Wym_ENOMEM      Not enough memory
.PP 
    [\fBRefer\fP] ::mktime
.\"--------------------------------------------
.PP
.BI "WyDate(WyDate& " "src" ", Wy::ByMove_t) throw()"
.PP
    See Wy_Array(Wy_Array&, Wy::ByMove_t) in wy_array(3wy)
    for definition of the move constructor.
.\"--------------------------------------------
.PP
.BI "~WyDate() throw()"
.PP
    Destruct *this
.\"--------------------------------------------
.PP
.BI "bool is_default(void) const throw()"
.PP
    Is *this equivalent to the default object
.PP
    [\fBRet\fP] true= object is equivalent to WyDate()
         false= otherwise
.\"--------------------------------------------
.PP
.BI "void swap(WyDate& " "date" ") throw()"
.PP
    Interchange state of *this with \fIdate\fP
.\"--------------------------------------------
.PP
.BI "void reset(void) throw()" 
.PP
    Reconstruct *this to the state as WyDate()
.\"--------------------------------------------
.PP
.BI "WyRet reset(const WyDate& " "tm" ") throw()"
.PP
    Reconstruct *this to the state as WyDate(\fItm\fP)
.PP
    [\fBRet\fP] Ok              Succeed
          Wym_ENOMEM      Not enough memory
.\"--------------------------------------------
.PP
.BI "WyRet reset(const char* " "tzval" ", const WyTimeSpec& " "ucs" ")"
.PP
.BI "WyRet reset(const WyStr& " "tzval" ", const WyTimeSpec& " "ucs" ")"
.PP
    Reconstruct *this to the state as WyDate(\fItzval\fP,\fIucs\fP)
.PP
    [\fBRet\fP] Ok              Succeed
          Wym_EFAULT      Inaccessible address
          Wym_EINVAL      Unrecognized \fItzval\fP
          Wym_ERANGE      Argument overrange
          Wym_ENOMEM      Not enough memory

    \fItzval\fP may be used to set environment variable \fBTZ\fP temporarily
    for the underlying C function call

    Warning: Unrecognized \fItzval\fP may be taken as if it were "UTC"
.PP 
    [\fBRefer\fP] ::localtime_r
.\"--------------------------------------------
.PP
.BI "WyRet reset(const char* " "tzval" ",int " "year" ",int " "month" ",int " "mday" ",int " "hour" ",int " "min" ",int " "sec" ")"
.PP
.BI "WyRet reset(const WyStr& " "tzval" ",int " "year" ",int " "month" ",int " "mday" ",int " "hour" ",int " "min" ",int " "sec" ")"
.PP
    Reconstruct *this to the state as 
    WyDate(\fItzval\fP,\fIyear\fP,\fImonth\fP,\fImday\fP,\fIhour\fP,\fImin\fP,\fIsec\fP)
.PP
    [\fBRet\fP] Ok              Succeed
          Wym_EFAULT      Inaccessible address
          Wym_EINVAL      Unrecognized \fItzval\fP
          Wym_ERANGE      Argument overrange
          Wym_ENOMEM      Not enough memory

    \fItzval\fP may be used to set environment variable \fBTZ\fP temporarily
    for the underlying C function call

    Warning: Unrecognized \fItzval\fP may be taken as if it were "UTC"
.PP 
    [\fBRefer\fP] ::mktime
.\"--------------------------------------------
.PP
.BI "const WyStr& time_zone(void) const throw()"
.PP
    Get time zone of *this

    Note: None-const members invalidate the output reference implicitly 
.PP
    [\fBRet\fP] Time zone string reference of *this
.\"--------------------------------------------
.PP
.BI "int year(void) const throw()"
.PP
    Get the year of the date
.PP
    [\fBRet\fP] Year of the date (for example: 2003)
.\"--------------------------------------------
.PP
.BI "int month(void) const throw()"
.PP
    Get the month of the year
.PP
    [\fBRet\fP] Month of the year [1-12]
.\"--------------------------------------------
.PP
.BI "int mday(void) const throw()"
.PP
    Get the day of the month
.PP
    [\fBRet\fP] Day of the month [1-31]
.\"--------------------------------------------
.PP
.BI "int hour(void) const throw()"
.PP
    Get the hour in a day
.PP
    [\fBRet\fP] hour in a day [0-23]
.\"--------------------------------------------
.PP
.BI "int min(void) const throw()"
.PP
    Get the minute in an hour
.PP
    [\fBRet\fP] Minutes in an houry [0-59]
.PP
.\"--------------------------------------------
.BI "int sec(void) const throw()"
.PP
    Get the seconds of the minute
.PP
    [\fBRet\fP] Seconds of the minute [0-61]
.\"--------------------------------------------
.PP
.BI "int wday(void) const throw()"
.PP
    Get the day of the week
.PP
    [\fBRet\fP] Day of the week [0-6]
          0=Sunday,1=Monday...6=Saturday
.\"--------------------------------------------
.PP
.BI "int yday(void) const throw()"
.PP
    Get the day of the year
.PP
    [\fBRet\fP] Day of the year [0-365]
.\"--------------------------------------------
.PP
.BI "int isdst(void) const throw()"
.PP
    Get the daylight saving time
.PP
    [\fBRet\fP] Daylight saving time
.PP 
    [\fBRefer\fP] struct tm
.\"--------------------------------------------
.PP
.BI "WyTimeSpec utc_time(void) const throw()"
.PP
    Get the corresponding UTC time of the date
.PP
    [\fBRet\fP] WyTimeSpec of corresponding UTC time

    Note: Nano-second of the returned value is zero
.\"--------------------------------------------
.PP
.BI "WyRet set_utc(const WyTimeSpec& " "ucs" ")"
.PP
    Set UTC time to \fIucs\fP, date is recomputed.

     time_zone() = intact
      utc_time() = \fIucs\fP
          year() = computed
         month() = computed
          mday() = computed
          hour() = computed
           min() = computed
           sec() = computed
          wday() = computed
          yday() = computed
         isdst() = computed

    Note: Fraction of \fIucs\fP is ignored

    \fItzval\fP may be used to set environment variable \fBTZ\fP temporarily
    for the underlying C function call
.PP 
    [\fBRet\fP] Ok              Succeed
          Wym_ERANGE      Result overrange
          Wym_ENOMEM      Not enough memory
.PP 
    [\fBRefer\fP] ::localtime_r
.\"--------------------------------------------
.PP
.BI "WyRet set_date(int " "year" ",int " "month" ",int " "mday" ",int " "hour" ",int " "min" ",int " "sec" ")"
.PP
    Set date as the arguments indicate, UTC time is recomputed.

     time_zone() = intact
      utc_time() = computed
          year() = \fIyear\fP   [A.D. year]
         month() = \fImonth\fP  [1-12]
          mday() = \fImday\fP   [1-31]
          hour() = \fIhour\fP   [0-23]
           min() = \fImin\fP    [0-59]
           sec() = \fIsec\fP    [0-61]
          wday() = computed
          yday() = computed
         isdst() = computed

    \fItzval\fP may be used to set environment variable \fBTZ\fP temporarily
    for the underlying C function call
.PP
    [\fBRet\fP] Ok              Succeed
          Wym_EINVAL      Invalid argument
          Wym_ERANGE      Argument overrange
          Wym_ENOMEM      Not enough memory
.PP 
    [\fBRefer\fP] ::mktime
.\"--------------------------------------------
.PP
.BI "WyRet add(const WyTimeSpec& " "tm" ")"
.PP
    Add time of *this by \fItm\fP

    Note: Fraction of \fItm\fP is ignored (reguarded as 0)
.PP 
    [\fBRet\fP] Ok              Succeed
          Wym_ERANGE      Result overrange
          Wym_ENOMEM      Not enough memory
.PP 
    [\fBRefer\fP] ::localtime_r
.\"--------------------------------------------
.PP
.BI "const WyDate& operator =(const WyDate& " "date" ") throw(Reply)"
.PP
    Assign *this to the state as WyDate(\fIdate\fP)
.PP
    [\fBThrow\fP] Reply
            Wym_ENOMEM      Not enough memory
.PP 
    [\fBRet\fP] Const reference of *this
.\"--------------------------------------------
.PP
.BI "const WyDate& operator +=(const WyTimeSpec& " "tm" ")"
.PP
    Add time of *this by \fItm\fP

    Note: Fraction of \fItm\fP is ignored (reguarded as 0)
.PP
    [\fBThrow\fP] Reply
            Wym_ERANGE      Result not representable
            Wym_ENOMEM      Not enough memory
.PP 
    [\fBRet\fP] Const reference of *this
.PP 
    [\fBRefer\fP] ::localtime_r
.\"--------------------------------------------
.PP 
.BI "bool operator ==(const WyDate& " "date" ") const throw()"
.PP
.BI "bool operator !=(const WyDate& " "date" ") const throw()"
.PP
    Test equivalence of *this with \fIdate\fP

    this->operator==(\fIdate\fP) yields true iff for all other
    const members \fBf\fP, this->\fBf\fP()==\fIdate\fP.\fBf\fP()
.PP 
    [\fBRet\fP] true= relation holds
         false= otherwise
.\"--------------------------------------------
.SH "AUXILIARY FUNCTIONS"
.PP
.BI "WyDate operator +(const WyDate& date,const WyTimeSpec& " "time" ")"
.PP
.BI "WyDate operator +(const WyTimeSpec& time,const WyDate& " "date" ")"
.PP
    Add time \fItime\fP to the date \fPdate\fP
.PP
    [\fBThrow\fP] Reply
            Wym_ERANGE      Result not representable
            Wym_ENOMEM      Not enough memory
.PP 
    [\fBRet\fP] WyDate of the result (\fIdate\fP+\fItime\fP, or \fItime\fP+\fIdate\fP)
.PP 
    [\fBRefer\fP] ::localtime_r
.\"--------------------------------------------
.SH "SEE ALSO"
.BR wy
.BR wystr
.BR wytimespec
.BR wyfilestat
.BR wymutex
.BR wylock
.BR wycond
.BR wy_thread
.SH NOTE
Project is in development, http://sourceforge.net/projects/libwx