Package: Util.Times.IO

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:
This package provides Image functions converting Day_Durations and Time_Differences to strings.

For date images, see packages Util.Calendars and Util.Calendars.Western.

Tasking Semantics
Neither task- nor abortion-safe.
Storage Semantics
No dynamic storage allocation.

Header

package Util.Times.IO is

Other Items:

function Image
  (Instant      : in 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 .. 11, 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.

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 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.

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 am" (noon) or "12:00 pm" (midnight; end of the day!) if Precision is zero! 

function Image
  (Instant   : in Time_Difference;
   With_Days : in Boolean := True)
  return String;
Generates a string of the format "25h11m13s" if With_Days is False or "1d01h11m13s" if it is True. A sub-second fraction is ignored; the value is not rounded. 
function Image
  (Instant   : in Time_Difference;
   Precision : in Natural;
   With_Days : in Boolean := True)
  return String;
As the other Image function, but also includes the fraction, rounded to the given precision. The format is "25h11m13.665s" or "1d01h11m13.665s". 
end Util.Times.IO;
Generated on 2002-12-01 at 14:23:20 by AdaBrowse 3.2 using configuration files util.cfg, common.cfg.