80 KiB
V Documentation
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 half an hour, 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.
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 the return type can be omitted.
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 one 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')
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.
Just like in Go and C, functions cannot be overloaded. This simplifies the code and improves maintainability and readability.
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 `_`
Variable number of arguments
fn sum(a ...int) int {
mut total := 0
for x in a {
total += x
}
return total
}
println(sum()) // Output: 0
println(sum(1)) // 1
println(sum(2,3)) // 5
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 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. Global (module level) variables are not allowed. There's no global state in V (see Pure functions by default for 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
}
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).
fn main() {
a := 10
if true {
a := 20 // error: shadowed variable
}
// warning: unused variable `a`
}
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
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 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
↗ ↗
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
name := 'Bob'
println(name.len)
println(name[0]) // indexing gives a byte B
println(name[1..3]) // slicing gives a string 'ob'
windows_newline := '\r\n' // escape special characters like in C
assert windows_newline.len == 2
In V, a string is a read-only array of bytes. String data is encoded using UTF-8. String values are immutable. You cannot mutate elements:
mut s := 'hello 🌎'
s[0] = `H` // not allowed
error: cannot assign to
s[i]
since V strings are immutable
Note that indexing a string will produce a byte
, not a rune
. Indexes correspond
to bytes in the string, not Unicode code points.
Character literals have type rune
. To denote them, use `
rocket := `🚀`
assert 'aloha!'[0] == `a`
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.
For raw strings, prepend r
. Raw strings are not escaped:
s := r'hello\nworld'
println(s) // "hello\nworld"
String interpolation
Basic interpolation syntax is pretty simple - use $
before a variable name.
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'
.
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
.
x := 123.4567
println('x = ${x:4.2f}')
println('[${x:10}]') // pad with spaces on the left
println('[${int(x):-10}]') // pad with spaces on the right
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) asstring
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')
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 := byte(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
.
Arrays
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{}
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(16), 32, 64, 128]
.
V arrays are homogeneous (all elements must have the same type).
This means that code like [1, 'a']
will not compile.
The .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.
Array operations
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.
Initializing array properties
During initialization you can specify the capacity of the array (cap
), its initial length (len
),
and the default element (init
):
arr := []int{ len: 5, init: -1 } // `[-1, -1, -1, -1, -1]`
Setting the capacity improves performance of insertions, as it reduces the number of reallocations needed:
mut numbers := []int{ cap: 1000 }
println(numbers.len) // 0
// Now appending elements won't reallocate
for i in 0 .. 1000 {
numbers << i
}
Note: The above code uses a range for
statement.
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:
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.
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]]]
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
Maps
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 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.
Selective imports
You can also import specific functions and types from modules directly:
import os { input }
import crypto.sha256 { sum }
import time { Time }
Note: 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')
os := user_os()
println('Your OS is ${os}.')
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
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
type MyTime = time.Time
fn (mut t MyTime) century() int {
return 1 + t.year % 100
}
fn main() {
mut my_time := MyTime{
year: 2020,
month: 12,
day: 25
}
println(time.new_time(my_time).utc_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
can be used as an expression:
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.
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 you have a struct field which should be checked, there is also a way to name an alias.
struct MyStruct {x int}
struct MyStruct2 {y string}
type MySumType = MyStruct | MyStruct2
struct Abc { bar MySumType }
x := Abc{ bar: MyStruct{123} }
if x.bar is MyStruct as bar {
// x.bar cannot be cast automatically
// you must explicitly state "as bar" to create a variable with the MyStruct type
println(bar)
}
In operator
in
allows to check whether an array or a map contains an element.
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 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.
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 have to use indexing:
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.
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 identifer.
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
.
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;; 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
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 expression returns the final expression from each 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'
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.
Note: match
as an expression is not usable in for
loop and if
statements.
Defer
A defer statement defers the execution of a block of statements until the surrounding function returns.
import os
fn read_log() {
mut ok := false
mut f := os.open('log.txt') or { panic(err) }
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
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
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.
Embedded structs
V doesn't allow subclassing, but it supports embedded structs:
struct Widget {
mut:
x int
y int
}
struct Button {
mut:
Widget
title string
}
mut button := Button{title: 'Click me'}
button.x = 3
Without embedding we'd have to name the Widget
field and do:
button.widget.x = 3
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.
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
struct Point{
x int
y int
}
mut p := Point{x: 10, y: 20}
// 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 returning a struct literal or passing one as a function argument.
Trailing struct literal arguments
V doesn't have default function arguments or named arguments, for that trailing struct literal syntax can be used instead:
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.
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:
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:
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:
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
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 (besides I/O).
This is achieved by a lack of global variables and all function arguments being immutable by default, even when 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
:
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 simply the first argument) is 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. 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.
Use user.register()
or user = register(user)
instead of register(mut user)
.
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 { u | is_registered: true }
}
mut user := User{name: 'abc' age: 23}
user = register(user)
println(user)
Anonymous & high order functions
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
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
right &Node
}
Constants
const (
pi = 3.14
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.
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, g, b int) Color { return Color{r: r, g: g, b: b} }
const (
numbers = [1, 2, 3]
red = Color{r: 255, g: 0, b: 0}
// evaluate function call at compile-time
blue = rgb(0, 0, 255)
)
println(numbers)
println(red)
println(blue)
Global variables are not allowed, so this can be really useful.
println('Top cities: $top_cities.filter(.usa)')
println and other builtin functions
println
is a simple yet powerful builtin function. It 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}"
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)
If you don't want to print a newline, use print()
instead.
The number of builtin functions is low. Other builtin functions are:
fn exit(exit_code int)
fn panic(message string)
fn print_backtrace()
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'.
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!')
}
You can now use mymodule
in your code:
import mymodule
fn main() {
mymodule.say_hi()
}
- Module names should be short, under 10 characters.
- Circular imports are not allowed.
- You can have as many .v files in a module as you want.
- You can create modules anywhere.
- All modules are compiled statically into a single executable.
init
functions
If you want a module to automatically call some setup/initialization code when it is imported,
you can use a module init
function:
fn init() {
// your setup code here ...
}
The init
function cannot be public - it will be called automatically. This feature is
particularly useful for initializing a C library.
Types 2
Interfaces
struct Dog {
breed string
}
struct Cat {
}
fn (d Dog) speak() string {
return 'woof'
}
fn (c Cat) speak() string {
return 'meow'
}
interface Speaker {
speak() string
}
dog := Dog{'Leonberger'}
cat := Cat{}
mut arr := []Speaker{}
arr << dog
arr << cat
for item in arr {
item.speak()
}
A type implements an interface by implementing its methods. There is no explicit declaration of intent, no "implements" keyword.
We can test the underlying type of an interface using dynamic cast operators:
fn announce(s Speaker) {
if s is Dog {
println('a $s.breed') // `s` is automatically cast to `Dog` (smart cast)
} else if s is Cat {
println('a cat')
} else {
println('something else')
}
}
For more information, see Dynamic casts.
Enums
enum Color {
red green blue
}
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 { ... }
.green { ... }
.blue { ... }
}
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.
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 = Moon | Mars | 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.
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 = Moon | Mars | 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. You can also specify a variable name:
if w is Mars as mars {
assert typeof(w).name == 'World'
if mars.dust_storm() {
println('bad weather!')
}
}
w
keeps its original type. This form is necessary if w
is a more
complex expression than just a variable name.
Matching sum types
You can also use match
to determine the variant:
struct Moon {}
struct Mars {}
struct Venus {}
type World = Moon | Mars | 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.
There are two ways to access the cast variant inside a match branch:
- the shadowed match variable
- using
as
to specify a variable name
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 {}
}
// using `as` to specify a name for each value
match w as var {
Mars { var.shiver() }
Venus { var.sweat() }
else {
// w is of type World
assert w is Moon
}
}
}
Note: shadowing only works when the match expression is a variable. It will not work on struct fields, array indexes, or map keys.
Option/Result types and error handling
Option types are declared with ?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 an option type
return user
}
}
return error('User $id not found')
}
fn main() {
repo := Repo {
users: [User{1, 'Andrew'}, User {2, 'Bob'}, User {10, 'Charles'}]
}
user := repo.find_user_by_id(10) or { // Option types must be handled by `or` blocks
return
}
println(user.id) // "10"
println(user.name) // "Charles"
}
V combines Option
and Result
into one type, so you don't need to decide which one to use.
The amount of work required to "upgrade" a function to an optional function is minimal;
you have to add a ?
to the return type and return an error when something goes wrong.
If you don't need to return an error message, you can simply return none
(this is a more efficient equivalent of return error("")
).
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. err
is empty if none
was returned.
user := repo.find_user_by_id(7) or {
println(err) // "User 7 not found"
return
}
Handling optionals
There are four ways of handling an optional. The first method is to propagate the error:
import net.http
fn f(url string) ?string {
resp := http.get(url) ?
return resp.text
}
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 optional, the enclosing function must return
an optional 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 error(err)
}
return resp.text
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 that break
and continue
can only be used inside a for
loop.
V does not have a way to forcibly "unwrap" an optional (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') // Could be `return none` as well
}
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.text) // resp is a http.Response, not an optional
} 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.
Generics
struct Repo<T> {
db DB
}
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>
At the moment only one type parameter named T
is supported.
Currently generic function definitions must declare their type parameters, but in
future V will infer generic type parameters from single-letter type names in
runtime parameter types. This is why find_by_id
can omit <T>
, because the
receiver argument r
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
V's model of concurrency is very similar to Go's. To run foo()
concurrently, just
call it with go foo()
. Right now, it launches the function on a new system
thread. Soon coroutines and a scheduler will be implemented.
import sync
import time
fn task(id, duration int, mut wg sync.WaitGroup) {
println("task ${id} begin")
time.sleep_ms(duration)
println("task ${id} end")
wg.done()
}
fn main() {
mut wg := sync.new_waitgroup()
wg.add(3)
go task(1, 500, mut wg)
go task(2, 900, mut wg)
go task(3, 100, mut wg)
wg.wait()
println('done')
}
// Output: task 1 begin
// task 2 begin
// task 3 begin
// task 3 end
// task 1 end
// task 2 end
// done
Channels
Channels are the preferred way to communicate between coroutines. V's channels work basically like
those in Go. You can push objects into a channel on one end and pop objects from the other end.
Channels can be buffered or unbuffered and it is possible to select
from multiple channels.
Syntax and Usage
Channels have the type chan objtype
. An optional buffer length can specified as the cap
property
in the declaration:
ch := chan int{} // unbuffered - "synchronous"
ch2 := chan f64{cap: 100} // buffer length 100
Channels do not have to be declared as mut
. The buffer length is not part of the type but
a property of the individual channel object. Channels can be passed to coroutines like normal
variables:
fn f(ch chan int) {
// ...
}
fn main() {
ch := chan int{}
go f(ch)
// ...
}
Objects can be pushed to channels using the arrow operator. The same operator can be used to pop objects from the other end:
mut ch := chan int{}
mut ch2 := chan f64{}
n := 5
x := 7.3
ch <- n // push
ch2 <- x
mut y := f64(0.0)
m := <-ch // pop creating new variable
y = <-ch2 // pop into existing variable
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 branch (see Handling Optionals).
mut ch := chan int{}
mut ch2 := chan f64{}
// ...
ch.close()
// ...
m := <-ch or {
println('channel has been closed')
}
// propagate error
y := <-ch2 ?
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 () {
mut c := chan f64{}
mut ch := chan f64{}
mut ch2 := chan f64{}
mut ch3 := chan f64{}
mut b := 0.0
// ...
select {
a := <-ch {
// do something with `a`
}
b = <-ch2 {
// do something with predeclared variable `b`
}
ch3 <- c {
// do something if `c` was sent
}
> 500 * time.millisecond {
// do something if no channel has become ready within 0.5s
}
}
}
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.
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 properties and methods:
struct Abc{x int}
a := 2.13
mut ch := chan f64{}
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
println(l)
println(c)
// mut b := Abc{}
// mut ch2 := chan f64{}
// 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.
Usage of these methods and properties in production is not recommended -
algorithms based on them are often subject to race conditions. Use select
instead.
Data can be exchanged between a coroutine and the calling thread via a shared variable.
Such variables should be created as references and passed to the coroutine as mut
.
The underlying struct
should also contain a mutex
to lock concurrent access:
import sync
struct St {
mut:
x int // share data
mtx &sync.Mutex
}
fn (mut b St) g() {
b.mtx.m_lock()
// read/modify/write b.x
b.mtx.unlock()
}
fn caller() {
mut a := &St{ // create as reference so it's on the heap
x: 10
mtx: sync.new_mutex()
}
go a.g()
a.mtx.m_lock()
// read/modify/write a.x
a.mtx.unlock()
}
Decoding JSON
import json
struct Foo {
x int
}
struct User {
name string
age int
// Use the `skip` attribute to skip certain fields
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 }'
user := json.decode(User, data) or {
eprintln('Failed to decode json')
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)
Because of the ubiquitous nature of JSON, support for it is built directly into V.
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.
V generates code for JSON encoding and decoding. No runtime reflection is used. This results in much better performance.
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 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.
Test files
// hello.v
module main
fn hello() string {
return 'Hello world'
}
fn main() {
println(hello())
}
module main
// hello_test.v
fn test_hello() {
assert hello() == 'Hello world'
}
To run the test 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.
- All test functions have to be inside a test file whose name ends in
_test.v
. - Test function names must begin with
test_
to mark them for execution. - Normal functions can also be defined in test files, and should be called manually. Other symbols can also be defined in test files e.g. types.
- There are two kinds of tests: external and internal.
- Internal tests must declare their module, just like all other .v files from the same module. Internal tests can even call private functions in the same module.
- External tests must import the modules which they test. They do not have access to the private functions/types of the modules. They can test only the external/public API that a module provides.
In the example above, test_hello
is an internal test, that can call
the private function hello()
because hello_test.v
has module main
,
just like hello.v
, i.e. both are part of the same module. Note also that
since module main
is a regular module like the others, internal tests can
be used to test private functions in your main program .v files too.
You can also define special test functions in a test file:
testsuite_begin
which will be run before all other test functions.testsuite_end
which will be run after all other test functions.
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.
Memory management
(Work in progress)
V doesn't use garbage collection or reference counting. The compiler cleans everything up during compilation. If your V program compiles, it's guaranteed that it's going to be leak free. For example:
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, the first two calls won't result in any allocations at all. These two strings are small, 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
}
ORM
(This is still in an alpha state)
V has a built-in ORM (object-relational mapping) which supports SQLite, and will soon support MySQL, Postgres, MS SQL, and Oracle.
V's ORM provides a number of benefits:
- One syntax for all SQL dialects. (Migrating between databases becomes much easier.)
- Queries are constructed using V's syntax. (There's no need to learn another syntax.)
- Safety. (All queries are automatically sanitised to prevent SQL injection.)
- Compile time checks. (This prevents typos which can only be caught during runtime.)
- Readability and simplicity. (You don't need to manually parse the results of a query and then manually construct objects from the parsed results.)
import sqlite
struct Customer { // struct name has to be the same as the table name (for now)
id int // a field named `id` of integer type must be the first field
name string
nr_orders int
country string
}
db := sqlite.connect('customers.db')?
// select count(*) from Customer
nr_customers := sql db { select count from Customer }
println('number of all customers: $nr_customers')
// V syntax can be used to build queries
// db.select returns an array
uk_customers := sql db { select from Customer where country == 'uk' && nr_orders > 0 }
println(uk_customers.len)
for customer in uk_customers {
println('$customer.id - $customer.name')
}
// by adding `limit 1` we tell V that there will be only one object
customer := sql db { select from Customer where id == 1 limit 1 }
println('$customer.id - $customer.name')
// insert a new customer
new_customer := Customer{name: 'Bob', nr_orders: 10}
sql db { insert new_customer into Customer }
For more examples, see vlib/orm/orm_test.v.
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.
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
.
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.
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: a) how many times a function was called b) how much time in total a function took (in ms) c) how much time on average, a call to a function took (in ns) d) the name of the v function
You can sort on column 3 (average time per function) using:
sort -n -k3 profile.txt|tail
You 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')
}
Advanced Topics
Memory-unsafe code
Sometimes for efficiency you may want to write low-level code that can potentially corrupt memory or be vulnerable to security exploits. V supports writing such code, but not by default.
V requires that any potentially memory-unsafe operations are marked intentionally. Marking them also indicates to anyone reading the code that there could be memory-safety violations if there was a mistake.
Examples of potentially memory-unsafe operations are:
- Pointer arithmetic
- Pointer indexing
- Conversion to pointer from an incompatible type
- Calling certain C functions, e.g.
free
,strlen
andstrncmp
.
To mark potentially memory-unsafe operations, enclose them in an unsafe
block:
// allocate 2 uninitialized bytes & return a reference to them
mut p := unsafe { malloc(2) }
p[0] = `h` // Error: pointer indexing is only allowed in `unsafe` blocks
unsafe {
p[0] = `h` // OK
p[1] = `i`
}
p++ // Error: pointer arithmetic is only allowed in `unsafe` blocks
unsafe {
p++ // OK
}
assert *p == `i`
Best practice is to avoid putting memory-safe expressions inside an unsafe
block,
so that the reason for using unsafe
is as clear as possible. Generally any code
you think is memory-safe should not be inside an unsafe
block, so the compiler
can verify it.
If you suspect your program does violate memory-safety, you have a head start on
finding the cause: look at the unsafe
blocks (and how they interact with
surrounding code).
- Note: This is work in progress.
Calling C functions from V
#flag -lsqlite3
#include "sqlite3.h"
// See also the example from https://www.sqlite.org/quickstart.html
struct C.sqlite3{}
struct C.sqlite3_stmt{}
type FnSqlite3Callback = fn(voidptr, int, &charptr, &charptr) int
fn C.sqlite3_open(charptr, &&C.sqlite3) int
fn C.sqlite3_close(&C.sqlite3) int
fn C.sqlite3_column_int(stmt &C.sqlite3_stmt, n int) int
// ... you can also just define the type of parameter & leave out the C. prefix
fn C.sqlite3_prepare_v2(&sqlite3, charptr, int, &&sqlite3_stmt, &charptr) int
fn C.sqlite3_step(&sqlite3_stmt)
fn C.sqlite3_finalize(&sqlite3_stmt)
fn C.sqlite3_exec(db &sqlite3, sql charptr, FnSqlite3Callback, cb_arg voidptr, emsg &charptr) int
fn C.sqlite3_free(voidptr)
fn my_callback(arg voidptr, howmany int, cvalues &charptr, cnames &charptr) int {
for i in 0..howmany {
print('| ${cstring_to_vstring(cnames[i])}: ${cstring_to_vstring(cvalues[i]):20} ')
}
println('|')
return 0
}
fn main() {
db := &C.sqlite3(0) // this means `sqlite3* db = 0`
// passing a string literal to a C function call results in a C string, not a V string
C.sqlite3_open('users.db', &db)
// C.sqlite3_open(db_path.str, &db)
// you can also use `.str byteptr` field to convert a V string to a C char pointer
query := 'select count(*) from users'
stmt := &C.sqlite3_stmt(0)
C.sqlite3_prepare_v2(db, query.str, - 1, &stmt, 0)
C.sqlite3_step(stmt)
nr_users := C.sqlite3_column_int(stmt, 0)
C.sqlite3_finalize(stmt)
println('There are $nr_users users in the database.')
//
error_msg := charptr(0)
query_all_users := 'select * from users'
rc := C.sqlite3_exec(db, query_all_users.str, my_callback, 7, &error_msg)
if rc != C.SQLITE_OK {
eprintln( cstring_to_vstring(error_msg) )
C.sqlite3_free(error_msg)
}
C.sqlite3_close(db)
}
#flag
Add #flag
directives to the top of your V files to provide C compilation flags like:
-I
for adding C include files search paths-l
for adding C library names that you want to get linked-L
for adding C library files search paths-D
for setting compile time variables
You can use different flags for different targets.
Currently the linux
, darwin
, freebsd
, and windows
flags are supported.
NB: Each flag must go on its own line (for now)
#flag linux -lsdl2
#flag linux -Ivig
#flag linux -DCIMGUI_DEFINE_ENUMS_AND_STRUCTS=1
#flag linux -DIMGUI_DISABLE_OBSOLETE_FUNCTIONS=1
#flag linux -DIMGUI_IMPL_API=
#pkgconfig
Add #pkgconfig
directive is used to tell the compiler which modules should be used for compiling
and linking using the pkg-config files provided by the respective dependencies.
As long as backticks can't be used in #flag
and spawning processes is not desirable for security
and portability reasons, V uses its own pkgconfig library that is compatible with the standard
freedesktop one.
If no flags are passed it will add --cflags
and --libs
, both lines below do the same:
#pkgconfig r_core
#pkgconfig --cflags --libs r_core
The .pc
files are looked up into a hardcoded list of default pkg-config paths, the user can add
extra paths by using the PKG_CONFIG_PATH
environment variable. Multiple modules can be passed.
Including C code
You can also include C code directly in your V module. For example, let's say that your C code is located in a folder named 'c' inside your module folder. Then:
- Put a v.mod file inside the toplevel folder of your module (if you
created your module with
v new
you already have v.mod file). For example:
Module {
name: 'mymodule',
description: 'My nice module wraps a simple C library.',
version: '0.0.1'
dependencies: []
}
- Add these lines to the top of your module:
#flag -I @VROOT/c
#flag @VROOT/c/implementation.o
#include "header.h"
NB: @VROOT will be replaced by V with the nearest parent folder, where there is a v.mod file.
Any .v file beside or below the folder where the v.mod file is,
can use #flag @VROOT/abc
to refer to this folder.
The @VROOT folder is also prepended to the module lookup path,
so you can import other modules under your @VROOT, by just naming them.
The instructions above will make V look for an compiled .o file in
your module folder/c/implementation.o
.
If V finds it, the .o file will get linked to the main executable, that used the module.
If it does not find it, V assumes that there is a @VROOT/c/implementation.c
file,
and tries to compile it to a .o file, then will use that.
This allows you to have C code, that is contained in a V module, so that its distribution is easier. You can see a complete minimal example for using C code in a V wrapper module here: project_with_c_code. Another example, demonstrating passing structs from C to V and back again: interoperate between C to V to C.
You can use -cflags
to pass custom flags to the backend C compiler.
You can also use -cc
to change the default C backend compiler.
For example: -cc gcc-9 -cflags -fsanitize=thread
.
C types
Ordinary zero terminated C strings can be converted to V strings with string(cstring)
or string(cstring, len)
.
NB: Each string(...)
function does NOT create a copy of the cstring
,
so you should NOT free it after calling string()
.
If you need to make a copy of the C string (some libc APIs like getenv
pretty much require that,
since they return pointers to internal libc memory), you can use cstring_to_vstring(cstring)
.
On Windows, C APIs often return so called wide
strings (utf16 encoding).
These can be converted to V strings with string_from_wide(&u16(cwidestring))
.
V has these types for easier interoperability with C:
voidptr
for C'svoid*
,byteptr
for C'sbyte*
andcharptr
for C'schar*
.&charptr
for C'schar**
To cast a voidptr
to a V reference, use user := &User(user_void_ptr)
.
voidptr
can also be dereferenced into a V struct through casting: user := User(user_void_ptr)
.
socket.v has an example which calls C code from V .
Debugging generated C code
To debug issues in the generated C code, you can pass these flags:
-cg
- produces a less optimized executable with more debug information in it.-showcc
- prints the C command that is used to build the program.
For the best debugging experience, you can pass all of them at the same time:
v -cg -showcc yourprogram.v
,
then just run your debugger (gdb/lldb) or IDE on the produced executable yourprogram
.
If you just want to inspect the generated C code,
without further compilation, you can also use the -o
flag (e.g. -o file.c
).
This will make V produce the file.c
then stop.
If you want to see the generated C source code for just a single C function,
for example main
, you can use: -printfn main -o file.c
.
To see a detailed list of all flags that V supports,
use v help
, v help build
and v help build-c
.
Conditional compilation
// 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 -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
.
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 , aarch64 |
debug , test , js |
mac , darwin , ios , |
clang , mingw |
x64 , x32 |
glibc , prealloc |
android ,mach , dragonfly |
msvc |
little_endian |
no_bounds_checking |
gnu , hpux , haiku , qnx |
cplusplus |
big_endian |
|
solaris , linux_or_macos |
Compile time pseudo variables
V also gives your code access to a set of pseudo string variables, that are substituted at compile time:
@FN
=> replaced with the name of the current V function@MOD
=> replaced with the name of the current V module@STRUCT
=> replaced with the name of the current V struct@FILE
=> replaced with the path of the V source file@LINE
=> replaced with the V line number where it appears (as a string).@COLUMN
=> replaced with the column where it appears (as a string).@VEXE
=> replaced with the path to the V compiler@VHASH
=> replaced with the shortened commit hash of the V compiler (as a string).@VMOD_FILE
=> replaced with the contents of the nearest v.mod file (as a string).
That allows you to do the following example, useful while debugging/logging/tracing your code:
eprintln( 'file: ' + @FILE + ' | line: ' + @LINE + ' | fn: ' + @MOD + '.' + @FN)
Another example, is if you want to embed the version/name from v.mod inside your executable:
import v.vmod
vm := vmod.decode( @VMOD_FILE ) or { panic(err) }
eprintln('$vm.name $vm.version\n $vm.description')
Performance tuning
The generated C code is usually fast enough, when you compile your code
with -prod
. There are some situations though, where you may want to give
additional hints to the compiler, so that it can further optimize some
blocks of code.
NB: These are rarely needed, and should not be used, unless you profile your code, and then see that there are significant benefits for them. To cite gcc's documentation: "programmers are notoriously bad at predicting how their programs actually perform".
[inline]
- you can tag functions with [inline]
, so the C compiler will
try to inline them, which in some cases, may be beneficial for performance,
but may impact the size of your executable.
[direct_array_access]
- in functions tagged with [direct_array_access]
the compiler will translate array operations directly into C array operations -
omiting bounds checking. This may save a lot of time in a function that iterates
over an array but at the cost of making the function unsafe - unless
the boundries will be checked by the user.
if _likely_(bool expression) {
this hints the C compiler, that the passed
boolean expression is very likely to be true, so it can generate assembly
code, with less chance of branch misprediction. In the JS backend,
that does nothing.
if _unlikely_(bool expression) {
similar to _likely_(x)
, but it hints that
the boolean expression is highly improbable. In the JS backend, that does nothing.
Compile-time reflection
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:
// TODO: not fully implemented
struct User {
name string
age int
}
// Note: T should be passed a struct name only
fn decode<T>(data string) T {
mut result := T{}
// compile-time `for` loop
// T.fields gives an array of a field metadata type
$for field in T.fields {
$if field.typ is string {
// $(string_expr) produces an identifier
result.$(field.name) = get_string(data, field.name)
} $else $if field.typ is int {
result.$(field.name) = get_int(data, field.name)
}
}
return result
}
// `decode<User>` generates:
fn decode_User(data string) User {
mut result := User{}
result.name = get_string(data, 'name')
result.age = get_int(data, 'age')
return result
}
Limited operator overloading
struct Vec {
x int
y int
}
fn (a Vec) str() string {
return '{$a.x, $a.y}'
}
fn (a Vec) + (b Vec) Vec {
return Vec {
a.x + b.x,
a.y + b.y
}
}
fn (a Vec) - (b Vec) Vec {
return Vec {
a.x - b.x,
a.y - b.y
}
}
fn main() {
a := Vec{2, 3}
b := Vec{4, 5}
println(a + b) // "{6, 8}"
println(a - b) // "{-2, -2}"
}
Operator overloading goes against V's philosophy of simplicity and predictability. But since scientific and graphical applications are among V's domains, operator overloading is an important feature to have in order to improve readability:
a.add(b).add(c.mul(d))
is a lot less readable than a + b + c * d
.
To improve safety and maintainability, operator overloading is limited:
- It's only possible to overload
+, -, *, /, %
operators. - Calling other functions inside operator functions is not allowed.
- Operator functions can't modify their arguments.
- Both arguments must have the same type (just like with all operators in V).
Inline assembly
TODO: not implemented yet
fn main() {
a := 10
asm x64 {
mov eax, [a]
add eax, 10
mov [a], eax
}
}
Translating C/C++ to V
TODO: translating C to V will be available in V 0.3. C++ to V will be available later this year.
V can translate your C/C++ code to human readable V code.
Let's create a simple program test.cpp
first:
#include <vector>
#include <string>
#include <iostream>
int main() {
std::vector<std::string> s;
s.push_back("V is ");
s.push_back("awesome");
std::cout << s.size() << std::endl;
return 0;
}
Run v translate test.cpp
and V will generate test.v
:
fn main() {
mut s := []string{}
s << 'V is '
s << 'awesome'
println(s.len)
}
An online C/C++ to V translator is coming soon.
When should you translate C code and when should you simply call C code from V?
If you have well-written, well-tested C code, then of course you can always simply call this C code from V.
Translating it to V gives you several advantages:
- If you plan to develop that code base, you now have everything in one language, which is much safer and easier to develop in than C.
- Cross-compilation becomes a lot easier. You don't have to worry about it at all.
- No more build flags and include files either.
Hot code reloading
module main
import time
import os
[live]
fn print_message() {
println('Hello! Modify this message while the program is running.')
}
fn main() {
for {
print_message()
time.sleep_ms(500)
}
}
Build this example with v -live message.v
.
Functions that you want to be reloaded must have [live]
attribute
before their definition.
Right now it's not possible to modify types while the program is running.
More examples, including a graphical application: github.com/vlang/v/tree/master/examples/hot_code_reload.
Cross compilation
To cross compile your project simply run
v -os windows .
or
v -os linux .
(Cross compiling for macOS is temporarily not possible.)
If you don't have any C dependencies, that's all you need to do. This works even
when compiling GUI apps using the ui
module or graphical apps using gg
.
You will need to install Clang, LLD linker, and download a zip file with libraries and include files for Windows and Linux. V will provide you with a link.
Cross-platform shell scripts in V
V can be used as an alternative to Bash to write deployment scripts, build scripts, etc.
The advantage of using V for this is the simplicity and predictability of the language, and cross-platform support. "V scripts" run on Unix-like systems as well as on Windows.
Use the .vsh
file extension. It will make all functions in the os
module global (so that you can use ls()
instead of os.ls()
, for example).
#!/usr/local/bin/v run
// The shebang above associates the file to V on Unix-like systems,
// so it can be run just by specifying the path to the file
// once it's made executable using `chmod +x`.
rm('build/*')
// Same as:
for file in ls('build/') {
rm(file)
}
mv('*.v', 'build/')
// Same as:
for file in ls('.') {
if file.ends_with('.v') {
mv(file, 'build/')
}
}
Now you can either compile this like a normal V program and get an executable you can deploy and run
anywhere:
v deploy.vsh && ./deploy
Or just run it more like a traditional Bash script:
v run deploy.vsh
On Unix-like platforms, the file can be run directly after making it executable using chmod +x
:
./deploy.vsh
Attributes
V has several attributes that modify the behavior of functions and structs.
An attribute is specified inside []
right before a function/struct declaration
and applies only to the following declaration.
// Calling this function will result in a deprecation warning
[deprecated]
fn old_function() {}
// This function's calls will be inlined.
[inline]
fn inlined_function() {}
// The following struct can only be used as a reference (`&Window`) and allocated on the heap.
[ref_only]
struct Window {
}
// V will not generate this function and all its calls if the provided flag is false.
// To use a flag, use `v -d flag`
[if debug]
fn foo() { }
fn bar() {
foo() // will not be called if `-d debug` is not passed
}
// For C interop only, tells V that the following struct is defined with `typedef struct` in C
[typedef]
struct C.Foo { }
// Used in Win32 API code when you need to pass callback function
[windows_stdcall]
fn C.DefWindowProc(hwnd int, msg int, lparam int, wparam int)
Appendices
Appendix I: Keywords
V has 41 reserved keywords (3 are literals):
as
asm
assert
atomic
break
const
continue
defer
else
embed
enum
false
fn
for
go
goto
if
import
in
interface
is
lock
match
module
mut
none
or
pub
return
rlock
select
shared
sizeof
static
struct
true
type
typeof
union
unsafe
See also Types.
Appendix II: Operators
This lists operators for primitive types only.
+ sum integers, floats, strings
- difference integers, floats
* product integers, floats
/ quotient integers, floats
% remainder integers
~ bitwise NOT integers
& bitwise AND integers
| bitwise OR integers
^ bitwise XOR integers
! logical NOT bools
&& logical AND bools
|| logical OR bools
!= logical XOR bools
<< left shift integer << unsigned integer
>> right shift integer >> unsigned integer
Precedence Operator
5 * / % << >> &
4 + - | ^
3 == != < <= > >=
2 &&
1 ||
Assignment Operators
+= -= *= /= %=
&= |= ^=
>>= <<=