!standard D.08    (14)                              05-03-18  AI95-00386/03
!standard D.08    (26)
!class amendment 04-10-12
!status Amendment 200Y 04-12-01
!status ARG Approved 9-0-1  04-11-19
!status work item 04-10-12
!status received 04-10-12
!priority Medium
!difficulty Easy
!subject Further functions returning Time_Span 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 5*60*Milliseconds(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
5*60*Milliseconds(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 D.8(14)

@drepl
@xcode<  @b<function> Nanoseconds  (NS : Integer) @b<return> Time_Span;
  @b<function> Microseconds (US : Integer) @b<return> Time_Span;
  @b<function> Milliseconds (MS : Integer) @b<return> Time_Span;>
@dby
@xcode<  @b<function> Nanoseconds  (NS : Integer) @b<return> Time_Span;
  @b<function> Microseconds (US : Integer) @b<return> Time_Span;
  @b<function> Milliseconds (MS : Integer) @b<return> Time_Span;
  @b<function> Seconds      (S  : Integer) @b<return> Time_Span;
  @b<function> Minutes      (M  : Integer) @b<return> Time_Span;>

!corrigendum D.8(26)

@drepl
The functions Nanoseconds, Microseconds, and Milliseconds convert the input
parameter to a value of the type Time_Span. NS, US, and MS are interpreted as a
number of nanoseconds, microseconds, and milliseconds respectively. The result
is rounded to the nearest exactly representable value (away from zero if
exactly halfway between two exactly representable values).
@dby
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).

!ACATS test

!appendix

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