luaXroot Wiki

A set of helper function to make the user's life simpler are provided. These functions goes from simple macros to more complex and effective tools.

Reminders:

  • Each argument is specified using the following nomenclature: < type, default value if any >
    Examples: , < float, 3.14157 >, < string, "O_RDONLY | O_NONBLOCK" >, ...
  • A [o] in front of an argument means that it's optional.
  • Some functions takes an arguments table. In this case the arguments are enclosed with { ... }. Each argument inside the table has a name that MUST be specified when calling the function. The advantage of arguments tables is that optional arguments can be omitted completely when calling the function, and passed in any order.

Index of this section:

click to expand

GetClockTime

([o] clockid=< int, CLOCK_REALTIME >)
Return values: table

(format=< string >, [o] clockid=< int, CLOCK_REALTIME >)
Return values: int

Returns the value of the clock specified by clockid. If no clockid is provided, CLOCK_REALTIME is used, which returns the time elapsed since Epoch.
If no argument format is provided, the function returns the following table

	 {
	    clockid,   -- the id of the clock used
	    sec,       -- the whole number part of the clock (seconds)
	    nsec       -- the decimal part of the clock (nanoseconds) 
	 }

A format argument can be provided as a string: second, millisecond, microsecond or nanosecond. In this case the clock value is returned as an integer matching the requested format.

go back to top

ClockTimeDiff

(origin=< table >, [o] format=< string >)
Return values: table OR int

Computes the time diffence between now and the clock passed as origin (a table obtained using a previous call to GetClockTime).
The optionnal format argument has the same meaning as in GetClockTime.

go back to top

isint

(x=< number >)
Return values: bool

Returns true if x is an integer, false otherwise.

go back to top

shallowcopy

(orig=< table >, [o] copyNested=< bool, false >, [o] ignores=< table, nil >)
Return values: table

As discussed before, tables in Lua cannot be copied trivially.
shallowcopy allows to create a copy of a table but it has limitations. As its name indicate the copy won't be complete. It doesn't handle metatables.

shallowcopy takes as first argument the table to be copied. The second argument specify how to treat nested tables (tables inside the table to copy). If set to false (default), a reference to the nested table will be inserted in the copied table. If set to true, shallowcopy will be called on these nested tables with the same argument of the calling function, creating a shallow copy of the nested table.

Finally the ignores optional argument is a table containing a list of the fields that should be ignored during the copy.

go back to top

deepcopy

(orig=< table >)
Return values: table

As discussed before, tables in Lua cannot be copied trivially.
deepcopy allows to create a copy of the table passed as the argument and it handles metatables.

deepcopy can be dangerous. For instance, it will be stuck in an endless loop if used on tables which are using a reference to themselves as their metatable.

go back to top

printtable

(tbl=< table >, [o] printNested=< bool, false >, [o] ignores=< table, nil >, [o] level=< int, 1 >, [o] maxlevel=< int, nil >)
Return values: nil

Helper function to print the content of a table.

  • tbl is the input table.
  • printNested is a boolean specifying if nested table should be printed using printtable.
  • ignores is a list of fields that should be ignored during the printout.
  • level should be set to either nil or 1.
  • maxlevel specify how deep the printout of nested tables should be propagated. No value means no limit.

printtable with printNested set to true and no maxlevel set can be dangerous. For instance, it will be stuck in an endless loop if used on tables which are using a reference to themselves as their metatable.

go back to top

findintable

(tbl=< table >, tofind=< any type >, [o] checksubtables=< bool, false >, [o] maxlevel=< int, nil >)
Return values: type of tofind

Search for tofind in tbl. If checksubtables is set to true, the search will be propagated to potential nested tables. maxlevel indicated how deep the search should be propagated if tbl contains nested tables. No values for maxvalue means no limit.

findintable with checksubtables set to true and no maxlevel set can be dangerous. For instance, it will be stuck in an endless loop if used on tables which are using a reference to themselves as their metatable.

go back to top

newtable

( )
Return values: table

Creates a new table and register some useful functions to manipulate that table. Tables created this way are meant to be used as arrays. These functions are:

  • insert : push back an element at the end of the table.
  • back : access the last element in the table.
  • GetSize : returns the amount of elements in the table.

go back to top

SizeOf

( datatype=< string > )
Return values: int

Returns the size in bytes of the requested type which name is passed as datatype.

go back to top

InitTable

( size=< int >, default=< any type > )
Return values: table

Creates a new table and insert size times default in it. The table is then returned.

go back to top

StartNewTask

Often the user will want to start a task without loosing the ability the interact with the luaXroot session and would rather run it in the background instead. For this instance, the helper function StartNewTask can be used to create a new thread that will run the requested task in the background while the user can still user the Lua command prompt to perform other operations. This functionality comes with a set of function to communicate with the tasks threads such as SendSignal to send for instance a pause request to that running task.

go back to top