Slice

public protocol Slice[T]

Shared read-only protocol for contiguous collections.

Slice[T] is the contiguous-collection counterpart to Str in std.text: one kernel method (asSlice), all read-only logic in a protocol extension. Both Array[T] and ArraySlice[T] conform, so generic code constrained to S: Slice[T] accepts either without overloading.

Examples

func sum[S](s: S) -> Int64 where S: Slice[Int64] {
    var total: Int64 = 0;
    for elem in s { total = total + elem }
    total
}
sum([1, 2, 3]);              // works with Array
sum([1, 2, 3].asSlice());    // works with ArraySlice

Properties

public var count: Int64 { get }

Element count. O(1).

Examples

[1, 2, 3].count;  // 3
[].count;          // 0

public var indices: Range[Int64] { get }

Half-open range 0..<count.

Examples

[10, 20, 30].indices;  // 0..<3

public var isEmpty: Bool { get }

true when count == 0.

Examples

[].isEmpty;   // true
[1].isEmpty;  // false

Methods

public func all(where: (T) -> Bool) -> Bool

true when every element satisfies predicate. O(n).

Short-circuits on the first failure. Vacuously true for empty collections.

Examples

[2, 4, 6].all(where: { it % 2 == 0 });  // true
[2, 3, 6].all(where: { it % 2 == 0 });  // false

public func any(where: (T) -> Bool) -> Bool

true when at least one element satisfies predicate. O(n).

Short-circuits on the first match. Always false for empty collections.

Examples

[1, 2, 3].any(where: { it > 2 });  // true
[1, 2, 3].any(where: { it > 5 });  // false

public func asPointer() -> Pointer[T]

Pointer to the first element. The pointer aliases the collection's buffer; do not outlive the source or mutate through it.

Safety

Reading past count is undefined behavior.

func asSlice() -> ArraySlice[T]

public func binarySearch(T) -> Int64?

Binary search for element. Returns its index or None. O(log n).

When duplicates exist, which index is returned is unspecified.

Safety

The collection must be sorted in ascending order. Calling on unsorted data won't crash but may produce false negatives.

Examples

[1, 2, 3, 4, 5].binarySearch(3);  // Some(2)
[1, 2, 3, 4, 5].binarySearch(6);  // None

public func chunks(of: Int64) -> ChunksView[T]

Multi-pass lazy view over non-overlapping size-sized chunks.

The trailing chunk may be shorter than size. Multi-pass: query count, index with view.get(i), and iterate repeatedly without re-creating the view.

Errors

Panics if size <= 0.

Examples

let v = [1, 2, 3, 4, 5].chunks(of: 2);
v.count;          // 3
v.get(2);          // ArraySlice[5]
for c in v { ... }

public func compactMap[U]((T) -> Optional[U]) -> Array[U]

Maps every element through transform, dropping .None results. O(n).

Examples

["1", "x", "3"].compactMap { Int64.parse(it) };  // [1, 3]

public func contains(T) -> Bool

true if the collection contains element. O(n).

Linear scan; short-circuits on the first match.

Examples

[1, 2, 3].contains(2);  // true
[1, 2, 3].contains(5);  // false

public func countItems(where: (T) -> Bool) -> Int64

Number of elements for which predicate is true. O(n).

Examples

[1, 2, 3, 4, 5].countItems(where: { it % 2 == 0 });  // 2

public func drop(first: Int64) -> ArraySlice[T]

Returns a slice with the first count elements skipped. O(1).

Complement of prefix.

Errors

Panics if count > self.count.

Examples

[1, 2, 3, 4, 5].drop(first: 2);  // ArraySlice[3, 4, 5]

public func drop(last: Int64) -> ArraySlice[T]

Returns a slice with the last count elements skipped. O(1).

Complement of suffix.

Errors

Panics if count > self.count.

Examples

[1, 2, 3, 4, 5].drop(last: 2);  // ArraySlice[1, 2, 3]

public func ends[__opaque_0](with: __opaque_0) -> Bool where __opaque_0: Slice[T]

true if the trailing elements match suffix. O(k) where k is the suffix length. Accepts any Slice[T] conformer.

Examples

