v2 / doc / docs.md
9001 lines · 7059 sloc · 238.97 KB · 37513121a31460af1448cbe957f474d30e6f0516
Raw

V Documentation

(See https://modules.vlang.io/ for documentation of V's standard library) (See also https://docs.vlang.io/introduction.html, which has the same information as this document, but split in separate pages for each section, for easier reading on mobile devices)

Introduction

V is a statically typed compiled programming language designed for building maintainable software.

It's similar to Go and its design has also been influenced by Oberon, Rust, Swift, Kotlin, and Python.

V is a very simple language. Going through this documentation will take you about a weekend, and by the end of it you will have pretty much learned the entire language.

The language promotes writing simple and clear code with minimal abstraction.

Despite being simple, V gives the developer a lot of power. Anything you can do in other languages, you can do in V.

Language specification

V does not yet have a separate formal language specification document like the Go spec.

Until V 1.0, the language reference is defined by:

Installing V from source

The best way to get the latest and greatest V, is to install it from source. It is easy, and it takes only a few seconds:

git clone --depth=1 https://github.com/vlang/v
cd v
make

Note: If you are on windows, outside of WSL, run makev.bat instead of make, in a CMD shell. Note: On Ubuntu/Debian, you may need to run sudo apt install git build-essential make first.

For more details, see the Installing V section in the README.md.

Upgrading V to latest version

If V is already installed on a machine, it can be upgraded to its latest version by using the V's built-in self-updater. To do so, run the command v up.

Project-local compiler versions with .vvmrc

If a project contains a .vvmrc file, commands like v run ., v run file.v, or v file.v will try to find and delegate to the requested V compiler version. This makes it easier to keep a project pinned to a known compiler release.

The file should contain one version per project, for example:

0.4.12

Both 0.4.12 and v0.4.12 are accepted. The special aliases latest and current keep using the currently running compiler.

V searches for .vvmrc from the target path upward and stops at repository and project boundaries such as .git, .hg, .svn, and .v.mod.stop.

Packaging V for distribution

See the notes on how to prepare a package for V .

Getting started

You can let V automatically set up the bare-bones structure of a project for you by using any of the following commands in a terminal:

Table of Contents

Hello World

fn main() {
    println('hello world')
}

Save this snippet into a file named hello.v. Now do: v run hello.v.

That is assuming you have symlinked your V with v symlink, as described here. If you haven't yet, you have to type the path to V manually.

Congratulations - you just wrote and executed your first V program!

You can compile a program without execution with v hello.v. See v help for all supported commands.

From the example above, you can see that functions are declared with the fn keyword. The return type is specified after the function name. In this case main doesn't return anything, so there is no return type.

As in many other languages (such as C, Go, and Rust), main is the entry point of your program.

println is one of the few built-in functions. It prints the value passed to it to standard output.

fn main() declaration can be skipped in single file programs. This is useful when writing small programs, "scripts", or just learning the language. For brevity, fn main() will be skipped in this tutorial.

This means that a "hello world" program in V is as simple as

println('hello world')

[!NOTE] If you do not explicitly use fn main() {}, you need to make sure that all your declarations come before any variable assignment statements or top level function calls, since V will consider everything after the first assignment/function call as part of your implicit main function.

Running a project folder with several files

Suppose you have a folder with several .v files in it, where one of them contains your main() function, and the other files have other helper functions. They may be organized by topic, but still not yet structured enough to be their own separate reusable modules, and you want to compile them all into one program.

As long as those files are in the same folder and declare the same module (usually module main for an application), you can call the helper functions directly from the other files. You do not need to import sibling .v files.

In other languages, you would have to use includes or a build system to enumerate all files, compile them separately to object files, then link them into one final executable.

In V however, you can compile and run the whole folder of .v files together, using just v run .. Passing parameters also works, so you can do: v run . --yourparam some_other_stuff

The above will first compile your files into a single program (named after your folder/project), and then it will execute the program with --yourparam some_other_stuff passed to it as CLI parameters.

Your program can then use the CLI parameters like this:

import os

println(os.args)

[!NOTE] After a successful run, V will delete the generated executable. If you want to keep it, use v -keepc run . instead, or just compile manually with v . .

[!NOTE] Any V compiler flags should be passed before the run command. Everything after the source file/folder, will be passed to the program as is - it will not be processed by V.

Comments

// This is a single line comment.
/*
This is a multiline comment.
   /* It can be nested. */
*/

Functions

fn main() {
    println(add(77, 33))
    println(sub(100, 50))
}

fn add(x int, y int) int {
    return x + y
}

fn sub(x int, y int) int {
    return x - y
}

Again, the type comes after the argument's name.

When a function signature spans multiple lines, commas between parameters are optional:

fn greet(
    salutation string
    name string
) string {
    return 'Hey, ${salutation} ${name}!'
}

Just like in Go and C, functions cannot be overloaded. This simplifies the code and improves maintainability and readability.

Hoisting

Functions can be used before their declaration: add and sub are declared after main, but can still be called from main. This is true for all declarations in V and eliminates the need for header files or thinking about the order of files and declarations.

Returning multiple values

fn foo() (int, int) {
    return 2, 3
}

a, b := foo()
println(a) // 2
println(b) // 3
c, _ := foo() // ignore values using `_`

Symbol visibility

pub fn public_function() {
}

fn private_function() {
}

Functions are private (not exported) by default. To allow other modules to use them, prepend pub. The same applies to structs, constants and types.

[!NOTE] pub can only be used from a named module. For information about creating a module, see Modules.

Variables

name := 'Bob'
age := 20
large_number := i64(9999999999)
println(name)
println(age)
println(large_number)

Variables are declared and initialized with :=. This is the only way to declare variables in V. This means that variables always have an initial value.

The variable's type is inferred from the value on the right hand side. To choose a different type, use type conversion: the expression T(v) converts the value v to the type T.

Unlike most other languages, V only allows defining variables in functions. By default V does not allow global variables. See more details.

For consistency across different code bases, all variable and function names must use the snake_case style, as opposed to type names, which must use PascalCase.

Mutable variables

mut age := 20
println(age)
age = 21
println(age)

To change the value of the variable use =. In V, variables are immutable by default. To be able to change the value of the variable, you have to declare it with mut.

Try compiling the program above after removing mut from the first line.

Initialization vs assignment

Note the (important) difference between := and =. := is used for declaring and initializing, = is used for assigning.

fn main() {
    age = 21
}

This code will not compile, because the variable age is not declared. All variables need to be declared in V.

fn main() {
    age := 21
}

The values of multiple variables can be changed in one line. In this way, their values can be swapped without an intermediary variable.

mut a := 0
mut b := 1
println('${a}, ${b}') // 0, 1
a, b = b, a
println('${a}, ${b}') // 1, 0

Warnings and declaration errors

In development mode the compiler will warn you that you haven't used the variable (you'll get an "unused variable" warning). In production mode (enabled by passing the -prod flag to v – v -prod foo.v) it will not compile at all (like in Go). The compiler also emits an informational notice for private top-level functions and constants in the main module when they are never referenced.

fn main() {
    a := 10
    // warning: unused variable `a`
}

The compiler also warns about obviously constant conditions, for example self-comparisons like if x == x { ... } or match branches that can never be reached. These warnings help catch redundant checks and dead branches early.

To ignore values returned by a function _ can be used

fn foo() (int, int) {
    return 2, 3
}

fn main() {
    c, _ := foo()
    print(c)
    // no warning about unused variable returned by foo.
}

Unlike most languages, variable shadowing is not allowed. Declaring a variable with a name that is already used in a parent scope will cause a compilation error.

fn main() {
    a := 10
    {
        a := 20 // error: redefinition of `a`
    }
}

While variable shadowing is not allowed, field shadowing is allowed.

pub struct Dimension {
    width  int = -1
    height int = -1
}

pub struct Test {
    Dimension
    width int = 100
    // height int
}

fn main() {
    test := Test{}
    println('${test.width} ${test.height} ${test.Dimension.width}') // 100 -1 -1
}

V Types

Primitive types

bool

string

i8    i16  int  i64      i128 (soon)
u8    u16  u32  u64      u128 (soon)

rune // represents a Unicode code point

f32 f64

isize, usize // platform-dependent, the size is how many bytes it takes to reference any location in memory

voidptr // this one is mostly used for [C interoperability](#v-and-c)

[!NOTE] Unlike C and Go, int is always a 32 bit integer.

There is an exception to the rule that all operators in V must have values of the same type on both sides. A small primitive type on one side can be automatically promoted if it fits completely into the data range of the type on the other side. These are the allowed possibilities:

   i8 → i16 → int → i64
                  ↘     ↘
                    f32 → f64
                  ↗     ↗
   u8 → u16 → u32 → u64 ⬎
      ↘     ↘     ↘      ptr
   i8 → i16 → int → i64 ⬏

An int value for example can be automatically promoted to f64 or i64 but not to u32. (u32 would mean loss of the sign for negative values). Promotion from int to f32, however, is currently done automatically (but can lead to precision loss for large values).

Literals like 123 or 4.56 are treated in a special way. They do not lead to type promotions, however they default to int and f64 respectively, when their type has to be decided:

u := u16(12)
v := 13 + u    // v is of type `u16` - no promotion
x := f32(45.6)
y := x + 3.14  // y is of type `f32` - no promotion
a := 75        // a is of type `int` - default for int literal
b := 14.7      // b is of type `f64` - default for float literal
c := u + a     // c is of type `int` - automatic promotion of `u`'s value
d := b + x     // d is of type `f64` - automatic promotion of `x`'s value

Strings

In V, strings are encoded in UTF-8, and are immutable (read-only) by default:

s := 'hello 🌎' // the `world` emoji takes 4 bytes, and string length is reported in bytes
assert s.len == 10

arr := s.bytes() // convert `string` to `[]u8`
assert arr.len == 10

s2 := arr.bytestr() // convert `[]u8` to `string`
assert s2 == s

name := 'Bob'
assert name.len == 3
// indexing gives a byte, u8(66) == `B`
assert name[0] == u8(66)
// slicing gives a string 'ob'
assert name[1..3] == 'ob'

// escape codes
// escape special characters like in C
windows_newline := '\r\n'
assert windows_newline.len == 2

// arbitrary bytes can be directly specified using `\x##` notation where `#` is
// a hex digit
aardvark_str := '\x61ardvark'
assert aardvark_str == 'aardvark'
assert '\xc0'[0] == u8(0xc0)

// or using octal escape `\###` notation where `#` is an octal digit
aardvark_str2 := '\141ardvark'
assert aardvark_str2 == 'aardvark'

// Unicode can be specified directly as `\u####` where # is a hex digit
// and will be converted internally to its UTF-8 representation
star_str := '\u2605' // ★
assert star_str == '★'
// UTF-8 can be specified this way too, as individual bytes.
assert star_str == '\xe2\x98\x85'

Since strings are immutable, you cannot directly change characters in a string:

mut s := 'hello 🌎'
s[0] = `H` // not allowed

error: cannot assign to s[i] since V strings are immutable

