Module builtin stdlib

str returns a string representation of an array of strings

Example:

['a', 'b', 'c'].str() // => "['a', 'b', 'c']".

hex returns a string with the hexadecimal representation of the byte elements of the array.

reduce executes a given reducer function on each element of the array, resulting in a single output value.

NOTE: It exists as a method on []int types only.

See also arrays.reduce for same name or arrays.fold for same functionality.

clone clones the byte array, and returns the newly created copy.

bytestr produces a string from all the bytes in the array.

Note: the returned string will have .len equal to the array.len, even when some of the array bytes were 0.

If you want to get a V string, that contains only the bytes till the first 0 byte, use tos_clone(&u8(array.data)) instead.

byterune attempts to decode a sequence of bytes from utf8 to utf32 and return the result as a rune it will produce an error if there are more than four bytes in the array.

string converts a rune array to a string

sort_ignore_case sorts the string array using case insesitive comparing.

sort_by_len sorts the the string array by each string's .len length.

join joins a string array into a string using sep separator.

Example:

assert ['Hello','V'].join(' ') == 'Hello V'

join joins a string array into a string using a \n newline delimiter.

convert array of utf8 bytes to single utf32 value will error if more than 4 bytes are submitted

hex returns a string with the hexadecimal representation of the byte elements of the array.

sort sorts the string array.

sort_ignore_case sorts the string array using case insesitive comparing.

sort_by_len sorts the the string array by each string's .len length.

Private function. Increases the cap of an array to the required value by copying the data to a new memory location (creating a clone) unless a.cap is already large enough.

repeat returns a new array with the given array elements repeated given times.

cgen will replace this with an apropriate call to repeat_to_depth

This is a dummy placeholder that will be overridden by cgen with an appropriate call to repeat_to_depth. However the checker needs it here.

repeat_to_depth is an unsafe version of repeat that handles multi-dimensional arrays.

It is unsafe to call directly because depth is not checked

insert inserts a value in the array at index i and increases the index of subsequent elements by 1.

This function is type-aware and can insert items of the same or lower dimensionality as the original array. That is, if the original array is []int, then the insert val may be int or []int. If the original array is [][]int, then val may be []int or [][]int. Consider the examples.

Example:

 mut a := [1, 2, 4]
 a.insert(2, 3)          // a now is [1, 2, 3, 4]
 mut b := [3, 4]
 b.insert(0, [1, 2])     // b now is [1, 2, 3, 4]
 mut c := [[3, 4]]
 c.insert(0, [1, 2])     // c now is [[1, 2], [3, 4]]

insert_many is used internally to implement inserting many values into an the array beginning at i.

prepend prepends one or more elements to an array.

It is shorthand for .insert(0, val)

prepend_many prepends another array to this array.

NOTE: prepend is probably all you need.

NOTE: This code is never called in all of vlib

delete deletes array element at index i.

This is exactly the same as calling .delete_many(i, 1).

NOTE: This function does NOT operate in-place. Internally, it creates a copy of the array, skipping over the element at i, and then points the original variable to the new memory location.

Example:

 mut a := ['0', '1', '2', '3', '4', '5']
 a.delete(1) // a is now ['0', '2', '3', '4', '5']

delete_many deletes size elements beginning with index i NOTE: This function does NOT operate in-place. Internally, it creates a copy of the array, skipping over size elements starting at i, and then points the original variable to the new memory location.

Example:

 mut a := [1, 2, 3, 4, 5, 6, 7, 8, 9]
 b := a[..9] // creates a <code>[slice](/standard_library/builtin.html#array_slice)</code> of `a`, not a clone
 a.delete_many(4, 3) // replaces `a` with a modified clone
 dump(a) // a: [1, 2, 3, 4, 8, 9] // `a` is now different
 dump(b) // b: [1, 2, 3, 4, 5, 6, 7, 8, 9] // `b` is still the same

clear clears the array without deallocating the allocated data.

It does it by setting the array length to 0

Example:

a.clear() // `a.len` is now 0

trim trims the array length to index without modifying the allocated data.

If index is greater than len nothing will be changed.

Example:

a.trim(3) // `a.len` is now <= 3

drop advances the array past the first num elements whilst preserving spare capacity.

If num is greater than len the array will be emptied.

Example:

 mut a := [1,2]
 a << 3
 a.drop(2)
 assert a == [3]
 assert a.cap > a.len

we manually inline this for single operations for performance without -prod

Private function. Used to implement array[] operator.

Private function. Used to implement x = a[i] or { ... }

first returns the first element of the array.

If the array is empty, this will panic.

However, a[0] returns an error object so it can be handled with an or block.

last returns the last element of the array.

If the array is empty, this will panic.

pop returns the last element of the array, and removes it.

If the array is empty, this will panic.

NOTE: this function reduces the length of the given array, but arrays sliced from this one will not change. They still retain their "view" of the underlying memory.

Example:

 mut a := [1, 2, 3, 4, 5, 6, 7, 8, 9]
 b := a[..9] // creates a "view" into the same memory
 c := a.pop() // c == 9
 a[1] = 5
 dump(a) // a: [1, 5, 3, 4, 5, 6, 7, 8]
 dump(b) // b: [1, 5, 3, 4, 5, 6, 7, 8, 9]

delete_last efficiently deletes the last element of the array.

It does it simply by reducing the length of the array by 1.

If the array is empty, this will panic.

See also: trim

slice returns an array using the same buffer as original array but starting from the start element and ending with the element before the end element of the original array with the length and capacity set to the number of the elements in the slice.

It will remain tied to the same memory location until the length increases (copy on grow) or clone is called on it.

If start and end are invalid this function will panic.

Alternative: Slices can also be made with [start..end] notation Alternative: slice_ni will always return an array.

