1------------------------------------------------------------------------------
2--                                                                          --
3--                         GNAT RUN-TIME COMPONENTS                         --
4--                                                                          --
5--                G N A T . C A L E N D A R . T I M E _ I O                 --
6--                                                                          --
7--                                 S p e c                                  --
8--                                                                          --
9--                     Copyright (C) 1999-2020, AdaCore                     --
10--                                                                          --
11-- GNAT is free software;  you can  redistribute it  and/or modify it under --
12-- terms of the  GNU General Public License as published  by the Free Soft- --
13-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
14-- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
15-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
16-- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
17--                                                                          --
18-- As a special exception under Section 7 of GPL version 3, you are granted --
19-- additional permissions described in the GCC Runtime Library Exception,   --
20-- version 3.1, as published by the Free Software Foundation.               --
21--                                                                          --
22-- You should have received a copy of the GNU General Public License and    --
23-- a copy of the GCC Runtime Library Exception along with this program;     --
24-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
25-- <http://www.gnu.org/licenses/>.                                          --
26--                                                                          --
27-- GNAT was originally developed  by the GNAT team at  New York University. --
28-- Extensive contributions were provided by Ada Core Technologies Inc.      --
29--                                                                          --
30------------------------------------------------------------------------------
31
32--  This package augments standard Ada.Text_IO with facilities for input
33--  and output of time values in standardized format.
34
35with Ada.Calendar.Time_Zones; use Ada.Calendar;
36
37package GNAT.Calendar.Time_IO is
38
39   Picture_Error : exception;
40   --  Exception raised for incorrect picture
41
42   type Picture_String is new String;
43   --  This is a string to describe date and time output format. The string is
44   --  a set of standard character and special tag that are replaced by the
45   --  corresponding values. It follows the GNU Date specification. Here are
46   --  the recognized directives:
47   --
48   --          %    a literal %
49   --          n    a newline
50   --          t    a horizontal tab
51   --
52   --          Time fields:
53   --
54   --          %H   hour (00..23)
55   --          %I   hour (01..12)
56   --          %k   hour ( 0..23)
57   --          %l   hour ( 1..12)
58   --          %M   minute (00..59)
59   --          %p   locale's AM or PM
60   --          %r   time, 12-hour (hh:mm:ss [AP]M)
61   --          %s   seconds  since 1970-01-01  00:00:00 UTC
62   --                (a nonstandard extension)
63   --          %S   second (00..59)
64   --          %T   time, 24-hour (hh:mm:ss)
65   --          %:::z  numeric time zone with : to necessary precision
66   --                 (e.g., -04, +05:30)
67   --
68   --          Date fields:
69   --
70   --          %a   locale's abbreviated weekday name (Sun..Sat)
71   --          %A   locale's    full   weekday   name,    variable   length
72   --                  (Sunday..Saturday)
73   --          %b   locale's abbreviated month name (Jan..Dec)
74   --          %B   locale's    full    month    name,   variable    length
75   --                  (January..December)
76   --          %c   locale's date and time (Sat Nov 04 12:02:33 EST 1989)
77   --          %d   day of month (01..31)
78   --          %D   date (mm/dd/yy)
79   --          %h   same as %b
80   --          %j   day of year (001..366)
81   --          %m   month (01..12)
82   --          %U   week number  of year with  Sunday as first day  of week
83   --                  (00..53)
84   --          %w   day of week (0..6) with 0 corresponding to Sunday
85   --          %W   week number  of year with  Monday as first day  of week
86   --                  (00..53)
87   --          %x   locale's date representation (mm/dd/yy)
88   --          %y   last two digits of year (00..99)
89   --          %Y   year (1970...)
90   --
91   --          By default,  date pads numeric fields with zeroes.  GNU date
92   --          recognizes the following nonstandard numeric modifiers:
93   --
94   --          -    (hyphen) do not pad the field
95   --          _    (underscore) pad the field with spaces
96   --
97   --  Here are some GNAT extensions to the GNU Date specification:
98   --
99   --          %i   milliseconds (3 digits)
100   --          %e   microseconds (6 digits)
101   --          %o   nanoseconds  (9 digits)
102
103   ISO_Time : constant Picture_String;
104   --  ISO 8601 standard date and time, with time zone.
105
106   ISO_Date : constant Picture_String;
107   --  This format follows the ISO 8601 standard. The format is "YYYY-MM-DD",
108   --  four digits year, month and day number separated by minus.
109
110   US_Date : constant Picture_String;
111   --  This format is the common US date format: "MM/DD/YY",
112   --  month and day number, two digits year separated by slashes.
113
114   European_Date : constant Picture_String;
115   --  This format is the common European date format: "DD/MM/YY",
116   --  day and month number, two digits year separated by slashes.
117
118   function Image
119     (Date    : Ada.Calendar.Time;
120      Picture : Picture_String) return String;
121   --  Return Date, as interpreted in the current local time zone, as a string
122   --  with format Picture. Raise Picture_Error if picture string is null or
123   --  has an incorrect format.
124
125   function Image
126     (Date      : Ada.Calendar.Time;
127      Picture   : Picture_String;
128      Time_Zone : Time_Zones.Time_Offset) return String;
129   --  Same as previous Image, except it uses the specified time zone instead
130   --  of the local time zone.
131
132   function Value (Date : String) return Ada.Calendar.Time;
133   --  Parse the string Date, interpreted as a time representation in the
134   --  current local time zone, and return the corresponding Time value. The
135   --  following time format is supported:
136   --
137   --     hh:mm:ss             - Date is the current date
138   --
139   --  The following formats are also supported. They all accept an optional
140   --  time with the format "hh:mm:ss". The time is separated from the date by
141   --  exactly one space character.
142   --
143   --  When the time is not specified, it is set to 00:00:00. The delimiter '*'
144   --  must be either '-' and '/' and both occurrences must use the same
145   --  character.
146   --
147   --  Trailing characters (in particular spaces) are not allowed
148   --
149   --     yyyy*mm*dd           - ISO format
150   --     yy*mm*dd             - Year is assumed to be 20yy
151   --     mm*dd*yyyy           - (US date format)
152   --     dd*mmm*yyyy          - month spelled out
153   --     yyyy*mmm*dd          - month spelled out
154   --     yyyymmdd             - Iso format, no separator
155   --     mmm dd, yyyy         - month spelled out
156   --     dd mmm yyyy          - month spelled out
157   --
158   --  The following ISO-8601 format expressed as a regular expression is also
159   --  supported:
160   --
161   --    (yyyymmdd | yyyy'-'mm'-'dd)'T'(hhmmss | hh':'mm':'ss)
162   --      [ ('.' | ',') s{s} ]
163   --      [ ('Z' | ('+'|'-')hh':'mm) ]
164   --  Trailing characters (including spaces) are not allowed.
165   --  In the ISO case, the current time zone is not used; the time zone
166   --  is as specified in the string, defaulting to UTC.
167   --
168   --  Examples:
169   --
170   --    2017-04-14T14:47:06      20170414T14:47:06       20170414T144706
171   --    2017-04-14T14:47:06,1234 20170414T14:47:06.1234
172   --    2017-04-14T19:47:06+05   20170414T09:00:06-05:47
173
174   --  Constraint_Error is raised if the input string is malformed (does not
175   --  conform to one of the above dates, or has an invalid time string), or
176   --  the resulting time is not valid.
177
178   procedure Put_Time (Date : Ada.Calendar.Time; Picture : Picture_String);
179   --  Put Date with format Picture. Raise Picture_Error if bad picture string
180
181private
182   ISO_Time      : constant Picture_String := "%Y-%m-%dT%H:%M:%S%:::z";
183   ISO_Date      : constant Picture_String := "%Y-%m-%d";
184   US_Date       : constant Picture_String := "%m/%d/%y";
185   European_Date : constant Picture_String := "%d/%m/%y";
186
187end GNAT.Calendar.Time_IO;
188