Note that indexing a string normally will produce a u8 (byte), not a rune nor another string. Indexes correspond to bytes in the string, not Unicode code points. If you want to convert the u8 to a string, use the .ascii_str() method on the u8:

country := 'Netherlands'
println(country[0]) // Output: 78
println(country[0].ascii_str()) // Output: N

However, you can easily get the runes for a string with the runes() method, which will return an array of the UTF-8 characters from the string. You can then index this array. Just be aware that there may be fewer indexes available on the rune array than on the bytes in the string, if there are any non-ASCII characters.

mut s := 'hello 🌎'
// there are 10 bytes in the string (as shown earlier), but only 7 runes, since the `world` emoji
// only counts as one `rune` (one Unicode character)
assert s.runes().len == 7
println(s.runes()[6])

If you want the code point from a specific string index or other more advanced UTF-8 processing and conversions, refer to the vlib/encoding/utf8 module.

Both single and double quotes can be used to denote strings. For consistency, vfmt converts double quotes to single quotes unless the string contains a single quote character.

Prepend r for raw strings. Escapes are not handled, so you will get exacly what you type:

s := r'hello\nworld' // the `\n` will be preserved as two characters
println(s) // "hello\nworld"

Strings can be easily converted to integers:

s := '42'
n := s.int() // 42

// all int literals are supported
assert '0xc3'.int() == 195
assert '0o10'.int() == 8
assert '0b1111_0000_1010'.int() == 3850
assert '-0b1111_0000_1010'.int() == -3850

For more advanced string processing and conversions, refer to the vlib/strconv module.

String interpolation

Basic interpolation syntax is pretty simple - use ${ before a variable name and } after. The variable will be converted to a string and embedded into the literal:

name := 'Bob'
println('Hello, ${name}!') // Hello, Bob!

It also works with fields: 'age = ${user.age}'. You may also use more complex expressions: 'can register = ${user.age > 13}'.

Format specifiers similar to those in C's printf() are also supported. f, g, x, o, b, etc. are optional and specify the output format. The compiler takes care of the storage size, so there is no hd or llu.

To use a format specifier, follow this pattern:

${varname:[flags][width][.precision][type]}

String operators

name := 'Bob'
bobby := name + 'by' // + is used to concatenate strings
println(bobby) // "Bobby"
mut s := 'hello '
s += 'world' // `+=` is used to append to a string
println(s) // "hello world"

All operators in V must have values of the same type on both sides. You cannot concatenate an integer to a string:

age := 10
println('age = ' + age) // not allowed

error: infix expr: cannot use int (right expression) as string

We have to either convert age to a string:

age := 11
println('age = ' + age.str())

or use string interpolation (preferred):

age := 12
println('age = ${age}')

See all methods of string and related modules strings, strconv.

Runes

