Unify the API of Nim[draft]

[ringabout]

Background

As Nim language becomes more mature, some APIs need to be redesigned. some legacy modules has many error-prone APIs and are hard to use. We need an API specification。

Motivate example

proc runeSubStr*(s: string, pos: int, len: int = int.high): string =
  ## Returns the UTF-8 substring starting at code point ``pos``
  ## with ``len`` code points.
  ##
  ## If ``pos`` or ``len`` is negative they count from
  ## the end of the string. If ``len`` is not given it means the longest
  ## possible string.

In unicode module, runeSubStr is very buggy. pos can be negative, len can be negative. That's a terrible API and brings many confusions. We can rely on ^ to get the right result or only allow natural position.

see nim-lang#17768

Not finished .......

[timotheecour]

pos can be negative, len can be negative. That's a terrible API and brings many confusions.

agreed, and it hides bugs (note that python has similar behavior, it's a poor-man's way around missing D's opDollar, see RFC in #73)

"Unify the API of Nim" is a bit broad and not very actionable (more generally we need a sets of do's and dont's along with rationale, expanding on the guidelines in contributing.rst + nep1.rst, that gets updated with latest features of the language).

But let's refocus this issue on just dealing with APIs involving a container + indexes pointing inside it.

it's not that simple though, what do you suggest concretely, that works with c, js, vm?

IMO this is impossible (in the general case of mutable openArray's) until we fix nim-lang#15952 (comment) (but that issue is very fixable and very worth fixing)

[ringabout]

let's refocus this issue on just dealing with APIs involving a container + indexes pointing inside it.

I agree

[ringabout]

agreed, and it hides bugs (note that python has similar behavior,

even worse, they introduce many bugs which are hard to fix if you look at the implementation.

[timotheecour]

for this specific example how about:

proc runeSlice*(s: openArray[char], maxCodePoints = int.high, fromLeft = true): Slice[int]

(and then user can reuse strbasics.setSlice to get a string if they want)

[ringabout]

not fit