feat(iterator): add documentation

Author: joelwurtz

guide/src/types/iterable.md

@@ -0,0 +1,59 @@
+# `Iterable`
+
+`Iterable`s are represented either by an `array` or `Traversable` type.
+
+| `T` parameter | `&T` parameter | `T` Return type | `&T` Return type | PHP representation               |
+|---------------|----------------|-----------------| ---------------- |----------------------------------|
+| Yes           | No             | No              | No               | `ZendHashTable` or `ZendIterator` |
+
+Converting from a zval to a `Iterable` is valid when the value is either an array or an object 
+that implements the `Traversable` interface. This means that any value that can be used in a
+`foreach` loop can be converted into a `Iterable`.
+
+## Rust example
+
+```rust,no_run
+# #![cfg_attr(windows, feature(abi_vectorcall))]
+# extern crate ext_php_rs;
+# use ext_php_rs::prelude::*;
+# use ext_php_rs::types::Iterable;
+#[php_function]
+pub fn test_iterable(mut iterable: Iterable) {
+    for (k, v) in iterable.iter() {
+        println!("k: {} v: {}", k, v.string().unwrap());
+    }
+}
+# fn main() {}
+```
+
+## PHP example
+
+```php
+<?php
+
+$generator = function() {
+    yield 'hello' => 'world';
+    yield 'rust' => 'php';
+    yield 'okk';
+};
+
+$array = [
+    'hello' => 'world',
+    'rust' => 'php',
+    'okk',
+];
+
+test_iterable($generator());
+test_iterable($array);
+```
+
+Output:
+
+```text
+k: hello v: world
+k: rust v: php
+k: 0 v: okk
+k: hello v: world
+k: rust v: php
+k: 0 v: okk
+```

guide/src/types/iterator.md

@@ -0,0 +1,50 @@
+# `ZendIterator`
+
+`ZendIterator`s are represented by the `Traversable` type.
+
+| `T` parameter | `&T` parameter | `T` Return type | `&T` Return type | PHP representation |
+|---------------| -------------- |-----------------| ---------------- | ------------------ |
+| No            | Yes            | No              | No               | `ZendIterator`    |
+
+Converting from a zval to a `ZendIterator` is valid when there is an associated iterator to 
+the variable. This means that any value, at the exception of an `array`, that can be used in 
+a `foreach` loop can be converted into a `ZendIterator`. As an example, a `Generator` can be
+used but also a the result of a `query` call with `PDO`.
+
+## Rust example
+
+```rust,no_run
+# #![cfg_attr(windows, feature(abi_vectorcall))]
+# extern crate ext_php_rs;
+# use ext_php_rs::prelude::*;
+# use ext_php_rs::types::ZendIterator;
+#[php_function]
+pub fn test_iterator(iterator: &mut ZendIterator) {
+    for (k, v) in iterator.iter() {
+        println!("k: {} v: {}", k, v.string().unwrap());
+    }
+}
+# fn main() {}
+```
+
+## PHP example
+
+```php
+<?php
+
+$generator = function() {
+    yield 'hello' => 'world';
+    yield 'rust' => 'php';
+    yield 'okk';
+};
+
+test_iterator($generator());
+```
+
+Output:
+
+```text
+k: hello v: world
+k: rust v: php
+k: 0 v: okk
+```

src/types/iterable.rs

@@ -5,13 +5,16 @@ use crate::flags::DataType;
 use crate::types::iterator::IterKey;
 use crate::types::{ZendHashTable, ZendIterator, Zval};
 