A rune represents a single UTF-32 encoded Unicode character and is an alias for u32. To denote them, use ` (backticks) :

rocket := `🚀`

A rune can be converted to a UTF-8 string by using the .str() method.

rocket := `🚀`
assert rocket.str() == '🚀'

A rune can be converted to UTF-8 bytes by using the .bytes() method.

rocket := `🚀`
assert rocket.bytes() == [u8(0xf0), 0x9f, 0x9a, 0x80]

Hex, Unicode, and Octal escape sequences also work in a rune literal:

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:

rocket_string := '🚀'
assert rocket_string[0] != `🚀`
assert 'aloha!'[0] == `a`

A string can be converted to runes by the .runes() method.

hello := 'Hello World 👋'
hello_runes := hello.runes() // [`H`, `e`, `l`, `l`, `o`, ` `, `W`, `o`, `r`, `l`, `d`, ` `, `👋`]
assert hello_runes.string() == hello

Numbers

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:

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:

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:

a := i64(123)
b := u8(42)
c := i16(12345)

Assigning floating point numbers works the same way:

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.

Float literals can also be declared as a power of ten:

f0 := 42e1 // 420
f1 := 123e-2 // 1.23
f2 := 456e+2 // 45600

Arrays

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.

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.

mut nums := [1, 2, 3]
nums << 4
println(nums) // "[1, 2, 3, 4]"

// append array
nums << [5, 6, 7]
println(nums) // "[1, 2, 3, 4, 5, 6, 7]"

mut names := ['John']
names << 'Peter'
names << 'Sam'
// names << 10  <-- This will not compile. `names` is an array of strings.

val in array returns true if the array contains val. See in operator.

names := ['John', 'Peter', 'Sam']
println('Alex' in names) // "false"

Array Fields

There are two fields that control the "size" of an array:

Array Initialization

The type of an array is determined by the first element:

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 and Sum Types to create an array which can handle different types (e.g. Points, Lines) of data elements.

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:

mut a := [][]int{len: 2, init: []int{len: 3}}
a[0][1] = 2
println(a) // [[0, 2, 0], [0, 0, 0]]

3d array example:

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

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():

nums := [1, 2, 3]
nums_copy := nums.clone()

Arrays can be efficiently filtered and mapped with the .filter() and .map() methods:

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)

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.

Additionally, .any() and .all() can be used to conveniently test for elements that satisfy a condition.

nums := [1, 2, 3]
println(nums.any(it == 2)) // true
println(nums.all(it >= 2)) // false

There are further built-in methods for arrays:

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.

mut numbers := [1, 3, 2]
numbers.sort() // 1, 2, 3
numbers.sort(a > b) // 3, 2, 1

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.

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

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.

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:

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) 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 to another array outside unsafe, V inserts an implicit .clone() and shows a notice. The shared-memory examples below therefore use unsafe {} intentionally.

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:

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:

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]

Note that, by default, V makes an implicit clone of the slice and displays a notice about this. So without the .clone() call the result of the code above will be the same. Make the slice in an unsafe {} block if you want to reuse 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:

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:

// 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

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.

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:

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

Note that slicing will cause the data of the fixed size array to be copied to the newly created ordinary array.

Maps

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.

The whole map can be initialized using this short syntax:

numbers := {
    'one': 1
    'two': 2
}
println(numbers)

If a key is not found, a zero value is returned by default:

sm := {
    'abc': 'xyz'
}
val := sm['bad_key']
println(val) // ''

intm := {
    1: 1234
    2: 5678
}
s := intm[3]
println(s) // 0

It's also possible to use an or {} block to handle missing keys:

mm := map[string]int{}
val := mm['bad_key'] or { panic('key not found') }

Modules can opt into stricter map indexing:

@[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:

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:

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:

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:

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 and maps.

Map update syntax

As with structs, V lets you initialise a map with an update applied on top of another map:

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:

// 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 can be imported using the import keyword:

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 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.

Cyclic module imports are not allowed, like in Go.

Selective imports

You can also import specific functions and types from modules directly:

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:

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:

module def

// func is a dummy example function.
pub fn func() {
    println('func')
}

can be called like this:

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).

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
}

You cannot alias an imported function or type. However, you can redeclare a type.

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

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.

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:

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:

n := arguments().len
x := if n > 2 {
    dump(arguments())
    42
} else {
    println('something else')
    100
}
dump(x)

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.

m := {
    'foo': 'bar'
}

// handle missing keys
if v := m['foo'] {
    println(v) // bar
} else {
    println('not found')
}

fn res() !int {
    return 42
}

// functions that return a result type
if v := res() {
    println(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

Type checks and casts

You can check the current type of a sum type using is and its negated form !is.

You can do it either in an if:

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:

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:

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:

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

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.

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:

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

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.

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.

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.

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.

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.

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.

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:

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.

Array for
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:

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:

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.

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
m := {
    'one': 1
    'two': 2
}
for key, value in m {
    println('${key} -> ${value}')
    // Output: one -> 1
    //         two -> 2
}

Either key or value can be ignored by using a single underscore as the identifier.

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
// 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), 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

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

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

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:

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. 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.

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:

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.

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:

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:

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 {}.

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.

if x {
    // ...
    if y {
        unsafe {
            goto my_label
        }
    }
    // ...
}
my_label:

goto should be avoided, particularly when for can be used instead. Labelled break/continue can be used to break out of a nested loop, and those do not risk violating memory-safety.

Structs

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:

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 to it, use the & prefix:

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 to Point. References are similar to Go pointers and C++ references.

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

Default field values

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.

It's also possible to define custom default values.

Required fields

struct Foo {
    n int @[required]
}

You can mark a struct field with the [required] attribute, 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:

_ = 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}.

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:

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)

Trailing struct literal arguments

V doesn't have default function arguments or named arguments, for that trailing struct literal syntax can be used instead:

@[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:

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:

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
}

Private fields are available only inside the same module, any attempt to directly access them from another module will cause an error during compilation. Public immutable fields are readonly everywhere.

Anonymous structs

V supports anonymous structs: structs that don't have to be declared separately with a struct name.

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:

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.

[!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.

For an example, consider the following source in a directory sample:

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:

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

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.

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

V supports embedded structs.

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:

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.

Conceptually, embedded structs are similar to mixins in OOP, NOT base classes.

You can also initialize an embedded struct:

mut button := Button{
    Size: Size{
        width:  3
        height: 2
    }
}

or assign values:

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.

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-SHIFTs and AND operations. With a union, you can access the individual bytes directly.

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.

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 are passed.

[!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:

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:

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.

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.

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

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:

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]

// 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

Closures

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.

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.

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.

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

If you need the value to be modified outside the function, use a reference.

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:

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:

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

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 &:

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.

In general, V's references are similar to Go pointers and C++ references. For example, a generic tree structure definition would look like this:

struct Node[T] {
    val   T
    left  &Node[T]
    right &Node[T]
}

To dereference a reference, use the * operator, just like in C.

Constants

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). Constant values can never be changed. You can also declare a single constant separately:

const e = 2.71828

V constants are more flexible than in most languages. You can assign more complex values:

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:

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.

Outside from module main all constants need to be prefixed with the module name.

Required module prefix

When naming constants, snake_case must be used. In order to distinguish consts from local variables, the full path to consts must be specified. For example, to access the PI const, full math.pi name must be used both outside the math module, and inside it. That restriction is relaxed only for the main module (the one containing your fn main()), where you can use the unqualified name of constants defined there, i.e. numbers, rather than main.numbers.

vfmt takes care of this rule, so you can type println(pi) inside the math module, and vfmt will automatically update it to println(math.pi).

Builtin functions

Some functions are builtin like println. Here is the complete list:

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 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.

println

println is a simple yet powerful builtin function, that can print anything: strings, numbers, arrays, maps, structs.

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.

Printing custom types

If you want to define a custom print value for your type, simply define a str() string method:

struct Color {
    r int
    g int
    b int
}

pub fn (c Color) str() string {
    return '{${c.r}, ${c.g}, ${c.b}}'
}

red := Color{
    r: 255
    g: 0
    b: 0
}
println(red)

Dumping expressions at runtime

You can dump/trace the value of any V expression using dump(expr). For example, save this code sample as factorial.v, then run it with v run factorial.v:

fn factorial(n u32) u32 {
    if dump(n <= 1) {
        return dump(1)
    }
    return dump(n * factorial(n - 1))
}

fn main() {
    println(factorial(5))
}

You will get:

[factorial.v:2] n <= 1: false
[factorial.v:2] n <= 1: false
[factorial.v:2] n <= 1: false
[factorial.v:2] n <= 1: false
[factorial.v:2] n <= 1: true
[factorial.v:3] 1: 1
[factorial.v:5] n * factorial(n - 1): 2
[factorial.v:5] n * factorial(n - 1): 6
[factorial.v:5] n * factorial(n - 1): 24
[factorial.v:5] n * factorial(n - 1): 120
120

Note that dump(expr) will trace both the source location, the expression itself, and the expression value.

Modules

Every file in the root of a folder is part of the same module. Simple programs don't need to specify module name, in which case it defaults to 'main'.

See symbol visibility, Access modifiers.

Create modules

V is a very modular language. Creating reusable modules is encouraged and is quite easy to do. To create a new module, create a directory with your module's name containing .v files with code:

cd ~/code/modules
mkdir mymodule
vim mymodule/myfile.v

// myfile.v
module mymodule

// To export a function we have to use `pub`
pub fn say_hi() {
    println('hello from mymodule!')
}

All items inside a module can be used between the files of a module regardless of whether or not they are prefaced with the pub keyword.

// myfile2.v
module mymodule

pub fn say_hi_and_bye() {
    say_hi() // from myfile.v
    println('goodbye from mymodule')
}

You can now use mymodule in your code:

import mymodule

fn main() {
    mymodule.say_hi()
    mymodule.say_hi_and_bye()
}

Special considerations for project folders

For the top level project folder (the one, compiled with v .), and only that folder, you can have several .v files, that may be mentioning different modules with module main, module abc etc

This is to ease the prototyping workflow in that folder:

init functions

If you want a module to automatically call some setup/initialization code when it is imported, you can define a module init function:

fn init() {
    // your setup code here ...
}

The init function cannot be public - it will be called automatically by V, just once, no matter how many times the module was imported in your program. This feature is particularly useful for initializing a C library.

cleanup functions

If you want a module to automatically call some cleanup/deinitialization code, when your program ends, you can define a module cleanup function:

fn cleanup() {
    // your deinitialisation code here ...
}

Just like the init function, the cleanup function for a module cannot be public - it will be called automatically, when your program ends, once per module, even if the module was imported transitively by other modules several times, in the reverse order of the init calls.

Type Declarations

Type aliases

To define a new type NewType as an alias for ExistingType, do type NewType = ExistingType. This is a special case of a sum type declaration.

Numeric aliases use ordinary conversions for initialization:

type Decimal = f64

amount := Decimal(0.0)

Enums

An enum is a group of constant integer values, each having its own name, whose values start at 0 and increase by 1 for each name listed. For example:

enum Color as u8 {
    red   // the default start value is 0
    green // the value is automatically incremented to 1
    blue  // the final value is now 2
}

mut color := Color.red
// V knows that `color` is a `Color`. No need to use `color = Color.green` here.
color = .green
println(color) // "green"
match color {
    .red { println('the color was red') }
    .green { println('the color was green') }
    .blue { println('the color was blue') }
}

println(int(color)) // prints 1

The enum type can be any integer type, but can be omitted, if it is int: enum Color {.

Enum match must be exhaustive or have an else branch. This ensures that if a new enum field is added, it's handled everywhere in the code.

Enum fields can re-use reserved keywords:

enum Color {
    none
    red
    green
    blue
}

color := Color.none
println(color)

Integers may be assigned to enum fields.

enum Grocery {
    apple
    orange = 5
    pear
}

g1 := int(Grocery.apple)
g2 := int(Grocery.orange)
g3 := int(Grocery.pear)
println('Grocery IDs: ${g1}, ${g2}, ${g3}')

Output: Grocery IDs: 0, 5, 6.

Compile-time $if blocks can also be used inside enum bodies to include fields conditionally.

enum Feature {
    base
    $if beta ? {
        beta_extension
    }
}

Operations are not allowed on enum variables; they must be explicitly cast to int.

Enums can have methods, just like structs.

enum Cycle {
    one
    two
    three
}

fn (c Cycle) next() Cycle {
    match c {
        .one {
            return .two
        }
        .two {
            return .three
        }
        .three {
            return .one
        }
    }
}

mut c := Cycle.one
for _ in 0 .. 10 {
    println(c)
    c = c.next()
}

Output:

one
two
three
one
two
three
one
two
three
one

Enums can be created from string or integer value and converted into string

enum Cycle {
    one
    two = 2
    three
}

// Create enum from value
println(Cycle.from(10) or { Cycle.three })
println(Cycle.from('two')!)

// Convert an enum value to a string
println(Cycle.one.str())

Output:

three
two
one

Function Types

You can use type aliases for naming specific function signatures - for example:

type Filter = fn (string) string

This works like any other type - for example, a function can accept an argument of a function type:

type Filter = fn (string) string

fn filter(s string, f Filter) string {
    return f(s)
}

V has duck-typing, so functions don't need to declare compatibility with a function type - they just have to be compatible:

fn uppercase(s string) string {
    return s.to_upper()
}

// now `uppercase` can be used everywhere where Filter is expected

Compatible functions can also be explicitly cast to a function type:

my_filter := Filter(uppercase)

The cast here is purely informational - again, duck-typing means that the resulting type is the same without an explicit cast:

my_filter := uppercase

You can pass the assigned function as an argument:

println(filter('Hello world', my_filter)) // prints `HELLO WORLD`

And you could of course have passed it directly as well, without using a local variable:

println(filter('Hello world', uppercase))

And this works with anonymous functions as well:

println(filter('Hello world', fn (s string) string {
    return s.to_upper()
}))

You can see the complete example here.

Interfaces

// interface-example.1
struct Dog {
    breed string
}

fn (d Dog) speak() string {
    return 'woof'
}

struct Cat {
    breed string
}

fn (c Cat) speak() string {
    return 'meow'
}

// unlike Go, but like TypeScript, V's interfaces can define both fields and methods.
interface Speaker {
    breed string
    speak() string
}

fn main() {
    dog := Dog{'Leonberger'}
    cat := Cat{'Siamese'}

    mut arr := []Speaker{}
    arr << dog
    arr << cat
    for item in arr {
        println('a ${item.breed} says: ${item.speak()}')
    }
}

Implement an interface

A type implements an interface by implementing its methods and fields.

An interface can have a mut: section. Implementing types will need to have a mut receiver, for methods declared in the mut: section of an interface.

// interface-example.2
module main

interface Foo {
    write(string) string
}

// => the method signature of a type, implementing interface Foo should be:
// `fn (s Type) write(a string) string`

interface Bar {
mut:
    write(string) string
}

// => the method signature of a type, implementing interface Bar should be:
// `fn (mut s Type) write(a string) string`

struct MyStruct {}

// MyStruct implements the interface Foo, but *not* interface Bar
fn (s MyStruct) write(a string) string {
    return a
}

fn main() {
    s1 := MyStruct{}
    fn1(s1)
    // fn2(s1) -> compile error, since MyStruct does not implement Bar
}

fn fn1(s Foo) {
    println(s.write('Foo'))
}

// fn fn2(s Bar) { // does not match
//      println(s.write('Foo'))
// }

There is an optional implements keyword for explicit declaration of intent, which applies to struct declarations.

struct PathError implements IError {
    Error
    path string
}

fn (err PathError) msg() string {
    return 'Failed to open path: ${err.path}'
}

fn try_open(path string) ! {
    return PathError{
        path: path
    }
}

fn main() {
    try_open('/tmp') or { panic(err) }
}

Casting an interface

We can test the underlying type of an interface using dynamic cast operators.

[!NOTE] Dynamic cast converts variable s into a pointer inside the if statements in this example:

// interface-example.3 (continued from interface-example.1)
interface Something {}

fn announce(s Something) {
    if s is Dog {
        println('a ${s.breed} dog') // `s` is automatically cast to `Dog` (smart cast)
    } else if s is Cat {
        println('a cat speaks ${s.speak()}')
    } else {
        println('something else')
    }
}

fn main() {
    dog := Dog{'Leonberger'}
    cat := Cat{'Siamese'}
    announce(dog)
    announce(cat)
}

Smart casting an interface value to T also means the smart-casted variable has type &T inside that branch. This matters when returning the value from a generic function:

fn get_component[T](entity Entity) !T {
    for component in entity.components {
        if component is T {
            return *component
        }
    }
    return error('Entity does not have component')
}

If you want to return the smart-casted pointer itself, use !&T as the return type instead.

// interface-example.4
interface IFoo {
    foo()
}

interface IBar {
    bar()
}

// implements only IFoo
struct SFoo {}

fn (sf SFoo) foo() {}

// implements both IFoo and IBar
struct SFooBar {}

fn (sfb SFooBar) foo() {}

fn (sfb SFooBar) bar() {
    dump('This implements IBar')
}

fn main() {
    mut arr := []IFoo{}
    arr << SFoo{}
    arr << SFooBar{}

    for a in arr {
        dump(a)
        // In order to execute instances that implements IBar.
        if a is IBar {
            a.bar()
        }
    }
}

For more information, see Dynamic casts.

Interface method definitions

Also unlike Go, an interface can have its own methods, similar to how structs can have their methods. These 'interface methods' do not have to be implemented, by structs which implement that interface. They are just a convenient way to write i.some_function() instead of some_function(i), similar to how struct methods can be looked at, as a convenience for writing s.xyz() instead of xyz(s).

[!NOTE] This feature is NOT a "default implementation" like in C#.

For example, if a struct cat is wrapped in an interface a, that has implemented a method with the same name speak, as a method implemented by the struct, and you do a.speak(), only the interface method is called:

interface Adoptable {}

fn (a Adoptable) speak() string {
    return 'adopt me!'
}

struct Cat {}

fn (c Cat) speak() string {
    return 'meow!'
}

struct Dog {}

fn main() {
    cat := Cat{}
    assert dump(cat.speak()) == 'meow!'

    a := Adoptable(cat)
    assert dump(a.speak()) == 'adopt me!' // call Adoptable's `speak`
    if a is Cat {
        // Inside this `if` however, V knows that `a` is not just any
        // kind of Adoptable, but actually a Cat, so it will use the
        // Cat `speak`, NOT the Adoptable `speak`:
        dump(a.speak()) // meow!
    }

    b := Adoptable(Dog{})
    assert dump(b.speak()) == 'adopt me!' // call Adoptable's `speak`
    // if b is Dog {
    //  dump(b.speak()) // error: unknown method or field: Dog.speak
    // }
}

Embedded interface

Interfaces support embedding, just like structs:

pub interface Reader {
mut:
    read(mut buf []u8) ?int
}

pub interface Writer {
mut:
    write(buf []u8) ?int
}

// ReaderWriter embeds both Reader and Writer.
// The effect is the same as copy/pasting all of the
// Reader and all of the Writer methods/fields into
// ReaderWriter.
pub interface ReaderWriter {
    Reader
    Writer
}

Sum types

A sum type instance can hold a value of several different types. Use the type keyword to declare a sum type:

struct Moon {}

struct Mars {}

struct Venus {}

type World = Mars | Moon | Venus

sum := World(Moon{})
assert sum.type_name() == 'Moon'
println(sum)

The built-in method type_name returns the name of the currently held type.

With sum types you could build recursive structures and write concise but powerful code on them.

// V's binary tree
struct Empty {}

struct Node {
    value f64
    left  Tree
    right Tree
}

type Tree = Empty | Node

// sum up all node values

fn sum(tree Tree) f64 {
    return match tree {
        Empty { 0 }
        Node { tree.value + sum(tree.left) + sum(tree.right) }
    }
}

fn main() {
    left := Node{0.2, Empty{}, Empty{}}
    right := Node{0.3, Empty{}, Node{0.4, Empty{}, Empty{}}}
    tree := Node{0.5, left, right}
    println(sum(tree)) // 0.2 + 0.3 + 0.4 + 0.5 = 1.4
}

Dynamic casts

To check whether a sum type instance holds a certain type, use sum is Type. To cast a sum type to one of its variants you can use sum as Type:

struct Moon {}

struct Mars {}

struct Venus {}

type World = Mars | Moon | Venus

fn (m Mars) dust_storm() bool {
    return true
}

fn main() {
    mut w := World(Moon{})
    assert w is Moon
    w = Mars{}
    // use `as` to access the Mars instance
    mars := w as Mars
    if mars.dust_storm() {
        println('bad weather!')
    }
}

as will panic if w doesn't hold a Mars instance. A safer way is to use a smart cast.

Smart casting

if w is Mars {
    assert typeof(w).name == 'Mars'
    if w.dust_storm() {
        println('bad weather!')
    }
}

w has type Mars inside the body of the if statement. This is known as flow-sensitive typing. If w is a mutable identifier, it would be unsafe if the compiler smart casts it without a warning. That's why you have to declare a mut before the is expression:

if mut w is Mars {
    assert typeof(w).name == 'Mars'
    if w.dust_storm() {
        println('bad weather!')
    }
}

Otherwise w would keep its original type.

This works for both simple variables and complex expressions like user.name and values[i]. The same rule applies to mutable method receivers, for example fn (mut w World) fn_name() { for mut w is Mars { ... } }.

Smart casts also work on indexed expressions in match branches:

type Entry = int | string

values := [Entry('v')]
match values[0] {
    string {
        assert values[0] == 'v'
    }
    else {
        assert false
    }
}

Matching sum types

You can also use match to determine the variant:

struct Moon {}

struct Mars {}

struct Venus {}

type World = Mars | Moon | Venus

fn open_parachutes(n int) {
    println(n)
}

fn land(w World) {
    match w {
        Moon {} // no atmosphere
        Mars {
            // light atmosphere
            open_parachutes(3)
        }
        Venus {
            // heavy atmosphere
            open_parachutes(1)
        }
    }
}

match must have a pattern for each variant or have an else branch.

struct Moon {}
struct Mars {}
struct Venus {}

type World = Moon | Mars | Venus

fn (m Moon) moon_walk() {}
fn (m Mars) shiver() {}
fn (v Venus) sweat() {}

fn pass_time(w World) {
    match w {
        // using the shadowed match variable, in this case `w` (smart cast)
        Moon { w.moon_walk() }
        Mars { w.shiver() }
        else {}
    }
}

Option/Result types and error handling

Option types can represent a value or none. Result types may represent a value, or an error returned from a function.

Option types are declared by prepending ? to the type name: ?Type. Result types use !: !Type.

struct User {
    id   int
    name string
}

struct Repo {
    users []User
}

fn (r Repo) find_user_by_id(id int) !User {
    for user in r.users {
        if user.id == id {
            // V automatically wraps this into a result or option type
            return user
        }
    }
    return error('User ${id} not found')
}

// A version of the function using an option
fn (r Repo) find_user_by_id2(id int) ?User {
    for user in r.users {
        if user.id == id {
            return user
        }
    }
    return none
}

fn main() {
    repo := Repo{
        users: [User{1, 'Andrew'}, User{2, 'Bob'}, User{10, 'Charles'}]
    }
    user := repo.find_user_by_id(10) or { // Option/Result types must be handled by `or` blocks
        println(err)
        return
    }
    println(user.id) // "10"
    println(user.name) // "Charles"

    user2 := repo.find_user_by_id2(10) or { return }

    // To create an Option var directly:
    my_optional_int := ?int(none)
    my_optional_string := ?string(none)
    my_optional_user := ?User(none)
}

Trailing option-typed parameters can also be omitted in function calls. When they are not passed, V supplies none:

fn connect(url string, timeout ?int) {
    actual_timeout := timeout or { 1000 }
    println('${url} -> ${actual_timeout}')
}

fn main() {
    connect('https://vlang.io')
    connect('https://vlang.io', 5000)
}

V used to combine Option and Result into one type, now they are separate.

The amount of work required to "upgrade" a function to an option/result function is minimal; you have to add a ? or ! to the return type and return none or an error (respectively) when something goes wrong.

This is the primary mechanism for error handling in V. They are still values, like in Go, but the advantage is that errors can't be unhandled, and handling them is a lot less verbose. Unlike other languages, V does not handle exceptions with throw/try/catch blocks.

err is defined inside an or block and is set to the string message passed to the error() function.

user := repo.find_user_by_id(7) or {
    println(err) // "User 7 not found"
    return
}

Use err is ... to compare errors:

import io

x := read() or {
    if err is io.Eof {
        println('end of file')
    }
    return
}

Options/results when returning multiple values

Only one Option or Result is allowed to be returned from a function. It is possible to return multiple values and still signal an error.

fn multi_return(v int) !(int, int) {
    if v < 0 {
        return error('must be positive')
    }
    return v, v * v
}

Handling options/results

There are four ways of handling an option/result. The first method is to propagate the error:

import net.http

fn f(url string) !string {
    resp := http.get(url)!
    return resp.body
}

http.get returns !http.Response. Because ! follows the call, the error will be propagated to the caller of f. When using ? after a function call producing an option, the enclosing function must return an option as well. If error propagation is used in the main() function it will panic instead, since the error cannot be propagated any further.

The body of f is essentially a condensed version of:

    resp := http.get(url) or { return err }
    return resp.body

The second method is to break from execution early:

user := repo.find_user_by_id(7) or { return }

Here, you can either call panic() or exit(), which will stop the execution of the entire program, or use a control flow statement (return, break, continue, etc) to break from the current block.

[!NOTE] break and continue can only be used inside a for loop.

V does not have a way to forcibly "unwrap" an option (as other languages do, for instance Rust's unwrap() or Swift's !). To do this, use or { panic(err) } instead.

The third method is to provide a default value at the end of the or block. In case of an error, that value would be assigned instead, so it must have the same type as the content of the Option being handled.

fn do_something(s string) !string {
    if s == 'foo' {
        return 'foo'
    }
    return error('invalid string')
}

a := do_something('foo') or { 'default' } // a will be 'foo'
b := do_something('bar') or { 'default' } // b will be 'default'
println(a)
println(b)

The fourth method is to use if unwrapping:

import net.http

if resp := http.get('https://google.com') {
    println(resp.body) // resp is a http.Response, not an option
} else {
    println(err)
}

Above, http.get returns a !http.Response. resp is only in scope for the first if branch. err is only in scope for the else branch.

Custom error types

V gives you the ability to define custom error types through the IError interface. The interface requires two methods: msg() string and code() int. Every type that implements these methods can be used as an error.

When defining a custom error type it is recommended to embed the builtin Error default implementation. This provides an empty default implementation for both required methods, so you only have to implement what you really need, and may provide additional utility functions in the future.

struct PathError {
    Error
    path string
}

fn (err PathError) msg() string {
    return 'Failed to open path: ${err.path}'
}

fn try_open(path string) ! {
    // V automatically casts this to IError
    return PathError{
        path: path
    }
}

fn main() {
    try_open('/tmp') or { panic(err) }
}

Generics


struct Repo[T] {
    db DB
}

struct User {
    id   int
    name string
}

struct Post {
    id   int
    user_id int
    title string
    body string
}

fn new_repo[T](db DB) Repo[T] {
    return Repo[T]{db: db}
}

// This is a generic function. V will generate it for every type it's used with.
fn (r Repo[T]) find_by_id(id int) ?T {
    table_name := T.name // in this example getting the name of the type gives us the table name
    return r.db.query_one[T]('select * from ${table_name} where id = ?', id)
}

db := new_db()
users_repo := new_repo[User](db) // returns Repo[User]
posts_repo := new_repo[Post](db) // returns Repo[Post]
user := users_repo.find_by_id(1)? // find_by_id[User]
post := posts_repo.find_by_id(1)? // find_by_id[Post]

Currently generic function definitions must declare their type parameters, but in future versions, V will infer generic type parameters from single-letter type names in runtime parameter types. This is why the find_by_id(1) calls above can omit [T], because the receiver argument r in the method declaration, uses a generic type T.

Another example:

fn compare[T](a T, b T) int {
    if a < b {
        return -1
    }
    if a > b {
        return 1
    }
    return 0
}

// compare[int]
println(compare(1, 0)) // Outputs: 1
println(compare(1, 1)) //          0
println(compare(1, 2)) //         -1
// compare[string]
println(compare('1', '0')) // Outputs: 1
println(compare('1', '1')) //          0
println(compare('1', '2')) //         -1
// compare[f64]
println(compare(1.1, 1.0)) // Outputs: 1
println(compare(1.1, 1.1)) //          0
println(compare(1.1, 1.2)) //         -1

Concurrency

Spawning Concurrent Tasks

V's model of concurrency is similar to Go's.

go foo() runs foo() concurrently in a lightweight thread managed by the V runtime.

spawn foo() runs foo() concurrently in a different thread:

import math

fn p(a f64, b f64) { // ordinary function without return value
    c := math.sqrt(a * a + b * b)
    println(c)
}

fn main() {
    spawn p(3, 4)
    // p will be run in parallel thread
    // It can also be written as follows
    // spawn fn (a f64, b f64) {
    //  c := math.sqrt(a * a + b * b)
    //  println(c)
    // }(3, 4)
}

[!NOTE] Threads rely on the machine's CPU (number of cores/threads). Be aware that OS threads spawned with spawn have limitations in regard to concurrency, including resource overhead and scalability issues, and might affect performance in cases of high thread count.

Sometimes it is necessary to wait until a parallel thread has finished. This can be done by assigning a handle to the started thread and calling the wait() method to this handle later:

import math

fn p(a f64, b f64) { // ordinary function without return value
    c := math.sqrt(a * a + b * b)
    println(c) // prints `5`
}

fn main() {
    h := spawn p(3, 4)
    // p() runs in parallel thread
    h.wait()
    // p() has definitely finished
}

This approach can also be used to get a return value from a function that is run in a parallel thread. There is no need to modify the function itself to be able to call it concurrently.

import math { sqrt }

fn get_hypot(a f64, b f64) f64 { //       ordinary function returning a value
    c := sqrt(a * a + b * b)
    return c
}

fn main() {
    g := spawn get_hypot(54.06, 2.08) // spawn thread and get handle to it
    h1 := get_hypot(2.32, 16.74) //   do some other calculation here
    h2 := g.wait() //                 get result from spawned thread
    println('Results: ${h1}, ${h2}') //   prints `Results: 16.9, 54.1`
}

If there is a large number of tasks, it might be easier to manage them using an array of threads.

import time

fn task(id int, duration int) {
    println('task ${id} begin')
    time.sleep(duration * time.millisecond)
    println('task ${id} end')
}

fn main() {
    mut threads := []thread{}
    threads << spawn task(1, 500)
    threads << spawn task(2, 900)
    threads << spawn task(3, 100)
    threads.wait()
    println('done')
}

// Output:
// task 1 begin
// task 2 begin
// task 3 begin
// task 3 end
// task 1 end
// task 2 end
// done

Additionally for threads that return the same type, calling wait() on the thread array will return all computed values.

fn expensive_computing(i int) int {
    return i * i
}

fn main() {
    mut threads := []thread int{}
    for i in 1 .. 10 {
        threads << spawn expensive_computing(i)
    }
    // Join all tasks
    r := threads.wait()
    println('All jobs finished: ${r}')
}

// Output: All jobs finished: [1, 4, 9, 16, 25, 36, 49, 64, 81]

When the spawned function returns ?T or !T, waiting on the thread array returns ?[]T or ![]T. That means the batch can be handled with or, ?, or ! the same way as a single thread handle.

fn maybe_square(i int) !int {
    if i < 0 {
        return error('negative input')
    }
    return i * i
}

fn main() {
    mut threads := []thread !int{}
    for i in 1 .. 4 {
        threads << spawn maybe_square(i)
    }
    values := threads.wait() or { panic(err) }
    println(values)
}

Channels

Channels are the preferred way to communicate between threads. They allow threads to exchange data safely without requiring explicit locking. V's channels are similar to those in Go, enabling you to push objects into a channel on one end and pop objects from the other. Channels can be buffered or unbuffered, and you can use the select statement to monitor multiple channels simultaneously.

Syntax and Usage

Channels are declared with the type chan objtype. You can optionally specify a buffer length using the cap field:

ch := chan int{} // unbuffered - "synchronous"
ch2 := chan f64{cap: 100} // buffered with a capacity of 100

Channels do not have to be declared as mut. The buffer length is not part of the type but a field of the individual channel object. Channels can be passed to threads like normal variables:

import time

fn worker(ch chan int) {
    for i in 0 .. 5 {
        ch <- i // push values into the channel
    }
}

fn clock(ch chan int) {
    for i in 0 .. 5 {
        time.sleep(1 * time.second)
        println('Clock tick')
        ch <- (i + 1000) // push a value into the channel
    }
    ch.close() // close the channel when done
}

fn main() {
    ch := chan int{cap: 5}
    spawn worker(ch)
    spawn clock(ch)
    for {
        value := <-ch or { // receive/pop values from the channel
            println('Channel closed')
            break
        }
        println('Received: ${value}')
    }
}

Buffered Channels

Buffered channels allow you to push multiple items without blocking, as long as the buffer is not full:

ch := chan string{cap: 2}
ch <- 'hello'
ch <- 'world'
// ch <- '!' // This would block because the buffer is full

println(<-ch) // "hello"
println(<-ch) // "world"

Closing Channels

A channel can be closed to indicate that no further objects can be pushed. Any attempt to do so will then result in a runtime panic (with the exception of select and try_push() - see below). Attempts to pop will return immediately if the associated channel has been closed and the buffer is empty. This situation can be handled using an or {} block (see Handling options/results). An optional IError can be passed to close(err) so receive operations that use or {} or ? can distinguish an error termination from a normal close.

ch := chan int{}
ch2 := chan f64{}
// ...
ch.close()
// ...
m := <-ch or {
    println('channel has been closed')
}

// propagate error
y := <-ch2 ?

ch2.close(error('worker failed'))
z := <-ch2 or {
    println(err.msg())
    0.0
}

Note: buffered channels can be closed while they have unread values in them. The buffered values can be retrieved, even after the closing:

ich := chan int{cap: 5}
for i in 0 .. 5 {
    ich <- i
}

for _ in 0 .. 2 {
    x := <-ich or { break }
    eprintln('>>  loop 0..2 | x: ${x} | ich.closed: ${ich.closed}')
}

ich.close()

for {
    x := <-ich or { break }
    eprintln('>> final loop | x: ${x} | ich.closed: ${ich.closed}')
}

... will produce:

>>  loop 0..2 | x: 0 | ich.closed: false
>>  loop 0..2 | x: 1 | ich.closed: false
>> final loop | x: 2 | ich.closed: true
>> final loop | x: 3 | ich.closed: true
>> final loop | x: 4 | ich.closed: true

Note: reading from the .closed field of the channel in the example, is done just for clarity of illustration. The recommended way to pop values from the channel is with: x := <-ich or { break } in a for loop, which will cleanly break out of the loop, when the channel is closed and empty. Avoid manually checking, whether the channel was closed or not, because that can introduce data races, if you are not careful.

Channel Select

The select command allows monitoring several channels at the same time without noticeable CPU load. It consists of a list of possible transfers and associated branches of statements - similar to the match command:

import time

fn main() {
    ch := chan f64{}
    ch2 := chan f64{}
    ch3 := chan f64{}
    mut b := 0.0
    c := 1.0
    // ... setup spawn threads that will send on ch/ch2
    spawn fn (the_channel chan f64) {
        time.sleep(5 * time.millisecond)
        the_channel <- 1.0
    }(ch)
    spawn fn (the_channel chan f64) {
        time.sleep(1 * time.millisecond)
        the_channel <- 1.0
    }(ch2)
    spawn fn (the_channel chan f64) {
        _ := <-the_channel
    }(ch3)

    select {
        a := <-ch {
            // do something with `a`
            eprintln('> a: ${a}')
        }
        b = <-ch2 {
            // do something with predeclared variable `b`
            eprintln('> b: ${b}')
        }
        ch3 <- c {
            // do something if `c` was sent
            time.sleep(5 * time.millisecond)
            eprintln('> c: ${c} was send on channel ch3')
        }
        500 * time.millisecond {
            // do something if no channel has become ready within 0.5s
            eprintln('> more than 0.5s passed without a channel being ready')
        }
    }
    eprintln('> done')
}

The timeout branch is optional. If it is absent select waits for an unlimited amount of time. It is also possible to proceed immediately if no channel is ready in the moment select is called by adding an else { ... } branch. else and <timeout> are mutually exclusive. In statement form, else also runs when every channel operation is unavailable because the channels are already closed. To drain buffered values from a closed channel, use a plain receive with or {} instead of select ... else.

The select command can be used as an expression of type bool that becomes false if all channels are closed:

if select {
    ch <- a {
        // ...
    }
} {
    // channel was open
} else {
    // channel is closed
}

Special Channel Features

For special purposes there are some builtin fields and methods:

ch := chan int{cap: 2}
println(ch.try_push(42)) // `.success` if pushed, `.not_ready` if full, `.closed` if closed
println(ch.len) // Number of items in the buffer
println(ch.cap) // Buffer capacity
println(ch.closed) // Whether the channel is closed

struct Abc {
    x int
}

a := 2.13
ch := chan f64{cap: 1} // buffered so `try_push()` can succeed without a waiting receiver
res := ch.try_push(a) // try to perform `ch <- a`
println(res)
l := ch.len // number of elements in queue
c := ch.cap // maximum queue length
is_closed := ch.closed // bool flag - has `ch` been closed
println(l)
println(c)
mut b := Abc{}
ch2 := chan Abc{}
res2 := ch2.try_pop(mut b) // try to perform `b = <-ch2`

The try_push/pop() methods will return immediately with one of the results .success, .not_ready or .closed - dependent on whether the object has been transferred or the reason why not. On an unbuffered channel, try_push() will return .not_ready unless a receiver is ready at the same time. Usage of these methods and fields in production is not recommended - algorithms based on them are often subject to race conditions. Especially .len and .closed should not be used to make decisions. Use or branches, error propagation or select instead (see Syntax and Usage and Channel Select above).

Shared Objects

Data can be exchanged between a thread and the calling thread via a shared variable. Such variables should be created as shared and passed to the thread as such, too. The underlying struct contains a hidden mutex that allows locking concurrent access using rlock for read-only and lock for read/write access.

Note: Shared variables must be structs, arrays or maps.

Example of Shared Objects

struct Counter {
mut:
    value int
}

fn (shared counter Counter) increment() {
    lock counter {
        counter.value += 1
        println('Incremented to: ${counter.value}')
    }
}

fn main() {
    shared counter := Counter{}

    spawn counter.increment()
    spawn counter.increment()

    rlock counter {
        println('Final value: ${counter.value}')
    }
}

Difference Between Channels and Shared Objects

Purpose:

JSON

Because of the ubiquitous nature of JSON, support for it is built directly into V.

V generates code for JSON encoding and decoding. No runtime reflection is used. This results in much better performance.

Decoding JSON

import json

struct Foo {
    x int
}

struct User {
    // Adding a [required] attribute will make decoding fail, if that
    // field is not present in the input.
    // If a field is not [required], but is missing, it will be assumed
    // to have its default value, like 0 for numbers, or '' for strings,
    // and decoding will not fail.
    name string @[required]
    age  int
    // Use the `@[skip]` attribute to skip certain fields.
    // You can also use `@[json: '-']`, and `@[sql: '-']`, which will cause only
    // the `json` module to skip the field, or only the SQL orm to skip it.
    foo Foo @[skip]
    // If the field name is different in JSON, it can be specified
    last_name string @[json: lastName]
}

data := '{ "name": "Frodo", "lastName": "Baggins", "age": 25, "nullable": null }'
user := json.decode(User, data) or {
    eprintln('Failed to decode json, error: ${err}')
    return
}
println(user.name)
println(user.last_name)
println(user.age)
// You can also decode JSON arrays:
sfoos := '[{"x":123},{"x":456}]'
foos := json.decode([]Foo, sfoos)!
println(foos[0].x)
println(foos[1].x)

The json.decode function takes two arguments: the first is the type into which the JSON value should be decoded and the second is a string containing the JSON data.

Encoding JSON

import json

struct User {
    name  string
    score i64
}

mut data := map[string]int{}
user := &User{
    name:  'Pierre'
    score: 1024
}

data['x'] = 42
data['y'] = 360

println(json.encode(data)) // {"x":42,"y":360}
println(json.encode(user)) // {"name":"Pierre","score":1024}

The json module also supports anonymous struct fields, which helps with complex JSON apis with lots of levels.

Testing

Asserts

fn foo(mut v []int) {
    v[0] = 1
}

mut v := [20]
foo(mut v)
assert v[0] < 4

An assert statement checks that its expression evaluates to true. If an assert fails, the program will usually abort. Asserts should only be used to detect programming errors. When an assert fails it is reported to stderr, and the values on each side of a comparison operator (such as <, ==) will be printed when possible. This is useful to easily find an unexpected value. Assert statements can be used in any function, not just test ones, which is handy when developing new functionality, to keep your invariants in check.

[!NOTE] All assert statements are removed, when you compile your program with the -prod flag.

Asserts with an extra message

This form of the assert statement, will print the extra message when it fails. Note that you can use any string expression there - string literals, functions returning a string, strings that interpolate variables, etc.

fn test_assertion_with_extra_message_failure() {
    for i in 0 .. 100 {
        assert i * 2 - 45 < 75 + 10, 'assertion failed for i: ${i}'
    }
}

Asserts that do not abort your program

When initially prototyping functionality and tests, it is sometimes desirable to have asserts that do not stop the program, but just print their failures. That can be achieved by tagging your assert containing functions with an [assert_continues] tag, for example running this program:

@[assert_continues]
fn abc(ii int) {
    assert ii == 2
}

for i in 0 .. 4 {
    abc(i)
}

... will produce this output:

assert_continues_example.v:3: FAIL: fn main.abc: assert ii == 2
   left value: ii = 0
   right value: 2
assert_continues_example.v:3: FAIL: fn main.abc: assert ii == 2
   left value: ii = 1
  right value: 2
assert_continues_example.v:3: FAIL: fn main.abc: assert ii == 2
   left value: ii = 3
  right value: 2

[!NOTE] V also supports a command line flag -assert continues, which will change the behaviour of all asserts globally, as if you had tagged every function with [assert_continues].

Test files

// hello.v
module main

fn hello() string {
    return 'Hello world'
}

fn main() {
    println(hello())
}

// hello_test.v
module main

fn test_hello() {
    assert hello() == 'Hello world'
}

To run the test file above, use v hello_test.v. This will check that the function hello is producing the correct output. V executes all test functions in the file.

[!NOTE] All _test.v files (both external and internal ones), are compiled as separate programs. In other words, you may have as many _test.v files, and tests in them as you like, they will not affect the compilation of your other code in .v files normally at all, but only when you do explicitly v file_test.v or v test ..

Running tests

To run test functions in an individual test file, use v foo_test.v.

To test an entire module, use v test mymodule. You can also use v test . to test everything inside your current folder (and subfolders). You can pass the -stats option to see more details about the individual tests run.

You can put additional test data, including .v source files in a folder, named testdata, right next to your _test.v files. V's test framework will ignore such folders, while scanning for tests to run. This is useful, if you want to put .v files with invalid V source code, or other tests, including known failing ones, that should be run in a specific way/options by a parent _test.v file.

[!NOTE] The path to the V compiler, is available through @VEXE, so a _test.v file, can easily run other test files like this:

import os

fn test_subtest() {
    res := os.execute('${os.quoted_path(@VEXE)} other_test.v')
    assert res.exit_code == 1
    assert res.output.contains('other_test.v does not exist')
}

Memory management

V avoids doing unnecessary allocations in the first place by using value types, string buffers, promoting a simple abstraction-free code style.

There are 4 ways to manage memory in V.

The default is a minimal and a well performing tracing GC.

The second way is autofree, it can be enabled with -autofree. It takes care of most objects (~90-100%): the compiler inserts necessary free calls automatically during compilation. Remaining small percentage of objects is freed via GC. The developer doesn't need to change anything in their code. "It just works", like in Python, Go, or Java, except there's no heavy GC tracing everything or expensive RC for each object.

For developers willing to have more low-level control, memory can be managed manually with -gc none.

Arena allocation is available via a -prealloc flag. Note: currently this mode is only suitable to speed up short lived, single-threaded, batch-like programs (like compilers).

Control

You can take advantage of V's autofree engine and define a free() method on custom data types:

struct MyType {}

@[unsafe]
fn (data &MyType) free() {
    // ...
}

Just as the compiler frees C data types with C's free(), it will statically insert free() calls for your data type at the end of each variable's lifetime.

Autofree can be enabled with an -autofree flag.

For developers willing to have more low-level control, autofree can be disabled with -manualfree, or by adding a [manualfree] on each function that wants to manage its memory manually. (See attributes).

[!NOTE] Autofree is still WIP. Until it stabilises and becomes the default, please avoid using it. Right now allocations are handled by a minimal and well performing GC until V's autofree engine is production ready.

Examples

import strings

fn draw_text(s string, x int, y int) {
    // ...
}

fn draw_scene() {
    // ...
    name1 := 'abc'
    name2 := 'def ghi'
    draw_text('hello ${name1}', 10, 10)
    draw_text('hello ${name2}', 100, 10)
    draw_text(strings.repeat(`X`, 10000), 10, 50)
    // ...
}

The strings don't escape draw_text, so they are cleaned up when the function exits.

In fact, with the -prealloc flag, the first two calls won't result in any allocations at all. These two strings are small, so V will use a preallocated buffer for them.

struct User {
    name string
}

fn test() []int {
    number := 7 // stack variable
    user := User{} // struct allocated on stack
    numbers := [1, 2, 3] // array allocated on heap, will be freed as the function exits
    println(number)
    println(user)
    println(numbers)
    numbers2 := [4, 5, 6] // array that's being returned, won't be freed here
    return numbers2
}

Stack and Heap

Stack and Heap Basics

Like with most other programming languages there are two locations where data can be stored:

V's default approach

Due to performance considerations V tries to put objects on the stack if possible, but allocates them on the heap when obviously necessary. Example:

struct MyStruct {
    n int
}

struct RefStruct {
    r &MyStruct
}

fn main() {
    q, w := f()
    println('q: ${q.r.n}, w: ${w.n}')
}

fn f() (RefStruct, &MyStruct) {
    a := MyStruct{
        n: 1
    }
    b := MyStruct{
        n: 2
    }
    c := MyStruct{
        n: 3
    }
    e := RefStruct{
        r: &b
    }
    x := a.n + c.n
    println('x: ${x}')
    return e, &c
}

Here a is stored on the stack since its address never leaves the function f(). However a reference to b is part of e which is returned. Also a reference to c is returned. For this reason b and c will be heap allocated.

Things become less obvious when a reference to an object is passed as a function argument:

struct MyStruct {
mut:
    n int
}

fn main() {
    mut q := MyStruct{
        n: 7
    }
    w := MyStruct{
        n: 13
    }
    x := q.f(&w) // references of `q` and `w` are passed
    println('q: ${q}\nx: ${x}')
}

fn (mut a MyStruct) f(b &MyStruct) int {
    a.n += b.n
    x := a.n * b.n
    return x
}

Here the call q.f(&w) passes references to q and w because a is mut and b is of type &MyStruct in f()'s declaration, so technically these references are leaving main(). However the lifetime of these references lies inside the scope of main() so q and w are allocated on the stack.

Manual Control for Stack and Heap

In the last example the V compiler could put q and w on the stack because it assumed that in the call q.f(&w) these references were only used for reading and modifying the referred values – and not to pass the references themselves somewhere else. This can be seen in a way that the references to q and w are only borrowed to f().

Things become different if f() is doing something with a reference itself:

struct RefStruct {
mut:
    r &MyStruct
}

// see discussion below
@[heap]
struct MyStruct {
    n int
}

fn main() {
    mut m := MyStruct{}
    mut r := RefStruct{
        r: &m
    }
    r.g()
    println('r: ${r}')
}

fn (mut r RefStruct) g() {
    s := MyStruct{
        n: 7
    }
    r.f(&s) // reference to `s` inside `r` is passed back to `main() `
}

fn (mut r RefStruct) f(s &MyStruct) {
    r.r = s // would trigger error without `[heap]`
}

Here f() looks quite innocent but is doing nasty things – it inserts a reference to s into r. The problem with this is that s lives only as long as g() is running but r is used in main() after that. For this reason the compiler would complain about the assignment in f() because s "might refer to an object stored on stack". The assumption made in g() that the call r.f(&s) would only borrow the reference to s is wrong.

A solution to this dilemma is the [heap] attribute at the declaration of struct MyStruct. It instructs the compiler to always allocate MyStruct-objects on the heap. This way the reference to s remains valid even after g() returns. The compiler takes into consideration that MyStruct objects are always heap allocated when checking f() and allows assigning the reference to s to the r.r field.

There is a pattern often seen in other programming languages:

fn (mut a MyStruct) f() &MyStruct {
    // do something with a
    return &a // would return address of borrowed object
}

Here f() is passed a reference a as receiver that is passed back to the caller and returned as result at the same time. The intention behind such a declaration is method chaining like y = x.f().g(). However, the problem with this approach is that a second reference to a is created – so it is not only borrowed and MyStruct has to be declared as [heap].

In V the better approach is:

struct MyStruct {
mut:
    n int
}

fn (mut a MyStruct) f() {
    // do something with `a`
}

fn (mut a MyStruct) g() {
    // do something else with `a`
}

fn main() {
    x := MyStruct{} // stack allocated
    mut y := x
    y.f()
    y.g()
    // instead of `mut y := x.f().g()
}

