997. "Effects: Equivalent to" is underspecified

Section: 16.3.2.4 [structure.specifications] Status: C++11 Submitter: Thomas Plum Opened: 2009-03-03 Last modified: 2016-01-28

Priority: Not Prioritized

View other active issues in [structure.specifications].

View all other issues in [structure.specifications].

View all issues with C++11 status.

Discussion:

Addresses UK-163 [CD1]

Many functions are defined as "Effects: Equivalent to a...", which seems to also define the preconditions, effects, etc. But this is not made clear.

After studying the occurrences of "Effects: Equivalent to", I agree with the diagnosis but disagree with the solution. In 27.4.3.3 [string.cons] we find

14 Effects: If InputIterator is an integral type, equivalent to basic_string(static_cast<size_type>(begin), static_cast<value_type>(end), a)

15 Otherwise constructs a string from the values in the range [begin, end), as indicated in the Sequence Requirements table (see 23.1.3).

This would be devishly difficult to re-write with an explicit "Equivalent to:" clause. Instead, I propose the following, which will result in much less editorial re-work.

[ 2009-05-09 Alisdair adds: ]

This issue is related to 492.

[ Batavia (2009-05): ]

We agree with the proposed resolution. Move to Tentatively Ready.

Proposed resolution:

Add a new paragraph after 16.3.2.4 [structure.specifications], p3:

-3- Descriptions of function semantics contain the following elements (as appropriate):¹⁵⁴

• Requires: the preconditions for calling the function
• Effects: the actions performed by the function
• Postconditions: the observable results established by the function
• Returns: a description of the value(s) returned by the function
• Throws: any exceptions thrown by the function, and the conditions that would cause the exception
• Complexity: the time and/or space complexity of the function
• Remarks: additional semantic constraints on the function
• Error conditions: the error conditions for error codes reported by the function.
• Notes: non-normative comments about the function

Whenever the Effects element specifies that the semantics of some function F are Equivalent to some code-sequence, then the various elements are interpreted as follows. If F's semantics specifies a Requires element, then that requirement is logically imposed prior to the equivalent-to semantics. Then, the semantics of the code-sequence are determined by the Requires, Effects, Postconditions, Returns, Throws, Complexity, Remarks, Error Conditions and Notes specified for the (one or more) function invocations contained in the code-sequence. The value returned from F is specified by F's Returns element, or if F has no Returns element, a non-void return from F is specified by the Returns elements in code-sequence. If F's semantics contains a Throws (or Postconditions, or Complexity) element, then that supersedes any occurrences of that element in the code-sequence.