Package: Util.Times

Dependencies

with Ada.Calendar;

with Util.Calendar;

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:: A complete replacement for Ada.Calendar based on Chronological Julian Days.
Chronological Julian Day differ from astronomical Julian Days by an offset of 12 hours (chronological JDs start at midnight, astronomical JDs start at noon).

Tasking Semantics: Neither task- nor abortion-safe.

Storage Semantics: No dynamic storage allocation.

Header

package Util.Times is

Known child units

Util.Times.IO (package)

Exceptions

Time_Error renames Ada.Calendar.Time_Error

Raised by To_Time if the result cannot be represented as a value of Ada.Calendar.Time.

Type Summary

`Time`
Primitive Operations:	`"+"`, `"+"`, `"+"`, `"+"`, `"+"`, `"+"`, `"-"`, `"-"`, `"-"`, `"-"`, `"-"`, `"<"`, `"<="`, `">"`, `">="`, `Days_Between`, `Julian_Day`, `Now`, `Secs`, `Split`, `Time_Of`, `To_Time`, `To_Time`, `UTC`
`Time_Difference`
Primitive Operations:	`""`, `""`, `""`, `""`, `"+"`, `"+"`, `"+"`, `"+"`, `"-"`, `"-"`, `"-"`, `"-"`, `"/"`, `"/"`, `"/"`, `"/"`, `"<"`, `"<="`, `">"`, `">="`, `From_Float`, `Split`, `Split`, `To_Duration`, `To_Float`

Constants and Named Numbers

Zero : constant Time_Difference;

Unary operators

Other Items:

type Time is private;

A time type not limited to the narrow range of Ada.Calendar.Time. Based on Chronological Julian Days, this should work for any date in range -4712-01-01 (i.e, Jan 1st, 4713 BC) to 1465102-10-18 (i.e., Oct 18, 1_465_102 AD).

subtype Julian_Day_Number is Integer range 0 .. 536838867;

We just limit the range to avoid constraint errors in the calendar packages when we try to convert a Julian_Day_Number into Day, Month, and Year. Anyway, this should be sufficient!

subtype Day_Duration      is Ada.Calendar.Day_Duration;

Conversion routines.

function To_Time
  (Instant : in Ada.Calendar.Time)
  return Time;

Converts an Ada.Calendar.Time to a Time value.

function To_Time
  (Instant : in Time)
  return Ada.Calendar.Time;

Converts a Time to an Ada.Calendar.Time value.

Raises Time_Error if the result cannot be represented in Ada.Calendar.Time.

function Now
  return Time;

Returns the current local time.

function UTC
  return Time;

Returns the current time, expressed as Coordinated Universal Time (UTC). Raises Time_Error if UTC is not available.

function Is_DST
  return Boolean;

Returns True if Now returns "daylight savings times"; False otherwise. Raises Time_Error if this information cannot be determined.

function Secs
  (Instant : in Time)
  return Day_Duration;

Returns the number of seconds (and fractions thereof) since midnight on that day.

function Julian_Day
  (Instant : in Time)
  return Julian_Day_Number;

procedure Split
  (Instant    : in     Time;
   Julian_Day :    out Julian_Day_Number;
   Seconds    :    out Day_Duration);

subtype Hours    is Util.Calendar.Hours_Type;

subtype Minutes  is Util.Calendar.Minutes_Type;

subtype Seconds  is Util.Calendar.Seconds_Type;

subtype Fraction is Day_Duration range 0.0 .. 1.0;

procedure Split
  (Secs : in     Day_Duration;
   Hrs  :    out Hours;
   Min  :    out Minutes;
   Sec  :    out Seconds);

procedure Split
  (Secs : in     Day_Duration;
   Hrs  :    out Hours;
   Min  :    out Minutes;
   Sec  :    out Seconds;
   Frac :    out Fraction);

Constructors

function Time_Of
  (Julian_Day : in Julian_Day_Number;
   Seconds    : in Day_Duration := 0.0)
  return Time;

