Chapter 1 Getting Started with V

This chapter introduces the core design philosophies of V. You will learn how to set up your development environment, compile and run programs, and document your code using comments.

+----------------+      +-------------+      +-------------------+      +--------------------+      +---------------+
|   .v Source    | ---> | Single-Pass | ---> | Static Safety &   | ---> | C99 Emission or    | ---> | Native Binary |
|   Files        |      | Parser/AST  |      | Type Verification |      | Direct x64/ARM/Wasm|      | (< 1MB size)  |
+----------------+      +-------------+      +-------------------+      +--------------------+      +---------------+

Code Comments

Single Line Comments

In plain words: A single-line comment starts with //. Everything after // on that line is a note for humans and is completely ignored by the computer.

Comments are non-executable lines of text in a program that explain what the code does. They are ignored by the compiler but are essential for human developers. This lesson on Single Line Comments demonstrates how to write and format comments in V.

module main

// greet function prints greetings to the console
pub fn greet() {
	println('Hello, Welcome to the Jungle!')
}

fn main() {
	greet()
}

Multi Line Comments

In plain words: A multi-line comment starts with /* and ends with */. Use it when your note spans several lines—and in V, you can even nest one /* ... */ inside another!

In V, multi-line (or block) comments are enclosed between /* and */.

module main

/*
multiply is a function that accepts two integer arguments (x and y).
It performs multiplication and returns the integer product.

Note: Comments formatted like this (/* ... */) do not show in code hints
using v-analyzer or `v doc`. You must use `//` for each line to enable IDE hints.

/*
Note: In V, block comments can be nested.
This is a nested block comment. In standard C, nesting block comments
would cause a compile error, but V's compiler parses them correctly.
*/
This is the end of the outer block comment.
*/
fn multiply(x int, y int) int {
	return x * y
}

fn main() {
	println(multiply(4, 5))
}

Programm Commented All Places

In plain words: You can place comments almost anywhere in a V file—above functions, at the end of a line of code, or even right in the middle of an expression—to explain what is happening.

Comments are non-executable lines of text in a program that explain what the code does. They are ignored by the compiler but are essential for human developers. This lesson on Programm Commented All Places demonstrates how to write and format comments in V.

module main

// Space3D A struct indicating the 3 dimensional coordinate system
struct Space3D {
mut:
	x int
	// x is an integer field that represents coordinate
	y int
	// y is an integer field that represents coordinate
	z int
	// z is an integer field that represents coordinate
}

/*
get_point is a function that returns a struct of Type Space3D with points x,y,z passed as input arguments to it
x is an input argument accepts values of type of int
y is an input argument accepts values of type of int
z is an input argument accepts values of type of int
get_point function returns a Struct result of type Space3D with its coordinates set as value passed as input arguments x, y and z
*/
fn get_point(x int, y int, z int) Space3D {
	return Space3D{
		x: x
		y: y
		z: z
	}
}

const origin = get_point(0, 0, 0)

// Defining origin as a constant
fn main() {
	// origin := Space3D {x: 0, y: 0, z:0}
	println(origin)
}

Chapter 2 Variables and Constants

Variables are the basic storage units of any program. In this chapter, we explore how V handles variables with a safety-first mindset: variables are immutable by default, variable shadowing is forbidden, and constants are declared in module scopes. You will learn to manage program data safely and cleanly.

Stack Frame:
+-------------------------------+-----------------------------------+
|  const int x = 10 (Immutable) |  int y = 20 (Mutable Stack Slot)  |
+-------------------------------+-----------------------------------+

// FORBIDDEN IN V:
fn example() {
    count := 10
    if true {
        count := 20 // Compile Error: duplicate variable name `count`
    }
}

Constants

Define Single Constant

In plain words: A constant (const) is a permanent, unchanging value given a name at the top of your file (like const app_name = 'V on Wheels').

Constants in V are defined using the const block. Constants are values that are known at compile time and never change throughout the execution of the program. By convention, constant names are written in lowercase, unlike many other languages.

This example shows how to define and use a single constant.

const app_name = 'V on Wheels'

fn main() {
	println(app_name)
}

Define Multiple Constants

In plain words: When you have several permanent values (like app settings, colors, or limits), you can group them all cleanly inside one const ( ... ) block.

You can define multiple constants within a single const block. This keeps related constants grouped together and makes the code cleaner.

This example shows how to declare multiple constants (integers, strings, floats) together.

const app_name = 'V on Wheels'
const max_connections = 1000
const decimal_places = 2
const pi = 3.14

fn main() {
	println(app_name)
	println(max_connections)
	println(decimal_places)
	println(pi)
}

Define Constant Of Type Struct

In plain words: Constants aren't limited to simple numbers or text! You can also store a complete custom struct inside a const block so your whole program can share a fixed configuration object that nobody can accidentally change.

What happens in this example:

• Defines custom data blueprint(s): Space3D.
• Prints the result to the terminal window so you can see the output right away.

module main

struct Space3D {
mut:
	x int
	y int
	z int
}

const origin = Space3D{
	x: 0
	y: 0
	z: 0
}

fn main() {
	println(origin)
}

Define Constant Of Type Function

In plain words: You can even set a constant equal to the result returned by a helper function, or store a function reference as a constant so it stays fixed throughout your program.

What happens in this example:

• Defines custom data blueprint(s): Space3D.
• Creates helper function(s)/method(s): get_point.
• Prints the result to the terminal window so you can see the output right away.

module main

struct Space3D {
mut:
	x int
	y int
	z int
}

fn get_point(x int, y int, z int) Space3D {
	return Space3D{
		x: x
		y: y
		z: z
	}
}

const origin = get_point(0, 0, 0)

fn main() {
	println(origin)
}

Define Module Level Constants

In plain words: In V, constants (const) always live at the top level of a file (outside of fn main() or other functions) so every function in that module can read them cleanly.

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

const app_name = 'V on Wheels'

fn main() {
	println(app_name)
}

Cannot Define Constants Inside Functions

In plain words: V does not allow const inside a function body. Why? Because inside a function, normal variables (x := 10) are already locked (immutable) by default! Use const only at the top of the file.

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

const app_name = 'V on Wheels'

fn main() {
        const greet = 'hi' // this is not top level constant definition, throws error.
        println(app_name)
}

Constants Module - Main (main.v)

In plain words: When your main.v file uses a public constant from another module (like mod1), you write the module's name in front of it (mod1.const_name) so it is always obvious which folder that constant came from.

module main

import mod1

fn main() {
	mod1.do_work()
}

Constant Module Prefix - Helper (file1.v)

In plain words: To let other folders/modules read a constant defined in this helper file, put pub const in front of it. Without pub, the constant stays private to its own folder.

What happens in this example:

• Creates helper function(s)/method(s): do_work.
• Prints the result to the terminal window so you can see the output right away.

module mod1

const greet_count = 5

pub fn do_work() {
	println(greet_count)
}

Variables

Parallel Declaration Immutable Variables

In plain words: You can create and fill two or more locked (immutable) variables on a single line separated by commas, like a, b := 10, 20.

In V, you can declare and initialize multiple variables in a single line. This is known as parallel declaration. By default, variables in V are immutable (read-only). Once assigned a value, they cannot be changed.

This program demonstrates declaring two variables a and b at the same time and assigning them initial values. Any attempt to modify a or b later in the code will cause a compile-time error.

fn main() {
	first_name, last_name, age := 'Ada', 'Lovelace', 36
	println('${first_name} ${last_name} is ${age} years old')
	println('Next milestone: ${first_name} will speak at the conference')
}

Parallel Declaration Mutable Variables

In plain words: This lesson (Parallel Declaration Mutable Variables) shows a clear, runnable V example from variables_and_constants/01_variables/01_variable_assignment/01_parallel_declaration/02_parallel\_\_declaration_mutable_variables.v that you can test directly in your terminal or the V Playground.

If you want to modify parallelly declared variables later, you must explicitly mark them as mutable using the mut keyword. In V, mutability is always explicit to make code safer and easier to reason about.

Here, we declare two mutable variables a and b at the same time using mut. We then reassign their values using the standard assignment operator (=).

fn main() {
	mut greeting, mut recipient := 'Hi', 'world'
	println('${greeting}, ${recipient}!')

	greeting, recipient = 'Hello', 'Ada'
	println('${greeting}, ${recipient}!')
}

Parallel Declaration Mut And Immutable Vars

In plain words: V lets you create several variables on a single line separated by commas. Even better, you can mix changeable (mut) and locked (immutable) variables on the very same line!

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut message, count := 'Hello', 32
	println(message)
	message = 'Hi'
	println(message)
	println(count)
}

Augmented Assignment String

In plain words: Instead of writing text = text + ' more' to tack extra words onto the end of a changeable (mut) string, you can use the shortcut += (add onto the existing value).

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut greeting := 'Hi'
	println(greeting)

	greeting = greeting + ' there'
	println(greeting)

	greeting += ', how are you today?'
	println(greeting)
}

Augmented Assignment Integer

In plain words: When updating a changeable (mut) number, shortcuts like += (add), -= (subtract), *= (multiply), and /= (divide) update the number in place without repeating the variable name twice.

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut score := 10
	println(score)

	score = score + 5
	println(score)

	score += 5
	println(score)
}

Declare Mutable Variable

In plain words: Putting mut in front of a new variable (mut age := 20) unlocks it so you can update its value later with = (age = 21).

By default, all variables in V are immutable (their values cannot change). To declare a variable whose value can be modified later, you must prepend the mut keyword before the variable name.

This example shows how to declare a mutable variable, change its value, and print the results.

fn main() {
	mut counter := 0
	counter += 1
	println(counter)
}

Cannot Update Mutable With Another Type

In plain words: Even when a variable is marked changeable (mut), its type is locked forever. If a box starts out holding a whole number (int), V will stop you from accidentally putting text (string) into that same box later.

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.

fn main() {
	mut i := 10
	i = 100
	i = 'Apple' // throws error
}

Declare Immutable Variable

In plain words: When you create a variable without mut (age := 20), V locks it automatically so no line of code can accidentally overwrite it later.

In V, variables are immutable by default. This design choice prevents accidental state mutation bugs, making code easier to reason about and safer for concurrency. When you declare a variable using the declaration operator :=, you are creating a read-only variable. If you try to reassign this variable later, the compilation will fail. This approach is similar to declaring constants in other languages, but it operates at the local scope level.

This example demonstrates how to declare an immutable variable and print its value.

fn main() {
	// 'msg' is initialized as an immutable string variable using :=
	msg := 'Hello'
	println(msg)
}

Cannot Update Immutable Variables

In plain words: If you try to change a locked variable that wasn't created with mut, the V compiler stops immediately and shows a helpful error message telling you how to fix it.

One of V's core safety features is immutability by default. If you declare a variable without the mut keyword and then try to reassign it a new value, the compiler will refuse to compile the program.

This example demonstrates what happens when you try to update an immutable variable (expect a compiler error).

fn main() {
	msg := 'Hello'
	msg = 'Good Day!' // throws error
}

Declared And Assigned

In plain words: In V, creating a variable and giving it a starting value happen in one single step using :=. There are no 'uninitialized' mystery variables in V!

What happens in this example:

• Code note: declared and assigned

fn main() {
	mut i := 0
	// declared and assigned
	println(i)
}

Declared And Not Assigned

In plain words: In V, you are never allowed to create an empty variable box without putting a starting value in it. Every variable must be created and given a value at the same time using :=.

V does not allow variables to be declared without an initial value. Unlike other languages that initialize variables to a default 'zero' value or null, V forces you to explicitly provide a value. This prevents uninitialized variable bugs.

This example illustrates that declaring a variable without an assignment is a compilation error.

fn main() {
	mut a // throws error
}

Unused Variables Will Be Warned

In plain words: If you create a variable and never use it anywhere, V warns you so your code doesn't get cluttered with forgotten, leftover variables.

To keep codebases clean and efficient, the V compiler detects if you declare a variable but never use (consume) it. By default, V treats unused variables as a compilation warning/error, encouraging you to clean up dead code.

This example shows a declared variable that is never used.

fn main() {
	i := 'hello' // i is not used anywhere, so warns when run in dev mode and throws error when run in prod mode
	x := 3
	y := 2
	println(x + y)
}

Global Variables Not Allowed - Scope Demo

In plain words: Variables created inside fn main() only live inside main(). Other functions cannot secretly reach in and grab them unless you pass them in as function inputs.

V does not allow global variables by default. Global state is a major source of bugs, race conditions in multi-threaded applications, and poor code structure. By forbidding globals, V enforces clean, modular code passing state via arguments.

These examples demonstrate that declaring variables outside of the main function or modules is strictly prohibited.

module main

fn method1() {
	msg := 'Hello from Method1'
	println(msg)
}

fn main() {
	method1()
	println(msg) // Will throw error as msg declared and accessible only in method1
}

Global Variables Not Allowed - File Scope Demo

In plain words: V does not allow loose variables floating at the top of a file outside of functions (use const for fixed values instead). This prevents 'spaghetti code' where any file can unexpectedly change shared data.

V does not allow global variables by default. Global state is a major source of bugs, race conditions in multi-threaded applications, and poor code structure. By forbidding globals, V enforces clean, modular code passing state via arguments.

