Package: Util.Calendars.Western

Dependencies

with Ada.Calendar;

with Util.Calendar.IO;
with Util.Times;

Description

This piece of software is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. This software is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License with this distribution, see file "GPL.txt". If not, write to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

As a special exception from the GPL, if other files instantiate generics from this unit, or you link this unit with other files to produce an executable, this unit does not by itself cause the resulting executable to be covered by the GPL. This exception does not however invalidate any other reasons why the executable file might be covered by the GPL.

Version: 1.1

Author:: Thomas Wolf (TW) <twolf AT acm DOT org>

Purpose:: Root package for western (christian) calendars.

Tasking Semantics: Neither task- nor abortion-safe.

Storage Semantics: No dynamic storage allocation.

Header

package Util.Calendars.Western is

Exceptions

Date_Error renames Util.Calendars.Date_Error

Renaming for convenience. See the comments in the parent package for explanations about when Date_Error is raised.

Type Summary

`Calendar` derived from `Calendar`
Overridden Operations:	`Image`, `Year`
New Operations:	`Add_Months`, `Date`, `Day`, `Day_In_Year`, `Day_Of_Week`, `Easter`, `Image`, `Is_Leap_Year`, `Is_Leap_Year`, `Julian_Day`, `Month`, `Split`, `Split`, `Sub_Months`, `Time_Of`, `Time_Of`

Constants and Named Numbers

DMY : constant Util.Calendar.IO.Date_Format := Util.Calendar.IO.DMY;

Fri : constant Week_Day := Util.Calendar.Fri;

MDY : constant Util.Calendar.IO.Date_Format := Util.Calendar.IO.MDY;

Mon : constant Week_Day := Util.Calendar.Mon;

Sat : constant Week_Day := Util.Calendar.Sat;

Sun : constant Week_Day := Util.Calendar.Sun;

Thu : constant Week_Day := Util.Calendar.Thu;

Tue : constant Week_Day := Util.Calendar.Tue;

Wed : constant Week_Day := Util.Calendar.Wed;

YMD : constant Util.Calendar.IO.Date_Format := Util.Calendar.IO.YMD;

Other Items:

type Calendar is abstract new Util.Calendars.Calendar with null record;

The three most important routines here are Julian_Day, Date, and Image. All the non-abstract primitive operations of this type re-dispatch to either Julian_Day or Date to convert a Time value to years, months, and days.

subtype Year_Number  is Util.Calendars.Year_Number;

subtype Month_Number is Ada.Calendar.Month_Number;

subtype Day_Number   is Ada.Calendar.Day_Number;

function Year
  (Base : in Calendar;
   Date : in Util.Times.Time)
  return Year_Number;

function Month
  (Base : in Calendar;
   Date : in Util.Times.Time)
  return Month_Number;

function Day
  (Base : in Calendar;
   Date : in Util.Times.Time)
  return Day_Number;

procedure Split
  (Base    : in     Calendar;
   Date    : in     Util.Times.Time;
   Year    :    out Year_Number;
   Month   :    out Month_Number;
   Day     :    out Day_Number);

procedure Split
  (Base    : in     Calendar;
   Instant : in     Util.Times.Time;
   Year    :    out Year_Number;
   Month   :    out Month_Number;
   Day     :    out Day_Number;
   Seconds :    out Util.Times.Day_Duration);

function Time_Of
  (Base    : in Calendar;
   Year    : in Year_Number;
   Month   : in Month_Number;
   Day     : in Day_Number;
   Seconds : in Util.Times.Day_Duration := 0.0)
  return Util.Times.Time;

function Is_Leap_Year
  (Base : in Calendar;
   Date : in Util.Times.Time)
  return Boolean;

Redispatches to the abstract Is_Leap_Year operation.

function Is_Leap_Year
  (Base : in Calendar;
   Year : in Year_Number)
  return Boolean
  is abstract;

Conversion routines.

function Julian_Day
  (Base  : in Calendar;
   Year  : in Year_Number;
   Month : in Month_Number;
   Day   : in Day_Number)
  return Util.Times.Julian_Day_Number
  is abstract;

procedure Date
  (Base       : in     Calendar;
   Julian_Day : in     Util.Times.Julian_Day_Number;
   Year       :    out Year_Number;
   Month      :    out Month_Number;
   Day        :    out Day_Number)
  is abstract;

Operations

function Add_Months
  (Base   : in Calendar;
   Date   : in Util.Times.Time;
   Months : in Natural)
  return Util.Times.Time;

function Sub_Months
  (Base   : in Calendar;
   Date   : in Util.Times.Time;
   Months : in Natural)
  return Util.Times.Time;

subtype Day_Count is Natural range 1 .. 366;

A system in which days are counted. January 1st is 1.

function Day_In_Year
  (Base : in Calendar;
   Date : in Util.Times.Time)
  return Day_Count;

function Time_Of
  (Base    : in Calendar;
   Year    : in Year_Number;
   Day     : in Day_Count;
   Seconds : in Util.Times.Day_Duration := 0.0)
  return Util.Times.Time;

Week days

subtype Week_Day is Util.Calendar.Weekday;

function Day_Of_Week
  (Base : in Calendar;
   Date : in Util.Times.Time)
  return Week_Day
  is abstract;

Easter date

function Easter
  (Base : in Calendar;
   Year : in Year_Number)
  return Util.Times.Time
  is abstract;

Returns midnight on easter in the given year. May raise Date_Error if either: the year is negative (there was no easter in B.C...) or the year is beyond the range of the calendar (e.g., in Gregorian calendars, you can compute easter dates only from 1583 on).

function Image
  (Base      : in Calendar;
   Date      : in Util.Times.Time;
   Format    : in Util.Calendar.IO.Date_Format;
   Separator : in String  := "";
   Padding   : in Boolean := True;
   BC_AD     : in Boolean := False)
  return String;

Individual date components are separated by the given Separator.

If Padding is true, day and month numbers smaller than 10 have a leading zero.

If BC_AD is False, dates before 1-JAN-1 are written with a negative year, if it is true, the year always is positive, but BC dates have " BC" appended. Note that if BC_AD is false, you get year 0 for 1 BC, -1 for 2 BC, and so on. (There is no year 0, the year before 1 AD is 1 BC!)

If Format is YMD and BC_AD is True, BC dates are formed by prepending "BC" & Separator.

Examples: (assuming Padding = True and BC_AD = False)

Format Separator 03-OCT-2001 yields:

English style: MDY "/" "10/03/2001"

German style: DMY ". " "03. 10. 2001"

ISO 8601: YMD "-" "2001-10-03"

Timestamp: YMD "" "20011003"

Note that there are no image functions with textual representations for the month and/or the day of the week. This is intentional, for month and weekday names depend highly on the locale, and it was felt that such things are better dealt with outside such a general package. If such functionality were included, where should the limit be? Should we support Wide_Character strings or not? Should we support different separators? What about ordinals? (As in the date "Jun 2nd, 2001".)

function Image
  (Base : in Calendar;
   Date : in Util.Times.Time)
  return String;

Override the inherited, abstract operation: returns the ISO 8601 image, i.e. "YYYY-MM-DD". Same as Image (Base, Date, YMD, "-");

end Util.Calendars.Western;