Version 1.2 of ais/ai-00386.txt

Unformatted version of ais/ai-00386.txt version 1.2
Other versions for file ais/ai-00386.txt

!standard D.08 (14)          04-10-12 AI95-00386/01
!class amendment 04-10-12
!status work item 04-10-12
!status received 04-10-12
!priority Medium
!difficulty Easy
!subject Further functions returning timespan values
!summary
Additional functions Seconds and Minutes are added to Ada.Real_Time.
!problem
Specifying time-spans of more than a second is clumsy because the largest unit available is provided by the function Milliseconds. Thus when using the package Ada.Real_Time.Timing_Events to provide a timer of say thirty seconds we have to express the interval as Milliseconds(30_000) or 30*Milliseconds(1000). Similarly a five minute interval has to be written as Milliseconds(300_000) or perhaps 560Milliseconds(1000). The former might even raise Constraint_Error even though time-spans are guaranteed up to one hour.
!proposal
Additional functions Seconds and Minutes are added to Ada.Real_Time.
!wording
Insert after D.8(14)
function Seconds(S : Integer) return Time_Span; function Minutes(M : Integer) return Time_Span;
Replace D.8(26) by
The functions Nanoseconds, Microseconds, Milliseconds, Seconds, and Minutes convert the input parameter to a value of the type Time_Span. NS, US, MS, S, and M are interpreted as a number of nanoseconds, microseconds, milliseconds, seconds, and minutes respectively. The result is rounded to the nearest exactly representable value (away from zero if exactly halfway between two exactly representable values).
!discussion
While writing the Rationale for Ada 2005, it was observed that the introduction of the package Ada.Real_Time.Timing_Events would be likely to require the use of time-spans of more than a few milliseconds. No doubt it was originally thought that Ada.Real_Time would only concern short time-spans of the order of less than a second. Hence functions Nanoseconds, Microseconds and Milliseconds only were supplied.
However, in some application areas, somewhat longer intervals need to be programmed (activities in chemical process control tend to be of the order of seconds or minutes).
Having to write Milliseconds(300_000) rather than Minutes(5) is less clear and thus error prone and might even raise Constraint_Error. One can write 560Milliseconds(1000) but that seems equally curious.
We therefore introduce functions for Seconds and Minutes. We considered a function Hours as well but Time_Span_Last is only guaranteed to be 3600 seconds and so time-spans of longer than an hour need not be supported. It might therefore be misleading to provide a function Hours.
Note that this is strictly an incompatibility because we are adding to the specification of a predefined library unit. However, it has been done with the string handling packages (AI-301).
!example
Boiling an egg for breakfast:
...
protected body Egg is procedure Is_Done(Event: in out Timing_Event) is begin Ring_The_Pinger; end Is_Done; end Egg; ... Egg_Done: Timing_Event; ... Put_Egg_In_Water; Set_Handler(Event => Egg_Done, In_Time => Minutes(4), Handler => Egg.Is_Done'access); -- now read the newspaper whilst waiting for egg
--!corrigendum
!ACATS test
!appendix

*************************************************************

Questions? Ask the ACAA Technical Agent