diff options
author | Emiel Bruijntjes <emiel.bruijntjes@copernica.com> | 2014-03-15 23:00:43 +0100 |
---|---|---|
committer | Emiel Bruijntjes <emiel.bruijntjes@copernica.com> | 2014-03-15 23:00:43 +0100 |
commit | a83e9b3af70f35400ec5d62a4b400d55b05c3492 (patch) | |
tree | 0df38ea3740645dcf7f8bcc7d28721fffecea405 /documentation | |
parent | a471f0f0c4c09c8f83197568af7becfbf28f2e37 (diff) |
update documentation about direct buffer access
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/variables.html | 113 |
1 files changed, 113 insertions, 0 deletions
diff --git a/documentation/variables.html b/documentation/variables.html index b3f4330..a5341c7 100644 --- a/documentation/variables.html +++ b/documentation/variables.html @@ -141,6 +141,119 @@ Php::Value myFunction(const Php::Value &value) can become complicated, but for you, the extension programmer, there is nothing to worry about. </p> +<h2 id="strings">Strings</h2> +<p> + Strings can be easily stored in Php::Value objects. It is so easy to + assign a string to a Php::Value, or to cast a Php::Value into a string, + that any explanation hardly is necessary. Normally, the assignment operators + and casting operators are sufficient. When performance is an issue however, + you may consider to get direct access to the internal buffer inside the + Php::Value object. +</p> +<p> + When a Php::Value is casted to a std::string, the entire string contents + are copied from the Php::Value object to the std::string object. + If you do not want to make such a full copy, you can cast the value to a + const char * instead. This gives you direct access to the buffer inside + the Php::Value object. The size of the string can be retrieved with the size() + method. But you must realize that once the Php::Value gets out of scope, + the pointer to the buffer is no longer guaranteed to be valid. +</p> +<p> +<pre class="language-c++"><code> +/** + * Example function + * @param params + */ +void myFunction(Parameters &params) +{ + // store the first parameter in a std::string (the entire string + // buffer is copied from the Php::Value object to the std::string) + std::string var1 = params[0]; + + // it also is possible to cast the object into a const char *. This works + // too, but the buffer is only valid for as long as the Php::Value object + // stays in scope + const char *var2 = params[0]; + size_t var2size = params[0].size(); +} +</code></pre> +</p> +<p> + It also is possible to directly write to the internal Php::Value buffer. + When you assign a string to a Php::Value object, the entire string buffer + is copied too. It does not matter if the string that you assign is a + std::string or a char*: a copy is always made. For small things, this hardly + is an issue and it would make your code much less readable if you did it + differently. But if you have to copy many bytes, you can better get direct + access to the buffer. +</p> +<p> +<pre class="language-c++"><code> +/** + * Example function to read bytes from a filedescriptor, and + * return it as a Php::Value object + * + * @param fd Filedescriptor + * @return Php::Value + */ +Php::Value readExample1(int fd) +{ + // buffer to read the bytes in + char buffer[4096]; + + // read the buffer + ssize_t bytes = read(fd, buffer, 4096); + if (bytes < 0) bytes = 0; + + // convert the buffer to a Php::Value object and return it + return Php::Value(buffer, bytes); +} + +/** + * Another example function, that does the same as the previous + * function, but now it reads the bytes directly into a Php::Value + * buffer, and does not use an intermediate buffer. + * + * @param fd Filedescriptor + * @param Php::Value + */ +Php::Value readExample2(int fd) +{ + // result variable + Php::Value result; + + // resize the buffer to 4096 bytes, the resize() method resizes + // the internal buffer to the appropriate size, and returns a pointer + // to the buffer + char *buffer = result.resize(4096); + + // read in the bytes directly into the just allocated buffer + ssize_t bytes = read(fd, buffer, 4096); + if (bytes < 0) bytes = 0; + + // resize the buffer to the actual number of bytes in it (this + // is necessary, otherwise the PHP strlen() returns 4096 even + // when less bytes were available + result.resize(bytes); + + // return the result + return result; +} +</code></pre> +</p> +<p> + The first example function is easier to read. The read() system call is + used to fill a local buffer with bytes. This local buffer is then converted + to a Php::Value object and returned. +</p> +<p> + The second example function is more efficient, because the read() system + call now immediately reads the bytes into the buffer of the Php::Value + object, and not into a temporary buffer. As a programmer, you must choose + between one of these algorithms depending on your needs: easy code or more + efficient code. +</p> <h2 id="arrays">Arrays</h2> <p> PHP supports two array types: regular arrays (indexed by numbers) and |