cplusplus / cplusplus/draft

[sequence.reqmts], [associative.reqmts.general]: Grammatical corrections for a.erase(q)

Open Beginner friendly
#9,166 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

P3-Other
Dominant language
TeX
Stars
221
Forks
813
Avg merge
16h 4m
Merged PRs (30d)
36

Description

Discussion:

The existing wording for a.erase(q) caught me out because it was ambiguous without referring back through the standard to prior knowledge. It also caught out others I mentioned it to. The ambiguity is due to grammatical incorrectness.

Current wording is:

Returns: An iterator that points to the element immediately following q prior to the element being
erased. If no such element exists, a.end() is returned.

The key ambiguity is in the phrase "If no such element exists", which depending on your reading, may either refer to "the element immediately following q", or
to "the element being erased". Grammatically, because the latter is closer to the secondary sentence, the logical conclusion when taking the paragraph in isolation that that is the 'element' referred to. This is apparently not the case.
The semantics of the two interpretations are as follows:

"the element immediately following q" - if no element exists after the element being erased, return end().

"the element being erased" - if erase has been supplied an iterator which does not point to an element in *this, return end().

The correct interpretation relies on knowledge of the blanket wording in [sequence.reqmts] 2.11, which states that q must be a valid constant interator into a. However, most people reading the standard for the first, second or even third time may not make that backwards leap to establish that the grammatical structure of the sentence is predicated on a sentence in an earlier passage.

Making this grammatically-correct is easily achievable by changing the phrase to "If no element follows q".

The similar wording for sequence.reqmts a.erase(q1, q2) is unambiguous because there is 'elements' and 'element', making it clear what 'element' in the second sentence refers to.

However, the same wording occurs later in the standard under [associative.reqmts.general].

Resolution:

This wording is relative to N5036.

  1. Modify [sequence.reqmts] as indicated:
  a.erase(q)

       -45- Result: iterator.
       -46- Preconditions: For vector, inplace_vector, and deque, T is Cpp17MoveAssignable.
       -47- Effects: Erases the element pointed to by q.
       -48- Returns: An iterator that points to the element immediately following q prior to the element being
       erased. If no element follows q, a.end() is returned.

  1. Modify [associative.reqmts.general] as indicated:
    a.erase(q)

        -126- Result: iterator
        -127- Effects: Erases the element pointed to by q.
        -128- Returns: An iterator pointing to the element immediately following q prior to the element being erased. 
        If no element follows q, returns a.end().
a.erase(r)

    -130- Result: iterator
    -131- Effects: Erases the element pointed to by r.
    -132- Returns: An iterator pointing to the element immediately following r prior to the element being erased. 
    If no element follows r, returns a.end().

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the [sequence.reqmts] and [associative.reqmts.general] clauses in the draft source. Apply the resolution's wording changes to both a.erase(q) occurrences and the analogous a.erase(r) wording, then verify that each return description says “If no element follows” and matches the issue's proposed text.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.