These examples demonstrate that declaring variables outside of the main function or modules is strictly prohibited.

module main

fn method1() {
	if true {
		mut b := 10
		b++
	}
	println(b)
}

fn main() {
	method1()
}

Variable Redeclaration

In plain words: Once you create a variable with := (like a := 10), you cannot create a second variable with the exact same name in the same block. This prevents accidental copy-paste mistakes.

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

fn main() {
        x := 3
        y := 2
        println(x + y)
        x := 5 // re-definition of variable x is not allowed
}

Variable Scope For Same Variable Names

In plain words: Two different functions are completely separate rooms—so two different functions are allowed to each have their own local variable with the same name (like x) without colliding.

In V, variables are strictly scoped to the function or block in which they are declared. This lexical scoping means that two different functions can declare variables with the exact same name (e.g., msg) without any collision or interference. The compiler guarantees that these variables occupy separate locations in memory and are completely isolated from one another. This allows developers to use common, context-appropriate names like temp, id, or msg locally inside individual functions without worrying about global or cross-functional namespace pollution.

This program illustrates how msg is declared separately in both method1 and method2, showing scope isolation in action.

module main

fn method1() {
	// 'msg' is local only to method1
	msg := 'Hello from Method1'
	println(msg)
}

fn method2() {
	// 'msg' is local only to method2; does not conflict with method1's 'msg'
	msg := 'Hello from Method2'
	println(msg)
}

fn main() {
	method1()
	method2()
}

Variable Shadowing Not Allowed

In plain words: Inside the same function, an inner { ... } block is not allowed to create a brand-new variable with the same name as one outside the block (shadowing), preventing confusing mix-ups.

Variable shadowing happens when a variable declared within an inner scope (like an if block, a loop, or a function body) has the same name as a variable in an outer scope. V strictly forbids variable shadowing at the compiler level. Prohibiting shadowing prevents a class of common bugs where a developer accidentally updates a local inner variable instead of the intended outer variable, or vice versa.

This example demonstrates how V rejects shadowed variable declarations.

module main

fn scope_demo() {
	// 'x' is declared in the function's main scope
	x := 10
	println(x)
	if true {
		// ERROR: Declaring another variable named 'x' in an inner block is forbidden.
		// To fix this, you must name the inner variable something else.
		x := 20 
		println(x)
	}
	println(x)
}

fn main() {
	scope_demo()
}

Chapter 3 Primitive Data Types

Primitive Types Demo

Primitive Types Demo Code

In plain words: A complete tour of V's built-in basic types: Yes/No switches (bool), text (string), single characters (rune), whole numbers (int, i8..i64, u8..u64), and decimals (f32, f64).

This comprehensive example demonstrates every primitive data type in V:

• Boolean: bool (representing true or false).
• String: string (representing an immutable array of bytes).
• Rune: rune (representing a single Unicode code point, alias for u32).
• Signed Integers: i8 (8-bit), i16 (16-bit), int (32-bit), i64 (64-bit).
• Unsigned Integers: u8 (8-bit), u16 (16-bit), u32 (32-bit), u64 (64-bit).
• Platform-dependent sizes: isize (signed size of a pointer), usize (unsigned size of a pointer).
• Floating Point Numbers: f32 (32-bit single-precision), f64 (64-bit double-precision).

For each type, the example initializes a value and prints its value, type (using typeof(var).name), and size in bytes (using sizeof(var)).

module main

fn main() {
	println('==================================================')
	println('        Vlang Primitive Data Types Demo           ')
	println('==================================================')

	// 1. Boolean Type
	b := true
	println('Boolean: val: ${b} | type: ${typeof(b).name} | size: ${sizeof(b)} byte')

	// 2. String Type
	s := 'Hello, V!'
	println('String:  val: "${s}" | type: ${typeof(s).name} | size: ${sizeof(s)} bytes')

	// 3. Rune Type (unicode character, represented as `r` prefix or backticks)
	r := `V`
	println('Rune:    val: ${r} (char: ${r.str()}) | type: ${typeof(r).name} | size: ${sizeof(r)} bytes')

	// 4. Signed Integers
	i_8 := i8(-128)
	i_16 := i16(-32768)
	i_32 := int(-2147483648)
	i_64 := i64(-9223372036854775808)
	println('i8:      val: ${i_8} | type: ${typeof(i_8).name} | size: ${sizeof(i_8)} byte')
	println('i16:     val: ${i_16} | type: ${typeof(i_16).name} | size: ${sizeof(i_16)} bytes')
	println('int:     val: ${i_32} | type: ${typeof(i_32).name} | size: ${sizeof(i_32)} bytes')
	println('i64:     val: ${i_64} | type: ${typeof(i_64).name} | size: ${sizeof(i_64)} bytes')

	// 5. Unsigned Integers
	u_8 := u8(255)
	u_16 := u16(65535)
	u_32 := u32(4294967295)
	u_64 := u64(18446744073709551615)
	println('u8:      val: ${u_8} | type: ${typeof(u_8).name} | size: ${sizeof(u_8)} byte')
	println('u16:     val: ${u_16} | type: ${typeof(u_16).name} | size: ${sizeof(u_16)} bytes')
	println('u32:     val: ${u_32} | type: ${typeof(u_32).name} | size: ${sizeof(u_32)} bytes')
	println('u64:     val: ${u_64} | type: ${typeof(u_64).name} | size: ${sizeof(u_64)} bytes')

	// 6. Platform-dependent Sizes
	isize_val := isize(-12345)
	usize_val := usize(12345)
	println('isize:   val: ${isize_val} | type: ${typeof(isize_val).name} | size: ${sizeof(isize_val)} bytes')
	println('usize:   val: ${usize_val} | type: ${typeof(usize_val).name} | size: ${sizeof(usize_val)} bytes')

	// 7. Floating Point Numbers
	f_32 := f32(3.14159)
	f_64 := f64(2.718281828459)
	println('f32:     val: ${f_32} | type: ${typeof(f_32).name} | size: ${sizeof(f_32)} bytes')
	println('f64:     val: ${f_64} | type: ${typeof(f_64).name} | size: ${sizeof(f_64)} bytes')

	println('==================================================')
}

V is a statically-typed language, meaning every variable has a fixed data type at compile time. In this chapter, you will learn about V's primitive types: booleans for logic, numeric types for numbers, runes for single characters, and strings for text. You will also learn about V's rich set of built-in methods on these types.

struct string {
pub:
    str    &u8 // Pointer to raw UTF-8 byte array (null-terminated)
    len    int // Length of the string in bytes
    is_lit int // 1 if string literal (static .rodata), 0 if heap-allocated
}

greeting := 'Hello, ${name}! You have ${unread_count} new messages.'

Boolean Type

Logical Operators

In plain words: Logical operators let you combine Yes/No (true/false) questions: && (AND) is true only when both sides are true, || (OR) is true when at least one side is true, and ! (NOT) flips true to false (and vice versa).

What happens in this example:

• Code note: Logical And using && operator
• Code note: Logical OR using || operator
• Code note: Logical not using ! Operator

module main

fn main() {
	t := true
	f := false

	// Logical And using && operator
	and_tt := t && t
	and_tf := t && f
	and_ft := f && t
	and_ff := f && f

	println('Logical And using && operator')
	println('${t} && ${t} = ${and_tt}')
	println('${t} && ${f} = ${and_tf}')
	println('${f} && ${t} = ${and_ft}')
	println('${f} && ${f} = ${and_ff}')
	println('')

	// Logical OR using || operator
	or_tt := t || t
	or_tf := t || f
	or_ft := f || t
	or_ff := f || f

	println('Logical OR using || Operator')
	println('${t} || ${t} = ${or_tt}')
	println('${t} || ${f} = ${or_tf}')
	println('${f} || ${t} = ${or_ft}')
	println('${f} || ${f} = ${or_ff}')
	println('')

	// Logical not using ! Operator
	not_t := !t
	not_f := !f

	println('Logical not using ! Operator')
	println('!${t} = ${not_t}')
	println('!${f} = ${not_f}')
}

Relational Operators

In plain words: Relational (comparison) operators compare two values and answer true or false: == (equals), != (does not equal), < (less than), > (greater than), <= (less than or equal to), and >= (greater than or equal to).

What happens in this example:

• Code note: Comparing using Relational operator >
• Code note: Comparing using Relational operator ==
• Code note: Comparing using Relational operator !=

module main

struct Note {
	id        int
	detail    string
	completed bool
}

fn main() {
	mut n := Note{
		id:     1001
		detail: 'get groceries'
	}
	println(n.completed) // un-assigned bool field will be false by default

	// Comparing using Relational operator >
	if n.id > 1000 { // comparison of note id of integer type to another integer evaluates to a boolean
		println('The note id is greater than 1000')
	} else {
		println('The note id is less than 1000')
	}

	// Comparing using Relational operator ==
	if n.detail == 'get groceries' {
		println('The note details about groceries')
	}

	// Comparing using Relational operator !=
	if n.detail != 'get dairy products' {
		println('The note does not details about dairy products')
	}
}

Boolean Methods

In plain words: Even a simple true or false (bool) value in V has a .str() method to turn it into the text word 'true' or 'false'.

Booleans in V are simple true or false values. V provides built-in methods on boolean types, such as str(), which converts the boolean value to its string representation ('true' or 'false').

This is useful for logging, printing, or interpolating booleans into strings.

module main

fn main() {
	t := true
	f := false

	// str() returns string representation ('true' or 'false')
	println(t.str()) // true
	println(f.str()) // false
}

Numeric Types

Declaring Integers

In plain words: Whole numbers default to int (32-bit), which handles numbers up to about 2 billion. You can also pick smaller or larger whole-number sizes (i8, i16, i64, u8, u16, u32, u64) when needed.

V has several built-in integer types, both signed and unsigned, of various sizes (e.g., i8, i16, i32, i64 for signed integers, and u8, u16, u32, u64 for unsigned integers). If you declare an integer using :=, V defaults to the standard 32-bit integer (int).

This example demonstrates how to declare different integer types.

module main

fn main() {
	x := 1
	println(typeof(x).name)
	// int

	i := 1_000
	j := 1000

	println(i == j) // true
}

Hex Binary Octa Notation Of Declaring Integers

In plain words: Whole numbers default to int (32-bit), which handles numbers up to about 2 billion. You can also pick smaller or larger whole-number sizes (i8, i16, i64, u8, u16, u32, u64) when needed.

V has several built-in integer types, both signed and unsigned, of various sizes (e.g., i8, i16, i32, i64 for signed integers, and u8, u16, u32, u64 for unsigned integers). If you declare an integer using :=, V defaults to the standard 32-bit integer (int).

This example demonstrates how to declare different integer types.

module main

fn demo() {
	h1 := 0x64 // hexadecimal starts with 0x
	b1 := 0b1100100 // binary starts with 0b
	o1 := 0o144 // Octal starts with 0o
	println('Value of var h1 with hexadecimal value : ${h1}')
	println('Data type of var h1 with hexadecimal value : ${typeof(h1).name}')
	println('Value of var b1 with binary value : ${b1}')
	println('Data type of var b1 with binary value : ${typeof(b1).name}')
	println('Value of var o1 with octal value : ${o1}')
	println('Data type of var o1 with octal value : ${typeof(o1).name}')
}

fn main() {
	demo()
}

Promoting Numeric Types

In plain words: To prevent accidental rounding mistakes, V never mixes different number sizes behind your back. To add an i16 and an int, you explicitly convert one to match the other (like int(my_small_num)).

V is very strict about types. It does not perform implicit type conversion (coercion) between different numeric types to prevent accidental precision loss or overflow bugs. If you want to perform arithmetic operations on different types, you must explicitly cast them.

This example shows how to cast (promote) smaller integer types to larger ones or to floats.

module main

fn demo() {
	ia := i8(2)
	ib := i16(2)
	ic := int(2)

	println('----type definitions----')
	println('variable ia is of type: ${typeof(ia).name}')
	println('variable ib is of type: ${typeof(ib).name}')
	println('variable ic is of type: ${typeof(ic).name}')
	println('')
	iaa := ia + ia // i8 with i8 results i8
	ibb := ib + ib // i16 with i16 results i16
	icc := ic + ic // int with int results int
	println('----mixing types----')
	println('variable iaa is of type: ${typeof(iaa).name}, after adding type ${typeof(ia).name} with itself')
	println('variable ibb is of type: ${typeof(ibb).name}, after adding type ${typeof(ib).name} with itself')
	println('variable icc is of type: ${typeof(icc).name}, after adding type ${typeof(ic).name} with itself')
	println('')
	iab := ia + ib // i8 with i16 results in i16
	ibc := ib - ic // i16 with i32 results in i32
	println('----type promotion----')
	println('variable iab is promoted to type: ${typeof(iab).name}, after adding type ${typeof(ia).name} with ${typeof(ib).name}')
	println('variable ibc is promoted to type: ${typeof(ibc).name}, after subtracting type ${typeof(ib).name} with ${typeof(ic).name}')

	iba := ib / ia // the division of i16 and i8 types
	println('Variable iba is promoted to the higher data type ${typeof(iba).name} which is carried from ib of type ${typeof(ib).name} divided from variable ia of type ${typeof(ia).name}')

	fa := f32(2)

	fa_iba := fa + iba // fa is type of f32 and iba is of type i32
	println('Variable fa_iba is promoted to the higher data type ${typeof(fa_iba).name} which is carried from fa of type ${typeof(fa).name} when added with variable iba of type ${typeof(iba).name}')
}

