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