lib/libcalendar/calendar.3

   1 .\" Copyright (c) 1997 Wolfgang Helbig
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/lib/libcalendar/calendar.3,v 1.6.2.5 2001/12/17 10:08:28 ru Exp $
  26 .\" $DragonFly: src/lib/libcalendar/calendar.3,v 1.3 2006/05/26 19:39:38 swildner Exp $
  27 .\"
  28 .Dd November 29, 1997
  29 .Dt CALENDAR 3
  30 .Os
  31 .Sh NAME
  32 .Nm easterg ,
  33 .Nm easterog ,
  34 .Nm easteroj ,
  35 .Nm gdate ,
  36 .Nm jdate ,
  37 .Nm ndaysg ,
  38 .Nm ndaysj ,
  39 .Nm week ,
  40 .Nm weekday
  41 .Nd Calendar arithmetic for the Christian era
  42 .Sh LIBRARY
  43 .Lb libcalendar
  44 .Sh SYNOPSIS
  45 .In calendar.h
  46 .Ft struct date *
  47 .Fn easterg "int year" "struct date *dt"
  48 .Ft struct date *
  49 .Fn easterog "int year" "struct date *dt"
  50 .Ft struct date *
  51 .Fn easteroj "int year" "struct date *dt"
  52 .Ft struct date *
  53 .Fn gdate "int nd" "struct date *dt"
  54 .Ft struct date *
  55 .Fn jdate "int nd" "struct date *dt"
  56 .Ft int
  57 .Fn ndaysg "struct date *dt"
  58 .Ft int
  59 .Fn ndaysj "struct date *dt"
  60 .Ft int
  61 .Fn week "int nd" "int *year"
  62 .Ft int
  63 .Fn weekday "int nd"
  64 .Sh DESCRIPTION
  65 These functions provide calendar arithmetic for a large range of years,
  66 starting at March 1st, year zero (i. e. 1 B.C.) and ending way beyond
  67 year 100000.
  68 .Pp
  69 Programs should be linked with
  70 .Fl lcalendar .
  71 .Pp
  72 The functions
  73 .Fn easterg ,
  74 .Fn easterog
  75 and
  76 .Fn easteroj
  77 store the date of Easter Sunday into the structure pointed at by
  78 .Fa dt
  79 and return a pointer to this structure.
  80 The function
  81 .Fn easterg
  82 assumes Gregorian Calendar (adopted by most western churches after 1582) and
  83 the functions
  84 .Fn easterog
  85 and
  86 .Fn easteroj
  87 compute the date of Easter Sunday according to the orthodox rules
  88 (Western churches before 1582, Greek and Russian Orthodox Church
  89 until today).
  90 The result returned by
  91 .Fn easterog
  92 is the date in Gregorian Calendar, whereas
  93 .Fn easteroj
  94 returns the date in Julian Calendar.
  95 .Pp
  96 The functions
  97 .Fn gdate ,
  98 .Fn jdate ,
  99 .Fn ndaysg
 100 and
 101 .Fn ndaysj
 102 provide conversions between the common "year, month, day" notation
 103 of a date and the "number of days" representation, which is better suited
 104 for calculations.
 105 The days are numbered from March 1st year 1 B.C., starting
 106 with zero, so the number of a day gives the number of days since March 1st,
 107 year 1 B.C. The conversions work for nonnegative day numbers only.
 108 .Pp
 109 The
 110 .Fn gdate
 111 and
 112 .Fn jdate
 113 functions
 114 store the date corresponding to the day number
 115 .Fa nd
 116 into the structure pointed at by
 117 .Fa dt
 118 and return a pointer to this structure.
 119 .Pp
 120 The
 121 .Fn ndaysg
 122 and
 123 .Fn ndaysj
 124 functions
 125 return the day number of the date pointed at by
 126 .Fa dt .
 127 .Pp
 128 The
 129 .Fn gdate
 130 and
 131 .Fn ndaysg
 132 functions
 133 assume Gregorian Calendar after October 4, 1582 and Julian Calendar before,
 134 whereas
 135 .Fn jdate
 136 and
 137 .Fn ndaysj
 138 assume Julian Calendar throughout.
 139 .Pp
 140 The two calendars differ by the definition of the leap year.
 141 The
 142 Julian Calendar says every year that is a multiple of four is a
 143 leap year.
 144 The Gregorian Calendar excludes years that are multiples of
 145 100 and not multiples of 400.
 146 This means the years 1700, 1800, 1900, 2100 are not leap years
 147 and the year 2000 is
 148 a leap year.
 149 The new rules were inaugurated on October 4, 1582 by deleting ten
 150 days following this date.
 151 Most catholic countries adopted the new
 152 calendar by the end of the 16th century, whereas others stayed with
 153 the Julian Calendar until the 20th century.
 154 The United Kingdom and
 155 their colonies switched on September 2, 1752. They already had to
 156 delete 11 days.
 157 .Pp
 158 The function
 159 .Fn week
 160 returns the number of the week which contains the day numbered
 161 .Fa nd .
 162 The argument
 163 .Fa *year
 164 is set with the year that contains (the greater part of) the week.
 165 The weeks are numbered per year starting with week 1, which is the
 166 first week in a year that includes more than three days of the year.
 167 Weeks start on Monday.
 168 This function is defined for Gregorian Calendar only.
 169 .Pp
 170 The function
 171 .Fn weekday
 172 returns the weekday (Mo = 0 .. Su = 6) of the day numbered
 173 .Fa nd .
 174 .Pp
 175 The structure
 176 .Fa date
 177 is defined in
 178 .In calendar.h .
 179 It contains these fields:
 180 .Bd -literal -offset indent
 181 int y;          /\(** year (0000 - ????) \(**/
 182 int m;          /\(** month (1 - 12) \(**/
 183 int d;          /\(** day of month (1 - 31) \(**/
 184 .Ed
 185 .Pp
 186 The year zero is written as "1 B.C." by historians and "0" by astronomers
 187 and in this library.
 188 .Sh SEE ALSO
 189 .Xr ncal 1 ,
 190 .Xr strftime 3
 191 .Sh STANDARDS
 192 The week number conforms to ISO 8601: 1988.
 193 .Sh HISTORY
 194 The
 195 .Nm calendar
 196 library first appeared in
 197 .Fx 3.0 .
 198 .Sh AUTHORS
 199 This manual page and the library was written by
 200 .An Wolfgang Helbig Aq helbig@FreeBSD.org .
 201 .Sh BUGS
 202 The library was coded with great care so there are no bugs left.