fn main() {
	demo()
}

Arithmetic Operators

In plain words: Arithmetic operators do everyday math on numbers: + (add), - (subtract), * (multiply), / (divide), and % (remainder after division, like 10 % 3 == 1).

What happens in this example:

• Code note: add using +
• Code note: subtract using -
• Code note: product using *
• Code note: / results in quotient

module main

fn main() {
	a := 10
	b := 2

	// add using +
	sum := a + b

	// subtract using -
	diff := b - a

	// product using *
	prod := a * b

	// / results in quotient
	quotient := a / b

	// % modulo results in remainder
	remainder := a % b

	println('Sum of ${a} and ${b} is ${sum}')
	println('Subtracting ${a} from ${b} is ${diff}')
	println('Product of ${a} and ${b} is ${prod}')
	println('Quotient when ${a} divided by ${b} is ${quotient}')
	println('Remainder when ${a} divided by ${b} is ${remainder}')
}

Bitwise Operators

In plain words: Computers store numbers as rows of 1s and 0s (bits). Bitwise operators (& AND, | OR, ^ XOR, ~ NOT) compare or flip those individual 1s and 0s directly—handy for hardware flags, graphics, and permissions.

What happens in this example:

• Code note: bitwise AND operation of two binary nums using & operator
• Code note: bitwise OR operation of two binary nums using | operator
• Code note: bitwise XOR operation of two binary nums using ^ operator
• Code note: bitwise NOT operation of an binary nums using ~ operator

module main

fn main() {
	a := 0b00000110 // 6
	b := 0b00000010 // 2

	// bitwise AND operation of two binary nums using & operator
	b_and := a & b

	// bitwise OR operation of two binary nums using | operator
	b_or := a | b

	// bitwise XOR operation of two binary nums using ^ operator
	b_xor := a ^ b

	// bitwise NOT operation of an binary nums using ~ operator
	not_a := ~a // Not operation yields value which is equal to -(a+1) in its integer form
	println('Bitwise AND: ${a:08b} & ${b:08b} = ${b_and:08b}')
	println('Bitwise OR: ${a:08b} | ${b:08b} = ${b_or:08b}')
	println('Bitwise XOR: ${a:08b} ^ ${b:08b} = ${b_xor:08b}')
	println('Bitwise NOT: ~${a:b} = ${not_a:b}')
}

Shift Operators

In plain words: Bit shift operators slide a number's binary 1s and 0s left (<<, which doubles the number each step) or right (>>, which halves the number each step).

What happens in this example:

• Code note: declare 8 bit integer with value 3
• Code note: 8 bits equals to 1 byte
• Code note: declare 8-bit unsigned integer to shift by 1 position
• Code note: Shift left the value 3 by 1 position

module main

fn main() {
	// declare 8 bit integer with value 3
	a := i8(3)

	// 8 bits equals to 1 byte
	println('a is ${sizeof(a)} byte(s)') // a is 1 byte(s)

	// declare 8-bit unsigned integer to shift by 1 position
	pos := u8(1)

	// Shift left the value 3 by 1 position
	a_left_shift := a << pos
	println('${a} << ${pos} = ${a_left_shift}')
}

Shift Operator On Range Of Integers

In plain words: Shifting bits left (<<) multiplies a number by powers of 2 ($2^1, 2^2, 2^3...$). Looping through a range and shifting 1 << i is an easy way to generate powers of two (1, 2, 4, 8, 16...).

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

fn main() {
	val := i8(1)

	bits := sizeof(val) * 8

	println('Performing left shift using << Operator')

	for i in 0 .. bits {
		after_shift := val << i
		println('${val} << ${i} = ${after_shift} // type after shift operation: ${typeof(after_shift).name}')
	}
}

Integer Methods

In plain words: Whole numbers (int) in V come with built-in helper methods like .str() (turn the number into text) and .hex() (show the number in base-16 hexadecimal format).

What happens in this example:

• Code note: str() returns string representation of the integer
• Code note: hex() returns hexadecimal representation without prefix
• Code note: hex2() returns hexadecimal representation with "0x" prefix
• Code note: hex_full() returns hexadecimal representation with full width padding for the type (8 digits for 32-bit int)

module main

fn main() {
	x := 42

	// str() returns string representation of the integer
	println(x.str()) // "42"

	// hex() returns hexadecimal representation without prefix
	println(x.hex()) // "2a"

	// hex2() returns hexadecimal representation with "0x" prefix
	println(x.hex2()) // "0x2a"

	// hex_full() returns hexadecimal representation with full width padding for the type (8 digits for 32-bit int)
	println(x.hex_full()) // "0000002a"
}

Float Methods

In plain words: Decimal numbers (f32, f64) have built-in helpers to convert them into formatted text strings or inspect their value cleanly.

What happens in this example:

• Code note: str() returns string representation of the float
• Code note: strg() returns string representation (often identical to str())
• Code note: strlong() returns a full/long string representation of the float
• Code note: strsci(precision) returns scientific notation with specified precision/decimal places

module main

fn main() {
	f := 12345.6789

	// str() returns string representation of the float
	println(f.str()) // "12345.6789"

	// strg() returns string representation (often identical to str())
	println(f.strg()) // "12345.6789"

	// strlong() returns a full/long string representation of the float
	println(f.strlong()) // "12345.6789"

	// strsci(precision) returns scientific notation with specified precision/decimal places
	println(f.strsci(4)) // "1.2346e+04"

	// eq_epsilon(other) performs a comparison using machine epsilon (for near-equality)
	f2 := 12345.678900000001
	println(f.eq_epsilon(f2)) // true
}

U8 Methods

In plain words: A u8 (a single byte, from 0 to 255) often represents a single ASCII text character. V gives u8 handy methods like .ascii_str(), .is_digit(), .is_letter(), and .is_space().

What happens in this example:

• Code note: str() returns string representation of the numeric value
• Code note: ascii_str() returns string of length 1 containing the character
• Code note: hex() returns hexadecimal representation
• Code note: hex_full() returns hexadecimal representation (same as hex() for u8)

module main

fn main() {
	b := u8(65) // ASCII code for 'A'

	// str() returns string representation of the numeric value
	println(b.str()) // "65"

	// ascii_str() returns string of length 1 containing the character
	println(b.ascii_str()) // "A"

	// hex() returns hexadecimal representation
	println(b.hex()) // "41"

	// hex_full() returns hexadecimal representation (same as hex() for u8)
	println(b.hex_full()) // "41"

	// is_alnum() checks if the character is alphanumeric
	println(b.is_alnum()) // true

	// is_bin_digit() checks if the character is a binary digit ('0' or '1')
	println(b.is_bin_digit()) // false

	// is_capital() checks if the character is an uppercase letter
	println(b.is_capital()) // true

	// is_digit() checks if the character is a decimal digit ('0'-'9')
	println(b.is_digit()) // false

	// is_hex_digit() checks if the character is a hexadecimal digit ('0'-'9', 'a'-'f', 'A'-'F')
	println(b.is_hex_digit()) // true

	// is_letter() checks if the character is an alphabetic letter
	println(b.is_letter()) // true

	// is_oct_digit() checks if the character is an octal digit ('0'-'7')
	println(b.is_oct_digit()) // false

	// is_space() checks if the character is a whitespace character
	println(b.is_space()) // false

	// repeat(count) repeats the character count times and returns a string
	println(b.repeat(3)) // "AAA"

	// str_escaped() returns an escaped string representation of the character
	println(b.str_escaped()) // "A"
}

Size Pointer Methods

In plain words: isize and usize are whole-number types that match your computer's memory-address size (64-bit on modern computers) and include helper methods for converting to text.

What happens in this example:

• Code note: isize and usize methods
• Code note: str() returns string representation
• Code note: voidptr methods
• Code note: str() returns the memory address as string

module main

fn main() {
	// isize and usize methods
	sz := isize(100)
	usz := usize(200)

	// str() returns string representation
	println(sz.str()) // "100"
	println(usz.str()) // "200"

	// voidptr methods
	x := 42
	p := voidptr(&x)

	// str() returns the memory address as string
	println(p.str().starts_with('0x')) // true

	// hex_full() returns full-width hex representation of address
	println(p.hex_full().len > 0) // true

	// vbytes(len) returns a byte array representation of the memory pointed to (must be called in unsafe block)
	unsafe {
		bytes := p.vbytes(int(sizeof(int)))
		println(bytes) // [42, 0, 0, 0]
	}
}

Rune Type

Declare Rune

In plain words: A rune holds one single character, symbol, or emoji wrapped in backticks (like A or 🚀 ), whereas a string holds text of any length wrapped in single quotes ('Hello').

A rune in V represents a single Unicode code point. Runes are declared using backticks (e.g., \a\, \🔥\) and are represented internally as 32-bit unsigned integers (u32). This allows V to support multi-byte Unicode characters (like emojis or Chinese characters) as single character tokens.

This example shows how to declare and print runes.

fn main() {
	// A rune stores a single Unicode character.
	l := `a`
	println(typeof(l).name)
	// rune
}

Rune Operations With Strings

In plain words: You can convert back and forth between a single character (rune) and text (string), or turn a string into a list of runes with .runes().

Since strings in V are arrays of UTF-8 encoded bytes, you cannot directly check for a rune inside a string using string operations unless the rune is first converted to a string. V provides .str() on the rune type to easily convert a rune to a 1-character string, allowing you to use string methods like .count(), .contains(), etc.

This example shows how to count occurrences of a Unicode rune in a string.

fn main() {
	beverage := 'café'
	// 's' is a rune representing the Unicode character 'é'
	s := `é`
	// Since .count() expects a string argument, we convert the rune 's' using .str()
	println(beverage.count(s.str()))
	// Outputs: 1
}

Rune Methods

In plain words: Single characters (rune) have built-in methods like .to_upper(), .to_lower(), .str(), and .length_in_bytes().

Runes in V are not just raw numbers; they are full-fledged Unicode characters that support several built-in methods. You can convert their case, check their byte length (which can range from 1 to 4 bytes depending on the character, such as emojis), obtain their byte array representation, or convert them to hexadecimal code points.

This lesson demonstrates common helper methods on the rune type.

module main

fn main() {
	r := `A`

	// bytes() returns the byte representation (UTF-8 bytes) of the rune
	println(r.bytes()) // [65]

	// hex() returns the hexadecimal representation of the rune code point
	println(r.hex()) // "41"

	// length_in_bytes() returns the size of the rune in bytes (1 to 4)
	println(r.length_in_bytes()) // 1

	// repeat(count) returns a string with the rune repeated count times
	println(r.repeat(3)) // "AAA"

	// str() returns the string representation of the rune
	println(r.str()) // "A"

	// to_lower() returns the lowercase rune
	println(r.to_lower().str()) // "a"

	// to_upper() returns the uppercase rune
	println(r.to_upper().str()) // "A"

	// to_title() returns the titlecase rune
	println(r.to_title().str()) // "A"

	// Testing with a multi-byte UTF-8 rune (dog emoji 🐕)
	r2 := `🐕`
	println(r2.bytes()) // [240, 159, 144, 149]
	println(r2.hex()) // "1f415" (Unicode code point in hex)
	println(r2.length_in_bytes()) // 4
	println(r2.repeat(2)) // "🐕🐕"
	println(r2.str()) // "🐕"
}

String Type

Declare String

In plain words: Strings hold text inside single quotes ('hello') or double quotes ("hello"), and .len tells you how many bytes long the text is.

In V, strings are representing read-only arrays of bytes, encoded natively in UTF-8. You can declare string variables using single quotes ('hello') or double quotes ("hello"), though single quotes are preferred in idiomatic V. The string type in V comes with built-in metadata, such as the .len field, which returns the total number of bytes in the string (not necessarily the number of Unicode characters/runes). You can inspect the runtime type of any variable using V's built-in typeof() function.

This example illustrates how to declare string variables, concatenate them, check string lengths, and query variable types at runtime.

module main

fn main() {
	// Strings can be declared using single quotes
	greeting := 'hello'
	name := 'Ada'
	
	// String concatenation using the '+' operator
	message := greeting + ', ' + name + '!'

	println(message)
	// Access the length (in bytes) of the string using the .len field
	println('Length: ${message.len}')
	// Inspect the variable type at runtime using typeof()
	println('Type: ${typeof(message).name}')
}

String Read Only Array Of Bytes

In plain words: Underneath, a string is a numbered row of byte values (u8). Indexing s[0] gives you the first byte, and s[0].ascii_str() shows it as a letter.

In V, strings are represented internally as read-only arrays of UTF-8 encoded bytes (u8). This means you can index into a string using bracket notation (str[index]) to extract the raw byte value at that position. The type returned from indexing a string is u8 (8-bit unsigned integer), not a string or rune.

This example shows how to read raw bytes from a string and prints the byte value and its type name.

fn main() {
	fruit := 'Orange'
	// Accessing the first byte of the string 'Orange'.
	// This returns the ASCII value of 'O' (which is 79), and its type is 'u8'.
	println(typeof(fruit[0]).name)
	// Outputs: u8
	
	println(fruit[0])
	// Outputs: 79
}