slice_ni returns an array using the same buffer as original array but starting from the start element and ending with the element before the end element of the original array.

This function can use negative indexes a.slice_ni(-3, a.len) that get the last 3 elements of the array otherwise it return an empty array.

This function always return a valid array.

used internally for [2..4]

clone_static_to_depth() returns an independent copy of a given array.

Unlike clone_to_depth it has a value receiver and is used internally for slice-clone expressions like a[2..4].clone() and in -autofree generated code.

clone returns an independent copy of a given array.

this will be overwritten by cgen with an apropriate call to clone_to_depth However the checker needs it here.

recursively clone given array - unsafe when called directly because depth is not checked

we manually inline this for single operations for performance without -prod

Private function. Used to implement assignment to the array element.

push_many implements the functionality for pushing another array.

val is array.data and user facing usage is a << [1,2,3]

reverse_in_place reverses existing array data, modifying original array.

reverse returns a new array with the elements of the original array in reverse order.

free frees all memory occupied by the array.

filter creates a new array with all elements that pass the test.

Ignore the function signature. filter does not take an actual callback. Rather, it takes an it expression.

Certain array functions (filter any all) support a simplified domain-specific-language by the backend compiler to make these operations more idiomatic to V. These functions are described here, but their implementation is compiler specific.

Each function takes a boolean test expression as its single argument.

These test expressions may use it as a pointer to a single element at a time.

Example:

array.filter(it < 5) // create an array of elements less than 5

Example:

array.filter(it % 2 == 1) // create an array of only odd elements

Example:

array.filter(it.name[0] == `A`) // create an array of elements whose `name` field starts with 'A'

any tests whether at least one element in the array passes the test.

Ignore the function signature. any does not take an actual callback. Rather, it takes an it expression.

It returns true if it finds an element passing the test. Otherwise, it returns false. It doesn't modify the array.

Example:

array.any(it % 2 == 1) // will return true if any element is odd

Example:

array.any(it.name == 'Bob') // will yield `true` if any element has `.name == 'Bob'

all tests whether all elements in the array pass the test.

Ignore the function signature. all does not take an actual callback. Rather, it takes an it expression.

It returns false if any element fails the test. Otherwise, it returns true. It doesn't modify the array.

Example:

array.all(it % 2 == 1) // will return true if every element is odd

map creates a new array populated with the results of calling a provided function on every element in the calling array.

It also accepts an it expression.

Example:

 words := ['hello', 'world']
 r1 := words.map(it.to_upper())
 assert r1 == ['HELLO', 'WORLD']
 

// map can also accept anonymous functions
 r2 := words.map(fn (w string) string {
    return w.to_upper()
 })
 assert r2 == ['HELLO', 'WORLD']

sort sorts the array in place.

Ignore the function signature. Passing a callback to sort is not supported for now. Consider using the sort_with_compare method if you need it.

sort can take a boolean test expression as its single argument.

The expression uses 2 'magic' variables a and b as pointers to the two elements being compared.

Example:

array.sort() // will sort the array in ascending order

Example:

array.sort(b < a) // will sort the array in decending order

Example:

array.sort(b.name < a.name) // will sort descending by the .name field

sort_with_compare sorts the array in-place using the results of the given function to determine sort order.

The function should return one of three values:

• -1 when a should come before b ( a < b )

• 1 when b should come before a ( b < a )

• 0 when the order cannot be determined ( a == b )

Example:

 fn main() {
    mut a := ['hi', '1', '5', '3']
    a.sort_with_compare(fn (a &string, b &string) int {
        if a < b {
            return -1
        }
        if a > b {
            return 1
        }
        return 0
    })
    assert a == ['1', '3', '5', 'hi']
 }

contains determines whether an array includes a certain value among its elements It will return true if the array contains an element with this value.

It is similar to any but does not take an it expression.

Example:

[1, 2, 3].contains(4) == false

index returns the first index at which a given element can be found in the array or -1 if the value is not found.

grow_cap grows the array's capacity by amount elements.

Internally, it does this by copying the entire array to a new memory location (creating a clone).

grow_len ensures that an array has a.len + amount of length Internally, it does this by copying the entire array to a new memory location (creating a clone) unless the array.cap is already large enough.

pointers returns a new array, where each element is the address of the corresponding element in the array.

Private function. Doubles array capacity if needed.

version of repeat that handles multi dimensional arrays unsafe to call directly because depth is not checked

insert inserts a value in the array at index i

insert_many inserts many values into the array from index i.

prepend prepends one value to the array.

prepend_many prepends another array to this array.

pop returns the last element of the array, and removes it.

clone_static_to_depth_noscan returns an independent copy of a given array.

Unlike clone_to_depth_noscan it has a value receiver and is used internally for slice-clone expressions like a[2..4].clone() and in -autofree generated code.

recursively clone given array - unsafe when called directly because depth is not checked

push_many implements the functionality for pushing another array.

val is array.data and user facing usage is a << [1,2,3]

reverse returns a new array with the elements of the original array in reverse order.

grow_cap grows the array's capacity by amount elements.

grow_len ensures that an array has a.len + amount of length

trim trims the array length to "index" without modifying the allocated data. If "index" is greater than len nothing will be changed.

last returns the last element of the array.

delete deletes array element at index i.

delete_many deletes size elements beginning with index i

prepend prepends one value to the array.

prepend_many prepends another array to this array.

reduce executes a given reducer function on each element of the array, resulting in a single output value.

delete_last effectively removes last element of an array.

todo: once (a []u8) will work rewrite this

Private function. Used to implement array[] operator

Private function. Used to implement assignment to the array element.

array.repeat returns new array with the given array elements repeated nr_repeat times

free frees the memory occupied by the assertion meta data. It is called automatically by the code, that V's test framework generates, after all other callbacks have been called.