| * [Language specification](#language-specification) * [Hello world](#hello-world) * [Running a project folder](#running-a-project-folder-with-several-files) * [Comments](#comments) * [Functions](#functions) * [Hoisting](#hoisting) * [Returning multiple values](#returning-multiple-values) * [Symbol visibility](#symbol-visibility) * [Variables](#variables) * [Mutable variables](#mutable-variables) * [Initialization vs assignment](#initialization-vs-assignment) * [Warnings and declaration errors](#warnings-and-declaration-errors) * [V types](#v-types) * [Primitive types](#primitive-types) * [Strings](#strings) * [Runes](#runes) * [Numbers](#numbers) * [Arrays](#arrays) * [Array update syntax](#array-update-syntax) * [Multidimensional arrays](#multidimensional-arrays) * [Array methods](#array-methods) * [Array slices](#array-slices) * [Fixed size arrays](#fixed-size-arrays) * [Maps](#maps) * [Map update syntax](#map-update-syntax) | * [Module imports](#module-imports) * [Selective imports](#selective-imports) * [Module hierarchy](#module-hierarchy) * [Module import aliasing](#module-import-aliasing) * [Statements & expressions](#statements--expressions) * [If](#if) * [`If` expressions](#if-expressions) * [`If` unwrapping](#if-unwrapping) * [Match](#match) * [In operator](#in-operator) * [For loop](#for-loop) * [Defer](#defer) * [Goto](#goto) * [Structs](#structs) * [Heap structs](#heap-structs) * [Default field values](#default-field-values) * [Required fields](#required-fields) * [Short struct literal syntax](#short-struct-literal-syntax) * [Struct update syntax](#struct-update-syntax) * [Trailing struct literal arguments](#trailing-struct-literal-arguments) * [Access modifiers](#access-modifiers) * [Anonymous structs](#anonymous-structs) * [Static type methods](#static-type-methods) * [[noinit] structs](#noinit-structs) * [Methods](#methods) * [Embedded structs](#embedded-structs) * [Unions](#unions) * [Why use unions?](#why-use-unions) * [Embedding](#embedding) | * [Functions 2](#functions-2) * [Immutable function args by default](#immutable-function-args-by-default) * [Mutable arguments](#mutable-arguments) * [Variable number of arguments](#variable-number-of-arguments) * [Anonymous & higher-order functions](#anonymous--higher-order-functions) * [Lambda expressions](#lambda-expressions) * [Closures](#closures) * [Parameter evaluation order](#parameter-evaluation-order) * [References](#references) * [Constants](#constants) * [Required module prefix](#required-module-prefix) * [Builtin functions](#builtin-functions) * [println](#println) * [Printing custom types](#printing-custom-types) * [Dumping expressions at runtime](#dumping-expressions-at-runtime) * [Modules](#modules) * [Create modules](#create-modules) * [Special considerations for project folders](#special-considerations-for-project-folders) * [init functions](#init-functions) * [cleanup functions](#cleanup-functions) |
| * [Type Declarations](#type-declarations) * [Type aliases](#type-aliases) * [Enums](#enums) * [Function Types](#function-types) * [Interfaces](#interfaces) * [Sum types](#sum-types) * [Option/Result types & error handling](#optionresult-types-and-error-handling) * [Handling options/results](#handling-optionsresults) * [Custom error types](#custom-error-types) * [Generics](#generics) * [Concurrency](#concurrency) * [Spawning Concurrent Tasks](#spawning-concurrent-tasks) * [Channels](#channels) * [Shared Objects](#shared-objects) * [Race Detector](#race-detector) * [JSON](#json) * [Decoding JSON](#decoding-json) * [Encoding JSON](#encoding-json) * [Testing](#testing) * [Asserts](#asserts) * [Asserts with an extra message](#asserts-with-an-extra-message) * [Asserts that do not abort your program](#asserts-that-do-not-abort-your-program) * [Test files](#test-files) * [Running tests](#running-tests) * [Memory management](#memory-management) * [Control](#control) * [Stack and Heap](#stack-and-heap) * [Ownership](ownership.md) * [ORM](#orm) * [Writing documentation](#writing-documentation) * [Newlines in Documentation Comments](#newlines-in-documentation-comments) | * [Tools](#tools) * [v fmt](#v-fmt) * [v mcp](#v-mcp) * [v skills](#v-skills) * [v clean](#v-clean) * [v env](#v-env) * [v shader](#v-shader) * [v tool](#v-tool) * [Profiling](#profiling) * [Profiling the compiler](#profiling-the-compiler) * [Package Management](#package-management) * [v mod why](#v-mod-why) * [Package commands](#package-commands) * [Locking dependency revisions](#locking-dependency-revisions) * [Publish package](#publish-package) * [Advanced Topics](#advanced-topics) * [Attributes](#attributes) * [Conditional compilation](#conditional-compilation) * [Compile time pseudo variables](#compile-time-pseudo-variables) * [Compile time reflection](#compile-time-reflection) * [Compile time code](#compile-time-code) * [Compile time types](#compile-time-types) * [Environment specific files](#environment-specific-files) * [Debugger](#debugger) * [Call stack](#call-stack) * [Trace](#trace) * [Memory-unsafe code](#memory-unsafe-code) * [Structs with reference fields](#structs-with-reference-fields) * [sizeof and __offsetof](#sizeof-and-__offsetof) * [Limited operator overloading](#limited-operator-overloading) * [Performance tuning](#performance-tuning) * [Atomics](#atomics) * [Global Variables](#global-variables) * [Static Variables](#static-variables) * [Cross compilation](#cross-compilation) * [Compiling for iOS](#compiling-for-ios) * [Debugging](#debugging) * [C Backend binaries Default](#c-backend-binaries-default) * [Native Backend binaries](#native-backend-binaries) * [Javascript Backend](#javascript-backend) | * [V and C](#v-and-c) * [Calling C from V](#calling-c-from-v) * [Calling V from C](#calling-v-from-c) * [Passing C compilation flags](#passing-c-compilation-flags) * [#pkgconfig](#pkgconfig) * [Including C code](#including-c-code) * [C types](#c-types) * [C Declarations](#c-declarations) * [Export to shared library](#export-to-shared-library) * [Translating C to V](#translating-c-to-v) * [Working around C issues](#working-around-c-issues) * [Other V Features](#other-v-features) * [Inline assembly](#inline-assembly) * [Hot code reloading](#hot-code-reloading) * [Cross-platform shell scripts in V](#cross-platform-shell-scripts-in-v) * [Vsh scripts with no extension](#vsh-scripts-with-no-extension) * [Source locations in generated code](#source-locations-in-generated-code) * [Appendices](#appendices) * [Keywords](#appendix-i-keywords) * [Operators](#appendix-ii-operators) * [Other online resources](#other-online-resources) |
` (backticks) :
```v
rocket := `🚀`
```
A `rune` can be converted to a UTF-8 string by using the `.str()` method.
```v
rocket := `🚀`
assert rocket.str() == '🚀'
```
A `rune` can be converted to UTF-8 bytes by using the `.bytes()` method.
```v
rocket := `🚀`
assert rocket.bytes() == [u8(0xf0), 0x9f, 0x9a, 0x80]
```
Hex, Unicode, and Octal escape sequences also work in a `rune` literal:
```v
assert `\x61` == `a`
assert `\141` == `a`
assert `\u0061` == `a`
// multibyte literals work too
assert `\u2605` == `★`
assert `\u2605`.bytes() == [u8(0xe2), 0x98, 0x85]
assert `\xe2\x98\x85`.bytes() == [u8(0xe2), 0x98, 0x85]
assert `\342\230\205`.bytes() == [u8(0xe2), 0x98, 0x85]
```
Note that `rune` literals use the same escape syntax as strings, but they can only hold one unicode
character. Therefore, if your code does not specify a single Unicode character, you will receive an
error at compile time.
Also remember that strings are indexed as bytes, not runes, so beware:
```v
rocket_string := '🚀'
assert rocket_string[0] != `🚀`
assert 'aloha!'[0] == `a`
```
A string can be converted to runes by the `.runes()` method.
```v
hello := 'Hello World 👋'
hello_runes := hello.runes() // [`H`, `e`, `l`, `l`, `o`, ` `, `W`, `o`, `r`, `l`, `d`, ` `, `👋`]
assert hello_runes.string() == hello
```
### Numbers
```v
a := 123
```
This will assign the value of 123 to `a`. By default `a` will have the
type `int`.
You can also use hexadecimal, binary or octal notation for integer literals:
```v
a := 0x7B
b := 0b01111011
c := 0o173
```
All of these will be assigned the same value, 123. They will all have type
`int`, no matter what notation you used.
V also supports writing numbers with `_` as separator:
```v
num := 1_000_000 // same as 1000000
three := 0b0_11 // same as 0b11
float_num := 3_122.55 // same as 3122.55
hexa := 0xF_F // same as 255
oct := 0o17_3 // same as 0o173
```
If you want a different type of integer, you can use casting:
```v
a := i64(123)
b := u8(42)
c := i16(12345)
```
Assigning floating point numbers works the same way:
```v
f := 1.0
f1 := f64(3.14)
f2 := f32(3.14)
```
If you do not specify the type explicitly, by default float literals
will have the type of `f64`.
Integer literals can be assigned to `f32` and `f64` variables without a cast.
Unary `+`, unary `-`, parentheses, and arithmetic on integer literals and on the
constants declared with them preserve this behavior:
```v
const tile_size = 32
mut a := f32(0)
a = 1
a = -1
assert a == f32(-1)
a = 6 * tile_size
assert a == f32(192)
```
This does not make typed integer variables implicitly assignable to `f32`;
use an explicit conversion such as `a = f32(value)` for those variables.
Float literals can also be declared as a power of ten:
```v
f0 := 42e1 // 420
f1 := 123e-2 // 1.23
f2 := 456e+2 // 45600
```
#### Checked integer arithmetic
Integer arithmetic wraps on overflow, a shift by the bit width or more gives `0`,
and a cast to a smaller integer type keeps the low bits.
Two opt-in flags turn these into runtime panics:
* `v -check-overflow` checks `+`, `-`, `*`, `++`, `--`, and `min / -1` and `min % -1`
(with their compound forms like `-=`, `/=`). In code outside the standard library, it also
checks the negation of the minimum value (`-x` for `x == min_i64`), and shifts whose count is
negative or not less than the bit width of the left operand.
* `v -check-casts` checks integer casts that lose information, like `i8(i64(300))`, `u8(-1)`
or `u64(i64(-5))`. Casts from floats, or to `char` and enums, are not checked. Only code
outside the standard library is checked, since vlib uses truncating casts on purpose
(hashes, byte extraction).
A function tagged with `@[ignore_overflow]` is not checked by either flag:
```v
@[ignore_overflow]
fn hash_step(h u32, b u8) u32 {
return (h ^ u32(b)) * 16777619 // wraps on purpose
}
```
### Arrays
Returning a new array through helper calls preserves each helper's parameter scope.
An array is a collection of data elements of the same type. An array literal is a
list of expressions surrounded by square brackets. An individual element can be
accessed using an *index* expression. Indexing starts from `0`.
A string literal keeps its string type even when its text names a type alias.
For example, `['Speed']` contains strings, while `[Speed(7)]` contains `Speed` values.
In `==` and `!=` comparisons, array and map literals use the element or value type of the
other operand. This also applies when that operand propagates an option or result with `?`
or `!`. Operands are evaluated from left to right.
After an array literal, separate `&&` from either adjacent token with whitespace or a comment
to use logical AND, as in `a == [] && flag`. An attached `[]&&Type{}` declares an array of
references to references. Separate `&` on both sides to use the binary AND operator;
`[]&Type{}` and `[] &Type{}` remain array initializers with reference elements.
```v
mut nums := [10, 20, 30]
println(nums) // `[10, 20, 30]`
println(nums[0]) // `10`
println(nums[1]) // `20`
nums[1] = 5
println(nums) // `[10, 5, 30]`
```
An element can be appended to the end of an array using the push operator `<<`.
It can also append an entire array.
The C backend uses typed stores for scalar element assignments and single-element appends.
Assignments retain bounds checking. Appends retain capacity checks and detach slice storage
when needed. The right-hand side can grow the array before the final element address is resolved.
```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]"
```
Use `<< ...array` to explicitly append the array's elements. When appending an array of
concrete values to an empty interface array, `<< array` appends the whole array as one
interface value, while `<< ...array` converts and appends each element separately.
For example, with `interface Value {}`, appending `['IT']` to `[]Value{}` produces
`[Value(['IT'])]` with `<<` and `[Value('IT')]` with `<< ...`.
`insert(index, ...array)` and `prepend(...array)` also convert each source element to the
destination element type before inserting it.
```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"
```
Use `<< ...array` to explicitly append the array's elements. For an interface array,
`<< array` can append the whole array as one interface value, while `<< ...array`
converts each element separately. `array.insert(index, ...values)` and
`array.prepend(...values)` also convert each source element to the destination element type.
#### Array Fields
There are two fields that control the "size" of an 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,
but not initialized or counted as elements. The array can grow up to this size without
being reallocated. Usually, V takes care of this field automatically but there are
cases where the user may want to do manual optimizations (see [below](#array-initialization)).
```v
mut nums := [1, 2, 3]
println(nums.len) // "3"
println(nums.cap) // "3" or greater
nums = [] // The array is now empty
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]
> Fields are read-only and can't be modified by the user.
#### Array Initialization
The type of an array is determined by the first element:
* `[1, 2, 3]` is an array of ints (`[]int`).
* `['a', 'b']` is an array of strings (`[]string`).
The user can explicitly specify the type for the first element: `[u8(16), 32, 64, 128]`.
V arrays are homogeneous (all elements must have the same type).
This means that code like `[1, 'a']` will not compile.
Array elements must be written inside square brackets. Braces accept named initializer
parameters only; `[]int{1, 2, 3}` and `[3]int{1, 2, 3}` are syntax errors.
Use `[1, 2, 3]` for a dynamic array or `[1, 2, 3]!` for a fixed array instead.
The above syntax is fine for a small number of known elements but for very large or empty
arrays there is a second initialization syntax:
```v
mut a := []int{len: 10000, cap: 30000, init: 3}
```
This creates an array of 10000 `int` elements that are all initialized with `3`. Memory
space is reserved for 30000 elements. The parameters `len`, `cap` and `init` are optional;
`len` defaults to `0` and `init` to the default initialization of the element type (`0`
for numerical type, `''` for `string`, etc). The run time system makes sure that the
capacity is not smaller than `len` (even if a smaller value is specified explicitly):
```v
arr := []int{len: 5, init: -1}
// `arr == [-1, -1, -1, -1, -1]`, arr.cap == 5
// Declare an empty array:
users := []int{}
```
Setting the capacity improves performance of pushing elements to the array
as reallocations can be avoided:
```v
mut numbers := []int{cap: 1000}
println(numbers.len) // 0
// Now appending elements won't reallocate
for i in 0 .. 1000 {
numbers << i
}
```
> [!NOTE]
> The above code uses a [range `for`](#range-for) statement.
You can initialize the array by accessing the `index` variable which gives
the index as shown here:
```v
count := []int{len: 4, init: index}
assert count == [0, 1, 2, 3]
mut square := []int{len: 6, init: index * index}
// square == [0, 1, 4, 9, 16, 25]
```
#### Array update syntax
V lets you initialise an array by spreading an existing array, optionally
followed by additional elements:
```v
base := [1, 2]
a := [...base, 3, 4]
assert a == [1, 2, 3, 4]
// Append to a copy of `base`, leaving `base` itself unchanged:
mut b := [...base]
b << 99
assert base == [1, 2]
assert b == [1, 2, 99]
```
This is functionally equivalent to cloning the array and appending to it,
except that you don't have to declare a mutable variable for the intermediate
value, and the additional elements may be inlined at the call site.
#### Array Types
An array can be of these types:
| Types | Example Definition |
|--------------|--------------------------------------|
| Number | `[]int,[]i64` |
| String | `[]string` |
| Rune | `[]rune` |
| Boolean | `[]bool` |
| Array | `[][]int` |
| Struct | `[]MyStructName` |
| Channel | `[]chan f64` |
| Function | `[]MyFunctionType` `[]fn (int) bool` |
| Interface | `[]MyInterfaceName` |
| Sum Type | `[]MySumTypeName` |
| Generic Type | `[]T` |
| Map | `[]map[string]f64` |
| Enum | `[]MyEnumType` |
| Alias | `[]MyAliasTypeName` |
| Thread | `[]thread int` |
| Reference | `[]&f64` |
| Shared | `[]shared MyStructType` |
| Option | `[]?f64` |
**Example Code:**
This example uses [Structs](#structs) and [Sum Types](#sum-types) to create an array
which can handle different types (e.g. Points, Lines) of data elements.
```v
struct Point {
x int
y int
}
struct Line {
p1 Point
p2 Point
}
type ObjectSumType = Line | Point
mut object_list := []ObjectSumType{}
object_list << Point{1, 1}
object_list << Line{
p1: Point{3, 3}
p2: Point{4, 4}
}
dump(object_list)
/*
object_list: [ObjectSumType(Point{
x: 1
y: 1
}), ObjectSumType(Line{
p1: Point{
x: 3
y: 3
}
p2: Point{
x: 4
y: 4
}
})]
*/
```
#### Multidimensional Arrays
Arrays can have more than one dimension.
2d array example:
```v
mut a := [][]int{len: 2, init: []int{len: 3}}
a[0][1] = 2
println(a) // [[0, 2, 0], [0, 0, 0]]
```
3d array example:
```v
mut a := [][][]int{len: 2, init: [][]int{len: 3, init: []int{len: 2}}}
a[0][1][1] = 2
println(a) // [[[0, 0], [0, 2], [0, 0]], [[0, 0], [0, 0], [0, 0]]]
```
#### Array methods
A function literal passed to `map` uses its return type for the output elements. Its parameters
and nested array expressions have their own scope, including parameters named `it`.
All arrays can be easily printed with `println(arr)` and converted to a string
with `s := arr.str()`.
Copying the data from the array is done with `.clone()`:
```v
nums := [1, 2, 3]
nums_copy := nums.clone()
```
Arrays can be efficiently filtered and mapped with the `.filter()` and
`.map()` methods:
```v
nums := [1, 2, 3, 4, 5, 6]
even := nums.filter(it % 2 == 0)
println(even) // [2, 4, 6]
// filter can accept anonymous functions
even_fn := nums.filter(fn (x int) bool {
return x % 2 == 0
})
println(even_fn)
```
```v
words := ['hello', 'world']
upper := words.map(it.to_upper())
println(upper) // ['HELLO', 'WORLD']
// map can also accept anonymous functions
upper_fn := words.map(fn (w string) string {
return w.to_upper()
})
println(upper_fn) // ['HELLO', 'WORLD']
```
`it` is a builtin variable which refers to the element currently being
processed in filter/map methods.
User-defined struct methods named `map` keep their declared return type, including when chained.
Additionally, `.any()` and `.all()` can be used to conveniently test
for elements that satisfy a condition.
```v
nums := [1, 2, 3]
println(nums.any(it == 2)) // true
println(nums.all(it >= 2)) // false
```
There are further built-in methods for arrays:
* `a.repeat(n)` concatenates the array elements `n` times
* `a.insert(i, val)` inserts a new element `val` at index `i` and
shifts all following elements to the right
* `a.insert(i, [3, 4, 5])` inserts several elements
* `a.prepend(val)` inserts a value at the beginning, equivalent to `a.insert(0, val)`
* `a.prepend(arr)` inserts elements of array `arr` at the beginning
* `a.trim(new_len)` truncates the length (if `new_length < a.len`, otherwise does nothing)
* `a.clear()` empties the array without changing `cap` (equivalent to `a.trim(0)`)
* `a.delete_many(start, size)` removes `size` consecutive elements from index `start`,
preserving order. On the C backend, it reuses the backing buffer and keeps capacity when
no slices share it
* `a.delete(index)` equivalent to `a.delete_many(index, 1)`
* `a.delete_last()` removes the last element; on the C backend it does not change `cap`
* `a.first()` equivalent to `a[0]`
* `a.last()` equivalent to `a[a.len - 1]`
* `a.pop()` removes the last element and returns it
* `a.reverse()` makes a new array with the elements of `a` in reverse order
* `a.reverse_in_place()` reverses the order of elements in `a`
* `a.join(joiner)` concatenates an array of strings into one string
using `joiner` string as a separator
See all methods of [array](https://modules.vlang.io/builtin.html#array)
See also [vlib/arrays](https://modules.vlang.io/arrays.html).
##### Sorting Arrays
Sorting arrays of all kinds is very simple and intuitive. Special variables `a` and `b`
are used when providing a custom sorting condition.
```v
mut numbers := [1, 3, 2]
numbers.sort() // 1, 2, 3
numbers.sort(a > b) // 3, 2, 1
```
`sorted()` returns a sorted copy. Alias element types keep their overloaded `<` operator,
including when the receiver is an array literal or a parenthesized array literal.
```v
struct User {
age int
name string
}
mut users := [User{21, 'Bob'}, User{20, 'Zarkon'}, User{25, 'Alice'}]
users.sort(a.age < b.age) // sort by User.age int field
users.sort(a.name > b.name) // reverse sort by User.name string field
```
V also supports custom sorting, through the `sort_with_compare` array method.
Which expects a comparing function which will define the sort order.
Useful for sorting on multiple fields at the same time by custom sorting rules.
The code below sorts the array ascending on `name` and descending `age`.
```v
struct User {
age int
name string
}
mut users := [User{21, 'Bob'}, User{65, 'Bob'}, User{25, 'Alice'}]
custom_sort_fn := fn (a &User, b &User) int {
// return -1 when a comes before b
// return 0, when both are in same order
// return 1 when b comes before a
if a.name == b.name {
if a.age < b.age {
return 1
}
if a.age > b.age {
return -1
}
return 0
}
if a.name < b.name {
return -1
} else if a.name > b.name {
return 1
}
return 0
}
users.sort_with_compare(custom_sort_fn)
```
#### Array Slices
Iteration over an array slice keeps the array's element type: iterating `[]string` yields
strings, including when the containing function is reached through generic calls.
A slice is a part of a parent array. Initially it refers to the elements
between two indices separated by a `..` operator. The right-side index must
be greater than or equal to the left side index.
If a right-side index is absent, it is assumed to be the array length. If a
left-side index is absent, it is assumed to be 0.
```v
nums := [0, 10, 20, 30, 40]
println(nums[1..4]) // [10, 20, 30]
println(nums[..4]) // [0, 10, 20, 30]
println(nums[1..]) // [10, 20, 30, 40]
```
In V slices are arrays themselves (they are not distinct types). As a result
all array operations may be performed on them. E.g. they can be pushed onto an
array of the same type:
```v
array_1 := [3, 5, 4, 7, 6]
mut array_2 := [0, 1]
array_2 << array_1[..3]
println(array_2) // `[0, 1, 3, 5, 4]`
```
A slice is always created with the smallest possible capacity `cap == len` (see
[`cap` above](#array-initialization)) no matter what the capacity or length
of the parent array is. As a result it is immediately reallocated and copied to another
memory location when the size increases thus becoming independent from the
parent array (*copy on grow*). In particular pushing elements to a slice
does not alter the parent:
When a slice expression like `a[2..4]` is assigned outside `unsafe` and either
the parent array or the resulting slice is mutable, V inserts an implicit
`.clone()` and shows a notice. This prevents changes through one array from
affecting the other. If both arrays are immutable, the slice safely reuses the
parent array's memory without cloning. The shared-memory examples below
therefore use `unsafe {}` intentionally.
Printing or interpolating the parent array shows changes made through such a shared slice.
Formatting such a mutated array with `-b wasm` currently reports an unsupported
runtime-formatting error.
```v
mut a := [0, 1, 2, 3, 4, 5]
// Create a slice, that reuses the *same memory* as the parent array
// initially, without doing a new allocation:
mut b := unsafe { a[2..4] } // the contents of `b`, reuses the memory, used by the contents of `a`.
b[0] = 7 // Note that `b[0]` and `a[2]` refer to *the same element* in memory.
println(a) // `[0, 1, 7, 3, 4, 5]` - changing `b[0]` above, changed `a[2]` too.
// the content of `b` will get reallocated, to have room for the `9` element:
b << 9
// The content of `b`, is now reallocated, and fully independent from the content of `a`.
println(a) // `[0, 1, 7, 3, 4, 5]` - no change, since the content of `b` was reallocated,
// to a larger block, before the appending.
println(b) // `[7, 3, 9]` - the contents of `b`, after the reallocation, and appending of the `9`.
```
Appending to the parent array, may or may not make it independent from its child slices.
The behaviour depends on the *parent's capacity* and is predictable:
```v
mut a := []int{len: 5, cap: 6, init: 2}
mut b := unsafe { a[1..4] } // the contents of `b` uses part of the same memory, that is used by `a` too
a << 3
// still no reallocation of `a`, since `a.len` still fits in `a.cap`
b[2] = 13 // `a[3]` is modified, through the slice `b`.
a << 4
// the content of `a` has been reallocated now, and is independent from `b` (`cap` was exceeded by `len`)
b[1] = 3 // no change in `a`
println(a) // `[2, 2, 2, 13, 2, 3, 4]`
println(b) // `[2, 3, 13]`
```
You can call .clone() on the slice, if you *do* want to have an independent copy right away:
```v
mut a := [0, 1, 2, 3, 4, 5]
mut b := a[2..4].clone()
b[0] = 7 // Note: `b[0]` is NOT referring to `a[2]`, as it would have been, without the `.clone()`
println(a) // [0, 1, 2, 3, 4, 5]
println(b) // [7, 3]
```
If either the parent array or the slice is mutable, V makes an implicit clone
of the slice and displays a notice. Therefore, without the `.clone()` call,
the result of the code above will be the same. When both arrays are immutable,
the slice reuses the parent array's memory because neither array can be changed.
Make the slice in an `unsafe {}` block if you want to share mutable memory;
otherwise use explicit cloning.
##### Slices with negative indexes
V supports array and string slices with negative indexes.
Negative indexing starts from the end of the array towards the start,
for example `-3` is equal to `array.len - 3`.
Negative slices have a different syntax from normal slices, i.e. you need
to add a `gate` between the array name and the square bracket: `a#[..-3]`.
The `gate` specifies that this is a different type of slice and remember that
the result is "locked" inside the array.
The returned slice is always a valid array, though it may be empty:
```v
a := [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
println(a#[-3..]) // [7, 8, 9]
println(a#[-20..]) // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
println(a#[-20..-8]) // [0, 1]
println(a#[..-3]) // [0, 1, 2, 3, 4, 5, 6]
// empty arrays
println(a#[-20..-10]) // []
println(a#[20..10]) // []
println(a#[20..30]) // []
```
#### Array method chaining
You can chain the calls of array methods like `.filter()` and `.map()` and use
the `it` built-in variable to achieve a classic `map/filter` functional paradigm:
```v
// using filter, map and negatives array slices
files := ['pippo.jpg', '01.bmp', '_v.txt', 'img_02.jpg', 'img_01.JPG']
filtered := files.filter(it#[-4..].to_lower() == '.jpg').map(it.to_upper())
// ['PIPPO.JPG', 'IMG_02.JPG', 'IMG_01.JPG']
```
### Fixed size arrays
Mapping a fixed size array preserves its length and uses the mapping expression or function
return type as its element type. Filtering still produces a dynamic array.
V also supports arrays with fixed size. Unlike ordinary arrays, their
length is constant. You cannot append elements to them, nor shrink them.
You can only modify their elements in place.
Iteration preserves the complete element type, including pointers to generic structs.
For example, iterating over `[2]&Box[string]` yields `&Box[string]` values.
However, access to the elements of fixed size arrays is more efficient,
they need less memory than ordinary arrays, and unlike ordinary arrays,
their data is on the stack, so you may want to use them as buffers if you
do not want additional heap allocations.
Most methods are defined to work on ordinary arrays, not on fixed size arrays.
You can convert a fixed size array to an ordinary array with slicing:
```v
mut fnums := [3]int{} // fnums is a fixed size array with 3 elements.
fnums[0] = 1
fnums[1] = 10
fnums[2] = 100
println(fnums) // => [1, 10, 100]
println(typeof(fnums).name) // => [3]int
fnums2 := [1, 10, 100].to_fixed_size() // explicit conversion syntax
fnums3 := [1, 10, 100]! // short init syntax, equivalent to `.to_fixed_size()`
anums := fnums[..] // same as `anums := fnums[0..fnums.len]`
println(anums) // => [1, 10, 100]
println(typeof(anums).name) // => []int
```
Whole fixed size arrays and their ranges can be passed to mutable array parameters.
These arguments borrow the original elements, so writes through either the array parameter
or another alias are immediately visible through both. Returned or stored views keep sharing
those elements. Local storage is moved to the heap before references to it are formed, so
retained views remain valid after the local goes out of scope. A callee can also retain a
reference to the separately allocated array header. Growing or reassigning that header follows
the usual array slice rules and leaves the original fixed array's size unchanged.
Immutable array-reference parameters, including each variadic argument, also borrow the
original elements. These rules also apply to array-reference parameters declared through aliases.
Fixed array values introduced by guards, multi-declarations, loop bindings, or select receives
also receive durable storage when passed to a retaining array-reference parameter.
Indexed fixed elements of dynamic arrays retain their original backing buffer, including through
managed slice aliases, so retained headers preserve writes and remain valid after owner cleanup.
The same rule applies to fixed elements obtained through `first()` or `last()`.
Fixed values read from maps, including inline fields, are copied into independent durable storage.
Mutable iteration over those fixed elements preserves the same backing lifetime.
Pointer fields and indexed pointers retain the original fixed-array roots recorded by their owners.
Borrowing does not clone elements or require a `clone()` method.
Passing a local struct's fixed-array storage by reference keeps the local on the stack when
the called function only reads or writes scalar fields and array elements, or passes the
reference, or the address of an element (`&buf[i]`), straight on to a function that does the
same. Calls that may retain the storage still move it to the heap; `-warn-about-allocs` reports
these moves.
Calls through local function values remain conservative, including values that shadow
function names.
Explicitly destroying owned source elements invalidates views of those elements, as with other
borrowed slices.
With ownership checking enabled, returning or storing a view copies its buffer to independent
storage. Owned elements are cloned so the retained value has independent owners. Retained array
references, including those stored inside options, receive a separate header, so other aliases
in the callee still share the original elements.
An operation that detaches a borrowed buffer also clones its owned elements. Such elements
need a compatible `clone()` method or `IClone` support. Retaining or detaching a nonempty
uncloneable borrowed buffer panics; borrowing it or changing its elements in place is allowed.
An empty view can grow without cloning any source elements.
Note that slicing will cause the data of the fixed size array to be copied to
the newly created ordinary array. The exception is a slice that is written to:
passing it as a `mut` argument, changing its elements, iterating over it with
`for mut`, or calling `sort()`, `sort_with_compare()` or `reverse_in_place()` on it,
updates the fixed size array itself:
```v
fn fill(mut a []int) {
for i in 0 .. a.len {
a[i] = 9
}
}
mut fixed := [4, 3, 2, 1]!
fill(mut fixed[2..])
println(fixed) // => [4, 3, 9, 9]
fixed[..2].sort()
println(fixed) // => [3, 4, 9, 9]
```
To copy elements into an existing array instead, use the builtin `copy` function.
Like Go's `copy`, it copies as many elements as both arguments have, returns that
number, and handles overlapping arguments. The destination can be an ordinary array,
a fixed size array, or a slice of either, and is updated in place. The source can
also be a string, when the destination holds bytes:
```v
items := [1, 2, 3, 4, 5]
mut fixed := [4]int{}
println(copy(mut fixed, items)) // => 4
println(fixed) // => [1, 2, 3, 4]
copy(mut fixed[2..], [9, 9, 9])
println(fixed) // => [1, 2, 9, 9]
mut buf := []u8{len: 3}
copy(mut buf, 'hello')
println(buf.bytestr()) // => hel
```
### Maps
Methods and references on map iteration values address the stored element, including nested maps.
Postfix updates to a mutable map value field, such as `m[key].level++`, update the stored
entry and insert a zero value first when the key is absent. The key is evaluated once.
```v
mut m := map[string]int{} // a map with `string` keys and `int` values
m['one'] = 1
m['two'] = 2
println(m['one']) // "1"
println(m['bad_key']) // "0"
println('bad_key' in m) // Use `in` to detect whether such key exists
println(m.keys()) // ['one', 'two']
m.delete('two')
```
Maps can have keys of type string, rune, integer, float, voidptr,
enum, or fixed arrays of those supported key types.
Struct keys are rejected, including when a generic key parameter is instantiated with a struct.
The whole map can be initialized using this short syntax:
```v
numbers := {
'one': 1
'two': 2
}
println(numbers)
```
If a key is not found, a zero value is returned by default:
```v
sm := {
'abc': 'xyz'
}
val := sm['bad_key']
println(val) // ''
```
```v
intm := {
1: 1234
2: 5678
}
s := intm[3]
println(s) // 0
```
It's also possible to use an `or {}` block to handle missing keys:
```v
mm := map[string]int{}
val := mm['bad_key'] or { panic('key not found') }
```
Modules can opt into stricter map indexing:
```v
@[strict_map_index]
module main
fn main() {
m := {
'abc': 'xyz'
}
value := m['abc'] or { panic('missing map key') }
if other := m['abc'] {
println(other)
}
// m['bad_key'] // compile error in `@[strict_map_index]` modules
println(value)
}
```
You can also check, if a key is present, and get its value, if it was present, in one go:
```v
m := {
'abc': 'def'
}
if v := m['abc'] {
println('the map value for that key is: ${v}')
}
```
Note: map indexing returns a copy of the stored value, including with `or {}`
and `if v := m[key] {}`. Mutating that local value does not update the value
stored in the map.
To update a stored value, mutate `m[key]` directly or assign the modified value
back to the map:
```v
mut data := map[string][]int{}
key := 'odd'
value := 1
if _ := data[key] {
data[key] << value
} else {
data[key] = [value]
}
```
The same option check applies to arrays:
```v
arr := [1, 2, 3]
large_index := 999
val := arr[large_index] or { panic('out of bounds') }
println(val)
// you can also do this, if you want to *propagate* the access error:
val2 := arr[333]!
println(val2)
```
V also supports nested maps:
```v
mut m := map[string]map[string]int{}
m['greet'] = {
'Hello': 1
}
m['place'] = {
'world': 2
}
m['code']['orange'] = 123
print(m)
```
Maps are ordered by insertion, like dictionaries in Python. The order is a
guaranteed language feature. This may change in the future.
See all methods of
[map](https://modules.vlang.io/builtin.html#map)
and
[maps](https://modules.vlang.io/maps.html).
### Map update syntax
As with structs, V lets you initialise a map with an update applied on top of
another map:
```v
const base_map = {
'a': 4
'b': 5
}
foo := {
...base_map
'b': 88
'c': 99
}
println(foo) // {'a': 4, 'b': 88, 'c': 99}
```
This is functionally equivalent to cloning the map and updating it, except that
you don't have to declare a mutable variable:
```v failcompile
// same as above (except mutable)
mut foo := base_map.clone()
foo['b'] = 88
foo['c'] = 99
```
## Module imports
For information about creating a module, see [Modules](#modules).
Modules can be imported using the `import` keyword:
```v
import os
fn main() {
// read text from stdin
name := os.input('Enter your name: ')
println('Hello, ${name}!')
}
```
This program can use any public definitions from the `os` module, such
as the `input` function. See the [standard library](https://modules.vlang.io/)
documentation for a list of common modules and their public symbols.
By default, you have to specify the module prefix every time you call an external function.
This may seem verbose at first, but it makes code much more readable
and easier to understand - it's always clear which function from
which module is being called. This is especially useful in large code bases.
A function declared in the current module, or stored in a local variable, keeps its own
behavior even when it has the same name as a standard library function. For example,
`join_path('a', 'b')` calls that binding; `os.join_path('a', 'b')` calls the `os` function.
A local function binding also takes precedence inside the library module that defines
the same function name.
Cyclic module imports are not allowed, like in Go.
### Selective imports
You can also import specific functions and types from modules directly:
```v
import os { input }
fn main() {
// read text from stdin
name := input('Enter your name: ')
println('Hello, ${name}!')
}
```
> [!NOTE]
> This will import the module as well. Also, this is not allowed for
> constants - they must always be prefixed.
You can import several specific symbols at once:
```v
import os { input, user_os }
name := input('Enter your name: ')
println('Name: ${name}')
current_os := user_os()
println('Your OS is ${current_os}.')
```
### Module hierarchy
> [!NOTE]
> This section is valid when .v files are not in the project's root directory.
Modules names in .v files, must match the name of their directory.
A .v file `./abc/source.v` must start with `module abc`. All .v files in this directory
belong to the same module `abc`. They should also start with `module abc`.
If you have `abc/def/`, and .v files in both folders, you can `import abc`, but you will have
to `import abc.def` too, to get to the symbols in the subfolder. It is independent.
In `module name` statement, name never repeats directory's hierarchy, but only its directory.
So in `abc/def/source.v` the first line will be `module def`, and not `module abc.def`.
`import module_name` statements must respect file hierarchy, you cannot `import def`, only
`abc.def`
Referring to a module symbol such as a function or const, only needs module name as prefix:
```v ignore
module def
// func is a dummy example function.
pub fn func() {
println('func')
}
```
can be called like this:
```v ignore
module main
import def
fn main() {
def.func()
}
```
A function, located in `abc/def/source.v`, is called with `def.func()`, not `abc.def.func()`
This always implies a *single prefix*, whatever sub-module depth. This behavior flattens
modules/sub-modules hierarchy. Should you have two modules with the same name in different
directories, then you should use Module import aliasing (see below).
### Module import aliasing
Any imported module name can be aliased using the `as` keyword:
> [!NOTE]
> This example will not compile unless you have created `mymod/sha256/somename.v`
> (submodule names are determined by their path, not by the names of the .v file(s) in them).
```v failcompile
import crypto.sha256
import mymod.sha256 as mysha256
fn main() {
v_hash := sha256.sum('hi'.bytes()).hex()
my_hash := mysha256.sum('hi'.bytes()).hex()
assert my_hash == v_hash
}
```
A nested module such as `app.html` can import a distinct module named `net.html`, with or without
an alias. Their full module paths determine their identities.
A module cannot import its own full path, even when the project has no `v.mod` file.
You cannot alias an imported function or type.
However, you _can_ redeclare a type.
```v
import time
import math
type MyTime = time.Time
fn (mut t MyTime) century() int {
return int(1.0 + math.trunc(f64(t.year) * 0.009999794661191))
}
fn main() {
mut my_time := MyTime{
year: 2020
month: 12
day: 25
}
println(time.new(my_time).http_header_string())
println('Century: ${my_time.century()}')
}
```
## Statements & expressions
### If
```v
a := 10
b := 20
if a < b {
println('${a} < ${b}')
} else if a > b {
println('${a} > ${b}')
} else {
println('${a} == ${b}')
}
```
`if` statements are pretty straightforward and similar to most other languages.
Unlike other C-like languages,
there are no parentheses surrounding the condition and the braces are always required.
The condition cannot start with another `if`, not even a parenthesized one: store the result of
the inner `if` expression in a variable first.
When the condition starts with a `match` expression, parentheses are required around the
condition, for example `if (match enabled { true { false } else { true } }) { ... }`.
#### `If` expressions
Unlike C, V does not have a ternary operator, that would allow you to do: `x = c ? 1 : 2` .
Instead, it has a bit more verbose, but also clearer to read, ability to use `if` as an
expression. The direct translation in V of the ternary construct above, assuming `c` is a
boolean condition, would be: `x = if c { 1 } else { 2 }`.
Here is another example:
```v
num := 777
s := if num % 2 == 0 { 'even' } else { 'odd' }
println(s)
// "odd"
```
You can use multiple statements in each of the branches of an `if` expression, followed by a final
value, that will become the value of the entire `if` expression, when it takes that branch:
```v
n := arguments().len
x := if n > 2 {
dump(arguments())
42
} else {
println('something else')
100
}
dump(x)
```
When comparing an enum value with an `if` or `match` expression using `==` or `!=`,
the enum operand supplies the type for shorthand values such as `.red` in the branches.
This works with the enum operand on either side of the comparison.
Branch-local values keep their declared types; unrelated enum types cannot be compared this way.
Appending an `if` or `match` expression to an enum array also supplies the element type
for shorthand values in its branches. Every branch must produce a compatible enum value.
When the first branch has type `?T`, later branches may supply `T` or `none`.
A function returning `?void` supplies an optional value without a payload; it cannot replace
`none` in a branch that needs `?int` or another option with a payload.
An `if` or `match` expression stored as a function value may combine compatible functions
with `unsafe { nil }`. Branch-local variables retain their types: a `voidptr` variable
cannot be stored as a function value.
#### `If` unwrapping
Anywhere you can use `or {}`, you can also use "if unwrapping". This binds the unwrapped value
of an expression to a variable when that expression is not none nor an error.
An optional struct field can be unwrapped this way even after an earlier `none` check.
```v
m := {
'foo': 'bar'
}
// handle missing keys
if v := m['foo'] {
println(v) // bar
} else {
println('not found')
}
```
```v
fn res() !int {
return 42
}
// functions that return a result type
if v := res() {
println(v)
}
```
```v
struct User {
name string
}
arr := [User{'John'}]
// if unwrapping with assignment of a variable
u_name := if v := arr[0] {
v.name
} else {
'Unnamed'
}
println(u_name) // John
```
Use `if mut value := expression { ... }` when the unwrapped variable must be mutable,
for example to pass it to a `mut` parameter. The binding stays mutable throughout the
successful branch, including in `if` expressions and chained calls to generic functions
or methods. This applies to option/result, map lookup, array lookup, and channel receive guards.
Channel receive guards used as values also preserve a trailing `match` expression in either branch.
#### Type checks and casts
You can check the current type of a sum type using `is` and its negated form `!is`.
Note that the variable's declared type stays the sum type itself. In the example
below, `x` has the static type `Alphabet`, even though the value it holds is an
`Abc`. Inside an `is` check (or a `match` branch) the compiler automatically
*smart casts* `x` to the matched variant, so within that block `x` has the static
type `Abc` and you can access its fields directly and safely, without writing an
explicit `as` cast.
You can do it either in an `if`:
```v cgen
struct Abc {
val string
}
struct Xyz {
foo string
}
type Alphabet = Abc | Xyz
x := Alphabet(Abc{'test'}) // sum type
if x is Abc {
// x is automatically cast to Abc and can be used here
println(x)
}
if x !is Abc {
println('Not Abc')
}
```
or using `match`:
```v oksyntax
match x {
Abc {
// x is automatically cast to Abc and can be used here
println(x)
}
Xyz {
// x is automatically cast to Xyz and can be used here
println(x)
}
}
```
This works also with struct fields:
```v
struct MyStruct {
x int
}
struct MyStruct2 {
y string
}
type MySumType = MyStruct | MyStruct2
struct Abc {
bar MySumType
}
x := Abc{
bar: MyStruct{123} // MyStruct will be converted to MySumType type automatically
}
if x.bar is MyStruct {
// x.bar is automatically cast
println(x.bar)
} else if x.bar is MyStruct2 {
new_var := x.bar as MyStruct2
// ... or you can use `as` to create a type cast an alias manually:
println(new_var)
}
match x.bar {
MyStruct {
// x.bar is automatically cast
println(x.bar)
}
else {}
}
```
Mutable variables can change, and doing a cast would be unsafe.
However, sometimes it's useful to type cast despite mutability.
In such cases the developer must mark the expression with the `mut` keyword
to tell the compiler that they know what they're doing.
It works like this:
```v oksyntax
mut x := MySumType(MyStruct{123})
if mut x is MyStruct {
// x is cast to MyStruct even if it's mutable
// without the mut keyword that wouldn't work
println(x)
}
// same with match
match mut x {
MyStruct {
// x is cast to MyStruct even if it's mutable
// without the mut keyword that wouldn't work
println(x)
}
}
```
### Match
A match expression can return multiple values. A branch ending with comma-separated values can
be combined with a branch ending in a call that returns the same types.
Conditions that compare different nested fields remain distinct match cases, even when
their final field names and comparison operators are the same.
```v
os := 'windows'
print('V is running on ')
match os {
'darwin' { println('macOS.') }
'linux' { println('Linux.') }
else { println(os) }
}
```
A match statement is a shorter way to write a sequence of `if - else` statements.
When a matching branch is found, the following statement block will be run.
The else branch will be run when no other branches match.
```v
number := 2
s := match number {
1 { 'one' }
2 { 'two' }
else { 'many' }
}
```
A match statement can also to be used as an `if - else if - else` alternative:
```v
match true {
2 > 4 { println('if') }
3 == 4 { println('else if') }
2 == 2 { println('else if2') }
else { println('else') }
}
// 'else if2' should be printed
```
or as an `unless` alternative: [unless Ruby](https://www.tutorialspoint.com/ruby/ruby_if_else.htm)
```v
match false {
2 > 4 { println('if') }
3 == 4 { println('else if') }
2 == 2 { println('else if2') }
else { println('else') }
}
// 'if' should be printed
```
A match expression returns the value of the final expression from the matching branch.
A `match` expression can propagate results with `!` in its branches, including results
containing pointers to interfaces. A branch error propagates from the enclosing function.
Where a pointer to an interface is expected, such as `&Shape` or `?&Shape`, the branches
can return pointers to different types that implement that interface.
When inferring an enum result, a qualified value in the first branch, such as `Color.red`,
provides the type for shorthand values such as `.blue` in subsequent branches.
This also applies to parenthesized shorthand values and bitwise expressions with flag enums.
```v
enum Color {
red
blue
green
}
fn is_red_or_blue(c Color) bool {
return match c {
.red, .blue { true } // comma can be used to test multiple values
.green { false }
}
}
```
A match statement can also be used to branch on the variants of an `enum`
by using the shorthand `.variant_here` syntax. An `else` branch is not allowed
when all the branches are exhaustive.
```v
c := `v`
typ := match c {
`0`...`9` { 'digit' }
`A`...`Z` { 'uppercase' }
`a`...`z` { 'lowercase' }
else { 'other' }
}
println(typ)
// 'lowercase'
```
A match statement also can match the variant types of a `sumtype`. Note that
in that case, the match is exhaustive, since all variant types are mentioned
explicitly, so there is no need for an `else{}` branch.
```v nofmt
struct Dog {}
struct Cat {}
struct Veasel {}
type Animal = Dog | Cat | Veasel
a := Animal(Veasel{})
match a {
Dog { println('Bay') }
Cat { println('Meow') }
Veasel { println('Vrrrrr-eeee') } // see: https://www.youtube.com/watch?v=qTJEDyj2N0Q
}
```
You can also use ranges as `match` patterns. If the value falls within the range
of a branch, that branch will be executed.
Note that the ranges use `...` (three dots) rather than `..` (two dots). This is
because the range is *inclusive* of the last element, rather than exclusive
(as `..` ranges are). Using `..` in a match branch will throw an error.
```v
const start = 1
const end = 10
c := 2
num := match c {
start...end {
1000
}
else {
0
}
}
println(num)
// 1000
```
Constants can also be used in the range branch expressions.
> [!NOTE]
> `match` as an expression is not usable in `for` loop and `if` statements.
### In operator
`in` allows to check whether an array or a map contains an element.
To do the opposite, use `!in`.
```v
nums := [1, 2, 3]
println(1 in nums) // true
println(4 !in nums) // true
```
> [!NOTE]
> `in` checks if map contains a key, not a value.
```v
m := {
'one': 1
'two': 2
}
println('one' in m) // true
println('three' !in m) // true
```
It's also useful for writing boolean expressions that are clearer and more compact:
```v
enum Token {
plus
minus
div
mult
}
struct Parser {
token Token
}
parser := Parser{}
if parser.token == .plus || parser.token == .minus || parser.token == .div || parser.token == .mult {
// ...
}
if parser.token in [.plus, .minus, .div, .mult] {
// ...
}
```
V optimizes such expressions,
so both `if` statements above produce the same machine code and no arrays are created.
### For loop
V has only one looping keyword: `for`, with several forms.
#### `for`/`in`
This is the most common form. You can use it with an array, map or
numeric range.
The opening `{` of the loop body may appear on the next line after the iterable or range.
##### Array `for`
```v
numbers := [1, 2, 3, 4, 5]
for num in numbers {
println(num)
}
names := ['Sam', 'Peter']
for i, name in names {
println('${i}) ${name}')
// Output: 0) Sam
// 1) Peter
}
```
The `for value in arr` form is used for going through elements of an array.
If an index is required, an alternative form `for index, value in arr` can be used.
Note that the value is read-only.
If you need to modify the array while looping, you need to declare the element as mutable:
```v
mut numbers := [0, 1, 2]
for mut num in numbers {
num++
}
println(numbers) // [1, 2, 3]
```
By default, array elements are taken by value, if you need elements to be taken by
reference, use `&` on the array you want to iterate over:
```v
struct User {
name string
}
users := [User{
name: 'someuserwow99'
}, User{
name: 'visgod'
}]
// note `&users`, this is how a reference to the elements of the array is received
for user in &users {
// some operations with `user`
}
```
The same applies to maps.
When an identifier is just a single underscore, it is ignored.
##### Custom iterators
Types that implement a `next` method returning an `Option` can be iterated
with a `for` loop.
```v
struct SquareIterator {
arr []int
mut:
idx int
}
fn (mut iter SquareIterator) next() ?int {
if iter.idx >= iter.arr.len {
return none
}
defer {
iter.idx++
}
return iter.arr[iter.idx] * iter.arr[iter.idx]
}
nums := [1, 2, 3, 4, 5]
iter := SquareIterator{
arr: nums
}
for squared in iter {
println(squared)
}
```
The code above prints:
```
1
4
9
16
25
```
##### Map `for`
```v
m := {
'one': 1
'two': 2
}
for key, value in m {
println('${key} -> ${value}')
// Output: one -> 1
// two -> 2
}
```
A mutable map iteration value still has the map's element type. Assigning it to a map entry copies
that element, including when its struct type comes from another module.
When iterating a reference to a map (`for key, value in &m`), values with ordinary element types
are pointers to their entries. Assigning one to another variable preserves its reference to the
same entry. If the map element is already a pointer or an optional, the loop value keeps that
element type instead.
A pointer to a nested array or map remains a reference container when iterated again,
including through parentheses or a closure capture.
Fixed-array map values also refer to their entry storage, so changes through the reference update
the map value.
An enum entry reference can be compared with an enum value using `==` or `!=`, including
shorthand values such as `.on`. The comparison reads the referenced enum value; comparing two
enum pointers still compares their addresses.
Aliases of array and map pointers preserve these reference semantics, including pointer rebinding.
Parentheses around a mutable map container do not change whether assigning the loop value updates
its entry.
Mutable map parameters, including explicit pointer parameters (`mut m &map[K]V`),
keep ordinary value iteration. A mutable loop value writes through to the map entry.
A mutable pointer-valued loop argument can rebind the stored pointer, including through
parentheses, while a mutable struct argument updates the pointed-to struct.
Either key or value can be ignored by using a single underscore as the identifier.
```v
m := {
'one': 1
'two': 2
}
// iterate over keys
for key, _ in m {
println(key)
// Output: one
// two
}
// iterate over values
for _, value in m {
println(value)
// Output: 1
// 2
}
```
##### Range `for`
```v
// Prints '01234'
for i in 0 .. 5 {
print(i)
}
```
`low..high` means an *exclusive* range, which represents all values
from `low` up to *but not including* `high`.
> [!NOTE]
> This exclusive range notation and zero-based indexing follow principles of
logical consistency and error reduction. As Edsger W. Dijkstra outlines in
'Why Numbering Should Start at Zero'
([EWD831](https://www.cs.utexas.edu/users/EWD/transcriptions/EWD08xx/EWD831.html)),
zero-based indexing aligns the index with the preceding elements in a sequence,
simplifying handling and minimizing errors, especially with adjacent subsequences.
This logical and efficient approach shapes our language design, emphasizing clarity
and reducing confusion in programming.
#### Condition `for`
```v
mut sum := 0
mut i := 0
for i <= 100 {
sum += i
i++
}
println(sum) // "5050"
```
This form of the loop is similar to `while` loops in other languages.
The loop will stop iterating once the boolean condition evaluates to false.
Again, there are no parentheses surrounding the condition, and the braces are always required.
#### Bare `for`
```v
mut num := 0
for {
num += 2
if num >= 10 {
break
}
}
println(num) // "10"
```
The condition can be omitted, resulting in an infinite loop.
#### C `for`
```v
for i := 0; i < 10; i += 2 {
// Don't print 6
if i == 6 {
continue
}
println(i)
}
```
Finally, there's the traditional C style `for` loop. It's safer than the `while` form
because with the latter it's easy to forget to update the counter and get
stuck in an infinite loop.
Here `i` doesn't need to be declared with `mut` since it's always going to be mutable by definition.
#### Labelled break & continue
`break` and `continue` control the innermost `for` loop by default.
You can also use `break` and `continue` followed by a label name to refer to an outer `for`
loop:
```v
outer: for i := 4; true; i++ {
println(i)
for {
if i < 7 {
continue outer
} else {
break outer
}
}
}
```
The label must immediately precede the outer loop.
A labelled loop can iterate over a `filter` or `map` result; `break` and `continue`
refer to that loop after its iterable has been evaluated.
The above code prints:
```
4
5
6
7
```
### Defer
A `defer {}` statement, defers the execution of the block of statements
until the surrounding scope of the defer ends. It is a convenient feature
that allows you to group related actions (getting access to a resource
and cleaning/freeing it after you are done) closely together, instead
of spreading them across multiple potentially very remote lines of code.
A `defer` body inherits the `unsafe` context where it is written, including `defer(fn)`
bodies that run later outside that block. It may also contain its own explicit `unsafe` block.
An `unsafe` block at a later return does not make a previously declared safe `defer` unsafe.
```v
import os
fn read_log() ! {
mut ok := false
mut f := os.open('log.txt')!
defer { f.close() }
// ...
if !ok {
// ...
// defer statement will be called here, the file will be closed
return
}
// ...
// defer statement will be called here too, the file will be closed
}
```
If the function returns a value the `defer` block is executed *after* the return
expression is evaluated:
```v
import os
enum State {
normal
write_log
return_error
}
// write log file and return number of bytes written
fn write_log(s State) !int {
mut f := os.create('log.txt')!
defer {
f.close()
}
if s == .write_log {
// `f.close()` will be called after `f.write()` has been
// executed, but before `write_log()` finally returns the
// number of bytes written to `main()`
return f.writeln('This is a log file')
} else if s == .return_error {
// the file will be closed after the `error()` function
// has returned - so the error message will still report
// it as open
return error('nothing written; file open: ${f.is_opened}')
}
// the file will be closed here, too
return 0
}
fn main() {
n := write_log(.return_error) or {
println('Error: ${err}')
0
}
println('${n} bytes written')
}
```
To access the result of the function inside a `defer` block the `$res()` expression can be used.
`$res()` is only used when a single value is returned, while on multi-return the `$res(idx)`
is parameterized.
```v ignore
fn (mut app App) auth_middleware() bool {
defer {
if !$res() {
app.response.status_code = 401
app.response.body = 'Unauthorized'
}
}
header := app.get_header('Authorization')
if header == '' {
return false
}
return true
}
fn (mut app App) auth_with_user_middleware() (bool, string) {
defer {
if !$res(0) {
app.response.status_code = 401
app.response.body = 'Unauthorized'
} else {
app.user = $res(1)
}
}
header := app.get_header('Authorization')
if header == '' {
return false, ''
}
return true, 'TestUser'
}
```
#### defer in loop scopes:
Defer can be used inside loops too, and the deferred statement will be executed once for each
iteration. You can also have multiple defer statements in the same scope, in which case, they
will be executed in reverse order of their appearance in the source code:
```v
fn main() {
defer { println('Program finish.') }
println('Loop start.')
for i in 1 .. 4 {
defer { println('Deferred execution for ${i}. Defer 1.') }
defer { println('Deferred execution for ${i}. Defer 2.') }
defer { println('Deferred execution for ${i}. Defer 3.') }
println('Loop iteration: ${i}')
}
println('Loop done.')
}
```
The example will print this:
```txt
Loop start.
Loop iteration: 1
Deferred execution for 1. Defer 3.
Deferred execution for 1. Defer 2.
Deferred execution for 1. Defer 1.
Loop iteration: 2
Deferred execution for 2. Defer 3.
Deferred execution for 2. Defer 2.
Deferred execution for 2. Defer 1.
Loop iteration: 3
Deferred execution for 3. Defer 3.
Deferred execution for 3. Defer 2.
Deferred execution for 3. Defer 1.
Loop done.
Program finish.
```
#### defer(fn) {}
Note, that in most of the examples above, the `defer{}` statement was directly inside
a function scope, so it was executed when the function itself returned. Sometimes, you
need to defer a statement to execute right at the function end (like the above), even
if you are inside an inner scope (deep inside an `if` or `for`).
For these more rare cases, you can use: `defer(fn) {}` instead of just `defer {}`.
#### Recovering from panics
A panic runs the pending `defer` blocks of every function on the stack, newest
first. Calling `recover()` directly in one of these blocks stops the panic, and
returns its message. The function that deferred the block then runs its other
deferred blocks, and returns normally, with the zero value of its result type.
This works like `recover` in Go.
```v
fn parse_age(s string) int {
defer {
if msg := recover() {
eprintln('invalid age ${s}: ${msg}')
}
}
age := s.int()
if age < 0 {
panic('negative age')
}
return age
}
fn main() {
println(parse_age('42')) // 42
println(parse_age('-1')) // 0, after printing `invalid age -1: negative age`
}
```
`recover()` returns `none` when there is no panic, and when it is not called
directly in a deferred block that runs because of the panic (for example, in a
function that such a block calls). A block can also run cleanup code without
calling `recover()`: the panic then goes on to the callers, and if nothing
recovers it, the program prints the message and exits once all deferred blocks
ran. Runtime errors that panic, like an array index out of range, can be
recovered as well. Signals, like a segmentation fault, cannot.
### Goto
V allows unconditionally jumping to a label with `goto`. The label name must be contained
within the same function as the `goto` statement. A program may `goto` a label outside
or deeper than the current scope. `goto` allows jumping past variable initialization or
jumping back to code that accesses memory that has already been freed, so it requires
`unsafe`.
```v ignore
if x {
// ...
if y {
unsafe {
goto my_label
}
}
// ...
}
my_label:
```
`goto` should be avoided, particularly when `for` can be used instead.
[Labelled break/continue](#labelled-break--continue) can be used to break out of
a nested loop, and those do not risk violating memory-safety.
## Structs
Concrete struct names can be a single capital letter, such as `M`. Functions can return these
structs directly, as results (`!M`), or as options (`?M`).
```v
struct Point {
x int
y int
}
mut p := Point{
x: 10
y: 20
}
println(p.x) // Struct fields are accessed using a dot
// Alternative positional syntax; values follow the field declaration order.
p = Point{10, 20}
assert p.x == 10
```
Struct fields can re-use reserved keywords, including C keywords such as `bool`:
```v
struct Employee {
type string
name string
}
employee := Employee{
type: 'FTE'
name: 'John Doe'
}
println(employee.type)
```
### Heap structs
Structs are allocated on the stack. To allocate a struct on the heap
and get a [reference](#references) to it, use the `&` prefix:
```v
struct Point {
x int
y int
}
p := &Point{10, 10}
// References have the same syntax for accessing fields
println(p.x)
```
The type of `p` is `&Point`. It's a [reference](#references) to `Point`.
References are similar to Go pointers and C++ references.
```v
struct Foo {
mut:
x int
}
fa := Foo{1}
mut a := fa
a.x = 2
assert fa.x == 1
assert a.x == 2
// fb := Foo{ 1 }
// mut b := &fb // error: `fb` is immutable, cannot have a mutable reference to it
// b.x = 2
mut fc := Foo{1}
mut c := &fc
c.x = 2
assert fc.x == 2
assert c.x == 2
println(fc) // Foo{ x: 2 }
println(c) // &Foo{ x: 2 } // Note `&` prefixed.
```
see also [Stack and Heap](#stack-and-heap)
### Default field values
```v
struct Foo {
n int // n is 0 by default
s string // s is '' by default
a []int // a is `[]int{}` by default
pos int = -1 // custom default value
}
```
All struct fields are zeroed by default during the creation of the struct.
Array and map fields are allocated.
In case of reference value, see [here](#structs-with-reference-fields).
It's also possible to define custom default values.
A keyword-named field can follow a default value on the next line:
```v
struct Settings {
enabled bool = true
in string
}
```
The same rule applies to defaults such as `match` expressions, including fields named `or`.
### Required fields
```v
struct Foo {
n int @[required]
}
```
You can mark a struct field with the `[required]` [attribute](#attributes), to tell V that
that field must be initialized when creating an instance of that struct.
This example will not compile, since the field `n` isn't explicitly initialized:
```v failcompile
_ = Foo{}
```
### Short struct literal syntax
Here "short" means omitting the field names and relying on the struct field
order, so `Point{10, 20}` is a shorter form of `Point{x: 10, y: 20}`.
For imported struct types, both forms report an unknown type using its qualified name
and the same suggestions. Dots in field values do not affect which type name is highlighted.
```v
struct Point {
x int
y int
}
long_form := Point{
x: 30
y: 4
}
short_form := Point{30, 4}
assert short_form == long_form
// Arrays still use `Point{...}` for each element.
// The short part is omitting field names, not the struct type name.
points := [Point{10, 20}, Point{20, 30}, Point{40, 50}]
println(points) // [Point{x: 10, y: 20}, Point{x: 20, y: 30}, Point{x: 40,y: 50}]
```
When the expected type is already known, V can also omit the struct name entirely
when returning a struct literal or passing one as a function argument. That is a
separate shorthand from the positional `Point{10, 20}` syntax above.
### Struct update syntax
V makes it easy to return a modified version of an object:
```v
struct User {
name string
age int
is_registered bool
}
fn register(u User) User {
return User{
...u
is_registered: true
}
}
mut user := User{
name: 'abc'
age: 23
}
user = register(user)
println(user)
```
A struct update can also spread a different struct type when the source supplies compatible
fields for every target field that is not explicitly initialized. An embedded struct can be
supplied by explicitly initializing all of its members through their promoted field names:
```v
struct Position {
x int
y int
}
struct ButtonConfig {
width int
}
struct Button {
Position
width int
}
config := ButtonConfig{
width: 80
}
button := Button{
...config
x: 10
y: 20
}
assert button.width == 80
assert button.Position.x == 10
assert button.Position.y == 20
```
Here `config` supplies `width`, while `x` and `y` fully initialize `Position`. If either member
is omitted, the source must instead supply a compatible `Position` field. Declared defaults do
not count as explicit initializers for this requirement. The same rule applies to nested embeds.
Only the embedded field that a promoted name refers to counts as supplied. A direct field
shadows an embedded field of the same name, and a name owned by an earlier embedding cannot also
initialize a later embedding. Use an explicit embedded-struct initializer for shadowed members.
### Trailing struct literal arguments
V doesn't have default function arguments or named arguments, for that trailing struct
literal syntax can be used instead:
```v
@[params]
struct ButtonConfig {
text string
is_disabled bool
width int = 70
height int = 20
}
struct Button {
text string
width int
height int
}
fn new_button(c ButtonConfig) &Button {
return &Button{
width: c.width
height: c.height
text: c.text
}
}
button := new_button(text: 'Click me', width: 100)
// the height is unset, so it's the default value
assert button.height == 20
```
As you can see, both the struct name and braces can be omitted, instead of:
```v oksyntax nofmt
new_button(ButtonConfig{text:'Click me', width:100})
```
This only works for functions that take a struct for the last argument.
> [!NOTE]
> Note the `[params]` tag is used to tell V, that the trailing struct parameter
> can be omitted *entirely*, so that you can write `button := new_button()`.
> Without it, you have to specify *at least* one of the field names, even if it
> has its default value, otherwise the compiler will produce this error message,
> when you call the function with no parameters:
> `error: expected 1 arguments, but got 0`.
### Access modifiers
Struct fields are private and immutable by default (making structs immutable as well).
Their access modifiers can be changed with
`pub` and `mut`. In total, there are 5 possible options:
```v
struct Foo {
a int // private immutable (default)
mut:
b int // private mutable
c int // (you can list multiple fields with the same access modifier)
pub:
d int // public immutable (readonly)
pub mut:
e int // public, but mutable only in parent module
__global:
// (not recommended to use, that's why the 'global' keyword starts with __)
f int // public and mutable both inside and outside parent module
}
```
Access modifiers can also be written before individual fields to preserve their declaration order:
```v
struct Record {
a int
mut b int
pub c int
pub mut d int
}
```
An inline `pub`, `mut`, or `pub mut` applies only to that field (or comma-separated field group).
It overrides the current section for that declaration; following fields still use the section's
modifiers. Without a section, following fields remain private and immutable.
`v fmt` preserves inline modifiers and aligns their field types.
Private fields are available only inside the same [module](#modules), any attempt
to directly access them from another module will cause an error during compilation.
Public immutable fields are readonly everywhere.
A public function can return a value of a private struct type. The caller can read its public
fields without naming the private type; its private fields remain inaccessible.
### Anonymous structs
V supports anonymous structs: structs that don't have to be declared separately
with a struct name.
```v
struct Book {
author struct {
name string
age int
}
title string
}
book := Book{
author: struct {
name: 'Samantha Black'
age: 24
}
}
assert book.author.name == 'Samantha Black'
assert book.author.age == 24
```
### Static type methods
V now supports static type methods like `User.new()`. These are defined on a struct via
`fn [Type name].[function name]` and allow to organize all functions related to a struct:
```v oksyntax
struct User {}
fn User.new() User {
return User{}
}
user := User.new()
```
This is an alternative to factory functions like `fn new_user() User {}` and should be used
instead.
Static type methods can also be used as function values by omitting the call parentheses,
such as `make_user := User.new`. A field selector rooted in a local variable, constant, or
global reads that value's field; it does not name a static type method.
A static type method and an instance method can share a name. `User.draw(...)` calls the
static method, while `user.draw(...)` calls the instance method. Each method has its own
visibility: a `pub fn User.draw(...)` is accessible from other modules as
`module_name.User.draw(...)`, even when the instance method `draw` is private.
Instance methods can also be used as unbound function values, such as `f := User.register`.
The receiver becomes the first parameter, so a mutable receiver is passed as `f(mut user)`.
Inside a method reflection loop, `T.$method` likewise creates an unbound function value.
Unbound and reflected method values follow the same method privacy and `mut` argument rules.
A reflected method bound to an instance, such as `f := app.$method`, can be stored in an array
like other function values.
> [!NOTE]
> Note, that these are not constructors, but simple functions. V doesn't have constructors or
> classes.
### `[noinit]` structs
V supports `[noinit]` structs, which are structs that cannot be initialised outside the module
they are defined in. They are either meant to be used internally or they can be used externally
through _factory functions_.
The restriction applies to empty literals and literals with explicit fields, including aliases
and concrete generic instances of the struct.
For an example, consider the following source in a directory `sample`:
```v oksyntax
module sample
@[noinit]
pub struct Information {
pub:
data string
}
pub fn new_information(data string) !Information {
if data.len == 0 || data.len > 100 {
return error('data must be between 1 and 100 characters')
}
return Information{
data: data
}
}
```
Note that `new_information` is a _factory_ function. Now when we want to use this struct
outside the module:
```v okfmt
import sample
fn main() {
// This doesn't work when the [noinit] attribute is present:
// info := sample.Information{
// data: 'Sample information.'
// }
// Use this instead:
info := sample.new_information('Sample information.')!
println(info)
}
```
### Methods
```v
struct User {
age int
}
fn (u User) can_register() bool {
return u.age > 16
}
user := User{
age: 10
}
println(user.can_register()) // "false"
user2 := User{
age: 20
}
println(user2.can_register()) // "true"
```
V doesn't have classes, but you can define methods on types.
A method is a function with a special receiver argument.
The receiver appears in its own argument list between the `fn` keyword and the method name.
Methods must be in the same module as the receiver type.
This also applies to receivers with any number of pointer levels
and to types imported under another name.
To add methods for an imported type, declare a local type alias and use it as the receiver.
For a generic receiver such as `other.Box[T]`, the alias must also declare its type parameters:
`type LocalBox[T] = other.Box[T]`. Use `LocalBox[T]` as the receiver and repeat `T` in the method's
generic parameter list.
In this example, the `can_register` method has a receiver of type `User` named `u`.
The convention is not to use receiver names like `self` or `this`,
but a short, preferably one letter long, name.
### Embedded structs
Promoted fields from different nested embeds can be initialized together. Their shared parent
is initialized once, retaining the explicitly supplied fields and defaults for omitted fields.
V supports embedded structs.
```v
struct Size {
mut:
width int
height int
}
fn (s &Size) area() int {
return s.width * s.height
}
struct Button {
Size
title string
}
```
With embedding, the struct `Button` will automatically get all the fields and methods from
the struct `Size`, which allows you to do:
```v oksyntax
mut button := Button{
title: 'Click me'
height: 2
}
button.width = 3
assert button.area() == 6
assert button.Size.area() == 6
print(button)
```
output :
```
Button{
Size: Size{
width: 3
height: 2
}
title: 'Click me'
}
```
Unlike inheritance, you cannot type cast between structs and embedded structs
(the embedding struct can also have its own fields, and it can also embed multiple structs).
If you need to access embedded structs directly, use an explicit reference like `button.Size`.
Optional fields keep their optional type when accessed through multiple embedded structs.
You can unwrap them with an `if` guard, including after an earlier check against `none`.
Omitted embedded structs retain their declared field defaults, including interface values.
Conceptually, embedded structs are similar to [mixin](https://en.wikipedia.org/wiki/Mixin)s
in OOP, *NOT* base classes.
You can also initialize an embedded struct:
```v oksyntax
mut button := Button{
Size: Size{
width: 3
height: 2
}
}
```
or assign values:
```v oksyntax
button.Size = Size{
width: 4
height: 5
}
```
If multiple embedded structs have methods or fields with the same name, or if methods or fields
with the same name are defined in the struct, you can call methods or assign to variables in
the embedded struct like `button.Size.area()`.
When you do not specify the embedded struct name, the method of the outermost struct will be
targeted.
## Unions
A union is a special type of struct that allows storing different data types in the same memory
location. You can define a union with many members, but only one member may contain a valid value
at any time, depending on the data types of the members. Unions provide an efficient way of using
the same memory location for multiple purposes.
All the members of a union share the same memory location. This means that modifying one member
automatically modifies all the rest. The largest union member defines the size of the union.
When constructing a union that contains interface storage, V clears the entire storage before
initializing the selected member. This also applies to interfaces inside nested union members.
An inactive interface member with no valid type tag formats as `unknown interface value`.
Accessing an inactive member still requires `unsafe` and does not create a valid interface value.
### Why use unions?
One reason, as stated above, is to use less memory for storing things. Since the size of a union
is the size of the largest field in it, and the size of a struct is the size of all the fields in
the struct added together, a union is definitely better for lower memory usage. As long as you
only need one of the fields to be valid at any time, the union wins.
Another reason is to allow easier access to parts of a field. For example, without using a union,
if you want to look at each of the bytes of a 32-bit integer separately, you'll need bitwise
`RIGHT-SHIFT`s and `AND` operations. With a union, you can access the individual bytes directly.
```v
union ThirtyTwo {
a u32
b [4]u8
}
```
Since `ThirtyTwo.a` and `ThirtyTwo.b` share the same memory locations, you can directly access
each byte of `a` by referencing `b[byte_offset]`.
### Embedding
Unions also support embedding, the same as structs.
```v
struct Rgba32_Component {
r u8
g u8
b u8
a u8
}
union Rgba32 {
Rgba32_Component
value u32
}
clr1 := Rgba32{
value: 0x008811FF
}
clr2 := Rgba32{
Rgba32_Component: Rgba32_Component{
a: 128
}
}
sz := sizeof(Rgba32)
unsafe {
println('Size: ${sz}B,clr1.b: ${clr1.b},clr2.b: ${clr2.b}')
}
```
Output: `Size: 4B, clr1.b: 136, clr2.b: 0`
Union member access must be performed in an `unsafe` block.
> [!NOTE]
> Embedded struct arguments are not necessarily stored in the order listed.
## Functions 2
### Immutable function args by default
In V function arguments are immutable by default, and mutable args have to be
marked on call.
Since there are also no globals, that means that the return values of the functions,
are a function of their arguments only, and their evaluation has no side effects
(unless the function uses I/O).
Function arguments are immutable by default, even when [references](#references) are passed.
An array returned from an immutable argument remains immutable, including when returned through
a local function value, a narrowed `if` or `match` branch, or after an exiting `if` guard.
Use `.clone()` for a mutable copy.
A cloned map has separate entry storage. After replacing a copied struct's map field with
a clone, replacing entries leaves the original map unchanged. The compiler may reject such
writes if a reference to the containing struct could rebind the field, including references
taken before the clone. A callback that may rebind a map also prevents subsequent entry writes
from being treated as independent of the original; a callback that shadows the enclosing
function's name still counts as a callback.
A pointer returned through a callback can still refer to an immutable argument, even if the
callback returns `voidptr`. Converting that result to a typed reference does not make the
underlying object mutable. Different pointee types do not prove separate storage: a `voidptr`
can erase the type of an existing reference. For an opaque container lookup that guarantees
separate mutable component storage, place the conversion in `unsafe { ... }`. The caller must
ensure the returned pointer does not provide mutable access to an immutable argument.
When a readable function returns a stored pointer to separate storage, or newly allocated storage
that contains no references or other shared storage from its arguments, the returned reference does
not borrow the containing object or the function's other arguments. A new outer object can still
borrow an argument through a reference-bearing field, such as `&Box{item: item}`.
A scalar passed by value to a callback is independent of the caller's storage. If a callback
parameter is a reference, an implicitly referenced scalar remains borrowed from its immutable
argument; the scalar's expression type alone does not establish a by-value copy.
Scalar fields supplied with collapsed struct argument syntax and scalar elements decomposed
into by-value parameters are copied too. Pointer fields and elements can still share storage.
> [!NOTE]
> However, V is not a purely functional language.
There is a compiler flag to enable global variables (`-enable-globals`), but this is
intended for low-level applications like kernels and drivers.
### Mutable arguments
It is possible to modify function arguments by declaring them with the keyword `mut`:
A method with a `mut` receiver requires a mutable value receiver even when it only
changes private fields in another module. An immutable value parameter cannot call
such a method: mutations would affect its copy and be lost when the function returns.
Declare the parameter or receiver with `mut` when its changes must reach the caller.
An explicit `mut param &T` takes mutable pointer storage. Passing `mut &value`
creates temporary pointer storage for that call, including when `value` is a
`mut value T` parameter. Changes to fields reach `value`; rebinding the temporary
pointer does not rebind the caller's value.
```v
struct User {
name string
mut:
is_registered bool
}
fn (mut u User) register() {
u.is_registered = true
}
mut user := User{}
println(user.is_registered) // "false"
user.register()
println(user.is_registered) // "true"
```
In this example, the receiver (which is just the first argument) is explicitly marked as mutable,
so `register()` can change the user object. The same works with non-receiver arguments:
```v
fn multiply_by_2(mut arr []int) {
for i in 0 .. arr.len {
arr[i] *= 2
}
}
mut nums := [1, 2, 3]
multiply_by_2(mut nums)
println(nums)
// "[2, 4, 6]"
```
Note that you have to add `mut` before `nums` when calling this function. This makes
it clear that the function being called will modify the value.
A comptime `app.$method(...)` call also requires `mut` when passing a pointer variable
to an explicit `mut param &T` parameter.
A mutable struct parameter refers to the caller's struct. Casting it to an integer
produces that struct's address.
It is preferable to return values instead of modifying arguments,
e.g. `user = register(user)` (or `user.register()`) instead of `register(mut user)`.
Modifying arguments should only be done in performance-critical parts of your application
to reduce allocations and copying.
For this reason V doesn't allow the modification of arguments with primitive types (e.g. integers).
Only more complex types such as arrays and maps may be modified.
### Variable number of arguments
V supports functions that receive an arbitrary, variable amounts of arguments, denoted with the
`...` prefix.
Below, `a ...int` refers to an arbitrary amount of parameters that will be collected
into an array named `a`.
Methods on generic structs can also accept these arguments. The receiver type determines
the specialization, and the arguments are collected into the parameter array.
The element type keeps its declaring module when the method is called from another module.
```v
fn sum(a ...int) int {
mut total := 0
for x in a {
total += x
}
return total
}
println(sum()) // 0
println(sum(1)) // 1
println(sum(2, 3)) // 5
// using array decomposition
a := [2, 3, 4]
println(sum(...a)) // <-- using prefix ... here. output: 9
b := [5, 6, 7]
println(sum(...b)) // output: 18
```
### Anonymous & higher order functions
Calling a function parameter or local function variable uses that binding, even when
another module defines a function constant with the same name.
```v
fn sqr(n int) int {
return n * n
}
fn cube(n int) int {
return n * n * n
}
fn run(value int, op fn (int) int) int {
return op(value)
}
fn main() {
// Functions can be passed to other functions
println(run(5, sqr)) // "25"
// Anonymous functions can be declared inside other functions:
double_fn := fn (n int) int {
return n + n
}
println(run(5, double_fn)) // "10"
// Functions can be passed around without assigning them to variables:
res := run(5, fn (n int) int {
return n + n
})
println(res) // "10"
// You can even have an array/map of functions:
fns := [sqr, cube]
println(fns[0](10)) // "100"
fns_map := {
'sqr': sqr
'cube': cube
}
println(fns_map['cube'](2)) // "8"
}
```
### Lambda expressions
Lambda expressions in V are small anonymous functions, defined using
the `|variables| expression` syntax. Note: this syntax is valid only inside calls to higher
order functions.
Here are some examples:
```v
mut a := [1, 2, 3]
a.sort(|x, y| x > y) // sorts the array, defining the comparator with a lambda expression
println(a.map(|x| x * 10)) // prints [30, 20, 10]
```
```v
// Lambda function can be used as callback
fn f(cb fn (a int) int) int {
return cb(10)
}
println(f(|x| x + 4)) // prints 14
```
Function values passed to generic methods are checked by their parameter and return types.
Parameter names and whitespace do not affect function type compatibility.
### Closures
An instance method can be used as an unbound function value through its type, such as
`App.method`. Its first parameter is the receiver, including the receiver's `&` or `mut`
modifier. This form captures no receiver and creates no closure. The same applies to
`T.$method` inside a compile-time loop over `T.methods`.
Callbacks in specialized generic functions retain the functions they call, including imported
functions referenced only from the callback body.
V supports closures too.
This means that anonymous functions can inherit variables from the scope they were created in.
They must do so explicitly by listing all variables that are inherited.
Each anonymous function has its own local scope. Locals, including `for` iteration variables,
may reuse names of enclosing variables that are not captured.
```v oksyntax
my_int := 1
my_closure := fn [my_int] () {
println(my_int)
}
my_closure() // prints 1
```
Inherited variables are copied when the anonymous function is created.
This means that if the original variable is modified after the creation of the function,
the modification won't be reflected in the function.
```v oksyntax
mut i := 1
func := fn [i] () int {
return i
}
println(func() == 1) // true
i = 123
println(func() == 1) // still true
```
However, the captured copy can be modified inside the anonymous function.
`mut` only makes the closure's copy mutable; it does not capture the original
variable by reference. The change won't be reflected outside, but will be in
later function calls.
This also applies to captured arrays, maps, and structs. For example,
`fn [mut files]` inside `os.walk(...)` will modify the closure's `files` copy,
not the outer `files` variable.
```v oksyntax
fn new_counter() fn () int {
mut i := 0
return fn [mut i] () int {
i++
return i
}
}
c := new_counter()
println(c()) // 1
println(c()) // 2
println(c()) // 3
```
A callback's captured values remain available while the callback is stored in a
struct field, including when that field is assigned through a pointer to the struct.
If you need the value to be modified outside the function, use a reference.
Capturing a `mut` parameter preserves its reference to the caller's value, including when the
closure passes it to a spawned function.
```v oksyntax
mut i := 0
mut ref := &i
print_counter := fn [ref] () {
println(*ref)
}
print_counter() // 0
i = 10
print_counter() // 10
```
For callbacks like `os.walk`, use `os.walk_with_context` when the callback
needs to update caller-owned state:
```v oksyntax
import os
mut files := []string{}
os.walk_with_context('.', &files, fn (mut files []string, file string) {
files << file
})
println(files.len > 0)
```
### Parameter evaluation order
The evaluation order of the parameters of function calls is *NOT* guaranteed.
Take for example the following program:
```v
fn f(a1 int, a2 int, a3 int) {
dump(a1 + a2 + a3)
}
fn main() {
f(dump(100), dump(200), dump(300))
}
```
V currently does not guarantee that it will print 100, 200, 300 in that order.
The only guarantee is that 600 (from the body of `f`) will be printed after all of them.
This *may* change in V 1.0 .
## References
Pointers to concrete values can be passed to optional interface parameters when their types
implement the interface. The option contains an interface value referring to the original object.
Additional pointer layers, such as `&&Record`, must be dereferenced before passing the object.
Pointers to interface values, such as `&Named`, must also be dereferenced first.
Parentheses around a concrete value or pointer also work when assigning or returning an optional
or result interface; the conversion is applied once.
Returning a stored pointer field returns that pointer value. It does not borrow the storage of
the containing struct, unlike taking the address of one of its fields.
```v
struct Foo {}
fn (foo Foo) bar_method() {
// ...
}
fn bar_function(foo Foo) {
// ...
}
```
If a function argument is immutable (like `foo` in the examples above)
V can pass it either by value or by reference. The compiler will decide,
and the developer doesn't need to think about it.
You no longer need to remember whether you should pass the struct by value
or by reference.
You can ensure that the struct is always passed by reference by
adding `&`:
```v
struct Foo {
abc int
}
fn (foo &Foo) bar() {
println(foo.abc)
}
```
`foo` is still immutable and can't be changed. For that,
`(mut foo Foo)` must be used.
When immutable reference parameters to structs are compared with `==` or `!=`,
V compares their addresses, not their fields. Dereference the parameters explicitly
to compare their values instead:
```v
struct Point {
x int
}
fn same_reference(a &Point, b &Point) bool {
return a == b
}
fn same_value(a &Point, b &Point) bool {
return *a == *b
}
a := Point{
x: 1
}
b := Point{
x: 1
}
assert !same_reference(a, b)
assert same_reference(a, a)
assert same_value(a, b)
```
This address-comparison rule also applies when reference parameters are captured by
a closure or their reference types are written through aliases. A user-defined `==`
operator takes precedence over the default address or value comparison.
In general, V's references are similar to Go pointers and C++ references.
For example, a generic tree structure definition would look like this:
```v
struct Node[T] {
val T
left &Node[T]
right &Node[T]
}
```
To dereference a reference, use the `*` operator, just like in C.
## Constants
A constant can be qualified with its module name inside that module, including in module tests.
A fixed array constant can be initialized by a function call; the call runs during initialization.
Sum type constants with aggregate variants are initialized at startup, including when compiling
with GCC.
Their resolved sum type remains the same when an import alias shares its module prefix.
```v
const pi = 3.14
const world = '世界'
println(pi)
println(world)
```
Constants are declared with `const`. They can only be defined
at the module level (outside of functions).
Global variables can infer their types from constants, including constants initialized by functions.
Global pointers to fixed-array literals are initialized at startup, including nested elements
computed by function calls.
Constant values can never be changed. You can also declare a single
constant separately:
```v
const e = 2.71828
```
A constant initializer may call a function with the same name, such as `const answer = answer()`.
Reading the constant itself in its initializer is still a cycle.
Dependencies in initializer expressions and helper calls are resolved in the initializer's module
and source file. This context is preserved when initialization waits for another constant.
V constants are more flexible than in most languages. You can assign more complex values:
```v
struct Color {
r int
g int
b int
}
fn rgb(r int, g int, b int) Color {
return Color{
r: r
g: g
b: b
}
}
const numbers = [1, 2, 3]
const red = Color{
r: 255
g: 0
b: 0
}
// evaluate function call at compile time*
const blue = rgb(0, 0, 255)
println(numbers)
println(red)
println(blue)
```
\* WIP - for now function calls are evaluated at program start-up
Global variables are not normally allowed, so this can be really useful.
**Modules**
Constants can be made public with `pub const`:
```v oksyntax
module mymodule
pub const golden_ratio = 1.61803
fn calc() {
println(golden_ratio)
}
```
The `pub` keyword is only allowed before the `const` keyword and cannot be used inside
a `const ( )` block.
Constants can be referenced without a module prefix from within the module where they are
defined. To access a public constant from another module, prefix it with the module name.
### Required module prefix
When naming constants, `snake_case` must be used. Outside the module where a constant is
defined, its full path must be specified. For example, use `math.pi` to access the public
`pi` constant from another module. Inside the `math` module, the unqualified name `pi` can
be used.
## Builtin functions
Some functions are builtin like `println`. Here is the complete list:
```v ignore
fn print(s string) // prints anything on stdout
fn println(s string) // prints anything and a newline on stdout
fn eprint(s string) // same as print(), but uses stderr
fn eprintln(s string) // same as println(), but uses stderr
fn exit(code int) // terminates the program with a custom error code
fn panic(s string) // prints a message and backtraces on stderr, and terminates the program with error code 1
fn recover() ?string // stops a panic from a `defer` block, see [Recovering from panics](#recovering-from-panics)
fn print_backtrace() // prints backtraces on stderr
```
> [!NOTE]
> Although the `print` functions take a string, V accepts other printable types too.
> See below for details.
There is also a special built-in function called [`dump`](#dumping-expressions-at-runtime).
### println
`println` is a simple yet powerful builtin function, that can print anything:
strings, numbers, arrays, maps, structs.
```v
struct User {
name string
age int
}
println(1) // "1"
println('hi') // "hi"
println([1, 2, 3]) // "[1, 2, 3]"
println(User{ name: 'Bob', age: 20 }) // "User{name:'Bob', age:20}"
```
See also [String interpolation](#string-interpolation).
### Printing custom types
Automatic string conversion also works for values whose local name was used for a reference in
an earlier scope.
Recursive sum types print nested values, including repeated types and shared payloads.
An actual circular reference is shown as `