Policy for exposing range structs

Seb via Digitalmars-d digitalmars-d at puremagic.com
Fri Mar 25 04:37:24 PDT 2016


If I understand it correctly, the current policy in Phobos is 
that range methods should use static nested structs to avoid the 
name clutter and document the capabilities of the returned ranges 
in the documentation.
However there are a lot of old functions that still use public 
structs, which leads to the rather confusing documentation output 
in std.range:

Chunks · chunks · Cycle · cycle ... evenChunks · EvenChunks · 
FrontTransversal · frontTransversal · ... · indexed · Indexed · 
... · lockstep · Lockstep · .. · Recurrence · recurrence · 
RefRange · refRange · repeat · Repeat · ... · sequence · Sequence 
· SortedRange · ... · Take · take · ... Transversal · transversal 
· TransverseOptions · zip · Zip

(off-topic: it's quite interesting to see that sometimes the 
structs are before the method and sometimes after it)

Two arguments to keep exposing the structs are that (1) an API 
user can explicitly specify the return type (in contrast to auto) 
and (2) one can see the capabilities of the struct in the 
documentation.

There are many cases where methods in these structs are optional 
and depend on the capabilities of the input range (e.g. backward, 
length, random access, ...). I could imagine that

1) We rework ddoc, s.t. it doesn't list these structs in the 
overview and adds the struct methods to the function (could get 
ugly)
2) We deprecate those exposed structs and make them 
private/nested (does anyone know whether it's common to depend on 
those structs?)

What are your thoughts on this matter?

(This is a follow-up from a short discussion with Jakob Ovrum on 
github [1].)

[1] https://github.com/D-Programming-Language/phobos/pull/4027


More information about the Digitalmars-d mailing list