[Issue 18998] Improve Operator Overloading docs

Jun 16, 2018

Manu

Jun 16, 2018

Jun 17, 2018

Oct 21, 2018

Dec 10, 2022

Dec 11, 2022

Dec 11, 2022

Dec 17, 2022

Jul 03, 2023

Jul 10, 2023

Sep 20, 2023

June 16, 2018

[Issue 18998] Improve Operator Overloading docs

Posted by Manu

Permalink

Manu

Permalink

https://issues.dlang.org/show_bug.cgi?id=18998

--- Comment #1 from Manu <turkeyman@gmail.com> ---
I also suggest, for each operator as it is introduced, demonstrate the 'canonical' signature; what is the 'most standard/correct' way to specify these functions in their most simple cases.

Imagine you were writing a D equivalent of std::vector, nothing could be
simpler in terms of API spec.
Read the section "Array Indexing and Slicing Operators Overloading" from the
perspective you were writing std::vector...

What indexing type to use? size_t?
What about argument ref-ness? ref? byval? auto ref?
Argument const-ness?
What should assignment operators return? `void`? A reference to `this` like
C++?
How to correctly handle the operators that receive strings?
  constraint:     int opBinary(string op) if (op == "+") { ... }
  specialisation: int opBinary(string op : "+") { ... }
  static-if:      int opBinary(string op) { static if (op == "+") { ... } }
Each have subtly different semantics with respect to overload selection, error
messages, etc. Default choices should be suggested.

This information being clearly provided will ensure that development of D container classes will follow the same set of guidelines.

It's worth noting, the document is almost obsessed with 2-d
slicing/indexing/op-assignment concepts.
Make a point that multi-dimensional indexing is even supported, and that it is
a separate topic, and requires different handling than 1d.
Users might not imagine that multi-dimensional indexing/slicing is possible on
first contact.

I suggest establishing all indexing/slicing operators with respect to their typical 1-d cases, and then have a specific section at the end relating n-d (or 2-d in this case) indexing/slicing mechanics.

--

https://issues.dlang.org/show_bug.cgi?id=18998 Seb <greensunny12@gmail.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Keywords| |bootcamp CC| |greensunny12@gmail.com --

https://issues.dlang.org/show_bug.cgi?id=18998 Nick Treleaven <nick@geany.org> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |nick@geany.org --- Comment #3 from Nick Treleaven <nick@geany.org> --- > Press Ctrl-F and type "opSlice", scroll the highlighted text, try and understand how to implement a slicing operator properly. Note that the first contact you see looks like this: `-a[i..j] a.opIndexUnary!("-")(a.opSlice(i, j))` wat?! Tweaked unary operator docs so there's now a brief explanation and link to slice overloading above the lowering table for opIndexUnary: https://github.com/dlang/dlang.org/pull/3463 --

https://issues.dlang.org/show_bug.cgi?id=18998 --- Comment #4 from Nick Treleaven <nick@geany.org> --- This one adds examples for opCmp, opOpAssign, s.opIndex(s.opSlice(...)). https://github.com/dlang/dlang.org/pull/3467 --

https://issues.dlang.org/show_bug.cgi?id=18998 --- Comment #5 from Nick Treleaven <nick@geany.org> --- > try and understand how to implement a slicing operator properly. Note that the first contact you see looks like this: > `-a[i..j] a.opIndexUnary!("-")(a.opSlice(i, j))` wat?! I think the docs for opIndexUnary, opIndexAssign and opIndexOpAssign should be moved to the Indexing and Slicing Operators section where they make more sense. > Make a point that multi-dimensional indexing is even supported, and that it is a separate topic, With the 2nd pull I have tweaked the slicing docs to introduce 1D slicing first with an example, then move on to multidimensional. > and requires different handling than 1d. Well non-template opSlice(i, j) 'is discouraged', so they're not different really. --

https://issues.dlang.org/show_bug.cgi?id=18998 Iain Buclaw <ibuclaw@gdcproject.org> changed: What |Removed |Added ---------------------------------------------------------------------------- Priority|P1 |P4 --

https://issues.dlang.org/show_bug.cgi?id=18998 --- Comment #6 from Dlang Bot <dlang-bot@dlang.rocks> --- @ntrel updated dlang/dlang.org pull request #3652 "[spec] Improve opCast & `opCast!bool` docs" mentioning this issue: - Part of Issue 18998 - Improve Operator Overloading docs https://github.com/dlang/dlang.org/pull/3652 --

https://issues.dlang.org/show_bug.cgi?id=18998 --- Comment #7 from Dlang Bot <dlang-bot@dlang.rocks> --- dlang/dlang.org pull request #3652 "[spec] Improve opCast & `opCast!bool` docs" was merged into master: - a6cfd0db7b7f74ec27c2d908d017d82e5355023b by Nick Treleaven: Part of Issue 18998 - Improve Operator Overloading docs https://github.com/dlang/dlang.org/pull/3652 --

Forums