From ed7de0678e4d027165fb79f3dabde99cb347886b Mon Sep 17 00:00:00 2001 From: Emiel Bruijntjes Date: Fri, 16 Jan 2015 13:53:59 +0100 Subject: lambda function documentation updates --- documentation/lambda-functions.html | 55 +++++++++++++++++++++++++------------ 1 file changed, 37 insertions(+), 18 deletions(-) (limited to 'documentation') diff --git a/documentation/lambda-functions.html b/documentation/lambda-functions.html index 19b7775..53cb5b9 100644 --- a/documentation/lambda-functions.html +++ b/documentation/lambda-functions.html @@ -20,7 +20,7 @@ $f = function($a, $b) { // return the sum of the parameters return $a + $b; -} +}; // pass the function to another function other_function($f); @@ -41,7 +41,8 @@ other_function(function() { but to demonstrate how to do this with PHP-CPP we are going to build it with C++. Just like all the other functions that you've seen in the earlier examples, such a C++ function function receives - a vector of Php::Value objects as its parameters. + a Php::Parmeters object as its parameter, which is a std::vector of + Php::Value objects. 

#include <phpcpp.h>
@@ -55,11 +56,12 @@ other_function(function() {
  */
 void other_function(Php::Parameters &params)
 {
-    // first parameter is an anonymous function
+    // this function is called from PHP user space, and it is called
+    // with a anonymous function as its first parameter
     Php::Value func = params[0];
     
     // the Php::Value class has implemented the operator (), which allows
-    // us to use the object just as if it is a real function.
+    // us to use the object just as if it is a real function
     Php::Value result = func(3, 4);
     
     // @todo do something with the result
@@ -90,15 +92,16 @@ extern "C" {
 

 

     It is that simple. But the other way around is possible too. Imagine
-    we have a function in PHP user space code that accepts a function
-    as it's parameter:
+    we have a function in PHP user space code that accepts a callback 
+    function. The following function is a simple version of the 
+    PHP array_map() function:
 

 

 
<php
 // function that iterates over an array, and calls a function on every
 // element in that array, it returns a new array with every item
 // replaced by the result of the callback
-function my_iterate($array, $callback) {
+function my_array_map($array, $callback) {
     
     // initial result variable
     $result = array();
@@ -143,13 +146,12 @@ void run_test()
     // the function now is callable
     Php::Value four = multiply_by_two(2);
     
-    // a Php::Function object is a derived Php::Value, and can be used
-    // as a normal Php::Value object - it just happen to store a callback,
-    // it can also be stored in a Php::Value object, without losing
-    // anything
+    // a Php::Function object is a derived Php::Value, and its value can 
+    // also be stored in a normal Php::Value object, it will then still 
+    // be a callback function then
     Php::Value value = multiply_by_two;
     
-    // the value object now also holds a function
+    // the value object now also holds the function
     Php::Value six = value(3);
     
     // create an array
@@ -160,7 +162,7 @@ void run_test()
     array[3] = 4;
     
     // call the user-space function
-    Php::Value result = Php::call("my_iterate", array, multiply_by_two);
+    Php::Value result = Php::call("my_array_map", array, multiply_by_two);
     
     // @todo do something with the result variable (which now holds
     // an array with values 2, 4, 6 and 8).
@@ -193,11 +195,11 @@ extern "C" {
     In the example we assigned a C++ lambda function to a Php::Function
     object. The Php::Function class is derived from the Php::Value class.
     The only difference between a Php::Value and a Php::Function is
-    that the constructor of Php::Function accepts a function as its 
-    parameter. Despite that difference, both classes are completely 
-    identical. In fact, we would have preferred to make it possible to
-    assign C++ functions directly to Php::Value objects, but that was
-    impossible because of calling ambiguities.
+    that the constructor of Php::Function accepts a function. Despite 
+    that difference, both classes are completely identical. In fact, we 
+    would have preferred to make it possible to assign C++ functions 
+    directly to Php::Value objects, and skip the Php::Function 
+    constructor, but that is impossible because of calling ambiguities.
 

 

     The Php::Function class can be used as if it is a normal Php::Value
@@ -206,3 +208,20 @@ extern "C" {
     In the above example we do exactly that: we call the user space
     my_iterate() function with our own 'multiply_by_two' C++ function.
 

+
Signature of the C++ function

+

+    You can pass different sort of C++ functions to the Php::Function
+    constructor, as long as they are compatible with the following two
+    function signatures:
+

+

+

+Php::Value function();
+Php::Value function(Php::Parameters &params);
+

+

+

+    Internally, the Php::Function class uses a C++ std::function object 
+    to store the function, so anything that can be stored in such a 
+    std::function object, can be assigned to the Php::Function class.
+

-- 
cgit v1.2.3