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-2013, 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
22with Ada.Calendar.Time_Zones;
23
24package 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
215end Ada.Calendar.Formatting;
216