gcc/ada/libgnat/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-2018, Free Software Foundation, Inc.          --
  10 --                                                                          --
  11 -- This specification is derived from the Ada Reference Manual for use with --
  12 -- GNAT.  In accordance with the copyright of that document, you can freely --
  13 -- copy and modify this specification,  provided that if you redistribute a --
  14 -- modified version,  any changes that you have made are clearly indicated. --
  15 --                                                                          --
  16 ------------------------------------------------------------------------------
  17
  18 --  This package provides additional components to Time, as well as new
  19 --  Time_Of and Split routines which handle time zones and leap seconds.
  20 --  This package is defined in the Ada 2005 RM (9.6.1).
  21
  22 with Ada.Calendar.Time_Zones;
  23
  24 package Ada.Calendar.Formatting is
  25
  26    --  Day of the week
  27
  28    type Day_Name is
  29      (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday);
  30
  31    function Day_Of_Week (Date : Time) return Day_Name;
  32
  33    --  Hours:Minutes:Seconds access
  34
  35    subtype Hour_Number     is Natural range 0 .. 23;
  36    subtype Minute_Number   is Natural range 0 .. 59;
  37    subtype Second_Number   is Natural range 0 .. 59;
  38    subtype Second_Duration is Day_Duration range 0.0 .. 1.0;
  39
  40    function Year
  41      (Date      : Time;
  42       Time_Zone : Time_Zones.Time_Offset := 0) return Year_Number;
  43
  44    function Month
  45      (Date      : Time;
  46       Time_Zone : Time_Zones.Time_Offset := 0) return Month_Number;
  47
  48    function Day
  49      (Date      : Time;
  50       Time_Zone : Time_Zones.Time_Offset := 0) return Day_Number;
  51
  52    function Hour
  53      (Date      : Time;
  54       Time_Zone : Time_Zones.Time_Offset := 0) return Hour_Number;
  55
  56    function Minute
  57      (Date      : Time;
  58       Time_Zone : Time_Zones.Time_Offset := 0) return Minute_Number;
  59
  60    function Second
  61      (Date : Time)                             return Second_Number;
  62
  63    function Sub_Second
  64      (Date : Time)                             return Second_Duration;
  65
  66    function Seconds_Of
  67      (Hour       : Hour_Number;
  68       Minute     : Minute_Number;
  69       Second     : Second_Number := 0;
  70       Sub_Second : Second_Duration := 0.0) return Day_Duration;
  71    --  Returns a Day_Duration value for the combination of the given Hour,
  72    --  Minute, Second, and Sub_Second. This value can be used in Ada.Calendar.
  73    --  Time_Of as well as the argument to Calendar."+" and Calendar."-". If
  74    --  Seconds_Of is called with a Sub_Second value of 1.0, the value returned
  75    --  is equal to the value of Seconds_Of for the next second with a Sub_
  76    --  Second value of 0.0.
  77
  78    procedure Split
  79      (Seconds    : Day_Duration;
  80       Hour       : out Hour_Number;
  81       Minute     : out Minute_Number;
  82       Second     : out Second_Number;
  83       Sub_Second : out Second_Duration);
  84    --  Splits Seconds into Hour, Minute, Second and Sub_Second in such a way
  85    --  that the resulting values all belong to their respective subtypes. The
  86    --  value returned in the Sub_Second parameter is always less than 1.0.
  87
  88    procedure Split
  89      (Date       : Time;
  90       Year       : out Year_Number;
  91       Month      : out Month_Number;
  92       Day        : out Day_Number;
  93       Hour       : out Hour_Number;
  94       Minute     : out Minute_Number;
  95       Second     : out Second_Number;
  96       Sub_Second : out Second_Duration;
  97       Time_Zone  : Time_Zones.Time_Offset := 0);
  98    --  Splits Date into its constituent parts (Year, Month, Day, Hour, Minute,
  99    --  Second, Sub_Second), relative to the specified time zone offset. The
 100    --  value returned in the Sub_Second parameter is always less than 1.0.
 101
 102    function Time_Of
 103      (Year        : Year_Number;
 104       Month       : Month_Number;
 105       Day         : Day_Number;
 106       Hour        : Hour_Number;
 107       Minute      : Minute_Number;
 108       Second      : Second_Number;
 109       Sub_Second  : Second_Duration := 0.0;
 110       Leap_Second : Boolean := False;
 111       Time_Zone   : Time_Zones.Time_Offset := 0) return Time;
 112    --  If Leap_Second is False, returns a Time built from the date and time
 113    --  values, relative to the specified time zone offset. If Leap_Second is
 114    --  True, returns the Time that represents the time within the leap second
 115    --  that is one second later than the time specified by the parameters.
 116    --  Time_Error is raised if the parameters do not form a proper date or
 117    --  time. If Time_Of is called with a Sub_Second value of 1.0, the value
 118    --  returned is equal to the value of Time_Of for the next second with a
 119    --  Sub_Second value of 0.0.
 120
 121    function Time_Of
 122      (Year        : Year_Number;
 123       Month       : Month_Number;
 124       Day         : Day_Number;
 125       Seconds     : Day_Duration := 0.0;
 126       Leap_Second : Boolean := False;
 127       Time_Zone   : Time_Zones.Time_Offset := 0) return Time;
 128    --  If Leap_Second is False, returns a Time built from the date and time
 129    --  values, relative to the specified time zone offset. If Leap_Second is
 130    --  True, returns the Time that represents the time within the leap second
 131    --  that is one second later than the time specified by the parameters.
 132    --  Time_Error is raised if the parameters do not form a proper date or
 133    --  time. If Time_Of is called with a Seconds value of 86_400.0, the value
 134    --  returned is equal to the value of Time_Of for the next day with a
 135    --  Seconds value of 0.0.
 136
 137    procedure Split
 138      (Date        : Time;
 139       Year        : out Year_Number;
 140       Month       : out Month_Number;
 141       Day         : out Day_Number;
 142       Hour        : out Hour_Number;
 143       Minute      : out Minute_Number;
 144       Second      : out Second_Number;
 145       Sub_Second  : out Second_Duration;
 146       Leap_Second : out Boolean;
 147       Time_Zone   : Time_Zones.Time_Offset := 0);
 148    --  If Date does not represent a time within a leap second, splits Date
 149    --  into its constituent parts (Year, Month, Day, Hour, Minute, Second,
 150    --  Sub_Second), relative to the specified time zone offset, and sets
 151    --  Leap_Second to False. If Date represents a time within a leap second,
 152    --  set the constituent parts to values corresponding to a time one second
 153    --  earlier than that given by Date, relative to the specified time zone
 154    --  offset, and sets Leap_Seconds to True. The value returned in the
 155    --  Sub_Second parameter is always less than 1.0.
 156
 157    procedure Split
 158      (Date        : Time;
 159       Year        : out Year_Number;
 160       Month       : out Month_Number;
 161       Day         : out Day_Number;
 162       Seconds     : out Day_Duration;
 163       Leap_Second : out Boolean;
 164       Time_Zone   : Time_Zones.Time_Offset := 0);
 165    --  If Date does not represent a time within a leap second, splits Date
 166    --  into its constituent parts (Year, Month, Day, Seconds), relative to the
 167    --  specified time zone offset, and sets Leap_Second to False. If Date
 168    --  represents a time within a leap second, set the constituent parts to
 169    --  values corresponding to a time one second earlier than that given by
 170    --  Date, relative to the specified time zone offset, and sets Leap_Seconds
 171    --  to True. The value returned in the Seconds parameter is always less
 172    --  than 86_400.0.
 173
 174    --  Simple image and value
 175
 176    function Image
 177      (Date                  : Time;
 178       Include_Time_Fraction : Boolean := False;
 179       Time_Zone             : Time_Zones.Time_Offset := 0) return String;
 180    --  Returns a string form of the Date relative to the given Time_Zone. The
 181    --  format is "Year-Month-Day Hour:Minute:Second", where the Year is a
 182    --  4-digit value, and all others are 2-digit values, of the functions
 183    --  defined in Ada.Calendar and Ada.Calendar.Formatting, including a
 184    --  leading zero, if needed. The separators between the values are a minus,
 185    --  another minus, a colon, and a single space between the Day and Hour. If
 186    --  Include_Time_Fraction is True, the integer part of Sub_Seconds*100 is
 187    --  suffixed to the string as a point followed by a 2-digit value.
 188
 189    function Value
 190      (Date       : String;
 191       Time_Zone  : Time_Zones.Time_Offset := 0) return Time;
 192    --  Returns a Time value for the image given as Date, relative to the given
 193    --  time zone. Constraint_Error is raised if the string is not formatted as
 194    --  described for Image, or the function cannot interpret the given string
 195    --  as a Time value.
 196
 197    function Image
 198      (Elapsed_Time          : Duration;
 199       Include_Time_Fraction : Boolean := False) return String;
 200    --  Returns a string form of the Elapsed_Time. The format is "Hour:Minute:
 201    --  Second", where all values are 2-digit values, including a leading zero,
 202    --  if needed. The separators between the values are colons. If Include_
 203    --  Time_Fraction is True, the integer part of Sub_Seconds*100 is suffixed
 204    --  to the string as a point followed by a 2-digit value. If Elapsed_Time <
 205    --  0.0, the result is Image (abs Elapsed_Time, Include_Time_Fraction)
 206    --  prefixed with a minus sign. If abs Elapsed_Time represents 100 hours or
 207    --  more, the result is implementation-defined.
 208
 209    function Value (Elapsed_Time : String) return Duration;
 210    --  Returns a Duration value for the image given as Elapsed_Time.
 211    --  Constraint_Error is raised if the string is not formatted as described
 212    --  for Image, or the function cannot interpret the given string as a
 213    --  Duration value.
 214
 215 end Ada.Calendar.Formatting;