https://issues.dlang.org/show_bug.cgi?id=18998
--- Comment #1 from Manu <turkey...@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. --