slice

An in-place permutation iterator.

Removes the first n elements (elems) from a slice of slices, spanning inner slices and dropping empty ones.

If elems is out of bounds (more than the total) this will trigger a bounds check.

Example:

import "core:fmt"
import "core:slice"

advance_slices_example :: proc() {
	slices := [][]byte {
		{1, 2, 3, 4},
		{5, 6, 7},
	}

	fmt.println(slice.advance_slices(slices, 4))
}

Output:

[[5, 6, 7]]

Searches the given slice for the given element. If the slice is not sorted, the returned index is unspecified and meaningless.

If the value is found then the returned int is the index of the matching element. If there are multiple matches, then any one of the matches could be returned.

If the value is not found then the returned int is the index where a matching element could be inserted while maintaining sorted order.

For slices of more complex types see: binary_search_by

Example:

/*
Looks up a series of four elements. The first is found, with a
uniquely determined position; the second and third are not
found; the fourth could match any position in `[1, 4]`.
*/

index: int
found: bool

s := []i32{0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55}

index, found = slice.binary_search(s, 13)
assert(index == 9 && found == true)

index, found = slice.binary_search(s, 4)
assert(index == 7 && found == false)

index, found = slice.binary_search(s, 100)
assert(index == 13 && found == false)

index, found = slice.binary_search(s, 1)
assert(index >= 1 && index <= 4 && found == true)

Searches the given slice for the given element. If the slice is not sorted, the returned index is unspecified and meaningless.

If the value is found then the returned int is the index of the matching element. If there are multiple matches, then any one of the matches could be returned.

If the value is not found then the returned int is the index where a matching element could be inserted while maintaining sorted order.

The array elements and key may be different types. This allows the filter procedure to compare keys against a slice of structs, one struct value at a time.

Returns:

• index: int
• found: bool

Turn a bit_set[E] into a []E e.g.: sl := slice.bitset_to_enum_slice(flag_buf[:], bs)

Turn a bit_set[E] into a []E, allocates e.g.: sl := slice.bitset_to_enum_slice(bs)

Turn a pointer and a length into a byte slice.

copies a slice into a new slice

copies slice into a new dynamic array

Free the state allocated by make_permutation_iterator.

Inputs:

• iter: The iterator created by make_permutation_iterator.
• allocator: The allocator used to create the iterator. (default is context.allocator)

Turn a []E into bit_set[E] e.g.: bs := slice.enum_slice_to_bitset(my_flag_slice, rl.ConfigFlags)

Convert a pointer to an enumerated array to a slice of the element type

Turn a pointer and a length into a slice.

Converts slice into a dynamic array without cloning or allocating memory

Searches the given slice for the given element in O(n) time.

If you need a custom search condition, see linear_search_proc

Inputs:

• array: The slice to search in.
• key: The element to search for.

Returns:

• index: The index i, such that array[i] is the first occurrence of key in array, or -1 if key is not present in array.

Example:

index: int
found: bool

a := []i32{10, 10, 10, 20}

index, found = linear_search_reverse(a, 10)
assert(index == 0 && found == true)

index, found = linear_search_reverse(a, 30)
assert(index == -1 && found == false)

// Note that `index == 1`, since it is relative to `a[2:]`
index, found = linear_search_reverse(a[2:], 20)
assert(index == 1 && found == true)

Searches the given slice for the first element satisfying predicate f in O(n) time.

Inputs:

• array: The slice to search in.
• f: The search condition.

Returns:

• index: The index i, such that array[i] is the first x in array for which f(x) == true, or -1 if such x does not exist.

Searches the given slice for the given element in O(n) time, starting from the slice end.

If you need a custom search condition, see linear_search_reverse_proc

Inputs:

• array: The slice to search in.
• key: The element to search for.

Returns:

• index: The index i, such that array[i] is the last occurrence of key in array, or -1 if key is not present in array.

Example:

index: int
found: bool

a := []i32{10, 10, 10, 20}

index, found = linear_search_reverse(a, 20)
assert(index == 3 && found == true)

index, found = linear_search_reverse(a, 10)
assert(index == 2 && found == true)

index, found = linear_search_reverse(a, 30)
assert(index == -1 && found == false)

// Note that `index == 1`, since it is relative to `a[2:]`
index, found = linear_search_reverse(a[2:], 20)
assert(index == 1 && found == true)

Searches the given slice for the last element satisfying predicate f in O(n) time, starting from the slice end.

Inputs:

• array: The slice to search in.
• f: The search condition.

Returns:

• index: The index i, such that array[i] is the last x in array for which f(x) == true, or -1 if such x does not exist.

Make an iterator to permute a slice in-place.

Allocates Using Provided Allocator