This way the [heap] attribute can be avoided – resulting in better performance.

However, stack space is very limited as mentioned above. For this reason the [heap] attribute might be suitable for very large structures even if not required by use cases like those mentioned above.

There is an alternative way to manually control allocation on a case to case basis. This approach is not recommended but shown here for the sake of completeness:

struct MyStruct {
    n int
}

struct RefStruct {
mut:
    r &MyStruct
}

// simple function - just to overwrite stack segment previously used by `g()`

fn use_stack() {
    x := 7.5
    y := 3.25
    z := x + y
    println('${x} ${y} ${z}')
}

fn main() {
    mut m := MyStruct{}
    mut r := RefStruct{
        r: &m
    }
    r.g()
    use_stack() // to erase invalid stack contents
    println('r: ${r}')
}

fn (mut r RefStruct) g() {
    s := &MyStruct{ // `s` explicitly refers to a heap object
        n: 7
    }
    // change `&MyStruct` -> `MyStruct` above and `r.f(s)` -> `r.f(&s)` below
    // to see data in stack segment being overwritten
    r.f(s)
}

fn (mut r RefStruct) f(s &MyStruct) {
    r.r = unsafe { s } // override compiler check
}

Here the compiler check is suppressed by the unsafe block. To make s be heap allocated even without [heap] attribute the struct literal is prefixed with an ampersand: &MyStruct{...}.

