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 WeekDay()">
 131 Calculate the day of the week, where 1 is Monday and 7 is Sunday.
 132 If the date is not a proper calendar date, return 0.
 133 </item>
 134 <item tag="string DayName()">
 135 </item>
 136 <item tag="string MonthName()">
 137 </item>
 138 <item tag="string WeekNumber()">
 139 Calculate the number of the week within the year.
 140 </item>
 141 </description>
 142 </section>
 143
 144 <section>
 145
 146 <heading>Arithmetic</heading>
 147 <description>
 148 <item tag="date operator+(date &amp;d1, date &amp;d2)">
 149 Add a number of days, months and years to a date.
 150 This is most usefull if one of the dates is a proper calendar date
 151 and the other is not.
 152 </item>
 153 <item tag="date operator+=(date &amp;d)">
 154 </item>
 155 <item tag="date operator+(long l, date &amp;d)">
 156 Add a number of days to a date.
 157 </item>
 158 <item tag="date operator+(date &amp;d, long l)">
 159 </item>
 160 <item tag="date operator+=(long l)">
 161 Add l days to the date.
 162 </item>
 163 <item tag="long operator-(date &amp;d1, date &amp;d2)">
 164 Calculate the number of days from d1 to d2.
 165 </item>
 166 <item tag="date operator-(date &amp;d1, date &amp;d2)">
 167 </item>
 168 <item tag="date operator-=(date &amp;d)">
 169 Subtract a number of days, months and years from the left-hand date.
 170 </item>
 171 <item tag="date operator-=(long l)">
 172 Subtract l days.
 173 </item>
 174 <item tag="date operator++()">
 175 </item>
 176 <item tag="date operator--()">
 177 </item>
 178 </description>
 179 </section>
 180
 181 <section>
 182 <heading>Stream I/O</heading>
 183 </section>
 184
 185 <section>
 186 <heading>SEE ALSO</heading>
 187 <para>
 188 <A HREF="hour.html">hour</A><A HREF="UTC.html"> UTC</A>
 189 </para>
 190 </section>
 191 </chapter>