int.modulo/int.remainder/% confusion

[jrunning]

I was surprised to find that int.modulo returns different output than the % operator, until I noticed that gleam/int also defines int.remainder.

import gleam/int

pub fn main() {
  echo -54 % 24 // -6
  echo int.remainder(-54, 24) // 18
  echo int.modulo(-54, 24) // -6
}

Fair enough; I had forgotten this. However, the docs for both int.modulo and int.remainder say:

Most the time you will want to use the % operator instead of this function.

This is a little confusing, since only int.remainder has the same behavior as %. I think the docs could spend a few more words on the distinction between these two operations, especially since % behaves differently than it does in many programming languages.

[inoas]

During my research back then I found Gleam's behaviour to not only be in line with what Erlang does (though there named rem) but also what most other languages do:

https://github.com/gleam-lang/stdlib/pull/342/files#diff-0228a35b489bf7c2df315a58ccbe57915ebfccff18cf8b60ca2622db98a5bc44R533-R606