www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Name a phobos function!

reply Dukc <ajieskola gmail.com> writes:
I am currently authoring a pull request to Phobos, here: 
https://github.com/dlang/phobos/pull/7794. I'm trying to get a 
new function added. Currently it's named `splitBy`, and it's 
behaviour is probably best described by documentation:

-------------------------
Splits a forward range into subranges in places determined by a 
binary predicate. When iterating, one element of `r` is compared 
with `pred` to the next element. If `pred` return true, a new 
subrange is started for the next element. Otherwise, they are 
part of the same subrange. If the elements are compared with an 
inequality (!=) operator, consider $(LREF chunkBy) instead, as 
it's likely faster to execute.
Params:
pred = Predicate for determining where to split. The earlier 
element in the source range is always given as the first argument.
r = A $(REF_ALTTEXT forward range, isForwardRange, 
std,range,primitives) to be split.
Returns: a range of subranges of `r`, split such that within a 
given subrange, calling `pred` with any pair of adjacent elements 
as arguments returns `false`.
Copying the range currently has reference semantics, but this may 
change in the future.
See_also:
$(LREF splitter), which uses elements as splitters instead of 
element-to-element
relations.

```
auto splitBy(alias pred, Range)(Range r) if 
(isForwardRange!Range);

nothrow pure  system unittest
{
     import std.algorithm.comparison : equal;
     import std.range : dropExactly;
     auto source = [4, 3, 2, 11, 0, -3, -3, 5, 3, 0];

     auto result1 = source.splitBy!((a,b) => a <= b);
     assert(result1.save.equal!equal([
         [4, 3, 2],
         [11, 0, -3],
         [-3],
         [5, 3, 0]
     ]));

     //splitBy, like chunkBy, is currently a reference range (this 
may change
     //in future). Remember to call `save` when appropriate.
     auto result2 = result1.dropExactly(2);
     assert(result1.save.equal!equal([
         [-3],
         [5, 3, 0]
     ]));
}
```
-------------------------

The pull request is currently going well, tests pass and one 
approval. Atila seems to be generally receptive, but is "slightly 
unsure of the naming". I thought, what a better place to name a 
function than the D forum?

The function has already changed name once. Originally it was 
named `chunkByAny`, with the predicate being inverted. Credit for 
the current name goes to Paul Backus. But can somebody do even 
better?
Mar 15 2021
next sibling parent reply Imperatorn <johan_forsberg_86 hotmail.com> writes:
On Monday, 15 March 2021 at 13:35:24 UTC, Dukc wrote:

 I am currently authoring a pull request to Phobos, here: 
 https://github.com/dlang/phobos/pull/7794. I'm trying to get a 
 new function added. Currently it's named `splitBy`, and it's 
 behaviour is probably best described by documentation:

 [...]


Could it be named just split? Overload? 🤔
Mar 15 2021
parent reply Dukc <ajieskola gmail.com> writes:
On Monday, 15 March 2021 at 16:37:08 UTC, Imperatorn wrote:

 Could it be named just split? Overload? 🤔


It would be a bad idea IMO to overload `split`, as that's 
`std.array` function that splits eagerly. Protoname `splitBy` 
splits lazily.

However, there is a possibility to overload `splitter` instead. 
Normally, with a binary predicate, it takes a separator element 
or a separator range, but if it took neither it could act as the 
protoname `splitBy`, by comparing adjacent elements.

Also it could perhaps have a default predicate like rest or the 
`splitter` binary predicates, so that 
`[1,2,3,3,4,5,5,6].splitter.equal([[1,2,3],[3,4,5],[5,6]])`.
Mar 15 2021
parent Imperatorn <johan_forsberg_86 hotmail.com> writes:
On Monday, 15 March 2021 at 20:50:22 UTC, Dukc wrote:

 On Monday, 15 March 2021 at 16:37:08 UTC, Imperatorn wrote:

 Could it be named just split? Overload? 🤔


 It would be a bad idea IMO to overload `split`, as that's 
 `std.array` function that splits eagerly. Protoname `splitBy` 
 splits lazily.

 However, there is a possibility to overload `splitter` instead. 
 Normally, with a binary predicate, it takes a separator element 
 or a separator range, but if it took neither it could act as 
 the protoname `splitBy`, by comparing adjacent elements.

 Also it could perhaps have a default predicate like rest or the 
 `splitter` binary predicates, so that 
 `[1,2,3,3,4,5,5,6].splitter.equal([[1,2,3],[3,4,5],[5,6]])`.


