|
111
|
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 -- --
|
|
131
|
9 -- Copyright (C) 2005-2018, Free Software Foundation, Inc. --
|
|
111
|
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;
|
