From fb306fd4acd46ec50eb2516fae4de5ec96db4487 Mon Sep 17 00:00:00 2001
From: Vincent Rischmann
Date: Sun, 3 Apr 2022 02:52:16 +0200
Subject: add documentation for user defined functions

---
 README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 235c995..ae5c03c 100644
--- a/README.md
+++ b/README.md
@@ -503,3 +503,33 @@ const rows = try stmt.all(usize, .{}, .{
 });
 _ = rows;
 ```
+
+## User defined functions
+
+sqlite supports [user-defined functions](https://www.sqlite.org/c3ref/create_function.html) which come in two types:
+* scalar functions
+* aggregate functions
+
+You can define a scalar function using `db.createScalarFunction`:
+```zig
+try db.createScalarFunction(
+    "blake3",
+    struct {
+        fn run(input: []const u8) [std.crypto.hash.Blake3.digest_length]u8 {
+            var hash: [std.crypto.hash.Blake3.digest_length]u8 = undefined;
+            std.crypto.hash.Blake3.hash(input, &hash, .{});
+            return hash;
+        }
+    }.run,
+    .{},
+);
+
+const hash = try db.one([std.crypto.hash.Blake3.digest_length]u8, "SELECT blake3('hello')", .{}, .{});
+```
+
+Each input arguments in the function call in the statement is passed on to the registered `run` function.
+Arguments are [sqlite3\_values](https://www.sqlite.org/c3ref/value_blob.html) and are converted to Zig values using the following rules:
+* TEXT values can be either `sqlite.Text` or `[]const u8`
+* BLOB values can be either `sqlite.Blob` or `[]const u8`
+* INTEGER values can be any Zig integer
+* REAL values can be any Zig float
-- 
cgit v1.2.3