builtin #

Description

builtin is a module that is implicitly imported by every V program.

It implements the builtin V types array, string, map.

It also implements builtin functions like println, eprintln, malloc, panic, print_backtrace.

The autogenerated documentation for builtin functions is lacking, so for these functions, please refer to the official V documentation.

fn C.android_print(fstream voidptr, format &char, opt ...voidptr)

used by Android for (e)println to output to the Android log system / logcat

fn arguments() []string

arguments returns the command line arguments, used for starting the current program as a V array of strings. The first string in the array (index 0), is the name of the program, used for invoking the program. The second string in the array (index 1), if it exists, is the first argument to the program, etc. For example, if you started your program as myprogram -option, then arguments() will return ['myprogram', '-option'].

Note: if you v run file.v abc def, then arguments() will return ['file', 'abc', 'def'], or ['file.exe', 'abc', 'def'] (on Windows).

fn at_exit(cb FnExitCb) !

at_exit registers a fn callback, that will be called at normal process termination. It returns an error, if the registration was not successful. The registered callback functions, will be called either via exit/1, or via return from the main program, in the reverse order of their registration. The same fn may be registered multiple times. Each callback fn will called once for each registration.

fn c_error_number_str(errnum int) string

return a C-API error message matching to errnum

fn compare_strings(a &string, b &string) int

compare_strings returns -1 if a < b, 1 if a > b else 0.

fn copy(mut dst []u8, src []u8) int

copy copies the src byte array elements to the dst byte array. The number of the elements copied is the minimum of the length of both arrays. Returns the number of elements copied.

Note: This is not an array method. It is a function that takes two arrays of bytes. See also: arrays.copy.

fn cstring_to_vstring(const_s &char) string

cstring_to_vstring creates a new V string copy of the C style string, pointed by s. This function is most likely what you want to use when working with C style pointers to 0 terminated strings (i.e. char*). It is recommended to use it, unless you do understand the implications of tos/tos2/tos3/tos4/tos5 in terms of memory management and interactions with -autofree and @[manualfree]. It will panic, if the pointer s is 0.

fn eprint(s string)

eprint prints a message to stderr. Both stderr and stdout are flushed.

fn eprintln(s string)

eprintln prints a message with a line end, to stderr. Both stderr and stdout are flushed.

fn error(message string) IError

error returns a default error instance containing the error given in message.

if ouch { return error('an error occurred') }

fn error_with_code(message string, code int) IError

error_with_code returns a default error instance containing the given message and error code.

if ouch { return error_with_code('an error occurred', 1) }

fn exit(code int)

exit terminates execution immediately and returns exit code to the shell.

fn f32_abs(a f32) f32

f32_abs returns the absolute value of a as a f32 value.

assert f32_abs(-2.0) == 2.0

fn f32_max(a f32, b f32) f32

f32_max returns the largest f32 of input a and b.

assert f32_max(2.0,3.0) == 3.0

fn f32_min(a f32, b f32) f32

f32_min returns the smallest f32 of input a and b.

assert f32_min(2.0,3.0) == 2.0

fn f64_max(a f64, b f64) f64

f64_max returns the largest f64 of input a and b.

assert f64_max(2.0,3.0) == 3.0

fn flush_stderr()

fn flush_stdout()

fn free(ptr voidptr)

free allows for manually freeing memory allocated at the address ptr.

fn gc_check_leaks()

for leak detection it is advisable to do explicit garbage collections

fn gc_collect()

gc_collect explicitly performs a single garbage collection run. Note, that garbage collections, are done automatically, when needed in most cases, so usually you should NOT need to call gc_collect() often. Note that gc_collect() is a NOP with -gc none.

fn gc_disable()

gc_disable explicitly disables the GC. Do not forget to enable it again by calling gc_enable(), when your program is otherwise idle, and can afford it. See also gc_enable() and gc_collect(). Note that gc_disable() is a NOP with -gc none.

fn gc_enable()

gc_enable explicitly enables the GC. Note, that garbage collections are done automatically, when needed in most cases, and also that by default the GC is on, so you do not need to enable it. See also gc_disable() and gc_collect(). Note that gc_enable() is a NOP with -gc none.

fn gc_get_warn_proc() FnGC_WarnCB

gc_get_warn_proc returns the current callback fn, that will be used for printing GC warnings

fn gc_heap_usage() GCHeapUsage

gc_heap_usage returns the info about heap usage

fn gc_is_enabled() bool

gc_is_enabled() returns true, if the GC is enabled at runtime. See also gc_disable() and gc_enable().

fn gc_memory_use() usize

gc_memory_use returns the total memory use in bytes by all allocated blocks

fn gc_set_warn_proc(cb FnGC_WarnCB)

gc_set_warn_proc sets the callback fn, that will be used for printing GC warnings

fn get_str_intp_u32_format(fmt_type StrIntpType, in_width int, in_precision int, in_tail_zeros bool,
	in_sign bool, in_pad_ch u8, in_base int, in_upper_case bool) u32

convert from data format to compact u32

fn get_str_intp_u64_format(fmt_type StrIntpType, in_width int, in_precision int, in_tail_zeros bool,
	in_sign bool, in_pad_ch u8, in_base int, in_upper_case bool) u64

convert from data format to compact u64

fn input_character() int

input_character gives back a single character, read from the standard input. It returns -1 on error (when the input is finished (EOF), on a broken pipe etc).

fn int_max(a int, b int) int

int_max returns the largest int of input a and b.

assert int_max(2,3) == 3

fn int_min(a int, b int) int

int_min returns the smallest int of input a and b.

assert int_min(2,3) == 2

fn isnil(v voidptr) bool

isnil returns true if an object is nil (only for C objects).

fn malloc(n isize) &u8

malloc dynamically allocates a n bytes block of memory on the heap. malloc returns a byteptr pointing to the memory address of the allocated space. unlike the calloc family of functions - malloc will not zero the memory block.

fn malloc_noscan(n isize) &u8

fn malloc_uncollectable(n isize) &u8

malloc_uncollectable dynamically allocates a n bytes block of memory on the heap, which will NOT be garbage-collected (but its contents will).

fn memdup(src voidptr, sz isize) voidptr

memdup dynamically allocates a sz bytes block of memory on the heap memdup then copies the contents of src into the allocated space and returns a pointer to the newly allocated space.

fn memdup_noscan(src voidptr, sz isize) voidptr