Strings Immutable By Default

In plain words: Just like other variables in V, a string variable cannot be pointed to new text unless you declare the variable with mut.

Strings in V are completely immutable. Once a string is created, its characters cannot be modified in place. Any operation that manipulates a string (such as replacing characters or converting to uppercase) returns a brand new string instead of modifying the original.

This example demonstrates that strings are read-only and cannot be changed.

fn main() {
	s := 'hello'
	// variable s is immutable
	s = 'Hello!'
	// this results in error
}

Declaring Mutable Strings

In plain words: Adding mut to a string variable (mut s := 'hello') lets you replace its text or tack on more words with +=.

While strings are immutable, you can declare a mutable string variable using mut. This allows the variable to be reassigned to a new string value, or appended to using the += operator.

This example shows how to declare a mutable string and append text to it.

fn main() {
	mut msg := 'Hello Friend!'
	msg = 'Hope you are doing good.'
	println(msg)
	// Hope you are doing good.
	msg = msg + ' There is a surprise for you.'
	println(msg)
	// Hope you are doing good. There is a surprise for you.
}

Cannot Mutate String Elements

In plain words: Even on a mut string variable, you cannot overwrite a single letter by index (s[0] = 'J' is forbidden); instead, build a new string or use .replace(...).

Although declaring a string variable with mut lets you reassign the variable to reference a completely different string, it does NOT let you mutate individual characters or bytes within the existing string (e.g. s[0] = \G\``). String data elements are strictly read-only arrays of bytes, and attempting to mutate them will fail compilation.

This program shows that element mutation is strictly forbidden.

fn main() {
	mut greet := 'good Day'

	// ERROR: Cannot assign directly to string indices.
	// Strings in V are read-only byte arrays and their contents cannot be mutated.
	greet[0] = 'G' 
}

String Interpolation

In plain words: Put ${variable} or ${expression} right inside a string literal and V will automatically plug the value into the text for you!

String interpolation is a clean way to insert variables or expressions inside a string literal. In V, you do this by wrapping the variable or expression in ${variable} inside a single-quoted string.

This example demonstrates how to format strings with variable values.

fn main() {
	a := 'coding'
	b := 'fun'
	println('${a} is ${b}')
	println('${a} is ${b}')
}

Escape Special Characters

In plain words: Backslash codes like \n (new line), \t (tab indent), and \' (single quote) let you include special formatting characters inside a string.

V strings support standard escape characters (like \n for newlines, \t for tabs, and \\ for backslashes) to represent special characters inside a string literal.

This example shows how these escape sequences are rendered in the console.

module main

fn main() {
	// 1. Newline escape character (\n)
	println('Hello\nWorld!')

	// 2. Tab escape character (\t)
	println('Name:\tAlice\tAge:\t25')

	// 3. Backslash escape character (\\)
	println('File path: C:\\Program Files\\V')

	// 4. Escaping single quotes (\') in a single-quoted string
	println("It's my Daughter's birthday!")

	// 5. Escaping double quotes (\") in a double-quoted string
	println('She said, "V is fast!"')
}

Declare Raw Strings

In plain words: Putting an r in front of a string (r'C:\Users\name') creates a raw string where backslashes \ are treated as plain everyday characters instead of escape codes.

