Edit on GitHub

Libraries

This is a list of built-in libraries in Nelua.

To use a library, use require 'libraryname'.

This page is under construction and is very incomplete.

arg

The arg library allows to use command line arguments from the entry point.

Variable Name Description
global arg: sequence(stringview, GeneralAllocator) Sequence of command line arguments.

basic

The basic library contains common functions.

Variable Name Description
global likely(x: boolean): boolean Binding for GNUC __builtin_expect(x, 1).
global unlikely(x: boolean): boolean Binding for GNUC __builtin_expect(x, 0).
global panic(msg: stringview) Returns an error message and stops execution.
global error(msg: stringview) Alias of panic.
global assert(cond: auto, msg: auto) Asserts the condition condand errors if it’s false.
global _VERSION: stringview A string of Nelua version.

iterators

The iterators library contains iterator-related functions.

Variable Name Description
ipairs(list: L): (Next, *L, integer) Use with for in to iterate contiguous containers. Works with vector, sequence, span and array.
mipairs(list: L): (Next, *L, integer) Like ipairs but yields reference to elements so that you can modify.
pairs(list: L): (Next, *L, K) Use with for in to iterate containers.
mpairs(list: L): (Next, *L, K) Like pairs but yields reference to elements so that you can modify.
next(list: L, [index: K]): (boolean, K, T) Get the next element from a container. Works with vector, sequence, span and array.
mnext(list: L, [index: K]): (boolean, K, *T) Like next but returns reference to elements so that you can modify.

filestream

The filestream library contains filestream records, mainly used for the io library.

Variable Name Description
global filestream filestream record.
filestream.id: uint64 file id.
filestream.open(filename: stringview[, mode: stringview]): (filestream, stringview, integer) Opens a file with given mode (default is "r"). Returns empty filesystem, error message and error code if failed.
filestream:flush(): (boolean, stringview, integer) Flushes the file.
filestream:close(): (boolean, stringview, integer) Closes the file.
filestream:seek([whence: stringview[, offset: integer]]): (integer, stringview, integer) Returns the caret position or goes to given offset or returns the size.
filestream:setvbuf(mode: stringview[, size: integer]) Sets buffer size.
filestream:read(fmt: [integer, stringview, niltype]): (string, stringview, integer) Reads the content of the file according to the given format.
filestream:write(s: stringview): (boolean, stringview, integer) Writes text to the file.
filestream:lines(fmt: [integer,stringview,niltype]): (function(state: LinesState, prevstr: string): (boolean, string), LinesState, string) Returns an iterator function that, each time it is called, reads the file according to the given formats. When no format is given, uses "l" as a default.
filestream:isopen(): boolean Returns open state of the file.
filestream:__tostring(): string converts the handled *FILE to string.

io

The IO library copies Lua’s io library.

Variable Name Description
global io io record.
global io.stderr: filestream Error file.
global io.stdout: filestream Output file used for io.write.
global io.stdin: filestream Input file used for io.read.
io.open(filename: stringview[, mode: stringview]) : (filestream, stringview, integer) Opens a file. Alias of filestream.open.
io.flush(): boolean Flushes stdout.
io.close([file]) Alias of file:close. Closes io.stdout if no file was given.
io.input(file: [stringview, filestream, niltype]): filestream Sets, opens or returns the input file.
io.output(file: [stringview, filestream, niltype]): filestream Sets, opens or returns the output file.
io.tmpfile(): (filestream, stringview, integer) In case of success, returns a handle for a temporary file. This file will automatically removed when the program ends.
io.read(fmt: [integer, stringview, niltype]): (string, stringview, integer) Alias of io.stdin:read.
io.write(s: stringview): (boolean, stringview, integer) Alias of io.stdout:write.
io.type(x: auto) Returns a type of a file as a string. Returns nil if not a file.
io.isopen(file: filestream): boolean Alias of file:isopen.
io.lines([filename: stringview, fmt: [integer,stringview,niltype]]) When no filename is given, is an alias of io.stdin:lines(), otherwise, it opens the given filename and returns an iterator function of file:lines(fmt) over the opened file.

math

The math library copies Lua’s math library with extra functions.

