sqlite::create_function | vsqlite++ Reference

sqlite::create_function is the high-level way to expose custom SQL functions without touching the raw SQLite C API. Provide any callable—lambda, functor, free function, or std::function—and the helper takes care of:

Use cases

Deducing the C++ parameter/return types and mapping them to SQLite value slots.
Owning the callable’s lifetime so SQLite can invoke it across statements safely.
Enabling optional flags (deterministic, direct-only, innocuous) through a single function_options struct.
Throwing a rich database_exception when registration fails so callers immediately know which function name/arity was rejected.

Example usage

sqlite::connection con{":memory:"};

auto normalize = [](std::string_view input) {
    std::string copy(input);
    std::ranges::transform(copy, copy.begin(),
        [](unsigned char c) { return std::tolower(c); });
    return copy;
};

sqlite::create_function(
    con,
    "normalize_text",
    normalize,
    {.deterministic = true}
);

sqlite::query q{con, "SELECT normalize_text(?)"};
q % "Déjà Vu";
std::cout << q.begin()->get<std::string>(0);

vsqlite++ stores your callable inside SQLite’s user-data slot, so lambdas with captures are fine—the wrapper makes sure the destructor runs when the function is removed.

`struct function_options`

Member	Description
`int arity = -1`	Override the callable's arity when the signature should be hidden. Defaults to the deduced number of parameters.
`int text_representation = SQLITE_UTF8`	Encoding flag passed to SQLite.
`bool deterministic = false`	Marks the function `SQLITE_DETERMINISTIC` when supported.
`bool direct_only = false`	Opt in to `SQLITE_DIRECTONLY`.
`bool innocuous = false`	Opt in to `SQLITE_INNOCUOUS`.

Registration

Signature	Description
`template<typename Callable> void create_function(connection& con, std::string_view name, Callable&& callable, function_options opts = {})`	Checks that `opts.arity` matches the callable (unless negative). Composes the text-representation bitmask (UTF-8 plus deterministic/direct/innocuous when available). Registers the function and throws `database_exception_code` on failure. Supports void-returning functions (SQLite receives NULL) and value-returning functions (converted via built-in result writers).