Package org.sqlite

## Class Function

- java.lang.Object
- - org.sqlite.Function

Direct Known Subclasses:
  `Function.Aggregate`

    public abstract class Function
    extends Object

Provides an interface for creating SQLite user-defined functions.

A subclass of `org.sqlite.Function` can be registered with `Function.create()` and called by the name it was given. All functions must implement `xFunc()`, which is called when SQLite runs the custom function. E.g.

          Class.forName("org.sqlite.JDBC");
          Connection conn = DriverManager.getConnection("jdbc:sqlite:");

          Function.create(conn, "myFunc", new Function() {
              protected void xFunc() {
                  System.out.println("myFunc called!");
              }
          });

          conn.createStatement().execute("select myFunc();");

Arguments passed to a custom function can be accessed using the `protected` functions provided. `args()` returns the number of arguments passed, while `value_<type>(int)` returns the value of the specific argument. Similarly, a function can return a value using the `result(<type>)` function.

### Nested Class Summary

Nested Classes
`static class` `Function.Aggregate` Provides an interface for creating SQLite user-defined aggregate functions.
`static class` `Function.Window` Provides an interface for creating SQLite user-defined window functions.

### Field Summary

Fields
`static int` `FLAG_DETERMINISTIC` Flag to provide to `create(Connection, String, Function, int)` that marks this Function as deterministic, making is usable in Indexes on Expressions.

### Constructor Summary

Constructors
`Function()`

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
`protected int` `args()` Returns the number of arguments passed to the function.
`static void` `create​(Connection conn, String name, Function f)` Registers a given function with the connection.
`static void` `create​(Connection conn, String name, Function f, int flags)` Registers a given function with the connection.
`static void` `create​(Connection conn, String name, Function f, int nArgs, int flags)` Registers a given function with the connection.
`static void` `destroy​(Connection conn, String name)` Removes a named function from the given connection.
`static void` `destroy​(Connection conn, String name, int nArgs)` Removes a named function from the given connection.
`protected void` `error​(String err)` Called by `xFunc` to throw an error.
`protected void` `result()` Called by `xFunc` to return a value.
`protected void` `result​(byte[] value)` Called by `xFunc` to return a value.
`protected void` `result​(double value)` Called by `xFunc` to return a value.
`protected void` `result​(int value)` Called by `xFunc` to return a value.
`protected void` `result​(long value)` Called by `xFunc` to return a value.
`protected void` `result​(String value)` Called by `xFunc` to return a value.
`protected byte[]` `value_blob​(int arg)` Called by `xFunc` to access the value of an argument.
`protected double` `value_double​(int arg)` Called by `xFunc` to access the value of an argument.
`protected int` `value_int​(int arg)` Called by `xFunc` to access the value of an argument.
`protected long` `value_long​(int arg)` Called by `xFunc` to access the value of an argument.
`protected String` `value_text​(int arg)` Called by `xFunc` to access the value of an argument.
`protected int` `value_type​(int arg)` Called by `xFunc` to access the value of an argument.
`protected abstract void` `xFunc()` Called by SQLite as a custom function.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### FLAG_DETERMINISTIC

    public static final int FLAG_DETERMINISTIC

Flag to provide to `create(Connection, String, Function, int)` that marks this Function as deterministic, making is usable in Indexes on Expressions.

See Also:
  Constant Field Values

### Constructor Detail

#### Function

    public Function()

### Method Detail

#### create

    public static void create​(Connection conn,
                              String name,
                              Function f)
                       throws SQLException

Registers a given function with the connection.

Parameters:
  `conn` - The connection.
  `name` - The name of the function.
  `f` - The function to register.
Throws:
  `SQLException`

#### create

    public static void create​(Connection conn,
                              String name,
                              Function f,
                              int flags)
                       throws SQLException

Registers a given function with the connection.

Parameters:
  `conn` - The connection.
  `name` - The name of the function.
  `f` - The function to register.
  `flags` - Extra flags to pass, such as `FLAG_DETERMINISTIC`
Throws:
  `SQLException`

#### create

    public static void create​(Connection conn,
                              String name,
                              Function f,
                              int nArgs,
                              int flags)
                       throws SQLException

Registers a given function with the connection.

Parameters:
  `conn` - The connection.
  `name` - The name of the function.
  `f` - The function to register.
  `nArgs` - The number of arguments that the function takes.
  `flags` - Extra flags to pass, such as `FLAG_DETERMINISTIC`
Throws:
  `SQLException`

#### destroy

    public static void destroy​(Connection conn,
                               String name,
                               int nArgs)
                        throws SQLException

Removes a named function from the given connection.

Parameters:
  `conn` - The connection to remove the function from.
  `name` - The name of the function.
  `nArgs` - Ignored.
Throws:
  `SQLException`

#### destroy

    public static void destroy​(Connection conn,
                               String name)
                        throws SQLException

Removes a named function from the given connection.

Parameters:
  `conn` - The connection to remove the function from.
  `name` - The name of the function.
Throws:
  `SQLException`

#### xFunc

    protected abstract void xFunc()
                           throws SQLException

Called by SQLite as a custom function. Should access arguments through `value_*(int)`, return results with `result(*)` and throw errors with `error(String)`.

Throws:
  `SQLException`

#### args

    protected final int args()
                      throws SQLException

Returns the number of arguments passed to the function. Can only be called from `xFunc()`.

Throws:
  `SQLException`

#### result

    protected final void result​(byte[] value)
                         throws SQLException

Called by `xFunc` to return a value.

Parameters:
  `value` -
Throws:
  `SQLException`

#### result

    protected final void result​(double value)
                         throws SQLException

Called by `xFunc` to return a value.

Parameters:
  `value` -
Throws:
  `SQLException`

#### result

    protected final void result​(int value)
                         throws SQLException

Called by `xFunc` to return a value.

Parameters:
  `value` -
Throws:
  `SQLException`

#### result

    protected final void result​(long value)
                         throws SQLException

Called by `xFunc` to return a value.

Parameters:
  `value` -
Throws:
  `SQLException`

#### result

    protected final void result()
                         throws SQLException

Called by `xFunc` to return a value.

Throws:
  `SQLException`

#### result

    protected final void result​(String value)
                         throws SQLException

Called by `xFunc` to return a value.

Parameters:
  `value` -
Throws:
  `SQLException`

#### error

    protected final void error​(String err)
                        throws SQLException

Called by `xFunc` to throw an error.

Parameters:
  `err` -
Throws:
  `SQLException`

#### value_text

    protected final String value_text​(int arg)
                               throws SQLException

Called by `xFunc` to access the value of an argument.

Parameters:
  `arg` -
Throws:
  `SQLException`

#### value_blob

    protected final byte[] value_blob​(int arg)
                               throws SQLException

Called by `xFunc` to access the value of an argument.

Parameters:
  `arg` -
Throws:
  `SQLException`

#### value_double

    protected final double value_double​(int arg)
                                 throws SQLException

Called by `xFunc` to access the value of an argument.

Parameters:
  `arg` -
Throws:
  `SQLException`

#### value_int

    protected final int value_int​(int arg)
                           throws SQLException

Called by `xFunc` to access the value of an argument.

Parameters:
  `arg` -
Throws:
  `SQLException`

#### value_long

    protected final long value_long​(int arg)
                             throws SQLException

Called by `xFunc` to access the value of an argument.

Parameters:
  `arg` -
Throws:
  `SQLException`

#### value_type

    protected final int value_type​(int arg)
                            throws SQLException

Called by `xFunc` to access the value of an argument.

Parameters:
  `arg` -
Throws:
  `SQLException`