iter

type CanBackward interface {
	IterCanBackward()
}

type CanIndexFromEnd interface {
	IterCanIndexFromEnd()
}

type CanSkip interface {
	IterCanSkip()
}

type Core[Elem any] interface {
	// Nth returns the n-th element, the returned bool value indicates whether
	// the element exists.
	//
	// It is required to support the 1-step [0, end) range as input sequence,
	// in which case Nth(int) MUST function exactly the same way as Next() would.
	//
	// Caller SHOULD assume the implementation only supports the iteration
	// style implied by the above requirement:
	//
	//	for i := 0; ; i++ {
	//		elem, ok := iter.Nth(i)
	//		if !ok {
	//			break
	//		}
	//
	//		_ = elem
	// 	}
	//
	// Following features are optional:
	//
	//   - Negative n (index from end)
	//   - Step more than 1 (calling with non-consecutive n)
	//   - Backward iteration (calling with n from high to low)
	//   - Arbitrary iteration (calling with unordered n)
	//
	// Rationales choosing Nth(int) instead of Next() as core iterator function:
	//
	//   - Passing an integer argument is cheap (a register in ABIInternal).
	//   - Nth(int) is Next() when called with a sequence of ascending numbers.
	//     (per implementation requirement)
	//   - Nth(int) may skip unwanted elements without extraneous call.
	//   - Nth(int) may step-backward with no external caching.
	//   - Nth(int) is more friendly to slices.
	//   - Nth(int) may be used with binary search to get the total length
	//     of the iterator (when unknown).
	//   - Stateless values can use the integer passed in to decide when to
	//     stop iteration, otherwise an additional Next() style iterator
	//     should be implemented.
	Nth(int) (Elem, bool)
}

type CoreEx[Arg, Elem any] interface {
	NthEx(Arg, int) (Elem, bool)
}

type Divisible[Self any] interface {
	// SliceFrom returns a sub-iterator by slicing at the `start` of current
	// itertor, it resembles the native `x[start:]` operation.
	SliceFrom(start int) Self
}

type DivisibleEx[Arg, Self any] interface {
	SliceFromEx(arg Arg, start int) Self
}

type Finite interface {
	// Len returns the count of elements a iterator may produce.
	Len() int
}

type FiniteEx[Arg any] interface {
	LenEx(Arg) int
}

type Func[Elem any] func(int) (Elem, bool)

type FuncEx[Arg, Elem any] func(Arg, int) (Elem, bool)

type Interface[T, Self any] interface {
	Core[T]
	Divisible[Self]
	Finite
}

type InterfaceEx[Arg, Elem, Self any] interface {
	CoreEx[Arg, Elem]
	FiniteEx[Arg]
	DivisibleEx[Arg, Self]
}

type MarkCanBackward struct{}

type MarkCanIndexFromEnd struct{}

type MarkCanSkip struct{}

type SliceIter[Elem any] []Elem

type SliceIterEx[Elem any, T []Elem] int

type SliceReverseIter[Elem any] []Elem

type SliceReverseIterEx[Elem any, T []Elem] int