gcc/ada/a-calfor.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT RUN-TIME COMPONENTS                         --
   4 --                                                                          --
   5 --              A D A . C A L E N D A R . F O R M A T T I N G               --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --         Copyright (C) 2005-2006, Free Software Foundation, Inc.          --
  10 --                                                                          --
  11 -- This specification is derived from the Ada Reference Manual for use with --
  12 -- GNAT. The copyright notice above, and the license provisions that follow --
  13 -- apply solely to the  contents of the part following the private keyword. --
  14 --                                                                          --
  15 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  16 -- terms of the  GNU General Public License as published  by the Free Soft- --
  17 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  18 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  19 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  20 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  21 -- for  more details.  You should have  received  a copy of the GNU General --
  22 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  23 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  24 -- MA 02111-1307, USA.                                                      --
  25 --                                                                          --
  26 -- As a special exception,  if other files  instantiate  generics from this --
  27 -- unit, or you link  this unit with other files  to produce an executable, --
  28 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  29 -- covered  by the  GNU  General  Public  License.  This exception does not --
  30 -- however invalidate  any other reasons why  the executable file  might be --
  31 -- covered by the  GNU Public License.                                      --
  32 --                                                                          --
  33 -- GNAT was originally developed  by the GNAT team at  New York University. --
  34 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  35 --                                                                          --
  36 ------------------------------------------------------------------------------
  37
  38 --  This package provides additional components to Time, as well as new
  39 --  Time_Of and Split routines which handle time zones and leap seconds.
  40 --  This package is defined in the Ada 2005 RM (9.6.1).
  41
  42 with Ada.Calendar.Time_Zones;
  43
  44 package Ada.Calendar.Formatting is
  45
  46    --  Day of the week
  47
  48    type Day_Name is
  49      (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday);
  50
  51    function Day_Of_Week (Date : Time) return Day_Name;
  52
  53    --  Hours:Minutes:Seconds access
  54
  55    subtype Hour_Number     is Natural range 0 .. 23;
  56    subtype Minute_Number   is Natural range 0 .. 59;
  57    subtype Second_Number   is Natural range 0 .. 59;
  58    subtype Second_Duration is Day_Duration range 0.0 .. 1.0;
  59
  60    function Year
  61      (Date      : Time;
  62       Time_Zone : Time_Zones.Time_Offset := 0) return Year_Number;
  63
  64    function Month
  65      (Date      : Time;
  66       Time_Zone : Time_Zones.Time_Offset := 0) return Month_Number;
  67
  68    function Day
  69      (Date      : Time;
  70       Time_Zone : Time_Zones.Time_Offset := 0) return Day_Number;
  71
  72    function Hour
  73      (Date      : Time;
  74       Time_Zone : Time_Zones.Time_Offset := 0) return Hour_Number;
  75
  76    function Minute
  77      (Date      : Time;
  78       Time_Zone : Time_Zones.Time_Offset := 0) return Minute_Number;
  79
  80    function Second
  81      (Date : Time)                             return Second_Number;
  82
  83    function Sub_Second
  84      (Date : Time)                             return Second_Duration;
  85
  86    function Seconds_Of
  87      (Hour       : Hour_Number;
  88       Minute     : Minute_Number;
  89       Second     : Second_Number := 0;
  90       Sub_Second : Second_Duration := 0.0) return Day_Duration;
  91    --  Returns a Day_Duration value for the combination of the given Hour,
  92    --  Minute, Second, and Sub_Second. This value can be used in Ada.Calendar.
  93    --  Time_Of as well as the argument to Calendar."+" and Calendar."–". If
  94    --  Seconds_Of is called with a Sub_Second value of 1.0, the value returned
  95    --  is equal to the value of Seconds_Of for the next second with a Sub_
  96    --  Second value of 0.0.
  97
  98    procedure Split
  99      (Seconds    : Day_Duration;
 100       Hour       : out Hour_Number;
 101       Minute     : out Minute_Number;
 102       Second     : out Second_Number;
 103       Sub_Second : out Second_Duration);
 104    --  Splits Seconds into Hour, Minute, Second and Sub_Second in such a way
 105    --  that the resulting values all belong to their respective subtypes. The
 106    --  value returned in the Sub_Second parameter is always less than 1.0.
 107
 108    procedure Split
 109      (Date       : Time;
 110       Year       : out Year_Number;
 111       Month      : out Month_Number;
 112       Day        : out Day_Number;
 113       Hour       : out Hour_Number;
 114       Minute     : out Minute_Number;
 115       Second     : out Second_Number;
 116       Sub_Second : out Second_Duration;
 117       Time_Zone  : Time_Zones.Time_Offset := 0);
 118    --  Splits Date into its constituent parts (Year, Month, Day, Hour, Minute,
 119    --  Second, Sub_Second), relative to the specified time zone offset. The
 120    --  value returned in the Sub_Second parameter is always less than 1.0.
 121
 122    function Time_Of
 123      (Year        : Year_Number;
 124       Month       : Month_Number;
 125       Day         : Day_Number;
 126       Hour        : Hour_Number;
 127       Minute      : Minute_Number;
 128       Second      : Second_Number;
 129       Sub_Second  : Second_Duration := 0.0;
 130       Leap_Second : Boolean := False;
 131       Time_Zone   : Time_Zones.Time_Offset := 0) return Time;
 132    --  If Leap_Second is False, returns a Time built from the date and time
 133    --  values, relative to the specified time zone offset. If Leap_Second is
 134    --  True, returns the Time that represents the time within the leap second
 135    --  that is one second later than the time specified by the parameters.
 136    --  Time_Error is raised if the parameters do not form a proper date or
 137    --  time. If Time_Of is called with a Sub_Second value of 1.0, the value
 138    --  returned is equal to the value of Time_Of for the next second with a
 139    --  Sub_Second value of 0.0.
 140
 141    function Time_Of
 142      (Year        : Year_Number;
 143       Month       : Month_Number;
 144       Day         : Day_Number;
 145       Seconds     : Day_Duration := 0.0;
 146       Leap_Second : Boolean := False;
 147       Time_Zone   : Time_Zones.Time_Offset := 0) return Time;
 148    --  If Leap_Second is False, returns a Time built from the date and time
 149    --  values, relative to the specified time zone offset. If Leap_Second is
 150    --  True, returns the Time that represents the time within the leap second
 151    --  that is one second later than the time specified by the parameters.
 152    --  Time_Error is raised if the parameters do not form a proper date or
 153    --  time. If Time_Of is called with a Seconds value of 86_400.0, the value
 154    --  returned is equal to the value of Time_Of for the next day with a
 155    --  Seconds value of 0.0.
 156
 157    procedure Split
 158      (Date        : Time;
 159       Year        : out Year_Number;
 160       Month       : out Month_Number;
 161       Day         : out Day_Number;
 162       Hour        : out Hour_Number;
 163       Minute      : out Minute_Number;
 164       Second      : out Second_Number;
 165       Sub_Second  : out Second_Duration;
 166       Leap_Second : out Boolean;
 167       Time_Zone   : Time_Zones.Time_Offset := 0);
 168    --  If Date does not represent a time within a leap second, splits Date
 169    --  into its constituent parts (Year, Month, Day, Hour, Minute, Second,
 170    --  Sub_Second), relative to the specified time zone offset, and sets
 171    --  Leap_Second to False. If Date represents a time within a leap second,
 172    --  set the constituent parts to values corresponding to a time one second
 173    --  earlier than that given by Date, relative to the specified time zone
 174    --  offset, and sets Leap_Seconds to True. The value returned in the
 175    --  Sub_Second parameter is always less than 1.0.
 176
 177    procedure Split
 178      (Date        : Time;
 179       Year        : out Year_Number;
 180       Month       : out Month_Number;
 181       Day         : out Day_Number;
 182       Seconds     : out Day_Duration;
 183       Leap_Second : out Boolean;
 184       Time_Zone   : Time_Zones.Time_Offset := 0);
 185    --  If Date does not represent a time within a leap second, splits Date
 186    --  into its constituent parts (Year, Month, Day, Seconds), relative to the
 187    --  specified time zone offset, and sets Leap_Second to False. If Date
 188    --  represents a time within a leap second, set the constituent parts to
 189    --  values corresponding to a time one second earlier than that given by
 190    --  Date, relative to the specified time zone offset, and sets Leap_Seconds
 191    --  to True. The value returned in the Seconds parameter is always less
 192    --  than 86_400.0.
 193
 194    --  Simple image and value
 195
 196    function Image
 197      (Date                  : Time;
 198       Include_Time_Fraction : Boolean := False;
 199       Time_Zone             : Time_Zones.Time_Offset := 0) return String;
 200    --  Returns a string form of the Date relative to the given Time_Zone. The
 201    --  format is "Year-Month-Day Hour:Minute:Second", where the Year is a
 202    --  4-digit value, and all others are 2-digit values, of the functions
 203    --  defined in Ada.Calendar and Ada.Calendar.Formatting, including a
 204    --  leading zero, if needed. The separators between the values are a minus,
 205    --  another minus, a colon, and a single space between the Day and Hour. If
 206    --  Include_Time_Fraction is True, the integer part of Sub_Seconds*100 is
 207    --  suffixed to the string as a point followed by a 2-digit value.
 208
 209    function Value
 210      (Date       : String;
 211       Time_Zone  : Time_Zones.Time_Offset := 0) return Time;
 212    --  Returns a Time value for the image given as Date, relative to the given
 213    --  time zone. Constraint_Error is raised if the string is not formatted as
 214    --  described for Image, or the function cannot interpret the given string
 215    --  as a Time value.
 216
 217    function Image
 218      (Elapsed_Time          : Duration;
 219       Include_Time_Fraction : Boolean := False) return String;
 220    --  Returns a string form of the Elapsed_Time. The format is "Hour:Minute:
 221    --  Second", where all values are 2-digit values, including a leading zero,
 222    --  if needed. The separators between the values are colons. If Include_
 223    --  Time_Fraction is True, the integer part of Sub_Seconds*100 is suffixed
 224    --  to the string as a point followed by a 2-digit value. If Elapsed_Time <
 225    --  0.0, the result is Image (abs Elapsed_Time, Include_Time_Fraction)
 226    --  prefixed with a minus sign. If abs Elapsed_Time represents 100 hours or
 227    --  more, the result is implementation-defined.
 228
 229    function Value (Elapsed_Time : String) return Duration;
 230    --  Returns a Duration value for the image given as Elapsed_Time.
 231    --  Constraint_Error is raised if the string is not formatted as described
 232    --  for Image, or the function cannot interpret the given string as a
 233    --  Duration value.
 234
 235 end Ada.Calendar.Formatting;