function To_Duration
  (Hrs  : in Hours;
   Min  : in Minutes;
   Sec  : in Seconds;
   Frac : in Fraction := 0.0)
  return Day_Duration;

Operations on Time values.

function "+"
  (Date : in Time;
   Days : in Julian_Day_Number)
  return Time;

function "+"
  (Days : in Julian_Day_Number;
   Date : in Time)
  return Time;

function "-"
  (Date : in Time;
   Days : in Julian_Day_Number)
  return Time;

function Days_Between
  (L, R : in Time)
  return Julian_Day_Number;

Disregards the time-of-day. I.e. (02-MAR-2002 00:00:01) - (01-MAR-2002 23:59:59) = 1, even if the two instants are only two seconds apart!

function "-"
  (L, R : in Time)
  return Julian_Day_Number
  renames Days_Between;

function "+"
  (Instant : in Time;
   Offset  : in Day_Duration)
  return Time;

function "+"
  (Offset  : in Day_Duration;
   Instant : in Time)
  return Time;

function "-"
  (Instant : in Time;
   Offset  : in Day_Duration)
  return Time;

function "<"
  (L, R : in Time)
  return Boolean;

function "<="
  (L, R : in Time)
  return Boolean;

function ">"
  (L, R : in Time)
  return Boolean;

function ">="
  (L, R : in Time)
  return Boolean;

Time differences.

type Time_Difference is private;

Time differences can be negative!

function "+"
  (Value : in Time_Difference)
  return Time_Difference;

function "-"
  (Value : in Time_Difference)
  return Time_Difference;

Binary operators

function "+"
  (Left, Right : in Time_Difference)
  return Time_Difference;

function "-"
  (Left, Right : in Time_Difference)
  return Time_Difference;

function "*"
  (Left  : in Time_Difference;
   Right : in Integer)
  return Time_Difference;

function "*"
  (Left  : in Integer;
   Right : in Time_Difference)
  return Time_Difference;

function "*"
  (Left  : in Time_Difference;
   Right : in Float)
  return Time_Difference;

function "*"
  (Left  : in Float;
   Right : in Time_Difference)
  return Time_Difference;

function "/"
  (Left, Right : in Time_Difference)
  return Integer;

function "/"
  (Left, Right : in Time_Difference)
  return Float;

function "/"
  (Left  : in Time_Difference;
   Right : in Integer)
  return Time_Difference;

function "/"
  (Left  : in Time_Difference;
   Right : in Float)
  return Time_Difference;

Relational operators

function "<"
  (Left, Right : in Time_Difference)
  return Boolean;

function "<="
  (Left, Right : in Time_Difference)
  return Boolean;

function ">"
  (Left, Right : in Time_Difference)
  return Boolean;

function ">="
  (Left, Right : in Time_Difference)
  return Boolean;

Float conversions

function To_Float
  (T : in Time_Difference)
  return Float;

function From_Float
  (F : in Float)
  return Time_Difference;

Constructor

function To_Duration
  (Days    : in Julian_Day_Number;
   Seconds : in Day_Duration := 0.0)
  return Time_Difference;

Accessors

procedure Split
  (Secs : in     Time_Difference;
   Neg  :    out Boolean;
   Days :    out Julian_Day_Number;
   Hrs  :    out Hours;
   Min  :    out Minutes;
   Sec  :    out Seconds);

procedure Split
  (Secs : in     Time_Difference;
   Neg  :    out Boolean;
   Days :    out Julian_Day_Number;
   Hrs  :    out Hours;
   Min  :    out Minutes;
   Sec  :    out Seconds;
   Frac :    out Fraction);

Operations on 'Time' values

function "-"
  (L, R : in Time)
  return Time_Difference;

function "+"
  (Instant : in Time;
   Offset  : in Time_Difference)
  return Time;

function "+"
  (Offset  : in Time_Difference;
   Instant : in Time)
  return Time;

function "-"
  (Instant : in Time;
   Offset  : in Time_Difference)
  return Time;

private

   --  Implementation-defined ...

end Util.Times;