V Types

Primitive types #

[!NOTE] int is a platform-width signed integer: 64 bits on 64-bit targets and 32 bits on 32-bit targets. Use i32 or i64 when you need a fixed width. Integer literal casts to int are checked against the target platform's width.

128-bit integers #

i128 and u128 hold 128 bits. The usual operators work on them: arithmetic, bitwise, shifts, comparisons, and casts to and from the other numeric types.

A shift by 128 or more gives 0. The count is read at its own width, so a count that does not fit in 64 bits shifts everything out rather than being taken for a small one. >> on a negative signed value is an arithmetic shift, so it gives -1 once the value is all ones, while >>> reads the same bits as unsigned and its result is a u128, whatever the sign of the operand. Division or modulo by zero panics, as it does for the other integer types, and overflow wraps.

The compiler does not require a 128-bit C type. Every operation becomes a call to a small helper, and the helper has two implementations: the C compiler's own __int128 where it exists (gcc, clang), and one built from 64-bit limbs everywhere else (tcc, MSVC, every 32-bit target), where a 128-bit value is a struct. Both answer identically, down to the rounding of a cast to f64: the whole 128-bit magnitude is rounded once, rather than each limb on its own. Pass -d v3_no_native_int128 to force the portable implementation on a compiler that has the native type.

Managed arrays of wide integers and structs containing them retain 16-byte element alignment on both 32-bit and 64-bit targets, including after growth or cloning.

Printing works through str(), so println and string interpolation show the decimal value, including the minimum i128 that has no positive counterpart.

A literal that needs more than 64 bits can be written directly and keeps its exact value:

The digits are split into two halves in the compiler, so the C compiler never sees a constant it would quietly cut down to its low 64 bits. A value outside the range of the target type is an error: u128(2^128) is rejected rather than wrapped, and i128(-2^127) is allowed because that is the minimum. Negative literals keep their full magnitude before negation, including values below the i64 minimum: i128(-9223372036854775809) is exactly -9223372036854775809.

A bare literal still follows the rule that applies to every other integer in V, so it wants an explicit cast.

The promotion ladder has a row for both new types, so wide + u64(1) is a u128 and keeps all 128 bits, and asking the expression for its own type answers u128 too. A narrower operand widens by its own sign, so i128(0) + u64(0xffffffffffffffff) is 2^64 - 1 rather than -1.

The usual conversions are there, so text, hex and binary work on a 128-bit value:

Format specifiers work on a 128-bit value, and a map of them prints its values:

str_base covers the bases a specifier cannot spell out: wide.str_base(2) writes the value in binary, and char_str writes the code point in the low bits.

typeof and a method called on a mixed-width expression name the wider operand: typeof(x + u64(1)) is u128, and (x + u64(1)).str() keeps all of its digits. Only json and json2 still have no encoder for either type.

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:

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

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

Strings #

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

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

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

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

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

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

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

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

Strings can be easily converted to integers:

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

String interpolation #

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

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

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

To use a format specifier, follow this pattern:

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

• flags: may be zero or more of the following: - to left-align output within the field, 0 to use 0 as the padding character instead of the default space character, and + to show the sign of decimal integers and floats with a width or precision. The + flag may be combined with - and 0 in any order; left alignment uses trailing spaces even when 0 is also present.

  Note

  V does not currently support the use of ' or # as format flags.

• width: may be an integer value describing the minimum width of total field to output. For runtime widths, wrap an int expression in parentheses, for example ${name:(width)}.

• precision: an integer value preceded by a . will guarantee that many digits after the decimal point without any insignificant trailing zeros. If displaying insignificant zero's is desired, append a f specifier to the precision value (see examples below). Applies only to float variables and is ignored for integer variables. Runtime precisions use the same parenthesized form, for example ${value:(width).(precision)f}. Negative zero keeps its sign when formatted, including when trailing zeros are omitted.

• type: f and F specify the input is a float and should be rendered as such, e and E specify the input is a float and should be rendered as an exponent (partially broken), g and G specify the input is a float--the renderer will use floating point notation for small values and exponent notation for large values, d specifies the input is an integer and should be rendered in base-10 digits, x and X require an integer and will render it as hexadecimal digits, o requires an integer and will render it as octal digits, b requires an integer and will render it as binary digits, s requires a string (almost never used).

  Note

  When a numeric type can render alphabetic characters, such as hex strings or special values like infinity, the lowercase version of the type forces lowercase alphabetics and the uppercase version forces uppercase alphabetics.

  Note

  In most cases, it's best to leave the format type empty. Floats will be rendered by default as g, integers will be rendered by default as d, and s is almost always redundant. There are only three cases where specifying a type is recommended:

• format strings are parsed at compile time, so specifying a type can help detect errors then