If you want to write a string literal where escape sequences (like \n) are treated as literal text instead of special commands, you can declare a raw string by prefixing the string literal with r (e.g., r\'hello\nworld\').

This is extremely useful when writing regular expressions or file paths.

module main

fn main() {
	i := r'hi \how are you/?'
	println(i)
}

String Concatenation Using Plus Sign

In plain words: You can glue two or more strings together into one longer string using the + sign (like 'Hello, ' + 'World!').

In V, joining strings together is performed using the + operator. Since strings are immutable byte arrays, each concatenation creates a brand-new string in memory and copies the contents of both source strings. While the + operator is extremely convenient and clear for joining a few strings, doing this in loops or performance-critical code paths is discouraged because it leads to excessive memory allocations. For high-performance string building, V offers the strings.Builder module.

This example illustrates the direct concatenation of two string variables.

module main

fn main() {
	a := 'con'
	b := 'cat'
	// Concatenate a and b, creating a new string 'concat' in memory
	println(a + b)
	// concat
}

String Concatenation Using Interpolation

In plain words: Instead of gluing strings together with +, you can drop variables directly inside a string using ${variable}. This is called string interpolation, and it is the cleanest way to build messages in V.

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

fn main() {
	i := 1
	j := 'man army'
	println('${i} ${j}')
}

Extract Substring From String Literal

In plain words: Use slice brackets s[start..end] or .substr(start, end) to cut out a smaller piece of text from inside a string.

V provides two main techniques to extract substrings from a string literal or variable:

1. The .substr(start, end) Method: Takes the starting index (inclusive) and ending index (exclusive) as parameters.
2. Range Slicing Syntax [start..end]: A clean and idiomatic syntax (similar to Go and Rust) where you specify range offsets. If the starting index is omitted (e.g. [..end]), it defaults to 0. If the ending index is omitted (e.g. [start..]), it defaults to the length of the string.

Both techniques are demonstrated in the example below.

module main

fn main() {
	a := 'Camel'

	// Method 1: Using the substr(start, end) method
	// Extracts characters from index 0 up to (but not including) index 3
	b := a.substr(0, 3)
	println(b) // Output: Cam

	// Method 2: Using idiomatic range slicing syntax [start..end] (similar to Go/Rust)
	// Slices from index 1 up to (but not including) index 4
	c := a[1..4]
	println(c) // Output: ame

	// Method 3: Slicing from start to index [..end]
	// If the start index is omitted, it defaults to 0
	d := a[..3]
	println(d) // Output: Cam

	// Method 4: Slicing from index to end [start..]
	// If the end index is omitted, it defaults to the string length
	e := a[2..]
	println(e) // Output: mel
}

Split String

In plain words: The .split(...) method chops a piece of text into a list (array) of smaller words or pieces wherever a separator character (like a space ' ' or comma ',') appears.

What happens in this example:

• Code note: split by space as delimiter
• Code note: ['The', 'tiny', 'tiger', 'tied', 'the', 'tie', 'tighter', 'to', 'its', 'tail']

module main

fn main() {
	sp := 'The tiny tiger tied the tie tighter to its tail'
	res := sp.split(' ')
	// split by space as delimiter
	println(typeof(res).name)
	// []string
	println(res)
	// ['The', 'tiny', 'tiger', 'tied', 'the', 'tie', 'tighter', 'to', 'its', 'tail']
}

String To Runes Array

In plain words: Because special characters and emojis can take more than one byte in memory, calling .runes() turns a text string into an accurate list of individual visual characters ([]rune).

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

fn main() {
	doge_moon := '🐕+🚀=🌑'
	doge_moon_runes := doge_moon.runes()
	println(doge_moon_runes)
	println(typeof(doge_moon_runes).name) // []rune
}

Count Sub String Occurences

In plain words: Calling .count('word') on a string tells you how many times that smaller word or letter appears inside the text.

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

fn main() {
	sp := 'The tiny tiger tied the tie tighter to its tail'
	println(sp.count('t'))
	// 10
	println(sp.count('T'))
	// 1
	println(sp.count('tie'))
	// 2
	println(sp.count('-'))
	// 0
}

Check String Contains Substring

In plain words: Calling .contains('word') checks if a piece of text appears anywhere inside a string and returns true (yes) or false (no).

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

fn main() {
	hs := 'monday'

	if hs.contains('mon') {
		println('${hs} contains mon')
	} else {
		println('${hs} does not contains mon')
	}
}

String Contains Is Case Sensitive

In plain words: .contains(...) cares about uppercase vs lowercase letters ('V' is different from 'v'). If you want a case-insensitive check, convert the string with .to_lower() first!

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

fn main() {
	hs := 'Monday'

	if hs.contains('mon') {
		println('${hs} contains mon')
	} else {
		println('${hs} does not contains mon')
	}
}

Common String Methods

In plain words: V strings come packed with everyday text helpers like .to_upper(), .to_lower(), .trim_space(), .replace(), .starts_with(), and .ends_with().

What happens in this example:

• Code note: to_lower() returns the lowercase version of the string
• Code note: to_upper() returns the uppercase version of the string
• Code note: trim_space() trims leading and trailing whitespaces
• Code note: trim(cutset) trims leading and trailing characters that match any character in the cutset

module main

fn main() {
	s := '  Hello, V!  '

	// to_lower() returns the lowercase version of the string
	println(s.to_lower()) // "  hello, v!  "

	// to_upper() returns the uppercase version of the string
	println(s.to_upper()) // "  HELLO, V!  "

	// trim_space() trims leading and trailing whitespaces
	println(s.trim_space()) // "Hello, V!"

	// trim(cutset) trims leading and trailing characters that match any character in the cutset
	println(s.trim(' ')) // "Hello, V!"

	// replace(old, new) replaces all occurrences of old with new
	println(s.replace('V', 'World')) // "  Hello, World!  "

	// replace_once(old, new) replaces the first occurrence of old with new
	println(s.replace_once('l', 'x')) // "  Hexlo, V!  "

	// index(sub) returns the start index of the first occurrence of sub as an optional ?int
	idx := s.index('Hello') or { -1 }
	println(idx) // 2

	// last_index(sub) returns the start index of the last occurrence of sub as an optional ?int
	last_idx := s.last_index('l') or { -1 }
	println(last_idx) // 5

	// starts_with(prefix) checks if the string starts with the prefix
	println(s.starts_with('  ')) // true

	// ends_with(suffix) checks if the string ends with the suffix
	println(s.ends_with('!')) // false (ends with spaces)

	// is_pure_ascii() checks if all characters in the string are pure ASCII
	println(s.is_pure_ascii()) // true

	// split_into_lines() splits a string into an array of lines
	multiline := 'line 1\nline 2'
	println(multiline.split_into_lines()) // ["line 1", "line 2"]

	// split_by_space() splits a string by space as delimiter
	println(s.split_by_space()) // ["Hello,", "V!"]
}

Chapter 4 Control Flow

Control flow determines the execution path of your code. In this chapter, we cover conditionals (if-else), pattern matching (match), and the versatile for loop. V simplifies control flow by using fewer keywords, making code highly readable.

status := if score >= 50 { 'Pass' } else { 'Fail' }

fn process_file(path string) ! {
    mut file := os.open(path)!
    defer { file.close() } // Guaranteed to execute whenever process_file returns

    // Perform operations...
}

Control Flow Extras

Chaining Else If

In plain words: When you have more than two choices, chain if ... else if ... else from top to bottom. V runs the first branch that is true and skips the rest.

When your program must choose between multiple mutually exclusive paths, you can chain multiple else if blocks together. V evaluates these conditions sequentially from top to bottom. As soon as one condition evaluates to true, the corresponding block of code is executed, and all remaining branches (including any final fallback else block) are skipped entirely. Like single if statements, parentheses are not required around the condition expressions in V.

This example defines a helper function that takes a weekday string and prints a corresponding breakfast menu using a chained conditional statement.

module main

// This helper chooses a meal plan based on the weekday.
fn breakfast_menu(day string) {
	// Cascading conditional checks
	if day == 'Monday' {
		println('Bread, Jam, Half boiled Egg')
	} else if day == 'Tuesday' {
		println('Bread, Jam, Juice')
	} else if day == 'Wednesday' {
		println('Milk, Bread, Fruit Bowl')
	} else if day == 'Thursday' {
		println('Bread, Jam, Juice')
	} else if day == 'Friday' {
		println('Cereals, Bread, Jam, Half boiled Egg')
	} else if day == 'Saturday' {
		println('Milk, Bread, Fruit Bowl')
	} else if day == 'Sunday' {
		println('Cereals, Bread, Jam, Half boiled Egg')
	} else {
		// Fallback block executed if no prior conditions match
		println('invalid input')
	}
}

fn main() {
	// Call the helper with a sample weekday.
	breakfast_menu('Saturday')
}

If With Goto

In plain words: unsafe { goto label } jumps directly to a named label in your code. You will almost never need goto in everyday programs (use loops and functions instead), but V includes it for rare low-level cleanup tasks.

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

import os

fn main() {
	improper_input_age:
	println('Invalid input. Please provide value greater than 0.')

	next_person:
	inp := os.input('Enter your age:')

	if inp != 'stop' {
		age := inp.int()

		if age >= 13 {
			println('You are allowed to watch this movie')
		} else if age > 0 && age < 13 {
			println('Parental Guidance is required to watch this movie')
		} else if age <= 0 {
			unsafe {
				goto improper_input_age
			}
		}
		unsafe {
			goto next_person
		}
	}
}

Cascade Match Conditions

In plain words: In a match block, if several different values should run the exact same code, you can list them together separated by commas (like 'Monday', 'Tuesday' { ... }).

What happens in this example:

• Creates helper function(s)/method(s): breakfast_menu.
• Prints the result to the terminal window so you can see the output right away.

module main

fn breakfast_menu(day string) string {
	return match day {
		'Monday' {
			'Bread, Jam, Half boiled Egg'
		}
		'Tuesday', 'Thursday' {
			'Bread, Jam, Juice'
		}
		'Wednesday' {
			'Milk, Bread, Fruit Bowl'
		}
		'Friday', 'Sunday' {
			'Cereals, Bread, Jam, Half boiled Egg'
		}
		'Saturday' {
			'Milk, Bread, Fruit Bowl'
		}
		else {
			'invalid input'
		}
	}
}

fn main() {
	friday_menu := breakfast_menu('Friday')
	println(friday_menu)

	sunday_menu := breakfast_menu('Sunday')
	println(sunday_menu)

	tuesday_menu := breakfast_menu('Tuesday')
	println(tuesday_menu)

	thursday_menu := breakfast_menu('Thursday')
	println(thursday_menu)
}

Match As Switch Case

In plain words: match is V's cleaner, safer version of if / else if: give it a value once at the top, and list each possible match case inside { ... }.

In V, there is no switch statement. Instead, the match keyword is used for branching on values. The match statement is highly readable and type-safe. Each branch is evaluated in order, and unlike in C/Java/Javascript, there is no "fall-through" behavior—the matching block executes and the statement completes immediately. This eliminates bugs caused by forgetting break statements. V also enforces that a match must cover all possible cases or provide an else block.

This example shows how to use match on string values.

module main

fn breakfast_menu(day string) {
	// A match block branches on the value of 'day'.
	// In V, match is an expression and can also return values.
	match day {
		'Monday' { println('Bread, Jam, Half boiled Egg') }
		'Tuesday' { println('Bread, Jam, Juice') }
		'Wednesday' { println('Milk, Bread, Fruit Bowl') }
		'Thursday' { println('Bread, Jam, Juice') }
		'Friday' { println('Cereals, Bread, Jam, Half boiled Egg') }
		'Saturday' { println('Milk, Bread, Fruit Bowl') }
		'Sunday' { println('Cereals, Bread, Jam, Half boiled Egg') }
		else { println('invalid input') } // Exhaustive match requirement handled by 'else'
	}
}

fn main() {
	breakfast_menu('Sunday')
}

Match Pattern Matching

In plain words: match can check not just single values, but also number ranges (like 1..10) to categorize values cleanly without writing complicated if conditions.

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

fn main() {
	age := 18
	res := match age {
		0...18 { 'Person with age ${age} classified as a Child' }
		19...120 { 'Person with age ${age} classified as an Adult' }
		else { '${age} is must be in the range 0 to 120' }
	}
	println(res)
}

Match With Enum

In plain words: An enum defines a fixed set of named options (like Color.red, .green, .blue), and match makes sure you handle every option cleanly.

One of V's strongest safety guarantees is exhaustive enum matching. When you match on an enum value, V requires you to handle every single enum member. If you miss one, the compiler will refuse to compile the program. This ensures that when new items are added to an enum in the future, the compiler will automatically guide you to update all match expressions across your codebase. Additionally, V supports shorthand syntax where you can write .member_name instead of EnumName.member_name inside the match arms.

This example illustrates matching over an enum to return a string menu item.

module main

// Define a Days-of-the-week enum
enum Day {
	sunday
	monday
	tuesday
	wednesday
	thursday
	friday
	saturday
}

fn breakfast_menu(day Day) string {
	// The match statement returns the value of the matching block.
	// Notice we use the shorthand dot syntax (.monday) since 'day' is known to be of type 'Day'.
	return match day {
		.monday {
			'Bread, Jam, Half boiled Egg'
		}
		.tuesday, .thursday {
			'Bread, Jam, Juice' // Grouping multiple enum members using comma
		}
		.wednesday {
			'Milk, Bread, Fruit Bowl'
		}
		.friday, .sunday {
			'Cereals, Bread, Jam, Half boiled Egg'
		}
		.saturday {
			'Milk, Bread, Fruit Bowl'
		}
	} // No else block is needed because all enum members are exhaustively handled.
}

fn main() {
	friday_menu := breakfast_menu(Day.friday)
	println(friday_menu)

	sunday_menu := breakfast_menu(Day.sunday)
	println(sunday_menu)

	tuesday_menu := breakfast_menu(Day.tuesday)
	println(tuesday_menu)

	thursday_menu := breakfast_menu(Day.thursday)
	println(thursday_menu)
}

Match With Enum And Else

In plain words: When matching on an enum (a fixed list of named choices), you can handle specific choices by name (.red, .green) and use else as a catch-all for any remaining choices.

What happens in this example:

• Creates helper function(s)/method(s): weekend_breakfast_menu.
• Prints the result to the terminal window so you can see the output right away.

module main

enum Day {
	sunday
	monday
	tuesday
	wednesday
	thursday
	friday
	saturday
}

fn weekend_breakfast_menu(day Day) string {
	return match day {
		.sunday {
			'Cereals, Bread, Jam, Half boiled Egg'
		}
		.saturday {
			'Milk, Bread, Fruit Bowl'
		}
		else {
			'Sorry, we are closed on weekdays!'
		}
	}
}

fn main() {
	sunday_menu := weekend_breakfast_menu(Day.sunday)
	println(sunday_menu)

	tuesday_menu := weekend_breakfast_menu(Day.tuesday)
	println(tuesday_menu)
}

Bare For

In plain words: A for { ... } loop with no condition runs forever until it hits a break or return inside—great for game loops and servers!

V simplifies iteration by only offering a single keyword for loops: for. There is no while keyword in V. A "bare" for (a loop declaration without any conditions or loop ranges) represents an infinite loop, which behaves exactly like while true in other languages. To exit a bare for loop, you must use a break statement inside the loop body, or exit the function using return.

This example shows how to declare a bare infinite loop.

module main

fn main() {
	mut count := 1
	// Bare for starts an infinite loop.
	// WARNING: Running this without a break condition will loop forever.
	for {
		println('Hi ${count} times')
		count += 1
		
		// To break out, a developer would normally add:
		if count > 5 {
			break
		}
	}
}

Break For

In plain words: Inside a for loop, the break keyword acts like an emergency exit—it stops the loop immediately and jumps to the code after the loop.

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

module main

import os

fn main() {
	mut count := 0
	input := os.input('Enter number of times to Greet:')
	limit := input.int()
	for {
		if count >= limit {
			break
		}
		println('Hi')
		count += 1
	}
	println('Greeted Hi ${count} times')
}

Continue For

In plain words: Inside a for loop, the continue keyword says 'skip the rest of this turn and jump straight to the next item in the loop.'

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

fn main() {
	for i in 0 .. 10 {
		if i % 2 == 0 { // skips printing number that is a multiple of 2
			continue
		}
		println(i)
	}
}

For C Style

In plain words: A 3-part for loop (for i := 0; i < 10; i++) sets a starting counter (i := 0), checks a keep-going condition (i < 10), and steps the counter (i++) after each turn.

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

fn main() {
	sample := [3, 4, 23, 12, 4, 1, 45, 12, 42, 17, 92, 38]
	for i := 0; i < sample.len; i += 3 {
		println(sample[i])
	}
}

For On Array Without Index

In plain words: When you just want to look at each item in a list (array) without needing its position number, write for item in my_list { ... }.

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

fn main() {
	col := [1, 2, 3, 4, 5, 6, 7]
	for val in col {
		if val % 2 == 0 {
			println('${val} is Even')
		} else {
			println('${val} is Odd')
		}
	}
}

For On Arrays

In plain words: Write for index, item in my_array to loop through a list while getting both the item's position number (index) and its value (item).

Iterating over arrays is a very common requirement. In V, you can iterate over both the index and value of each element using the for index, value in array syntax. During each iteration, the index variable (e.g., idx) contains the zero-based array index, and the element variable (e.g., ele) contains a read-only copy of the item. Both variables are scoped exclusively to the body of the loop and cannot be mutated. If you only need the element values and not their indices, V allows you to omit the index variable (e.g. for value in array).

This example declares a list of fruits and iterates over them, printing each fruit alongside its corresponding index.

module main

fn main() {
	fruits := ['apple', 'banana', 'coconut']
	
	// Loop over the indices (idx) and elements (ele) of the fruits array
	for idx, ele in fruits {
		println('idx: ${idx} \t fruit: ${ele}')
	}
}

For On Maps

In plain words: Write for key, value in my_map to step through every key and its matching value in a dictionary map.

V makes iterating over key-value collections (maps) straightforward. By using the syntax for key, value in map, you can access both the key and the value of each entry directly during each iteration. Like arrays, the iteration variables (key and value) are local to the loop scope and are immutable. Note that iteration order over maps is not guaranteed to be stable or sorted, matching standard hash map behavior in other systems languages.

This example demonstrates how to declare a map and iterate over its key-value pairs.

module main

fn main() {
	// Initialize a map with string keys and integer values
	lottery := {
		'First':       1000
		'Second':      700
		'Consolation': 200
	}

	// Loop over keys (k) and values (v) in the 'lottery' map.
	for k, v in lottery {
		println('${k} prize lottery amount: ${v}')
	}
}

For On Maps Ignore Key

In plain words: When looping over a map (dictionary), if you only care about the values and want to ignore the keys, use _ as a blank placeholder for the key: for _, value in my_map.

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

module main

fn main() {
	basket := {
		'apples':  10
		'bananas': 12
	}

	mut total := 0
	for _, v in basket {
		total += v
	}
	println('Total number of fruits: ${total}')
}

For On Range

In plain words: Writing for i in 1 .. 5 loops i through the numbers 1, 2, 3, 4 (stopping right before the upper number 5).

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

fn main() {
	for val in 0 .. 4 {
		println(val)
	}
}

For With Continue Break And Labels

In plain words: When you have one loop nested inside another loop, you can put a name label (outer:) on the outside loop so break outer or continue outer can control the outer loop directly!

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

import os

fn main() {
	input := os.input('Enter the number of multiplication tables to print:')
	limit := input.int()
	if limit <= 0 {
		return
	}
	first_loop: for i := 1; i <= 10; i++ {
		println('Printing multiplication table for ${i}')
		for j := 1; j <= 10; j++ {
			mul := i * j
			println('${i} * ${j} = ${mul}')
			if mul >= limit * 10 {
				break first_loop
			}
		}
		println('*********')
	}
}

Reverse For

In plain words: By using a C-style for loop that starts at the end and counts down (i--), you can walk through numbers or array items backward.

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

module main

fn main() {
	subjects := ['zoology', 'chemistry', 'physics', 'algebra']

	for i := subjects.len - 1; i >= 0; i-- {
		println(subjects[i])
	}
}

Chapter 5 Collections: Arrays and Maps

Collections allow you to group multiple data items together. V provides two primary built-in collection types: arrays (ordered lists of elements) and maps (key-value dictionaries). This chapter covers creating, accessing, and manipulating these collections using modern functional patterns like map and filter.

struct Array {
    data         voidptr // Pointer to continuous heap-allocated memory block
    offset       int     // Slicing offset
    len          int     // Number of active elements currently in array
    cap          int     // Total capacity allocated in memory
    element_size int     // Size in bytes of each element (e.g., 4 for int)
}

Array Header: [ data* | offset: 0 | len: 3 | cap: 4 | element_size: 4 ]
                      |
                      v
Heap Buffer:   [ 10 ][ 20 ][ 30 ][ <unallocated> ]

Arrays

Declare And Initialize

In plain words: To create a list (array) with starting items, wrap the items in square brackets separated by commas, like [1, 2, 3]. V automatically figures out the list's type from the items inside!

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut sports := ['cricket', 'hockey', 'football']
	println(sports)
}

Declare Empty Array

In plain words: To create an empty list (array) that you plan to fill later, write [] followed by the type of item it will hold and {} at the end—for example, mut list := []int{}.

What happens in this example:

• Code note: prints empty array: []
• Code note: ['Chimpanzee', 'Dog']

fn main() {
	mut animals := []string{}
	println(animals)
	// prints empty array: []
	animals << 'Chimpanzee'
	animals << 'Dog'
	println(animals)
	// ['Chimpanzee', 'Dog']
}

Declare Array With Len

In plain words: Writing []int{len: 3} creates an array that already has 3 slots ready to go, filled with 0 by default ([0, 0, 0]).

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut i := []int{len: 3}
	println(i)
}

Declare Array With Init And Len

In plain words: Writing []int{len: 3, init: 1} creates an array of 3 slots and fills every slot with your chosen starting value (1) instead of 0, giving [1, 1, 1].

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut j := []int{len: 3, init: 1}
	println(j)
}

Declare Array With Cap

In plain words: Writing []int{cap: 2} creates an empty list (len: 0), but quietly reserves room in memory for 2 items ahead of time so appending items later is extra fast.

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut k := []int{cap: 2}
	println(k)
}

Working With Array Properties

In plain words: Every array has two built-in size properties: .len (how many items are currently in the list) and .cap (how many slots are currently reserved in memory before the array needs to grow).

What happens in this example:

• Code note: Length of sports array
• Code note: Capacity of sports array
• Code note: deleting football

fn main() {
	mut sports := ['cricket', 'hockey', 'football']
	println(sports.len)
	// Length of sports array
	println(sports.cap)
	// Capacity of sports array
	println('----Deleting football----')
	sports.delete(2)
	// deleting football
	println('Length of sports array: ${sports.len}')
	println('Capacity of sports array: ${sports.cap}')

	println('----Adding volleyball and baseball----')

	sports << ['volleyball', 'baseball']
	println(sports)
	println('Length of sports array: ${sports.len}')
	println('Capacity of sports array: ${sports.cap}')
}

