AI22-0113-1/06

AI22-0113-1

!standard 9.6.1(91/5) 25-04-24 AI22-0113-1/06

!standard 13.3(20)

!standard 13.13.1(38)

!class binding interpretation 24-07-19

!status Revision-202Y 24-11-04

!status WG9 Approved 25-10-08

!status ARG Approved 13-0-2 24-10-31

!status work item 24-07-19

!status received 24-07-18

!submitter Christoph Grein

!priority Low

!difficulty Easy

!qualifier Clarification

!subject Usage Advice (part 3)

!summary

Split from AI22-0097-1/04 Usage Advice (Part 2): Better wording needed; reference to wrong example has to be corrected.

!issue

RM 9.6.1(91/5) NOTE 2 and the corresponding discussion in AARM 9.6.1 (91.a/5) amounts to advice not to do something. For the new Usage header, better wording is needed.
On further reflection, this note seems superfluous, see discussion.
13.3(20) is poorly formulated as advice.
13.13.1(38) NOTE 1 has a reference to Streams.Stream_IO for an example of extending type Root_Stream_Type, but there is no such type extension. Find an example of extending Root_Stream_Type elsewhere in the document.

!recommendation

(See Summary.)

!wording

Delete 9.6.1(91/5):

NOTE 2 Calling Split on the results of subtracting Duration(Local_Time_Offset*60) from Clock provides the components (hours, minutes, and so on) of the UTC time. In the United States, for example, Local_Time_Offset will generally be negative.

Delete AARM 9.6.1 (91.a/5):

Discussion: This is an illustration to help specify the value of Local_Time_Offset. A user should pass zero UTC_Time_Offset as the Time_Zone parameter of Split, rather than trying to make the above calculation.

Modify 13.3(20):

{Usage}

[NOTE 1 ] The specification of a link name with the Link_Name aspect (see B.1) for a subprogram or object is an alternative to explicit specification of its link-time address, allowing a link-time directive to place the subprogram or object within memory.

Replace 13.13.1(38) by:

Usage

Ada.Streams.Storage above provides an example of extending type Root_Stream_Type.

!discussion

For Point 1:

(Author’s note: this is the essence of a discussion between Randy and Christoph.)

The original Ada 2005 definition of Time_Offset RM 9.6.1(40/2) was confusing, so Note 2 was meant to explain what the value of Local_Time_Offset actually is (and not to be some sort of advice).

With the improved definition of Time_Offset (40/5), this confusing Note and AARM discussion should simply all be deleted. There is not much benefit to a Usage Advice, since it just repeats the definitions of the functions. And why does it suddenly start talking about subtracting a Time_Offset value in the time parameter of Split (especially as there are two such operations Calendar.Split and Calendar.Formatting.Split – which one is meant); nothing in the interface as defined suggests that someone should (or could) do that. In Tucker's world-view of time, that isn't even a meaningful operation.

For point 2, we eventually decided that we couldn’t find anything better as advice, so it was left as originally written.

!corrigendum 9.6.1(91/5)

@ddel

@xindent{@s9{NOTE 2 @ Calling Split on the results of subtracting Duration(Local_Time_Offset*60) from Clock provides the components (hours, minutes, and so on) of the UTC time. In the United States, for example, Local_Time_Offset will generally be negative.}}

!corrigendum 13.3(20)

@drepl

@xindent{@s9{NOTE 1 @ The specification of a link name with the Link_Name aspect (see @ref{B.1}) for a subprogram or object is an alternative to explicit specification of its link-time address, allowing a link-time directive to place the subprogram or object within memory.}}

@dby

@s8{@i{Usage}}

The specification of a link name with the Link_Name aspect (see @ref{B.1}) for a subprogram or object is an alternative to explicit specification of its link-time address, allowing a link-time directive to place the subprogram or object within memory.

!corrigendum 13.13.1(38)