| * [Hello world](#hello-world) * [Comments](#comments) * [Functions](#functions) * [Variables](#variables) * [Types](#types) * [Primitive types](#primitive-types) * [Strings](#strings) * [Numbers](#numbers) * [Arrays](#arrays) * [Maps](#maps) * [Module Imports](#module-imports) * [Statements & Expressions](#statements--expressions) * [If](#if) * [In Operator](#in-operator) * [For loop](#for-loop) * [Match](#match) * [Defer](#defer) * [Structs](#structs) * [Trailing struct literal syntax](#short-struct-initialization-syntax) * [Access modifiers](#access-modifiers) * [Methods](#methods) | * [println](#println) * [Functions 2](#functions-2) * [Pure functions by default](#pure-functions-by-default) * [Mutable arguments](#mutable-arguments) * [Anonymous & high order functions](#anonymous--high-order-functions) * [References](#references) * [Modules](#modules) * [Constants](#constants) * [Types 2](#types-2) * [Interfaces](#interfaces) * [Enums](#enums) * [Sum types](#sum-types) * [Option/Result types & error handling](#optionresult-types-and-error-handling) * [Generics](#generics) * [Concurrency](#concurrency) * [Decoding JSON](#decoding-json) * [Testing](#testing) * [Memory management](#memory-management) * [ORM](#orm) | * [Writing documentation](#writing-documentation) * [Tools](#tools) * [vfmt](#vfmt) * [Profiling](#profiling) * [Advanced](#advanced) * [Calling C functions from V](#calling-c-functions-from-v) * [Debugging generated C code](#debugging-generated-c-code) * [Conditional compilation](#conditional-compilation) * [Compile time pseudo variables](#compile-time-pseudo-variables) * [Reflection via codegen](#reflection-via-codegen) * [Limited operator overloading](#limited-operator-overloading) * [Inline assembly](#inline-assembly) * [Translating C/C++ to V](#translating-cc-to-v) * [Hot code reloading](#hot-code-reloading) * [Cross compilation](#cross-compilation) * [Cross-platform shell scripts in V](#cross-platform-shell-scripts-in-v) * [Attributes](#attributes) * [Appendices](#appendices) * [Keywords](#appendix-i-keywords) * [Operators](#appendix-ii-operators) |
```v fn foo() (int, int) { return 2, 3 } a, b := foo() println(a) // 2 println(b) // 3 c, _ := foo() // ignore values using `_` ``` Functions can return multiple values.
```v pub fn public_function() { } fn private_function() { } ``` Like constants and types, functions are private (not exported) by default. To allow other modules to use them, prepend `pub`. The same applies to constants and types. ## Variables ```v 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. Global (module level) variables are not allowed. There's no global state in V.
```v 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. Note the (important) difference between `:=` and `=` `:=` is used for declaring and initializing, `=` is used for assigning.
```v fn main() { age = 21 } ``` This code will not compile, because the variable `age` is not declared. All variables need to be declared in V.
```v fn main() { age := 21 } ``` ### 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).
```v fn main() { a := 10 if true { a := 20 } } ``` 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. ## Types ### Primitive types ```v bool string i8 i16 int i64 i128 (soon) byte u16 u32 u64 u128 (soon) rune // represents a Unicode code point f32 f64 any_int, any_float // internal intermediate types of number literals byteptr, voidptr, charptr, size_t // these are mostly used for C interoperability any // similar to C's void* and Go's interface{} ``` Please note that unlike C and Go, `int` is always a 32 bit integer. There is an exceptions 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 ↗ ↗ byte → u16 → u32 → u64 ⬎ ↘ ↘ ↘ ptr i8 → i16 → int → i64 ⬏ ``` An `int` value for example can be automatically promoted to `f64` or `i64` but not to `f32` or `u32`. (`f32` would mean precision loss for large values and `u32` would mean loss of the sign for negative values). ### Strings ```v name := 'Bob' println('Hello, $name!') // `$` is used for string interpolation println(name.len) bobby := name + 'by' // + is used to concatenate strings println(bobby) // "Bobby" println(bobby[1..3]) // "ob" mut s := 'hello ' s += 'world' // `+=` is used to append to a string println(s) // "hello world" ``` In V, a string is a read-only array of bytes. String data is encoded using UTF-8. Strings are immutable. 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. Interpolation syntax is pretty simple. It also works with fields: `'age = $user.age'`. If you need more complex expressions, use `${}`: `'can register = ${user.age > 13}'`. Format specifiers similar to those in C's `printf()` are also supported. `f`, `g`, `x`, etc. are optional and specify the output format. The compiler takes care of the storage size, so there is no `hd` or `llu`. ```v println('x = ${x:12.3f}') println('${item:-20} ${n:20d}') ``` All operators in V must have values of the same type on both sides. This code will not compile if `age` is not a string (for example if `age` were an `int`): ```v println('age = ' + age) ``` We have to either convert `age` to a `string`: ```v println('age = ' + age.str()) ``` or use string interpolation (preferred): ```v println('age = $age') ``` To denote character literals, use ` ```v a := `a` assert 'aloha!'[0] == `a` ``` For raw strings, prepend `r`. Raw strings are not escaped: ```v s := r'hello\nworld' println(s) // "hello\nworld" ``` ### Numbers ```v a := 123 ``` This will assign the value of 123 to `a`. By default `a` will have the type `int`. You can also use hexadecimal, binary or octal notation for integer literals: ```v a := 0x7B b := 0b01111011 c := 0o173 ``` All of these will be assigned the same value, 123. They will all have type `int`, no matter what notation you used. V also supports writing numbers with `_` as separator: ```v num := 1_000_000 // same as 1000000 three := 0b0_11 // same as 0b11 float_num := 3_122.55 // same as 3122.55 hexa := 0xF_F // same as 255 oct := 0o17_3 // same as 0o173 ``` If you want a different type of integer, you can use casting: ```v a := i64(123) b := byte(42) c := i16(12345) ``` Assigning floating point numbers works the same way: ```v f := 1.0 f1 := f64(3.14) f2 := f32(3.14) ``` If you do not specify the type explicitly, by default float literals will have the type of `f64`. ### Arrays ```v mut nums := [1, 2, 3] println(nums) // "[1, 2, 3]" println(nums[1]) // "2" nums[1] = 5 println(nums) // "[1, 5, 3]" println(nums.len) // "3" nums = [] // The array is now empty println(nums.len) // "0" // Declare an empty array: users := []int{} // We can also preallocate a certain amount of elements. ids := []int{ len: 50, init: 0 } // This creates an array with 50 zeros ``` The type of an array is determined by the first element: * `[1, 2, 3]` is an array of ints (`[]int`). * `['a', 'b']` is an array of strings (`[]string`). If V is unable to infer the type of an array, the user can explicitly specify it for the first element: `[byte(0x0E), 0x1F, 0xBA, 0x0E]` V arrays are homogeneous (all elements must have the same type). This means that code like `[1, 'a']` will not compile. `.len` field returns the length of the array. Note that it's a read-only field, and it can't be modified by the user. Exported fields are read-only by default in V. See [Access modifiers](#access-modifiers). ```v mut nums := [1, 2, 3] nums << 4 println(nums) // "[1, 2, 3, 4]" // append array nums << [5, 6, 7] println(nums) // "[1, 2, 3, 4, 5, 6, 7]" mut names := ['John'] names << 'Peter' names << 'Sam' // names << 10 <-- This will not compile. `names` is an array of strings. println(names.len) // "3" println('Alex' in names) // "false" ``` `<<` is an operator that appends a value to the end of the array. It can also append an entire array. `val in array` returns true if the array contains `val`. See [`in` operator](#in-operator). During initialization you can specify the capacity of the array (`cap`), its initial length (`len`), and the default element (`init`). Setting the capacity improves performance of insertions, as it reduces the amount of reallocations in dynamic arrays: ```v mut numbers := []int{ cap: 1000 } // Now able to add new elements without reallocating for i in 0 .. 1000 { numbers << i // same as // numbers[i] = i } ``` `[]int{ len: 5, init: -1 }` will create `[-1, -1, -1, -1, -1]`. #### Array methods All arrays can be easily printed with `println(arr)` and converted to a string with `s := arr.str()`. Arrays can be efficiently filtered and mapped with the `.filter()` and `.map()` methods: ```v nums := [1, 2, 3, 4, 5, 6] even := nums.filter(it % 2 == 0) println(even) // [2, 4, 6] words := ['hello', 'world'] upper := words.map(it.to_upper()) println(upper) // ['HELLO', 'WORLD'] ``` `it` is a builtin variable which refers to element currently being processed in filter/map methods. ### Maps ```v mut m := map[string]int // Only maps with string keys are allowed for now 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 m.delete('two') // Short syntax numbers := { 'one': 1 'two': 2 } ``` ## Module Imports For information about creating a module, see [Modules](#modules) ### Importing a Module Modules can be imported using keyword `import`. ```v import os fn main() { name := os.input('Enter your name:') println('Hello, $name!') } ``` When using constants from other modules, the module name must be prefixed. However, you can import functions and types from other modules directly: ```v import os { input } import crypto.sha256 { sum } import time { Time } ``` ### 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.v` ```v 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. ```v import time type MyTime time.Time fn main() { my_time := MyTime{ year: 2020, month: 12, day: 25 } println(my_time.unix_time()) } ``` ## Statements & Expressions ### If ```v a := 10 b := 20 if a < b { println('$a < $b') } else if a > b { println('$a > $b') } else { println('$a == $b') } ``` `if` statements are pretty straightforward and similar to most other languages. Unlike other C-like languages, there are no parentheses surrounding the condition, and the braces are always required. `if` can be used as an expression: ```v num := 777 s := if num % 2 == 0 { 'even' } else { 'odd' } println(s) // "odd" ``` #### Is check You can check sum types using `if` like `match`ing them. ```v 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 castet to Abc and can be used here println(x) } ``` If you have a struct field which should be checked, there is also a way to name a alias. ``` if x.bar is MyStruct as bar { // x.bar cannot be castet automatically, instead you say "as bar" which creates a variable with the MyStruct typing println(bar) } ``` ### In operator `in` allows to check whether an array or a map contains an element. ```v nums := [1, 2, 3] println(1 in nums) // true m := {'one': 1, 'two': 2} println('one' in m) // true ``` It's also useful for writing clearer and more compact boolean expressions: ```v 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 construct: `for`. ```v numbers := [1, 2, 3, 4, 5] for num in numbers { println(num) } names := ['Sam', 'Peter'] for i, name in names { println('$i) $name') // Output: 0) Sam } // 1) Peter ``` The `for value in` loop is used for going through elements of an array. If an index is required, an alternative form `for index, value in` can be used. Note, that the value is read-only. If you need to modify the array while looping, you have to use indexing: ```v mut numbers := [0, 1, 2] for i, _ in numbers { numbers[i]++ } println(numbers) // [1, 2, 3] ``` When an identifier is just a single underscore, it is ignored. ```v mut sum := 0 mut i := 0 for i <= 100 { sum += i i++ } println(sum) // "5050" ``` This form of the loop is similar to `while` loops in other languages. The loop will stop iterating once the boolean condition evaluates to false. Again, there are no parentheses surrounding the condition, and the braces are always required. ```v mut num := 0 for { num++ if num >= 10 { break } } println(num) // "10" ``` The condition can be omitted, resulting in an infinite loop. ```v for i := 0; i < 10; i++ { // 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. ### Match ```v os := 'windows' print('V is running on ') match os { 'darwin' { println('macOS.') } 'linux' { println('Linux.') } else { println(os) } } ``` A match statement is a shorter way to write a sequence of `if - else` statements. When a matching branch is found, the following statement block will be run. The else branch will be run when no other branches match. ```v number := 2 s := match number { 1 { 'one' } 2 { 'two' } else { 'many'} } ``` A match expression returns the final expression from each branch. ```v enum Color { red blue green } fn is_red_or_blue(c Color) bool { return match c { .red { true } .blue { true } .green { false } } } ``` A match statement can also be used to branch on the variants of an `enum` by using the shorthand `.variant_here` syntax. An `else` branch is not allowed when all the branches are exhaustive. ```v c := `v` typ := match c { `0`...`9` { 'digit' } `A`...`Z` { 'uppercase' } `a`...`z` { 'lowercase' } else { 'other' } } println(typ) // 'lowercase' ``` 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. ### Defer A defer statement defers the execution of a block of statements until the surrounding function returns. ```v fn read_log() { 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, the file will be closed } ``` ## Structs ```v struct Point { x int y int } mut p := Point{ x: 10 y: 20 } println(p.x) // Struct fields are accessed using a dot // Alternative literal syntax for structs with 3 fields or fewer p = Point{10, 20} assert p.x == 10 // you can omit the struct name when it's already known p = {x: 30, y: 4} assert p.y == 4 ``` Omitting the struct name also works for function arguments.
Structs are allocated on the stack. To allocate a struct on the heap and get a reference to it, use the `&` prefix: ```v 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.
V doesn't allow subclassing, but it supports embedded structs: ```v // TODO: this will be implemented later struct Button { Widget title string } button := new_button('Click me') button.set_pos(x, y) // Without embedding we'd have to do button.widget.set_pos(x,y) ```
```v struct Foo { n int // n is 0 by default s string // s is '' by default a []int // a is `[]int{}` by default pos int = -1 // custom default value } ``` All struct fields are zeroed by default during the creation of the struct. Array and map fields are allocated. It's also possible to define custom default values. ### Trailing struct literal syntax There are no default function arguments or named arguments, for that trailing struct literal syntax can be used instead: ```v struct ButtonConfig { text string is_disabled bool width int = 70 height int = 20 } 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, we can use ``` new_button(text:'Click me', width:100) ``` instead of ``` new_button(ButtonConfig{text:'Click me', width:100}) ``` This only works for functions that have a struct for the last argument. ### Access modifiers Struct fields are private and immutable by default (making structs immutable as well). Their access modifiers can be changed with `pub` and `mut`. In total, there are 5 possible options: ```v struct Foo { a int // private immutable (default) mut: b int // private mutable c int // (you can list multiple fields with the same access modifier) pub: d int // public immutable (readonly) pub mut: e int // public, but mutable only in parent module __global: f int // public and mutable both inside and outside parent module } // (not recommended to use, that's why the 'global' keyword // starts with __) ``` For example, here's the `string` type defined in the `builtin` module: ```v struct string { str byteptr pub: len int } ``` It's easy to see from this definition that `string` is an immutable type. The byte pointer with the string data is not accessible outside `builtin` at all. The `len` field is public, but immutable: ```v fn main() { str := 'hello' len := str.len // OK str.len++ // Compilation error } ``` This means that defining public readonly fields is very easy in V, no need in getters/setters or properties. ### Methods ```v struct User { age int } fn (u User) can_register() bool { return u.age > 16 } user := User{age: 10} println(user.can_register()) // "false" user2 := User{age: 20} println(user2.can_register()) // "true" ``` V doesn't have classes. But you can define methods on types. A method is a function with a special receiver argument. The receiver appears in its own argument list between the `fn` keyword and the method name. 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. ## Functions 2 ### Pure functions by default V functions are pure by default, meaning that their return values are a function of their arguments only, and their evaluation has no side effects. This is achieved by a lack of global variables and all function arguments being immutable by default, even when [references](#references) are passed. V is not a purely functional language however. 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 using the keyword `mut`: ```v struct User { 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 simply the first argument) is marked as mutable, so `register()` can change the user object. The same works with non-receiver arguments: ```v fn multiply_by_2(mut arr []int) { for i in 0..arr.len { arr[i] *= 2 } } mut nums := [1, 2, 3] multiply_by_2(mut nums) println(nums) // "[2, 4, 6]" ``` Note, that you have to add `mut` before `nums` when calling this function. This makes it clear that the function being called will modify the value. It is preferable to return values instead of modifying arguments. 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 such as integers. Only more complex types such as arrays and maps may be modified. Use `user.register()` or `user = register(user)` instead of `register(mut user)`. V makes it easy to return a modified version of an object: ```v fn register(u User) User { return { u | is_registered: true } } user = register(user) ``` ### Anonymous & high order functions ```v fn sqr(n int) int { return n * n } fn run(value int, op fn(int) int) int { return op(value) } fn main() { 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 }) } ``` ## References ```v 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 value or reference. The compiler will determine this by itself, and the developer doesn't need to think about it. You no longer need to remember whether you should pass the struct by value or by reference. You can ensure that the struct is always passed by reference by adding `&`: ```v fn (foo &Foo) bar() { println(foo.abc) } ``` `foo` is still immutable and can't be changed. For that, `(mut foo Foo)` has to be used. In general, V's references are similar to Go pointers and C++ references. For example, a tree structure definition would look like this: ```v struct Node