[numarray] Add standard description elements. #1215

jensmaurer · 2016-12-12T23:56:05Z

Partially addresses #1071.

This is a first step. I've only inserted description elements such as \effects and \returns and removed boilerplate introductory phrases where appropriate.

zygoloid

I definitely think this is an improvement, and from a cursory investigation it looks correct, but I've not checked that every wording change continues to convey the correct normative intent. I'd like @jwakely to review this for normative correctness before going forward.

zygoloid · 2016-12-14T20:30:08Z

source/numerics.tex

-\tcode{valarray<T>}\footnote{For convenience, such objects are referred
-to as ``arrays'' throughout the
-remainder of~\ref{numarray}.}
+Constructs a \tcode{valarray}
 which has zero length.\footnote{This default constructor is essential,


which -> that (here and below), as this is a restrictive clause.

Pre-existing text... Will do.

zygoloid · 2016-12-14T20:30:11Z

source/numerics.tex

@@ -6874,7 +6874,7 @@

 \begin{itemdescr}
 \pnum
-\effects Same as \tcode{valarray(il.begin(), il.size())}.
+\effects Equivalent to \tcode{valarray(il.begin(), il.size())}.


We have been reluctant to add "Equivalent to"s in the past, since "Equivalent to" also notionally populates the other elements of the description whereas "Same as" does not; see [structure.specifications]/4.

@jwakely Can you check that the change to "Equivalent to" here doesn't have an (unintended) normative effect?

If we don't go for "Equivalent to", it seems we have a hole in the specification regarding exceptions etc. for this function.

It probably should have used "Equivalent to" when this was added for C++11, but it didn't, and adding it is normative and arguably not editorial. However, since the constructor it refers to currently has no elements, and after this change would only have Effects: (which we want to refer to) and Requires: (which is satisfied) I don't see any actual normative change that would be caused by using "Equivalent to" here.

jensmaurer · 2016-12-14T21:17:28Z

Updated for "which" -> "that".

jwakely

The changes to "Equivalent to" don't seem to make any normative difference. The other changes are all good improvements (my comments are mostly for pre-existing problems).

jwakely · 2017-01-09T12:41:28Z

source/numerics.tex

-The elements of the array are initialized with the value of the first argument.
+\effects
+Constructs a \tcode{valarray} that has length \tcode{n}.
+The elements of the array are initialized with \tcode{v}.


Would this be clearer if it said "Each element of the array is initialized with v" ?

Fixed, also in the signature before that ("Each element of the array is value-initialized.")

jwakely · 2017-01-09T12:42:11Z

source/numerics.tex

-\tcode{n}.
+\requires
+The number of values pointed to by \tcode{p} is
+equal to or greater than \tcode{n}.


This seems a bit clunky. The form used in Clause 21 is "p points to an array of at least n elements." Although I suppose "array" has been redefined to mean "valarray" in this subclause so that might not be an improvement.

We could add a cross-reference to 8.3.4 [dcl.array] after this particular "array" to disambiguate. Done.

jwakely · 2017-01-09T13:01:41Z

source/numerics.tex

@@ -6874,7 +6874,7 @@

 \begin{itemdescr}
 \pnum
-\effects Same as \tcode{valarray(il.begin(), il.size())}.
+\effects Equivalent to \tcode{valarray(il.begin(), il.size())}.


It probably should have used "Equivalent to" when this was added for C++11, but it didn't, and adding it is normative and arguably not editorial. However, since the constructor it refers to currently has no elements, and after this change would only have Effects: (which we want to refer to) and Requires: (which is satisfied) I don't see any actual normative change that would be caused by using "Equivalent to" here.

jwakely · 2017-01-09T13:30:09Z

source/numerics.tex

-This property indicates an absence of aliasing and may be used to
-advantage by optimizing compilers.\footnote{Compilers may take advantage
+\remarks
+The expression \tcode{\&a[i+j] == \&a[i] + j}


We need to use addressof here, but that's a separate issue.

Yes, please.

[numeric.defns] bullet 1.9 mean that we can ignore the usual concerns leading to addressof in this case, so I think there is no issue at all.

Ah yes, not the first time I've forgotten about that provision.

jwakely · 2017-01-09T14:07:22Z

source/numerics.tex

-hand side, the behavior is undefined.
+\remarks
+The appearance of an array on the left-hand side of a compound assignment
+does \emph{not} invalidate references or pointers.


Why are we emphasising "not" here at all?

Removed \emph (twice).

jwakely · 2017-01-09T14:24:20Z

source/numerics.tex

-Each of these operators
-performs the indicated operation on each of its elements and the
-corresponding element of the argument array.
+to which the indicated operator can be applied. 


Do we want to be more precise in these requirements? Being able to apply the operator doesn't mean much if we don't say what types the operands are. A type could overload T::operator*=(std::string) but that doesn't mean we can use valarray<T>{} *= T{}.

Maybe something like "For each operator function, the operator that it implements is invocable with two operands of type T"

I'd like to point out that this is pre-existing text; and I think LWG failed in distant history to produce a specification for std::complex that would allow T's other than built-in floating-point types. I'm reluctant to attempt to come up with a better specification here. (Although I admit the std::complex case was probably more about trigonometric functions thatn simple stuff.)

I've added a slight rewording, highlighting the "two operands" issue.

jwakely · 2017-01-09T14:47:59Z

source/numerics.tex

-
-\pnum
-\returns \tcode{*this}.
+\effects Equivalent to: \tcode{return *this = valarray(il);}


I don't see any negative effect from using "Equivalent to" here either, although it's again arguably not editorial.

jensmaurer · 2017-01-09T21:11:54Z

I've updated the patch.

jensmaurer · 2017-01-10T08:20:47Z

@zygoloid: Back in your front yard; @jwakely has approved the change.

tkoeppe · 2017-02-04T23:27:47Z

@jensmaurer: rebase?

zygoloid · 2017-02-05T01:00:09Z

Jens, can you rebase this please? (I'm also waiting on Marshall to confirm that we're OK to do this without further LWG signoff.)

mclow · 2017-02-05T15:43:36Z

This looks good to me. The only place I had a concern was around (replaced) link 7266, but after a re-read I'm good with that, too. Thanks, Jens!

Partially addresses cplusplus#1071.

jensmaurer · 2017-02-05T19:11:23Z

Rebased as requested.

jensmaurer force-pushed the b16 branch from a8918d7 to 2187d13 Compare December 13, 2016 08:02

jensmaurer changed the title ~~[valarray] Add standard description elements.~~ [numarray] Add standard description elements. Dec 13, 2016

zygoloid reviewed Dec 14, 2016

View reviewed changes

zygoloid requested a review from jwakely December 14, 2016 20:35

jensmaurer assigned jwakely Dec 14, 2016

jensmaurer force-pushed the b16 branch from 2187d13 to c4a4c8c Compare December 14, 2016 21:16

jwakely approved these changes Jan 9, 2017

View reviewed changes

jensmaurer mentioned this pull request Jan 9, 2017

[valarray.access] 'evaluates as' -> 'evaluates to'. #1337

Merged

jensmaurer force-pushed the b16 branch from c4a4c8c to 7dbbd1c Compare January 9, 2017 21:11

jensmaurer assigned zygoloid and unassigned jwakely Jan 10, 2017

[numarray] Add standard description elements.

23241d6

Partially addresses cplusplus#1071.

jensmaurer force-pushed the b16 branch from 7dbbd1c to 23241d6 Compare February 5, 2017 19:08

zygoloid merged commit b79c419 into cplusplus:master Feb 6, 2017

jensmaurer deleted the b16 branch February 6, 2017 09:28

jensmaurer mentioned this pull request Feb 8, 2017

[valarray] wording needs major overhaul #1071

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[numarray] Add standard description elements. #1215

[numarray] Add standard description elements. #1215

jensmaurer commented Dec 12, 2016

zygoloid left a comment

zygoloid Dec 14, 2016

jensmaurer Dec 14, 2016

zygoloid Dec 14, 2016

jensmaurer Dec 14, 2016

jwakely Jan 9, 2017

jensmaurer commented Dec 14, 2016

jwakely left a comment

jwakely Jan 9, 2017

jensmaurer Jan 9, 2017

jwakely Jan 9, 2017

jensmaurer Jan 9, 2017

jwakely Jan 9, 2017

jwakely Jan 9, 2017

jensmaurer Jan 9, 2017

AlisdairM Jan 15, 2017

jwakely Jan 16, 2017

jwakely Jan 9, 2017

jensmaurer Jan 9, 2017

jwakely Jan 9, 2017

jensmaurer Jan 9, 2017

jensmaurer Jan 9, 2017

jwakely Jan 9, 2017

jensmaurer commented Jan 9, 2017

jensmaurer commented Jan 10, 2017

tkoeppe commented Feb 4, 2017

zygoloid commented Feb 5, 2017

mclow commented Feb 5, 2017

jensmaurer commented Feb 5, 2017

[numarray] Add standard description elements. #1215

[numarray] Add standard description elements. #1215

Conversation

jensmaurer commented Dec 12, 2016

zygoloid left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jensmaurer commented Dec 14, 2016

jwakely left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jensmaurer commented Jan 9, 2017

jensmaurer commented Jan 10, 2017

tkoeppe commented Feb 4, 2017

zygoloid commented Feb 5, 2017

mclow commented Feb 5, 2017

jensmaurer commented Feb 5, 2017