------------------------------------------------------------------------------
--                                                                          --
--                         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-2021, 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, Time_Error is raised.

   function Local_Image
     (Date                  : Time;
      Include_Time_Fraction : Boolean := False) return String
   is (Image (Date,
              Include_Time_Fraction,
              Time_Zones.Local_Time_Offset (Date)));
   --  Returns a string form of Date relative to the local time offset.

   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;