[1, 2, 3].ends(with: [2, 3]);  // true
[1, 2, 3].ends(with: [1, 2]);  // false
[1, 2, 3].ends(with: []);       // true (vacuous)

mutating func ensureUnique()

public func filter(where: (T) -> Bool) -> Array[T]

Returns a new array containing every element matching predicate. O(n). Result size is unknown; uses geometric growth.

Examples

[1, 2, 3, 4].filter(where: { it % 2 == 0 });  // [2, 4]

public func first() -> T?

First element, or .None for an empty collection. O(1).

Read-only — to remove the first element from an Array, use popFirst().

Examples

[1, 2, 3].first();  // Some(1)
[].first();          // None

public func first(where: (T) -> Bool) -> T?

First element matching predicate, or None. O(n).

Examples

[1, 2, 3, 4, 5].first(where: { it > 3 });  // Some(4)

public func firstIndex(where: (T) -> Bool) -> Int64?

Index of the first element matching predicate, or None. O(n).

Short-circuits on the first match. For value-based search on Equatable collections, use firstIndex(of:).

Examples

[1, 2, 3, 4, 5].firstIndex(where: { it > 3 });   // Some(3)
[1, 2, 3].firstIndex(where: { it > 10 });         // None

public func firstIndex(of: T) -> Int64?

Index of the first element equal to element, or None. O(n).

Examples

[1, 2, 3, 2].firstIndex(of: 2);  // Some(1)
[1, 2, 3].firstIndex(of: 5);      // None

public func flatMap[U]((T) -> Array[U]) -> Array[U]

Maps every element through transform and concatenates the results into one flat array. O(n + total_output).

Examples

[1, 2, 3].flatMap { [it, it * 10] };  // [1, 10, 2, 20, 3, 30]

public func format(into: mutating StringBuilder, FormatOptions)

Renders as "[e1, e2, ...]". Empty collections render as "[]".

Examples

[1, 2, 3].format();  // "[1, 2, 3]"
[].format();          // "[]"

public func isEqual(to: Self) -> Bool

Element-wise equality. O(n).

Short-circuits on the first mismatch. Order matters.

Examples

[1, 2, 3].isEqual(to: [1, 2, 3]);  // true
[1, 2, 3].isEqual(to: [3, 2, 1]);  // false

public func isSorted() -> Bool

true if elements are in non-decreasing order. O(n).

Equal adjacent elements are allowed. Empty and single-element collections are vacuously sorted.

Examples

[1, 2, 3].isSorted();  // true
[1, 3, 2].isSorted();  // false
[1, 1, 1].isSorted();  // true
[].isSorted();          // true

public func isValidIndex(Int64) -> Bool

true if index is in [0, count).

Examples

[10, 20, 30].isValidIndex(2);   // true
[10, 20, 30].isValidIndex(3);   // false
[10, 20, 30].isValidIndex(-1);  // false

public func last() -> T?

Last element, or .None for an empty collection. O(1).

Read-only — to remove the last element from an Array, use pop().

Examples

[1, 2, 3].last();  // Some(3)
[].last();          // None

public func last(where: (T) -> Bool) -> T?

Last element matching predicate, or None. O(n).

Examples

[1, 2, 3, 2, 1].last(where: { it > 1 });  // Some(2)

public func lastIndex(where: (T) -> Bool) -> Int64?

Index of the last element matching predicate, or None. O(n).

Scans from the back; short-circuits on the first match.

Examples

[1, 2, 3, 2, 1].lastIndex(where: { it == 2 });  // Some(3)

public func lastIndex(of: T) -> Int64?

Index of the last element equal to element, or None. O(n).

Examples

[1, 2, 3, 2].lastIndex(of: 2);  // Some(3)
[1, 2, 3].lastIndex(of: 5);      // None

public func map[U]((T) -> U) -> Array[U]

Maps every element through transform into a new array. O(n).

Pre-sizes the result buffer to self.count, so no growth steps. For the lazy version that fuses into a chain, use iter().map { ... }.

Examples

[1, 2, 3].map { it * 2 };       // [2, 4, 6]
[1, 2, 3].map { it.format() };  // ["1", "2", "3"]

