216 lines
9.9 KiB
Ada
216 lines
9.9 KiB
Ada
------------------------------------------------------------------------------
|
|
-- --
|
|
-- GNAT RUN-TIME COMPONENTS --
|
|
-- --
|
|
-- A D A . C A L E N D A R . F O R M A T T I N G --
|
|
-- --
|
|
-- S p e c --
|
|
-- --
|
|
-- Copyright (C) 2005-2013, Free Software Foundation, Inc. --
|
|
-- --
|
|
-- This specification is derived from the Ada Reference Manual for use with --
|
|
-- GNAT. In accordance with the copyright of that document, you can freely --
|
|
-- copy and modify this specification, provided that if you redistribute a --
|
|
-- modified version, any changes that you have made are clearly indicated. --
|
|
-- --
|
|
------------------------------------------------------------------------------
|
|
|
|
-- 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
|
|
|
|
-- Day of the week
|
|
|
|
type Day_Name is
|
|
(Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday);
|
|
|
|
function Day_Of_Week (Date : Time) return Day_Name;
|
|
|
|
-- Hours:Minutes:Seconds access
|
|
|
|
subtype Hour_Number is Natural range 0 .. 23;
|
|
subtype Minute_Number is Natural range 0 .. 59;
|
|
subtype Second_Number is Natural range 0 .. 59;
|
|
subtype Second_Duration is Day_Duration range 0.0 .. 1.0;
|
|
|
|
function Year
|
|
(Date : Time;
|
|
Time_Zone : Time_Zones.Time_Offset := 0) return Year_Number;
|
|
|
|
function Month
|
|
(Date : Time;
|
|
Time_Zone : Time_Zones.Time_Offset := 0) return Month_Number;
|
|
|
|
function Day
|
|
(Date : Time;
|
|
Time_Zone : Time_Zones.Time_Offset := 0) return Day_Number;
|
|
|
|
function Hour
|
|
(Date : Time;
|
|
Time_Zone : Time_Zones.Time_Offset := 0) return Hour_Number;
|
|
|
|
function Minute
|
|
(Date : Time;
|
|
Time_Zone : Time_Zones.Time_Offset := 0) return Minute_Number;
|
|
|
|
function Second
|
|
(Date : Time) return Second_Number;
|
|
|
|
function Sub_Second
|
|
(Date : Time) return Second_Duration;
|
|
|
|
function Seconds_Of
|
|
(Hour : Hour_Number;
|
|
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;
|
|
Hour : out Hour_Number;
|
|
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;
|
|
Year : out Year_Number;
|
|
Month : out Month_Number;
|
|
Day : out Day_Number;
|
|
Hour : out Hour_Number;
|
|
Minute : out Minute_Number;
|
|
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;
|
|
Month : Month_Number;
|
|
Day : Day_Number;
|
|
Hour : Hour_Number;
|
|
Minute : Minute_Number;
|
|
Second : Second_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;
|
|
Month : Month_Number;
|
|
Day : Day_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;
|
|
Year : out Year_Number;
|
|
Month : out Month_Number;
|
|
Day : out Day_Number;
|
|
Hour : out Hour_Number;
|
|
Minute : out Minute_Number;
|
|
Second : out Second_Number;
|
|
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;
|
|
Year : out Year_Number;
|
|
Month : out Month_Number;
|
|
Day : out Day_Number;
|
|
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
|
|
|
|
function Image
|
|
(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;
|