+/// This type represents a PHP iterable, which can be either an array or an object implementing
+/// the Traversable interface.
 #[derive(Debug)]
 pub enum Iterable<'a> {
     Array(&'a ZendHashTable),
     Traversable(&'a mut ZendIterator),
 }
 
 impl<'a> Iterable<'a> {
+    /// Creates a new rust iterator from a PHP iterable.
     pub fn iter(&mut self) -> Iter {
         match self {
             Iterable::Array(array) => Iter::Array(array.iter()),
@@ -36,6 +39,7 @@ impl<'a> FromZval<'a> for Iterable<'a> {
     }
 }
 
+/// Rust iterator over a PHP iterable.
 pub enum Iter<'a> {
     Array(ZendHashTableIter<'a>),
     Traversable(ZendIteratorIter<'a>),

src/types/iterator.rs

@@ -13,13 +13,22 @@ use std::fmt::{Debug, Display, Formatter};
 pub type ZendIterator = zend_object_iterator;
 
 impl ZendIterator {
+    /// Creates a new rust iterator from a zend_object_iterator.
+    ///
+    /// # Returns
+    ///
+    /// Returns a iterator over the zend_object_iterator.
     pub fn iter(&mut self) -> Iter {
         self.index = 0;
         self.rewind();
 
         Iter { zi: self }
     }
 
+    /// Check if the current position of the iterator is valid.
+    ///
+    /// As an example this will call the user defined valid method of the ['\Iterator'] interface.
+    /// see https://www.php.net/manual/en/iterator.valid.php
     pub fn valid(&mut self) -> bool {
         if let Some(valid) = unsafe { (*self.funcs).valid } {
             unsafe { valid(&mut *self) != 0 }
@@ -28,6 +37,10 @@ impl ZendIterator {
         }
     }
 
+    /// Rewind the iterator to the first element.
+    ///
+    /// As an example this will call the user defined rewind method of the ['\Iterator'] interface.
+    /// see https://www.php.net/manual/en/iterator.rewind.php
     pub fn rewind(&mut self) {
         if let Some(rewind) = unsafe { (*self.funcs).rewind } {
             unsafe {
@@ -36,6 +49,10 @@ impl ZendIterator {
         }
     }
 
+    /// Move the iterator forward to the next element.
+    ///
+    /// As an example this will call the user defined next method of the ['\Iterator'] interface.
+    /// see https://www.php.net/manual/en/iterator.next.php
     pub fn move_forward(&mut self) {
         if let Some(move_forward) = unsafe { (*self.funcs).move_forward } {
             unsafe {
@@ -44,13 +61,25 @@ impl ZendIterator {
         }
     }
 
+    /// Get the current data of the iterator.
+    ///
+    /// # Returns
+    ///
+    /// Returns a reference to the current data of the iterator if available
+    /// , ['None'] otherwise.
     pub fn get_current_data<'a>(&mut self) -> Option<&'a Zval> {
         let get_current_data = unsafe { (*self.funcs).get_current_data }?;
         let value = unsafe { &*get_current_data(&mut *self) };
 
         Some(value)
     }
 
+    /// Get the current key of the iterator.
+    ///
+    /// # Returns
+    ///
+    /// Returns a new ['Zval'] containing the current key of the iterator if available
+    /// , ['None'] otherwise.
     pub fn get_current_key(&mut self) -> Option<Zval> {
         let get_current_key = unsafe { (*self.funcs).get_current_key }?;
         let mut key = Zval::new();
@@ -74,7 +103,13 @@ pub enum IterKey {
     String(String),
 }
 
+/// Represent the key of a PHP iterator, which can be either a long or a string.
 impl IterKey {
+    /// Check if the key is numerical.
+    ///
+    /// # Returns
+    ///
+    /// Returns true if the key is numerical, false otherwise.
     pub fn is_numerical(&self) -> bool {
         match self {
             IterKey::Long(_) => true,
@@ -103,6 +138,7 @@ impl FromZval<'_> for IterKey {
     }
 }
 
+/// Immutable iterator upon a reference to a PHP iterator.
 pub struct Iter<'a> {
     zi: &'a mut ZendIterator,
 }

src/types/mod.rs

@@ -16,6 +16,7 @@ mod zval;
 pub use array::ZendHashTable;
 pub use callable::ZendCallable;
 pub use class_object::ZendClassObject;
+pub use iterable::Iterable;
 pub use iterator::ZendIterator;
 pub use long::ZendLong;
 pub use object::{PropertyQuery, ZendObject};