xref: /PHP-8.1/Zend/zend_iterators.h (revision 312201dc)
1 /*
2    +----------------------------------------------------------------------+
3    | Zend Engine                                                          |
4    +----------------------------------------------------------------------+
5    | Copyright (c) Zend Technologies Ltd. (http://www.zend.com)           |
6    +----------------------------------------------------------------------+
7    | This source file is subject to version 2.00 of the Zend license,     |
8    | that is bundled with this package in the file LICENSE, and is        |
9    | available through the world-wide-web at the following url:           |
10    | http://www.zend.com/license/2_00.txt.                                |
11    | If you did not receive a copy of the Zend license and are unable to  |
12    | obtain it through the world-wide-web, please send a note to          |
13    | license@zend.com so we can mail you a copy immediately.              |
14    +----------------------------------------------------------------------+
15    | Author: Wez Furlong <wez@thebrainroom.com>                           |
16    |         Marcus Boerger <helly@php.net>                               |
17    +----------------------------------------------------------------------+
18 */
19 
20 /* These iterators were designed to operate within the foreach()
21  * structures provided by the engine, but could be extended for use
22  * with other iterative engine opcodes.
23  * These methods have similar semantics to the zend_hash API functions
24  * with similar names.
25  * */
26 
27 typedef struct _zend_object_iterator zend_object_iterator;
28 
29 typedef struct _zend_object_iterator_funcs {
30 	/* release all resources associated with this iterator instance */
31 	void (*dtor)(zend_object_iterator *iter);
32 
33 	/* check for end of iteration (FAILURE or SUCCESS if data is valid) */
34 	int (*valid)(zend_object_iterator *iter);
35 
36 	/* fetch the item data for the current element */
37 	zval *(*get_current_data)(zend_object_iterator *iter);
38 
39 	/* fetch the key for the current element (optional, may be NULL). The key
40 	 * should be written into the provided zval* using the ZVAL_* macros. If
41 	 * this handler is not provided auto-incrementing integer keys will be
42 	 * used. */
43 	void (*get_current_key)(zend_object_iterator *iter, zval *key);
44 
45 	/* step forwards to next element */
46 	void (*move_forward)(zend_object_iterator *iter);
47 
48 	/* rewind to start of data (optional, may be NULL) */
49 	void (*rewind)(zend_object_iterator *iter);
50 
51 	/* invalidate current value/key (optional, may be NULL) */
52 	void (*invalidate_current)(zend_object_iterator *iter);
53 
54 	/* Expose owned values to GC.
55 	 * This has the same semantics as the corresponding object handler. */
56 	HashTable *(*get_gc)(zend_object_iterator *iter, zval **table, int *n);
57 } zend_object_iterator_funcs;
58 
59 struct _zend_object_iterator {
60 	zend_object std;
61 	zval data;
62 	const zend_object_iterator_funcs *funcs;
63 	zend_ulong index; /* private to fe_reset/fe_fetch opcodes */
64 };
65 
66 typedef struct _zend_class_iterator_funcs {
67 	zend_function *zf_new_iterator;
68 	zend_function *zf_valid;
69 	zend_function *zf_current;
70 	zend_function *zf_key;
71 	zend_function *zf_next;
72 	zend_function *zf_rewind;
73 } zend_class_iterator_funcs;
74 
75 BEGIN_EXTERN_C()
76 /* given a zval, returns stuff that can be used to iterate it. */
77 ZEND_API zend_object_iterator* zend_iterator_unwrap(zval *array_ptr);
78 
79 /* given an iterator, wrap it up as a zval for use by the engine opcodes */
80 ZEND_API void zend_iterator_init(zend_object_iterator *iter);
81 ZEND_API void zend_iterator_dtor(zend_object_iterator *iter);
82 
83 ZEND_API void zend_register_iterator_wrapper(void);
84 END_EXTERN_C()
85