1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- G N A T . C A L E N D A R . T I M E _ I O --
9 -- Copyright (C) 1999-2024, AdaCore --
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. --
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. --
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/>. --
27 -- GNAT was originally developed by the GNAT team at New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
30 ------------------------------------------------------------------------------
32 -- This package augments standard Ada.Text_IO with facilities for input
33 -- and output of time values in standardized format.
35 with Ada
.Calendar
.Time_Zones
; use Ada
.Calendar
;
37 package GNAT
.Calendar
.Time_IO
is
39 Picture_Error
: exception;
40 -- Exception raised for incorrect picture
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:
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)
64 -- %T time, 24-hour (hh:mm:ss)
65 -- %:::z numeric time zone with : to necessary precision
66 -- (e.g., -04, +05:30)
70 -- %a locale's abbreviated weekday name (Sun..Sat)
71 -- %A locale's full weekday name, variable length
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)
80 -- %j day of year (001..366)
82 -- %U week number of year with Sunday as first day of week
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
87 -- %x locale's date representation (mm/dd/yy)
88 -- %y last two digits of year (00..99)
91 -- By default, date pads numeric fields with zeroes. GNU date
92 -- recognizes the following nonstandard numeric modifiers:
94 -- - (hyphen) do not pad the field
95 -- _ (underscore) pad the field with spaces
97 -- Here are some GNAT extensions to the GNU Date specification:
99 -- %i milliseconds (3 digits)
100 -- %e microseconds (6 digits)
101 -- %o nanoseconds (9 digits)
103 ISO_Time
: constant Picture_String
;
104 -- ISO 8601 standard date and time, with time zone.
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.
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.
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.
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.
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.
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:
137 -- hh:mm:ss - Date is the current date
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.
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
147 -- Trailing characters (in particular spaces) are not allowed
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
158 -- The following ISO-8601 format expressed as a regular expression is also
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.
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
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.
178 procedure Put_Time
(Date
: Ada
.Calendar
.Time
; Picture
: Picture_String
);
179 -- Put Date with format Picture. Raise Picture_Error if bad picture string
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";
187 end GNAT
.Calendar
.Time_IO
;