doc: improve Arrays section (#13842)

pull/13846/head
Nick Treleaven 2022-03-27 15:45:00 +01:00 committed by GitHub
parent f75ce9dd82
commit 3a4bb09de2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 45 additions and 36 deletions

View File

@ -780,19 +780,50 @@ f2 := 456e+2 // 45600
``` ```
### Arrays ### Arrays
#### Basic Array Concepts
Arrays are collections of data elements of the same type. They can be represented by An array is a collection of data elements of the same type. An array literal is a
a list of elements surrounded by brackets. The elements can be accessed by appending list of expressions surrounded by square brackets. An individual element can be
an *index* (starting with `0`) in brackets to the array variable: accessed using an *index* expression. Indexes start from `0`:
```v ```v
mut nums := [1, 2, 3] mut nums := [1, 2, 3]
println(nums) // `[1, 2, 3]` println(nums) // `[1, 2, 3]`
println(nums[0]) // `1` println(nums[0]) // `1`
println(nums[1]) // `2` println(nums[1]) // `2`
nums[1] = 5 nums[1] = 5
println(nums) // `[1, 5, 3]` println(nums) // `[1, 5, 3]`
``` ```
<a id='array-operations' />
An element can be appended to the end of an array using the push operator `<<`.
It can also append an entire array.
```v
mut nums := [1, 2, 3]
nums << 4
println(nums) // "[1, 2, 3, 4]"
// append array
nums << [5, 6, 7]
println(nums) // "[1, 2, 3, 4, 5, 6, 7]"
```
```v
mut names := ['John']
names << 'Peter'
names << 'Sam'
// names << 10 <-- This will not compile. `names` is an array of strings.
```
`val in array` returns true if the array contains `val`. See [`in` operator](#in-operator).
```v
names := ['John', 'Peter', 'Sam']
println('Alex' in names) // "false"
```
#### Array Fields #### Array Fields
There are two fields that control the "size" of an array: There are two fields that control the "size" of an array:
* `len`: *length* - the number of pre-allocated and initialized elements in the array * `len`: *length* - the number of pre-allocated and initialized elements in the array
* `cap`: *capacity* - the amount of memory space which has been reserved for elements, * `cap`: *capacity* - the amount of memory space which has been reserved for elements,
@ -807,11 +838,13 @@ println(nums.cap) // "3" or greater
nums = [] // The array is now empty nums = [] // The array is now empty
println(nums.len) // "0" println(nums.len) // "0"
``` ```
`data` is a field (of type `voidptr`) with the address of the first
element. This is for low-level [`unsafe`](#memory-unsafe-code) code.
Note that fields are read-only and can't be modified by the user. Note that the fields are read-only and can't be modified by the user.
#### Array Initialization #### Array Initialization
The basic initialization syntax is as described [above](#basic-array-concepts).
The type of an array is determined by the first element: The type of an array is determined by the first element:
* `[1, 2, 3]` is an array of ints (`[]int`). * `[1, 2, 3]` is an array of ints (`[]int`).
* `['a', 'b']` is an array of strings (`[]string`). * `['a', 'b']` is an array of strings (`[]string`).
@ -852,12 +885,15 @@ for i in 0 .. 1000 {
numbers << i numbers << i
} }
``` ```
Note: The above code uses a [range `for`](#range-for) statement and a Note: The above code uses a [range `for`](#range-for) statement.
[push operator (`<<`)](#array-operations).
You can initialize the array by accessing the `it` variable as shown here: You can initialize the array by accessing the `it` variable which gives
the index as shown here:
```v ```v
count := []int{len: 4, init: it}
assert count == [0, 1, 2, 3]
mut square := []int{len: 6, init: it * it} mut square := []int{len: 6, init: it * it}
// square == [0, 1, 4, 9, 16, 25] // square == [0, 1, 4, 9, 16, 25]
``` ```
@ -945,33 +981,6 @@ a[0][1][1] = 2
println(a) // [[[0, 0], [0, 2], [0, 0]], [[0, 0], [0, 0], [0, 0]]] println(a) // [[[0, 0], [0, 2], [0, 0]], [[0, 0], [0, 0], [0, 0]]]
``` ```
#### Array Operations
Elements can be appended to the end of an array using the push operator `<<`.
It can also append an entire array.
```v
mut nums := [1, 2, 3]
nums << 4
println(nums) // "[1, 2, 3, 4]"
// append array
nums << [5, 6, 7]
println(nums) // "[1, 2, 3, 4, 5, 6, 7]"
mut names := ['John']
names << 'Peter'
names << 'Sam'
// names << 10 <-- This will not compile. `names` is an array of strings.
```
`val in array` returns true if the array contains `val`. See [`in` operator](#in-operator).
```v
names := ['John', 'Peter', 'Sam']
println(names.len) // "3"
println('Alex' in names) // "false"
```
#### Array methods #### Array methods
All arrays can be easily printed with `println(arr)` and converted to a string All arrays can be easily printed with `println(arr)` and converted to a string