Access Array Elements Using Index

In plain words: You read or change a specific item in an array using its position number (index) inside square brackets arr[index]. Remember: the first item is always at index 0!

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut sports := ['cricket', 'hockey', 'football']
	s := sports[1]
	println(s) // hockey
}

Access Array Elements Using Slices

In plain words: A slice (arr[start..end]) grabs a range of items from an array—starting at start and stopping right before end.

What happens in this example:

• Code note: Positive slicing: from index 1 to 3 (excluding index 3)
• Code note: V does not support negative indices natively in slices (e.g., sports[-2..] will not compile).
• Code note: To achieve "negative slicing" (indexing from the end of the array), use the .len property:
• Code note: Slice up to the last element (excluding it): Python's sports[..-1]

fn main() {
	mut sports := ['cricket', 'hockey', 'football', 'basketball', 'tennis']

	// Positive slicing: from index 1 to 3 (excluding index 3)
	println(sports[1..3]) // ['hockey', 'football']

	// V does not support negative indices natively in slices (e.g., sports[-2..] will not compile).
	// To achieve "negative slicing" (indexing from the end of the array), use the `.len` property:

	// Slice up to the last element (excluding it): Python's sports[..-1]
	println(sports[..sports.len - 1]) // ['cricket', 'hockey', 'football', 'basketball']

	// Slice from 3rd to last up to 1st to last (excluding it): Python's sports[-3..-1]
	println(sports[sports.len - 3..sports.len - 1]) // ['football', 'basketball']

	// Slice the last two elements: Python's sports[-2..]
	println(sports[sports.len - 2..]) // ['basketball', 'tennis']

	// --- REFERENCE VS VALUE BEHAVIOR ---
	// In V, slices are reference views of the original array.
	// If you modify an element of a slice, it affects the original array.
	// Note: To prevent unsafe behavior, assigning a slice to a variable requires an `unsafe` block
	// if you want it by-reference, or an explicit `.clone()` to get a copy by-value.

	// 1. Modifying by reference (using unsafe)
	mut original := [10, 20, 30, 40, 50]
	mut ref_slice := unsafe { original[1..4] }
	ref_slice[0] = 99
	println(original) // [10, 99, 30, 40, 50] (Original is modified!)

	// 2. Modifying by value (using .clone())
	mut original_two := [10, 20, 30, 40, 50]
	mut val_slice := original_two[1..4].clone()
	val_slice[0] = 99
	println(original_two) // [10, 20, 30, 40, 50] (Original remains unchanged!)
}

In Operator With Array

In plain words: Want to know if a value is inside an array? Just ask value in my_array (or value !in my_array for 'not in')—no manual loop required!

What happens in this example:

• Code note: prints: true
• Code note: prints: true

fn main() {
	odd := [1, 3, 5, 7]

	println(3 in odd)
	// prints: true
	println(8 !in odd)
	// prints: true
}

Append Array

In plain words: The push arrow << adds a new item (or even an entire list of items!) onto the end of a changeable (mut) array.

What happens in this example:

• Code note: prints [2, 4, 6, 8]
• Code note: prints: [2, 4, 6, 8, 10, 12, 14]

fn main() {
	mut even := [2, 4, 6]
	even << 8
	println(even)
	// prints [2, 4, 6, 8]
	even << [10, 12, 14]
	println(even)
	// prints: [2, 4, 6, 8, 10, 12, 14]
}

Define Fixed Size Array

In plain words: Putting a number inside the brackets ([3]int) creates a fixed-size array whose length is locked at 3 items forever. Because it never grows, V stores it directly in ultra-fast stack memory.

What happens in this example:

• Code note: [0, 0, 0, 0]

fn main() {
	mut fix := [4]int{}
	println(fix)
	// [0, 0, 0, 0]
}

Update Fixed Size Array Elements

In plain words: Even though a fixed-size array ([3]int) cannot grow or shrink in length, you can still change the individual values inside its slots if the variable is marked mut.

What happens in this example:

• Code note: [0, 33, 0, 0]

fn main() {
	mut fix := [4]int{}
	fix[1] = 33
	println(fix)
	//[0, 33, 0, 0]
}

Determining Type Of Fixed Array

In plain words: In V, a fixed-size array's length is part of its type name (for example, [3]int is a distinct type from []int), which you can verify with typeof(arr).name.

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut fix := [4]int{}
	println(typeof(fix).name) // [4]int
}

Slicing Fixed Size Array Results In Ordinary Array

In plain words: If you take a slice of a fixed-size array (using arr[0..2] or arr[..]), V gives you back a normal dynamic array ([]int) so you can pass it to functions that expect standard arrays.

What happens in this example:

• Code note: [33, 0, 0]

fn main() {
	mut fix := [4]int{}
	fix[1] = 33
	s := fix[1..]
	println(s)
	// [33, 0, 0]
	println(typeof(s).name) // prints: []int
}

Declaring Multi Dimensional Arrays

In plain words: A 2D or multi-dimensional array ([][]int) is simply a 'list of lists'—like a grid, spreadsheet, or game board with rows and columns.

What happens in this example:

• Code note: [[0, 0], [0, 0], [0, 0], [0, 0]]

fn main() {
	mut coordinates_2d := [][]int{len: 4, init: []int{len: 2}}
	println(typeof(coordinates_2d).name)
	// [][]int
	println(coordinates_2d)
	// [[0, 0], [0, 0], [0, 0], [0, 0]]
}

Updating Multi Dimensional Array Indices

In plain words: In a 2D grid ([][]int), you access or change a single cell using two brackets: grid[row][column].

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut coordinates_2d := [][]int{len: 4, init: []int{len: 2}}
	println(coordinates_2d.len)

	point_1 := [0, 0]
	point_2 := [0, 1]
	point_3 := [1, 0]
	point_4 := [1, 1]

	coordinates_2d[0] = point_1
	coordinates_2d[1] = point_2
	coordinates_2d[2] = point_3
	coordinates_2d[3] = point_4
	println(coordinates_2d)
}

Reassigning Multi Dimensional Arrays

In plain words: You can also replace an entire row of a 2D array at once by assigning a new 1D list to grid[row].

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut coordinates_2d := [][]int{len: 4, init: []int{len: 2}}
	println(coordinates_2d.len)
	coordinates_2d = [
		[0, 0],
		[0, 1],
		[1, 0],
		[1, 1],
	]
	println(coordinates_2d)
}

Clone Array

In plain words: Assigning one array variable to another (b := a) can share the underlying memory. Calling .clone() creates a brand-new, independent copy so changing one list never affects the other.

What happens in this example:

• Code note: copies the array r to u

fn main() {
	r := [1, 2, 3, 4]
	mut u := r.clone()
	// copies the array r to u
	println(u)
}

Copy Array

In plain words: Assigning one array variable to another (b := a) can share the underlying memory. Calling .clone() creates a brand-new, independent copy so changing one list never affects the other.

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

fn main() {
	r := [1, 2, 3, 4]
	s := unsafe { r }
	println(s)
	unsafe {
		r.free()
	}
}

Sort Integer Array

In plain words: Calling .sort() on a changeable (mut) number array sorts it from smallest to largest (a < b). You can also sort from largest to smallest using .sort(a > b)!

What happens in this example:

• Code note: ascending order
• Code note: descending order

fn main() {
	mut i := [3, 2, 8, 1]
	i.sort()
	// ascending order
	println(i)
	i.sort(a > b)
	// descending order
	println(i)
}

Sort String Array

In plain words: Calling .sort() on a changeable (mut) list of strings puts them in alphabetical order (A to Z), or reverse alphabetical order with .sort(a > b).

What happens in this example:

• Code note: ascending order
• Code note: reverse order

fn main() {
	mut fruits := ['Apples', 'avocado', 'banana', 'Orange']

	fruits.sort()
	// ascending order
	println(fruits)
	fruits.sort(a > b)
	// reverse order
	println(fruits)
}

Sort Struct Array

In plain words: When you have a list of custom structs (like User), you tell .sort(...) which field to compare—for example, users.sort(a.age < b.age) sorts users from youngest to oldest!

What happens in this example:

• Code note: Declare an empty array
• Code note: Create students
• Code note: Append all the students to the array
• Code note: Reverse Sort students by id

module main

struct Student {
	id    int
	name  string
	class int
}

fn main() {
	// Declare an empty array
	mut students := []Student{}

	// Create students
	st1 := Student{
		id:    1
		name:  'Ram'
		class: 9
	}
	st2 := Student{
		id:    2
		name:  'Katy'
		class: 3
	}
	st3 := Student{
		id:    3
		name:  'Tom'
		class: 6
	}

	// Append all the students to the array
	students << [st1, st2, st3]
	println(students)

	// Reverse Sort students by id
	students.sort(a.id > b.id)

	println('Students sorted in reverse order of id:')
	println(students)

	// Sort students by class in ascending order
	students.sort(a.class < b.class)

	println('Students sorted in ascending order of class:')
	println(students)

	// Sort students by name in reverse order
	students.sort(a.name > b.name)

	println('Students sorted in reverse order of name:')
	println(students)
}

Filter Array

In plain words: .filter(...) creates a new list keeping only the items that pass your test. Inside .filter(...), the special variable it stands for the current item being checked (like nums.filter(it > 10)).

What happens in this example:

• Code note: [3, 6, 9]

fn main() {
	f := [1, 2, 3, 4, 5, 6, 7, 8, 9]
	multiples_of_3 := f.filter(it % 3 == 0)
	println(multiples_of_3)
	// [3, 6, 9]
}

Filter With Anonymous Funcs On Array

In plain words: Instead of using it, you can pass a custom helper function (fn (x int) bool { ... }) into .filter(...) when your filtering rule needs more than a quick one-liner.

What happens in this example:

• Creates helper function(s)/method(s): bool.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	fruits := ['apple', 'mango', 'water melon', 'musk melon']

	fruits_starting_m := fruits.filter(fn (f string) bool {
		return f.starts_with('m')
	})

	println(fruits_starting_m)
}

Map Array Items

In plain words: .map(...) transforms every item in a list into something new (using it for each item)—for example, nums.map(it * 2) returns a new list where every number is doubled!

What happens in this example:

• Prints the result to the terminal window so you can see the output right away.

fn main() {
	visitor := ['Tom', 'Ram', 'Rao']
	res := visitor.map('Mr. ' + it)
	println(res)
}

Map Using Anonymous Funcs On Array

In plain words: You can also pass an anonymous function (fn (x string) string { ... }) inside .map(...) to transform each item in an array step by step.

What happens in this example:

• Creates helper function(s)/method(s): int.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	colors := ['red', 'blue', 'green', 'white', 'black']

	colors_with_letter_e := colors.map(fn (c string) int {
		if c.contains('e') { return 1 } else { return 0 }
	})

	println(colors_with_letter_e)
}

Array Methods

In plain words: V arrays include convenient everyday methods like .reverse(), .first(), .last(), .pop(), .delete(), .insert(), .any(), and .all().

What happens in this example:

• Code note: A custom comparison function for sorting.
• Code note: It accepts references to elements (e.g. &int) and returns -1, 1, or 0.
• Code note: 1. ensure_cap(required)
• Code note: Ensures that the array has at least the specified capacity.

module main

// A custom comparison function for sorting.
// It accepts references to elements (e.g. &int) and returns -1, 1, or 0.
fn compare_ints(a &int, b &int) int {
	val_a := *a
	val_b := *b
	if val_a < val_b {
		return -1
	}
	if val_a > val_b {
		return 1
	}
	return 0
}