public func max() -> T?

Largest element, or None if empty. O(n).

Ties go to the first occurrence.

Examples

[3, 1, 4].max();  // Some(4)
[].max();          // None

public func min() -> T?

Smallest element, or None if empty. O(n).

Ties go to the first occurrence.

Examples

[3, 1, 4].min();  // Some(1)
[].min();          // None

public func prefix(Int64) -> ArraySlice[T]

Returns a slice over the first count elements. O(1).

Errors

Panics if count > self.count.

Examples

[1, 2, 3, 4, 5].prefix(3);  // ArraySlice[1, 2, 3]
[1, 2].prefix(0);            // empty slice

public func reversed() -> ReversedView[T]

Multi-pass lazy reversed view. Iterates back-to-front and supports indexed access in O(1).

Examples

let v = [1, 2, 3].reversed();
v.first();        // Some(3)
v.toArray();       // [3, 2, 1] — eager copy

public func sorted() -> Array[T]

Returns a new sorted array; original unchanged. O(n log n).

Examples

let arr = [3, 1, 4, 1, 5];
arr.sorted();  // [1, 1, 3, 4, 5]
// arr is still [3, 1, 4, 1, 5]

public func split(where: consuming (T) -> Bool) -> ArraySplitWhereView[T]

Multi-pass lazy view over the segments produced by splitting at each element matching predicate. Matching elements are dropped.

Examples

let v = [1, -1, 2, 3, -1, 4].split(where: { it < 0 });
for seg in v { ... }

public func split(T) -> ArraySplitView[T]

Multi-pass lazy view over the segments produced by splitting on each occurrence of separator. Separators are dropped; empty runs between adjacent separators are preserved.

Use view.toArray() to materialize all segments into an owned Array[ArraySlice[T]].

Examples

let v = [1, 0, 2, 0, 3].split(separator: 0);
for seg in v { ... }            // ArraySlice[1], ArraySlice[2], ArraySlice[3]
v.toArray();                     // eager: 3 segments

[1, 2, 3].split(separator: 0).toArray();
// [ArraySlice[1, 2, 3]] — separator not found, single segment

public func starts[__opaque_0](with: __opaque_0) -> Bool where __opaque_0: Slice[T]

true if the leading elements match prefix. O(k) where k is the prefix length. Accepts any Slice[T] conformer.

Examples

[1, 2, 3].starts(with: [1, 2]);     // true
[1, 2, 3].starts(with: [2, 3]);     // false
[1, 2, 3].starts(with: []);          // true (vacuous)

public func suffix(Int64) -> ArraySlice[T]

Returns a slice over the last count elements. O(1).

Errors

Panics if count > self.count.

Examples

[1, 2, 3, 4, 5].suffix(2);  // ArraySlice[4, 5]

public func unique() -> Array[T]

Returns a new array with duplicates removed, preserving first-occurrence order. O(n²).

For the mutating variant on Array, see removeDuplicates().

Examples

[1, 2, 1, 3, 2, 4].unique();  // [1, 2, 3, 4]

public func windows(of: Int64) -> WindowsView[T]

Multi-pass lazy view over overlapping size-sized sliding windows.

Adjacent windows overlap by size - 1 elements. Empty when the source has fewer than size elements.

Errors

Panics if size <= 0.

Examples

let v = [1, 2, 3, 4].windows(of: 2);
v.count;          // 3
for w in v { ... }

Subscripts

public subscript[I](I) -> I.SeqOutput { get set }

public subscript[I](checked: I) -> I.SeqOutput? { get }

public subscript[I](unchecked: I) -> I.SeqOutput { get set }

public subscript[I](clamped: I) -> I.SeqClampedOutput { get set }

public subscript[I](wrapped: I) -> I.SeqWrappedOutput { get set }

ImplementsIterable

Associated Types

type Item

The element type that iteration yields.

type TargetIterator

The concrete iterator type returned by iter(). Constrained so TargetIterator.Item matches Self.Item.

Methods

public func iter() -> ArraySliceIterator[T]

Forward iterator over the elements.

Examples

for item in [1, 2, 3] { ... }

Defined in lang/std/collections/slice.ks