Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 102 lines (80 sloc) 3.316 kb
27d63c5b »
2001-10-22 Adding some docs for new parameter parsing API. They really should be…
1 New parameter parsing functions
2 ===============================
3
4 It should be easier to parse input parameters to an extension function.
5 Hence, borrowing from Python's example, there are now a set of functions
6 that given the string of type specifiers, can parse the input parameters
7 and store the results in the user specified variables. This avoids most
8 of the IS_* checks and convert_to_* conversions. The functions also
9 check for the appropriate number of parameters, and try to output
10 meaningful error messages.
11
12
13 Prototypes
14 ----------
15 /* Implemented. */
16 zend_parse_parameters(int num_args, char *type_spec, ...);
17 zend_parse_parameters_ex(int flags, int num_args, char *type_spec, ...);
18
19 /* Not implemented yet. */
20 zend_parse_parameters_hash(HashTable *ht, char *type_spec, ...);
21 zend_parse_parameters_hash_ex(int flags, HashTable *ht, char *type_spec, ...);
22
23
24 The zend_parse_parameters() function takes the number of parameters
25 passed to the extension function, the type specifier string, and the
26 list of pointers to variables to store the results in. The _ex() version
27 also takes 'flags' argument -- current only ZEND_PARSE_PARAMS_QUIET can
28 be used as 'flags' to specify that the function should operate quietly
29 and not output any error messages.
30
31 The auto-conversions are performed as necessary. Arrays, objects, and
32 resources cannot be autoconverted.
33
34
35 Type specifiers
36 ---------------
37 l - long
38 d - double
39 s - string (with possible null bytes) and its length
40 b - boolean, stored in zend_bool
41 r - resource (stored in zval)
42 a - array
43 o - object (of any type)
44 O - object (of specific type, specified by class entry)
45 z - the actual zval
46
47 The following characters also have a meaning in the specifier string:
48 | - indicates that the remaining parameters are optional, they
49 should be initialized to default values by the extension since they
50 will not be touched by the parsing function if they are not
51 passed to it.
52 / - use SEPARATE_ZVAL_IF_NOT_REF() on the parameter it follows
53 ! - the parameter it follows can be of specified type or NULL (only applies
54 to 'a', 'o', 'O', 'r', and 'z'). If NULL is passed, the results
55 pointer is set to NULL as well.
56
57 Examples
58 --------
59 /* Gets a long, a string and its length, and a zval */
60 long l;
61 char *s;
62 int s_len;
63 zval *param;
64 zend_parse_parameters(ZEND_NUM_ARGS(), "lsz", &l, &s, &s_len, &param);
65
66
67 /* Gets an object of class specified by my_ce, and an optional double. */
68 zval *obj;
69 double d = 0.5;
70 zend_parse_parameters(ZEND_NUM_ARGS(), "O|d", &obj, my_ce, &d);
71
72
73 /* Gets an object or null, and an array.
74 If null is passed for object, obj will be set to NULL. */
75 zval *obj;
76 zval *arr;
77 zend_parse_parameters(ZEND_NUM_ARGS(), "O!a", &obj, &arr);
78
79
80 /* Gets a separated array. */
81 zval *arr;
82 zend_parse_parameters(ZEND_NUM_ARGS(), "a/", &arr));
83
84
85 /* Get only the first three parameters (useful for varargs functions). */
86 zval *z;
87 zend_bool b;
88 zval *r;
89 zend_parse_parameters(3, "zbr!", &z, &b, &r);
90
91
92 /* Get either a set of 3 longs or a string. */
93 long l1, l2, l3;
94 char *s;
95 if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(), "lll", &l1, &l2, &l3)) {
96 /* manipulate longs */
97 } else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(), "s", &s)) {
98 /* manipulate string */
99 } else {
100 /* output error */
101 }
Something went wrong with that request. Please try again.