File : g-catiio.ads
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-2013, 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 -- --
19 -- --
20 -- --
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
35 package GNAT.Calendar.Time_IO is
36
37 Picture_Error : exception;
38 -- Exception raised for incorrect picture
39
40 type Picture_String is new String;
41 -- This is a string to describe date and time output format. The string is
42 -- a set of standard character and special tag that are replaced by the
43 -- corresponding values. It follows the GNU Date specification. Here are
44 -- the recognized directives :
45 --
46 -- % a literal %
47 -- n a newline
48 -- t a horizontal tab
49 --
50 -- Time fields:
51 --
52 -- %H hour (00..23)
53 -- %I hour (01..12)
54 -- %k hour ( 0..23)
55 -- %l hour ( 1..12)
56 -- %M minute (00..59)
57 -- %p locale's AM or PM
58 -- %r time, 12-hour (hh:mm:ss [AP]M)
59 -- %s seconds since 1970-01-01 00:00:00 UTC
60 -- (a nonstandard extension)
61 -- %S second (00..59)
62 -- %T time, 24-hour (hh:mm:ss)
63 --
64 -- Date fields:
65 --
66 -- %a locale's abbreviated weekday name (Sun..Sat)
67 -- %A locale's full weekday name, variable length
68 -- (Sunday..Saturday)
69 -- %b locale's abbreviated month name (Jan..Dec)
70 -- %B locale's full month name, variable length
71 -- (January..December)
72 -- %c locale's date and time (Sat Nov 04 12:02:33 EST 1989)
73 -- %d day of month (01..31)
74 -- %D date (mm/dd/yy)
75 -- %h same as %b
76 -- %j day of year (001..366)
77 -- %m month (01..12)
78 -- %U week number of year with Sunday as first day of week
79 -- (00..53)
80 -- %w day of week (0..6) with 0 corresponding to Sunday
81 -- %W week number of year with Monday as first day of week
82 -- (00..53)
83 -- %x locale's date representation (mm/dd/yy)
84 -- %y last two digits of year (00..99)
85 -- %Y year (1970...)
86 --
87 -- By default, date pads numeric fields with zeroes. GNU date
88 -- recognizes the following nonstandard numeric modifiers:
89 --
90 -- - (hyphen) do not pad the field
91 -- _ (underscore) pad the field with spaces
92 --
93 -- Here are some GNAT extensions to the GNU Date specification:
94 --
95 -- %i milliseconds (3 digits)
96 -- %e microseconds (6 digits)
97 -- %o nanoseconds (9 digits)
98
99 ISO_Date : constant Picture_String;
100 -- This format follow the ISO 8601 standard. The format is "YYYY-MM-DD",
101 -- four digits year, month and day number separated by minus.
102
103 US_Date : constant Picture_String;
104 -- This format is the common US date format: "MM/DD/YY",
105 -- month and day number, two digits year separated by slashes.
106
107 European_Date : constant Picture_String;
108 -- This format is the common European date format: "DD/MM/YY",
109 -- day and month number, two digits year separated by slashes.
110
111 function Image
112 (Date : Ada.Calendar.Time;
113 Picture : Picture_String) return String;
114 -- Return Date, as interpreted in the current local time zone, as a string
115 -- with format Picture. Raise Picture_Error if picture string is null or
116 -- has an incorrect format.
117
118 function Value (Date : String) return Ada.Calendar.Time;
119 -- Parse the string Date, interpreted as a time representation in the
120 -- current local time zone, and return the corresponding Time value. The
121 -- following time format is supported:
122 --
123 -- hh:mm:ss - Date is the current date
124 --
125 -- The following formats are also supported. They all accept an optional
126 -- time with the format "hh:mm:ss". The time is separated from the date by
127 -- exactly one space character.
128 --
129 -- When the time is not specified, it is set to 00:00:00. The delimiter '*'
130 -- must be either '-' and '/' and both occurrences must use the same
131 -- character.
132 --
133 -- Trailing characters (in particular spaces) are not allowed
134 --
135 -- yyyy*mm*dd - ISO format
136 -- yy*mm*dd - Year is assumed to be 20yy
137 -- mm*dd*yyyy - (US date format)
138 -- dd*mmm*yyyy - month spelled out
139 -- yyyy*mmm*dd - month spelled out
140 -- yyyymmdd - Iso format, no separator
141 -- mmm dd, yyyy - month spelled out
142 -- dd mmm yyyy - month spelled out
143 --
144 -- Constraint_Error is raised if the input string is malformed (does not
145 -- conform to one of the above dates, or has an invalid time string), or
146 -- the resulting time is not valid.
147
148 procedure Put_Time (Date : Ada.Calendar.Time; Picture : Picture_String);
149 -- Put Date with format Picture. Raise Picture_Error if bad picture string
150
151 private
152 ISO_Date : constant Picture_String := "%Y-%m-%d";
153 US_Date : constant Picture_String := "%m/%d/%y";
154 European_Date : constant Picture_String := "%d/%m/%y";
155
156 end GNAT.Calendar.Time_IO;