reorganize module
This commit is contained in:
Timur Gordon
247
_archive/rhai_engine/rhaibook/ref/fn-ptr.md
Normal file
247
_archive/rhai_engine/rhaibook/ref/fn-ptr.md
Normal file
@@ -0,0 +1,247 @@
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user