• format strings default to using lowercase letters for hex digits and the e in exponents. Use a uppercase type to force the use of uppercase hex digits and an uppercase E in exponents.

• format strings are the most convenient way to get hex, binary or octal strings from an integer.

See Format Placeholder Specification for more information.

Scientific float interpolation (e, E, g, or G) uses at least two exponent digits, without additional leading zeroes, including when a precision is specified.

V also has r and R switches, which will repeat the string the specified amount of times.

String operators #

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

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

We have to either convert age to a string:

or use string interpolation (preferred):

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

Runes #

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

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

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

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

Note that rune literals use the same escape syntax as strings, but they can only hold one unicode character. Therefore, if your code does not specify a single Unicode character, you will receive an error at compile time.

Also remember that strings are indexed as bytes, not runes, so beware:

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

Numbers #

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:

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:

If you want a different type of integer, you can use casting:

Assigning floating point numbers works the same way:

If you do not specify the type explicitly, by default float literals will have the type of f64.

Integer literals can be assigned to f32 and f64 variables without a cast. Unary +, unary -, parentheses, and arithmetic on integer literals and on the constants declared with them preserve this behavior:

This does not make typed integer variables implicitly assignable to f32; use an explicit conversion such as a = f32(value) for those variables.

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

Checked integer arithmetic #

Integer arithmetic wraps on overflow, a shift by the bit width or more gives 0, and a cast to a smaller integer type keeps the low bits. Two opt-in flags turn these into runtime panics:

• v -check-overflow checks +, -, *, ++, --, and min / -1 and min % -1 (with their compound forms like -=, /=). In code outside the standard library, it also checks the negation of the minimum value (-x for x == min_i64), and shifts whose count is negative or not less than the bit width of the left operand.
• v -check-casts checks integer casts that lose information, like i8(i64(300)), u8(-1) or u64(i64(-5)). Casts from floats, or to char and enums, are not checked. Only code outside the standard library is checked, since vlib uses truncating casts on purpose (hashes, byte extraction).

A function tagged with @[ignore_overflow] is not checked by either flag:

Arrays #

Returning a new array through helper calls preserves each helper's parameter scope.

An array is a collection of data elements of the same type. An array literal is a list of expressions surrounded by square brackets. An individual element can be accessed using an index expression. Indexing starts from 0.

A string literal keeps its string type even when its text names a type alias. For example, ['Speed'] contains strings, while [Speed(7)] contains Speed values.

After an array literal, separate && from either adjacent token with whitespace or a comment to use logical AND, as in a == [] && flag. An attached []&&Type{} declares an array of references to references. Separate & on both sides to use the binary AND operator; []&Type{} and [] &Type{} remain array initializers with reference elements.

An element can be appended to the end of an array using the push operator <<. It can also append an entire array.

The C backend uses typed stores for scalar element assignments and single-element appends. Assignments retain bounds checking. Appends retain capacity checks and detach slice storage when needed. The right-hand side can grow the array before the final element address is resolved.

Use << ...array to explicitly append the array's elements. When appending an array of concrete values to an empty interface array, << array appends the whole array as one interface value, while << ...array converts and appends each element separately. For example, with interface Value {}, appending ['IT'] to []Value{} produces [Value(['IT'])] with << and [Value('IT')] with << .... insert(index, ...array) and prepend(...array) also convert each source element to the destination element type before inserting it.

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

Use << ...array to explicitly append the array's elements. For an interface array, << array can append the whole array as one interface value, while << ...array converts each element separately. array.insert(index, ...values) and array.prepend(...values) also convert each source element to the destination element type.

Array Fields #

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

• len: length - the number of pre-allocated and initialized elements in the array
• cap: capacity - the amount of memory space which has been reserved for elements, but not initialized or counted as elements. The array can grow up to this size without being reallocated. Usually, V takes care of this field automatically but there are cases where the user may want to do manual optimizations (see below).

data is a field (of type voidptr) with the address of the first element. This is for low-level unsafe code.

[!NOTE] Fields are read-only and can't be modified by the user.

Array Initialization #

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

• [1, 2, 3] is an array of ints ([]int).
• ['a', 'b'] is an array of strings ([]string).

The user can explicitly specify the type for the first element: [u8(16), 32, 64, 128]. V arrays are homogeneous (all elements must have the same type). This means that code like [1, 'a'] will not compile.

Array elements must be written inside square brackets. Braces accept named initializer parameters only; []int{1, 2, 3} and [3]int{1, 2, 3} are syntax errors. Use [1, 2, 3] for a dynamic array or [1, 2, 3]! for a fixed array instead.

The above syntax is fine for a small number of known elements but for very large or empty arrays there is a second initialization syntax:

This creates an array of 10000 int elements that are all initialized with 3. Memory space is reserved for 30000 elements. The parameters len, cap and init are optional; len defaults to 0 and init to the default initialization of the element type (0 for numerical type, '' for string, etc). The run time system makes sure that the capacity is not smaller than len (even if a smaller value is specified explicitly):

Setting the capacity improves performance of pushing elements to the array as reallocations can be avoided:

[!NOTE] The above code uses a range for statement.

You can initialize the array by accessing the index variable which gives the index as shown here:

Array update syntax #

V lets you initialise an array by spreading an existing array, optionally followed by additional elements:

This is functionally equivalent to cloning the array and appending to it, except that you don't have to declare a mutable variable for the intermediate value, and the additional elements may be inlined at the call site.

Array Types #

An array can be of these types:

Example Code:

This example uses Structs and Sum Types to create an array which can handle different types (e.g. Points, Lines) of data elements.

Multidimensional Arrays #

Arrays can have more than one dimension.

2d array example:

3d array example:

Array methods #

A function literal passed to map uses its return type for the output elements. Its parameters and nested array expressions have their own scope, including parameters named it.

All arrays can be easily printed with println(arr) and converted to a string with s := arr.str().

Copying the data from the array is done with .clone():

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

it is a builtin variable which refers to the element currently being processed in filter/map methods.

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

There are further built-in methods for arrays:

• a.repeat(n) concatenates the array elements n times
• a.insert(i, val) inserts a new element val at index i and shifts all following elements to the right
• a.insert(i, [3, 4, 5]) inserts several elements
• a.prepend(val) inserts a value at the beginning, equivalent to a.insert(0, val)
• a.prepend(arr) inserts elements of array arr at the beginning
• a.trim(new_len) truncates the length (if new_length < a.len, otherwise does nothing)
• a.clear() empties the array without changing cap (equivalent to a.trim(0))
• a.delete_many(start, size) removes size consecutive elements from index start, preserving order. On the C backend, it reuses the backing buffer and keeps capacity when no slices share it
• a.delete(index) equivalent to a.delete_many(index, 1)
• a.delete_last() removes the last element; on the C backend it does not change cap
• a.first() equivalent to a[0]
• a.last() equivalent to a[a.len - 1]
• a.pop() removes the last element and returns it
• a.reverse() makes a new array with the elements of a in reverse order
• a.reverse_in_place() reverses the order of elements in a
• a.join(joiner) concatenates an array of strings into one string using joiner string as a separator

See all methods of array

See also vlib/arrays.

Sorting Arrays #

Sorting arrays of all kinds is very simple and intuitive. Special variables a and b are used when providing a custom sorting condition.

sorted() returns a sorted copy. Alias element types keep their overloaded < operator, including when the receiver is an array literal or a parenthesized array literal.

V also supports custom sorting, through the sort_with_compare array method. Which expects a comparing function which will define the sort order. Useful for sorting on multiple fields at the same time by custom sorting rules. The code below sorts the array ascending on name and descending age.

Array Slices #

Iteration over an array slice keeps the array's element type: iterating []string yields strings, including when the containing function is reached through generic calls.

A slice is a part of a parent array. Initially it refers to the elements between two indices separated by a .. operator. The right-side index must be greater than or equal to the left side index.

If a right-side index is absent, it is assumed to be the array length. If a left-side index is absent, it is assumed to be 0.

In V slices are arrays themselves (they are not distinct types). As a result all array operations may be performed on them. E.g. they can be pushed onto an array of the same type:

A slice is always created with the smallest possible capacity cap == len (see cap above) no matter what the capacity or length of the parent array is. As a result it is immediately reallocated and copied to another memory location when the size increases thus becoming independent from the parent array (copy on grow). In particular pushing elements to a slice does not alter the parent:

When a slice expression like a[2..4] is assigned outside unsafe and either the parent array or the resulting slice is mutable, V inserts an implicit .clone() and shows a notice. This prevents changes through one array from affecting the other. If both arrays are immutable, the slice safely reuses the parent array's memory without cloning. The shared-memory examples below therefore use unsafe {} intentionally.

Appending to the parent array, may or may not make it independent from its child slices. The behaviour depends on the parent's capacity and is predictable:

You can call .clone() on the slice, if you do want to have an independent copy right away:

If either the parent array or the slice is mutable, V makes an implicit clone of the slice and displays a notice. Therefore, without the .clone() call, the result of the code above will be the same. When both arrays are immutable, the slice reuses the parent array's memory because neither array can be changed. Make the slice in an unsafe {} block if you want to share mutable memory; otherwise use explicit cloning.

Slices with negative indexes #