🤦‍♂️, you're right, it's called splitter 😎
Mar 15 2021
prev sibling next sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Mar 15, 2021 at 01:35:24PM +0000, Dukc via Digitalmars-d wrote:

 I am currently authoring a pull request to Phobos, here:
 https://github.com/dlang/phobos/pull/7794. I'm trying to get a new
 function added. Currently it's named `splitBy`, and it's behaviour is
 probably best described by documentation:
 
 -------------------------
 Splits a forward range into subranges in places determined by a binary
 predicate. When iterating, one element of `r` is compared with `pred`
 to the next element. If `pred` return true, a new subrange is started
 for the next element. Otherwise, they are part of the same subrange.
 If the elements are compared with an inequality (!=) operator,
 consider $(LREF chunkBy) instead, as it's likely faster to execute.


[...]

Thanks for doing this!  I've been feeling a need for something like this
for a while now, but just haven't gotten around to implementing it
myself.

IMO, `splitBy` and `chunkBy` are too similar, yet with quite different
(almost opposite) semantics.  I propose `splitWhen`, since the range is
split when the predicate returns true.


On a more general note, I wonder if there's an overarching or unifying
theme between the current range-splitting functions, of which we have
quite a variety:

- std.range.chunks
- std.algorithm.group
- std.algorithm.splitter
- std.algorithm.chunkBy (no thanks to yours truly ;-))
- Now being proposed: splitBy / splitWhen

It would be nice to have some uniformity across these range-splitting
functions so that their individual roles are clearer.  Currently, a new
user looking at the above list would likely be left scratching his head
as to what the difference between these functions are, and when to use
which.  It would be nice if there was a way to unify them under a single
umbrella (or two); or if not, at the very least have some sort of
logical system to the naming so that their individual roles are clearly
situated in a coherent scheme, rather than the current haphazard mess.


T

-- 
The best compiler is between your ears. -- Michael Abrash
Mar 15 2021
next sibling parent Dukc <ajieskola gmail.com> writes:
On Monday, 15 March 2021 at 17:09:56 UTC, H. S. Teoh wrote:

 [proposed `splitWhen`]


Sounds good. I think I'll choose that if Atila and others are on 
the edge between it and `splitBy`.

Other ideas? Or commentary about the names already proposed / the 
pr itself?
Mar 15 2021
prev sibling parent Paul Backus <snarwin gmail.com> writes:
On Monday, 15 March 2021 at 17:09:56 UTC, H. S. Teoh wrote:

 On a more general note, I wonder if there's an overarching or 
 unifying theme between the current range-splitting functions, 
 of which we have quite a variety:

 - std.range.chunks
 - std.algorithm.group
 - std.algorithm.splitter
 - std.algorithm.chunkBy (no thanks to yours truly ;-))
 - Now being proposed: splitBy / splitWhen


`std.algorithm.group` does not belong in this list--it is 
actually a variant of `std.algorithm.uniq`.

One of the top candidates for "most misleading name in Phobos," 
if you ask me. :)
Mar 15 2021
prev sibling next sibling parent Mark Lagodych <lgd.mrk gmail.com> writes:
On Monday, 15 March 2021 at 13:35:24 UTC, Dukc wrote:

 I am currently authoring a pull request to Phobos, here: 
 https://github.com/dlang/phobos/pull/7794. I'm trying to get a 
 new function added. Currently it's named `splitBy`, and it's 
 behaviour is probably best described by documentation:

 -------------------------
 Splits a forward range into subranges in places determined by a 
 binary predicate. When iterating, one element of `r` is 
 compared with `pred` to the next element. If `pred` return 
 true, a new subrange is started for the next element. 
 Otherwise, they are part of the same subrange. If the elements 
 are compared with an inequality (!=) operator, consider $(LREF 
 chunkBy) instead, as it's likely faster to execute.


chopBy()
chop()
subrangeBy()
Mar 16 2021
prev sibling parent reply Dukc <ajieskola gmail.com> writes:
We decided to go with `splitWhen`. Thanks for everybody who 
suggested something!
Mar 17 2021
parent Imperatorn <johan_forsberg_86 hotmail.com> writes:
On Wednesday, 17 March 2021 at 21:36:14 UTC, Dukc wrote:

 We decided to go with `splitWhen`. Thanks for everybody who 
 suggested something!


"Naming is the hardest problem in programming" 😅
Mar 18 2021