Skip to content

Commit 0ddb0e8

Browse files
committed
Didn't actually add the README in the last commit.
1 parent fb49265 commit 0ddb0e8

File tree

1 file changed

+33
-27
lines changed

1 file changed

+33
-27
lines changed

README.md

Lines changed: 33 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -76,14 +76,14 @@ A Julia interface to the SQLite library and support for operations on DataFrames
7676

7777
`drop` is pretty self-explanatory. It's really just a convenience wrapper around `query` to execute a DROP TABLE command, while also calling "VACUUM" to clean out freed memory from the database.
7878

79-
* `registerfunc(db::SQLiteDB, nargs::Int, func::Function, isdeterm::Bool=true; name="")`
79+
* `register(db::SQLiteDB, func::Function; nargs::Int=-1, name::AbstractString=string(func), isdeterm::Bool=true)`
80+
* `register(db::SQLiteDB, init, step::Function, final::Function; nargs::Int=-1, name::AbstractString=string(final), isdeterm::Bool=true)`
8081

81-
Register a function `func` (which takes `nargs` number of arguments) with the SQLite database connection `db`. If the keyword argument `name` is given the function is registered with that name, otherwise it is registered with the name of `func`. If the function is stochastic (e.g. uses a random number) `isdeterm` should be set to `false`, see SQLite's [function creation documentation](http://sqlite.org/c3ref/create_function.html) for more information.
82+
Register a scalar (first method) or aggregate (second method) function with a `SQLiteDB`.
8283

83-
* `@scalarfunc function`
84-
`@scalarfunc name function`
84+
* `@register db function`
8585

86-
Define a function which can then be passed to `registerfunc`. In the first usage the function name is infered from the function definition, in the second it is explicitly given as the first parameter. The second form is only recommended when it's use is absolutely necessary, see below.
86+
Automatically define then register `function` with a `SQLiteDB`.
8787

8888
* `sr"..."`
8989

@@ -188,45 +188,31 @@ The sr"..." currently escapes all special characters in a string but it may be c
188188

189189
##### Custom Scalar Functions
190190

191-
SQLite.jl also provides a way that you can implement your own [Scalar Functions](https://www.sqlite.org/lang_corefunc.html) (though [Aggregate Functions](https://www.sqlite.org/lang_aggfunc.html) are not currently supported). This is done using the `registerfunc` function and `@scalarfunc` macro.
191+
SQLite.jl also provides a way that you can implement your own [Scalar Functions](https://www.sqlite.org/lang_corefunc.html). This is done using the `register` function and macro.
192192

193-
`@scalarfunc` takes an optional function name and a function and defines a new function which can be passed to `registerfunc`. It can be used with block function syntax
193+
`@register` takes a `SQLiteDB` and a function. The function can be in block syntax
194194

195195
```julia
196-
julia> @scalarfunc function add3(x)
196+
julia> @register db function add3(x)
197197
x + 3
198198
end
199-
add3 (generic function with 1 method)
200-
201-
julia> @scalarfunc add5 function irrelevantfuncname(x)
202-
x + 5
203-
end
204-
add5 (generic function with 1 method)
205199
```
206200

207201
inline function syntax
208202

209203
```julia
210-
julia> @scalarfunc mult3(x) = 3 * x
211-
mult3 (generic function with 1 method)
212-
213-
julia> @scalarfunc mult5 anotherirrelevantname(x) = 5 * x
214-
mult5 (generic function with 1 method)
204+
julia> @register db mult3(x) = 3 * x
215205
```
216206

217-
and previously defined functions (note that name inference does not work with this method)
207+
and previously defined functions
218208

219209
```julia
220-
julia> @scalarfunc sin sin
221-
sin (generic function with 1 method)
222-
223-
julia> @scalarfunc subtract -
224-
subtract (generic function with 1 method)
210+
julia> @register db sin
225211
```
226212

227-
The function that is defined can then be passed to `registerfunc`. `registerfunc` takes three arguments; the database to which the function should be registered, the number of arguments that the function takes and the function itself. The function is registered to the database connection rather than the database itself so must be registered each time the database opens. Your function can not take more than 127 arguments unless it takes a variable number of arguments, if it does take a variable number of arguments then you must pass -1 as the second argument to `registerfunc`.
213+
The `register` function takes optional arguments; `nargs` which defaults to `-1`, `name` which defaults to the name of the function, `isdeterm` which defaults to `true`. In practice these rarely need to be used.
228214

229-
The `@scalarfunc` macro uses the `sqlreturn` function to return your function's return value to SQLite. By default, `sqlreturn` maps the returned value to a [native SQLite type](http://sqlite.org/c3ref/result_blob.html) or, failing that, serializes the julia value and stores it as a `BLOB`. To change this behaviour simply define a new method for `sqlreturn` which then calls a previously defined method for `sqlreturn`. Methods which map to native SQLite types are
215+
The `register` function uses the `sqlreturn` function to return your function's return value to SQLite. By default, `sqlreturn` maps the returned value to a [native SQLite type](http://sqlite.org/c3ref/result_blob.html) or, failing that, serializes the julia value and stores it as a `BLOB`. To change this behaviour simply define a new method for `sqlreturn` which then calls a previously defined method for `sqlreturn`. Methods which map to native SQLite types are
230216

231217
```julia
232218
sqlreturn(context, ::NullType)
@@ -251,3 +237,23 @@ sqlreturn(context, val::Bool) = sqlreturn(context, int(val))
251237
```
252238

253239
Any new method defined for `sqlreturn` must take two arguments and must pass the first argument straight through as the first argument.
240+
241+
#### Custom Aggregate Functions
242+
243+
Using the `register` function, you can also define your own aggregate functions with largely the same semantics.
244+
245+
The `register` function for aggregates must take a `SQLiteDB`, an initial value, a step function and a final function. The first argument to the step function will be the return value of the previous function (or the initial value if it is the first iteration). The final function must take a single argument which will be the return value of the last step function.
246+
247+
```julia
248+
julia> dsum(prev, cur) = prev + cur
249+
250+
julia> dsum(prev) = 2 * prev
251+
252+
julia> register(db, 0, dsum, dsum)
253+
```
254+
255+
If no name is given the name of the second (final) function is used (in this case "dsum"). You can also use lambdas, the following does the same as the previous code snippet
256+
257+
```julia
258+
julia> register(db, 0, (p,c) -> p+c, p -> 2p, name="dsum")
259+
```

0 commit comments

Comments
 (0)