Julia function naming: When should I append a bang?

Question

The Julia style guide says that functions which "modify their arguments" should have their name end on a !.

However, what about:

1. functions that do modify their arguments, but return them to their original state before returning?

2. functions that return a Task which modifies the argument when executed?

3. functions that return such a Task, but when it is done, the arguments will have been restored to their original states?

Should their names end on a !?

---

As an example, consider this module for finding exact covers using Knuth's Dancing Links Algorithm. It implements a type CoverSet that can be populated with the subsets and then queried for the first exact cover:

set = CoverSet()
push!(set, [1, 2])
push!(set, [2, 3])
push!(set, [3, 4])
push!(set, [4, 1])

find_exact_cover(set) # returns [1, 3]

The find_exact_cover function temporarily modifies the data in set while searching for a solution, but by the time find_exact_cover returns, set will be in its original state. Should it be named find_exact_cover! instead?

Similarly, exact_cover_producer returns a Task that produces all exact covers, but when that Task is done, set will have been restored:

for cover in exact_cover_producer(set)
  println(cover) # prints [1,3] and [2,4]
end
# By now, set is restored.

Should it be exact_cover_producer!?

---

I am aware that this might be considered subjective, so let me clarify what I am asking for: I would like to know whether there is a convention on this in the Julia community, and ideally also examples from the standard library or any packages that use either style.

Answer 1

See e.g. the discussion at Julia commit e7ce4cba44fa3b508fd50e0c3d03f6bc5a7a5032: the current convention is that a function is mutating and hence has a ! appended if it changes what one of its arguments would be == to.

(But there is some justification for slightly broader definitions as well; see the abovementioned discussion.)