V supports array and string slices with negative indexes. Negative indexing starts from the end of the array towards the start, for example -3 is equal to array.len - 3. Negative slices have a different syntax from normal slices, i.e. you need to add a gate between the array name and the square bracket: a#[..-3]. The gate specifies that this is a different type of slice and remember that the result is "locked" inside the array. The returned slice is always a valid array, though it may be empty:

Array method chaining #

You can chain the calls of array methods like .filter() and .map() and use the it built-in variable to achieve a classic map/filter functional paradigm:

Fixed size arrays #

Mapping a fixed size array preserves its length and uses the mapping expression or function return type as its element type. Filtering still produces a dynamic array.

V also supports arrays with fixed size. Unlike ordinary arrays, their length is constant. You cannot append elements to them, nor shrink them. You can only modify their elements in place.

However, access to the elements of fixed size arrays is more efficient, they need less memory than ordinary arrays, and unlike ordinary arrays, their data is on the stack, so you may want to use them as buffers if you do not want additional heap allocations.

Most methods are defined to work on ordinary arrays, not on fixed size arrays. You can convert a fixed size array to an ordinary array with slicing:

Whole fixed size arrays and their ranges can be passed to mutable array parameters. These arguments borrow the original elements, so writes through either the array parameter or another alias are immediately visible through both. Returned or stored views keep sharing those elements. Local storage is moved to the heap before references to it are formed, so retained views remain valid after the local goes out of scope. A callee can also retain a reference to the separately allocated array header. Growing or reassigning that header follows the usual array slice rules and leaves the original fixed array's size unchanged. Immutable array-reference parameters, including each variadic argument, also borrow the original elements. These rules also apply to array-reference parameters declared through aliases. Fixed array values introduced by guards, multi-declarations, loop bindings, or select receives also receive durable storage when passed to a retaining array-reference parameter. Indexed fixed elements of dynamic arrays retain their original backing buffer, including through managed slice aliases, so retained headers preserve writes and remain valid after owner cleanup. The same rule applies to fixed elements obtained through first() or last(). Fixed values read from maps, including inline fields, are copied into independent durable storage. Mutable iteration over those fixed elements preserves the same backing lifetime. Pointer fields and indexed pointers retain the original fixed-array roots recorded by their owners. Borrowing does not clone elements or require a clone() method.

Passing a local struct's fixed-array storage by reference keeps the local on the stack when the called function only reads or writes scalar fields and array elements, or passes the reference, or the address of an element (&buf[i]), straight on to a function that does the same. Calls that may retain the storage still move it to the heap; -warn-about-allocs reports these moves. Calls through local function values remain conservative, including values that shadow function names. Explicitly destroying owned source elements invalidates views of those elements, as with other borrowed slices. With ownership checking enabled, returning or storing a view copies its buffer to independent storage. Owned elements are cloned so the retained value has independent owners. Retained array references, including those stored inside options, receive a separate header, so other aliases in the callee still share the original elements. An operation that detaches a borrowed buffer also clones its owned elements. Such elements need a compatible clone() method or IClone support. Retaining or detaching a nonempty uncloneable borrowed buffer panics; borrowing it or changing its elements in place is allowed. An empty view can grow without cloning any source elements.

Note that slicing will cause the data of the fixed size array to be copied to the newly created ordinary array. The exception is a slice that is written to: passing it as a mut argument, changing its elements, iterating over it with for mut, or calling sort(), sort_with_compare() or reverse_in_place() on it, updates the fixed size array itself:

To copy elements into an existing array instead, use the builtin copy function. Like Go's copy, it copies as many elements as both arguments have, returns that number, and handles overlapping arguments. The destination can be an ordinary array, a fixed size array, or a slice of either, and is updated in place. The source can also be a string, when the destination holds bytes:

Maps #

Methods and references on map iteration values address the stored element, including nested maps. Postfix updates to a mutable map value field, such as m[key].level++, update the stored entry and insert a zero value first when the key is absent. The key is evaluated once.

Maps can have keys of type string, rune, integer, float, voidptr, enum, or fixed arrays of those supported key types. Struct keys are rejected, including when a generic key parameter is instantiated with a struct.

The whole map can be initialized using this short syntax:

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

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

Modules can opt into stricter map indexing:

You can also check, if a key is present, and get its value, if it was present, in one go:

Note: map indexing returns a copy of the stored value, including with or {} and if v := m[key] {}. Mutating that local value does not update the value stored in the map.

To update a stored value, mutate m[key] directly or assign the modified value back to the map:

The same option check applies to arrays:

V also supports nested maps:

Maps are ordered by insertion, like dictionaries in Python. The order is a guaranteed language feature. This may change in the future.

See all methods of map and maps.

Map update syntax #

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

This is functionally equivalent to cloning the map and updating it, except that you don't have to declare a mutable variable: