doc/date.xml

   1 <?xml version="1.0"?>
   2 <chapter>
   3 <heading>date - Date class</heading>
   4 <pre>
   5 #include &lt;date.h&gt;
   6
   7 date d;
   8 </pre>
   9 <para>
  10 The <emph>date</emph> class encapsulates the concept of a date, represented by
  11 days, months and years. It holds
  12 a day and a month, both between 0 and 255, and a year ranging from -32768 to
  13 +32767. Although full-range dates can be usefull in calulations, a real date
  14 should have a day between 1 and 31 inclusive, and a month between 1 and 12.
  15 Only such dates can be used as proper calender dates.
  16 A different kind of date may be used as a relative date to perform calculations.
  17 For example, to add 2 years, 3 months and 6 days to a date, a date like (6, 3, 2) can be created.
  18 All calculations with dates are based on the Julian calendar.
  19 </para>
  20 <para>
  21 Parsing text into a date object is a challenging task.
  22 Partly because there are many ways to write dates but also because some
  23 ways to write a date are ambiguous.
  24 For example, the date 8-2-12 could mean August 2nd 2012, 12th of February 2008
  25 or 8th of February 2012.
  26 These are some ways to write February 8th 2012 that are supported by the parser:
  27 <itemize>
  28 <item>20120208</item>
  29 <item>2012-02-08</item>
  30 <item>2012 02 08</item>
  31 <item>08-02-2012</item>
  32 <item>02/08/2012</item>
  33 <item>Feb 8 2012</item>
  34 <item>2012 Feb 8</item>
  35 <item>8 FEB 2012</item>
  36 <item>2012 8 feb</item>
  37 <item>8 February 2012</item>
  38 </itemize>
  39
  40 </para>
  41
  42 <section>
  43 <heading>Construction</heading>
  44 <description>
  45 <item tag="date()">
  46 The default constructor sets all elements (day, month and year) to 0.
  47 </item>
  48 <item tag="date(unsigned day, unsigned month=0, short year=0)">
  49 Constructs a date object with the specified year, month and day.
  50 For this date object to be a proper calendar date, the month must be between
  51 1 and 12 an the day myst be between 1 and the number of days in that month.
  52 </item>
  53 <item tag="date(unsigned day, string month, short year)">
  54 </item>
  55 <item tag="date(String s)">
  56 </item>
  57 </description>
  58 </section>
  59
  60 <section>
  61 <heading>Assignment</heading>
  62 <description>
  63 <item tag="operator=(date &amp;d)">
  64 </item>
  65 <item tag="operator=(String &amp;s)">
  66 Parse string s and extract a day, month and year if the string contains an actual date.
  67 </item>
  68 </description>
  69 </section>
  70
  71 <section>
  72
  73 <heading>Conversion</heading>
  74 <description>
  75 <item tag="long()">
  76 Converts to the Julian date number. This is the number of days since the
  77 base date of the Julian calendar.
  78 </item>
  79 <item tag="string()">
  80 Converts a date to an ASCII format.
  81 </item>
  82 </description>
  83 </section>
  84
  85 <section>
  86 <heading>Relational operations</heading>
  87 <para>
  88 The relational operators are defined with obvious meanings:
  89 </para>
  90 <description>
  91 <item tag="operator==(date d)">
  92 </item>
  93 <item tag="operator!=(date d)">
  94 </item>
  95 <item tag="operator&lt;(date d)">
  96 </item>
  97 <item tag="operator&lt;=(date d)">
  98 </item>
  99 <item tag="operator&gt;(date d)">
 100 </item>
 101 <item tag="operator&gt;=(date d)">
 102 </item>
 103 </description>
 104 </section>
 105
 106 <section>
 107 <heading>Attributes</heading>
 108 <description>
 109 <item tag="unsigned Day()">
 110 </item>
 111 <item tag="unsigned Month()">
 112 </item>
 113 <item tag="short Year()">
 114 </item>
 115 </description>
 116 </section>
 117
 118 <section>
 119
 120 <heading>Operations</heading>
 121 <description>
 122 <item tag="int Leap()">
 123 Returns TRUE if this year is a leapyear. If this year is not a leapyear,
 124 <code>leap()</code> returns 0.
 125 </item>
 126 <item tag="unsigned DaysInMonth()">
 127 Returns the number of days in this month, or zero if the month is not
 128 between 1 and 12.
 129 </item>
 130 <item tag="unsigned YearDay()">
 131 Calculate the day of the year, starting from January 1st.
 132 For example, 1 means January 1st and the 22nd of February is 53.
 133 If the date is not a proper calendar date, return 0.
 134 </item>
 135 <item tag="unsigned WeekDay()">
 136 Calculate the day of the week, where 1 is Monday and 7 is Sunday.
 137 If the date is not a proper calendar date, return 0.
 138 </item>
 139 <item tag="string DayName()">
 140 </item>
 141 <item tag="string MonthName()">
 142 </item>
 143 <item tag="string WeekNumber()">
 144 Calculate the number of the week within the year.
 145 </item>
 146 </description>
 147 </section>
 148
 149 <section>
 150
 151 <heading>Arithmetic</heading>
 152 <description>
 153 <item tag="date operator+(date &amp;d1, date &amp;d2)">
 154 Add a number of days, months and years to a date.
 155 This is most usefull if one of the dates is a proper calendar date
 156 and the other is not.
 157 </item>
 158 <item tag="date operator+=(date &amp;d)">
 159 </item>
 160 <item tag="date operator+(long l, date &amp;d)">
 161 Add a number of days to a date.
 162 </item>
 163 <item tag="date operator+(date &amp;d, long l)">
 164 </item>
 165 <item tag="date operator+=(long l)">
 166 Add l days to the date.
 167 </item>
 168 <item tag="long operator-(date &amp;d1, date &amp;d2)">
 169 Calculate the number of days from d1 to d2.
 170 </item>
 171 <item tag="date operator-(date &amp;d1, date &amp;d2)">
 172 </item>
 173 <item tag="date operator-=(date &amp;d)">
 174 Subtract a number of days, months and years from the left-hand date.
 175 </item>
 176 <item tag="date operator-=(long l)">
 177 Subtract l days.
 178 </item>
 179 <item tag="date operator++()">
 180 </item>
 181 <item tag="date operator--()">
 182 </item>
 183 </description>
 184 </section>
 185
 186 <section>
 187 <heading>Stream I/O</heading>
 188 </section>
 189
 190 <section>
 191 <heading>SEE ALSO</heading>
 192 <para>
 193 <A HREF="hour.html">hour</A><A HREF="UTC.html"> UTC</A>
 194 </para>
 195 </section>
 196 </chapter>