v Documentation

Technical Documentation: vlang/v

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

Key Features of V Copy Chapter

• Simplicity: the language can be learned over the course of a weekend
• Fast compilation: ≈110k loc/s with a Clang backend,
  ≈500k loc/s with native and tcc backends (Intel i5-7500, SSD, no
  optimization) (demo video)
• Easy to develop: V compiles itself in less than a second
• Performance: as fast as C (V's main backend compiles to human-readable C)
• Safety: no null, no globals, no undefined behavior (wip), immutability by default
• C to V translation (Translating DOOM demo video)
• Hot code reloading
• Flexible memory management. GC by default, manual via v -gc none,
  arena allocation via v -prealloc, autofree via v -autofree
  (autofree demo video).
• Cross-platform UI library
• Built-in graphics library
• Easy cross-compilation
• REPL
• Built-in ORM
• Built-in web framework
• C and JavaScript backends
• Great for writing low-level software (Vinix OS)

Stability, future changes, post 1.0 freeze Copy Chapter

Despite being at an early development stage, the V language is relatively stable, and doesn't
change often. But there will be changes before 1.0.
Most changes in the syntax are handled via vfmt automatically.

The V core APIs (primarily the os module) will also have minor changes until
they are stabilized in V 1.0. Of course, the APIs will grow after that, but without breaking
existing code.

After the 1.0 release V is going to be in the "feature freeze" mode. That means no breaking changes
in the language, only bug fixes and performance improvements. Similar to Go.

Will there be V 2.0? Not within a decade after 1.0, perhaps not ever.

To sum it up, unlike many other languages, V is not going to be always changing, with new features
introduced and old features modified. It is always going to be a small and simple
language, very similar to the way it is right now.

Installing V from source Copy Chapter

This is the preferred method.

Linux, macOS, Windows, \*BSD, Solaris, WSL, etc. Copy Section

Usually, installing V is quite simple if you have an environment that already has a
functional git installation.

Note: On Windows, run makev.bat instead of make in CMD, or ./makev.bat in
PowerShell.
To build with Visual Studio, run makev.bat -msvc. If the bundled TCC bootstrap cannot be
compiled or fails while building the next compiler stage, the script retries with MSVC,
then Clang and GCC.
Note: On FreeBSD, OpenBSD, NetBSD, DragonFly, and Solaris, install GNU make and run it as
gmake.
Note: On Ubuntu/Debian, you may need to run sudo apt install git build-essential make first.

To get started, execute the following in your terminal/shell:

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

That should be it, and you should find your V executable at [path to V repo]/v.
[path to V repo] can be anywhere.

On Unix-like systems, make and the v self bootstrap fallback stream compatibility fixes
for older vc/v.c snapshots to the C compiler. These match the peak RSS helper's return type
to i64 and guard Linux-only prctl code. The snapshot stays unchanged on disk.
The compatibility filter uses the system sh; Bash is not required.

On Windows, makev.bat generates the first compiler stage as C and links it directly.
This also works with older bootstrap snapshots whose process-spawn code is broken.
Direct TCC links add the installed bundle's thirdparty\tcc\lib\openlibm.o, when present,
for C99 math functions such as remainder. Each bundle ships this object for its own compiler,
so an existing amd64 or i386 checkout links a matching object even when it differs from the
branch selected by the host, -tcc32, or TCC_BRANCH.
For paths longer than 260 characters, see Long paths on Windows.

(Like the note above says, on Windows, use makev.bat, instead of make.)

Now try running ./v run examples/hello_world.v (or v run examples/hello_world.v in cmd shell).

• Trouble? Please see the notes above, and link to
  Installation Issues
  for help.

Note: V is being constantly updated. To update V to its latest version, simply run:

v up

This also refreshes the bundled TCC binaries used for fast C compilation.
Previously cached modules are validated with the updated compiler. Successful checks that
produce no output remain quiet; Caching module <name>... reports actual C compilation.
Different build configurations can compile the same module separately.
Use v up -v to show progress for every checked cache configuration, including reused objects.

[!NOTE]
If you run into any trouble, or you have a different operating
system or Linux distribution that doesn't install or work immediately, please see
Installation Issues
and search for your OS and problem.

If you can't find your problem, please add it to an existing discussion if one exists for
your OS, or create a new one if a main discussion doesn't yet exist for your OS.

Void Linux Copy Section

# xbps-install -Su base-devel
# xbps-install libatomic-devel
$ git clone --depth=1 https://github.com/vlang/v
$ cd v
$ make

Docker Copy Section

git clone --depth=1 https://github.com/vlang/v
cd v
docker build -t vlang .
docker run --rm -it vlang:latest

Docker with Alpine/musl Copy Section

git clone --depth=1 https://github.com/vlang/v
cd v
docker build -t vlang_alpine - < Dockerfile.alpine
alias with_alpine='docker run -u 1000:1000 --rm -it -v .:/src -w /src vlang_alpine:latest'

Compiling static executables, ready to be copied to a server, that is running
another linux distro, without dependencies:

with_alpine v -prod -cc gcc -cflags -static -compress examples/http_server.v
with_alpine v -prod -cc gcc -cflags -static -compress -gc none examples/hello_world.v
ls -la examples/http_server examples/hello_world
file   examples/http_server examples/hello_world
examples/http_server: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, no section header
examples/hello_world: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, no section header

You should see something like this:

-rwxr-xr-x 1 root root  16612 May 27 17:07 examples/hello_world
-rwxr-xr-x 1 root root 335308 May 27 17:07 examples/http_server

FreeBSD Copy Section

On FreeBSD, V needs boehm-gc-threaded and GNU make packages preinstalled. After installing
them, use gmake to build V:

pkg install boehm-gc-threaded gmake
git clone --depth=1 https://github.com/vlang/v
cd v
gmake

OpenBSD Copy Section

On OpenBSD (release 7.8), V needs boehm-gc and openssl-3.5 packages preinstalled. After
installing them, use GNU make (installed with gmake package), to build V.

pkg_add boehm-gc openssl%3.5 gmake
git clone --depth=1 https://github.com/vlang/v
cd v
gmake

Termux/Android Copy Section

On Termux, V needs some packages preinstalled - a working C compiler, also libexecinfo,
libgc and libgc-static. After installing them, you can use the same script, like on
Linux/macos:

pkg install clang libexecinfo libgc libgc-static tcc make git
pkg update
git clone --depth=1 https://github.com/vlang/v
cd v
make
./v symlink

Note: there is no need for sudo ./v symlink on Termux (and sudo is not installed by default).
For faster development builds, keep the Termux tcc package installed; V will use it by default
when no compatible bundled thirdparty/tcc binary is available on the host.

C compiler Copy Section

The Tiny C Compiler (tcc) is downloaded for you by make if
there is a compatible version for your system, and installed under the V thirdparty directory.

For regular non-production builds on supported hosts, V prefers a working bundled TCC, then a
working tcc from PATH, before using the platform compiler. The system fallback is selected only
when required V runtime artifacts are available, including the bundled libgc.a used by default
glibc and Windows Boehm builds.

On macOS 27 (Darwin 27) and later, V never selects TCC by itself, and make and v self build
V with the system compiler: depending on their layout, TCC-linked executables can start there
with corrupted global variables (#29744). An explicit
-cc tcc is still honored.

-prod builds never default to TCC, which cannot do their optimizations. On x64 Windows,
without -cc, a -prod build uses MSVC when an x64 Visual Studio Developer environment is
active (cl on PATH, with INCLUDE and LIB set; not for -o file.o), otherwise a clang
that targets x86_64 MinGW, otherwise gcc. A native -prod build on another Windows
architecture uses gcc. An explicit -cc always wins.

An explicit -cc msvc on Windows does not need a Developer environment. When INCLUDE or LIB
is not set, V finds the Visual Studio C++ tools (the cl on PATH, VCToolsInstallDir, or the
newest installation vswhere reports) and the Windows SDK (WindowsSdkDir, the KitsRoot10
registry value, or Program Files (x86)\Windows Kits\10). Expandable registry values use the
current environment. V puts a cl for the architecture V
builds for on PATH when none is there, or when the one there is for another architecture (unless
-cc names it by its path), and sets the missing variables for the C compiler. Variables that are
already set, as in a Developer Command Prompt, are left as they are. The program that v run
starts gets the environment it was started with, not these changes. If V cannot find tools for
the requested architecture or a usable SDK, it reports what is missing before cl fails.

On macOS, -cc tcc -gc boehm uses a persistent bundled libgc.dylib store when the physical V
installation path contains a comma. The store is under $XDG_DATA_HOME/v-tcc-libgc-v1, or
$HOME/.local/share/v-tcc-libgc-v1 when the XDG variable is unset or empty. V creates the fallback
directories with private permissions. An explicit XDG_DATA_HOME must already be absolute,
user-owned, not group/world-writable, and have a safe, comma-free canonical path. Compiled binaries
can depend on this store at runtime, so do not delete it while they are in use.

This compiler is very fast, but does almost no optimizations. It is best for development builds.

For production builds (using the -prod option to V), it's recommended to use clang, gcc, or
Microsoft Visual C++. If you are doing development, you most likely already have one of those
installed.

Otherwise, follow these instructions:

• Installing a C compiler on Linux and macOS

• Installing a C compiler on Windows

Symlinking Copy Section

[!NOTE]
It is highly recommended, that you put V on your PATH. That saves
you the effort to type in the full path to your v executable every time.
V provides a convenience v symlink command to do that more easily.

On Unix systems, it creates a v symlink in /usr/local/bin by
default. To do that, run:

sudo ./v symlink

You can also pass a different directory, for example:

./v symlink ~/.local/bin

On Windows, start a new shell with administrative privileges, for example by pressing the
Windows Key, then type cmd.exe, right-click on its menu entry, and choose Run as administrator. In the new administrative shell, cd to the path where you have compiled V, then
type:

v symlink

(or .\v symlink in PowerShell)

You can pass a different directory there too, for example
v symlink C:\Users\you\bin.

That will make V available everywhere, by adding it to your PATH. Please restart your
shell/editor after that, so that it can pick up the new PATH variable.

[!NOTE]
There is no need to run v symlink more than once - v will still be available, even after
v up, restarts, and so on. You only need to run it again if you decide to move the V repo
folder somewhere else.

Editor/IDE Plugins Copy Chapter

• Atom
• CodeLite
• Emacs
• JetBrains
• Sublime Text 3
• Vim
• Vim/Neovim Runtime Files
• VS Code
• Zed

To bring IDE functions for the V programming languages to your editor, check out
v-analyzer. It provides language server capabilities.

v ls --check reports whether the VLS launcher has an installed, executable language server.
It exits successfully when none is installed. Use --path to check a specific executable.

Testing and running the examples Copy Chapter

Make sure V can compile itself:

$ v self
$ v
V 0.3.x
Use Ctrl-C or `exit` to exit

>>> println('hello world')
hello world
>>>

v self defaults to -gc none. Pass -gc <mode> if you need a different GC mode.
v -prod self uses a single production build of one C unit instead of the three-pass
PGO cycle. Use v -prod -parallel-cc self to compile the generated C units in parallel.

On macOS ARM64, first run v -compile-backend arm64 self to include the native backend in
the current compiler. Then use v -b arm64 self to rebuild the full compiler with the native
ARM64 backend. v -b arm64 self x2 replaces the compiler twice, so the second build runs the
compiler produced by the first native build. Use -o v_arm64 to keep the current compiler
and write a separate executable. Native self-builds use -gc none and retain commands
such as self, fmt, and version. The native compiler includes the C backend and leaves
out FastC by default.

cd examples
v hello_world.v && ./hello_world    # or simply
v run hello_world.v                 # this builds the program and runs it right away

v run word_counter/word_counter.v word_counter/cinderella.txt
v run news_fetcher.v
v run tetris/tetris.v

When a project has a .vvmrc file, v and v run try
to use the requested V binary (for example v0.4.6) before falling back to
the current compiler.

Sokol and GG GUI apps/games: Copy Chapter

In order to build Tetris or 2048 (or anything else using the sokol or gg graphics modules),
you will need to install additional development libraries for your system.

V net.http, net.websocket, `v install` Copy Chapter

The net.http module, the net.websocket module, and the v install command may all use SSL.
V comes with a version of mbedtls, which should work on all systems. If you find a need to
use OpenSSL instead, you will need to make sure that it is installed on your system, then
use the -d use_openssl switch when you compile.

Note: Mbed-TLS is smaller and easier to install on windows too (V comes with it), but if you
write programs, that do lots of http requests to HTTPS/SSL servers, in most cases, it is best
to compile with -d use_openssl, and do so on a system, where you do have OpenSSL installed
(see below). Mbed-TLS is slower, and can have more issues, especially when you are doing parallel
http requests to multiple hosts (for example in web scrapers, REST API clients, RSS readers, etc).
On windows, it is better to run such programs in WSL2.

To install OpenSSL on non-Windows systems:

On Windows, OpenSSL is simply hard to get working correctly. The instructions
here may (or may not) help.

V sync Copy Chapter

V's sync module and channel implementation uses libatomic.
It is most likely already installed on your system, but if not,
you can install it, by doing the following:

V UI Copy Chapter

https://github.com/vlang/ui

Android graphical apps Copy Chapter

With V's vab tool, building V UI and graphical apps for Android can become as easy as:

./vab /path/to/v/examples/2048

https://github.com/vlang/vab.

Developing web applications Copy Chapter

Check out the
Building a simple web blog
tutorial and Gitly, a light and fast alternative to GitHub/GitLab:

https://github.com/vlang/gitly

Vinix, an OS/kernel written in V Copy Chapter

V is great for writing low-level software like drivers and kernels.
Vinix is an OS/kernel that already runs bash, GCC, V, and nano.

https://github.com/vlang/vinix

Acknowledgement Copy Chapter

TCC Copy Section

V thanks Fabrice Bellard for his original work on the
TCC - Tiny C Compiler.
Note the TCC website is old; the current TCC repository can be found
here.
V utilizes pre-built TCC binaries located at
https://github.com/vlang/tccbin/.
On Linux, make retries the portable thirdparty-linuxmusl-* TCC bundle when
the host-specific bundle does not run on the current system.
To rebuild the bundled thirdparty/tcc in place from upstream TinyCC on the
platforms that have an in-tree build script, run make latest_tcc_source.
Pass TCC_COMMIT=<hash-or-branch> to pin a specific upstream revision.

PVS-Studio Copy Section

PVS-Studio - static analyzer for C, C++, C#, and Java code.

Troubleshooting Copy Chapter

Please see the
Troubleshooting
section on our
wiki page.

Doc Assertion Output (`doc/assertion_output.md`) Copy Section

Assertion and test output

Failed assertions and failed test error propagation write their reports to standard error.
Generated reports flush standard output before each diagnostic line and standard error afterwards.
When both streams share a pipe or file, earlier standard output appears before the report,
including when standard error is fully buffered on Windows.
Assertions marked @[assert_continues] keep the same output order when execution continues.

Doc C Aggregate Members (`doc/c_aggregate_members.md`) Copy Section

C aggregate member names

C struct and union members retain their declared spelling, including names such as index
and select that are also C library functions. C keeps aggregate members in a separate
namespace, so these field names do not conflict with function names.

A binding such as struct C.Record { index u64 } accesses the C member index in both
C.Record{ index: 42 } and record.index. This also applies through V aliases and pointers,
and when the C aggregate is embedded in a V struct. Escapes for V keywords, such as @type,
refer to the native C member type.

Ordinary V struct fields retain V's generated identifier spelling, even when an alias or
pointer is used. This includes fields whose names overlap with C library functions.
The name complex is escaped for V identifiers so including <complex.h> does not expand
them as C macros. A C binding's complex member still retains its external spelling.

Doc C And V Type Interoperability (`doc/c_and_v_type_interoperability.md`) Copy Section

[!NOTE]
an important detail to remember, is that in V, the type always follows
the identifier in declarations, i.e. you use x int in V in function parameters,
and in struct declarations, not int x, like you would in C.

Number types in C and V: Copy Chapter

• A V i8 is equivalent to C signed char, or int8_t.

• A V i16 is equivalent to C short, or int16_t.

• A V i32 is equivalent to C int, or int32_t.

• A V i64 is equivalent to C long, or int64_t.

• A V u8 is equivalent to C unsigned char, or uint8_t.

• A V u16 is equivalent to C unsigned short, or uint16_t.

• A V u32 is equivalent to C unsigned int, or uint32_t.

• A V u64 is equivalent to C unsigned long, or uint64_t.

• A V f32 is equivalent to C float.

• A V f64 is equivalent to C double.

char in C is a distinct type with implementation-defined signedness, so use
V char, &char, or charptr when you need to match C char, char*,
or char**.

• A V isize is equivalent to C ssize_t.
  It is a signed integer, and isize is guaranteed to be at least 16 bits.
  It is 32 bit on 32 bit platforms, and 64 bits on 64 bit ones.

• A V usize is equivalent to C size_t.
  It is an unsigned integer, and usize is guaranteed to be at least 16 bits.
  It is 32 bit on 32 bit platforms, and 64 bits on 64 bit ones.

• A V int is currently equivalent to C int, or int64_t.
  There are plans to make it equivalent to isize, so if you want to write C
  library wrappers, it is better to describe your fn C. parameters using i32
  instead of using int.

Representing pointers in C and V: Copy Chapter

Pointers in V are equivalent to pointers in C in usage.
One difference in their declarations, is that the order of placing the pointer
sign is swapped. For example, you use long * in C, which is equivalent to &i64 in V.

If you have a C function func_name, that accepts a int *, and an int index,
and returns an unsigned char:

unsigned char func_name(int * p, index int);

... then you can represent its function signature in V like this:

fn C.func_name(p &int, index i32) u8

For a C output parameter, pass the address of the variable or struct field that C should update.
A cast such as voidptr(&handle) preserves that address when passed to a C void **
parameter declared as &voidptr in V. Writes by C update the original caller storage,
including fields in heap allocated structs.

Representing compound types in C and V: Copy Chapter

A V struct is the same as a C struct, with the same field names and
types, but the order of declaring field names and their types in C structs
and V structs is different - in C you use: short field_name;, but in V,
that would be: field_name i16.

V does not scan C headers to discover declarations. Redeclare the fields you use
in a .c.v file, and mark a C typedef with @[typedef]. For example,
typedef struct { int x; } Foo; needs this V binding:

@[typedef]
struct C.Foo {
	x int
}

The attribute is required with both #include and #insert.

Passing V strings to C functions: Copy Chapter

The V string type, is currently defined like this:

struct string {
    u8* str;
    int len;
    int is_lit;
};

If you have a string s in V, and you also have a C function which
accepts unsigned char * in C, you can pass s.str to that function.
Do not pass &s, since that will be the address of the s struct
itself, and not the address of the characters in it (which is pointed
by s.str).

Passing V dynamic array elements to C functions: Copy Chapter

All V array types currently share the same C type, currently defined like this:

struct array {
    void * data;
    // For arrays, the following `offset` field is 0.
    // For slices, the `offset` field contains the offset (in elements) from
    // the start of the original array.
    int offset; 
    int len;
    int cap;
    int flags;
    int element_size;
};
```									
									
If you want to pass a pointer to the elements of a V array `a`, to a C function,
use `a.data`. NOTE: do *not* use `&a` for that purpose. That will result in the address
of the `array` itself, getting passed to the C function, and *not* the address of the
elements of the V array.

Passing `a.data` to a V pointer parameter also passes the element buffer directly.
Parenthesizing the argument, such as `(a.data)`, preserves that behavior.
This holds when `a` is a pointer to an array or a mutable array parameter.


## Passing V fixed array elements to C functions:
Unlike dynamic arrays, fixed arrays are the same in both V and C.
The address of the first element of the V fixed array of integers `fa` with
type `[5]i32`, is `&fa[0]` . That address can be directly used a parameter to
C functions, that accept `int * p` or `int arr[]` parameters.


## Functions in V and C:
The type of a V function, with no receiver, is equivalent to a C function, 
given that the types of the parameters are equivalent.

Ordinary V functions named `sync` or `syncfs` can coexist with the system C functions.
Their generated C names also remain distinct from V functions named `main__sync` or `main__syncfs`.
Use the `C.` prefix to refer to the C function.
For Linux bindings that declare `fn C.syncfs`, V enables GNU header declarations before
including C headers, so `` supplies the `syncfs` prototype.

When a V function returns more than one value, the C function returns a struct.
For example, these functions have equivalent types:
```v ignore
fn v_function(a u64, b i8) (i32, f32)

struct { int i; float f; } c_function(unsigned long a, signed char b);

A pointer to a V function is equivalent to a pointer to a C function, when the
functions have equivalent types.

For V functions taking ...voidptr, non-pointer scalar arguments are stored in temporaries.
Integers and enum values narrower than the target's V int are widened to int, and f32
is widened to f64. The callee must read each slot using its corresponding storage type.

Other V types, that are currently not supported/documented for use with C: Copy Chapter

Other V types like interface, thread, chan, and map types are represented
as C structs, but they are deliberately not yet completely documented for the
purposes of C interoperability, since their implementations can still change.

C struct types containing bitfields, currently have no corresponding V types.

C++ class types have no corresponding V types.

Memory allocation in V and C Copy Chapter

Keep in mind, that V uses the Boehm's garbage collector by default. You can pass
a pointer to allocated memory from C to V, just remember that the responsibility
of freeing the pointer will remain with the C side, and if the C side frees the
pointer while the V side still has a copy, your program will fail.

When passing a pointer from V to C, the V function must retain a visible copy
of it in some V variable. Otherwise the V garbage collector may free the
corresponding memory, while the C function is still using it. You can use the
attribute @[keep_args_alive] to tag your fn C. declarations, that accept
pointers, to keep them from being freed, while the call to your C.fname()
function has not returned.
For more details, see also this
test for keep_args_alive .

Doc C Backend Headers (`doc/c_backend_headers.md`) Copy Section

Headers in generated C

Literal hello world programs generate C without #include directives on supported hosted Unix,
Windows, Android and iOS targets. Windows keeps its CRT output mode; mobile targets retain
their platform logging APIs. Compiler self builds use standalone core declarations on
macOS, Linux, Windows and the BSD targets with a described libc ABI.

NetBSD, Solaris, Haiku, QNX, Serenity, Vinix and Emscripten retain the SDK preamble for
compiler and runtime builds. Their symbol versions, storage or constants require native
declarations that the standalone preamble does not yet describe completely. Literal
hello output still avoids those headers on the other hosted targets. Vinix retains the complete
runtime even for literal output. Native execution must be validated on each
platform; generating C for a target alone does not verify its runtime ABI.
The compiler's string literals can contain the text of includes for other generated programs.
The C backend emits libc prototypes from bodyless V declarations such as
fn C.strlen(const_s &char) usize. Without system headers, this includes the bindings that a
program declares itself, such as fn C.getpgrp() int or a Win32 function in Windows C,
which nothing else would declare. Runtime bindings are marked used so cached modules
retain their prototypes. Native backends retain C declarations without rooting same-named
V functions.
With -target-libc-headers, <errno.h> owns the errno accessor declarations.
This avoids conflicting i32* prototypes on targets whose int32_t is long,
such as ARM newlib.
Explicit headers for other C libraries remain included. Core SDK headers are also
restored when another binding requests headers, so native declarations stay authoritative
regardless of source collection order.
The headerless requirement covers hello world and compiler self builds, rather than every
library binding. Modules such as compress.brotli retain their C headers and cached
implementations.
Coverage and profiling retain file I/O and timer declarations even when the application
imports no standard library modules.
On macOS, standalone statvfs storage retains the native 32-bit block and inode counters;
its field offsets and widths are checked against the installed SDK.
Mach task APIs declared by the application also keep their prototypes in headerless C.
An explicit Mach SDK header remains authoritative when supplied by the application.

On FreeBSD and OpenBSD, builds with system headers include <sys/sysctl.h> for
os.executable() and retain its native sysctl declaration. Headerless builds supply
the sysctl constants and prototype directly.

Win32 API names in headerless C declarations receive WINAPI and their wide export
names only for Windows targets. On other targets, names such as Sleep and CreateFile
keep the spelling and calling convention of the program's own C functions.

For a single-file hosted program containing only literal print, println, eprint,
and eprintln calls, the compiler proves that no V allocations are needed. It emits
only main and the required native declarations, without linking a collector or initializing
the V runtime. Platform logging adapters remain linked when required.
On POSIX targets a single println uses puts; other output preserves
embedded NUL bytes and handles partial writes. Windows ASCII output uses the CRT in binary mode,
with bounded write counts and partial-write retries. Unicode console output retains
the normal Windows runtime. Android retains log priorities, formatting and configurable
tags. iOS retains the native logger; allocations within platform loggers belong to those
libraries. iOS format literals containing % retain the normal runtime. Programs with
allocations, initialization, or other runtime requirements retain their normal runtime.
Instrumented, library, freestanding,
and -file-list builds also retain their runtime support. Portable -os cross and -cross
snapshots retain the complete runtime, pointer-width checks, and custom-define metadata even
for literal output.

The GC, signal, process, and compiler helpers are linked from native objects. Their platform headers
are parsed when those objects are built. V caches the objects using the C compiler, target,
flags, and source and header dependencies. -nocache disables the V module cache; native
objects can still be reused. The collector's thread registration and signal handling stay
in the native helpers.
Missing shipped C objects are built with the selected compiler, including TinyCC.
On macOS, existing or external object inputs still select the platform C compiler.
Wrappers that expand Boehm allocation macros include the collector header explicitly.
Warm incremental builds share the cached declaration prefix's string storage and retain
new program literals and cleanup hooks after source edits.
Warm builds using os also retain system-header ownership, so platform stat macros do not
conflict with compatibility declarations. Windows standalone and custom-libc builds keep
their required native layouts.
Windows file and console APIs preserve C.DWORD output pointer types at SDK call sites.
This preserves the SDK's pointer types when a C compiler checks calls against Windows headers.
Core file mappings retain standalone declarations on verified 64-bit targets, including native
mapping flags and the synchronization function signature. Other targets and programs using
explicit C headers or custom libc headers keep platform-header ownership.

Regular generated C declares interned strings with _SL(_str_N, "...", byte_length).
The macro expands to a static const string with a plain brace initializer. V supplies the byte
length, including embedded NUL bytes, so the C compiler needs no compound literal or sizeof.
Literal IDs remain ordinary identifiers so they do not expand C struct member names. This form also
works in portable snapshots and MSVC output. Cached modules retain explicit literal initializers
for sharing and rewriting through their declaration prefix.
The _SL helper is defined only around each literal table and undefined before generated functions,
so a C binding can declare and call a function named _SL. A _SL macro defined by an included C
header or a -D flag is saved with #pragma push_macro before the table and restored after it.

Generated C still needs the native objects and library flags when linked. Use V to build
executables, or -generate-c-project to export a build command with the native sources
and library flags.

Autofree uses a monolithic build so cleanup retains complete local-variable metadata.

Scalar array appends can use typed stores into spare capacity in library modules as well as
main. Growth and slice handling retain the runtime append helper. User functions and callbacks
named array_push keep their own calls.

Older bootstrap compilers use compatibility headers for their first compiler build.
The BSD constants used by os.executable() are defined in V. The current compiler
supplies an internal capability define and omits the compatibility headers.
FreeBSD resident memory lookup also uses V-owned sysctl identifiers without libprocstat.

Portable -os cross snapshots and -is_o objects embed their V-owned native runtime helpers,
so standalone C consumers do not need helper paths from the compiler checkout. These modes
and -no-builtin use compatibility headers when complete V bindings are unavailable.

Portable compiler snapshots generated with -cross cmd/v or -os cross cmd/v supply
their runtime declarations and helper definitions from V without include directives on
the supported hosted targets, except explicit Windows targets. Windows compiler snapshots
use the Windows SDK and embed the native stream, clock, thread, tool-cache, and atomic helpers,
so they can be compiled and linked without native objects from the generating checkout.
They retain the complete compiler runtime and disable the platform signal handler.
The text of includes inside compiler string literals is still present for other generated programs.

Malformed embedded compatibility headers are diagnosed before C compilation in portable,
object, and -no-builtin modes. Parallel builds can reuse a native object cache directory
created by another compiler process; filesystem failures remain errors.

Negated integer literals above INT_MAX and within the signed 64-bit range receive an LL
suffix in C output, including parenthesized operands and constant initializers. This preserves
their sign with MSVC.

With -target-libc-headers, the target libc owns the accessor behind its errno macro.
The generated C includes <errno.h> and leaves the libc accessor declaration to that header,
avoiding conflicts where the target's int32_t differs from C's int. Headerless output
retains the V-owned declarations.

Doc C Compiler Selection (`doc/c_compiler_selection.md`) Copy Section

C compiler selection

For ordinary C builds without -cc, V uses an available TinyCC when the target and build
options allow it. For binary output, V checks native flags and probes link dependencies before
transforming or monomorphizing the program. Known incompatible C++ or Objective-C inputs, external
objects on macOS, and missing or incompatible dependencies select the platform compiler.
Deferred compile-time branches are excluded from this probe until their conditions are known.
C and object output skip the link dependency probe.

If headers or generated program symbols expose a later TinyCC failure, V regenerates the program
for the platform compiler. Regeneration re-evaluates compiler-specific conditions such as
$if tinyc. On POSIX systems it replaces the compiler process, releasing the earlier AST and C
buffers before the retry. Windows waits for the retry to preserve its exit status.

Known incompatible native inputs select the platform compiler quietly; -v reports the reason.
Dependency probe failures and later TinyCC failures print a warning after semantic validation.
Invalid programs retain their existing error diagnostics. -silent suppresses this warning.
An explicit -cc tcc bypasses early preflight and retains the existing
retry behavior for recognized TinyCC failures. -no-retry-compilation disables these retries.
Passing -cc clang, -cc gcc, or -cc cc selects that compiler directly.

Doc C String Literals (`doc/c_string_literals.md`) Copy Section

Generated C string literals

The C backend emits long string table entries as adjacent C string literals on separate
source lines. Each piece stays below the per-literal and source-line limits used by MSVC.
This includes strings embedded in the compiler itself, such as its C prelude, so they can
be compiled during makev.bat -msvc bootstrap stages.

Splitting preserves the string's bytes and byte length, including embedded zero bytes and
escaped characters. It applies to regular, split, and cached string table declarations.
The limits on the total size of concatenated literals still depend on the target C compiler.

Doc Closure Sum Returns (`doc/closure_sum_returns.md`) Copy Section

Closures returning sum types

Closures can return imported sum types and containers of them, such as []json2.Any.
Their variables remain function values and can be called or assigned to other callback variables.

import json2

parts := fn (s string) []json2.Any {
    return s.split(',').map(json2.Any(it))
}
println(json2.encode(parts('a,b'))) // ["a","b"]

Doc Codelite (`doc/codelite.md`) Copy Section

CodeLite Setup

CodeLite works well with V when you open the code as a
File System Workspace
and define custom build targets with
CodeLite macros.

This guide uses POSIX shell commands, which match Linux and macOS. On Windows,
use .exe outputs and replace rm -f with del.

Prerequisites Copy Chapter

• Put v on your PATH. If it is not on your PATH, replace v below
  with the absolute path to your V compiler.
• Create a CodeLite workspace from your existing source tree:
  1. Open File -> New -> New workspace
  2. Choose File System Workspace
  3. Select the folder containing your V sources

Open the workspace settings by right-clicking the top-level folder and choosing
Settings....

General Settings Copy Chapter

Set these fields first:

• Tool chain: gcc or clang
• File extensions: add v, vsh, and vv

CodeLite uses the selected tool chain mainly to parse build output, so any
GNU-like tool chain is fine here.

For single-file programs, use:

• Executable: $(CurrentFilePath)/$(CurrentFileName)
• Working directory: $(CurrentFilePath)

For a project rooted at the workspace folder, use:

• Executable: $(WorkspacePath)/$(WorkspaceName)
• Working directory: $(WorkspacePath)

Build Targets Copy Chapter

The default build and clean targets can not be removed. Add run and
test targets if you want them in the Build menu.

Build the current file Copy Section

This is the simplest setup for scripts, examples, and small programs:

• build:
  v -g -o "$(CurrentFilePath)/$(CurrentFileName)" "$(CurrentFileFullPath)"
• clean: rm -f "$(CurrentFilePath)/$(CurrentFileName)"
• run: v run "$(CurrentFileFullPath)"
• test: v test "$(CurrentFileFullPath)"

Build the whole workspace Copy Section

If the workspace root is a V project with v.mod, or the workspace folder is
your app entry point, use:

• build: v -g -o "$(WorkspacePath)/$(WorkspaceName)" "$(WorkspacePath)"
• clean: rm -f "$(WorkspacePath)/$(WorkspaceName)"

If your app starts from a specific file such as src/main.v, replace
"$(WorkspacePath)" with that file path in the build target.

Running and Debugging Copy Chapter

• Press F7 to run the build target.
• Use Run or Debug after Executable points to the file produced by the
  build target.
• Keep -g in the build command so gdb or lldb can show V source
  locations.

Better Compiler Errors in the IDE Copy Chapter

If CodeLite opens the wrong file from compiler errors, add this workspace
environment variable:

• VERROR_PATHS=absolute

That makes v print absolute file paths, which is often better for IDE
launchers.

Formatting and Language Features Copy Chapter

For manual formatting, or for a formatter command inside CodeLite, use:

• v fmt -w "$(CurrentFileFullPath)"

For completion, go-to-definition, hover information, and related IDE features,
use v-analyzer alongside CodeLite.

Doc Compile Error Messages (`doc/compile_error_messages.md`) Copy Section

Compile-time error messages

$compile_error accepts a plain string literal as its message.
Concatenated strings, interpolation, and other expressions receive an explicit parser diagnostic.
In generic reflection loops, selected errors include the directive's source location and are
reported once, without treating the directive as an ordinary function call.
With -json-errors, the diagnostic keeps its structured file, line, column, and message fields.

Doc Compiler Fallback (`doc/compiler-fallback.md`) Copy Section

Compiler fallback diagnostics

V automatically retries with the V 0.5.2 compatibility compiler only after a
c_compilation_error failure. V errors (compiler_error), including parser and
checker errors, and unsupported inline assembly (inline_asm) do not trigger a
compatibility retry. They retain the original compiler's failure exit status,
without locating, installing, or launching the compatibility compiler.

If a V executable embeds an incomplete vlib/v/gen/c/manual_stdlib_c_headers.h, builds that
need its manual libc preamble report the damaged header before generating C and exit 1.
The diagnostic appears once and does not trigger a compatibility retry. Restore the header
with git restore vlib/v/gen/c/manual_stdlib_c_headers.h, then rebuild V with make.
Headerless C output and -target-libc-headers builds do not use this embedded header.

Hard checker errors in dependency functions referenced by the selected source files,
including callbacks, stored function values, and transitive calls, are reported at the
dependency's source location before C generation. This also applies to standard-library
and installed modules. Dependency warnings and notices remain limited to project-owned files.

Compiler builds report ordinary checker diagnostics before C generation, including v -check cmd/v.
The compiler entry paths select self-build optimizations; naming an ordinary program v.v does
not. Explicit -building-v builds still validate assignments, field access, and mutability.

For a C compiler failure, V prints the saved output when available, without compiling
again, before retrying. It is labeled C compiler output from the default V compiler:.
Internal arguments used to restart the default compiler are removed before launching
the compatibility compiler, so a prior implicit TCC warning cannot cause an unknown-argument error.
Option values and arguments passed to a program remain intact during this filtering.

Literal-output programs retain the array iteration helpers used by Linux backtrace formatting.
For example, v -show-timings examples/hello_world.v builds without a missing array__get symbol.

If V diagnostics were deferred while a failure marker was armed, V replays only the
default compiler with fallback disabled to display them. This diagnostic replay is
not a compatibility retry and cannot turn the original failure into success.
When saved C output is missing or empty, the same replay recovers the C diagnostic
before the compatibility retry. Replayed output is labeled
Compiler output from the default V compiler:.
The replay uses -skip-running and VNORUN=1, so user programs and .vsh scripts
are not executed even if compilation succeeds on the second attempt. Already-merged
VFLAGS are not applied twice, and the replay's environment changes do not affect
the parent or an actual C-error retry. If the replay produces no output, V reports
that explicitly instead of silently omitting the diagnostic.

V diagnostics use the compatibility compiler's colors: errors are red, notices are
yellow, and warnings and conflicting declarations are magenta. Source locations,
severity labels, and underlines are bold; the highlighted source span uses the
severity's color. Diagnostic replay preserves the parent terminal's color support
even though it captures the compiler output through a pipe. Use -color or -nocolor
to override detection, or VCOLORS=always / VCOLORS=never to set its default.
Redirected diagnostics remain plain unless colors are explicitly enabled.

Diagnostic output does not depend on automatic bug reporting being enabled. For C
errors, it is shown before locating or launching the fallback, even when that
fallback succeeds. A successful C-error fallback still returns success, and
unsuccessful retries retain their exit status. Diagnostics already shown are not
replayed again if the fallback is unavailable.

Use v -new-compiler ... to disable the C-error compatibility fallback as well.
An explicit v -old-compiler ... request still selects V 0.5.2 directly and does not
have a failed default compilation to display.

When a compatibility compiler must be built, V searches PATH for make, then gmake.
On Windows it also accepts MSYS2's mingw32-make. Install GNU make and ensure that
MSYS2's make executable and sh are on PATH: the make v1 target uses POSIX shell recipes.

The -vls-mode compatibility protocol suppresses successful on-demand installation progress
so the first response contains only the requested compiler output. Installation failures still
include the installer's output and a failing exit status. Other commands retain installation
progress.

If a build needs a missing bundled Boehm GC archive, V reports the missing library
before invoking the C compiler. Reinstall V to restore the bundled libraries, or
pass -d use_bundled_libgc to build GC from source. -gc none compiles without GC.
Generating C or an object file does not require this archive. Missing system -lgc
libraries retain the linker diagnostic and advice to install the development package.

On Linux amd64, V's TCC fence shim uses a private symbol so it can link alongside
TCC's atomic runtime helpers. Boehm GC builds use the canonical GC header under
TCC, avoiding a duplicate compatibility definition of GC_noop1_ptr. These builds
can use TCC directly without a duplicate-symbol warning and a retry with cc.

The compatibility compiler cache uses V1_FALLBACK_CACHE_DIR when set, followed by
XDG_CACHE_HOME/v/v1-fallback and HOME/.cache/v/v1-fallback. On Windows, when those
variables are unset, it uses LOCALAPPDATA\v\v1-fallback, reusing the same cache
across invocations. Looking up this path does not create directories. If none of
these variables is set, V reserves a private cache under the temporary directory;
on Windows, that last-resort cache has a fresh random name.

Implicit C compiler selection excludes TCC for -race, because TCC has no ThreadSanitizer
runtime. Test build facts follow this rule on every host, including Windows, where race
builds themselves are unsupported. Explicit compiler requests are checked separately.

User builds have a default memory safety limit of 10176 MiB. Set -memory-limit <size>
(or --memory-limit <size>) before the source or subcommand to choose another limit.
Unsuffixed values and M/m values use MiB; K/k use KiB and G/g use GiB.
The value must be a nonnegative integer whose converted KiB value fits in a signed 64-bit
integer. Missing, empty, malformed, negative, and overflowing values produce a CLI error.
An explicit zero disables the limit, as does -no-memory-limit.

The Windows TCC backend supports -cstrict, including the startup code that sets the compiler's
VEXE environment variable. Generated CRT calls retain explicit declarations and strict checks
for implicit function declarations.

Doc Compiler Output (`doc/compiler_output.md`) Copy Section

Compiler output files

With the C or FastC backend, ./v -b c -o app source.v retains generated C as app.c.
For a Windows target, the executable is app.exe; its suffix does not change the C filename.
An explicit .exe output name is respected: -o app.exe retains C as app.exe.c.
An output name ending in .c generates only C and does not invoke the C compiler.

In constant fixed arrays, shorthand enum values resolve against the array element type,
including aliases of enum types. Other enums with the same member name do not affect the value.

Doc Comptime Reflection Sources (`doc/comptime-reflection-sources.md`) Copy Section

Compile-time reflection sources

Reflection loops such as $for variant in val.variants resolve their source in the scope
of the function containing the loop. In a generic function, a parameter of type T can
be reflected on inside $if T is $sumtype. The compiler checks that parameter when its
function scope and type are available.

Importing a module with an unused generic reflection function does not resolve its
parameter as a type in another imported module. Named types used as reflection sources
are checked in the source file's own module, including before function body checking.

A concrete type passed to a generic reflection function keeps its declaring module.
For example, config.Cfg retains its own fields when another dependency imports
rand.config; an unrelated module import cannot change $for field in T.fields.

An explicit import alias keeps the type imported by that source file. A generic
reflection function can import another type under the same alias as its caller
without changing the concrete type passed as T.

Repeated method reflection loops in generic specializations borrow AST node headers during
metadata lookup. Empty method scans allocate only their metadata containers instead of a
node copy for every scanned AST entry.

Doc Custom Attribute Arguments (`doc/custom_attribute_arguments.md`) Copy Section

Attribute arguments

Typed attributes accept positional and named arguments. Each schema field must be supplied once;
repeating a named field or supplying it both positionally and by name is an error.

Enum values use a leading dot. A call such as @[Route(method: .get)] can begin with a named
enum argument, including when the schema is qualified with its module name.

Doc Custom Attributes (`doc/custom_attributes.md`) Copy Section

Attribute schemas

A struct marked with @[attribute] declares a metadata schema. Schemas cannot be initialized,
embedded, or supplied as generic type arguments. This restriction covers generic types,
function and method calls, and generic functions taken as values.

Doc Docs (`doc/docs.md`) Copy Section

V Documentation

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

Introduction Copy Chapter

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

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

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

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

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

Language specification Copy Chapter

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

Until V 1.0, the language reference is defined by:

• This document (doc/docs.md) for syntax and semantics.
• The compiler implementation in vlib/v/.
• The executable language tests in vlib/v/tests/, vlib/v/parser/tests/,
  vlib/v/checker/tests/, and vlib/v/slow_tests/inout/.

When documentation and implementation diverge, compiler behavior and tests are the source of truth.

Installing V from source Copy Chapter

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

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

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

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

Upgrading V to latest version Copy Chapter

If V is already installed on a machine, it can be upgraded to its latest version
by using the V's built-in self-updater.
To do so, run the command v up.
This also refreshes the bundled TCC binaries used for fast C compilation.

After updating, v up refreshes previously cached vlib modules with the compiler
and flags used to cache them, including normal and -prod builds. Unchanged
modules are reused. Each module being cached is printed to standard output as
Caching module <name>.... A failed cache refresh makes v up fail.
Cached module headers preserve struct field attribute groups, so valid deprecation
attributes do not introduce warnings during refresh.
Ordinary builds report cache progress on standard error. Refreshes retain absolute
module search paths, resolved C compiler commands, and build modes. They omit
linker-only flags, including operands embedded in -cflags. Relative V3CACHE
and VTMP paths are resolved against the directory where v up was invoked.
Refreshes retain each build's working directory for relative C compilation inputs
and its effective -run-only test selectors and assertion display mode.
Object flags include source #flag directives. Records with vanished project
directories or required compile inputs are skipped. Builds without relative inputs
or project interface scopes share refresh records across projects.
Project directives are merged with flags from the updated modules, so changes to
vlib #flag directives take effect during refresh. Cached TCC production builds
apply the production optimization flags to both module objects and the program.
Refreshes use the original entry when needed to preserve project interface
implementers, stopping before linking or running the program. Refreshes
retain absolute -file-list operands for live entries, re-expanding directories
to include their current sources. Records whose listed files or directories vanished
are skipped. Historical records sharing the same live command, working directory,
entry and assertion display mode refresh once. Synthetic refreshes
also replay source C driver options such as sanitizers at link time. Records for
unavailable C compilers are skipped.
Unreadable, truncated, and unsupported inventory files are skipped. Live entries
retain their project source identity; after the project input changes, obsolete
configurations are skipped until a successful build records the current inputs.
Older live records without source identities require rebuilding the project once.
Isolated test caches use the primary V compiler executable, including when
v up runs through the fallback compiler or as a separate tool, or a build uses
the delegated ownership compiler. Ownership dispatch preserves the primary path
through V3_PRIMARY_VEXE, independently of the helper's VEXE.

For caches created before V recorded their build settings, v up identifies the
cached vlib modules and refreshes them in both modes for the available C compilers,
for programs and tests. Successful migrations mark the old headers so subsequent
updates use the new inventory without repeating the fallback matrix.

v up reports the agent skills that the new revision left behind, since a new
revision may ship updated copies of them. It writes nothing: the skills belong to
the user, and updating the compiler is not consent to overwrite them. Pass
-skills to refresh the ones that were not edited locally, or run
v skills update --global to choose which ones.

The report is about the skills installed for the whole machine, so
v skills update needs --global to act on them; on its own it defaults to the
project directory, which is a different installation. Skills with local changes,
and skills installed before V recorded what it installed, are reported either way
and left alone; see v skills update below.

Project-local compiler versions with `.vvmrc` Copy Chapter

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

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

0.4.12

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

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

The default compiler Copy Chapter

On every native platform, the top-level v executable contains the default
compiler whose source lives in vlib/v. Every direct C build, including compiler
self-builds, is compiled in-process. The CLI remains in cmd/v; test is
handled by the default compiler, and external tools are compiled with it first.

External tools are cached under the user's V cache directory. Rebuilding a tool
prunes stale builds while retaining fresh builds for other flags and checkouts.
Pruning accepts only regular metadata files opened without following symbolic
links. On Unix, it also checks ownership before reading another cache entry.

The standard bootstrap does not build the sibling v1_fallback executable
(v1_fallback.exe on Windows). When V needs the compatibility compiler and the
sibling is missing, it reports that it is running make v1. That target reuses
or downloads the complete 0.5.2 release under the user cache. If no release
binary can run, oldv clones the 0.5.2 V sources and matching vc snapshot and
builds the fallback there. You can run make v1 explicitly to prepare it ahead
of time. Automatic provisioning keeps its launcher metadata in the user cache,
so an older read-only sibling installation can remain untouched. -old-compiler
launches the fallback explicitly, and ordinary user builds and external tools
retry through it after a compiler or C compilation failure. Explicit
-new-compiler builds remain strict default-compiler operations.
-new-compiler remains accepted for command-line compatibility and otherwise
selects the same embedded driver.

oldv --command runs a shell command in the checked-out repository, using sh -c
on Unix and cmd /c on Windows. Commands can use shell operators such as &&,
pipes, and redirection; oldv returns the command's exit status.

The installer supplements the cached fallback vlib with modules whose public
paths moved after 0.5.2. Fallback roots missing these compatibility modules are
not used. The fallback identity check also rejects a current launcher copied into the
fallback slot, including older launchers that report the same compiler version, so
compatibility commands cannot recursively launch it.
If a fallback command exits unsuccessfully, V notes where the default
compiler stopped and how to show its suppressed diagnostics. For a command
that may have run user code, the note preserves the child's status without
mislabeling it as a compiler failure, including JavaScript tests run by the compatibility compiler.
Re-run the command with -new-compiler
to see the default-compiler diagnostics without a fallback retry.

Packaging V for distribution Copy Chapter

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

Getting started Copy Chapter

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

• v init → adds necessary files to the current folder to make it a V project
• v new abc → creates a new project in the new folder abc, by default a "hello world" project.
• v new --web abcd → creates a new project in the new folder abcd, using the veb template.

The v new --web template uses veb, V's web framework.

When run in a terminal, v new and v init interactively prompt for the project's
description, version and license. When stdin is not a terminal (for example when the
input is piped or redirected, as in CI), the prompts are skipped and the defaults are
used instead of blocking on input; in that case the project name must be passed as an
argument, e.g. v new abc.

Table of Contents Copy Chapter

| * Language specification

• Hello world
• Running a project folder
• Comments
• Functions
  • Hoisting
  • Returning multiple values
• Symbol visibility
• Variables
  • Mutable variables
  • Initialization vs assignment
  • Warnings and declaration errors
• V types
  • Primitive types
  • Strings
  • Runes
  • Numbers
  • Arrays
    • Array update syntax
    • Multidimensional arrays
    • Array methods
    • Array slices
  • Fixed size arrays
  • Maps
    • Map update syntax | * Module imports
  • Selective imports
  • Module hierarchy
  • Module import aliasing
• Statements & expressions
  • If
    • If expressions
    • If unwrapping
  • Match
  • In operator
  • For loop
  • Defer
  • Goto
• Structs
  • Heap structs
  • Default field values
  • Required fields
  • Short struct literal syntax
  • Struct update syntax
  • Trailing struct literal arguments
  • Access modifiers
  • Anonymous structs
  • Static type methods
  • [noinit] structs
  • Methods
  • Embedded structs
• Unions
  • Why use unions?
  • Embedding | * Functions 2
  • Immutable function args by default
  • Mutable arguments
  • Variable number of arguments
  • Anonymous & higher-order functions
  • Lambda expressions
  • Closures
  • Parameter evaluation order
• References
• Constants
  • Required module prefix
• Builtin functions
  • println
  • Printing custom types
  • Dumping expressions at runtime
• Modules
  • Create modules
  • Special considerations for project folders
  • init functions
  • cleanup functions |
    | --- | --- | --- |
    | * Type Declarations
  • Type aliases
  • Enums
  • Function Types
  • Interfaces
  • Sum types
  • Option/Result types & error handling
    • Handling options/results
  • Custom error types
  • Generics
• Concurrency
  • Spawning Concurrent Tasks
  • Channels
  • Shared Objects
  • Race Detector
• JSON
  • Decoding JSON
  • Encoding JSON
• Testing
  • Asserts
  • Asserts with an extra message
  • Asserts that do not abort your program
  • Test files
  • Running tests
• Memory management
  • Control
  • Stack and Heap
  • Ownership
• ORM
• Writing documentation

  • Newlines in Documentation Comments | * Tools

  • v fmt

  • v mcp

  • v skills

  • v clean

  • v env

  • v shader

  • v tool

  • Profiling

    • Profiling the compiler
• Package Management
  • v mod why
  • Package commands
  • Locking dependency revisions
  • Publish package
• Advanced Topics
  • Attributes
  • Conditional compilation
    • Compile time pseudo variables
    • Compile time reflection
    • Compile time code
    • Compile time types
    • Environment specific files
  • Debugger
    • Call stack
      • Trace
  • Memory-unsafe code
  • Structs with reference fields
  • sizeof and __offsetof
  • Limited operator overloading
  • Performance tuning
  • Atomics
  • Global Variables
  • Static Variables
  • Cross compilation
  • Compiling for iOS
  • Debugging
    • C Backend binaries Default
    • Native Backend binaries
    • Javascript Backend | * V and C
  • Calling C from V
  • Calling V from C
  • Passing C compilation flags
  • #pkgconfig
  • Including C code
  • C types
  • C Declarations
  • Export to shared library
  • Translating C to V
  • Working around C issues
• Other V Features
  • Inline assembly
  • Hot code reloading
  • Cross-platform shell scripts in V
  • Vsh scripts with no extension
  • Source locations in generated code
• Appendices
  • Keywords
  • Operators
  • Other online resources |

Hello World Copy Chapter

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

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

V source files use UTF-8. A UTF-8 byte order mark at the start of a file is ignored;
a byte order mark outside a string or comment elsewhere in the file is rejected.

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

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

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

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

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

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

fn main() declaration can be skipped in single file programs.
This is useful when writing small programs, "scripts", or just learning the language.
Imports and script statements can share a line when separated by semicolons.
For brevity, fn main() will be skipped in this tutorial.

Scripts can print values returned by imported functions, including floating-point values,
and interpolate them with the same formatting available inside an explicit main function.

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

println('hello world')

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

Running a project folder with several files Copy Chapter

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

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

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

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

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

Your program can then use the CLI parameters like this:

import os

println(os.args)

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

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

Comments Copy Chapter

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

Functions Copy Chapter

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

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

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

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

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

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

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

Hoisting Copy Section

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 Copy Section

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

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

Symbol visibility Copy Chapter

pub fn public_function() {
}

fn private_function() {
}

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

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

Variables Copy Chapter

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

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

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

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

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

Mutable variables Copy Section

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 Copy Section

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

fn main() {
	age = 21
}

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

fn main() {
	age := 21
}

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

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

Warnings and declaration errors Copy Section

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

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

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

To ignore values returned by a function _ can be used

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

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

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

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

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

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

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

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

V Types Copy Chapter

Primitive types Copy Section

bool

string

i8    i16  int  i64  i128
u8    u16  u32  u64  u128

rune // represents a Unicode code point

f32 f64

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

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

[!NOTE]
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 Copy Section

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.

fn main() {
	total := u128(1) << 100 // 2^100
	assert total / u128(4) == u128(1) << 98
	assert (u128(1) << 127) * u128(2) == u128(0) // wraps at 128 bits
	assert i128(-8) >> 1 == i128(-4) // keeps the sign
	assert i128(-8) >>> 1 == (u128(1) << 127) - u128(4)
}

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:

fn main() {
	assert u128(31732946804115296442105984367).str() == '31732946804115296442105984367'
}

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.

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:

fn main() {
	wide := u128(1) << 100
	assert '12345'.u128() == u128(12345)
	assert wide.hex() == '10000000000000000000000000'
	assert wide.bin().len == 101
}

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

fn main() {
	wide := (u128(1) << 100) + u128(255)
	assert '${wide:08x}' == '100000000000000000000000ff'
	m := {
		'a': wide
	}
	assert m.str().contains('100000000000000000000000ff')
}

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:

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

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

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

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

Strings Copy Section

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Strings can be easily converted to integers:

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

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

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

String interpolation

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

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

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

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

To use a format specifier, follow this pattern:

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

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

x := 123.4567
println('[${x:.2}]') // round to two decimal places => [123.46]
println('[${x:10}]') // right-align with spaces on the left => [   123.457]
println('[${int(x):-10}]') // left-align with spaces on the right => [123       ]
println('[${int(x):010}]') // pad with zeros on the left => [0000000123]
println('[${int(x):+05}]') // include the sign in the padded width => [+0123]
println('[${x:+08.2f}]') // sign, zero padding, and precision => [+0123.46]
println('[${x:-+010.2f}]') // sign and left alignment override zero padding => [+123.46   ]
println('[${int(x):b}]') // output as binary => [1111011]
println('[${int(x):o}]') // output as octal => [173]
println('[${int(x):X}]') // output as uppercase hex => [7B]

println('[${10.0000:.2}]') // remove insignificant 0s at the end => [10]
println('[${10.0000:.2f}]') // do show the 0s at the end, even though they do not change the number => [10.00]

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

println('[${'abc':3r}]') // [abcabcabc]
println('[${'abc':3R}]') // [ABCABCABC]

String operators

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

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

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

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

We have to either convert age to a string:

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

or use string interpolation (preferred):

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

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

Runes Copy Section

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

rocket := `🚀`

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

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

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

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

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

assert `\x61` == `a`
assert `\141` == `a`
assert `\u0061` == `a`

// multibyte literals work too
assert `\u2605` == `★`
assert `\u2605`.bytes() == [u8(0xe2), 0x98, 0x85]
assert `\xe2\x98\x85`.bytes() == [u8(0xe2), 0x98, 0x85]
assert `\342\230\205`.bytes() == [u8(0xe2), 0x98, 0x85]

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

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

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

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

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

Numbers Copy Section

a := 123

This will assign the value of 123 to a. By default a will have the
type int.

You can also use hexadecimal, binary or octal notation for integer literals:

a := 0x7B
b := 0b01111011
c := 0o173

All of these will be assigned the same value, 123. They will all have type
int, no matter what notation you used.

V also supports writing numbers with _ as separator:

num := 1_000_000 // same as 1000000
three := 0b0_11 // same as 0b11
float_num := 3_122.55 // same as 3122.55
hexa := 0xF_F // same as 255
oct := 0o17_3 // same as 0o173

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

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

Assigning floating point numbers works the same way:

f := 1.0
f1 := f64(3.14)
f2 := f32(3.14)

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

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:

const tile_size = 32

mut a := f32(0)
a = 1
a = -1
assert a == f32(-1)
a = 6 * tile_size
assert a == f32(192)

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

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

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

Checked integer arithmetic

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

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

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

@[ignore_overflow]
fn hash_step(h u32, b u8) u32 {
	return (h ^ u32(b)) * 16777619 // wraps on purpose
}

Arrays Copy Section

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.

mut nums := [10, 20, 30]
println(nums) // `[10, 20, 30]`
println(nums[0]) // `10`
println(nums[1]) // `20`

nums[1] = 5
println(nums) // `[10, 5, 30]`

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

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

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

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

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

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

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

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

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

mut nums := [1, 2, 3]
println(nums.len) // "3"
println(nums.cap) // "3" or greater
nums = [] // The array is now empty
println(nums.len) // "0"

data is a field (of type voidptr) with the address of the first
element. This is for low-level unsafe 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:

mut a := []int{len: 10000, cap: 30000, init: 3}

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

arr := []int{len: 5, init: -1}
// `arr == [-1, -1, -1, -1, -1]`, arr.cap == 5

// Declare an empty array:
users := []int{}

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

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.

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

count := []int{len: 4, init: index}
assert count == [0, 1, 2, 3]

mut square := []int{len: 6, init: index * index}
// square == [0, 1, 4, 9, 16, 25]

Array update syntax

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

base := [1, 2]
a := [...base, 3, 4]
assert a == [1, 2, 3, 4]

// Append to a copy of `base`, leaving `base` itself unchanged:
mut b := [...base]
b << 99
assert base == [1, 2]
assert b == [1, 2, 99]

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

Array Types

An array can be of these types:

Example Code:

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

struct Point {
	x int
	y int
}

struct Line {
	p1 Point
	p2 Point
}

type ObjectSumType = Line | Point

mut object_list := []ObjectSumType{}
object_list << Point{1, 1}
object_list << Line{
	p1: Point{3, 3}
	p2: Point{4, 4}
}
dump(object_list)
/*
object_list: [ObjectSumType(Point{
    x: 1
    y: 1
}), ObjectSumType(Line{
    p1: Point{
        x: 3
        y: 3
    }
    p2: Point{
        x: 4
        y: 4
    }
})]
*/

Multidimensional Arrays

Arrays can have more than one dimension.

2d array example:

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

3d array example:

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

Array methods

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

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

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

nums := [1, 2, 3, 4, 5, 6]
even := nums.filter(it % 2 == 0)
println(even) // [2, 4, 6]
// filter can accept anonymous functions
even_fn := nums.filter(fn (x int) bool {
	return x % 2 == 0
})
println(even_fn)

words := ['hello', 'world']
upper := words.map(it.to_upper())
println(upper) // ['HELLO', 'WORLD']
// map can also accept anonymous functions
upper_fn := words.map(fn (w string) string {
	return w.to_upper()
})
println(upper_fn) // ['HELLO', 'WORLD']

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

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

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

There are further built-in methods for arrays:

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

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

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

struct User {
	age  int
	name string
}

mut users := [User{21, 'Bob'}, User{20, 'Zarkon'}, User{25, 'Alice'}]
users.sort(a.age < b.age) // sort by User.age int field
users.sort(a.name > b.name) // reverse sort by User.name string field

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

struct User {
	age  int
	name string
}

mut users := [User{21, 'Bob'}, User{65, 'Bob'}, User{25, 'Alice'}]

custom_sort_fn := fn (a &User, b &User) int {
	// return -1 when a comes before b
	// return 0, when both are in same order
	// return 1 when b comes before a
	if a.name == b.name {
		if a.age < b.age {
			return 1
		}
		if a.age > b.age {
			return -1
		}
		return 0
	}
	if a.name < b.name {
		return -1
	} else if a.name > b.name {
		return 1
	}
	return 0
}
users.sort_with_compare(custom_sort_fn)

Array Slices

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.

nums := [0, 10, 20, 30, 40]
println(nums[1..4]) // [10, 20, 30]
println(nums[..4]) // [0, 10, 20, 30]
println(nums[1..]) // [10, 20, 30, 40]

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

array_1 := [3, 5, 4, 7, 6]
mut array_2 := [0, 1]
array_2 << array_1[..3]
println(array_2) // `[0, 1, 3, 5, 4]`

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

When a slice expression like a[2..4] is assigned 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.

mut a := [0, 1, 2, 3, 4, 5]

// Create a slice, that reuses the *same memory* as the parent array
// initially, without doing a new allocation:
mut b := unsafe { a[2..4] } // the contents of `b`, reuses the memory, used by the contents of `a`.

b[0] = 7 // Note that `b[0]` and `a[2]` refer to *the same element* in memory.
println(a) // `[0, 1, 7, 3, 4, 5]` - changing `b[0]` above, changed `a[2]` too.

// the content of `b` will get reallocated, to have room for the `9` element:
b << 9
// The content of `b`, is now reallocated, and fully independent from the content of `a`.

println(a) // `[0, 1, 7, 3, 4, 5]` - no change, since the content of `b` was reallocated,
// to a larger block, before the appending.

println(b) // `[7, 3, 9]` - the contents of `b`, after the reallocation, and appending of the `9`.

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

mut a := []int{len: 5, cap: 6, init: 2}
mut b := unsafe { a[1..4] } // the contents of `b` uses part of the same memory, that is used by `a` too

a << 3
// still no reallocation of `a`, since `a.len` still fits in `a.cap`
b[2] = 13 // `a[3]` is modified, through the slice `b`.

a << 4
// the content of `a` has been reallocated now, and is independent from `b` (`cap` was exceeded by `len`)
b[1] = 3 // no change in `a`

println(a) // `[2, 2, 2, 13, 2, 3, 4]`
println(b) // `[2, 3, 13]`

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

mut a := [0, 1, 2, 3, 4, 5]
mut b := a[2..4].clone()
b[0] = 7 // Note: `b[0]` is NOT referring to `a[2]`, as it would have been, without the `.clone()`
println(a) // [0, 1, 2, 3, 4, 5]
println(b) // [7, 3]

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:

a := [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
println(a#[-3..]) // [7, 8, 9]
println(a#[-20..]) // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
println(a#[-20..-8]) // [0, 1]
println(a#[..-3]) // [0, 1, 2, 3, 4, 5, 6]

// empty arrays
println(a#[-20..-10]) // []
println(a#[20..10]) // []
println(a#[20..30]) // []

Array method chaining

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

// using filter, map and negatives array slices
files := ['pippo.jpg', '01.bmp', '_v.txt', 'img_02.jpg', 'img_01.JPG']
filtered := files.filter(it#[-4..].to_lower() == '.jpg').map(it.to_upper())
// ['PIPPO.JPG', 'IMG_02.JPG', 'IMG_01.JPG']

Fixed size arrays Copy Section

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:

mut fnums := [3]int{} // fnums is a fixed size array with 3 elements.
fnums[0] = 1
fnums[1] = 10
fnums[2] = 100
println(fnums) // => [1, 10, 100]
println(typeof(fnums).name) // => [3]int

fnums2 := [1, 10, 100].to_fixed_size() // explicit conversion syntax
fnums3 := [1, 10, 100]! // short init syntax, equivalent to `.to_fixed_size()`

anums := fnums[..] // same as `anums := fnums[0..fnums.len]`
println(anums) // => [1, 10, 100]
println(typeof(anums).name) // => []int

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

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

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

fn fill(mut a []int) {
	for i in 0 .. a.len {
		a[i] = 9
	}
}

mut fixed := [4, 3, 2, 1]!
fill(mut fixed[2..])
println(fixed) // => [4, 3, 9, 9]
fixed[..2].sort()
println(fixed) // => [3, 4, 9, 9]

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

items := [1, 2, 3, 4, 5]
mut fixed := [4]int{}
println(copy(mut fixed, items)) // => 4
println(fixed) // => [1, 2, 3, 4]
copy(mut fixed[2..], [9, 9, 9])
println(fixed) // => [1, 2, 9, 9]
mut buf := []u8{len: 3}
copy(mut buf, 'hello')
println(buf.bytestr()) // => hel

Maps Copy Section

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.

mut m := map[string]int{} // a map with `string` keys and `int` values
m['one'] = 1
m['two'] = 2
println(m['one']) // "1"
println(m['bad_key']) // "0"
println('bad_key' in m) // Use `in` to detect whether such key exists
println(m.keys()) // ['one', 'two']
m.delete('two')

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

The whole map can be initialized using this short syntax:

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

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

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

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

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

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

Modules can opt into stricter map indexing:

@[strict_map_index]
module main

fn main() {
	m := {
		'abc': 'xyz'
	}
	value := m['abc'] or { panic('missing map key') }
	if other := m['abc'] {
		println(other)
	}
	// m['bad_key'] // compile error in `@[strict_map_index]` modules
	println(value)
}

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

m := {
	'abc': 'def'
}
if v := m['abc'] {
	println('the map value for that key is: ${v}')
}

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

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

mut data := map[string][]int{}
key := 'odd'
value := 1
if _ := data[key] {
	data[key] << value
} else {
	data[key] = [value]
}

The same option check applies to arrays:

arr := [1, 2, 3]
large_index := 999
val := arr[large_index] or { panic('out of bounds') }
println(val)
// you can also do this, if you want to *propagate* the access error:
val2 := arr[333]!
println(val2)

V also supports nested maps:

mut m := map[string]map[string]int{}
m['greet'] = {
	'Hello': 1
}
m['place'] = {
	'world': 2
}
m['code']['orange'] = 123
print(m)

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

See all methods of
map
and
maps.

Map update syntax Copy Section

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

const base_map = {
	'a': 4
	'b': 5
}

foo := {
	...base_map
	'b': 88
	'c': 99
}

println(foo) // {'a': 4, 'b': 88, 'c': 99}

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

// same as above (except mutable)
mut foo := base_map.clone()
foo['b'] = 88
foo['c'] = 99

Module imports Copy Chapter

For information about creating a module, see Modules.

Modules can be imported using the import keyword:

import os

fn main() {
	// read text from stdin
	name := os.input('Enter your name: ')
	println('Hello, ${name}!')
}

This program can use any public definitions from the os module, such
as the input function. See the standard library
documentation for a list of common modules and their public symbols.

By default, you have to specify the module prefix every time you call an external function.
This may seem verbose at first, but it makes code much more readable
and easier to understand - it's always clear which function from
which module is being called. This is especially useful in large code bases.

Cyclic module imports are not allowed, like in Go.

Selective imports Copy Section

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

import os { input }

fn main() {
	// read text from stdin
	name := input('Enter your name: ')
	println('Hello, ${name}!')
}

[!NOTE]
This will import the module as well. Also, this is not allowed for
constants - they must always be prefixed.

You can import several specific symbols at once:

import os { input, user_os }

name := input('Enter your name: ')
println('Name: ${name}')
current_os := user_os()
println('Your OS is ${current_os}.')

Module hierarchy Copy Section

[!NOTE]
This section is valid when .v files are not in the project's root directory.

Modules names in .v files, must match the name of their directory.

A .v file ./abc/source.v must start with module abc. All .v files in this directory
belong to the same module abc. They should also start with module abc.

If you have abc/def/, and .v files in both folders, you can import abc, but you will have
to import abc.def too, to get to the symbols in the subfolder. It is independent.

In module name statement, name never repeats directory's hierarchy, but only its directory.
So in abc/def/source.v the first line will be module def, and not module abc.def.

import module_name statements must respect file hierarchy, you cannot import def, only
abc.def

Referring to a module symbol such as a function or const, only needs module name as prefix:

module def

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

can be called like this:

module main

import def

fn main() {
	def.func()
}

A function, located in abc/def/source.v, is called with def.func(), not abc.def.func()

This always implies a single prefix, whatever sub-module depth. This behavior flattens
modules/sub-modules hierarchy. Should you have two modules with the same name in different
directories, then you should use Module import aliasing (see below).

Module import aliasing Copy Section

Any imported module name can be aliased using the as keyword:

[!NOTE]
This example will not compile unless you have created mymod/sha256/somename.v
(submodule names are determined by their path, not by the names of the .v file(s) in them).

import crypto.sha256
import mymod.sha256 as mysha256

fn main() {
	v_hash := sha256.sum('hi'.bytes()).hex()
	my_hash := mysha256.sum('hi'.bytes()).hex()
	assert my_hash == v_hash
}

A nested module such as app.html can import a distinct module named net.html, with or without
an alias. Their full module paths determine their identities.
A module cannot import its own full path, even when the project has no v.mod file.

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

import time
import math

type MyTime = time.Time

fn (mut t MyTime) century() int {
	return int(1.0 + math.trunc(f64(t.year) * 0.009999794661191))
}

fn main() {
	mut my_time := MyTime{
		year:  2020
		month: 12
		day:   25
	}
	println(time.new(my_time).http_header_string())
	println('Century: ${my_time.century()}')
}

Statements & expressions Copy Chapter

If Copy Section

a := 10
b := 20
if a < b {
	println('${a} < ${b}')
} else if a > b {
	println('${a} > ${b}')
} else {
	println('${a} == ${b}')
}

if statements are pretty straightforward and similar to most other languages.
Unlike other C-like languages,
there are no parentheses surrounding the condition and the braces are always required.
The condition cannot start with another if, not even a parenthesized one: store the result of
the inner if expression in a variable first.
When the condition starts with a match expression, parentheses are required around the
condition, for example if (match enabled { true { false } else { true } }) { ... }.

`If` expressions

Unlike C, V does not have a ternary operator, that would allow you to do: x = c ? 1 : 2 .
Instead, it has a bit more verbose, but also clearer to read, ability to use if as an
expression. The direct translation in V of the ternary construct above, assuming c is a
boolean condition, would be: x = if c { 1 } else { 2 }.

Here is another example:

num := 777
s := if num % 2 == 0 { 'even' } else { 'odd' }
println(s)
// "odd"

You can use multiple statements in each of the branches of an if expression, followed by a final
value, that will become the value of the entire if expression, when it takes that branch:

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

When comparing an enum value with an if or match expression using == or !=,
the enum operand supplies the type for shorthand values such as .red in the branches.
This works with the enum operand on either side of the comparison.
Branch-local values keep their declared types; unrelated enum types cannot be compared this way.

Appending an if or match expression to an enum array also supplies the element type
for shorthand values in its branches. Every branch must produce a compatible enum value.

`If` unwrapping

Anywhere you can use or {}, you can also use "if unwrapping". This binds the unwrapped value
of an expression to a variable when that expression is not none nor an error.
An optional struct field can be unwrapped this way even after an earlier none check.

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

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

fn res() !int {
	return 42
}

// functions that return a result type
if v := res() {
	println(v)
}

struct User {
	name string
}

arr := [User{'John'}]

// if unwrapping with assignment of a variable
u_name := if v := arr[0] {
	v.name
} else {
	'Unnamed'
}
println(u_name) // John

Type checks and casts

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

Note that the variable's declared type stays the sum type itself. In the example
below, x has the static type Alphabet, even though the value it holds is an
Abc. Inside an is check (or a match branch) the compiler automatically
smart casts x to the matched variant, so within that block x has the static
type Abc and you can access its fields directly and safely, without writing an
explicit as cast.

You can do it either in an if:

struct Abc {
	val string
}

struct Xyz {
	foo string
}

type Alphabet = Abc | Xyz

x := Alphabet(Abc{'test'}) // sum type
if x is Abc {
	// x is automatically cast to Abc and can be used here
	println(x)
}
if x !is Abc {
	println('Not Abc')
}

or using match:

match x {
	Abc {
		// x is automatically cast to Abc and can be used here
		println(x)
	}
	Xyz {
		// x is automatically cast to Xyz and can be used here
		println(x)
	}
}

This works also with struct fields:

struct MyStruct {
	x int
}

struct MyStruct2 {
	y string
}

type MySumType = MyStruct | MyStruct2

struct Abc {
	bar MySumType
}

x := Abc{
	bar: MyStruct{123} // MyStruct will be converted to MySumType type automatically
}
if x.bar is MyStruct {
	// x.bar is automatically cast
	println(x.bar)
} else if x.bar is MyStruct2 {
	new_var := x.bar as MyStruct2
	// ... or you can use `as` to create a type cast an alias manually:
	println(new_var)
}
match x.bar {
	MyStruct {
		// x.bar is automatically cast
		println(x.bar)
	}
	else {}
}

Mutable variables can change, and doing a cast would be unsafe.
However, sometimes it's useful to type cast despite mutability.
In such cases the developer must mark the expression with the mut keyword
to tell the compiler that they know what they're doing.

It works like this:

mut x := MySumType(MyStruct{123})
if mut x is MyStruct {
	// x is cast to MyStruct even if it's mutable
	// without the mut keyword that wouldn't work
	println(x)
}
// same with match
match mut x {
	MyStruct {
		// x is cast to MyStruct even if it's mutable
		// without the mut keyword that wouldn't work
		println(x)
	}
}

Match Copy Section

A match expression can return multiple values. A branch ending with comma-separated values can
be combined with a branch ending in a call that returns the same types.

Conditions that compare different nested fields remain distinct match cases, even when
their final field names and comparison operators are the same.

os := 'windows'
print('V is running on ')
match os {
	'darwin' { println('macOS.') }
	'linux' { println('Linux.') }
	else { println(os) }
}

A match statement is a shorter way to write a sequence of if - else statements.
When a matching branch is found, the following statement block will be run.
The else branch will be run when no other branches match.

number := 2
s := match number {
	1 { 'one' }
	2 { 'two' }
	else { 'many' }
}

A match statement can also to be used as an if - else if - else alternative:

match true {
	2 > 4 { println('if') }
	3 == 4 { println('else if') }
	2 == 2 { println('else if2') }
	else { println('else') }
}

// 'else if2' should be printed

or as an unless alternative: unless Ruby

match false {
	2 > 4 { println('if') }
	3 == 4 { println('else if') }
	2 == 2 { println('else if2') }
	else { println('else') }
}

// 'if' should be printed

A match expression returns the value of the final expression from the matching branch.

A match expression can propagate results with ! in its branches, including results
containing pointers to interfaces. A branch error propagates from the enclosing function.
Where a pointer to an interface is expected, such as &Shape or ?&Shape, the branches
can return pointers to different types that implement that interface.

When inferring an enum result, a qualified value in the first branch, such as Color.red,
provides the type for shorthand values such as .blue in subsequent branches.
This also applies to parenthesized shorthand values and bitwise expressions with flag enums.

enum Color {
	red
	blue
	green
}

fn is_red_or_blue(c Color) bool {
	return match c {
		.red, .blue { true } // comma can be used to test multiple values
		.green { false }
	}
}

A match statement can also be used to branch on the variants of an enum
by using the shorthand .variant_here syntax. An else branch is not allowed
when all the branches are exhaustive.

c := `v`
typ := match c {
	`0`...`9` { 'digit' }
	`A`...`Z` { 'uppercase' }
	`a`...`z` { 'lowercase' }
	else { 'other' }
}

println(typ)
// 'lowercase'

A match statement also can match the variant types of a sumtype. Note that
in that case, the match is exhaustive, since all variant types are mentioned
explicitly, so there is no need for an else{} branch.

struct Dog {}
struct Cat {}
struct Veasel {}
type Animal = Dog | Cat | Veasel
a := Animal(Veasel{})
match a {
	Dog { println('Bay') }
	Cat { println('Meow') }
	Veasel { println('Vrrrrr-eeee') } // see: https://www.youtube.com/watch?v=qTJEDyj2N0Q
}

You can also use ranges as match patterns. If the value falls within the range
of a branch, that branch will be executed.

Note that the ranges use ... (three dots) rather than .. (two dots). This is
because the range is inclusive of the last element, rather than exclusive
(as .. ranges are). Using .. in a match branch will throw an error.

const start = 1

const end = 10

c := 2
num := match c {
	start...end {
		1000
	}
	else {
		0
	}
}

println(num)
// 1000

Constants can also be used in the range branch expressions.

[!NOTE]
match as an expression is not usable in for loop and if statements.

In operator Copy Section

in allows to check whether an array or a map contains an element.
To do the opposite, use !in.

nums := [1, 2, 3]
println(1 in nums) // true
println(4 !in nums) // true

[!NOTE]
in checks if map contains a key, not a value.

m := {
	'one': 1
	'two': 2
}

println('one' in m) // true
println('three' !in m) // true

It's also useful for writing boolean expressions that are clearer and more compact:

enum Token {
	plus
	minus
	div
	mult
}

struct Parser {
	token Token
}

parser := Parser{}
if parser.token == .plus || parser.token == .minus || parser.token == .div || parser.token == .mult {
	// ...
}
if parser.token in [.plus, .minus, .div, .mult] {
	// ...
}

V optimizes such expressions,
so both if statements above produce the same machine code and no arrays are created.

For loop Copy Section

V has only one looping keyword: for, with several forms.

`for`/`in`

This is the most common form. You can use it with an array, map or
numeric range.
The opening { of the loop body may appear on the next line after the iterable or range.

Array `for`

numbers := [1, 2, 3, 4, 5]
for num in numbers {
	println(num)
}
names := ['Sam', 'Peter']
for i, name in names {
	println('${i}) ${name}')
	// Output: 0) Sam
	//         1) Peter
}

The for value in arr form is used for going through elements of an array.
If an index is required, an alternative form for index, value in arr can be used.

Note that the value is read-only.
If you need to modify the array while looping, you need to declare the element as mutable:

mut numbers := [0, 1, 2]
for mut num in numbers {
	num++
}
println(numbers) // [1, 2, 3]

By default, array elements are taken by value, if you need elements to be taken by
reference, use & on the array you want to iterate over:

struct User {
	name string
}

users := [User{
	name: 'someuserwow99'
}, User{
	name: 'visgod'
}]
// note `&users`, this is how a reference to the elements of the array is received
for user in &users {
	// some operations with `user`
}

The same applies to maps.

When an identifier is just a single underscore, it is ignored.

Custom iterators

Types that implement a next method returning an Option can be iterated
with a for loop.

struct SquareIterator {
	arr []int
mut:
	idx int
}

fn (mut iter SquareIterator) next() ?int {
	if iter.idx >= iter.arr.len {
		return none
	}
	defer {
		iter.idx++
	}
	return iter.arr[iter.idx] * iter.arr[iter.idx]
}

nums := [1, 2, 3, 4, 5]
iter := SquareIterator{
	arr: nums
}
for squared in iter {
	println(squared)
}

The code above prints:

1
4
9
16
25

Map `for`

m := {
	'one': 1
	'two': 2
}
for key, value in m {
	println('${key} -> ${value}')
	// Output: one -> 1
	//         two -> 2
}

A mutable map iteration value still has the map's element type. Assigning it to a map entry copies
that element, including when its struct type comes from another module.
When iterating a reference to a map (for key, value in &m), values with ordinary element types
are pointers to their entries. Assigning one to another variable preserves its reference to the
same entry. If the map element is already a pointer or an optional, the loop value keeps that
element type instead.
A pointer to a nested array or map remains a reference container when iterated again,
including through parentheses or a closure capture.
Fixed-array map values also refer to their entry storage, so changes through the reference update
the map value.
Aliases of array and map pointers preserve these reference semantics, including pointer rebinding.
Parentheses around a mutable map container do not change whether assigning the loop value updates
its entry.
Mutable map parameters, including explicit pointer parameters (mut m &map[K]V),
keep ordinary value iteration. A mutable loop value writes through to the map entry.
A mutable pointer-valued loop argument can rebind the stored pointer, including through
parentheses, while a mutable struct argument updates the pointed-to struct.

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

m := {
	'one': 1
	'two': 2
}
// iterate over keys
for key, _ in m {
	println(key)
	// Output: one
	//         two
}
// iterate over values
for _, value in m {
	println(value)
	// Output: 1
	//         2
}

Range `for`

// Prints '01234'
for i in 0 .. 5 {
	print(i)
}

low..high means an exclusive range, which represents all values
from low up to but not including high.

[!NOTE]
This exclusive range notation and zero-based indexing follow principles of
logical consistency and error reduction. As Edsger W. Dijkstra outlines in
'Why Numbering Should Start at Zero'
(EWD831),
zero-based indexing aligns the index with the preceding elements in a sequence,
simplifying handling and minimizing errors, especially with adjacent subsequences.
This logical and efficient approach shapes our language design, emphasizing clarity
and reducing confusion in programming.

Condition `for`

mut sum := 0
mut i := 0
for i <= 100 {
	sum += i
	i++
}
println(sum) // "5050"

This form of the loop is similar to while loops in other languages.
The loop will stop iterating once the boolean condition evaluates to false.
Again, there are no parentheses surrounding the condition, and the braces are always required.

Bare `for`

mut num := 0
for {
	num += 2
	if num >= 10 {
		break
	}
}
println(num) // "10"

The condition can be omitted, resulting in an infinite loop.

C `for`

for i := 0; i < 10; i += 2 {
	// Don't print 6
	if i == 6 {
		continue
	}
	println(i)
}

Finally, there's the traditional C style for loop. It's safer than the while form
because with the latter it's easy to forget to update the counter and get
stuck in an infinite loop.

Here i doesn't need to be declared with mut since it's always going to be mutable by definition.

Labelled break & continue

break and continue control the innermost for loop by default.
You can also use break and continue followed by a label name to refer to an outer for
loop:

outer: for i := 4; true; i++ {
	println(i)
	for {
		if i < 7 {
			continue outer
		} else {
			break outer
		}
	}
}

The label must immediately precede the outer loop.
A labelled loop can iterate over a filter or map result; break and continue
refer to that loop after its iterable has been evaluated.
The above code prints:

4
5
6
7

Defer Copy Section

A defer {} statement, defers the execution of the block of statements
until the surrounding scope of the defer ends. It is a convenient feature
that allows you to group related actions (getting access to a resource
and cleaning/freeing it after you are done) closely together, instead
of spreading them across multiple potentially very remote lines of code.

import os

fn read_log() ! {
	mut ok := false
	mut f := os.open('log.txt')!
	defer { f.close() }
	// ...
	if !ok {
		// ...
		// defer statement will be called here, the file will be closed
		return
	}
	// ...
	// defer statement will be called here too, the file will be closed
}

If the function returns a value the defer block is executed after the return
expression is evaluated:

import os

enum State {
	normal
	write_log
	return_error
}

// write log file and return number of bytes written

fn write_log(s State) !int {
	mut f := os.create('log.txt')!
	defer {
		f.close()
	}
	if s == .write_log {
		// `f.close()` will be called after `f.write()` has been
		// executed, but before `write_log()` finally returns the
		// number of bytes written to `main()`
		return f.writeln('This is a log file')
	} else if s == .return_error {
		// the file will be closed after the `error()` function
		// has returned - so the error message will still report
		// it as open
		return error('nothing written; file open: ${f.is_opened}')
	}
	// the file will be closed here, too
	return 0
}

fn main() {
	n := write_log(.return_error) or {
		println('Error: ${err}')
		0
	}
	println('${n} bytes written')
}

To access the result of the function inside a defer block the $res() expression can be used.
$res() is only used when a single value is returned, while on multi-return the $res(idx)
is parameterized.

fn (mut app App) auth_middleware() bool {
	defer {
		if !$res() {
			app.response.status_code = 401
			app.response.body = 'Unauthorized'
		}
	}
	header := app.get_header('Authorization')
	if header == '' {
		return false
	}
	return true
}

fn (mut app App) auth_with_user_middleware() (bool, string) {
	defer {
		if !$res(0) {
			app.response.status_code = 401
			app.response.body = 'Unauthorized'
		} else {
			app.user = $res(1)
		}
	}
	header := app.get_header('Authorization')
	if header == '' {
		return false, ''
	}
	return true, 'TestUser'
}

defer in loop scopes:

Defer can be used inside loops too, and the deferred statement will be executed once for each
iteration. You can also have multiple defer statements in the same scope, in which case, they
will be executed in reverse order of their appearance in the source code:

fn main() {
	defer { println('Program finish.') }
	println('Loop start.')
	for i in 1 .. 4 {
		defer { println('Deferred execution for ${i}. Defer 1.') }
		defer { println('Deferred execution for ${i}. Defer 2.') }
		defer { println('Deferred execution for ${i}. Defer 3.') }
		println('Loop iteration: ${i}')
	}
	println('Loop done.')
}

The example will print this:

Loop start.
Loop iteration: 1
Deferred execution for 1. Defer 3.
Deferred execution for 1. Defer 2.
Deferred execution for 1. Defer 1.
Loop iteration: 2
Deferred execution for 2. Defer 3.
Deferred execution for 2. Defer 2.
Deferred execution for 2. Defer 1.
Loop iteration: 3
Deferred execution for 3. Defer 3.
Deferred execution for 3. Defer 2.
Deferred execution for 3. Defer 1.
Loop done.
Program finish.

defer(fn) {}

Note, that in most of the examples above, the defer{} statement was directly inside
a function scope, so it was executed when the function itself returned. Sometimes, you
need to defer a statement to execute right at the function end (like the above), even
if you are inside an inner scope (deep inside an if or for).

For these more rare cases, you can use: defer(fn) {} instead of just defer {}.

Recovering from panics

A panic runs the pending defer blocks of every function on the stack, newest
first. Calling recover() directly in one of these blocks stops the panic, and
returns its message. The function that deferred the block then runs its other
deferred blocks, and returns normally, with the zero value of its result type.
This works like recover in Go.

fn parse_age(s string) int {
	defer {
		if msg := recover() {
			eprintln('invalid age ${s}: ${msg}')
		}
	}
	age := s.int()
	if age < 0 {
		panic('negative age')
	}
	return age
}

fn main() {
	println(parse_age('42')) // 42
	println(parse_age('-1')) // 0, after printing `invalid age -1: negative age`
}

recover() returns none when there is no panic, and when it is not called
directly in a deferred block that runs because of the panic (for example, in a
function that such a block calls). A block can also run cleanup code without
calling recover(): the panic then goes on to the callers, and if nothing
recovers it, the program prints the message and exits once all deferred blocks
ran. Runtime errors that panic, like an array index out of range, can be
recovered as well. Signals, like a segmentation fault, cannot.

Goto Copy Section

V allows unconditionally jumping to a label with goto. The label name must be contained
within the same function as the goto statement. A program may goto a label outside
or deeper than the current scope. goto allows jumping past variable initialization or
jumping back to code that accesses memory that has already been freed, so it requires
unsafe.

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

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

Structs Copy Chapter

Concrete struct names can be a single capital letter, such as M. Functions can return these
structs directly, as results (!M), or as options (?M).

struct Point {
	x int
	y int
}

mut p := Point{
	x: 10
	y: 20
}
println(p.x) // Struct fields are accessed using a dot
// Alternative positional syntax; values follow the field declaration order.
p = Point{10, 20}
assert p.x == 10

Struct fields can re-use reserved keywords:

struct Employee {
	type string
	name string
}

employee := Employee{
	type: 'FTE'
	name: 'John Doe'
}
println(employee.type)

Heap structs Copy Section

Structs are allocated on the stack. To allocate a struct on the heap
and get a reference to it, use the & prefix:

struct Point {
	x int
	y int
}

p := &Point{10, 10}
// References have the same syntax for accessing fields
println(p.x)

The type of p is &Point. It's a reference to Point.
References are similar to Go pointers and C++ references.

struct Foo {
mut:
	x int
}

fa := Foo{1}
mut a := fa
a.x = 2
assert fa.x == 1
assert a.x == 2

// fb := Foo{ 1 }
// mut b := &fb  // error: `fb` is immutable, cannot have a mutable reference to it
// b.x = 2

mut fc := Foo{1}
mut c := &fc
c.x = 2
assert fc.x == 2
assert c.x == 2
println(fc) // Foo{ x: 2 }
println(c) // &Foo{ x: 2 } // Note `&` prefixed.

see also Stack and Heap

Default field values Copy Section

struct Foo {
	n   int    // n is 0 by default
	s   string // s is '' by default
	a   []int  // a is `[]int{}` by default
	pos int = -1 // custom default value
}

All struct fields are zeroed by default during the creation of the struct.
Array and map fields are allocated.
In case of reference value, see here.

It's also possible to define custom default values.

Required fields Copy Section

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 Copy Section

Here "short" means omitting the field names and relying on the struct field
order, so Point{10, 20} is a shorter form of Point{x: 10, y: 20}.

For imported struct types, both forms report an unknown type using its qualified name
and the same suggestions. Dots in field values do not affect which type name is highlighted.

struct Point {
	x int
	y int
}

long_form := Point{
	x: 30
	y: 4
}
short_form := Point{30, 4}
assert short_form == long_form

// Arrays still use `Point{...}` for each element.
// The short part is omitting field names, not the struct type name.
points := [Point{10, 20}, Point{20, 30}, Point{40, 50}]
println(points) // [Point{x: 10, y: 20}, Point{x: 20, y: 30}, Point{x: 40,y: 50}]

When the expected type is already known, V can also omit the struct name entirely
when returning a struct literal or passing one as a function argument. That is a
separate shorthand from the positional Point{10, 20} syntax above.

Struct update syntax Copy Section

V makes it easy to return a modified version of an object:

struct User {
	name          string
	age           int
	is_registered bool
}

fn register(u User) User {
	return User{
		...u
		is_registered: true
	}
}

mut user := User{
	name: 'abc'
	age:  23
}
user = register(user)
println(user)

Trailing struct literal arguments Copy Section

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

@[params]
struct ButtonConfig {
	text        string
	is_disabled bool
	width       int = 70
	height      int = 20
}

struct Button {
	text   string
	width  int
	height int
}

fn new_button(c ButtonConfig) &Button {
	return &Button{
		width:  c.width
		height: c.height
		text:   c.text
	}
}

button := new_button(text: 'Click me', width: 100)
// the height is unset, so it's the default value
assert button.height == 20

As you can see, both the struct name and braces can be omitted, instead of:

new_button(ButtonConfig{text:'Click me', width:100})

This only works for functions that take a struct for the last argument.

[!NOTE]
Note the [params] tag is used to tell V, that the trailing struct parameter
can be omitted entirely, so that you can write button := new_button().
Without it, you have to specify at least one of the field names, even if it
has its default value, otherwise the compiler will produce this error message,
when you call the function with no parameters:
error: expected 1 arguments, but got 0.

Access modifiers Copy Section

Struct fields are private and immutable by default (making structs immutable as well).
Their access modifiers can be changed with
pub and mut. In total, there are 5 possible options:

struct Foo {
	a int // private immutable (default)
mut:
	b int // private mutable
	c int // (you can list multiple fields with the same access modifier)
pub:
	d int // public immutable (readonly)
pub mut:
	e int // public, but mutable only in parent module
__global:
	// (not recommended to use, that's why the 'global' keyword starts with __)
	f int // public and mutable both inside and outside parent module
}

Access modifiers can also be written before individual fields to preserve their declaration order:

struct Record {
	a         int
	mut     b int
	pub     c int
	pub mut d int
}

An inline pub, mut, or pub mut applies only to that field (or comma-separated field group).
It overrides the current section for that declaration; following fields still use the section's
modifiers. Without a section, following fields remain private and immutable.
v fmt preserves inline modifiers and aligns their field types.

Private fields are available only inside the same module, any attempt
to directly access them from another module will cause an error during compilation.
Public immutable fields are readonly everywhere.
A public function can return a value of a private struct type. The caller can read its public
fields without naming the private type; its private fields remain inaccessible.

Anonymous structs Copy Section

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

struct Book {
	author struct {
		name string
		age  int
	}

	title string
}

book := Book{
	author: struct {
		name: 'Samantha Black'
		age:  24
	}
}
assert book.author.name == 'Samantha Black'
assert book.author.age == 24

Static type methods Copy Section

V now supports static type methods like User.new(). These are defined on a struct via
fn [Type name].[function name] and allow to organize all functions related to a struct:

struct User {}

fn User.new() User {
	return User{}
}

user := User.new()

This is an alternative to factory functions like fn new_user() User {} and should be used
instead.

Static type methods can also be used as function values by omitting the call parentheses,
such as make_user := User.new. A field selector rooted in a local variable, constant, or
global reads that value's field; it does not name a static type method.

A static type method and an instance method can share a name. User.draw(...) calls the
static method, while user.draw(...) calls the instance method. Each method has its own
visibility: a pub fn User.draw(...) is accessible from other modules as
module_name.User.draw(...), even when the instance method draw is private.

Instance methods can also be used as unbound function values, such as f := User.register.
The receiver becomes the first parameter, so a mutable receiver is passed as f(mut user).
Inside a method reflection loop, T.$method likewise creates an unbound function value.
Unbound and reflected method values follow the same method privacy and mut argument rules.

[!NOTE]
Note, that these are not constructors, but simple functions. V doesn't have constructors or
classes.

`[noinit]` structs Copy Section

V supports [noinit] structs, which are structs that cannot be initialised outside the module
they are defined in. They are either meant to be used internally or they can be used externally
through factory functions.

The restriction applies to empty literals and literals with explicit fields, including aliases
and concrete generic instances of the struct.

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

module sample

@[noinit]
pub struct Information {
pub:
	data string
}

pub fn new_information(data string) !Information {
	if data.len == 0 || data.len > 100 {
		return error('data must be between 1 and 100 characters')
	}
	return Information{
		data: data
	}
}

Note that new_information is a factory function. Now when we want to use this struct
outside the module:

import sample

fn main() {
	// This doesn't work when the [noinit] attribute is present:
	// info := sample.Information{
	// 	data: 'Sample information.'
	// }

	// Use this instead:
	info := sample.new_information('Sample information.')!

	println(info)
}

Methods Copy Section

struct User {
	age int
}

fn (u User) can_register() bool {
	return u.age > 16
}

user := User{
	age: 10
}
println(user.can_register()) // "false"
user2 := User{
	age: 20
}
println(user2.can_register()) // "true"

V doesn't have classes, but you can define methods on types.
A method is a function with a special receiver argument.
The receiver appears in its own argument list between the fn keyword and the method name.
Methods must be in the same module as the receiver type.
This also applies to receivers with any number of pointer levels
and to types imported under another name.
To add methods for an imported type, declare a local type alias and use it as the receiver.
For a generic receiver such as other.Box[T], the alias must also declare its type parameters:
type LocalBox[T] = other.Box[T]. Use LocalBox[T] as the receiver and repeat T in the method's
generic parameter list.

In this example, the can_register method has a receiver of type User named u.
The convention is not to use receiver names like self or this,
but a short, preferably one letter long, name.

Embedded structs Copy Section

Promoted fields from different nested embeds can be initialized together. Their shared parent
is initialized once, retaining the explicitly supplied fields and defaults for omitted fields.

V supports embedded structs.

struct Size {
mut:
	width  int
	height int
}

fn (s &Size) area() int {
	return s.width * s.height
}

struct Button {
	Size
	title string
}

With embedding, the struct Button will automatically get all the fields and methods from
the struct Size, which allows you to do:

mut button := Button{
	title:  'Click me'
	height: 2
}

button.width = 3
assert button.area() == 6
assert button.Size.area() == 6
print(button)

output :

Button{
    Size: Size{
        width: 3
        height: 2
    }
    title: 'Click me'
}

Unlike inheritance, you cannot type cast between structs and embedded structs
(the embedding struct can also have its own fields, and it can also embed multiple structs).

If you need to access embedded structs directly, use an explicit reference like button.Size.

Optional fields keep their optional type when accessed through multiple embedded structs.
You can unwrap them with an if guard, including after an earlier check against none.

Omitted embedded structs retain their declared field defaults, including interface values.

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

You can also initialize an embedded struct:

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

or assign values:

button.Size = Size{
	width:  4
	height: 5
}

If multiple embedded structs have methods or fields with the same name, or if methods or fields
with the same name are defined in the struct, you can call methods or assign to variables in
the embedded struct like button.Size.area().
When you do not specify the embedded struct name, the method of the outermost struct will be
targeted.

Unions Copy Chapter

A union is a special type of struct that allows storing different data types in the same memory
location. You can define a union with many members, but only one member may contain a valid value
at any time, depending on the data types of the members. Unions provide an efficient way of using
the same memory location for multiple purposes.

All the members of a union share the same memory location. This means that modifying one member
automatically modifies all the rest. The largest union member defines the size of the union.
When constructing a union that contains interface storage, V clears the entire storage before
initializing the selected member. This also applies to interfaces inside nested union members.
An inactive interface member with no valid type tag formats as unknown interface value.
Accessing an inactive member still requires unsafe and does not create a valid interface value.

Why use unions? Copy Section

One reason, as stated above, is to use less memory for storing things. Since the size of a union
is the size of the largest field in it, and the size of a struct is the size of all the fields in
the struct added together, a union is definitely better for lower memory usage. As long as you
only need one of the fields to be valid at any time, the union wins.

Another reason is to allow easier access to parts of a field. For example, without using a union,
if you want to look at each of the bytes of a 32-bit integer separately, you'll need bitwise
RIGHT-SHIFTs and AND operations. With a union, you can access the individual bytes directly.

union ThirtyTwo {
	a u32
	b [4]u8
}

Since ThirtyTwo.a and ThirtyTwo.b share the same memory locations, you can directly access
each byte of a by referencing b[byte_offset].

Embedding Copy Section

Unions also support embedding, the same as structs.

struct Rgba32_Component {
	r u8
	g u8
	b u8
	a u8
}

union Rgba32 {
	Rgba32_Component
	value u32
}

clr1 := Rgba32{
	value: 0x008811FF
}

clr2 := Rgba32{
	Rgba32_Component: Rgba32_Component{
		a: 128
	}
}

sz := sizeof(Rgba32)
unsafe {
	println('Size: ${sz}B,clr1.b: ${clr1.b},clr2.b: ${clr2.b}')
}

Output: Size: 4B, clr1.b: 136, clr2.b: 0

Union member access must be performed in an unsafe block.

[!NOTE]
Embedded struct arguments are not necessarily stored in the order listed.

Functions 2 Copy Chapter

Immutable function args by default Copy Section

In V function arguments are immutable by default, and mutable args have to be
marked on call.

Since there are also no globals, that means that the return values of the functions,
are a function of their arguments only, and their evaluation has no side effects
(unless the function uses I/O).

Function arguments are immutable by default, even when references are passed.
An array returned from an immutable argument remains immutable, including when returned through
a local function value, a narrowed if or match branch, or after an exiting if guard.
Use .clone() for a mutable copy.

A pointer returned through a callback can still refer to an immutable argument, even if the
callback returns voidptr. Converting that result to a typed reference does not make the
underlying object mutable. Different pointee types do not prove separate storage: a voidptr
can erase the type of an existing reference. For an opaque container lookup that guarantees
separate mutable component storage, place the conversion in unsafe { ... }. The caller must
ensure the returned pointer does not provide mutable access to an immutable argument.

When a readable function returns a stored pointer to separate storage, or newly allocated storage
that contains no references or other shared storage from its arguments, the returned reference does
not borrow the containing object or the function's other arguments. A new outer object can still
borrow an argument through a reference-bearing field, such as &Box{item: item}.

A scalar passed by value to a callback is independent of the caller's storage. If a callback
parameter is a reference, an implicitly referenced scalar remains borrowed from its immutable
argument; the scalar's expression type alone does not establish a by-value copy.
Scalar fields supplied with collapsed struct argument syntax and scalar elements decomposed
into by-value parameters are copied too. Pointer fields and elements can still share storage.

[!NOTE]
However, V is not a purely functional language.

There is a compiler flag to enable global variables (-enable-globals), but this is
intended for low-level applications like kernels and drivers.

Mutable arguments Copy Section

It is possible to modify function arguments by declaring them with the keyword mut:

A method with a mut receiver requires a mutable value receiver even when it only
changes private fields in another module. An immutable value parameter cannot call
such a method: mutations would affect its copy and be lost when the function returns.
Declare the parameter or receiver with mut when its changes must reach the caller.

An explicit mut param &T takes mutable pointer storage. Passing mut &value
creates temporary pointer storage for that call, including when value is a
mut value T parameter. Changes to fields reach value; rebinding the temporary
pointer does not rebind the caller's value.

struct User {
	name string
mut:
	is_registered bool
}

fn (mut u User) register() {
	u.is_registered = true
}

mut user := User{}
println(user.is_registered) // "false"
user.register()
println(user.is_registered) // "true"

In this example, the receiver (which is just the first argument) is explicitly marked as mutable,
so register() can change the user object. The same works with non-receiver arguments:

fn multiply_by_2(mut arr []int) {
	for i in 0 .. arr.len {
		arr[i] *= 2
	}
}

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

Note that you have to add mut before nums when calling this function. This makes
it clear that the function being called will modify the value.

A comptime app.$method(...) call also requires mut when passing a pointer variable
to an explicit mut param &T parameter.

It is preferable to return values instead of modifying arguments,
e.g. user = register(user) (or user.register()) instead of register(mut user).
Modifying arguments should only be done in performance-critical parts of your application
to reduce allocations and copying.

For this reason V doesn't allow the modification of arguments with primitive types (e.g. integers).
Only more complex types such as arrays and maps may be modified.

Variable number of arguments Copy Section

V supports functions that receive an arbitrary, variable amounts of arguments, denoted with the
... prefix.
Below, a ...int refers to an arbitrary amount of parameters that will be collected
into an array named a.

Methods on generic structs can also accept these arguments. The receiver type determines
the specialization, and the arguments are collected into the parameter array.
The element type keeps its declaring module when the method is called from another module.

fn sum(a ...int) int {
	mut total := 0
	for x in a {
		total += x
	}
	return total
}

println(sum()) // 0
println(sum(1)) // 1
println(sum(2, 3)) // 5
// using array decomposition
a := [2, 3, 4]
println(sum(...a)) // <-- using prefix ... here. output: 9
b := [5, 6, 7]
println(sum(...b)) // output: 18

Anonymous & higher order functions Copy Section

Calling a function parameter or local function variable uses that binding, even when
another module defines a function constant with the same name.

fn sqr(n int) int {
	return n * n
}

fn cube(n int) int {
	return n * n * n
}

fn run(value int, op fn (int) int) int {
	return op(value)
}

fn main() {
	// Functions can be passed to other functions
	println(run(5, sqr)) // "25"
	// Anonymous functions can be declared inside other functions:
	double_fn := fn (n int) int {
		return n + n
	}
	println(run(5, double_fn)) // "10"
	// Functions can be passed around without assigning them to variables:
	res := run(5, fn (n int) int {
		return n + n
	})
	println(res) // "10"
	// You can even have an array/map of functions:
	fns := [sqr, cube]
	println(fns[0](10)) // "100"
	fns_map := {
		'sqr':  sqr
		'cube': cube
	}
	println(fns_map['cube'](2)) // "8"
}

Lambda expressions Copy Section

Lambda expressions in V are small anonymous functions, defined using
the |variables| expression syntax. Note: this syntax is valid only inside calls to higher
order functions.

Here are some examples:

mut a := [1, 2, 3]
a.sort(|x, y| x > y) // sorts the array, defining the comparator with a lambda expression
println(a.map(|x| x * 10)) // prints [30, 20, 10]

// Lambda function can be used as callback
fn f(cb fn (a int) int) int {
	return cb(10)
}

println(f(|x| x + 4)) // prints 14

Function values passed to generic methods are checked by their parameter and return types.
Parameter names and whitespace do not affect function type compatibility.

Closures Copy Section

An instance method can be used as an unbound function value through its type, such as
App.method. Its first parameter is the receiver, including the receiver's & or mut
modifier. This form captures no receiver and creates no closure. The same applies to
T.$method inside a compile-time loop over T.methods.

Callbacks in specialized generic functions retain the functions they call, including imported
functions referenced only from the callback body.

V supports closures too.
This means that anonymous functions can inherit variables from the scope they were created in.
They must do so explicitly by listing all variables that are inherited.

my_int := 1
my_closure := fn [my_int] () {
	println(my_int)
}
my_closure() // prints 1

Inherited variables are copied when the anonymous function is created.
This means that if the original variable is modified after the creation of the function,
the modification won't be reflected in the function.

mut i := 1
func := fn [i] () int {
	return i
}
println(func() == 1) // true
i = 123
println(func() == 1) // still true

However, the captured copy can be modified inside the anonymous function.
mut only makes the closure's copy mutable; it does not capture the original
variable by reference. The change won't be reflected outside, but will be in
later function calls.

This also applies to captured arrays, maps, and structs. For example,
fn [mut files] inside os.walk(...) will modify the closure's files copy,
not the outer files variable.

fn new_counter() fn () int {
	mut i := 0
	return fn [mut i] () int {
		i++
		return i
	}
}

c := new_counter()
println(c()) // 1
println(c()) // 2
println(c()) // 3

A callback's captured values remain available while the callback is stored in a
struct field, including when that field is assigned through a pointer to the struct.

If you need the value to be modified outside the function, use a reference.
Capturing a mut parameter preserves its reference to the caller's value, including when the
closure passes it to a spawned function.

mut i := 0
mut ref := &i
print_counter := fn [ref] () {
	println(*ref)
}

print_counter() // 0
i = 10
print_counter() // 10

For callbacks like os.walk, use os.walk_with_context when the callback
needs to update caller-owned state:

import os

mut files := []string{}
os.walk_with_context('.', &files, fn (mut files []string, file string) {
	files << file
})
println(files.len > 0)

Parameter evaluation order Copy Section

The evaluation order of the parameters of function calls is NOT guaranteed.
Take for example the following program:

fn f(a1 int, a2 int, a3 int) {
	dump(a1 + a2 + a3)
}

fn main() {
	f(dump(100), dump(200), dump(300))
}

V currently does not guarantee that it will print 100, 200, 300 in that order.
The only guarantee is that 600 (from the body of f) will be printed after all of them.

This may change in V 1.0 .

References Copy Chapter

Pointers to concrete values can be passed to optional interface parameters when their types
implement the interface. The option contains an interface value referring to the original object.
Additional pointer layers, such as &&Record, must be dereferenced before passing the object.
Pointers to interface values, such as &Named, must also be dereferenced first.

Returning a stored pointer field returns that pointer value. It does not borrow the storage of
the containing struct, unlike taking the address of one of its fields.

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.

When immutable reference parameters to structs are compared with == or !=,
V compares their addresses, not their fields. Dereference the parameters explicitly
to compare their values instead:

struct Point {
	x int
}

fn same_reference(a &Point, b &Point) bool {
	return a == b
}

fn same_value(a &Point, b &Point) bool {
	return *a == *b
}

a := Point{
	x: 1
}
b := Point{
	x: 1
}
assert !same_reference(a, b)
assert same_reference(a, a)
assert same_value(a, b)

This address-comparison rule also applies when reference parameters are captured by
a closure or their reference types are written through aliases. A user-defined ==
operator takes precedence over the default address or value comparison.

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

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

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

Constants Copy Chapter

A constant can be qualified with its module name inside that module, including in module tests.

A fixed array constant can be initialized by a function call; the call runs during initialization.

const pi = 3.14
const world = '世界'

println(pi)
println(world)

Constants are declared with const. They can only be defined
at the module level (outside of functions).
Global variables can infer their types from constants, including constants initialized by functions.
Global pointers to fixed-array literals are initialized at startup, including nested elements
computed by function calls.

Constant values can never be changed. You can also declare a single
constant separately:

const e = 2.71828

A constant initializer may call a function with the same name, such as const answer = answer().
Reading the constant itself in its initializer is still a cycle.

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

struct Color {
	r int
	g int
	b int
}

fn rgb(r int, g int, b int) Color {
	return Color{
		r: r
		g: g
		b: b
	}
}

const numbers = [1, 2, 3]
const red = Color{
	r: 255
	g: 0
	b: 0
}
// evaluate function call at compile time*
const blue = rgb(0, 0, 255)

println(numbers)
println(red)
println(blue)

* WIP - for now function calls are evaluated at program start-up

Global variables are not normally allowed, so this can be really useful.

Modules

Constants can be made public with pub const:

module mymodule

pub const golden_ratio = 1.61803

fn calc() {
	println(golden_ratio)
}

The pub keyword is only allowed before the const keyword and cannot be used inside
a const ( ) block.

Constants can be referenced without a module prefix from within the module where they are
defined. To access a public constant from another module, prefix it with the module name.

Required module prefix Copy Section

When naming constants, snake_case must be used. Outside the module where a constant is
defined, its full path must be specified. For example, use math.pi to access the public
pi constant from another module. Inside the math module, the unqualified name pi can
be used.

Builtin functions Copy Chapter

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

fn print(s string) // prints anything on stdout
fn println(s string) // prints anything and a newline on stdout

fn eprint(s string) // same as print(), but uses stderr
fn eprintln(s string) // same as println(), but uses stderr

fn exit(code int) // terminates the program with a custom error code
fn panic(s string) // prints a message and backtraces on stderr, and terminates the program with error code 1
fn recover() ?string // stops a panic from a `defer` block, see [Recovering from panics](#recovering-from-panics)
fn print_backtrace() // prints backtraces on stderr

[!NOTE]
Although the print functions take a string, V accepts other printable types too.
See below for details.

There is also a special built-in function called dump.

println Copy Section

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

struct User {
	name string
	age  int
}

println(1) // "1"
println('hi') // "hi"
println([1, 2, 3]) // "[1, 2, 3]"
println(User{ name: 'Bob', age: 20 }) // "User{name:'Bob', age:20}"

See also String interpolation.

Printing custom types Copy Section

Automatic string conversion also works for values whose local name was used for a reference in
an earlier scope.

Recursive sum types print nested values, including repeated types and shared payloads.
An actual circular reference is shown as <circular>.

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)

Note: Calling .str() on an unchanged receiver, or an unchanged alias of it,
inside a custom str() method is not allowed because it causes infinite recursion.
Use string interpolation of the individual fields instead, or for type aliases,
cast to the underlying type first:

struct Color {
	r int
	g int
	b int
}

fn (c Color) str() string {
	return c.str() // error: cannot call `str()` method recursively
}

Dumping expressions at runtime Copy Section

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

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

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

You will get:

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

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

Modules Copy Chapter

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'.
This also applies to scripts with top-level statements that import other modules.

See symbol visibility, Access modifiers.

Create modules Copy Section

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

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

// myfile.v
module mymodule

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

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

// myfile2.v
module mymodule

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

You can now use mymodule in your code:

import mymodule

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

• Module names should be short, under 10 characters.
• Module names must use snake_case.
• Circular imports are not allowed.
• You can have as many .v files in a module as you want.
• You can create modules anywhere under a valid V module lookup root.
• All modules are compiled statically into a single executable.

Reserved keywords can be module names without escaping. For example, type/type.v can declare
module type; another file can use import type and call type.value(). Keywords also work in
longer import paths, such as import type.bar. If a keyword cannot be used as an expression
qualifier, give the import an alias with as.
Module path segments must not start with @.

In normal projects, the nearest v.mod file is that lookup root.
Besides package metadata, v.mod also acts as a relative module anchor:
V prepends the folder containing v.mod to the module lookup path, so
files beside or below it can import sibling modules under the same tree.

To keep module lookup inside a project, place an empty .v.mod.stop file in
its root. When V walks upward from a source file, it searches that directory
but not its parents. The marker also prevents V from selecting a v.mod above
it as the project's root. An explicit -path can still name modules outside
the boundary. v doc follows the same boundary when resolving a module name.

A .git, .hg, or .svn entry also prevents V from selecting a parent
directory's v.mod. These repository markers do not stop the upward module
search, so projects can still import a module checked out beside them.

For example, this layout works:

myapp/
├── v.mod
├── main.v
└── myapp/common/structs.v

main.v can use import myapp.common, and structs.v should still
declare module common.

A module's import path is its path under that lookup root, so the directory
holding a module has to sit at the root itself. There is no virtual modules/
directory anymore: modules/mymod is not searched, the same way the virtual
src/ source root is no longer searched. Move such a directory up beside the
v.mod it belongs to, which leaves every import unchanged:

myapp/
├── v.mod
├── main.v
└── mymod/            # was myapp/modules/mymod

V reports the move for you when an import would otherwise have resolved there.

Module aliases Copy Section

When a module moves, an alias.v file can keep its old import path working without copying its
implementation. The alias module contains only a module declaration with an alias attribute:

@[alias: '@VMODROOT/new_name']
module old_name

The attribute value is the path to the canonical module. Relative paths are resolved from the
alias directory. @VMODROOT is resolved from the v.mod that contains alias.v. An alias also
applies to submodules: if old_name aliases new_name, importing old_name.sub resolves to
new_name.sub. The old and new import paths refer to the same module and use the same types.

Special considerations for project folders Copy Section

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

This is to ease the prototyping workflow in that folder:

• you can start developing some new project with a single .v file
• split functionality as necessary to different .v files in the same folder
• when that makes logical sense to be further organised, put them into their own directory module.

Note that in ordinary modules, all .v files must start with module name_of_folder.

`init` functions Copy Section

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

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

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

`cleanup` functions Copy Section

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

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

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

Type Declarations Copy Chapter

Type aliases Copy Section

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

Methods declared on a fixed-array alias keep that alias receiver, including methods whose names
match builtin array methods.

Numeric aliases use ordinary conversions for initialization:

type Decimal = f64

amount := Decimal(0.0)

Enums Copy Section

Methods on an ordinary enum keep their definitions even when another module declares a
flag enum with the same type name.

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

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

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

println(int(color)) // prints 1

The enum type can be any integer type, but can be omitted, if it is int: enum Color {.
When a struct field expects an enum, its value can use the short .field form, including
inside parentheses in a collapsed struct call argument.

An unqualified enum name or alias in a struct field's default resolves in the struct's module.
An importing module's same-named enum does not change that default, including in fixed arrays.

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

Enum fields can re-use reserved keywords:

The @ escape is also accepted in qualified and shorthand member references, including
comparisons, assignments, struct defaults, match branches, and constant integer expressions.
These references also work with the eval backend, with shorthand on either side of a comparison.
Enum initializers can refer to earlier keyword members, for example next = int(Kind.@struct) + 1.
Exact declarations take precedence: if both none and @none are declared, they retain distinct
values and match coverage.

enum Color {
	none
	red
	green
	blue
}

color := Color.none
println(color)

Integers may be assigned to enum fields.

enum Grocery {
	apple
	orange = 5
	pear
}

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

Output: Grocery IDs: 0, 5, 6.

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

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

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

Enums can have methods, just like structs.

enum Cycle {
	one
	two
	three
}

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

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

Output:

one
two
three
one
two
three
one
two
three
one

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

Enum.from(value) returns a Result. It can be forwarded directly from a function returning
!Enum, preserving the enum value on success and the conversion error on failure.

enum Cycle {
	one
	two = 2
	three
}

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

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

Output:

three
two
one

Function Types Copy Section

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

type Filter = fn (string) string

Function signatures can include fixed-size arrays, pointers to fixed-size arrays, and other
function types. Arrays of explicitly backed enums retain their element type in these signatures.
This also applies to optional and result callback return types.

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

type Filter = fn (string) string

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

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

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

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

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

my_filter := Filter(uppercase)

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

my_filter := uppercase

You can pass the assigned function as an argument:

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

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

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

And this works with anonymous functions as well:

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

You can see the complete
example here.

Interfaces Copy Section

A mutable interface alias can use mut value as OtherInterface when its source is mutable.
A narrowed interface value can be cast for an immediate scalar getter that only reads fields.
Type tests joined by || do not narrow the value in the true branch; they do not require mut
unless a nested condition itself narrows the value.
A negative type guard whose body exits also narrows the value after the guard and requires mut.

Casting a pointer to an interface can be used directly as the receiver of a method returning
multiple values. Interface data fields retain their individual types during the conversion.

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

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

struct Cat {
	breed string
}

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

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

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

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

Implement an interface

A type implements an interface by implementing its methods and fields.
Equivalent fixed array lengths in method signatures may use different constant expressions.
Callback userdata parameters may use voidptr or a concrete pointer type.
An interface field's default value may be a pointer to a type that implements the interface.
Fixed array fields are supported when converting a pointer to an interface with I(value)
or &I(value). Mutable fields continue to refer to the concrete object's fields.

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

// interface-example.2
module main

interface Foo {
	write(string) string
}

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

interface Bar {
mut:
	write(string) string
}

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

struct MyStruct {}

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

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

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

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

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

struct PathError implements IError {
	Error
	path string
}

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

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

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

Casting an interface

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

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

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

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

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

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

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

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

Appending a smart-casted value to an array of its original interface type preserves the
complete interface value. Both animals << animal and animals << Animal(animal) retain
the underlying type and allow interface method calls on the appended element.

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

interface IBar {
	bar()
}

// implements only IFoo
struct SFoo {}

fn (sf SFoo) foo() {}

// implements both IFoo and IBar
struct SFooBar {}

fn (sfb SFooBar) foo() {}

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

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

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

A test against another interface checks the type of the stored value at run time. It compiles
even when no type implements both interfaces; it is then always false. Casting with
a as IBar panics when the stored value does not implement IBar.

For more information, see Dynamic casts.

Interface method definitions

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

An immediate read-only interface method call on a smart-casted value can return
a scalar, including char, rune, isize, usize, or an enum.

Receiver methods are also available through embedded interfaces. A mutable receiver method
updates the underlying concrete object's mutable fields, including when called through an
interface pointer or multiple levels of interface embedding.

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

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

interface Adoptable {}

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

struct Cat {}

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

struct Dog {}

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

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

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

Embedded interface

Interfaces support embedding, just like structs:

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

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

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

An interface value smart cast to a struct refers to the concrete object stored in the interface.
It can be dereferenced to copy the struct or returned through a struct reference.
This applies to single-type match branches as well as if and assert smart casts.
For a value pattern such as item is T, a function returning that struct by value can copy the
smart-casted value directly, including through ?T and !T returns and if/match expressions.
An explicit pointer pattern such as item is &T requires *item to copy the struct by value.

Sum types Copy Section

Mapping an array variant inside a match branch infers the result element type from the mapper.

Assignments to common struct fields also work through sum type array elements, including
compound assignments after filtering or smart casting other elements.

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

struct Moon {}

struct Mars {}

struct Venus {}

type World = Mars | Moon | Venus

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

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

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

// V's binary tree
struct Empty {}

struct Node {
	value f64
	left  Tree
	right Tree
}

type Tree = Empty | Node

// sum up all node values

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

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

Dynamic casts

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

struct Moon {}

struct Mars {}

struct Venus {}

type World = Mars | Moon | Venus

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

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

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

Smart casting

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

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

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

Otherwise w would keep its original type.

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

Smart casts also work on indexed expressions in match branches:

type Entry = int | string

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

Matching sum types

You can also use match to determine the variant:

struct Moon {}

struct Mars {}

struct Venus {}

type World = Mars | Moon | Venus

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

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

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

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

type World = Moon | Mars | Venus

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

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

Named variants

A sum type can also identify its variants by name instead of by type. Each named variant
holds at most one payload, so two variants can carry the same payload type, and a variant
can carry no payload at all:

type Expr = IntLit(int) | Count(int) | Str(string) | Void

fn describe(e Expr) string {
	return match e {
		Expr.IntLit(n) { 'literal ${n}' }
		Expr.Count(n) { 'count ${n}' }
		Expr.Str(s) { 'string ${s}' }
		Expr.Void { 'void' }
	}
}

fn main() {
	e := Expr.Count(3)
	println(describe(e)) // count 3
	println(e) // Expr.Count(3)
	println(e is Expr.Count) // true
	println(e == Expr.IntLit(3)) // false
	println(describe(Expr.Void)) // void
}

A declaration is named as soon as one variant is written as Name(Type). Then every
variant is either Name(Type) or a bare Name without a payload, and its name must be
capitalized and unique in the sum type. The names belong to the sum type: Expr.Void does
not clash with a type called Void or with a Void variant of another sum type.
Declarations without any Name(Type) variant keep their usual meaning, where each variant
is a type.

Values are created with Expr.Count(3) and Expr.Void. A match branch like
Expr.Count(n) binds the payload to n. The binding is an immutable copy of the payload;
to change a value in a match mut branch, assign a new variant to the matched variable.
Payload bindings follow the same redeclaration and global shadowing rules as other local variables.
A branch can list several variants, like Expr.IntLit, Expr.Count {, when it binds no
payload. match must cover every variant or have an else branch, and is/!is checks
work with variants as well: e is Expr.Void. Two values are equal when they hold the same
variant and equal payloads.

Payloads can have any type, including structs, arrays, maps, options and other sum types,
and a payload can refer to its own sum type, like Node([]Tree) in
type Tree = Leaf(int) | Node([]Tree). A payload with several values is written as a
struct: Rect(Size). Generic sum types are supported too, but their values need explicit
type arguments:

type Opt[T] = Some(T) | Nothing

fn main() {
	a := Opt[int].Some(3)
	b := Opt[int].Nothing
	println(a) // Opt[int].Some(3)
	println(b) // Opt[int].Nothing
	println(a is Opt[int].Some) // true
	match a {
		Opt[int].Some(n) { println(n) } // 3
		Opt[int].Nothing {}
	}
}

$for v in Expr.variants iterates the named variants; typeof(v.typ).name gives their
names, like Expr.Count. Types in @[generated] modules can also use named variants
when their type names start with a lowercase letter or underscore.

Option/Result types and error handling Copy Section

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

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

struct User {
	id   int
	name string
}

struct Repo {
	users []User
}

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

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

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

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

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

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

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

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

An Option stores either a value or none. It has no error field and cannot carry an error as
its failure state. A Result stores either a value or an IError.
An IError may still be an ordinary Option payload, for example ?IError.

A function returning only ! or ? has no success payload. Its return type is a Result or
Option of void; callers still handle errors or absence with an or block or propagation.

With the C backend, Options store their payload inline. Wrapping a value or returning none
does not allocate; the payload itself can require allocation, as with arrays or interface values.
Results also store their payload inline, sharing storage between the value and error.
The success flag determines which is valid. An IError references its concrete error object;
msg() and code() dispatch to that object. Creating an error object may allocate.

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

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

A Result's or block and failed if guard bind err to its IError.
Use err.msg() for its message and err.code() for its code.
An Option's or block or failed if guard does not bind err.
Any existing outer variable named err keeps its ordinary meaning in those blocks.
Use or { return none } to propagate absence, or construct an explicit error when converting
absence to a Result failure.

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

Use err is ... to compare errors:

import io

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

A local err declared in a nested block shadows the implicit or error variable, including in
result values.

Options/results when returning multiple values

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

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

Handling options/results

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

import net.http

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

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

The body of f is essentially a condensed version of:

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

The second method is to break from execution early:

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

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

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

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

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

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

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

The fourth method is to use if unwrapping:

import net.http

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

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

Custom error types Copy Section

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

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

struct PathError {
	Error
	path string
}

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

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

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

Generics Copy Section

Cross-module privacy violations that do not depend on type parameters are diagnosed even
in the program's unused generic functions and methods. Accesses that depend on type parameters
are checked in concrete instances.

Generic method calls retain the declaring modules of their type arguments when selecting
the concrete method, including methods returning Result or Option values.

Omitted fields of a generic struct use their declared defaults, including in nested structs.
This also applies through concrete generic aliases and imported structs; defaults use the
imports visible in the declaring file.
Fixed array fields initialize each element with its specialized generic defaults.

Generic types brought into scope by a selective import retain their declaring module when
passed to generic functions and methods in other modules.

Type arguments retain the module where they are declared when used in a generic struct from
another module, including arguments inside arrays, pointers, and maps.

Methods called on a generic factory result retain their dependencies in the compiled program.

Returning a generic struct as a generic interface retains its concrete methods, including when
an interface type argument is itself a generic interface.

struct Repo[T] {
    db DB
}

struct User {
	id   int
	name string
}

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

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

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

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

A generic method retains its receiver type when called inside a function returning multiple
values, including a Result tuple. The enclosing return type does not replace receiver arguments.
This also applies when a value from a Result tuple is returned as an interface.
An explicitly specialized generic method can also be stored as a function value when the
method is promoted from an embedded struct; the value binds that embedded receiver.

Editor hover and definition queries resolve generic type parameters within their declaration.
A later declaration using a module type with the same name resolves to that module type.

Generic calls keep the identity of caller types even when an imported module declares a type
with the same short name.
When an imported generic constructs a caller's struct, omitted fields use that struct's defaults,
including shared fields and fixed arrays. This applies to value and heap literals and
Result returns.
Inside a generic declaration, its type parameters take precedence over same-named concrete
types. A concrete single-letter struct can still be passed as a generic type argument.

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

Receiver inference also works across module imports and aliases. Declared receiver types
are resolved in the module that defines the method, so a caller type with the same name
does not change the inferred type arguments. typeof(call()).name reports the concrete
return type of an inferred generic method call.
Inference also follows receivers obtained by unwrapping an option or propagating a result.

Nested generic calls preserve reference return types when passed directly to another generic
call, including references stored as map values.

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

V can also infer a generic callback's return type from an unbound instance
method passed as an argument, such as item.call(Item.value) when call[T]
accepts a fn (mut Item) T callback.

Generic type inference also works with field initialization shorthand in nested calls.
For struct Box[T] { value T } and fn wrap[U](box Box[U]) Box[U],
wrap(value: 42) infers U as int. The struct and function may use different
parameter names or arrange those parameters in a different order.

Constraints

A type parameter can name, after it, what its type arguments must be: an interface,
which a type argument implements; a sum type, or an alias of one, whose variants are
the types it takes; or a struct, which takes that struct and the structs that embed it.
A call is checked against the constraint where it is written, and in the body a value
of the type parameter has what the constraint provides: the members of the interface
or of the struct, or what every variant of the sum type has, operators included.
Nested generic sums retain the variants of each concrete instance. For example,
Part[int] | Part[string] accepts variants from both instances of Part[T].
Recursive sum constraints that keep growing their type arguments are rejected instead of
silently omitting nested variants. Finite recursive instances and aliases remain valid.
Modules referenced only by a generic constraint still count as used imports.
Struct constraints accept finite embedding paths without a depth limit.

interface Named {
	name string
}

struct User {
	name string
	age  int
}

fn longest[T Named](a T, b T) T {
	return if a.name.len >= b.name.len { a } else { b }
}

type Number = int | f64

fn half[T Number](x T) T {
	return x / 2
}

fn main() {
	println(longest(User{ name: 'ana' }, User{ name: 'leonor' }).name) // leonor
	println(half(7)) // 3
	println(half(1.5)) // 0.75
}

longest(1, 2) is reported at the call: int does not implement Named. And a body
that used a.age would be reported too, as Named declares no age. In a branch of
$if T is f64 {, T is f64, and in its $else the rest of the set.

Structured generic receiver patterns

Generic methods can constrain their receiver to a structured shape of the
wrapped type, and the checker will bind the inner type parameters from the
concrete receiver.

The most common case is requiring the wrapped type to be a dynamic array:

struct Expect[T] {
	value T
}

fn (e Expect[[]T]) first_or(value T) T {
	if e.value.len == 0 {
		return value
	}
	return e.value[0]
}

fn main() {
	a := Expect[[]int]{
		value: [1, 2, 3]
	}
	println(a.first_or(0)) // 1, T is bound to int

	b := Expect[[]string]{
		value: []string{}
	}
	println(b.first_or('none')) // none, T is bound to string
}

Nested array patterns are matched recursively, so Expect[[][]int] binds
T = []int, and Expect[[]map[string]int] binds T = map[string]int.

Maps work the same way and can bind two parameters at once:

struct Expect[T] {
	value T
}

fn (e Expect[map[K]V]) get_or(key K, value V) V {
	if key in e.value {
		return e.value[key]
	}
	return value
}

fn main() {
	m := Expect[map[string]int]{
		value: {
			'a': 1
		}
	}
	println(m.get_or('a', 0)) // 1   (K = string, V = int)
	println(m.get_or('b', -1)) // -1
}

Expect[map[string]map[string]int] binds K = string and
V = map[string]int.

Rules:

• Expect[[]T] matches dynamic arrays; fixed-size arrays are not matched.
• Expect[map[K]V] matches maps.
• Nested patterns are matched recursively.
• Plain generic receivers like Expect[T] continue to work, and an exact
  concrete receiver method (for example fn (e Expect[[]int]) ...) keeps
  precedence over a structured pattern.
• A repeated placeholder must bind consistently: Expect[map[K]K] on
  Expect[map[string]int] is rejected because K cannot be both string
  and int.
• Raw voidptr is not allowed to bind into these patterns; cast through an
  explicit V type instead.

Concurrency Copy Chapter

Spawning Concurrent Tasks Copy Section

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

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

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

import math

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

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

If a spawned thread's handle is discarded, including inside a discarded array or struct,
V detaches the thread. Keep its handle and call wait() when the result or completion matters.
The detached thread releases an owned return value after its function finishes.
If the return value is a thread handle, it joins that thread; a returned closure releases
its captured context.

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

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

import math

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

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

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

import math { sqrt }

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

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

Discarding a spawned thread's handle, including through dump(spawn ...), detaches the thread.
Keep the handle when you need to call .wait().

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

import time

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

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

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

Additionally for threads that return the same type, calling wait()
on the thread array will return all computed values.
Arrays whose elements are aliases of thread handles support wait() as well,
including aliases of thread and thread T.
The elements must be handles themselves; arrays of pointers to handles cannot be joined.

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

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

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

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

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

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

Channels Copy Section

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

Syntax and Usage

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

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

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

import time

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

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

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

Buffered Channels

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

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

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

Closing Channels

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

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

// propagate error
y := <-ch2 ?

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

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

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

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

ich.close()

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

... will produce:

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

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

Channel Select

Assertion messages inside a select branch can use values declared or received in that branch,
including arrays and structs converted to strings.

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

import time

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

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

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

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

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

Special Channel Features

For special purposes there are some builtin fields and methods:

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

struct Abc {
	x int
}

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

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

Shared Objects Copy Section

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

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

Example of Shared Objects

struct Counter {
mut:
	value int
}

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

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

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

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

Thread-safe maps

A single operation on a shared map does not need a lock/rlock block: it locks
the map by itself, for the duration of that one operation. So a shared map can be used
as a thread-safe map:

import sync

fn count(shared words map[string]int, text string, mut wg sync.WaitGroup) {
	for word in text.split(' ') {
		words[word]++ // locks `words` while it is updated
	}
	wg.done()
}

fn main() {
	shared words := map[string]int{}
	mut wg := sync.new_waitgroup()
	wg.add(2)
	spawn count(shared words, 'a b a', mut wg)
	spawn count(shared words, 'b c', mut wg)
	wg.wait()
	println(words['a']) // 2, read with an `rlock`
	println('c' in words) // true
	println(words.len) // 3
}

Statements that change the map (m[k] = v, m[k] += v, m[k]++, m[k] << v,
m.delete(k) and m.clear()) take a lock. The whole statement runs with the map
locked, so m[k] = m[k] * 2 is atomic too. Reads (m[k], m[k] or { ... }, k in m,
m.len, m.keys(), m.values() and m.clone()) take an rlock. This works for
shared variables, parameters, globals and struct fields.

Operations that must happen together still need an explicit block, and so do iterating
over the map, if v := m[k] { and statements that use two shared maps:

shared m := map[string]int{}
// check and insert in one step
lock m {
	if 'a' !in m {
		m['a'] = 0
	}
}
rlock m {
	for k, v in m {
		println('${k}: ${v}')
	}
}

Difference Between Channels and Shared Objects Copy Section

Purpose:

• Channels: Used for message passing between threads, ensuring safe communication.
• Shared objects: Used for direct data sharing and modification between threads.

Synchronization:

• Channels: Implicit (via channel operations)
• Shared objects: Explicit (via rlock/lock blocks)

Race Detector Copy Section

A data race happens when two threads access the same memory at the same time, and at least
one of the accesses is a write, without a channel, a lock/rlock block, a sync primitive
or an atomic operation ordering them. Data races are hard to find: they depend on timing, and
the program usually works until it does not.

Like Go, V has a race detector built in. Build or run a program, or its tests, with -race:

v -race run main.v
v -race test .

Consider this program, where two threads increment one counter without synchronization:

struct Counter {
mut:
	n int
}

fn inc(mut c Counter) {
	for _ in 0 .. 1000 {
		c.n++
	}
}

fn main() {
	mut c := &Counter{}
	t1 := spawn inc(mut c)
	t2 := spawn inc(mut c)
	t1.wait()
	t2.wait()
	println(c.n)
}

v -race run main.v reports the race with the V source positions of both accesses, of the
allocation, and of the spawn calls that started the threads:

==================
WARNING: ThreadSanitizer: data race (pid=55780)
  Write of size 8 at 0x000109800380 by thread T2:
    #0 inc main.v:8
    #1 inc_args_thread_wrapper src.c:2438

  Previous write of size 8 at 0x000109800380 by thread T1:
    #0 inc main.v:8
    #1 inc_args_thread_wrapper src.c:2438

  Location is heap block of size 8 at 0x000109800380 allocated by main thread:
    #0 malloc <null>
    #1 v_malloc allocation.c.v:96
    #2 memdup allocation.c.v:503
    #3 main main.v:13

  Thread T2 (tid=19154470, running) created by main thread at:
    #0 pthread_create <null>
    #1 __v_thread_spawn src.c:672
    #2 main main.v:15
  ...
SUMMARY: ThreadSanitizer: data race main.v:8 in inc
==================
2000
ThreadSanitizer: reported 1 warnings

Making n an atomic int, putting it in a shared object, or guarding it with a
sync.Mutex removes the race.

The race detector finds the races that happen while the program runs; it cannot find races
in code that does not run. So it is most useful with tests and realistic workloads. A program
that reported races exits with status 66, so a test that races fails.

How it works: -race compiles the program with ThreadSanitizer (-fsanitize=thread), the
race detection runtime that Go's race detector uses too. Like Go's runtime, V's channels,
sync types and closure allocator tell it the happens-before relations that the language
guarantees, instead of those of their implementation. V passes the race detector test suite
of Go (vlib/v/slow_tests/race). -race needs clang or gcc with the ThreadSanitizer
runtime (on some Linux distributions, the libtsan package for gcc), and uses clang when it
is installed: gcc does not instrument copies of whole struct values, like strings and arrays
passed to functions, so it misses races on them. It is supported on linux (amd64, arm64,
ppc64le, s390x, loongarch64, riscv64), macos (amd64, arm64), freebsd/amd64 and netbsd/amd64.
Race builds:

• do not use a garbage collector, like -gc none, and cannot use -prealloc:
  ThreadSanitizer has to see every allocation and free of heap memory, which a garbage
  collector or an arena allocator hides from it;
• typically run 2-20x slower and use 5-10x more memory, like in Go (with -prod, a function
  that was inlined into its caller is reported as the caller);
• define race, so code can check for them with $if race ? {}, and _d_race.v files are
  compiled in them. That define is reserved: -d race without -race is an error.

The VRACE environment variable passes options to the race detector, in the same format as
Go's GORACE. For example, VRACE="halt_on_error=1" stops the program at the first race,
VRACE="log_path=/tmp/race" writes the reports to /tmp/race. instead of stderr, and
VRACE="exitcode=1" changes the exit status. TSAN_OPTIONS takes the same options, and
overrides VRACE.

On some Linux kernels, older ThreadSanitizer runtimes stop with
FATAL: ThreadSanitizer: unexpected memory mapping. Run the program with address space
randomization reduced (setarch $(uname -m) -R ./program, or
sudo sysctl vm.mmap_rnd_bits=28), or use a newer compiler.

JSON Copy Chapter

Because of the ubiquitous nature of JSON, V provides the pure V json2 module for encoding and
decoding. It uses compile-time reflection instead of runtime reflection.

Decoding JSON Copy Section

import json2

struct Foo {
	x int
}

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

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

The json2.decode function takes the target type as a generic type argument and the JSON data as
a string argument.

Encoding JSON Copy Section

import json2

struct User {
	name  string
	score i64
}

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

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

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

The json2 module also supports anonymous struct fields, which helps with complex JSON APIs with
many levels.

Protocol Buffers Copy Chapter

V ships encoding.protobuf, the Protocol Buffers binary wire format in pure V. It has no C
dependency and needs no protoc at build time.

The usual way in is the v pbgen tool, which reads a .proto file and writes the message
structs, their codecs, and the gRPC service declarations:

v pbgen -m kv -o kv/codec.v kv.proto

pub struct GetRequest {
pub mut:
	// key is `string key = 1`.
	key string
}

pub fn (msg GetRequest) encode() ![]u8 {
	return msg.encode_with(protobuf.EncodeOpts{})
}

pub fn decode_get_request(data []u8) !GetRequest {
	return decode_get_request_with(data, protobuf.DecodeOpts{})
}

Only proto3 is supported. v help pbgen documents the options, and
vlib/encoding/protobuf/README.md documents the runtime, the type mapping, and the shape of
the generated code.

Testing Copy Chapter

Asserts Copy Section

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

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

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

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

Asserts with an extra message Copy Section

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

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

Asserts that do not abort your program Copy Section

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

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

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

... will produce this output:

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

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

Test files Copy Section

// hello.v
module main

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

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

// hello_test.v
module main

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

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

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

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

If a test function has an error return type, any propagated errors will fail the test:

import strconv

fn test_atoi() ! {
	assert strconv.atoi('1')! == 1
	assert strconv.atoi('one')! == 1 // test will fail
}

Running tests Copy Section

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

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

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

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

import os

fn test_subtest() {
	res := os.exec([@VEXE, 'other_test.v'])
	assert res.exit_code == 1
	assert res.output.contains('other_test.v does not exist')
}

Memory management Copy Chapter

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

There are 4 ways to manage memory in V.

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

With Boehm GC, -d no_gc_thread_local_alloc builds the bundled collector without thread-local
allocation, so allocation counters also observe warmed small-object allocations. It uses the
platform C compiler unless -cc selects one explicitly. This option preserves compiler selection
when GC is disabled or -d dynamic_boehm is enabled; an empty define value does not enable a flag.

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

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

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

For scoped arenas, use the arena module: while an arena is pushed on a thread, all V
allocations on that thread (strings, arrays, maps, ...) come from it, and they are released
together by reset() or free(). This keeps memory bounded in long-running, multi-threaded
programs built with -gc none. It also works with the default GC, but not with -prealloc.

import arena

mut a := arena.new()
mut results := []string{}
for i in 0 .. 3 {
	a.push()
	s := 'iteration ${i}: ' + 'x'.repeat(i)
	a.pop()
	results << s.clone() // copy the value out of the arena
	a.reset() // reuse the arena memory in the next iteration
}
a.free()
println(results)

Control Copy Section

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

struct MyType {}

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

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

Autofree can be enabled with an -autofree flag.

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

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

Examples

import strings

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

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

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

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

struct User {
	name string
}

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

Stack and Heap Copy Section

Stack and Heap Basics

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

• The stack allows fast allocations with almost zero administrative overhead. The
  stack grows and shrinks with the function call depth – so every called
  function has its stack segment that remains valid until the function returns.
  No freeing is necessary, however, this also means that a reference to a stack
  object becomes invalid on function return. Furthermore stack space is
  limited (typically to a few Megabytes per thread).
• The heap is a large memory area (typically some Gigabytes) that is administrated
  by the operating system. Heap objects are allocated and freed by special function
  calls that delegate the administrative tasks to the OS. This means that they can
  remain valid across several function calls, however, the administration is
  expensive.

V's default approach

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

struct MyStruct {
	n int
}

struct RefStruct {
	r &MyStruct
}

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

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

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

Heap allocation preserves value reads in declaration initializers. An initializer reads
the bindings that are visible before the new declaration is installed.
Leaving a nested scope restores the storage and type metadata of outer heap-backed bindings.

Moving a local to the heap preserves its source-level type. For example, typeof(c).name
still reports MyStruct; the pointer used to store the local does not change type reflection.

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

struct MyStruct {
mut:
	n int
}

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

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

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

Manual Control for Stack and Heap

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

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

struct RefStruct {
mut:
	r &MyStruct
}

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

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

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

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

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

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

Type aliases of a heap struct retain its allocation behavior. Returning such a value as
Alias, ?Alias, or !Alias preserves the struct value, including when a defer runs.

There is a pattern often seen in other programming languages:

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

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

In V the better approach is:

struct MyStruct {
mut:
	n int
}

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

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

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

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

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

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

struct MyStruct {
	n int
}

struct RefStruct {
mut:
	r &MyStruct
}

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

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

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

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

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

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

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

ORM Copy Chapter

(This is still in an alpha state)

Deprecation notice: the Function Call API (orm_fn;
orm.new_query[T] / QueryBuilder) is deprecated and will be removed
from the standard library after 2027-08-17, to be maintained in a
separate repository. Prefer the built-in sql ORM syntax shown below
for new code. Compiler deprecation warnings begin on 2027-02-18;
until then the compiler emits a migration notice. See
https://github.com/vlang/v/issues/27001 for details.

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

V's ORM provides a number of benefits:

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

/* Detailed source-code truncated for AI context efficiency. */

For more examples and the docs, see vlib/orm.

Troubleshooting compilation problems with SQLite Copy Section

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

v vlib/db/sqlite/install_thirdparty_sqlite.vsh

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

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

• Debian/Ubuntu: sudo apt install -y libsqlite3-dev
• Fedora/RHEL: sudo dnf -y install sqlite-devel
• Arch: sudo pacman -S sqlite

Interactive SQLite CLI Copy Section

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

v sqlite mydb.db

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

Convenience Methods Copy Section