# sol2 3.5.0 documentation

## types

### Search the Documentation

# types

nil, lua_primitive type traits, and other fundamentals

The `types.hpp` header contains various fundamentals and utilities of sol.

## enumerations

syntax of a function called by Lua

    enum class call_syntax {
    dot = 0,
    colon = 1
    };

This enumeration indicates the syntax a function was called with in a specific scenario. There are two ways to call a function: with `obj:func_name( ... )` or `obj.func_name( ... );` The first one passes “obj” as the first argument: the second one does not. In the case of usertypes, this is used to determine whether the call to a constructor/initializer was called with a `:` or a `.`, and not misalign the arguments.

status of a Lua function call

    enum class call_status : int {
        ok      = LUA_OK,
        yielded = LUA_YIELD,
        runtime = LUA_ERRRUN,
        memory  = LUA_ERRMEM,
        handler = LUA_ERRERR,
        gc      = LUA_ERRGCMM
    };

This strongly-typed enumeration contains the errors potentially generated by a call to a protected function or a coroutine.

status of a Lua thread

    enum class thread_status : int {
        ok  = LUA_OK,
        yielded = LUA_YIELD,
        runtime = LUA_ERRRUN,
        memory  = LUA_ERRMEM,
        gc      = LUA_ERRGCMM,
        handler = LUA_ERRERR,
        dead,
    };

This enumeration contains the status of a thread. The `thread_status::dead` state is generated when the thread has nothing on its stack and it is not running anything.

status of a Lua load operation

    enum class load_status : int {
        ok      = LUA_OK,
        runtime = LUA_ERRSYNTAX,
        memory  = LUA_ERRMEM,
        gc      = LUA_ERRGCMM,
        file    = LUA_ERRFILE,
    };

This enumeration contains the status of a load operation from state::load(_file).

type enumeration

    enum class type : int {
        none          = LUA_TNONE,
        lua_nil       = LUA_TNIL,
        string        = LUA_TSTRING,
        number        = LUA_TNUMBER,
        thread        = LUA_TTHREAD,
        boolean       = LUA_TBOOLEAN,
        function      = LUA_TFUNCTION,
        userdata      = LUA_TUSERDATA,
        lightuserdata = LUA_TLIGHTUSERDATA,
        table         = LUA_TTABLE,
        poly          = none   | nil     | string   | number   | thread          |
                        table  | boolean | function | userdata | lightuserdata,
        // if not in Objective C land...
        nil           = LUA_TNIL
    };

The base types that Lua natively communicates in and understands. Note that “poly” isn’t really a true type, it’s just a symbol used in sol for something whose type hasn’t been checked (and you should almost never see it).

## type traits

lua_type_of trait

    template <typename T>
    struct lua_type_of;

This type trait maps a C++ type to a type enumeration value. The default value is `type::userdata`.

primitive checking traits

    template <typename T>
    struct is_lua_primitive;

    template <typename T>
    struct is_proxy_primitive;

This trait is used by proxy to know which types should be returned as references to internal Lua memory (e.g., `userdata` types) and which ones to return as values (strings, numbers, references). `std::reference_wrapper`, `std::tuple<...>` are returned as values, but their contents can be references. The default value is false.

## special types

nil

    struct lua_nil_t {};
    constexpr lua_nil_t lua_nil {};
    bool operator==(lua_nil_t, lua_nil_t);
    bool operator!=(lua_nil_t, lua_nil_t);

    // if not in Objective-C land
    using nil_t = lua_nil_t;
    constexpr nil_t nil {};

`nil` is a constant used to signify Lua’s `nil`, which is a type and object that something does not exist. It is comparable to itself, sol::object and proxy values.

non_null

    template <typename T>
    struct non_null {};

A tag type that, when used with stack::get<non_null<T*>>, does not perform a `nil` check when attempting to retrieve the userdata pointer.

type list

    template <typename... Args>
    struct types;

A type list that, unlike `std::tuple<Args...>`, does not actually contain anything. Used to indicate types and groups of types all over sol.

## functions

type_of

    template<typename T>
    type type_of();

    type type_of(lua_State* L, int index);

These functions get the type of a C++ type `T`; or the type at the specified index on the Lua stack.

type checking convenience functions

    int type_panic_string(lua_State* L, int index, type expected, type actual, const std::string& message);

    int type_panic_c_str(lua_State* L, int index, type expected, type actual, const char* message);

    int no_panic(lua_State*, int, type, type, const char*) noexcept;

    void type_error(lua_State* L, int expected, int actual);

    void type_error(lua_State* L, type expected, type actual);

    void type_assert(lua_State* L, int index, type expected, type actual);

    void type_assert(lua_State* L, int index, type expected);

The purpose of these functions is to assert / throw / crash / error (or do nothing, as is the case with `no_panic`). They’re mostly used internally in the framework, but they’re provided here if you should need them.

type name retrieval

    std::string type_name(lua_State*L, type t);

Gets the Lua-specified name of the type.

## structs

    struct userdata_value {
            void* value;
    };

    struct light_userdata_value {
            void* value;
    };

    struct upvalue_index {
            int index;
    };

    struct raw_index {
            int index;
    };

    struct absolute_index {
            int index;
    };

    struct ref_index {
            int index;
    };

Types that differentiate between the two kinds of `void*` Lua hands back from its API: full userdata and light userdata, as well as a type that modifies the index passed to `get` to refer to up values These types can be used to trigger different underlying API calls to Lua when working with stack namespace and the `push`/`get`/`pop`/`check` functions.

The `raw_index` type is used to tell a sol::reference type or similar that the desired index – negative or not – should be passed through directly to the API.

The `absolute_index` type is used to tell a sol::reference type or similar that the desired index – negative or not – should be passed through Lua’s lua_absindex function first to adjust where it is, and then given to the underlying API.

The `ref_index` type is used to tell a sol::reference type or similar that it should look into the Lua C Registry for its type.