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-2003 Ada Core Technologies, Inc.           --
10--                                                                          --
11-- This specification is derived from the Ada Reference Manual for use with --
12-- GNAT. The copyright notice above, and the license provisions that follow --
13-- apply solely to the  contents of the part following the private keyword. --
14--                                                                          --
15-- GNAT is free software;  you can  redistribute it  and/or modify it under --
16-- terms of the  GNU General Public License as published  by the Free Soft- --
17-- ware  Foundation;  either version 2,  or (at your option) any later ver- --
18-- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
19-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
20-- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
21-- for  more details.  You should have  received  a copy of the GNU General --
22-- Public License  distributed with GNAT;  see file COPYING.  If not, write --
23-- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
24-- MA 02111-1307, USA.                                                      --
25--                                                                          --
26-- As a special exception,  if other files  instantiate  generics from this --
27-- unit, or you link  this unit with other files  to produce an executable, --
28-- this  unit  does not  by itself cause  the resulting  executable  to  be --
29-- covered  by the  GNU  General  Public  License.  This exception does not --
30-- however invalidate  any other reasons why  the executable file  might be --
31-- covered by the  GNU Public License.                                      --
32--                                                                          --
33-- GNAT was originally developed  by the GNAT team at  New York University. --
34-- Extensive contributions were provided by Ada Core Technologies Inc.      --
35--                                                                          --
36------------------------------------------------------------------------------
37
38--  This package augments standard Ada.Text_IO with facilities for input
39--  and output of time values in standardized format.
40
41package GNAT.Calendar.Time_IO is
42
43   Picture_Error : exception;
44   --  Exception raised for incorrect picture
45
46   type Picture_String is new String;
47   --  This is a string to describe date and time output format. The string is
48   --  a set of standard character and special tag that are replaced by the
49   --  corresponding values. It follows the GNU Date specification. Here are
50   --  the recognized directives :
51   --
52   --          %    a literal %
53   --          n    a newline
54   --          t    a horizontal tab
55   --
56   --          Time fields:
57   --
58   --          %H   hour (00..23)
59   --          %I   hour (01..12)
60   --          %k   hour ( 0..23)
61   --          %l   hour ( 1..12)
62   --          %M   minute (00..59)
63   --          %p   locale's AM or PM
64   --          %r   time, 12-hour (hh:mm:ss [AP]M)
65   --          %s   seconds  since 1970-01-01  00:00:00 UTC
66   --                (a nonstandard extension)
67   --          %S   second (00..59)
68   --          %T   time, 24-hour (hh:mm:ss)
69   --
70   --          Date fields:
71   --
72   --          %a   locale's abbreviated weekday name (Sun..Sat)
73   --          %A   locale's    full   weekday   name,    variable   length
74   --                  (Sunday..Saturday)
75   --          %b   locale's abbreviated month name (Jan..Dec)
76   --          %B   locale's    full    month    name,   variable    length
77   --                  (January..December)
78   --          %c   locale's date and time (Sat Nov 04 12:02:33 EST 1989)
79   --          %d   day of month (01..31)
80   --          %D   date (mm/dd/yy)
81   --          %h   same as %b
82   --          %j   day of year (001..366)
83   --          %m   month (01..12)
84   --          %U   week number  of year with  Sunday as first day  of week
85   --                  (00..53)
86   --          %w   day of week (0..6) with 0 corresponding to Sunday
87   --          %W   week number  of year with  Monday as first day  of week
88   --                  (00..53)
89   --          %x   locale's date representation (mm/dd/yy)
90   --          %y   last two digits of year (00..99)
91   --          %Y   year (1970...)
92   --
93   --          By default,  date pads numeric fields with zeroes.  GNU date
94   --          recognizes the following nonstandard numeric modifiers:
95   --
96   --          -    (hyphen) do not pad the field
97   --          _    (underscore) pad the field with spaces
98   --
99   --  Here are some GNAT extensions to the GNU Date specification:
100   --
101   --          %i   milliseconds (3 digits)
102   --          %e   microseconds (6 digits)
103   --          %o   nanoseconds  (9 digits)
104
105   ISO_Date : constant Picture_String;
106   --  This format follow the ISO 8601 standard. The format is "YYYY-MM-DD",
107   --  four digits year, month and day number separated by minus.
108
109   US_Date : constant Picture_String;
110   --  This format is the common US date format: "MM/DD/YY",
111   --  month and day number, two digits year separated by slashes.
112
113   European_Date : constant Picture_String;
114   --  This format is the common European date format: "DD/MM/YY",
115   --  day and month number, two digits year separated by slashes.
116
117   function Image
118     (Date    : Ada.Calendar.Time;
119      Picture : Picture_String)
120      return    String;
121   --  Return Date as a string with format Picture.
122   --  raise Picture_Error if picture string is wrong
123
124   procedure Put_Time
125     (Date    : Ada.Calendar.Time;
126      Picture : Picture_String);
127   --  Put Date with format Picture.
128   --  raise Picture_Error if picture string is wrong
129
130private
131   ISO_Date      : constant Picture_String := "%Y-%m-%d";
132   US_Date       : constant Picture_String := "%m/%d/%y";
133   European_Date : constant Picture_String := "%d/%m/%y";
134
135end GNAT.Calendar.Time_IO;
136