factor
sequence words that mutate should have ! in their names, e.g. set-nth!
List them here:
- [ ] set-nth
- [ ] ?set-nth
- [ ] change-nth
- [ ] change-nths
- [ ] change-at
- [ ] change
- [ ] set-length
- [ ] delete-all
- [ ] delete-slice
- [ ] exchange
- [ ] push
- [ ] push-all
- [ ] shorten
- [ ] set-at
- [ ] set-at*
- [ ] pop
- [ ] pop*
- [ ] matrix-set-nth
- [ ] matrix-set-nths
shorten doesn't have a "side effects" section in its documentation, either, but based on the description it should (and should be named shorten!).
This also applies to assocs, e.g. set-at mutates the assoc and there is no non-mutating version.
As for seqs: pop and pop* should also be on the list.
This also applies to assocs, e.g.
set-atmutates the assoc and there is no non-mutating version.
The persistent.assocs has the poorly named new-at word.
Yeah, my expectation there would be that set-at is the non-mutating version and is defined for both assocs and passocs, and set-at! is the mutating one and is not defined for passocs.
Minor background, though -- If persistent data structures were more pervasive, then those two types of words would make more sense. As it is, almost nothing is using the persistent versions, and a "clone set-at" version isn't as useful. So perhaps part of this would be to improve the persistent versions.
- [ ]
matrix-set-nthand - [ ]
matrix-set-nths
both modify the input matrix. also, the { $side-effects } markup element is nice for this.
i swore i had !s on these, but i guess not :')
@catb0t feel free to just mention them, and i'll edit the words into the main list.
See also #2711
Although consistency is to be preferred, I think most ! words mutate an existing object, in case a similar word exists that makes a new copy. Words with set- and change- don't have counter-parts that are read-only. Words with delete- strongly suggest modification already (else remove- would be more appropriate?). In my opinion it doesn't make sense, and makes words less readable to forcefully add ! to these words. It's enough to be able to quickly see which words make copies of words in the description of the word.
Compare this with the conventions for modifying symbols: set- words modify, and no set- is an implicit read. No ! are involved there.
most ! words mutate an existing object, in case a similar word exists that makes a new copy
This was mentioned on the discord as well, and I don't think it's a compelling argument against consistency; I think it might be an argument that mutation is the default in Factor, and thus the ! should be assumed, but in that case I think the ! suffix should be abandoned entirely and some other mechanism found for denoting functions that return a modified copy rather than mutating their inputs.
My instinct is to go with marking mutation with ! because (a) that's what I'm used to from other languages and (b) I consider mutation an inherently more risky operation and thus feel that it should always be the "marked" version of the operation, even if mutation functions are the majority and some have no corresponding non-mutating version, but I would also be ok with, say, mutating functions are unmarked and functions that return a modified copy have a -copy suffix or something. The point is not to be surprised when some hazardous functions are marked with ! and some are not.
Compare this with the conventions for modifying symbols: set- words modify, and no set- is an implicit read. No ! are involved there.
It's a different convention everywhere you look, though! Like, you can look at one corner of the language and say that "set- is mutating and no set- is non-mutating", but look at a different vocabulary, even in core, and the convention might instead be a change- prefix, or a -set- infix, or a ! suffix, or a clear- prefix, or or or. I think both this and #2711 are both biting at the same underlying issue, which is that learning the nomenclature of a given vocabulary or a given datatype doesn't give you nearly as much of a handle as you might expect on others because there is very little consistency between them.
I'm not in favor of having a set-foo that clones and modifies and a set-foo! that modifies.
I feel like english words set-, change-, update- are sufficient to indicate mutation.
I don't think nth! is a good name for a thing that changes the value at an index, however.
what is the overall consensus on renaming? seems to be 3 for and 2 against from a skim of this thread. I think i agree with avoiding renaming here. but maybe we should have it elaborated upon in the Conventions article.