1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- A D A . C A L E N D A R . F O R M A T T I N G --
9 -- Copyright (C) 2005-2006, Free Software Foundation, Inc. --
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. --
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. --
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. --
33 -- GNAT was originally developed by the GNAT team at New York University. --
34 -- Extensive contributions were provided by Ada Core Technologies Inc. --
36 ------------------------------------------------------------------------------
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).
42 with Ada
.Calendar
.Time_Zones
;
44 package Ada
.Calendar
.Formatting
is
49 (Monday
, Tuesday
, Wednesday
, Thursday
, Friday
, Saturday
, Sunday
);
51 function Day_Of_Week
(Date
: Time
) return Day_Name
;
53 -- Hours:Minutes:Seconds access
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;
62 Time_Zone
: Time_Zones
.Time_Offset
:= 0) return Year_Number
;
66 Time_Zone
: Time_Zones
.Time_Offset
:= 0) return Month_Number
;
70 Time_Zone
: Time_Zones
.Time_Offset
:= 0) return Day_Number
;
74 Time_Zone
: Time_Zones
.Time_Offset
:= 0) return Hour_Number
;
78 Time_Zone
: Time_Zones
.Time_Offset
:= 0) return Minute_Number
;
81 (Date
: Time
) return Second_Number
;
84 (Date
: Time
) return Second_Duration
;
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.
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.
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.
124 Month
: Month_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.
143 Month
: Month_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.
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.
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
194 -- Simple image and value
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.
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
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.
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
235 end Ada
.Calendar
.Formatting
;