-- --
-- S p e c --
-- --
--- Copyright (C) 2005 - 2006, Free Software Foundation, Inc. --
+-- Copyright (C) 2005-2006, Free Software Foundation, Inc. --
-- --
-- This specification is derived from the Ada Reference Manual for use with --
-- GNAT. The copyright notice above, and the license provisions that follow --
-- --
------------------------------------------------------------------------------
+-- This package provides additional components to Time, as well as new
+-- Time_Of and Split routines which handle time zones and leap seconds.
+-- This package is defined in the Ada 2005 RM (9.6.1).
+
with Ada.Calendar.Time_Zones;
package Ada.Calendar.Formatting is
Minute : Minute_Number;
Second : Second_Number := 0;
Sub_Second : Second_Duration := 0.0) return Day_Duration;
+ -- Returns a Day_Duration value for the combination of the given Hour,
+ -- Minute, Second, and Sub_Second. This value can be used in Ada.Calendar.
+ -- Time_Of as well as the argument to Calendar."+" and Calendar."–". If
+ -- Seconds_Of is called with a Sub_Second value of 1.0, the value returned
+ -- is equal to the value of Seconds_Of for the next second with a Sub_
+ -- Second value of 0.0.
procedure Split
(Seconds : Day_Duration;
Minute : out Minute_Number;
Second : out Second_Number;
Sub_Second : out Second_Duration);
+ -- Splits Seconds into Hour, Minute, Second and Sub_Second in such a way
+ -- that the resulting values all belong to their respective subtypes. The
+ -- value returned in the Sub_Second parameter is always less than 1.0.
procedure Split
(Date : Time;
Second : out Second_Number;
Sub_Second : out Second_Duration;
Time_Zone : Time_Zones.Time_Offset := 0);
+ -- Splits Date into its constituent parts (Year, Month, Day, Hour, Minute,
+ -- Second, Sub_Second), relative to the specified time zone offset. The
+ -- value returned in the Sub_Second parameter is always less than 1.0.
function Time_Of
(Year : Year_Number;
Sub_Second : Second_Duration := 0.0;
Leap_Second : Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0) return Time;
+ -- If Leap_Second is False, returns a Time built from the date and time
+ -- values, relative to the specified time zone offset. If Leap_Second is
+ -- True, returns the Time that represents the time within the leap second
+ -- that is one second later than the time specified by the parameters.
+ -- Time_Error is raised if the parameters do not form a proper date or
+ -- time. If Time_Of is called with a Sub_Second value of 1.0, the value
+ -- returned is equal to the value of Time_Of for the next second with a
+ -- Sub_Second value of 0.0.
function Time_Of
(Year : Year_Number;
Seconds : Day_Duration := 0.0;
Leap_Second : Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0) return Time;
+ -- If Leap_Second is False, returns a Time built from the date and time
+ -- values, relative to the specified time zone offset. If Leap_Second is
+ -- True, returns the Time that represents the time within the leap second
+ -- that is one second later than the time specified by the parameters.
+ -- Time_Error is raised if the parameters do not form a proper date or
+ -- time. If Time_Of is called with a Seconds value of 86_400.0, the value
+ -- returned is equal to the value of Time_Of for the next day with a
+ -- Seconds value of 0.0.
procedure Split
(Date : Time;
Sub_Second : out Second_Duration;
Leap_Second : out Boolean;
Time_Zone : Time_Zones.Time_Offset := 0);
+ -- If Date does not represent a time within a leap second, splits Date
+ -- into its constituent parts (Year, Month, Day, Hour, Minute, Second,
+ -- Sub_Second), relative to the specified time zone offset, and sets
+ -- Leap_Second to False. If Date represents a time within a leap second,
+ -- set the constituent parts to values corresponding to a time one second
+ -- earlier than that given by Date, relative to the specified time zone
+ -- offset, and sets Leap_Seconds to True. The value returned in the
+ -- Sub_Second parameter is always less than 1.0.
procedure Split
(Date : Time;
Seconds : out Day_Duration;
Leap_Second : out Boolean;
Time_Zone : Time_Zones.Time_Offset := 0);
+ -- If Date does not represent a time within a leap second, splits Date
+ -- into its constituent parts (Year, Month, Day, Seconds), relative to the
+ -- specified time zone offset, and sets Leap_Second to False. If Date
+ -- represents a time within a leap second, set the constituent parts to
+ -- values corresponding to a time one second earlier than that given by
+ -- Date, relative to the specified time zone offset, and sets Leap_Seconds
+ -- to True. The value returned in the Seconds parameter is always less
+ -- than 86_400.0.
-- Simple image and value
(Date : Time;
Include_Time_Fraction : Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0) return String;
+ -- Returns a string form of the Date relative to the given Time_Zone. The
+ -- format is "Year-Month-Day Hour:Minute:Second", where the Year is a
+ -- 4-digit value, and all others are 2-digit values, of the functions
+ -- defined in Ada.Calendar and Ada.Calendar.Formatting, including a
+ -- leading zero, if needed. The separators between the values are a minus,
+ -- another minus, a colon, and a single space between the Day and Hour. If
+ -- Include_Time_Fraction is True, the integer part of Sub_Seconds*100 is
+ -- suffixed to the string as a point followed by a 2-digit value.
function Value
(Date : String;
Time_Zone : Time_Zones.Time_Offset := 0) return Time;
+ -- Returns a Time value for the image given as Date, relative to the given
+ -- time zone. Constraint_Error is raised if the string is not formatted as
+ -- described for Image, or the function cannot interpret the given string
+ -- as a Time value.
function Image
(Elapsed_Time : Duration;
Include_Time_Fraction : Boolean := False) return String;
+ -- Returns a string form of the Elapsed_Time. The format is "Hour:Minute:
+ -- Second", where all values are 2-digit values, including a leading zero,
+ -- if needed. The separators between the values are colons. If Include_
+ -- Time_Fraction is True, the integer part of Sub_Seconds*100 is suffixed
+ -- to the string as a point followed by a 2-digit value. If Elapsed_Time <
+ -- 0.0, the result is Image (abs Elapsed_Time, Include_Time_Fraction)
+ -- prefixed with a minus sign. If abs Elapsed_Time represents 100 hours or
+ -- more, the result is implementation-defined.
function Value (Elapsed_Time : String) return Duration;
+ -- Returns a Duration value for the image given as Elapsed_Time.
+ -- Constraint_Error is raised if the string is not formatted as described
+ -- for Image, or the function cannot interpret the given string as a
+ -- Duration value.
end Ada.Calendar.Formatting;
OSDN Git Service