fn main() {
	println('--- Array Built-in Methods ---')

	// 1. ensure_cap(required)
	// Ensures that the array has at least the specified capacity.
	mut a := [10, 20, 30]
	a.ensure_cap(10)
	println('ensure_cap: cap is ${a.cap >= 10}') // true

	// 2. repeat(count)
	// Repeats the array count times and returns a new array.
	rep := a.repeat(2)
	println('repeat: ${rep}') // [10, 20, 30, 10, 20, 30]

	// 3. repeat_to_depth(count, depth) (unsafe)
	// Recursively repeats a multi-dimensional array count times to the specified depth.
	grid := [[1, 2], [3, 4]]
	unsafe {
		rep_grid := grid.repeat_to_depth(2, 1)
		// Cast the raw array struct back to typed [][]int
		typed_grid := *(&[][]int(&rep_grid))
		println('repeat_to_depth: ${typed_grid}') // [[1, 2], [3, 4], [1, 2], [3, 4]]
		rep_grid.free()
	}
	// 4. insert(index, val)
	// Inserts a new element at the specified index.
	a.insert(1, 15)
	println('insert: ${a}') // [10, 15, 20, 30]

	// 5. prepend(val)
	// Prepends a new element at the beginning of the array.
	a.prepend(5)
	println('prepend: ${a}') // [5, 10, 15, 20, 30]

	// 6. delete(index)
	// Deletes the element at the specified index.
	a.delete(1) // Deletes index 1 (which is 10)
	println('delete: ${a}') // [5, 15, 20, 30]

	// 7. delete_many(index, size)
	// Deletes size elements starting from the specified index.
	a.delete_many(1, 2) // Deletes 2 elements starting at index 1
	println('delete_many: ${a}') // [5, 30]

	// 8. clear()
	// Sets the array length to 0, retaining capacity.
	mut a_clear := [1, 2, 3]
	a_clear.clear()
	println('clear: len is ${a_clear.len}') // 0

	// 9. reset() (unsafe)
	// Sets all elements of the array to 0 / empty values without altering len or cap.
	mut a_reset := [1, 2, 3]
	unsafe {
		a_reset.reset()
	}
	println('reset: ${a_reset}') // [0, 0, 0]
	unsafe {
		a_reset.free()
	}

	// 10. trim(index)
	// Truncates the array length to index.
	mut a_trim := [1, 2, 3, 4]
	a_trim.trim(2)
	println('trim: ${a_trim}') // [1, 2]

	// 11. drop(num)
	// Drops the first num elements in-place.
	mut a_drop := [1, 2, 3, 4]
	a_drop.drop(2)
	println('drop: ${a_drop}') // [3, 4]

	// 12. first()
	// Returns the first element of the array.
	println('first: ${a_drop.first()}') // 3

	// 13. last()
	// Returns the last element of the array.
	println('last: ${a_drop.last()}') // 4

	// 14. pop_left()
	// Removes and returns the first element of the array.
	mut a_pop := [1, 2, 3]
	first_val := a_pop.pop_left()
	println('pop_left: value = ${first_val}, array = ${a_pop}') // 1, [2, 3]

	// 15. pop()
	// Removes and returns the last element of the array.
	last_val := a_pop.pop()
	println('pop: value = ${last_val}, array = ${a_pop}') // 3, [2]

	// 16. delete_last()
	// Deletes the last element of the array.
	mut a_del_last := [1, 2, 3]
	a_del_last.delete_last()
	println('delete_last: ${a_del_last}') // [1, 2]

	// 17. clone()
	// Returns a deep copy of the array.
	a_clone := a_del_last.clone()
	println('clone: ${a_clone}') // [1, 2]

	// 18. clone_to_depth(depth) (unsafe)
	// Recursively clones a multi-dimensional array up to the specified depth.
	grid2 := [[1, 2], [3, 4]]
	unsafe {
		grid_clone := grid2.clone_to_depth(1)
		typed_clone := *(&[][]int(&grid_clone))
		println('clone_to_depth: ${typed_clone}') // [[1, 2], [3, 4]]
		grid_clone.free()
	}
	// 19. push_many(val, size) (unsafe)
	// Appends size elements starting from a raw pointer val to the array.
	mut a_push := [1, 2]
	vals := [3, 4]
	unsafe {
		a_push.push_many(vals.data, 2)
	}
	println('push_many: ${a_push}') // [1, 2, 3, 4]
	unsafe {
		a_push.free()
		vals.free()
	}
	// 20. reverse()
	// Returns a new reversed copy of the array.
	a_rev := [1, 2, 3]
	println('reverse: ${a_rev.reverse()}') // [3, 2, 1]

	// 21. reverse_in_place()
	// Reverses the array elements in-place.
	mut a_rev_ip := [1, 2, 3]
	a_rev_ip.reverse_in_place()
	println('reverse_in_place: ${a_rev_ip}') // [3, 2, 1]

	// 22. free() (unsafe)
	// Deallocates the array's buffer.
	mut a_free := [1, 2, 3]
	unsafe {
		a_free.free()
	}
	println('free: array freed')

	// 23. filter(it)
	// Filters elements that satisfy a predicate using compiler-defined `it` expression.
	a_filt := [1, 2, 3, 4]
	filtered := a_filt.filter(it % 2 == 0)
	println('filter: ${filtered}') // [2, 4]

	// 24. any(it)
	// Checks if any element satisfies the predicate.
	println('any: ${a_filt.any(it > 3)}') // true

	// 25. count(it)
	// Counts how many elements satisfy the predicate.
	println('count: ${a_filt.count(it % 2 == 0)}') // 2

	// 26. all(it)
	// Checks if all elements satisfy the predicate.
	println('all: ${a_filt.all(it > 0)}') // true

	// 27. map(it)
	// Maps elements to a new array using a transformation expression.
	mapped := a_filt.map(it * 10)
	println('map: ${mapped}') // [10, 20, 30, 40]

	// 28. sort() & sort(custom)
	// Sorts elements in-place. Uses optional boolean expression for custom order (uses magic vars a and b).
	mut a_sort := [3, 1, 4, 2]
	a_sort.sort()
	println('sort (default ascending): ${a_sort}') // [1, 2, 3, 4]
	a_sort.sort(a > b)
	println('sort (custom descending): ${a_sort}') // [4, 3, 2, 1]

	// 29. sorted() & sorted(custom)
	// Returns a sorted copy of the array. Uses optional boolean expression for custom order (uses magic vars a and b).
	a_sorted := [3, 1, 4, 2]
	println('sorted (default): ${a_sorted.sorted()}') // [1, 2, 3, 4]
	println('sorted (custom): ${a_sorted.sorted(a > b)}') // [4, 3, 2, 1]

	// 30. sort_with_compare(callback)
	// Sorts the array in-place using a custom comparison function.
	mut a_compare := [3, 1, 4, 2]
	a_compare.sort_with_compare(compare_ints)
	println('sort_with_compare: ${a_compare}') // [1, 2, 3, 4]

	// 31. sorted_with_compare(callback)
	// Returns a sorted copy of the array using a custom comparison function.
	a_sorted_comp := [3, 1, 4, 2]
	println('sorted_with_compare: ${a_sorted_comp.sorted_with_compare(compare_ints)}') // [1, 2, 3, 4]

	// 32. contains(value)
	// Checks if the array contains value.
	println('contains: ${a_filt.contains(3)}') // true

	// 33. index(value)
	// Returns the index of the first occurrence of value, or -1 if not found.
	println('index: ${a_filt.index(3)}') // 2

	// 34. last_index(value)
	// Returns the index of the last occurrence of value, or -1 if not found.
	a_dup := [1, 2, 3, 2]
	println('last_index: ${a_dup.last_index(2)}') // 3

	// 35. grow_cap(amount)
	// Increases the array capacity by the specified amount.
	mut a_grow := [1, 2]
	a_grow.grow_cap(10)
	println('grow_cap: cap is ${a_grow.cap >= 12}') // true

	// 36. grow_len(amount) (unsafe)
	// Increases the array length by the specified amount.
	unsafe {
		a_grow.grow_len(3)
	}
	println('grow_len: ${a_grow}') // [1, 2, 0, 0, 0]
	unsafe {
		a_grow.free()
	}

	// 37. pointers() (unsafe)
	// Returns an array of void pointers (pointers()) pointing to each element.
	a_ptrs := [10, 20]
	unsafe {
		ptrs := a_ptrs.pointers()
		println('pointers (first element): ${*(&int(ptrs[0]))}') // 10
		ptrs.free()
		a_ptrs.free()
	}
}

Array Update Syntax

In plain words: Using [...old_array, new_item] creates a new array that copies all items from old_array and tacks on additional items.

V lets you initialise an array by spreading an existing array (using ellipsis spread syntax ...), optionally followed by additional elements.

module main

fn main() {
	println('=== Array Update Syntax ===')

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

	println('base: ${base}') // [1, 2]
	println('a: ${a}')       // [1, 2, 3, 4]

	assert base == [1, 2]
	assert a == [1, 2, 3, 4]
}

Maps

Explicit Map Initialization

In plain words: To create an empty map (key-value dictionary), write map[KeyType]ValueType{}—for example, mut ages := map[string]int{} maps text names (string) to whole-number ages (int).

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut books := map[string]int{}
	books['V on Wheels'] = 320
	books['Go for Dummies'] = 279

	println(books)
}

Short Syntax Initialization Of Map

In plain words: When you already know the starting key-value pairs, you can create a map with the short { 'key': value } syntax—just like a mini dictionary!

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut student_1 := {
		'english':     90
		'mathematics': 96
		'physics':     83
		'chemistry':   89
	}
	println(student_1)
}

Count Key Value Pairs In Map

In plain words: Checking .len on a map tells you how many key: value pairs are currently stored inside it.

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut student_1 := {
		'english':     90
		'mathematics': 96
		'physics':     83
		'chemistry':   89
	}
	cnt := student_1.len
	println('There are ${cnt} key-value pairs in student_1 map')
}

Value Given Key Of Map

In plain words: You look up a value in a map by putting its key inside square brackets: my_map['key'].

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut student_1 := {
		'english':     90
		'mathematics': 96
		'physics':     83
		'chemistry':   89
	}

	println(student_1['physics']) // 83
}

Value Given Non Existent Key Of Map

In plain words: If you look up a key that isn't in the map yet, V safely gives you the default zero/empty value for that type (0 for numbers, '' for strings) instead of crashing!

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut student_1 := {
		'english':     90
		'mathematics': 96
		'physics':     83
		'chemistry':   89
	}

	println(student_1['geography']) // 0
}

Handling Missing Keys In Map

In plain words: To tell the difference between a key whose value is 0 and a key that doesn't exist at all, use key in my_map or attach an or { ... } block to my_map[key]!

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Includes an or { ... } safety block to handle potential errors or missing values calmly.

fn main() {
	mut student_1 := {
		'english':     90
		'mathematics': 96
		'physics':     83
		'chemistry':   89
	}

	sub := 'geography'
	res := student_1[sub] or { panic('marks for subject ${sub} not yet updated') } // throws error
}

Update Value Given A Key In Map

In plain words: On a changeable (mut) map, my_map['key'] = new_value adds the key if it is new, or updates its value if the key is already there.

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut student_1 := {
		'english':     90
		'mathematics': 96
		'physics':     83
		'chemistry':   89
	}
	student_1['english'] = 93
	println(student_1)
}

Delete Key Value Pair From Map

In plain words: Calling my_map.delete('key') removes that key and its value from a changeable (mut) map.

What happens in this example:

• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn main() {
	mut student_1 := {
		'english':     90
		'mathematics': 96
		'physics':     83
		'chemistry':   89
	}

	println('Key-Value pairs before deleting a key: ${student_1.len}')
	student_1.delete('physics')
	println('Key-Value pairs after deleting a key ${student_1.len}')
}

Map Methods

In plain words: Maps provide helpful methods like .keys() (get a list of all keys), .values() (get a list of all values), .clone() (make an independent copy), and .clear().

What happens in this example:

• Code note: 1. keys()
• Code note: Returns an array containing all keys in the map.
• Code note: 2. values()
• Code note: Returns an array containing all values in the map.

module main

fn main() {
	println('--- Map Built-in Methods ---')

	mut m := {
		'one': 1
		'two': 2
	}
	println('initial map: ${m}') // {"one": 1, "two": 2}

	// 1. keys()
	// Returns an array containing all keys in the map.
	println('keys: ${m.keys()}') // ["one", "two"]

	// 2. values()
	// Returns an array containing all values in the map.
	println('values: ${m.values()}') // [1, 2]

	// 3. clone()
	// Returns a deep copy of the map.
	mut m_clone := m.clone()
	println('clone: ${m_clone}') // {"one": 1, "two": 2}

	// 4. delete(key)
	// Removes a key-value pair from the map by key.
	m.delete('one')
	println('delete: ${m}') // {"two": 2}

	// 5. reserve(capacity)
	// Pre-allocates space for at least capacity elements in the map.
	m.reserve(10)
	println('reserve: reserved capacity successfully')

	// 6. clear()
	// Removes all key-value pairs from the map without deallocating data.
	m.clear()
	println('clear: len is ${m.len}') // 0

	// 7. move()
	// Moves the map contents to a new map variable and clears the original map to empty.
	mut m_move := {
		'three': 3
		'four':  4
	}
	moved := m_move.move()
	println('move (new map): ${moved}') // {"three": 3, "four": 4}
	println('move (original map): ${m_move}') // {}

	// 8. free() (unsafe)
	// Deallocates the map memory.
	mut m_free := {
		'temp': 100
	}
	unsafe {
		m_free.free()
	}
	println('free: map freed successfully')
}

Import Maps Helpers

In plain words: The standard maps module (import maps) adds extra power tools for filtering, transforming (to_array), inverting, and merging maps.

The maps module provides higher-level helpers for filtering, transforming, inverting, merging, and converting between maps and arrays. These helpers are useful when you want to work with map data in a functional style without manually writing the loops yourself.

module main

import maps

fn main() {
	println('--- Import Maps Module Helpers ---')

	// Start with a simple map of fruit counts.
	m1 := {
		'apple':  1
		'banana': 2
		'cherry': 3
	}

	// filter() keeps only the entries that satisfy the callback condition.
	filtered := maps.filter(m1, fn (k string, v int) bool {
		return v > 1
	})
	println('filter(): ${filtered}')

	// to_array() builds a new array by transforming each entry.
	keys_upper := maps.to_array(m1, fn (k string, v int) string {
		return k.to_upper()
	})
	println('to_array(): ${keys_upper}')

	// invert() swaps each key/value pair so the values become the keys.
	inverted := maps.invert(m1)
	println('invert(): ${inverted}')

	// from_array() creates a map from a list of strings.
	fruits := ['apple', 'banana', 'cherry']
	map_from_arr := maps.from_array(fruits)
	println('from_array(): ${map_from_arr}')

	// merge() combines two maps and lets the second map override duplicates.
	m2 := {
		'banana': 20
		'date':   4
	}
	merged := maps.merge(m1, m2)
	println('merge(): ${merged}')

	// merge_in_place() mutates the first map directly.
	mut mut_map := {
		'a': 1
	}
	maps.merge_in_place(mut mut_map, {
		'b': 2
		'c': 3
	})
	println('merge_in_place(): ${mut_map}')

	// flat_map() can expand each entry into multiple output values.
	flat_items := maps.flat_map[string, int, string](m1, fn (k string, v int) []string {
		return [k, v.str()]
	})
	println('flat_map(): ${flat_items}')

	// to_map() transforms each entry into a new key/value pair.
	transformed := maps.to_map[string, int, string, int](m1, fn (k string, v int) (string, int) {
		return k.to_upper(), v * 10
	})
	println('to_map(): ${transformed}')
}

