Range documentation

[Steven Schveighoffer]

On Sat, 23 Mar 2013 23:55:26 -0400, Manu <turkeyman at gmail.com> wrote:

> I'd like to clarify some conflicts I've encountered.
>
> TDPL talks about ranges, it mentions random access ranges requiring these
> functions:
>
>   T at(int i)
>   Range slice(int x, int y)
>
> But most code I encounter rather implements:
>
>   T opIndex(size_t i)
>   Range opSlice(size_t x, size_t y)

I don't think TDPL says a lot about ranges (it purposely does not talk  
much about the library, given how incomplete the library was/is).  In the  
index, it has 3 references to ranges, and none of them at a quick glance  
did I see these words.

> Which is it? Is there a distinction? One approach is deprecated?

The latter is the correct interface.  I don't ever remember the former  
being used.  Ever.

> Also, forward ranges require:
>
>   Range save()
>
> But there is also this function:
>
>   Range opSlice()
>
> With no args, handles the syntax 'range[]'. save() and opSlice() with no
> args would appear to be identical.
> Why have both? Which will be used in which cases?

opSlice indicates the range can have slicing semantics.  Forward ranges do  
not require slicing, so it would be awkward to require [] on forward  
ranges that don't support slicing.  Although, I don't think anyone brought  
[] up as a possible replacement for .save.  I'm also not sure they are the  
same thing.  .save should create a completely separate copy (if supported)  
of the range, such that the two ranges will go forward independently.  I  
can imagine that [] on some ranges may not do that, but I can't think of a  
good use case.

-Steve