This last step would not be required by the compiler but without it the reference inside r becomes invalid (the memory area pointed to will be overwritten by use_stack()) and the program might crash (or at least produce an unpredictable final output). That's why this approach is unsafe and should be avoided!

ORM

(This is still in an alpha state)

V has a built-in ORM (object-relational mapping) which supports SQLite, MySQL and Postgres, but soon it will support MS SQL and Oracle.

V's ORM provides a number of benefits:

Troubleshooting compilation problems with SQLite

On any platform (Windows, Linux, macOS), you can run:

v vlib/db/sqlite/install_thirdparty_sqlite.vsh

This downloads the SQLite amalgamation source and places it in v/thirdparty/sqlite. V will then compile it automatically during your build.

On Linux, you can also install the system development package instead:

Interactive SQLite CLI

V includes a built-in SQLite CLI (v sqlite) as a V-native replacement for sqlite3:

v sqlite mydb.db

It provides a full readline REPL with history and tab completion, 9 output modes, .dump, .import/.export, .backup, session control, and schema tools. Run .help inside the REPL for the full command list.

Convenience Methods

The db.sqlite module includes helper methods for common queries:

db.tables()!         // list all user table names
db.columns('users')! // column names for a table
db.schema('users')!  // CREATE statement(s)
db.db_size()!        // file size in bytes

