Fast, dangerous, mutable vs safe, slow, immutable.

[dragonfly-ai]

The S.L.A.S.H. (Scala Linear Algebra & Statistics Hacks) library supports two broad kinds of operations:

1. Mutable: fast and light but dangerous.
2. Immutable: safe but slow and heavy.

To improve accessibility, we want to find a way to clearly delineate the category of each and every operation.

For vector operations like += and + Scala provides natural ways to cue users about whether the operation mutates or copies data. However, ambiguity pools up around named operations like def clamp(min:Double, MAX:Double), def min(minimum:Double), or def MAX(maximum:Double).

Should we follow the example of Scala collections? That splits the Vector and Matrix types into two packages: mutable and immutable. This approach drastically increases complexity; even under a condition of total separation of these two packages, it doubles the number of types to document, test, and maintain. However, without total separation, complexity increases exponentially wherever these two families of types interact. For example, consider addition between a mutable vector and an immutable vector:

val mv:mutable.Vec[3] = mutable.Vec[3](1, 2, 3) 
val iv:immutable.Vec[3] = immutable.Vec[3](4, 5, 6)

val v = mv + iv // is v mutable or immutable?

What type should the result have: mutable.Vec[3] or immutable.Vec[3]? What's more, now the + operation has to somehow support 4 cases: mv + mv, iv + iv, mv + iv, iv + mv, where it used to only support 1: v + v.

Rather, what if we take the hint from ArrayOps? ArrayOps.sort mutates data in place and ArrayOps.sorted yields a sorted copy. Can we rely on the "ed" suffix to designate all of the immutable operations?
It seems reasonable to provide mutable clamp alongside immutable clamped, but that implies mutable min & MAX beside immutable mined & MAXed. In particular, the word "mined" can mean a lot of things, but none of them imply: "Returns a copy of this vector with all elements greater than or equal to a specified minimum."

Instead of an English language suffix, the documentation in the Julia programming language proposes a convention of marking unsafe methods that may mutate their parameters with an exclamation point:

"Functions can modify (mutate) the contents of the objects their arguments refer to. (The names of functions which do this are conventionally suffixed with '!'.)"

function f!(x); x[:] .+= 1; end

https://docs.julialang.org/en/v1/base/base/#Keywords

The exclamation point might not suit S.L.A.S.H. which already defines ! as a call to the factorial method, but maybe some other symbol?

More generally, if we decide to label operations as unsafe/mutable vs. safe/immutable, should we consider one as default and mark the other? As an analogy, should we force users who prioritize performance to read warning labels every time they move or should we require the people who put safety first to put soft padding on everything?

Alternatively, since all of these operations take the form of extension methods, maybe we should just separate the mutable extensions from the immutable ones? One anticipates all sorts of naming collisions in scopes that may need to use both.

Suppose, instead, we create S.L.A.S.H as a mutable only library, then create another one that wraps it with immutable/safe abstractions?

Should we better just not worry about any of this?

How would you address this accessibility concern?

[JD557]

Just to add, you might also want to consider what's the return type of the mutable variants

Namely Unit vs this.type. Unit makes the API a bit more cumbersome to use, but in the flip side it makes it pretty obvious that the method is mutable.

[dragonfly-ai]

Oh yeah! I knew I forgot something. Thanks!

Great point! In your opinion, is the distinction so important that we should deliberately sabotage usability just to emphasize it?

[JD557]

I personally prefer this.type (and if that's the function signature at least it's a bit obvious that it's going to mutate).
However, I guess with scala.util.chaining returning Unit is not as bad as could be.

[Quafadas]

First time I've seen scala.util.chaining ... and I'd certainly support giving that a go, personally.

[JD557]

Another alternative that I just remember is to have something like (don't take this example too literally):

trait Vector2D {
  def getX(): Double
  def getY(): Double
}

trait MutVector2D extends Vector2D {
  def setX(x: Double): this.type
  def setY(y: Double): this.type
}

This is closer to what Rust does with mut, namely all variables might be mutable (you don't have the same guarantees as Scala's stdlib), but you "need permission" to mutate them.
For example, if you see some functions like:

def foo(vec: Vector2D): Double
def bar(vec: MutVector2D): Double

You know that foo for sure won't mutate the vector, while bar probably will.

[dragonfly-ai]

This idea is new to me! Vec[N] is just an alias for Array[Double] on JVM and Native and Float64Array in JS, so we'd have to do this with opaque types instead of inheritance, but it could work and it wouldn't even incur any performance costs.

Thanks!

[Quafadas]

My own vote, is to either

• follow Julia's convention, which appends an obvious character to the end of mutuable method calls.
• return unit and lean into the scala.util.chaining concept, which I actually wasn't aware of until this discussion!

e.g. i.e.
val x = min(vec, 2.0) I is immutable.
min(vec, 2.0) to be mutable and return Unit.
or
val mutated = min!(vec, 2.0) to be mutable and return the mutated vector.

When we discussed this in the past however, Unit potentially prevented function chaining, e.g.

val chained = vec.times(1.0).add(2.0) wouldn't work under that convention, as .times(1.0), would return unit.

It remains my preference .... with @JD557 suggestion of the scala.util.chaining operator appearing to be a great solution, if we're willing to write pipe everywhere :-). I personally am.

Would be the equivelant I guess. From what I can see, and designed against exactly this sort of use case... I'd support leaning into re-using that work in stdlib. My only real preference is that it's very clear at the callsite, which flavour of mutable vs immutable is being used.

[dragonfly-ai]

Come to think of it, this looks really weird:

v0 + v1 += v2

I'll change return types to Unit on mutating operations and experiment with splitting the mutable and immutable extension methods into separate packages.