Home Explore Blog CI



neovim

32th chunk of `runtime/doc/luaref.txt`
2e1e4e1861532a85c5604da6ea87f75fafd3cfebf148ffda0000000100000fa1
                           *userdata*
        Userdata represents C values in Lua. A full userdata represents a
        block of memory. It is an object (like a table): you must create it,
        it can have its own metatable, and you can detect when it is being
        collected. A full userdata is only equal to itself (under raw
        equality).

        When Lua collects a full userdata with a `gc` metamethod, Lua calls
        the metamethod and marks the userdata as finalized. When this userdata
        is collected again then Lua frees its corresponding memory.

lua_next                                                            *lua_next()*
>c
    int lua_next (lua_State *L, int index);
<
        Pops a key from the stack, and pushes a key-value pair from the table
        at the given index (the "next" pair after the given key). If there are
        no more elements in the table, then `lua_next` returns 0 (and pushes
        nothing).

                                                         *lua-tabletraversal*
        A typical traversal looks like this:
>c
               /* table is in the stack at index 't' */
               lua_pushnil(L);  /* first key */
               while (lua_next(L, t) != 0) {
                 /* uses 'key' (at index -2) and 'value' (at index -1) */
                 printf("%s - %s\n",
                        lua_typename(L, lua_type(L, -2)),
                        lua_typename(L, lua_type(L, -1)));
                 /* removes 'value'; keeps 'key' for next iteration */
                 lua_pop(L, 1);
               }
<
        While traversing a table, do not call `lua_tolstring` (see
        |lua_tolstring()|) directly on a key, unless you know that the
        key is actually a string. Recall that `lua_tolstring` `changes` the
        value at the given index; this confuses the next call to `lua_next`.

lua_Number                                                          *lua_Number*
>c
    typedef double lua_Number;
<
        The type of numbers in Lua. By default, it is double, but that can be
        changed in `luaconf.h`.

        Through the configuration file you can change Lua to operate with
        another type for numbers (e.g., float or long).

lua_objlen                                                        *lua_objlen()*
>c
    size_t lua_objlen (lua_State *L, int index);
<
        Returns the "length" of the value at the given acceptable index: for
        strings, this is the string length; for tables, this is the result of
        the length operator (`#`); for userdata, this is the size of the
        block of memory allocated for the userdata; for other values, it is 0.

lua_pcall                                                          *lua_pcall()*
>c
    lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);
<
        Calls a function in protected mode.

        Both `nargs` and `nresults` have the same meaning as in `lua_call`
        (see |lua_call()|). If there are no errors during the call,
        `lua_pcall` behaves exactly like `lua_call`. However, if there is any
        error, `lua_pcall` catches it, pushes a single value on the stack (the
        error message), and returns an error code. Like `lua_call`,
        `lua_pcall` always removes the function and its arguments from the
        stack.

        If `errfunc` is 0, then the error message returned on the stack is
        exactly the original error message. Otherwise, `errfunc` is the stack
        index of an `error` `handler function`. (In the current
        implementation, this index cannot be a pseudo-index.) In case of
        runtime errors, this function will be called with the error message
        and its return value will be the message returned on the stack by
        `lua_pcall`.

        Typically, the error handler function is used to add more debug
        information to the error message, such as a stack traceback. Such
        information cannot be gathered after the return

Title: Lua C API: Userdata, Table Traversal, Number Type, Object Length, and Protected Calls
Summary
This section details Lua C API functions. It explains userdatas and their garbage collection behavior. `lua_next` iterates through a table. A code snippet illustrates a typical table traversal. `lua_Number` defines the numeric type used in Lua. `lua_objlen` retrieves the "length" of a value. `lua_pcall` calls a function in protected mode, catching errors and using an optional error handler function.