fn memdup_uncollectable(src voidptr, sz isize) voidptr

memdup_uncollectable dynamically allocates a sz bytes block of memory on the heap, which will NOT be garbage-collected (but its contents will). memdup_uncollectable then copies the contents of src into the allocated space and returns a pointer to the newly allocated space.

fn panic(s string)

panic prints a nice error message, then exits the process with exit code of 1. It also shows a backtrace on most platforms.

fn panic_error_number(basestr string, errnum int)

panic with a C-API error message matching errnum

fn panic_lasterr(base string)

fn panic_option_not_set(s string)

panic_option_not_set is called by V, when you use option error propagation in your main function. It ends the program with a panic.

fn panic_result_not_set(s string)

panic_result_not_set is called by V, when you use result error propagation in your main function It ends the program with a panic.

fn print(s string)

print prints a message to stdout. Note that unlike eprint, stdout is not automatically flushed.

fn print_backtrace()

print_backtrace shows a backtrace of the current call stack on stdout

fn print_backtrace_skipping_top_frames(xskipframes int) bool

print_backtrace_skipping_top_frames prints the backtrace skipping N top frames

fn print_character(ch u8) int

print_character writes the single character ch to the standard output. It returns -1 on error (when the output is closed, on a broken pipe, etc).

Note: this function does not allocate memory, unlike print(ch.ascii_str()) which does, and is thus cheaper to call, which is important, if you have to output many characters one by one. If you instead want to print entire strings at once, use print(your_string).

fn println(s string)

println prints a message with a line end, to stdout. Note that unlike eprintln, stdout is not automatically flushed.

fn proc_pidpath(int, voidptr, int) int

<libproc.h>

fn ptr_str(ptr voidptr) string

ptr_str returns the address of ptr as a string.

fn realloc_data(old_data &u8, old_size int, new_size int) &u8

realloc_data resizes the memory block pointed by old_data to new_size bytes. old_data must be a pointer to an existing memory block, previously allocated with malloc or vcalloc, of size old_data. realloc_data returns a pointer to the new location of the block.

Note: if you know the old data size, it is preferable to call realloc_data, instead of v_realloc, at least during development, because realloc_data can make debugging easier, when you compile your program with -d debug_realloc.

fn str_intp(data_len int, input_base &StrIntpData) string

interpolation function

fn str_intp_g32(in_str string) string

fn str_intp_g64(in_str string) string

fn str_intp_rune(in_str string) string

fn str_intp_sq(in_str string) string

fn str_intp_sub(base_str string, in_str string) string

replace %% with the in_str

fn string_from_wide(_wstr &u16) string

string_from_wide creates a V string, encoded in UTF-8, given a windows style string encoded in UTF-16. Note that this function first searches for the string terminator 0 character, and is thus slower, while more convenient compared to string_from_wide2/2 (you have to know the length in advance to use string_from_wide2/2). See also builtin.wchar.to_string/1, for a version that eases working with the platform dependent &wchar_t L"" strings.

fn string_from_wide2(_wstr &u16, len int) string

string_from_wide2 creates a V string, encoded in UTF-8, given a windows style string, encoded in UTF-16. It is more efficient, compared to string_from_wide, but it requires you to know the input string length, and to pass it as the second argument. See also builtin.wchar.to_string2/2, for a version that eases working with the platform dependent &wchar_t L"" strings.

fn string_to_ansi_not_null_terminated(_str string) []u8

string_to_ansi_not_null_terminated returns an ANSI version of the string _str.

Note: This is most useful for converting a vstring to an ANSI string under Windows.

Note: The ANSI string return is not null-terminated, then you can use os.write_file_array write an ANSI file.

fn tos(s &u8, len int) string

tos creates a V string, given a C style pointer to a 0 terminated block.

Note: the memory block pointed by s is reused, not copied! It will panic, when the pointer s is 0. See also tos_clone.

fn tos2(s &u8) string

tos2 creates a V string, given a C style pointer to a 0 terminated block.

Note: the memory block pointed by s is reused, not copied! It will calculate the length first, thus it is more costly than tos. It will panic, when the pointer s is 0. It is the same as tos3, but for &u8 pointers, avoiding callsite casts. See also tos_clone.

fn tos3(s &char) string

tos3 creates a V string, given a C style pointer to a 0 terminated block.

Note: the memory block pointed by s is reused, not copied! It will calculate the length first, so it is more costly than tos. It will panic, when the pointer s is 0. It is the same as tos2, but for &char pointers, avoiding callsite casts. See also tos_clone.

fn tos4(s &u8) string

tos4 creates a V string, given a C style pointer to a 0 terminated block.

Note: the memory block pointed by s is reused, not copied! It will calculate the length first, so it is more costly than tos. It returns '', when given a 0 pointer s, it does NOT panic. It is the same as tos5, but for &u8 pointers, avoiding callsite casts. See also tos_clone.

fn tos5(s &char) string

tos5 creates a V string, given a C style pointer to a 0 terminated block.

Note: the memory block pointed by s is reused, not copied! It will calculate the length first, so it is more costly than tos. It returns '', when given a 0 pointer s, it does NOT panic. It is the same as tos4, but for &char pointers, avoiding callsite casts. See also tos_clone.

fn tos_clone(const_s &u8) string

tos_clone creates a new V string copy of the C style string, pointed by s. See also cstring_to_vstring (it is the same as it, the only difference is, that tos_clone expects &u8, while cstring_to_vstring expects &char). It will panic, if the pointer s is 0.

fn unbuffer_stdout()

unbuffer_stdout will turn off the default buffering done for stdout. It will affect all consequent print and println calls, effectively making them behave like eprint and eprintln do. It is useful for programs, that want to produce progress bars, without cluttering your code with a flush_stdout() call after every print() call. It is also useful for programs (sensors), that produce small chunks of output, that you want to be able to process immediately. Note 1: if used, it should be called at the start of your program, before using print or println(). Note 2: most libc implementations, have logic that use line buffering for stdout, when the output stream is connected to an interactive device, like a terminal, and otherwise fully buffer it, which is good for the output performance for programs that can produce a lot of output (like filters, or cat etc), but bad for latency. Normally, it is usually what you want, so it is the default for V programs too. See https://www.gnu.org/software/libc/manual/html_node/Buffering-Concepts.html . See https://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_05 .

fn utf32_decode_to_buffer(code u32, mut buf &u8) int