Map Update Syntax

In plain words: Using { ...old_map, 'key': new_val } creates a fresh copy of old_map with specific keys added or updated.

Similar to structs, V lets you initialise a new map with updates applied on top of an existing map using the spread syntax .... This is functionally equivalent to cloning the map and updating it, except that it avoids declaring a mutable intermediate variable and allows inlining elements.

module main

fn main() {
	println('=== Map Update Syntax ===')

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

	// Create a new map by updating elements of base_map
	foo := {
		...base_map
		'b': 88
		'c': 99
	}

	println('base_map: ${base_map}') // {'a': 4, 'b': 5}
	println('foo: ${foo}')           // {'a': 4, 'b': 88, 'c': 99}
	
	assert base_map['b'] == 5
	assert foo['a'] == 4
	assert foo['b'] == 88
	assert foo['c'] == 99
}

Chapter 6 Functions

Functions let you turn repeated or complex logic into small, named building blocks. A useful mental model is: define the task, give it inputs if needed, do the work, and return a useful result. This chapter starts with simple functions and then introduces multiple returns, optional results, higher-order functions, and cleanup with defer.

fn divide(a int, b int) (int, int) {
    return a / b, a % b
}

typedef struct { int arg0; int arg1; } MultiReturn_int_int;

multiplier := 3
triple := fn [multiplier] (x int) int {
    return x * multiplier
}

Advanced Function Features

Function Returns Value Example 1

In plain words: When a function calculates an answer, put the answer's type after the (...) parameters and use return to hand that value back to the caller.

A simple function is a small helper that turns inputs into a useful result. The basic pattern is: define the function, pass in values, do some work, and return the answer. In this example, add takes two integers and returns their sum.

fn add(a int, b int) int {
	return a + b
}

fn main() {
	println(add(2, 3))
}

Function Returns Value Example 2

In plain words: A function can check conditions and return early with an answer as soon as its work is done.

A function does not need to print anything itself. It can build a value and hand it back to the caller. Here, say_hello returns a greeting string, and main decides how to display it.

What happens in this example:

• Code note: call the method
• Code note: prints: Hello!

fn say_hello() string {
	return 'Hello!'
}

fn main() {
	// call the method
	res := say_hello()
	println(res)
	// prints: Hello!
}

Functions Without Return Type

In plain words: If a function just performs an action (like printing a message) and doesn't need to hand back a value, simply leave off the return type after (...).

Some functions are used for actions rather than calculations. They may print output, write files, or update state. In that case, you can leave out the return type and focus on the side effect.

What happens in this example:

• Code note: prints: Hello!

fn console_greeter() {
	println('Hello!')
}

fn main() {
	console_greeter()
	// prints: Hello!
}

Function With Input Arguments

In plain words: You pass inputs (arguments) into a function by listing each input's name and type inside the parentheses: fn add(x int, y int) int.

Functions become much more useful when they accept inputs. This example uses two numbers as arguments and returns their sum, showing the classic input → process → output flow.

What happens in this example:

• Code note: prints: 6

fn add(a int, b int) int {
	return a + b
}

fn main() {
	res := add(2, 4)
	println(res)
	// prints: 6
}

Function Return Multiple Values

In plain words: In V, a single function can return two or more values at once by wrapping the return types in parentheses, like fn stats() (int, int).

In V, functions are not limited to returning a single value. A function can return a tuple containing two or more values when they logically belong together. A very common pattern in systems programming is returning both the main result of an operation and a secondary value (such as status flags, byte counts, or errors). Returning multiple values is clean, avoids wrapping results in temporary struct containers, and is assigned using parallel declaration at the call site.

This example shows how a function computes a string greeting and returns both the greeting string and its length as an integer.

// The return types are declared within parentheses: (string, int)
fn greet_and_message_length(name string) (string, int) {
	mut greeting := 'Hello, ' + name + '!'
	// Multiple values are returned as a comma-separated list
	return greeting, greeting.len
}

fn main() {
	// Receive multiple return values using parallel assignment
	i, j := greet_and_message_length('Navule')
	println(i) // Prints: Hello, Navule!
	println(j) // Prints the length: 14
}

Ignore Function Return Value

In plain words: When a function returns multiple values and you only need one of them, put an underscore _ in place of the value you want to ignore: first, _ := get_pair().

Sometimes you only care about one returned value. V lets you ignore the rest with _, which keeps the code readable when you are only interested in part of the result.

What happens in this example:

• Creates helper function(s)/method(s): greet_and_message_length.
• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn greet_and_message_length(name string) (string, int) {
	mut greeting := 'Hello, ' + name + '!'
	return greeting, greeting.len
}

fn main() {
	i, _ := greet_and_message_length('Navule')
	println(i)
}

Function Calls Other Function

In plain words: Big problems become easy when you break them into small helper functions that call each other step by step.

Functions can call other functions to split a bigger problem into smaller steps. This makes the code easier to understand and easier to reuse later.

What happens in this example:

• Creates helper function(s)/method(s): greet, welcome.
• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn greet(p string) string {
	return 'Hello, ${p}!'
}

fn welcome(p string) string {
	msg := 'Nice to meet you!'
	mut g := greet(p)
	g = g + ' ${msg}'
	return g
}

fn main() {
	res := welcome('Visitor')
	println(res)
}

Example 1

In plain words: You can pass any V type—numbers, strings, arrays, maps, structs, or even other functions—into a function as an input parameter.

What happens in this example:

• Creates helper function(s)/method(s): increment_array_items.
• Uses mut so the variable or collection is allowed to be updated after creation.
• Prints the result to the terminal window so you can see the output right away.

fn increment_array_items(arr []int, inc int) []int {
	mut tmp := arr.clone()
	for mut i in tmp {
		i += inc
	}
	return tmp
}

fn main() {
	a := [5, 6]

	res := increment_array_items(a, 100)

	println('a: ${a}')
	println('res: ${res}')
}

Example 2

In plain words: You can pass any V type—numbers, strings, arrays, maps, structs, or even other functions—into a function as an input parameter.

What happens in this example:

• Code note: Must specify mut keyword when sending value to mut arg of a function

fn increment_array_items(mut arr []int, inc int) {
	for mut i in arr {
		i += inc
	}
}

fn main() {
	mut a := [5, 6]
	increment_array_items(mut a, 100)
	// Must specify mut keyword when sending value to mut arg of a function
	println('a: ${a}')
}

Error Script Functions

In plain words: In V shell scripts (.vsh files), any helper functions you write (fn ...) should be placed before the top-level script statements that call them.

What happens in this example:

• Creates helper function(s)/method(s): log.
• Prints the result to the terminal window so you can see the output right away.

#!/usr/local/bin/v run

cnt := 2

for i in 0 .. cnt {
	log('iteration ${i}')
}

fn log(msg string) {
	println(msg)
}

Script Functions

In plain words: In V shell scripts (.vsh files), any helper functions you write (fn ...) should be placed before the top-level script statements that call them.

What happens in this example:

• Creates helper function(s)/method(s): log.
• Prints the result to the terminal window so you can see the output right away.

#!/usr/local/bin/v run

fn log(msg string) {
	println(msg)
}

cnt := 2

for i in 0 .. cnt {
	log('iteration ${i}')
}

Functions Module Variables - Main (main.v)

In plain words: Because V avoids hidden global variables, functions share fixed values across a module using module-level const blocks or by passing structs/values as function inputs.

What happens in this example:

• Code note: file: main.v

// file: main.v
module main

import mymod

fn main() {
	mymod.msg := 'global variable demo'
	println(mymod.msg)
}

Mymod

In plain words: Because V avoids hidden global variables, functions share fixed values across a module using module-level const blocks or by passing structs/values as function inputs.

What happens in this example:

• Code note: file: mymod/mymod.v

// file: mymod/mymod.v
module mymod

__global (
	msg string
)

Functions With Optional Return Types Example 1

In plain words: Putting ? in front of a function's return type (like ?int or ?string) means the function might return a real value OR none if nothing was found.

What happens in this example:

• Creates helper function(s)/method(s): is_teen.
• Includes an or { ... } safety block to handle potential errors or missing values calmly.
• Prints the result to the terminal window so you can see the output right away.

module main

fn is_teen(age int) ?string {
	if age < 0 {
		return none
	} else if age >= 13 && age <= 19 {
		return 'teenager'
	} else {
		return 'not teenager'
	}
}

fn main() {
	x := is_teen(-3) or { 'invalid age provided' }
	println(x)
}

Function With Optional Return Type Example 2

In plain words: Putting ? in front of a function's return type (like ?int or ?string) means the function might return a real value OR none if nothing was found.

What happens in this example:

• Creates helper function(s)/method(s): is_teen.
• Includes an or { ... } safety block to handle potential errors or missing values calmly.
• Prints the result to the terminal window so you can see the output right away.

module main

fn is_teen(age int) !string {
	if age < 0 {
		return error('invalid age provided')
	} else if age >= 13 && age <= 19 {
		return 'teenager'
	} else {
		return 'not teenager'
	}
}

fn main() {
	x := is_teen(-3) or { err.msg() }
	println(x)
}

Mod1

In plain words: Functions without pub can only be called by files in the same folder. Adding pub fn unlocks the function so other modules that import this folder can call it.

What happens in this example:

• Code note: file: mod1/mod1.v

// file: mod1/mod1.v
module mod1

fn greet1() string {
	return 'Hello from greet1'
}

pub fn greet2() string {
	return 'Hello from greet2'
}

pub fn greet_and_wish() string {
	wish := 'Have a nice day!'
	return greet1() + ', ' + wish
}

Public Function Demo1

In plain words: Functions without pub can only be called by files in the same folder. Adding pub fn unlocks the function so other modules that import this folder can call it.

What happens in this example:

• Code note: file: publicfunctiondemo1.v

// file: public_function_demo1.v
import mod1

fn main() {
	g := mod1.greet1()
	println(g)
}

Public Function Demo2

In plain words: Functions without pub can only be called by files in the same folder. Adding pub fn unlocks the function so other modules that import this folder can call it.

What happens in this example:

• Code note: file: publicfunctiondemo2.v

// file: public_function_demo2.v
import mod1

fn main() {
	g := mod1.greet2()
	println(g)
}

Public Function Demo3

In plain words: Functions without pub can only be called by files in the same folder. Adding pub fn unlocks the function so other modules that import this folder can call it.

What happens in this example:

• Code note: file: publicfunctiondemo3.v

// file: public_function_demo3.v
import mod1

fn main() {
	g := mod1.greet_and_wish()
	println(g)
}

Function With Defer Block

In plain words: Code inside a defer { ... } block waits patiently and runs automatically right when the current function finishes—perfect for closing files or connections so you never forget.

The defer keyword is a crucial feature for resource safety and cleanups. A defer block schedules a block of code to run automatically right before the containing function exits, regardless of which return path is taken. If there are multiple defer blocks in a function, they are executed in reverse order of their declaration (Last-In, First-Out). This ensures resources (like file descriptors, database connections, or socket connections) are closed safely without duplicating cleanup code across every return statement.

This example illustrates the execution sequence of statements inside a function containing a defer block.

module main

fn void_func_defer() {
	println('Hello')
	
	// This block is scheduled to execute at the very end of the function scope.
	defer {
		println('Hi from defer block')
	}
	
	println('How are you?')
	// The function ends here, triggering the deferred block execution automatically.
}

fn main() {
	void_func_defer()
}

Functions As Elements Of Array Or Map

In plain words: In V, functions are first-class values: you can store functions inside an array or a map and call them dynamically!

Functions can be stored in arrays and maps just like other values. This allows you to choose an operation dynamically at runtime, which is helpful in flexible programs.

What happens in this example:

• Creates helper function(s)/method(s): adder, subtractor, multiplier.
• Prints the result to the terminal window so you can see the output right away.

module main

fn adder(i int, j int) int {
	return i + j
}

fn subtractor(i int, j int) int {
	return i - j
}

fn multiplier(i int, j int) int {
	return i * j
}

fn main() {
	i, j := 2, 5
	println('Functions as elements of an Array')
	funcs := [adder, subtractor, multiplier]

	for f in funcs {
		res := f(i, j)
		println(res)
	}
	println('Functions as elements of Map')
	d := {
		'sum':        adder
		'difference': subtractor
		'product':    multiplier
	}

	for key, val in d {
		res := val(i, j)
		println('${key} of ${i} and ${j}: ${res}')
	}
}

Function Extras

Hello

In plain words: fn main() is the front door of every V program—when you run your app, execution always starts right here.