Improving Symbol Names

[pbackus]

Which symbols in Phobos are poorly-named, and how might they be improved?

[pbackus]

countUntil should be renamed to indexOf.

A forum search for "indexOf countUntil" reveals just how many people have gotten caught in this trap over the years.

The full history of the name is recounted in this post by @schveiguy.

[rikkimax]

It may compile, but it may not give the result someone needs.

Sequentiality has to be defined to fit a person's use case.

And this is a key concept of what I described with offset and index, both of these have a natural order based upon the sequential nature of whole numbers.

Multiple dimensional arrays can have multiple sequences that are all valid, this makes them a key, not an index or offset.

[crazymonkyyy]

It may compile, but it may not give the result someone needs.
natural order

Its already the datastructures responsibility to define ranges in the natural ways to iterate

a tree will need both a depth first and breath first iteration, and if you think a 2d array needs a (always slower) colum based iteration, I geuss you should tell snar to add it to his todo list

tree.depthfirst.indexOf and tree.breathefirst.indexOf should be expected natural code

[jmdavis]

I agree we should not be conflating indexing and counting. That's slightly less critical when auto-decoding isn't a thing, but they're distinct concepts which imply completely different algorithmic complexity, and I think that we should keep them that way. And if there are places where we screwed that up in Phobos v2, then we should fix it in v3, not compound it.

[pbackus]

Just got another question in the community Discord where someone was asking for indexOf, and I had to point them to countUntil.

[LightBender]

IMO, this one has to change. The rest of the world uses different terms than we do for it. That's why one of the naming rules is to do an audit of the StdLib's of major languages to see what they did.

[pbackus]

Prefixes should be dropped from all names in std.meta.

Currently, three different styles of name are used in std.meta:

1. Prefixed with static (e.g., staticMap)
2. Prefixed with template (e.g., templateOr)
3. Capitalized with no prefix (e.g., Filter)

Most names currently use style (3). The remaining prefixed names should be changed to match.

[jmdavis]

All that's been ported in that camp thus far is staticMap, but I went with Map, which matches the Phobos naming convention for types.

Historically, I think that the problem came about, because while AliasSeqs usually contain types in the context of std.meta, they don't always, so there was debate over whether the naming convention for types should be followed, and we got a mess as a result.

However, they are almost always types, and the result is shorter, so IMHO, it makes sense to just go with #3.

[ntrel]

Yes, if it might hold a type then it should be capitalized. This is why AliasSeq is capitalized.

[crazymonkyyy]

all io naming conflicts should be resolved
dirEnties seems bad; and probably should be replaced with a "pathRange" and some sane defaults wrappers of "iterate over files in this folder", "all .jpg files", "~/.config" or "%appdata$/" depending on os

[pbackus]

Flag!"each" should be given a more descriptive name.

Currently, the callback passed to each may return Yes.each to continue iteration, or No.each to stop. This name is not meaningful, and makes it hard to tell which value corresponds to which behavior.

The ideal name for this flag would be Flag!"continue", but Yes.continue and No.continue are syntactically invalid, because continue is a keyword.

[pbackus]

If we really want to get rid of each, my proposed alternative would be a sink template that takes a callback and creates an output range from it. Then you could write:

someRange
    .doWhatever
    .copy(sink!fun); // instead of each!fun

With an improved output range interface (bool put(E e), which returns false on failure), this can even support early termination.

[rikkimax]

It would achieve the goal of each from what I have needed in the past, therefore no opinion from me.

[crazymonkyyy]

I use each when map doesnt work with void functions; I assumed theres a mathy style reason map doesn't have a void element type overload that's eager
if each was merged into map Id perfer that

[crazymonkyyy]

We should be using building blocks. count

I think a "last" would be a better building block
"iterate a range, until you find the end,(backtrack 1) return last valid state"
filter.last.index cumitivesum.filter(not nan).last

[ArthaTi]

all and any already do this.

only(1, 2, 3)
    .all!((a) {
        writeln(a);  // prints 1 and 2
        return a < 2;
    });

It's not an obvious solution, but it is one.

[crazymonkyyy]

allot of the meta range function got overly latinized names
iota instead of counter
retro instead of backwards
Transversal instead of takeColume

[pbackus]

std.algorithm.iteration.group should be made into an overload of uniq.

In Unix terms, what group does is analogous to uniq -c. In the same way that the uniq -c command is a variant of the uniq command, the group function should be a variant of the uniq function.

[crazymonkyyy]

several traits seems strange and should be combined, like I have to look up perimeters vs fields, instead of using fields for both functions and structs to get a tuple of types

[pbackus]

std.random.dice should be given a more descriptive name, or removed.

This function has nothing to do with dice. It samples from what Wikipedia calls a "categorical distribution", which is a special case of a multinomial distribution. The result of rolling a die, by contrast, has a uniform distribution.

[ichordev]

