Package: Ada.Calendar.Formatting

Dependencies

pragma License (Unrestricted);

with Ada.Calendar.Time_Zones;

Description

AI-351

Implementation Advice

An implementation should support leap seconds if the target system supports them. If leap seconds are not supported, functions returning leap seconds should return zero, and Time_Of should raise Time_Error if Leap_Second is true.

Header

package Ada.Calendar.Formatting is

Type Summary

Day_Name

Other Items:

type Day_Name is
   (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday);

function Day_of_Week (Date : in Time) return Day_Name;

Returns the day of the week for Time. This is based on the Year, Month, and Day values of Time.

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 Hour (Date        : in Time;
               Time_Offset : in Time_Zones.Time_Offset := 0)
   return Hour_Number;

Returns the hour for Date, as appropriate the specified time zone offset.

function Minute (Date        : in Time;
                 Time_Offset : in Time_Zones.Time_Offset := 0)
   return Minute_Number;

Returns the minute within the hour for Date, as appropriate for the specified time zone offset.

function Second (Date        : in Time;
                 Time_Offset : in Time_Zones.Time_Offset := 0)
   return Second_Number;

Returns the second within the hour and minute for Date, as appropriate for the specified time zone offset.

function Sub_Second (Date        : in Time;
                     Time_Offset : in Time_Zones.Time_Offset := 0)
   return Second_Duration;

Returns the fraction of second for Date. (This has the same accuracy as Day_Duration), as appropriate for the specified time zone offset.

function Seconds_Of (Hour       : in Hour_Number;
                     Minute     : in Minute_Number;
                     Second     : in Second_Number := 0;
                     Sub_Second : in Second_Duration := 0.0)
   return Day_Duration;

Returns a Day_Duration value for the Hour:Minute:Second.Sub_Second. This value can be used in Calendar.Time_Of as well as the argument to Calendar."+" and Calendar."-".

procedure Split (Seconds    : in  Day_Duration;
                 Hour       : out Hour_Number;
                 Minute     : out Minute_Number;
                 Second     : out Second_Number;
                 Sub_Second : out Second_Duration);

Split Seconds into Hour:Minute:Second.Sub_Second.

procedure Split (Date        : in  Time;
                 Time_Offset : in  Time_Zones.Time_Offset := 0;
                 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);

Split Date into its constituent parts (Year, Month, Day, Hour, Minute, Second, Sub_Second), relative to the specified time zone offset.

function Time_Of (Year        : in Year_Number;
                  Month       : in Month_Number;
                  Day         : in Day_Number;
                  Hour        : in Hour_Number;
                  Minute      : in Minute_Number;
                  Second      : in Second_Number;
                  Sub_Second  : in Second_Duration := 0.0;
                  Leap_Second : in Boolean := False;
                  Time_Offset : in Time_Zones.Time_Offset := 0)
   return Time;

Returns a Time built from the date and time values, relative to the specified timezone. Time_Error is raised if Leap_Second is True, and Hour, Minute, and Second are not appropriate for a Leap_Second.

AARM Note:

A leap second always occurs as midnight UTC, and is 23:59:60 UTC in ISO notation. So, if the time zone is UTC, if any of Hour /= 23, Minute /= 59, or Second /= 59, then Time_Error should be raised. However, we do not say that, because other time zones will have different values for them.

function Time_Of (Year        : in Year_Number;
                  Month       : in Month_Number;
                  Day         : in Day_Number;
                  Seconds     : in Day_Duration;
                  Leap_Second : in Boolean := False;
                  Time_Offset : in Time_Zones.Time_Offset := 0)
   return Time;

Returns a Time built from the date and time values, relative to the specified time zone offset. Time_Error is raised if Leap_Second is True, and Seconds is not appropriate for a Leap_Second.

procedure Split (Date        : in  Time;
                 Time_Offset : in  Time_Zones.Time_Offset := 0;
                 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);

Split Date into its constituent parts (Year, Month, Day, Hour, Minute, Second, Sub_Second), relative to the specified time zone offset. Leap_Second is true if Date identifies a leap second.

procedure Split (Date        : in  Time;
                 Time_Offset : in  Time_Zones.Time_Offset := 0;
                 Year        : out Year_Number;
                 Month       : out Month_Number;
                 Day         : out Day_Number;
                 Seconds     : out Day_Duration;
                 Leap_Second : out Boolean);

Split Date into its constituent parts (Year, Month, Day, Seconds), relative to the specified time zone offset. Leap_Second is true if Date identifies a leap second.

function Image (Date                  : Time;
                Include_Time_Fraction : Boolean := False) return String;

Returns a string form of the Date. The format is "Year-Month-Day Hour:Minute:Second", where each value other than Year is a 2 digit form of the value of the functions defined in Calendar and Calendar.Formatting, including a leading '0', if needed. Year is a 4 digit value. If Include_Time_Fraction is True, and Sub_Seconds*100 is suffixed to the string as a 2 digit value following a '.'.

AARM Note:

The Image provides a string in ISO 8601 format, the international standard time format. Alternative representations allowed in ISO 8601 are not supported here.

ISO 8601 allows 24:00:00 for midnight; and a seconds value of 60 for leap seconds. These are not allowed here (the routines mentioned above cannot produce those results).

function Value (Date : String) return Time;

Returns a Time value for the image given as Date. 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 The format is "Hours:Minute:Second", where each value is a 2 digit form of the value, including a leading '0', if needed. If Include_Time_Fraction is True, Sub_Seconds*100 is suffixed to the string as a 2 digit value following a '.'.

AARM Note:

This cannot be implemented (directly) by calling Ada.Calendar.Formatting.Split, since it may be out of the range of Day_Duration, and thus the number of hours may be out of the range of Hour_Number.

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;