This procedure allocates some state to assist in permutation and does not make a copy of the underlying slice. If you want to permute a slice without altering the underlying data, use clone to create a copy, then permute that instead.

Inputs:

• slice: The slice to permute.
• allocator: (default is context.allocator)

Returns:

• iter: The iterator, to be passed to permute.
• error: An Allocator_Error, if allocation failed.

Find the index of the (first) maximum element in a slice.

Find the index of the (first) minimum element in a slice.

Permute a slice in-place.

Note that the first iteration will always be the original, unpermuted slice.

Inputs:

• iter: The iterator created by make_permutation_iterator.

Returns:

• ok: True if the permutation succeeded, false if the iteration is complete.

return the prefix length common between slices a and b.

slice.prefix_length([]u8{1, 2, 3, 4}, []u8{1}) -> 1
	slice.prefix_length([]u8{1, 2, 3, 4}, []u8{1, 2, 3}) -> 3
	slice.prefix_length([]u8{1, 2, 3, 4}, []u8{2, 3, 4}) -> 0

Turn a slice of one type, into a slice of another type.

Only converts the type and length of the slice itself. The length is rounded down to the nearest whole number of items.

Example:

import "core:fmt"
import "core:slice"

i64s_as_i32s :: proc() {
	large_items := []i64{1, 2, 3, 4}
	small_items := slice.reinterpret([]i32, large_items)
	assert(len(small_items) == 8)
	fmt.println(large_items, "->", small_items)
}

bytes_as_i64s :: proc() {
	small_items := [12]byte{}
	small_items[0] = 1
	small_items[8] = 2
	large_items := slice.reinterpret([]i64, small_items[:])
	assert(len(large_items) == 1) // only enough bytes to make 1 x i64; two would need at least 8 bytes.
	fmt.println(small_items, "->", large_items)
}

reinterpret_example :: proc() {
	i64s_as_i32s()
	bytes_as_i64s()
}

Output:

[1, 2, 3, 4] -> [1, 0, 2, 0, 3, 0, 4, 0]
[1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0] -> [1]

Gets the byte size of the backing data

sort sorts a slice This sort is not guaranteed to be stable

sort_by sorts a slice with a given procedure to test whether two values are ordered "i < j" This sort is not guaranteed to be stable

TODO(bill): Should sort_by_key exist or is sort_by more than enough?

sort_by sorts a slice with a given procedure to test whether two values are ordered "i < j" This sort is not guaranteed to be stable

sort sorts a slice and returns a slice of the original indices This sort is not guaranteed to be stable

Sorts a slice while maintaining the relative order of elements with the same key. For an example see either stable_sort_by or stable_sort_by_cmp.

Sorts a slice while maintaining the relative order of elements with the same key. Two items i and j are ordered if less(i, j) returns true.

Example:

import "core:slice"
import "core:fmt"

stable_sort_by_example :: proc() {
	Example :: struct { n: int, s: string }

	arr := []Example {
		{2, "name"},
		{3, "Bill"},
		{1, "My"},
		{2, "is"}
	}
	slice.stable_sort_by(arr, proc(i, j: Example) -> bool {
		return i.n < j.n
	})

	for e in arr do  fmt.printf("%s ", e.s)
	fmt.println()
}

Output:

My name is Bill

Sorts a slice while maintaining the relative order of elements with the same key. The ordering of the any two items is defined by the user-provided cmp.

Example:

import "core:slice"
import "core:fmt"

stable_sort_by_cmp_example :: proc() {
	Example :: struct { n: int, s: string }

	arr := []Example {
		{2, "name"},
		{3, "Bill"},
		{1, "My"},
		{2, "is"}
	}
	slice.stable_sort_by_cmp(arr, proc(i, j: Example) -> slice.Ordering {
		return slice.cmp(i.n, j.n)
	})

	for e in arr do  fmt.printf("%s ", e.s)
	fmt.println()
}

Output:

My name is Bill

return the suffix length common between slices a and b.

slice.suffix_length([]u8{1, 2, 3, 4}, []u8{1, 2, 3, 4}) -> 4
	slice.suffix_length([]u8{1, 2, 3, 4}, []u8{3, 4}) -> 2
	slice.suffix_length([]u8{1, 2, 3, 4}, []u8{1}) -> 0
	slice.suffix_length([]u8{1, 2, 3, 4}, []u8{1, 3, 5}) -> 0
	slice.suffix_length([]u8{3, 4, 5}, []u8{3, 5}) -> 1

Turn a slice into a byte slice.

See `slice.reinterpret` to go the other way.

Turns a byte slice into a type.

'unique' replaces consecutive runs of equal elements with a single copy. The procedures modifies the slice in-place and returns the modified slice.

'unique_proc' replaces consecutive runs of equal elements with a single copy using a comparison procedure The procedures modifies the slice in-place and returns the modified slice.