gcc/ada/libgnat/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-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
  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    --  The following ISO-8861 format expressed as a regular expression is also
 145    --  supported:
 146    --
 147    --    (yyyymmdd | yyyy'-'mm'-'dd)'T'(hhmmss | hh':'mm':'ss)
 148    --      [ ('Z' | ('.' | ',') s{s} | ('+'|'-')hh':'mm) ]
 149    --
 150    --  Examples:
 151    --
 152    --    2017-04-14T14:47:06      20170414T14:47:06       20170414T144706
 153    --    2017-04-14T14:47:06,1234 20170414T14:47:06.1234
 154    --    2017-04-14T19:47:06+05   20170414T09:00:06-05:47
 155
 156    --  Constraint_Error is raised if the input string is malformed (does not
 157    --  conform to one of the above dates, or has an invalid time string), or
 158    --  the resulting time is not valid.
 159
 160    procedure Put_Time (Date : Ada.Calendar.Time; Picture : Picture_String);
 161    --  Put Date with format Picture. Raise Picture_Error if bad picture string
 162
 163 private
 164    ISO_Date      : constant Picture_String := "%Y-%m-%d";
 165    US_Date       : constant Picture_String := "%m/%d/%y";
 166    European_Date : constant Picture_String := "%d/%m/%y";
 167
 168 end GNAT.Calendar.Time_IO;