fn utf32_to_str(code u32) string

Convert utf32 to utf8 utf32 == Codepoint

fn utf32_to_str_no_malloc(code u32, mut buf &u8) string

fn utf8_char_len(b u8) int

utf8_char_len returns the length in bytes of a UTF-8 encoded codepoint that starts with the byte b

fn utf8_str_visible_length(s string) int

Calculate string length for formatting, i.e. number of "characters" This is simplified implementation. if you need specification compliant width, use utf8.east_asian.display_width.

fn v_realloc(b &u8, n isize) &u8

v_realloc resizes the memory block b with n bytes. The b byteptr must be a pointer to an existing memory block previously allocated with malloc or vcalloc. Please, see also realloc_data, and use it instead if possible.

fn vcalloc(n isize) &u8

vcalloc dynamically allocates a zeroed n bytes block of memory on the heap. vcalloc returns a byteptr pointing to the memory address of the allocated space. vcalloc checks for negative values given in n.

fn vcalloc_noscan(n isize) &u8

special versions of the above that allocate memory which is not scanned for pointers (but is collected) when the Boehm garbage collection is used

fn vmemcmp(const_s1 voidptr, const_s2 voidptr, n isize) int

vmemcmp compares the first n bytes (each interpreted as unsigned char) of the memory areas s1 and s2. It returns an integer less than, equal to, or greater than zero, if the first n bytes of s1 is found, respectively, to be less than, to match, or be greater than the first n bytes of s2. For a nonzero return value, the sign is determined by the sign of the difference between the first pair of bytes (interpreted as unsigned char) that differ in s1 and s2. If n is zero, the return value is zero. Do NOT use vmemcmp to compare security critical data, such as cryptographic secrets, because the required CPU time depends on the number of equal bytes. You should use a function that performs comparisons in constant time for this.

fn vmemcpy(dest voidptr, const_src voidptr, n isize) voidptr

vmemcpy copies n bytes from memory area src to memory area dest. The memory areas MUST NOT OVERLAP. Use vmemmove, if the memory areas do overlap. vmemcpy returns a pointer to dest.

fn vmemmove(dest voidptr, const_src voidptr, n isize) voidptr

vmemmove copies n bytes from memory area src to memory area dest. The memory areas MAY overlap: copying takes place as though the bytes in src are first copied into a temporary array that does not overlap src or dest, and the bytes are then copied from the temporary array to dest. vmemmove returns a pointer to dest.

fn vmemset(s voidptr, c int, n isize) voidptr

vmemset fills the first n bytes of the memory area pointed to by s, with the constant byte c. It returns a pointer to the memory area s.

fn vstrlen(s &u8) int

vstrlen returns the V length of the C string s (0 terminator is not counted). The C string is expected to be a &u8 pointer.

fn vstrlen_char(s &char) int

vstrlen_char returns the V length of the C string s (0 terminator is not counted). The C string is expected to be a &char pointer.

fn wide_to_ansi(_wstr &u16) []u8

wide_to_ansi create an ANSI string, given a windows style string, encoded in UTF-16. It use CP_ACP, which is ANSI code page identifier, as dest encoding.

Note: It return a vstring(encoded in UTF-8) []u8 under Linux.

interface IError {
	msg() string
	code() int
}

IError holds information about an error instance

fn (ie &IError) free()

fn (err IError) str() string

str returns the message of IError

type FnExitCb = fn ()

fn (err MessageError) str() string

str returns both the .msg and .code of MessageError, when .code is != 0

fn (err MessageError) msg() string

msg returns only the message of MessageError

fn (err MessageError) code() int

code returns only the code of MessageError

fn (err &MessageError) free()

fn (ra []rune) string() string

string converts a rune array to a string

fn (mut a []string) free()

fn (a []string) join(sep string) string

join joins a string array into a string using sep separator.

assert ['Hello','V'].join(' ') == 'Hello V'

fn (s []string) join_lines() string

join joins a string array into a string using a \n newline delimiter.

fn (mut s []string) sort_by_len()

sort_by_len sorts the string array by each string's .len length.

fn (mut s []string) sort_ignore_case()

sort_ignore_case sorts the string array using case insensitive comparing.

fn (a []string) str() string

str returns a string representation of an array of strings

['a', 'b', 'c'].str() // => "['a', 'b', 'c']".

fn (b []u8) byterune() !rune

byterune attempts to decode a sequence of bytes from utf8 to utf32 and return the result as a rune it will produce an error if there are more than four bytes in the array.

fn (b []u8) bytestr() string

bytestr produces a string from all the bytes in the array.

Note: the returned string will have .len equal to the array.len, even when some of the array bytes were 0. If you want to get a V string, that contains only the bytes till the first 0 byte, use tos_clone(&u8(array.data)) instead.

fn (b []u8) hex() string

hex returns a string with the hexadecimal representation of the byte elements of the array b.

fn (_bytes []u8) utf8_to_utf32() !rune

convert array of utf8 bytes to single utf32 value will error if more than 4 bytes are submitted

fn (b bool) str() string

str returns the value of the bool as a string.

assert (2 > 1).str() == 'true'

fn (nn byteptr) str() string