Variable Name Description
global math math record
global math.pi The compile-time value of #[math.pi]#, which is the the value of π.
global math.huge The compile-time value of #[math.huge]#, which is a value greater than any other numeric value.
global math.maxinteger The maximum possible compile-time value of integer.
global math.mininteger The minimum possible compile-time value of integer.
math.abs(x) Returns the absolute value of x.
math.ceil(x) Returns the smallest integral value greater than or equal to x.
math.floor(x) Returns the largest integral value less than or equal to x.
math.ifloor(x): integer Returns the result of math.floor(x), but returns an integer.
math.sqrt(x) Returns the square root of x.
math.exp(x) Returns the value eˣ (where e is the base of natural logarithms).
math.acos(x) Returns the arc cosine of x (in radians).
math.asin(x) Returns the arc sine of x (in radians).
math.cos(x) Returns the cosine of x (assumed to be in radians).
math.sin(x) Returns the sine of x (assumed to be in radians).
math.tan(x) Returns the tangent of x (assumed to be in radians).
math.cosh(x) Returns the hyperbolic cosine of x.
math.sinh(x) Returns the hyperbolic sine of x.
math.tanh(x) Returns the hyperbolic tangent of x.
math.log10(x) Returns the base-10 logarithm of x.
math.max(x, y) Returns the argument with the maximum value, according to the Nelua operator <.
math.min(x, y) Returns the argument with the minimum value, according to the Nelua operator <.
math.fmod(x, y) Returns the remainder of the division of x by y that rounds the quotient towards zero.
math.atan2(y, x) Returns the arc tangent of y/x (in radians), but uses the signs of both parameters to find the quadrant of the result. (It also handles correctly the case of x being zero.).
math.pow(x, y) Returns xʸ. (You can also use the expression x^y to compute this value.).
math.atan(y[, x]) If x argument is passed, it returns the same value as math.atan2(y, x), otherwise it returns the arc tangent of y (in radians).
math.log(x[, base]) If base argument is passed, it returns the logarithm of x in the given base, otherwise it returns the natural logarithm of x).
math.deg(x) Converts the angle x from radians to degrees.
math.rad(x) Returns the angle x (given in degrees) in radians.
math.modf(x) Returns the integral part of x and the fractional part of x.
math.frexp(x) Returns m (multiplier) and e (exponent) such that x = m2ᵉ, e is an integer and the absolute value of m is in the range [0.5, 1) (or zero when x is zero).
math.ldexp(m, e) Returns m2ᵉ (e should be an integral).
math.tointeger(x) If the value x is convertible to an integer, returns that integer. Otherwise, returns nil.
math.type(x) Returns "integer" if x is an integral, "float" if it is a float, or "nil" if x is not a number.
math.ult(m, n) Both m and n should be convertible to an integer; returns true if and only if integer m is below integer n when they are compared as unsigned integers.
math.randomseed(x) Sets x as the “seed” for the pseudo-random generator: equal seeds produce equal sequences of numbers.
math.random([m[, n]]) When called without arguments, returns a pseudo-random float with uniform distribution in the range [0,1). When called with two integers m and n, it returns a pseudo-random integer with uniform distribution in the range [m, n]. The call math.random(n), for a positive n, is equivalent to math.random(1,n).

memory

Memory library description (TODO)

Variable Name Description
global memory memory record
memory.copy(dest: pointer, src: pointer, size: usize)  
memory.move(dest: pointer, src: pointer, size: usize)  
memory.set(dest: pointer, x: byte, size: usize)  
memory.zero(dest: pointer, size: usize)  
memory.compare(a: pointer, b: pointer, size: usize): int32  
memory.equals(a: pointer, b: pointer, size: usize): boolean  
memory.scan(p: pointer, x: byte, size: usize): pointer  
memory.find(haystack: pointer, haystacksize: usize, needle: pointer, needlesize: usize): pointer  
memory.spancopy(dest: is_span, src: is_span)  
emory.spanmove(dest: is_span, src: is_span)  
memory.spanset(dest: is_span, x: auto)  
memory.spanzero(dest: is_span)  
memory.spancompare(a: is_span, b: is_span): int32  
memory.spanequals(a: is_span, b: is_span): boolean  
memory.spanfind(s: is_span, x: auto): isize  
memory.spancontains(s: is_span, x: auto): boolean  

os

The OS library copies Lua’s os library.

Variable Name Description
global os os record.
os.clock(): number Returns an approximation of the amount in seconds of CPU time used by the program, as returned by the underlying ISO C function clock.
os.date(): string Returns a human-readable date and time representation string using the current locale.
os.difftime(t1: integer, t2: integer): integer Returns the difference, in seconds, from time t1 to time t2 (where the times are values returned by os.time)
os.execute([command: stringview]) This function is equivalent to the ISO C function system. It passes command to be executed by an operating system shell. It returns three values, the first value is a boolean indicating if the command terminated successfully; the second and third values are a stringview (either "exit" or "signal") and a cint (either correspondent exit status of the command or the signal that terminated the command). When called without a command, os.execute returns a boolean that is true if a shell is available.
os.exit(code: [integer, boolean, niltype]) Calls the ISO C function exit to terminate the host program. If code is true, the returned status is EXIT_SUCCESS; if code is false, the returned status is EXIT_FAILURE; if code is a number, the returned status is this number. When called without a code, the returned status is EXIT_SUCCESS.
os.getenv(varname: stringview): string Returns the value of the process environment variable varname or an empty string if the variable is not defined.
os.remove(filename: stringview): (boolean, stringview, integer) Deletes the file (or empty directory, on POSIX systems) with the given name. If this function fails, it returns false plus a string describing the error and the error code. Otherwise, it returns true, an empty string and 0.
os.rename(oldname: stringview, newname: stringview): (boolean, stringview, integer) Renames the file or directory named oldname to newname. If this function fails, it returns false plus a string describing the error and the error code. Otherwise, it returns true, an empty string and 0.
os.setlocale(locale: stringview[, category: stringview]): string Sets the current locale of the program. locale is a system-dependent string specifying a locale; category is an optional string describing which category to change: "all", "collate", "ctype", "monetary", "numeric", or "time"; the default category is “all”. The function returns the name of the new locale, or an empty string if the request cannot be honored. If locale is the empty string, the current locale is set to an implementation-defined native locale. If locale is the string “C”, the current locale is set to the standard C locale. This function may be not thread safe because of its reliance on C function setlocale.
global os_time_desc the os_time_desc record, contains, declared in that order, year, month, day, hour, min and sec integer fields and a isdst boolean field.
os.time([desc: os_time_desc]): integer Returns the current time when called without arguments, or a time representing the local date and time specified by the given desc.
os.tmpname(): string Returns a string with a file name that can be used for a temporary file. The file must be explicitly opened before its use and explicitly removed when no longer needed. In POSIX systems, this function also creates a file with that name, to avoid security risks. (Someone else might create the file with wrong permissions in the time between getting the name and creating the file.) You still have to open the file to use it and to remove it (even if you do not use it). When possible, you may prefer to use io.tmpfile, which automatically removes the file when the program ends.