Using the sqlite VPM package

V also maintains the sqlite VPM package. It wraps an SQLite amalgamation, but otherwise has the same API as db.sqlite.

Its benefit is that you do not need to install a separate system-level SQLite package or library on your system, which can be harder on Windows or musl-based systems. Its downside is that it can make compilation a bit slower, since it compiles SQLite from C in addition to your own code.

To install it, run:

v install sqlite

Then, in your code, use this:

import sqlite

instead of:

import db.sqlite

Writing Documentation

The way it works is very similar to Go. It's very simple: there's no need to write documentation separately for your code, vdoc will generate it from docstrings in the source code.

Documentation for each function/type/const must be placed right before the declaration:

// clearall clears all bits in the array
fn clearall() {
}

The comment must start with the name of the definition.

Sometimes one line isn't enough to explain what a function does, in that case comments should span to the documented function using single line comments:

// copy_all recursively copies all elements of the array by their value,
// if `dupes` is false all duplicate values are eliminated in the process.
fn copy_all(dupes bool) {
    // ...
}

By convention it is preferred that comments are written in present tense.

An overview of the module must be placed in the first comment right after the module's name.

To generate documentation use vdoc, for example v doc net.http.

Newlines in Documentation Comments

Comments spanning multiple lines are merged together using spaces, unless