hex returns the value of the byteptr as a hexadecimal string. Note that the output is not zero padded. pub fn (nn byteptr) str() string {

fn (data byteptr) vbytes(len int) []u8

byteptr.vbytes() - makes a V []u8 structure from a C style memory buffer. Note: the data is reused, NOT copied!

fn (bp byteptr) vstring() string

vstring converts a C style string to a V string. Note: the string data is reused, NOT copied. strings returned from this function will be normal V strings beside that (i.e. they would be freed by V's -autofree mechanism, when they are no longer used).

fn (bp byteptr) vstring_literal() string

vstring_literal converts a C style string to a V string.

Note: the string data is reused, NOT copied. NB2: unlike vstring, vstring_literal will mark the string as a literal, so it will not be freed by autofree. This is suitable for readonly strings, C string literals etc, that can be read by the V program, but that should not be managed by it, for example os.args is implemented using it.

fn (bp byteptr) vstring_literal_with_len(len int) string

vstring_with_len converts a C style string to a V string.

Note: the string data is reused, NOT copied.

fn (bp byteptr) vstring_with_len(len int) string

vstring_with_len converts a C style string to a V string.

Note: the string data is reused, NOT copied.

fn (ch chan) close()

close closes the channel for further push transactions. closed channels cannot be pushed to, however they can be popped from as long as there is still objects available in the channel buffer.

fn (ch chan) try_pop(obj voidptr) ChanState

try_pop returns ChanState.success if an object is popped from the channel. try_pop effectively pops from the channel without waiting for objects to become available. Both the test and pop transaction is done atomically.

fn (ch chan) try_push(obj voidptr) ChanState

try_push returns ChanState.success if the object is pushed to the channel. try_push effectively both push and test if the transaction ch <- a succeeded. Both the test and push transaction is done atomically.

fn (cptr &char) str() string

str returns string equivalent of cptr

fn (cp &char) vstring() string

vstring converts a C style string to a V string.

Note: the memory block pointed by bp is reused, not copied! Strings returned from this function will be normal V strings beside that, (i.e. they would be freed by V's -autofree mechanism, when they are no longer used).

Note: instead of &u8(a.data).vstring(), use tos_clone(&u8(a.data)). See also tos_clone.

fn (cp &char) vstring_literal() string

vstring_literal converts a C style string char* pointer to a V string.

Note: the memory block pointed by bp is reused, not copied! See also byteptr.vstring_literal for more details. See also tos_clone.

fn (cp &char) vstring_literal_with_len(len int) string

vstring_literal_with_len converts a C style string char* pointer, to a V string.

Note: the memory block pointed by bp is reused, not copied! This method has lower overhead compared to .vstring_literal(), since it does not need to calculate the length of the 0 terminated string. See also tos_clone.

fn (cp &char) vstring_with_len(len int) string

vstring_with_len converts a C style 0 terminated string to a V string.

Note: the memory block pointed by bp is reused, not copied! This method has lower overhead compared to .vstring(), since it does not calculate the length of the 0 terminated string. See also tos_clone.

fn (nn charptr) str() string

fn (cp charptr) vstring() string

vstring converts C char* to V string.

Note: the string data is reused, NOT copied.

fn (cp charptr) vstring_literal() string

vstring_literal converts C char* to V string. See also vstring_literal defined on byteptr for more details.

Note: the string data is reused, NOT copied.

fn (cp charptr) vstring_literal_with_len(len int) string

vstring_literal_with_len converts C char* to V string. See also vstring_literal_with_len defined on byteptr.

Note: the string data is reused, NOT copied.

fn (cp charptr) vstring_with_len(len int) string

vstring_with_len converts C char* to V string.

Note: the string data is reused, NOT copied.

fn (x f32) str() string

str returns a f32 as string in suitable notation.

fn (x f32) strg() string

strg return a f32 as string in "g" printf format

fn (x f32) strsci(digit_num int) string

strsci returns the f32 as a string in scientific notation with digit_num decimals displayed, max 8 digits.

assert f32(1.234).strsci(3) == '1.234e+00'

fn (x f32) strlong() string

strlong returns a decimal notation of the f32 as a string.

fn (a f32) eq_epsilon(b f32) bool

eq_epsilon returns true if the f32 is equal to input b. using an epsilon of typically 1E-5 or higher (backend/compiler dependent).

assert f32(2.0).eq_epsilon(2.0)

fn (x f64) str() string

fn (x f64) strg() string

strg return a f64 as string in "g" printf format

fn (x f64) strsci(digit_num int) string

strsci returns the f64 as a string in scientific notation with digit_num decimals displayed, max 17 digits.

assert f64(1.234).strsci(3) == '1.234e+00'

fn (x f64) strlong() string

strlong returns a decimal notation of the f64 as a string.

assert f64(1.23456).strlong() == '1.23456'

fn (a f64) eq_epsilon(b f64) bool

eq_epsilon returns true if the f64 is equal to input b. using an epsilon of typically 1E-9 or higher (backend/compiler dependent).

assert f64(2.0).eq_epsilon(2.0)

fn (d float_literal) str() string

str returns the value of the float_literal as a string.

fn (n i16) str() string

str returns the value of the i16 as a string.

assert i16(-20).str() == '-20'

fn (nn i16) hex() string

hex returns the value of the i16 as a hexadecimal string. Note that the output is not zero padded.

assert i16(2).hex() == '2'

assert i16(200).hex() == 'c8'

fn (nn i16) hex_full() string

fn (n i32) str() string

fn (nn i64) str() string

str returns the value of the i64 as a string.

assert i64(-200000).str() == '-200000'

fn (nn i64) hex() string

hex returns the value of the i64 as a hexadecimal string. Note that the output is not zero padded.

assert i64(2).hex() == '2'

assert i64(-200).hex() == 'ffffffffffffff38'

assert i64(2021).hex() == '7e5'

fn (nn i64) hex_full() string

fn (n i8) str() string

str returns the value of the i8 as a string.

assert i8(-2).str() == '-2'

fn (nn i8) hex() string

hex returns the value of the i8 as a hexadecimal string. Note that the output is zero padded for values below 16.

assert i8(8).hex() == '08'

assert i8(10).hex() == '0a'

assert i8(15).hex() == '0f'

fn (nn i8) hex_full() string

fn (nn int) hex_full() string

fn (n int) str() string

str returns the value of the int as a string.

assert int(-2020).str() == '-2020'

fn (nn int) hex() string

hex returns the value of the int as a hexadecimal string. Note that the output is not zero padded.

assert int(2).hex() == '2'

assert int(200).hex() == 'c8'

fn (n int) hex2() string

hex2 returns the value of the int as a 0x-prefixed hexadecimal string. Note that the output after 0x is not zero padded.

assert int(8).hex2() == '0x8'

assert int(15).hex2() == '0xf'

assert int(18).hex2() == '0x12'

fn (n int_literal) str() string

str returns the value of the int_literal as a string.

fn (nn int_literal) hex() string

hex returns the value of the int_literal as a hexadecimal string. Note that the output is not zero padded.

fn (nn int_literal) hex_full() string

fn (x isize) str() string

str returns string equivalent of x

fn (_ none) str() string

fn (c rune) str() string

str converts a rune to string

fn (c rune) repeat(count int) string

repeat returns a new string with count number of copies of the rune it was called on.

fn (c rune) bytes() []u8

bytes converts a rune to an array of bytes

fn (c rune) length_in_bytes() int

length_in_bytes returns the number of bytes needed to store the code point. Returns -1 if the data is not a valid code point.

fn (c rune) to_upper() rune

to_upper convert to uppercase mode.

fn (c rune) to_lower() rune

to_lower convert to lowercase mode.

fn (c rune) to_title() rune

to_title convert to title mode.

fn (n u16) str() string

str returns the value of the u16 as a string.

assert u16(20).str() == '20'

fn (nn u16) hex() string

hex returns the value of the u16 as a hexadecimal string. Note that the output is not zero padded.

assert u16(2).hex() == '2'

assert u16(200).hex() == 'c8'

fn (nn u16) hex_full() string

fn (nn u32) str() string

str returns the value of the u32 as a string.

assert u32(20000).str() == '20000'

fn (nn u32) hex() string

hex returns the value of the u32 as a hexadecimal string. Note that the output is not zero padded.

assert u32(2).hex() == '2'

assert u32(200).hex() == 'c8'

fn (nn u32) hex_full() string

fn (nn u64) str() string

str returns the value of the u64 as a string.

assert u64(2000000).str() == '2000000'

fn (nn u64) hex() string

hex returns the value of the u64 as a hexadecimal string. Note that the output is not zero padded.

assert u64(2).hex() == '2'

assert u64(2000).hex() == '7d0'

fn (nn u64) hex_full() string

hex_full returns the value of the u64 as a full 16-digit hexadecimal string.

assert u64(2).hex_full() == '0000000000000002'

assert u64(255).hex_full() == '00000000000000ff'

fn (b u8) ascii_str() string

ascii_str returns the contents of byte as a zero terminated ASCII string character.

assert u8(97).ascii_str() == 'a'

fn (nn u8) hex() string

hex returns the value of the byte as a hexadecimal string. Note that the output is zero padded for values below 16.

assert u8(2).hex() == '02'

assert u8(15).hex() == '0f'

assert u8(255).hex() == 'ff'

fn (nn u8) hex_full() string

fn (c u8) is_alnum() bool

is_alnum returns true if the byte is in range a-z, A-Z, 0-9 and false otherwise.

assert u8(`V`).is_alnum() == true

fn (c u8) is_bin_digit() bool

is_bin_digit returns true if the byte is a binary digit (0 or 1) and false otherwise.

assert u8(`0`).is_bin_digit() == true

fn (c u8) is_capital() bool

is_capital returns true, if the byte is a Latin capital letter.

assert `H`.is_capital() == true

assert `h`.is_capital() == false

fn (c u8) is_digit() bool

is_digit returns true if the byte is in range 0-9 and false otherwise.

assert u8(`9`).is_digit() == true

fn (c u8) is_hex_digit() bool

is_hex_digit returns true if the byte is either in range 0-9, a-f or A-F and false otherwise.

assert u8(`F`).is_hex_digit() == true

fn (c u8) is_letter() bool

is_letter returns true if the byte is in range a-z or A-Z and false otherwise.

assert u8(`V`).is_letter() == true

fn (c u8) is_oct_digit() bool

is_oct_digit returns true if the byte is in range 0-7 and false otherwise.

assert u8(`7`).is_oct_digit() == true

fn (c u8) is_space() bool

is_space returns true if the byte is a white space character. The following list is considered white space characters: , \t, \n, \v, \f, \r, 0x85, 0xa0

assert u8(` `).is_space() == true

fn (b u8) repeat(count int) string

repeat returns a new string with count number of copies of the byte it was called on.

fn (b u8) str() string

str returns the contents of byte as a zero terminated string. See also: byte.ascii_str

assert u8(111).str() == '111'

fn (b u8) str_escaped() string

str_escaped returns the contents of byte as an escaped string.

assert u8(0).str_escaped() == r'`\0`'

fn (data &u8) vbytes(len int) []u8

vbytes on &u8 makes a V []u8 structure from a C style memory buffer.

Note: the data is reused, NOT copied!

fn (bp &u8) vstring() string

vstring converts a C style string to a V string.

Note: the memory block pointed by bp is reused, not copied!

Note: instead of &u8(arr.data).vstring(), do use tos_clone(&u8(arr.data)). Strings returned from this function will be normal V strings beside that, (i.e. they would be freed by V's -autofree mechanism, when they are no longer used). See also tos_clone.

fn (bp &u8) vstring_literal() string

vstring_literal converts a C style string to a V string.

Note: the memory block pointed by bp is reused, not copied! NB2: unlike vstring, vstring_literal will mark the string as a literal, so it will not be freed by -autofree. This is suitable for readonly strings, C string literals etc, that can be read by the V program, but that should not be managed/freed by it, for example os.args is implemented using it. See also tos_clone.

fn (bp &u8) vstring_literal_with_len(len int) string

vstring_with_len converts a C style string to a V string.

Note: the memory block pointed by bp is reused, not copied! This method has lower overhead compared to .vstring_literal(), since it does not need to calculate the length of the 0 terminated string. See also tos_clone.

fn (bp &u8) vstring_with_len(len int) string

vstring_with_len converts a C style 0 terminated string to a V string.

Note: the memory block pointed by bp is reused, not copied! This method has lower overhead compared to .vstring(), since it does not need to calculate the length of the 0 terminated string. See also tos_clone.

fn (x usize) str() string

str returns string equivalent of x

fn (nn voidptr) hex_full() string

fn (nn voidptr) str() string

hex returns the value of the voidptr as a hexadecimal string. Note that the output is not zero padded.

fn (data voidptr) vbytes(len int) []u8

vbytes onvoidptr makes a V []u8 structure from a C style memory buffer.

Note: the data is reused, NOT copied!

enum ArrayFlags {
	noslices // when <<, `.noslices` will free the old data block immediately (you have to be sure, that there are *no slices* to that specific array). TODO: integrate with reference counting/compiler support for the static cases.
	noshrink // when `.noslices` and `.noshrink` are *both set*, .delete(x) will NOT allocate new memory and free the old. It will just move the elements in place, and adjust .len.
	nogrow   // the array will never be allowed to grow past `.cap`. set `.nogrow` and `.noshrink` for a truly fixed heap array
	nofree   // `.data` will never be freed
}

enum AttributeKind {
	plain           // [name]
	string          // ['name']
	number          // [123]
	comptime_define // [if name]
}

enum ChanState {
	success
	not_ready // push()/pop() would have to wait, but no_block was requested
	closed
}

ChanState describes the result of an attempted channel transaction.

enum StrIntpType {
	si_no_str = 0 // no parameter to print only fix string
	si_c
	si_u8
	si_i8
	si_u16
	si_i16
	si_u32
	si_i32
	si_u64
	si_i64
	si_e32
	si_e64
	si_f32
	si_f64
	si_g32
	si_g64
	si_s
	si_p
	si_r
	si_vp
}

fn (x StrIntpType) str() string

struct C.DIR {
}

struct C.FILE {}

struct C.GC_stack_base {
	mem_base voidptr
	// reg_base voidptr
}

struct C.IError {
	_object voidptr
}

struct EnumData {
pub:
	name  string
	value i64
	attrs []string
}

struct Error {}

Error is the empty default implementation of IError.

fn (err Error) msg() string

fn (err Error) code() int

struct FieldData {
pub:
	name          string // the name of the field f
	typ           int    // the internal TypeID of the field f,
	unaliased_typ int    // if f's type was an alias of int, this will be TypeID(int)

	attrs  []string // the attributes of the field f
	is_pub bool     // f is in a `pub:` section
	is_mut bool     // f is in a `mut:` section

	is_shared bool // `f shared Abc`
	is_atomic bool // `f atomic int` , TODO
	is_option bool // `f ?string` , TODO

	is_array  bool // `f []string` , TODO
	is_map    bool // `f map[string]int` , TODO
	is_chan   bool // `f chan int` , TODO
	is_enum   bool // `f Enum` where Enum is an enum
	is_struct bool // `f Abc` where Abc is a struct , TODO
	is_alias  bool // `f MyInt` where `type MyInt = int`, TODO

	indirections u8 // 0 for `f int`, 1 for `f &int`, 2 for `f &&int` , TODO
}

FieldData holds information about a field. Fields reside on structs.

struct FunctionData {
pub:
	name        string
	attrs       []string
	args        []MethodParam
	return_type int
	typ         int
}

FunctionData holds information about a parsed function.

struct GCHeapUsage {
pub:
	heap_size      usize
	free_bytes     usize
	total_bytes    usize
	unmapped_bytes usize
	bytes_since_gc usize
}

struct MethodParam {
pub:
	typ  int
	name string
}

MethodParam holds type information for function and/or method arguments.

struct SortedMap {
	value_bytes int
mut:
	root &mapnode
pub mut:
	len int
}

fn (mut m SortedMap) delete(key string)

fn (m &SortedMap) keys() []string

fn (mut m SortedMap) free()

fn (m SortedMap) print()

struct StrIntpCgenData {
pub:
	str string
	fmt string
	d   string
}

storing struct used by cgen

struct StrIntpData {
pub:
	str string
	// fmt     u64  // expanded version for future use, 64 bit
	fmt u32
	d   StrIntpMem
}

Note: LOW LEVEL structstoring struct passed to V in the C code

union StrIntpMem {
pub mut:
	d_c   u32
	d_u8  u8
	d_i8  i8
	d_u16 u16
	d_i16 i16
	d_u32 u32
	d_i32 int
	d_u64 u64
	d_i64 i64
	d_f32 f32
	d_f64 f64
	d_s   string
	d_r   string
	d_p   voidptr
	d_vp  voidptr
}

Union data used by StrIntpData

struct VAssertMetaInfo {
pub:
	fpath   string // the source file path of the assertion
	line_nr int    // the line number of the assertion
	fn_name string // the function name in which the assertion is
	src     string // the actual source line of the assertion
	op      string // the operation of the assertion, i.e. '==', '<', 'call', etc ...
	llabel  string // the left side of the infix expressions as source
	rlabel  string // the right side of the infix expressions as source
	lvalue  string // the stringified *actual value* of the left side of a failed assertion
	rvalue  string // the stringified *actual value* of the right side of a failed assertion
	message string // the value of the `message` from `assert cond, message`
	has_msg bool   // false for assertions like `assert cond`, true for `assert cond, 'oh no'`
}

VAssertMetaInfo is used during assertions. An instance of it is filled in by compile time generated code, when an assertion fails.

fn (ami &VAssertMetaInfo) free()

free frees the memory occupied by the assertion meta data. It is called automatically by the code, that V's test framework generates, after all other callbacks have been called.

struct VAttribute {
pub:
	name    string
	has_arg bool
	arg     string
	kind    AttributeKind
}

struct VContext {
	allocator int
}

----- value to string functions -----

struct VariantData {
pub:
	typ int
}

struct WrapConfig {
pub:
	width int    = 80
	end   string = '\n'
}

struct array {
pub mut:
	data   voidptr
	offset int // in bytes (should be `usize`), to avoid copying data while making slices, unless it starts changing
	len    int // length of the array in elements.
	cap    int // capacity of the array in elements.
	flags  ArrayFlags
pub:
	element_size int // size in bytes of one element in the array.
}

array is a struct, used for denoting all array types in V. .data is a void pointer to the backing heap memory block, which avoids using generics and thus without generating extra code for every type.

fn (a array) repeat(count int) array

repeat returns a new array with the given array elements repeated given times. cgen will replace this with an appropriate call to repeat_to_depth()

This is a dummy placeholder that will be overridden by cgen with an appropriate call to repeat_to_depth(). However the checker needs it here.

fn (a array) repeat_to_depth(count int, depth int) array

repeat_to_depth is an unsafe version of repeat() that handles multi-dimensional arrays.

It is unsafe to call directly because depth is not checked

fn (mut a array) insert(i int, val voidptr)

insert inserts a value in the array at index i and increases the index of subsequent elements by 1.

This function is type-aware and can insert items of the same or lower dimensionality as the original array. That is, if the original array is []int, then the insert val may be int or []int. If the original array is [][]int, then val may be []int or [][]int. Consider the examples.

mut a := [1, 2, 4]
a.insert(2, 3)          // a now is [1, 2, 3, 4]
mut b := [3, 4]
b.insert(0, [1, 2])     // b now is [1, 2, 3, 4]
mut c := [[3, 4]]
c.insert(0, [1, 2])     // c now is [[1, 2], [3, 4]]

fn (mut a array) prepend(val voidptr)

prepend prepends one or more elements to an array. It is shorthand for .insert(0, val)

fn (mut a array) delete(i int)

delete deletes array element at index i. This is exactly the same as calling .delete_many(i, 1).

Note: This function does NOT operate in-place. Internally, it creates a copy of the array, skipping over the element at i, and then points the original variable to the new memory location.

mut a := ['0', '1', '2', '3', '4', '5']
a.delete(1) // a is now ['0', '2', '3', '4', '5']

fn (mut a array) delete_many(i int, size int)

delete_many deletes size elements beginning with index i

Note: This function does NOT operate in-place. Internally, it creates a copy of the array, skipping over size elements starting at i, and then points the original variable to the new memory location.

mut a := [1, 2, 3, 4, 5, 6, 7, 8, 9]
b := a[..9] // creates a `slice` of `a`, not a clone
a.delete_many(4, 3) // replaces `a` with a modified clone
dump(a) // a: [1, 2, 3, 4, 8, 9] // `a` is now different
dump(b) // b: [1, 2, 3, 4, 5, 6, 7, 8, 9] // `b` is still the same

fn (mut a array) clear()

clear clears the array without deallocating the allocated data. It does it by setting the array length to 0

a.clear() // `a.len` is now 0

fn (mut a array) reset()

reset quickly sets the bytes of all elements of the array to 0. Useful mainly for numeric arrays. Note, that calling reset() is not safe, when your array contains more complex elements, like structs, maps, pointers etc, since setting them to 0, can later lead to hard to find bugs.

fn (mut a array) trim(index int)

trim trims the array length to index without modifying the allocated data. If index is greater than len nothing will be changed.

a.trim(3) // `a.len` is now <= 3

fn (mut a array) drop(num int)

drop advances the array past the first num elements whilst preserving spare capacity. If num is greater than len the array will be emptied.

mut a := [1,2]
a << 3
a.drop(2)
assert a == [3]
assert a.cap > a.len

fn (a array) first() voidptr

first returns the first element of the array. If the array is empty, this will panic. However, a[0] returns an error object so it can be handled with an or block.

fn (a array) last() voidptr

last returns the last element of the array. If the array is empty, this will panic.

fn (mut a array) pop() voidptr

pop returns the last element of the array, and removes it. If the array is empty, this will panic.

Note: this function reduces the length of the given array, but arrays sliced from this one will not change. They still retain their "view" of the underlying memory.

mut a := [1, 2, 3, 4, 5, 6, 7, 8, 9]
b := a[..9] // creates a "view" into the same memory
c := a.pop() // c == 9
a[1] = 5
dump(a) // a: [1, 5, 3, 4, 5, 6, 7, 8]
dump(b) // b: [1, 5, 3, 4, 5, 6, 7, 8, 9]

fn (mut a array) delete_last()

delete_last efficiently deletes the last element of the array. It does it simply by reducing the length of the array by 1. If the array is empty, this will panic. See also: trim

fn (a &array) clone() array

clone returns an independent copy of a given array. this will be overwritten by cgen with an appropriate call to .clone_to_depth() However the checker needs it here.

fn (a &array) clone_to_depth(depth int) array

recursively clone given array - unsafe when called directly because depth is not checked

fn (mut a array) push_many(val voidptr, size int)

push_many implements the functionality for pushing another array. val is array.data and user facing usage is a << [1,2,3]

fn (mut a array) reverse_in_place()

reverse_in_place reverses existing array data, modifying original array.

fn (a array) reverse() array

reverse returns a new array with the elements of the original array in reverse order.

fn (a &array) free()

free frees all memory occupied by the array.

fn (a array) filter(predicate fn (voidptr) bool) array

filter creates a new array with all elements that pass the test. Ignore the function signature. filter does not take an actual callback. Rather, it takes an it expression.

Certain array functions (filter any all) support a simplified domain-specific-language by the backend compiler to make these operations more idiomatic to V. These functions are described here, but their implementation is compiler specific.

Each function takes a boolean test expression as its single argument. These test expressions may use it as a pointer to a single element at a time.

array.filter(it < 5) // create an array of elements less than 5

array.filter(it % 2 == 1) // create an array of only odd elements

array.filter(it.name[0] == `A`) // create an array of elements whose `name` field starts with 'A'

fn (a array) any(predicate fn (voidptr) bool) bool

any tests whether at least one element in the array passes the test. Ignore the function signature. any does not take an actual callback. Rather, it takes an it expression. It returns true if it finds an element passing the test. Otherwise, it returns false. It doesn't modify the array.

array.any(it % 2 == 1) // will return true if any element is odd

array.any(it.name == 'Bob') // will yield `true` if any element has `.name == 'Bob'`

fn (a array) all(predicate fn (voidptr) bool) bool

all tests whether all elements in the array pass the test. Ignore the function signature. all does not take an actual callback. Rather, it takes an it expression. It returns false if any element fails the test. Otherwise, it returns true. It doesn't modify the array.

array.all(it % 2 == 1) // will return true if every element is odd

fn (a array) map(callback fn (voidptr) voidptr) array

map creates a new array populated with the results of calling a provided function on every element in the calling array. It also accepts an it expression.

words := ['hello', 'world']
r1 := words.map(it.to_upper())
assert r1 == ['HELLO', 'WORLD']

// map can also accept anonymous functions
r2 := words.map(fn (w string) string {
	return w.to_upper()
})
assert r2 == ['HELLO', 'WORLD']

fn (mut a array) sort(callback fn (voidptr, voidptr) int)

sort sorts the array in place. Ignore the function signature. Passing a callback to .sort is not supported for now. Consider using the .sort_with_compare method if you need it.

sort can take a boolean test expression as its single argument. The expression uses 2 'magic' variables a and b as pointers to the two elements being compared.

array.sort() // will sort the array in ascending order

array.sort(b < a) // will sort the array in descending order

array.sort(b.name < a.name) // will sort descending by the .name field

fn (a &array) sorted(callback fn (voidptr, voidptr) int) array

sorted returns a sorted copy of the original array. The original array is NOT modified. See also .sort() .

assert [9,1,6,3,9].sorted() == [1,3,6,9,9]

assert [9,1,6,3,9].sorted(b < a) == [9,9,6,3,1]

fn (mut a array) sort_with_compare(callback fn (voidptr, voidptr) int)

sort_with_compare sorts the array in-place using the results of the given function to determine sort order.

The function should return one of three values:- -1 when a should come before b ( a < b )

• 1 when b should come before a ( b < a )
• 0 when the order cannot be determined ( a == b )

fn main() {
	mut a := ['hi', '1', '5', '3']
	a.sort_with_compare(fn (a &string, b &string) int {
		if a < b {
			return -1
		}
		if a > b {
			return 1
		}
		return 0
	})
	assert a == ['1', '3', '5', 'hi']
}

fn (a &array) sorted_with_compare(callback fn (voidptr, voidptr) int) array

sorted_with_compare sorts a clone of the array, using the results of the given function to determine sort order. The original array is not modified. See also .sort_with_compare()

fn (a array) contains(value voidptr) bool

contains determines whether an array includes a certain value among its elements It will return true if the array contains an element with this value. It is similar to .any but does not take an it expression.

[1, 2, 3].contains(4) == false

fn (a array) index(value voidptr) int

index returns the first index at which a given element can be found in the array or -1 if the value is not found.

fn (mut a array) grow_cap(amount int)

grow_cap grows the array's capacity by amount elements. Internally, it does this by copying the entire array to a new memory location (creating a clone).

fn (mut a array) grow_len(amount int)

grow_len ensures that an array has a.len + amount of length Internally, it does this by copying the entire array to a new memory location (creating a clone) unless the array.cap is already large enough.

fn (a array) pointers() []voidptr

pointers returns a new array, where each element is the address of the corresponding element in the array.

struct map {
	// Number of bytes of a key
	key_bytes int
	// Number of bytes of a value
	value_bytes int
mut:
	// Highest even index in the hashtable
	even_index u32
	// Number of cached hashbits left for rehashing
	cached_hashbits u8
	// Used for right-shifting out used hashbits
	shift u8
	// Array storing key-values (ordered)
	key_values DenseArray
	// Pointer to meta-data:
	// - Odd indices store kv_index.
	// - Even indices store probe_count and hashbits.
	metas &u32
	// Extra metas that allows for no ranging when incrementing
	// index in the hashmap
	extra_metas     u32
	has_string_keys bool
	hash_fn         MapHashFn
	key_eq_fn       MapEqFn
	clone_fn        MapCloneFn
	free_fn         MapFreeFn
pub mut:
	// Number of key-values currently in the hashmap
	len int
}

map is the internal representation of a V map type.

fn (mut m map) move() map

move moves the map to a new location in memory. It does this by copying to a new location, then setting the old location to all 0 with vmemset

fn (mut m map) clear()

clear clears the map without deallocating the allocated data. It does it by setting the map length to 0

a.clear() // `a.len` and `a.key_values.len` is now 0

fn (mut m map) reserve(meta_bytes u32)

reserve memory for the map meta data

fn (mut m map) delete(key voidptr)

delete removes the mapping of a particular key from the map.

fn (m &map) keys() array

keys returns all keys in the map.

fn (m &map) values() array

values returns all values in the map.

fn (m &map) clone() map

clone returns a clone of the map.

fn (m &map) free()

free releases all memory resources occupied by the map.

struct string {
pub:
	str &u8 = 0 // points to a C style 0 terminated string of bytes.
	len int // the length of the .str field, excluding the ending 0 byte. It is always equal to strlen(.str).
mut:
	is_lit int
	// NB string.is_lit is an enumeration of the following:
	// .is_lit == 0 => a fresh string, should be freed by autofree
	// .is_lit == 1 => a literal string from .rodata, should NOT be freed
	// .is_lit == -98761234 => already freed string, protects against double frees.
	// ---------> ^^^^^^^^^ calling free on these is a bug.
	// Any other value means that the string has been corrupted.
}

fn (s string) after(sub string) string

Todo: deprecate either .all_after_last or .after

assert '23:34:45.234'.after(':') == '45.234'

assert 'abcd'.after('z') == 'abcd'

fn (s string) after_char(sub u8) string

after_char returns the contents after the first occurrence of sub character in the string. If the substring is not found, it returns the full input string.

assert '23:34:45.234'.after_char(`:`) == '34:45.234'

assert 'abcd'.after_char(`:`) == 'abcd'

fn (s string) all_after(sub string) string

all_after returns the contents after sub in the string. If the substring is not found, it returns the full input string.

assert '23:34:45.234'.all_after('.') == '234'

assert 'abcd'.all_after('z') == 'abcd'

fn (s string) all_after_first(sub string) string

all_after_first returns the contents after the first occurrence of sub in the string. If the substring is not found, it returns the full input string.

assert '23:34:45.234'.all_after_first(':') == '34:45.234'

assert 'abcd'.all_after_first('z') == 'abcd'

fn (s string) all_after_last(sub string) string

all_after_last returns the contents after the last occurrence of sub in the string. If the substring is not found, it returns the full input string.

assert '23:34:45.234'.all_after_last(':') == '45.234'

assert 'abcd'.all_after_last('z') == 'abcd'

fn (s string) all_before(sub string) string

all_before returns the contents before sub in the string. If the substring is not found, it returns the full input string.

assert '23:34:45.234'.all_before('.') == '23:34:45'

assert 'abcd'.all_before('.') == 'abcd'

fn (s string) all_before_last(sub string) string

all_before_last returns the contents before the last occurrence of sub in the string. If the substring is not found, it returns the full input string.

assert '23:34:45.234'.all_before_last(':') == '23:34'

assert 'abcd'.all_before_last('.') == 'abcd'

fn (s string) before(sub string) string

Todo: deprecate and remove either .before or .all_before

assert '23:34:45.234'.before('.') == '23:34:45'

assert 'abcd'.before('.') == 'abcd'

fn (s string) bool() bool

bool returns true if the string equals the word "true" it will return false otherwise.

fn (s string) bytes() []u8

bytes returns the string converted to a byte array.

fn (s string) camel_to_snake() string

camel_to_snake convert string from camelCase to snake_case

assert 'Abcd'.camel_to_snake() == 'abcd'

assert 'aaBB'.camel_to_snake() == 'aa_bb'

assert 'BBaa'.camel_to_snake() == 'b_baa'

assert 'aa_BB'.camel_to_snake() == 'aa_bb'

fn (s string) capitalize() string

capitalize returns the string with the first character capitalized.

assert 'hello'.capitalize() == 'Hello'

fn (a string) clone() string

clone returns a copy of the V string a.

fn (s string) compare(a string) int

compare returns -1 if s < a, 0 if s == a, and 1 if s > a

fn (s string) contains(substr string) bool

contains returns true if the string contains substr. See also: string.index

fn (s string) contains_any(chars string) bool

contains_any returns true if the string contains any chars in chars.