File : 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-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
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;