Tools

v fmt

You don't need to worry about formatting your code or setting style guidelines. v fmt takes care of that:

v fmt file.v

It's recommended to set up your editor, so that v fmt -w runs on every save. A vfmt run is usually pretty cheap (takes <30ms).

Always run v fmt -w file.v before pushing your code.

Disabling the formatting locally

To disable formatting for a block of code, wrap it with // vfmt off and // vfmt on comments.

// Not affected by fmt
// vfmt off

... your code here ...

// vfmt on

// Affected by fmt
... your code here ...

v shader

You can use GPU shaders with V graphical apps. You write your shaders in an annotated GLSL dialect and use v shader to compile them for all supported target platforms.

v shader /path/to/project/dir/or/file.v

Currently you need to include a header and declare a glue function before using the shader in your code.

Profiling

V has good support for profiling your programs: v -profile profile.txt run file.v That will produce a profile.txt file, which you can then analyze.

The generated profile.txt file will have lines with 4 columns:

  1. How many times a function was called.
  2. How much time in total a function took (in ms).
  3. How much time a function took (in ms), on its own, without the calls inside it. It is reliable for multithreaded programs, when tcc is not used.
  4. How much time on average, a call to a function took (in ns).
  5. The name of the v function.You can sort on column 3 (average time per function) using: sort -n -k3 profile.txt|tailYou can also use stopwatches to measure just portions of your code explicitly:
    import time

fn main() {
 sw := time.new_stopwatch()
 println('Hello world')
 println('Greeting the world took: ${sw.elapsed().nanoseconds()}ns')
}

Package management

A V module is a single folder with .v files inside. A V package can contain one or more V modules. A V package should have a v.mod file at its top folder, describing the contents of the package.

That v.mod file is also the package's relative module anchor. When V compiles a file beside or below it, imports are resolved relative to the folder containing v.mod.

V packages are installed normally in your ~/.vmodules folder. That location can be overridden by setting the env variable VMODULES.

Package commands

You can use the V frontend to do package operations, just like you can use it for compiling code, formatting code, vetting code etc.

v [package_command] [param]

where a package command can be one of:

   install           Install a package from VPM.
   remove            Remove a package that was installed from VPM.
   search            Search for a package from VPM.
   update            Update an installed package from VPM.
   upgrade           Upgrade all the outdated packages.
   list              List all installed packages.
   outdated          Show installed packages that need updates.

You can install packages already created by someone else with VPM:

v install [package]

Example:

v install ui

Packages can be installed directly from git or mercurial repositories.

v install [--once] [--git|--hg] [url]

Example:

v install --git https://github.com/vlang/markdown

Sometimes you may want to install the dependencies ONLY if those are not installed:

v install --once [package]

Removing a package with v:

v remove [package]

Example:

v remove ui

Updating an installed package from VPM:

v update [package]

Example:

v update ui

Or you can update all your packages:

v update

To see all the packages you have installed, you can use:

v list

Example:

> v list
Installed packages:
  markdown
  ui

To see all the packages that need updates:

v outdated

Example:

> v outdated
Package are up to date.

Publish package

  1. Put a v.mod file inside the toplevel folder of your package (if you created your package with the command v new mypackage or v init you already have a v.mod file).
    v new mypackage
Input your project description: My nice package.
Input your project version: (0.0.0) 0.0.1
Input your project license: (MIT)
Initialising ...
Complete!
    Example v.mod:
    Module {
    name: 'mypackage'
    base_url: 'src'
    description: 'My nice package.'
    version: '0.0.1'
    license: 'MIT'
    dependencies: []
}
    base_url is optional. When set, V resolves the package sources relative to that folder, next to the v.mod file.Minimal file structure:
    v.mod
mypackage.v
    You can also add subdirs: ['internal'] to v.mod to compile files from selected subdirectories as part of the same module. These paths are relative to the module source root, and files there should declare the same module mypackage.The name of your package should be used with the module directive at the top of all files in your package. For mypackage.v:
    module mypackage

pub fn hello_world() {
    println('Hello World!')
}
  2. Create a git repository in the folder with the v.mod file (this is not required if you used v new or v init):
    git init
git add .
git commit -m "INIT"
  3. Create a public repository on github.com.
  4. Connect your local repository to the remote repository and push the changes.
  5. Add your package to the public V package registry VPM: https://vpm.vlang.io/newYou will have to login with your Github account to register the package. Warning: Currently it is not possible to edit your entry after submitting. Check your package name and github url twice as this cannot be changed by you later.
  6. The final package name is a combination of your github account and the package name you provided e.g. mygithubname.mypackage.Optional: tag your V package with vlang and vlang-package on github.com to allow for a better search experience.

Advanced Topics

Attributes

V has several attributes that modify the behavior of functions and structs.

An attribute is a compiler instruction specified inside [] right before a function/struct/enum declaration and applies only to the following declaration. Attributes with arguments support both name: value and call-style name(value) syntax. Call-style attributes can also use named arguments.

// @[flag] enables Enum types to be used as bitfields

@[flag]
enum BitField {
    read
    write
    other
}

fn main() {
    assert 1 == int(BitField.read)
    assert 2 == int(BitField.write)
    mut bf := BitField.read
    assert bf.has(.read | .other) // test if *at least one* of the flags is set
    assert !bf.all(.read | .other) // test if *all* of the flags are set
    bf.set(.write | .other)
    assert bf.has(.read | .write | .other)
    assert bf.all(.read | .write | .other)
    bf.toggle(.other)
    assert bf == BitField.read | .write
    assert bf.all(.read | .write)
    assert !bf.has(.other)
    empty := BitField.zero()
    assert empty.is_empty()
    assert !empty.has(.read)
    assert !empty.has(.write)
    assert !empty.has(.other)
    mut full := empty
    full.set_all()
    assert int(full) == 7 // 0x01 + 0x02 + 0x04
    assert full == .read | .write | .other
    mut v := full
    v.clear(.read | .other)
    assert v == .write
    v.clear_all()
    assert v == empty
    assert BitField.read == BitField.from('read')!
    assert BitField.other == BitField.from('other')!
    assert BitField.write == BitField.from(2)!
    assert BitField.zero() == BitField.from('')!
}

// @[_allow_multiple_values] allows an enum to have multiple duplicate values.
// Use it carefully, only when you really need it.

@[_allow_multiple_values]
enum ButtonStyle {
    primary   = 1
    secondary = 2
    success   = 3

    blurple = 1
    grey    = 2
    gray    = 2
    green   = 3
}

fn main() {
    assert int(ButtonStyle.primary) == 1
    assert int(ButtonStyle.blurple) == 1

    assert int(ButtonStyle.secondary) == 2
    assert int(ButtonStyle.gray) == 2
    assert int(ButtonStyle.grey) == 2

    assert int(ButtonStyle.success) == 3
    assert int(ButtonStyle.green) == 3

    assert ButtonStyle.primary == ButtonStyle.blurple
    assert ButtonStyle.secondary == ButtonStyle.grey
    assert ButtonStyle.secondary == ButtonStyle.gray
    assert ButtonStyle.success == ButtonStyle.green
}

Struct field deprecations:

module abc

// Note that only *direct* accesses to Xyz.d in *other modules*, will produce deprecation notices/warnings:
pub struct Xyz {
pub mut:
    a int
    d int @[deprecated: 'use Xyz.a instead'; deprecated_after: '2999-03-01']
    // the tags above, will produce a notice, since the deprecation date is in the far future
}

Function/method deprecations:

Functions are deprecated before they are finally removed to give users time to migrate their code. Adding a date is preferable in most cases. An immediate change, without a deprecation date, may be used for functions that are found to be conceptually broken and obsoleted by much better functionality. Other than that setting a date is advisable to grant users a grace period.

Deprecated functions cause warnings, which cause errors if built with -prod. To avoid immediate CI breakage, it is advisable to set a future date, ahead of the date when the code is merged. This gives people who actively developed V projects, the chance to see the deprecation notice at least once and fix the uses. Setting a date in the next 30 days, assumes they would have compiled their projects manually at least once, within that time. For small changes, this should be plenty of time. For complex changes, this time may need to be longer.

Different V projects and maintainers may reasonably choose different deprecation policies. Depending on the type and impact of the change, you may want to consult with them first, before deprecating a function.

// Calling this function will result in a deprecation warning
@[deprecated]
fn old_function() {}

// It can also display a custom deprecation message
@[deprecated: 'use new_function() instead']
fn legacy_function() {}

// Equivalent call-style syntax:
@[deprecated('use new_function() instead')]
fn legacy_function_call_style() {}

// You can also specify a date, after which the function will be
// considered deprecated. Before that date, calls to the function
// will be compiler notices - you will see them, but the compilation
// is not affected. After that date, calls will become warnings,
// so ordinary compiling will still work, but compiling with -prod
// will not (all warnings are treated like errors with -prod).
// 6 months after the deprecation date, calls will be hard
// compiler errors.

@[deprecated: 'use new_function2() instead']
@[deprecated_after: '2021-05-27']
fn legacy_function2() {}

