248 lines
7.0 KiB
Markdown
248 lines
7.0 KiB
Markdown
Function Pointers
|
|
=================
|
|
|
|
It is possible to store a _function pointer_ in a variable just like a normal value.
|
|
|
|
A function pointer is created via the `Fn` function, which takes a [string](strings-chars.md) parameter.
|
|
|
|
Call a function pointer via the `call` method.
|
|
|
|
|
|
Short-Hand Notation
|
|
-------------------
|
|
|
|
```admonish warning.side "Not for native"
|
|
|
|
Native Rust functions cannot use this short-hand notation.
|
|
```
|
|
|
|
Having to write `Fn("foo")` in order to create a function pointer to the [function](functions.md)
|
|
`foo` is a chore, so there is a short-hand available.
|
|
|
|
A function pointer to any _script-defined_ [function](functions.md) _within the same script_ can be
|
|
obtained simply by referring to the [function's](functions.md) name.
|
|
|
|
```rust
|
|
fn foo() { ... } // function definition
|
|
|
|
let f = foo; // function pointer to 'foo'
|
|
|
|
let f = Fn("foo"); // <- the above is equivalent to this
|
|
|
|
let g = bar; // error: variable 'bar' not found
|
|
```
|
|
|
|
The short-hand notation is particularly useful when passing [functions](functions.md) as
|
|
[closure](fn-closure.md) arguments.
|
|
|
|
```rust
|
|
fn is_even(n) { n % 2 == 0 }
|
|
|
|
let array = [1, 2, 3, 4, 5];
|
|
|
|
array.filter(is_even);
|
|
|
|
array.filter(Fn("is_even")); // <- the above is equivalent to this
|
|
|
|
array.filter(|n| n % 2 == 0); // <- ... or this
|
|
```
|
|
|
|
|
|
Built-in Functions
|
|
------------------
|
|
|
|
The following standard methods operate on function pointers.
|
|
|
|
| Function | Parameter(s) | Description |
|
|
| ---------------------------------- | ------------ | -------------------------------------------------------------------------------------------- |
|
|
| `name` method and property | _none_ | returns the name of the [function](functions.md) encapsulated by the function pointer |
|
|
| `is_anonymous` method and property | _none_ | does the function pointer refer to an [anonymous function](fn-anon.md)? |
|
|
| `call` | _arguments_ | calls the [function](functions.md) matching the function pointer's name with the _arguments_ |
|
|
|
|
|
|
Examples
|
|
--------
|
|
|
|
```rust
|
|
fn foo(x) { 41 + x }
|
|
|
|
let func = Fn("foo"); // use the 'Fn' function to create a function pointer
|
|
|
|
let func = foo; // <- short-hand: equivalent to 'Fn("foo")'
|
|
|
|
print(func); // prints 'Fn(foo)'
|
|
|
|
let func = fn_name.Fn(); // <- error: 'Fn' cannot be called in method-call style
|
|
|
|
func.type_of() == "Fn"; // type_of() as function pointer is 'Fn'
|
|
|
|
func.name == "foo";
|
|
|
|
func.call(1) == 42; // call a function pointer with the 'call' method
|
|
|
|
foo(1) == 42; // <- the above de-sugars to this
|
|
|
|
call(func, 1); // normal function call style also works for 'call'
|
|
|
|
let len = Fn("len"); // 'Fn' also works with registered native Rust functions
|
|
|
|
len.call("hello") == 5;
|
|
|
|
let fn_name = "hello"; // the function name does not have to exist yet
|
|
|
|
let hello = Fn(fn_name + "_world");
|
|
|
|
hello.call(0); // error: function not found - 'hello_world (i64)'
|
|
```
|
|
|
|
|
|
```admonish warning "Not First-Class Functions"
|
|
|
|
Beware that function pointers are _not_ first-class functions.
|
|
|
|
They are _syntactic sugar_ only, capturing only the _name_ of a [function](functions.md) to call.
|
|
They do not hold the actual [functions](functions.md).
|
|
|
|
The actual [function](functions.md) must be defined in the appropriate namespace for the call to
|
|
succeed.
|
|
```
|
|
|
|
~~~admonish warning "Global Namespace Only"
|
|
|
|
Because of their dynamic nature, function pointers cannot refer to functions in
|
|
[`import`](modules/import.md)-ed [modules](modules/index.md).
|
|
|
|
They can only refer to [functions](functions.md) defined globally within the script
|
|
or a built-in function.
|
|
|
|
```js
|
|
import "foo" as f; // assume there is 'f::do_work()'
|
|
|
|
f::do_work(); // works!
|
|
|
|
let p = Fn("f::do_work"); // error: invalid function name
|
|
|
|
fn do_work_now() { // call it from a local function
|
|
f::do_work();
|
|
}
|
|
|
|
let p = Fn("do_work_now");
|
|
|
|
p.call(); // works!
|
|
```
|
|
~~~
|
|
|
|
|
|
Dynamic Dispatch
|
|
----------------
|
|
|
|
The purpose of function pointers is to enable rudimentary _dynamic dispatch_, meaning to determine,
|
|
at runtime, which function to call among a group.
|
|
|
|
Although it is possible to simulate dynamic dispatch via a number and a large
|
|
[`if-then-else-if`](if.md) statement, using function pointers significantly simplifies the code.
|
|
|
|
```rust
|
|
let x = some_calculation();
|
|
|
|
// These are the functions to call depending on the value of 'x'
|
|
fn method1(x) { ... }
|
|
fn method2(x) { ... }
|
|
fn method3(x) { ... }
|
|
|
|
// Traditional - using decision variable
|
|
let func = sign(x);
|
|
|
|
// Dispatch with if-statement
|
|
if func == -1 {
|
|
method1(42);
|
|
} else if func == 0 {
|
|
method2(42);
|
|
} else if func == 1 {
|
|
method3(42);
|
|
}
|
|
|
|
// Using pure function pointer
|
|
let func = if x < 0 {
|
|
method1
|
|
} else if x == 0 {
|
|
method2
|
|
} else if x > 0 {
|
|
method3
|
|
};
|
|
|
|
// Dynamic dispatch
|
|
func.call(42);
|
|
|
|
// Using functions map
|
|
let map = [ method1, method2, method3 ];
|
|
|
|
let func = sign(x) + 1;
|
|
|
|
// Dynamic dispatch
|
|
map[func].call(42);
|
|
```
|
|
|
|
|
|
Bind the `this` Pointer
|
|
-----------------------
|
|
|
|
When `call` is called as a _method_ but not on a function pointer, it is possible to dynamically dispatch
|
|
to a function call while binding the object in the method call to the `this` pointer of the function.
|
|
|
|
To achieve this, pass the function pointer as the _first_ argument to `call`:
|
|
|
|
```rust
|
|
fn add(x) { // define function which uses 'this'
|
|
this += x;
|
|
}
|
|
|
|
let func = add; // function pointer to 'add'
|
|
|
|
func.call(1); // error: 'this' pointer is not bound
|
|
|
|
let x = 41;
|
|
|
|
func.call(x, 1); // error: function 'add (i64, i64)' not found
|
|
|
|
call(func, x, 1); // error: function 'add (i64, i64)' not found
|
|
|
|
x.call(func, 1); // 'this' is bound to 'x', dispatched to 'func'
|
|
|
|
x == 42;
|
|
```
|
|
|
|
Beware that this only works for [_method-call_](fn-method.md) style.
|
|
Normal function-call style cannot bind the `this` pointer (for syntactic reasons).
|
|
|
|
|
|
Currying
|
|
--------
|
|
|
|
It is possible to _curry_ a function pointer by providing partial (or all) arguments.
|
|
|
|
Currying is done via the `curry` keyword and produces a new function pointer which carries the
|
|
curried arguments.
|
|
|
|
When the curried function pointer is called, the curried arguments are inserted starting from the _left_.
|
|
|
|
The actual call arguments should be reduced by the number of curried arguments.
|
|
|
|
```rust
|
|
fn mul(x, y) { // function with two parameters
|
|
x * y
|
|
}
|
|
|
|
let func = mul; // <- de-sugars to 'Fn("mul")'
|
|
|
|
func.call(21, 2) == 42; // two arguments are required for 'mul'
|
|
|
|
let curried = func.curry(21); // currying produces a new function pointer which
|
|
// carries 21 as the first argument
|
|
|
|
let curried = curry(func, 21); // function-call style also works
|
|
|
|
curried.call(2) == 42; // <- de-sugars to 'func.call(21, 2)'
|
|
// only one argument is now required
|
|
```
|