Package: Util.Calendar.IO

Dependencies

with Ada.Calendar;

Description

Copyright © 2001, 2002 by Thomas Wolf.
This piece of software is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. This software is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License with this distribution, see file "GPL.txt". If not, write to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
As a special exception from the GPL, if other files instantiate generics from this unit, or you link this unit with other files to produce an executable, this unit does not by itself cause the resulting executable to be covered by the GPL. This exception does not however invalidate any other reasons why the executable file might be covered by the GPL.

Version: 1.1

Author:
Thomas Wolf (TW) <twolf AT acm DOT org>
Purpose:
Routines for converting Ada.Calendar.Time values to strings. Identical in function to the operations in Util.Calendars.Western and Util.Times.IO.

Provided nonetheless because one doesn't always want to drag in all the extended time and calendar support, especially for simple applications.

Tasking Semantics
Fully task-safe; not abortion-safe.
Storage Semantics
No dynamic storage allocation.

Header

package Util.Calendar.IO is

 
pragma Elaborate_Body;

Type Summary

Date_Format

Other Items:

function Image
  (Instant      : in Ada.Calendar.Day_Duration;
   With_Seconds : in Boolean := True;
   AM_PM        : in Boolean := False)
  return String;
Returns a string representation of the given time value. If Seconds is False, the format is "HH:MM", seconds are omitted. If Seconds is True, the format is "HH:MM:SS".

If AM_PM is false, the international 24h representation is chosen, otherwise the english a.m./p.m. format is generated: the hour part always is in the range 0 .. 12, and the strings " am" or " pm" are appended as needed. Note that noon and midnight cannot be represented in the am/pm system (12:00 am or 00:00 am have no meaning at all; "am" starts after midnight, and "pm" starts after noon). If AM_PM is True, noon generates the string "Noon", and midnight generates the string "Midnight". Note that midnight is 00:00:00, hence it is the beginning of the day, not the end! Also note that you still can get a string "00:00 am" or "00:00:00 am" if the seconds or the fraction is > zero, but not displayed. Instants between noon and 13:00:00 generate strings with an hour part "12" and " pm" at the end.

The function never rounds, i.e. seconds or fractions omitted are just truncated, e.g. 11:11:59.665 yields "11:11" or "11:11:59". 

function Image
  (Instant   : in Ada.Calendar.Day_Duration;
   Precision : in Natural;
   AM_PM     : in Boolean := False)
  return String;
Returns a string with the format "HH:MM:SS.FFF", where FFF has as many digits as specified by Precision. If Precision is zero, the whole fraction including the decimal point is omitted. AM_PM has the same effect as for the other Image function, except that instances between noon and 13:00:00 generate strings with an hour part "00" and " pm" at the end. This is because rounding of e.g. 23:59:59.9 with precision 0 may generate the string "12:00:00 pm", and so might e.g. 12:00:00.1 if we returned these mid-day times with an hour part "12", too.

This function rounds the fraction to the given precision:
PrecisionResulting String
11:11:59.66511:11:59.999
0 "11:12:00" "11:12:00"
1 "11:11:59.7" "11:12:00.0"
2 "11:11:59.67" "11:12:00.00"
3 "11:11:59.665" "11:11:59.999"
4 "11:11:59.6650" "11:11:59.9990"

Note that rounding may generate a result of "24:00:00" or "12:00:00 am" (noon) or "12:00:00 pm" (midnight; end of the day!) if Precision is zero! 

type Date_Format is (DMY, MDY, YMD);
Day-Month-Year, Month-Day-Year, Year-Month-Day. I've never come across any other ordering, and hence the remaining permutations DYM, MYD, and YDM are not supported. 
function Image
  (Date      : in Ada.Calendar.Time;
   Format    : in Date_Format := YMD;
   Separator : in String      := "-";
   Padding   : in Boolean     := True)
  return String;
Individual date components are separated by the given Separator.

If Padding is true, day and month numbers smaller than 10 have a leading zero.

Examples: (assuming Padding = True)
FormatSeparator03-OCT-2001 yields:
English style:MDY"/" "10/03/2001"
German style: DMY". " "03. 10. 2001"
ISO 8601: YMD"-" "2001-10-03"
Timestamp: YMD"" "20011003"

With the default arguments, the function returns the ISO 8601 date representation. 

end Util.Calendar.IO;
Generated on 2002-12-01 at 14:23:16 by AdaBrowse 3.2 using configuration files util.cfg, common.cfg.