This module features several types and functionality related to linear sequences and linear indexing.

The most useful from an ergonomics perspective is probably StridedSlice which is like a HSlice but with a stride (step). This is akin to Python's general slicing like xs[start:stop:step], or its range(start,stop,step) function.

The primary way to construct strided slices is with the @: operator, which can be applied in several ways.

Example:

import strides

let greet = "hello world"

# The obvious way, as a strided slice:
assert greet[ 2 .. 8 @: 3 ] == "l r"

# As a prefix: assumes the whole length.
assert greet[ @: 2 ] == "hlowrd"
assert greet[ @: -1 ] == "dlrow olleh"

# As a length + step: shorthand for `0 ..< length` or `length-1 .. 0`
assert greet[ 5 @: 1 ] == "hello"
assert greet[ 5 @: 2 ] == "hlo"
assert greet[ 5 @: -1 ] == "olleh"

assert greet[greet.len @: 3] == greet[@:3]

Given a length (for example of the container being sliced) we can "resolve" a StridedSlice into a LinearSegment (a finite LinearSequence). A LinearSegment_ consists of the fields (initial, stride, count) which should all be integers.

There are two ways to resolve a slice: the Nim way (hard slices) and the Python way (soft slices).

Standard Nim behavior is for slices to go out of bounds. For example "test"[0 ..< 20] will trigger an exception. Whereas in Python "test"[0:20] will work and simply return "test".

The first behavior is met with the ^! operator which functions very similar to ^^. It merely translates BackwardsIndex and StridedIndex into integers, not doing any bounds checking.

The second way is with the operator ^? which does soft slicing. It works the same way as ^! but automatically constrains the slice so it doesn't go out of bounds.

By default, and for convenience(?), containers use ^? to mimic Python behavior when using strided slices specifically (might change?), but regular slices (HSlice) still triggers out of bounds.

Example:

import strides

# ^! resolves the strided slice into a linear segment given a length.
let linseg1 = (1 .. 100 @: 5) ^! 10
assert linseg1 is LinearSegment
assert linseg1.len == 20

# ^? does the same but constrains the linear segment to `0 ..< length`.
let linseg2 = (1 .. 100 @: 5) ^? 10
assert linseg2.len == 2 # constrained to only cover [1, 6]

let text = "aAbBcCdDeEfF"

# "Hard" slices trigger out of bounds:
# text[ (0 .. 100 @: 2) ^! 12 ] --> exception!

# But this works:
assert text[ (0 .. 100 @: 2) ^? 12 ] == "abcdef"

Example:

import strides
type MyList = object

proc len*(_: MyList): int = 69

proc `[]`*(lst: MyList, idx: AnyStrided): auto =
  when idx isnot LinearSegment:
    let idx = idx ^? lst.len # or `^!` for slices that trigger out of bounds.

  assert idx is LinearSegment

  # ...