I agree with giving it a more descriptive name. There's a note in std.random with a good suggestion:

In future Phobos versions, this function might get renamed to something like weightedChoice to avoid confusion.

[Ogi-kun]

I think other std.random functions could also use more descriptive names.
uniform → randomUniform,
uniform01 → randomUniform01,
uniformDistribution → randomUniformDistribution,
choice → randomChoice (This one especially. I confuse choice and choose all the time),
dice → randomChoiceWeighted,
randomCover → asRandomShuffled (like e.g. asUpperCase).

Maybe uniformDistribution should be removed entirely, given that it’s not commonly used and is trivial to implement.

[pbackus]

In general I think we should avoid repeating the module name in the names of individual functions.

My suggestions:

• randomSample → sample
• choice → sampleOne (like takeOne and dropOne from std.range)
• randomCover → shuffled
• randomShuffle → shuffle

[ntrel]

std.traits should not use Tuple to mean a sequence. Instead I suggest we rename these templates as per dlang/phobos#6227.

[crazymonkyyy]

stdio.remove, mutation.remove

[ntrel]

std.algorithm.remove should be renamed removeIndex (dlang/phobos#6154 (comment)).

stdio.remove

Probably you meant std.file.remove. Possibly it could be renamed delete if that stopped being a keyword in the next edition. That would actually be a lot clearer than just seeing remove(someString).

[crazymonkyyy]

random.randomShuffle

[pbackus]

std.typecons.Nullable should be renamed to Optional or Maybe.

We get a steady stream of users in the forums and on Discord asking why Nullable!T can't be assigned or compared with null, why Nullable!(T*) has two different "null" states, etc. The source of this confusion is the name Nullable.

[crazymonkyyy]

there should probably be two nullables, one thats overly correct and verbose and one that simply appends a bool to a type

[ichordev]

I would prefer the name Opt, as in optional; Optional and Nullable are just so long that I would never use them.

That said, I really wish we just had the Swift ? syntax & pattern matching for optionals as a language feature...

[jmdavis]

Out of those, I'd go with Maybe, since it's shorter. I like the name Nullable in general, but I definitely like the idea of getting away from the issues related to folks wanting to do is null or getting confused about null arrays or pointers.

[pbackus]

std.functional.bind is too easily confused with Javascript's bind and C++'s std::bind. Its name should be changed to something without conflicting associations in other widely-used languages.

Some possibilities:

• unpack (from Python's * operator)
• spread (from Javascript's ... operator)
• splat (from Ruby's * operator)

Lisp and Scheme call this function apply, but D already has opApply, which associates a different meaning with that word.

[ichordev]

unpack has my vote there.

[schveiguy]

I'd also nominate walkLength for the axe. We have std.algorithm.searching.count, which does the same thing when not provided any target to search for, and is way way more intuitive.

[ntrel]

Makes sense, though walkLength takes an optional upTo argument.
https://dlang.org/phobos/std_range_primitives.html#walkLength

This works though, and is clearer: InfiniteRange().take(4).count.

[SRKX0A]

One addition that I think might be useful would be to change std.functional.not to negate instead. Would be related to allowing keyword forms like and, or, and not, a la this post: https://forum.dlang.org/thread/hlxedfavwmivxllxmzuw@forum.dlang.org.

[Ogi-kun]

I think that std.compiler.name should be either renamed to compilerName, or redefined as a static member of std.compiler.Compiler struct. Same with other variables in this module.

[Ogi-kun]

Also, version_major/version_minor and D_major/D_major from the same module don’t follow D naming conventions. Should be renamed to versionMajor/versionMinor and dMajor/dMinor. (Or maybe dlangMajor/dlangMinor?)

[pbackus]

Variant should be renamed to Any.

[ichordev]

I even forgot that’s what ‘variant’ was for because of the confusing name. I was looking for something like that!

[dukc]

From std.bitmanip, there's no reason for the "native" words in the endian functions. aFloat.toLittleEndian and byteQuad.littleEndianTo!float would work just as well. I know Átila already hates the present names and doesn't need convincing but putting it here in case this thread will be used as a sort of memo list.

[ArthaTi]

std.conv.text is too general for me. It's not a verb, but a noun that may easily be confused with a struct member. concatenate would be more descriptive of what it does, but maybe a bit awkward.

[ArthaTi]

True, although I do think it's still too general and it's easy to confuse. E.g. is message.text a field of message or will it just call message.toString?

[andrey-zherikov]

May be toText?

[atilaneves]

I think text is not just fine but pretty good.

[rikkimax]

I'm happy with text also.

But if we had to change it I'd go for asText or asString.

I use asX to mean some sort of conversion with memory allocation taking place into another form.

[ArthaTi]

That would be good. Note that at least in case of std.uni, asUpperCase is the non-allocating, range variant, and toUpper is the allocating one. I think toText would work well.