// Equivalent call-style syntax:
@[deprecated(msg: 'use new_function2() instead', after: '2021-05-27')]
fn legacy_function2_call_style() {}

// This function's calls will be inlined.
@[inline]
fn inlined_function() {
}

// This function's calls will NOT be inlined.
@[noinline]
fn function() {
}

// Calls to this function in const and enum expressions can be evaluated at compile time,
// when all call arguments are compile-time constants.
@[comptime]
fn make_mask(value u32, shift u32) u32 {
    return value << shift
}

// This function will NOT return to its callers.
// Such functions can be used at the end of or blocks,
// just like exit/1 or panic/1. Such functions can not
// have return types, and should end either in for{}, or
// by calling other `[noreturn]` functions.
@[noreturn]
fn forever() {
    for {}
}

// The following struct must be allocated on the heap. Therefore, it can only be used as a
// reference (`&Window`) or inside another reference (`&OuterStruct{ Window{...} }`).
// See section "Stack and Heap"
@[heap]
struct Window {
}

// Calls to following function must be in unsafe{} blocks.
// Note that the code in the body of `risky_business()` will still be
// checked, unless you also wrap it in `unsafe {}` blocks.
// This is useful, when you want to have an `[unsafe]` function that
// has checks before/after a certain unsafe operation, that will still
// benefit from V's safety features.
@[unsafe]
fn risky_business() {
    // code that will be checked, perhaps checking pre conditions
    unsafe {
        // code that *will not be* checked, like pointer arithmetic,
        // accessing union fields, calling other `[unsafe]` fns, etc...
        // Usually, it is a good idea to try minimizing code wrapped
        // in unsafe{} as much as possible.
        // See also [Memory-unsafe code](#memory-unsafe-code)
    }
    // code that will be checked, perhaps checking post conditions and/or
    // keeping invariants
}

// V's autofree engine will not take care of memory management in this function.
// You will have the responsibility to free memory manually yourself in it.
// Note: it is NOT related to the garbage collector. It will only make the
// -autofree mechanism, ignore the body of that function.
@[manualfree]
fn custom_allocations() {
}

// The memory pointed to by the pointer arguments of this function will not be
// freed by the garbage collector (if in use) before the function returns
// For C interop only.
@[keep_args_alive]
fn C.my_external_function(voidptr, int, voidptr) int

// A @[weak] tag tells the C compiler, that the next declaration will be weak, i.e. when linking,
// if there is another declaration of a symbol with the same name (a 'strong' one), it should be
// used instead, *without linker errors about duplicate symbols*.
// For C interop only.

@[weak]
__global abc = u64(1)

// Tell V, that the following global was defined on the C side,
// thus V will not initialise it, but will just give you access to it.
// For C interop only.

@[c_extern]
__global my_instance C.my_struct
struct C.my_struct {
    a int
    b f64
}

// Tell V that the following struct is defined with `typedef struct` in C.
// For C interop only.
@[typedef]
pub struct C.Foo {}

// Used to add a custom calling convention to a function, available calling convention: stdcall, fastcall and cdecl.
// This list also applies for type aliases (see below).
// For C interop only.
@[callconv: 'stdcall']
fn C.DefWindowProc(hwnd int, msg int, lparam int, wparam int)

// Used to add a custom calling convention to a function type aliases.
// For C interop only.

@[callconv: 'fastcall']
type FastFn = fn (int) bool

// Calls to the following function, will have to use its return value somehow.
// Ignoring it, will emit warnings.
@[must_use]
fn f() int {
    return 42
}

fn g() {
    // just calling `f()` here, will produce a warning
    println(f()) // this is fine, because the return value was used as an argument
}

// Windows only (and obsolete; instead of it, use `-subsystem windows` when compiling)
// Without this attribute all graphical apps will have the following behavior on Windows:
// If run from a console or terminal; keep the terminal open so all (e)println statements can be viewed.
// If run from e.g. Explorer, by double-click; app is opened, but no terminal is opened, and no
// (e)println output can be seen.
// Use it to force-open a terminal to view output in, even if the app is started from Explorer.
// Valid before main() only.
@[console]
fn main() {
}

Conditional compilation

The goal of this feature, is to tell V to not compile a function, and all its calls, in the final executable, if a provided custom flag is not passed.

V will still type check the function and all its calls, even if they will not be present in the final executable, due to the passed -d flags.

In order to see it in action, run the following example with v run example.v once, and then a second time with v -d trace_logs run example.v:

@[if trace_logs ?]
fn elog(s string) {
    eprintln(s)
}

fn main() {
    elog('some expression: ${2 + 2}') // such calls will not be done *at all*, if `-d trace_logs` is not passed
    println('hi')
    elog('finish')
}

Conditional compilation, based on custom flags, can also be used to produce slightly different executables, which share the majority of the same code, but where some of the logic, is needed only some of the time, for example a network server/client program can be written like so:

fn act_as_client() { ... }
fn act_as_server() { ... }
fn main() {
    $if as_client ? {
        act_as_client()
    }
    $if as_server ? {
        act_as_server()
    }
}

To generate a client.exe executable do: v -d as_client -o client.exe . To generate a server.exe executable do: v -d as_server -o server.exe .

Compile time pseudo variables

V also gives your code access to a set of pseudo string variables, that are substituted at compile time:

Compile time reflection

$ is used as a prefix for compile time (also referred to as 'comptime') operations.

Having built-in JSON support is nice, but V also allows you to create efficient serializers for any data format. V has compile time if and for constructs:

Type metadata

Comptime type expressions expose metadata through fields like .idx, .typ, .unaliased_typ, .indirections, .key_type, .value_type, .element_type, .pointee_type, .payload_type, and .variant_types.

fn zero_payload[T](x ?T) T {
    return $zero(typeof(x).payload_type)
}

fn main() {
    value := ?int(123)
    assert zero_payload(value) == 0
    assert typeof[map[string]int]().key_type == typeof[string]().idx
    assert typeof[?&int]().payload_type == typeof[&int]().idx
}

$zero(Type) returns the zero value for a comptime type expression. $new(Type) returns a pointer to a new zero value.

.fields

You can iterate over struct fields using .fields, it also works with generic types (e.g. T.fields) and generic arguments (e.g. param.fields where fn gen[T](param T) {).

struct User {
    name string
    age  int
}

fn main() {
    $for field in User.fields {
        $if field.typ is string {
            println('${field.name} is of type string')
        }
    }
}

// Output:
// name is of type string

.values

You can read Enum values and their attributes.

enum Color {
    red   @[RED]  // first attribute
    blue  @[BLUE] // second attribute
}

fn main() {
    $for e in Color.values {
        println(e.name)
        println(e.attrs)
    }
}

// Output:
// red
// ['RED']
// blue
// ['BLUE']

.attributes

You can read Struct attributes.

@[COLOR]
struct Foo {
    a int
}

fn main() {
    $for e in Foo.attributes {
        println(e)
    }
}

// Output:
// StructAttribute{
//    name: 'COLOR'
//    has_arg: false
//    arg: ''
//    kind: plain
// }

.variants

You can read variant types from Sum type.

type MySum = int | string

fn main() {
    $for v in MySum.variants {
        $if v.typ is int {
            println('has int type')
        } $else $if v.typ is string {
            println('has string type')
        }
    }
}

// Output:
// has int type
// has string type

.methods

You can retrieve information about struct methods.

struct Foo {
}

fn (f Foo) test() int {
    return 123
}

fn (f Foo) test2() string {
    return 'foo'
}

fn main() {
    foo := Foo{}
    $for m in Foo.methods {
        $if m.return_type is int {
            print('${m.name} returns int: ')
            println(foo.$method())
        } $else $if m.return_type is string {
            print('${m.name} returns string: ')
            println(foo.$method())
        }
    }
}

// Output:
// test returns int: 123
// test2 returns string: foo

.params

You can retrieve information about struct method params.

struct Test {
}

fn (t Test) foo(arg1 int, arg2 string) {
}

fn main() {
    $for m in Test.methods {
        $for param in m.params {
            println('${typeof(param.typ).name}: ${param.name}')
        }
    }
}

// Output:
// int: arg1
// string: arg2

See examples/compiletime/reflection.v for a more complete example.

Compile time code

$if condition

fn main() {
    // Support for multiple conditions in one branch
    $if ios || android {
        println('Running on a mobile device!')
    }
    $if linux && x64 {
        println('64-bit Linux.')
    }
    // Usage as expression
    os := $if windows { 'Windows' } $else { 'UNIX' }
    println('Using ${os}')
    // $else-$if branches
    $if tinyc {
        println('tinyc')
    } $else $if clang {
        println('clang')
    } $else $if gcc {
        println('gcc')
    } $else {
        println('different compiler')
    }
    $if test {
        println('testing')
    }
    // v -cg ...
    $if debug {
        println('debugging')
    }
    // v -prod ...
    $if prod {
        println('production build')
    }
    // v -d option ...
    $if option ? {
        println('custom option')
    }
}

If you want an if to be evaluated at compile time it must be prefixed with a $ sign. Right now it can be used to detect an OS, compiler, platform or compilation options. $if debug is a special option like $if windows or $if x32, it's enabled if the program is compiled with v -g or v -cg. If you're using a custom ifdef, then you do need $if option ? {} and compile withv -d option. Full list of builtin options:

| OS | Compilers | Platforms | Other | |--------------------------------|------------------|-------------------------------|-----------------------------------------------| | windows, linux, macos | gcc, tinyc | amd64, arm64, aarch64 | debug, prod, test | | darwin, ios, bsd | clang, mingw | i386, arm32 | js, glibc, prealloc | | freebsd, openbsd, netbsd | msvc | rv64, rv32, s390x | no_bounds_checking, freestanding | | android, mach, dragonfly | cplusplus | ppc64le | no_segfault_handler, no_backtrace | | gnu, hpux, haiku, qnx | | x64, x32 | no_main, fast_math, apk, threads | | solaris, termux | | little_endian, big_endian | js_node, js_browser, js_freestanding | | serenity, vinix, plan9 | | | interpreter, es5, profile, wasm32 | | | | | wasm32_emscripten, wasm32_wasi | | | | | native, autofree |

$embed_file

import os
fn main() {
    embedded_file := $embed_file('v.png')
    os.write_file('exported.png', embedded_file.to_string())!
}

V can embed arbitrary files into the executable with the $embed_file(<path>) compile time call. Paths can be absolute or relative to the source file.

Paths could also use the compile time pseudo variables @VEXEROOT, @VMODROOT, @DIR, $d and $env.

logo := $embed_file('@VEXEROOT/examples/assets/logo.png')

Note that by default, using $embed_file(file), will always embed the whole content of the file, but you can modify that behaviour by passing: -d embed_only_metadata when compiling your program. In that case, the file will not be embedded. Instead, it will be loaded the first time your program calls embedded_file.data() at runtime, making it easier to change in external editor programs, without needing to recompile your program.

Embedding a file inside your executable, will increase its size, but it will make it more