resourcepool

Resource Pool library description (TODO)

Variable Name Description
resourcepool Resourcepool constructor.

sequence

Sequence library description (TODO)

Variable Name Description
sequence Sequence constructor.

span

Span library description (TODO)

Variable Name Description
span Span constructor

string

String library description (TODO)

Variable Name Description
string String type.
tostring Converts values to string using __tostring.
string.__tocstring  
string.__tostringview  
string.__convert  
string.sub  
string.rep  
string.reverse  
string.upper  
string.lower  
string.char  
string.format  
string.__concat  
string.__len  
string.__eq  
string.__lt  
string.__le  
string.__add  
string.__sub  
string.__mul  
string.__div  
string.__idiv  
string.__tdiv  
string.__mod  
string.__tmod  
string.__pow  
string.__unm  
string.__band  
string.__bor  
string.__bxor  
string.__shl  
string.__shr  
string.__bnot  
string.len  
string.byte  
string.find  
string.subview  
stringview.__concat  
stringview.rep  
stringview.sub  
stringview.reverse  
stringview.upper  
stringview.lower  
stringview.format  

stringbuilder

String Builder library description (TODO)

Variable Name Description
stringbuilder.make Stringbuilder constructor.

stringview

String View library description (TODO)

Variable Name Description
tostringview  
tonumber  
tointeger  
stringview.__len  
stringview.__eq  
stringview.__lt  
stringview.__le  
stringview.len  
stringview.byte  
stringview.subview  
stringview.find  
stringview.__add  
stringview.__sub  
stringview.__mul  
stringview.__div  
stringview.__idiv  
stringview.__tdiv  
stringview.__mod  
stringview.__tmod  
stringview.__pow  
stringview.__unm  
stringview.__band  
stringview.__bor  
stringview.__bxor  
stringview.__shl  
stringview.__shr  
stringview.__bnot  

traits

The traits library contains useful functions to get information about types at runtime.

Variable Name Description
global typeid: type type alias of uint32.
global typeid_of(val: auto): typeid Returns the typeid of the given val.
global type(x: auto): stringview Returns the type of its only argument, coded as a string.
global typeinfo typeinfo record.
global typeinfo_of(x: auto): typeinfo Return the typeinfo of the given x.

vector

The Vector library is an efficient vector implementation.

Variable Name Description
vector(T) Generic vector type expression.
vectorT.data: span(T) Elements storage of the vector.
vectorT.size: usize Number of elements in the vector.
vectorT.allocator: Allocator Allocator of the vector.
vectorT.make(allocator) Create a vector using a custom allocator instance.
vectorT:clear() Removes all elements from the vector.
vectorT:destroy() Resets the vector to zeroed state, freeing all used resources.
vectorT:reserve(n: usize) Reserve at least n elements in the vector storage.
vectorT:resize(n: usize) Resizes the vector so that it contains n elements.
vectorT:copy(): vectorT Returns a shallow copy of the vector, allocating new space.
vectorT:push(v: T) Adds a element v at the end of the vector.
vectorT:pop(): T Removes the last element in the vector and returns its value.
vectorT:insert(pos: usize, v: T) Inserts element v at position pos in the vector.
vectorT:remove(pos: usize): T Removes element at position pos in the vector and returns its value.
vectorT:remove_value(v: T) Removes the first item from the vector whose value is given.
vectorT:remove_if(pred) Removes all elements from the vector where pred function returns true.
vectorT:capacity(): isize Returns the number of elements the vector can store before triggering a reallocation.
vectorT:__atindex(i: usize): *T Returns reference to element at index pos.
vectorT:__len(): isize Returns the number of elements in the vector.

Differences »