Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PERLAPI 1" | |
132 | .TH PERLAPI 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | perlapi \- autogenerated documentation for the perl public API | |
135 | .SH "DESCRIPTION" | |
136 | .IX Xref "Perl API API api" | |
137 | .IX Header "DESCRIPTION" | |
138 | This file contains the documentation of the perl public \s-1API\s0 generated by | |
139 | embed.pl, specifically a listing of functions, macros, flags, and variables | |
140 | that may be used by extension writers. The interfaces of any functions that | |
141 | are not listed here are subject to change without notice. For this reason, | |
142 | blindly using functions listed in proto.h is to be avoided when writing | |
143 | extensions. | |
144 | .PP | |
145 | Note that all Perl \s-1API\s0 global variables must be referenced with the \f(CW\*(C`PL_\*(C'\fR | |
146 | prefix. Some macros are provided for compatibility with the older, | |
147 | unadorned names, but this support may be disabled in a future release. | |
148 | .PP | |
149 | The listing is alphabetical, case insensitive. | |
150 | .ie n .SH """Gimme"" Values" | |
151 | .el .SH "``Gimme'' Values" | |
152 | .IX Header "Gimme Values" | |
153 | .IP "\s-1GIMME\s0" 8 | |
154 | .IX Xref "GIMME" | |
155 | .IX Item "GIMME" | |
156 | A backward-compatible version of \f(CW\*(C`GIMME_V\*(C'\fR which can only return | |
157 | \&\f(CW\*(C`G_SCALAR\*(C'\fR or \f(CW\*(C`G_ARRAY\*(C'\fR; in a void context, it returns \f(CW\*(C`G_SCALAR\*(C'\fR. | |
158 | Deprecated. Use \f(CW\*(C`GIMME_V\*(C'\fR instead. | |
159 | .Sp | |
160 | .Vb 1 | |
161 | \& U32 GIMME | |
162 | .Ve | |
163 | .IP "\s-1GIMME_V\s0" 8 | |
164 | .IX Xref "GIMME_V" | |
165 | .IX Item "GIMME_V" | |
166 | The XSUB\-writer's equivalent to Perl's \f(CW\*(C`wantarray\*(C'\fR. Returns \f(CW\*(C`G_VOID\*(C'\fR, | |
167 | \&\f(CW\*(C`G_SCALAR\*(C'\fR or \f(CW\*(C`G_ARRAY\*(C'\fR for void, scalar or list context, | |
168 | respectively. | |
169 | .Sp | |
170 | .Vb 1 | |
171 | \& U32 GIMME_V | |
172 | .Ve | |
173 | .IP "G_ARRAY" 8 | |
174 | .IX Xref "G_ARRAY" | |
175 | .IX Item "G_ARRAY" | |
176 | Used to indicate list context. See \f(CW\*(C`GIMME_V\*(C'\fR, \f(CW\*(C`GIMME\*(C'\fR and | |
177 | perlcall. | |
178 | .IP "G_DISCARD" 8 | |
179 | .IX Xref "G_DISCARD" | |
180 | .IX Item "G_DISCARD" | |
181 | Indicates that arguments returned from a callback should be discarded. See | |
182 | perlcall. | |
183 | .IP "G_EVAL" 8 | |
184 | .IX Xref "G_EVAL" | |
185 | .IX Item "G_EVAL" | |
186 | Used to force a Perl \f(CW\*(C`eval\*(C'\fR wrapper around a callback. See | |
187 | perlcall. | |
188 | .IP "G_NOARGS" 8 | |
189 | .IX Xref "G_NOARGS" | |
190 | .IX Item "G_NOARGS" | |
191 | Indicates that no arguments are being sent to a callback. See | |
192 | perlcall. | |
193 | .IP "G_SCALAR" 8 | |
194 | .IX Xref "G_SCALAR" | |
195 | .IX Item "G_SCALAR" | |
196 | Used to indicate scalar context. See \f(CW\*(C`GIMME_V\*(C'\fR, \f(CW\*(C`GIMME\*(C'\fR, and | |
197 | perlcall. | |
198 | .IP "G_VOID" 8 | |
199 | .IX Xref "G_VOID" | |
200 | .IX Item "G_VOID" | |
201 | Used to indicate void context. See \f(CW\*(C`GIMME_V\*(C'\fR and perlcall. | |
202 | .SH "Array Manipulation Functions" | |
203 | .IX Header "Array Manipulation Functions" | |
204 | .IP "AvFILL" 8 | |
205 | .IX Xref "AvFILL" | |
206 | .IX Item "AvFILL" | |
207 | Same as \f(CW\*(C`av_len()\*(C'\fR. Deprecated, use \f(CW\*(C`av_len()\*(C'\fR instead. | |
208 | .Sp | |
209 | .Vb 1 | |
210 | \& int AvFILL(AV* av) | |
211 | .Ve | |
212 | .IP "av_clear" 8 | |
213 | .IX Xref "av_clear" | |
214 | .IX Item "av_clear" | |
215 | Clears an array, making it empty. Does not free the memory used by the | |
216 | array itself. | |
217 | .Sp | |
218 | .Vb 1 | |
219 | \& void av_clear(AV* ar) | |
220 | .Ve | |
221 | .IP "av_delete" 8 | |
222 | .IX Xref "av_delete" | |
223 | .IX Item "av_delete" | |
224 | Deletes the element indexed by \f(CW\*(C`key\*(C'\fR from the array. Returns the | |
225 | deleted element. If \f(CW\*(C`flags\*(C'\fR equals \f(CW\*(C`G_DISCARD\*(C'\fR, the element is freed | |
226 | and null is returned. | |
227 | .Sp | |
228 | .Vb 1 | |
229 | \& SV* av_delete(AV* ar, I32 key, I32 flags) | |
230 | .Ve | |
231 | .IP "av_exists" 8 | |
232 | .IX Xref "av_exists" | |
233 | .IX Item "av_exists" | |
234 | Returns true if the element indexed by \f(CW\*(C`key\*(C'\fR has been initialized. | |
235 | .Sp | |
236 | This relies on the fact that uninitialized array elements are set to | |
237 | \&\f(CW&PL_sv_undef\fR. | |
238 | .Sp | |
239 | .Vb 1 | |
240 | \& bool av_exists(AV* ar, I32 key) | |
241 | .Ve | |
242 | .IP "av_extend" 8 | |
243 | .IX Xref "av_extend" | |
244 | .IX Item "av_extend" | |
245 | Pre-extend an array. The \f(CW\*(C`key\*(C'\fR is the index to which the array should be | |
246 | extended. | |
247 | .Sp | |
248 | .Vb 1 | |
249 | \& void av_extend(AV* ar, I32 key) | |
250 | .Ve | |
251 | .IP "av_fetch" 8 | |
252 | .IX Xref "av_fetch" | |
253 | .IX Item "av_fetch" | |
254 | Returns the \s-1SV\s0 at the specified index in the array. The \f(CW\*(C`key\*(C'\fR is the | |
255 | index. If \f(CW\*(C`lval\*(C'\fR is set then the fetch will be part of a store. Check | |
256 | that the return value is non-null before dereferencing it to a \f(CW\*(C`SV*\*(C'\fR. | |
257 | .Sp | |
258 | See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" in perlguts for | |
259 | more information on how to use this function on tied arrays. | |
260 | .Sp | |
261 | .Vb 1 | |
262 | \& SV** av_fetch(AV* ar, I32 key, I32 lval) | |
263 | .Ve | |
264 | .IP "av_fill" 8 | |
265 | .IX Xref "av_fill" | |
266 | .IX Item "av_fill" | |
267 | Ensure than an array has a given number of elements, equivalent to | |
268 | Perl's \f(CW\*(C`$#array = $fill;\*(C'\fR. | |
269 | .Sp | |
270 | .Vb 1 | |
271 | \& void av_fill(AV* ar, I32 fill) | |
272 | .Ve | |
273 | .IP "av_len" 8 | |
274 | .IX Xref "av_len" | |
275 | .IX Item "av_len" | |
276 | Returns the highest index in the array. Returns \-1 if the array is | |
277 | empty. | |
278 | .Sp | |
279 | .Vb 1 | |
280 | \& I32 av_len(AV* ar) | |
281 | .Ve | |
282 | .IP "av_make" 8 | |
283 | .IX Xref "av_make" | |
284 | .IX Item "av_make" | |
285 | Creates a new \s-1AV\s0 and populates it with a list of SVs. The SVs are copied | |
286 | into the array, so they may be freed after the call to av_make. The new \s-1AV\s0 | |
287 | will have a reference count of 1. | |
288 | .Sp | |
289 | .Vb 1 | |
290 | \& AV* av_make(I32 size, SV** svp) | |
291 | .Ve | |
292 | .IP "av_pop" 8 | |
293 | .IX Xref "av_pop" | |
294 | .IX Item "av_pop" | |
295 | Pops an \s-1SV\s0 off the end of the array. Returns \f(CW&PL_sv_undef\fR if the array | |
296 | is empty. | |
297 | .Sp | |
298 | .Vb 1 | |
299 | \& SV* av_pop(AV* ar) | |
300 | .Ve | |
301 | .IP "av_push" 8 | |
302 | .IX Xref "av_push" | |
303 | .IX Item "av_push" | |
304 | Pushes an \s-1SV\s0 onto the end of the array. The array will grow automatically | |
305 | to accommodate the addition. | |
306 | .Sp | |
307 | .Vb 1 | |
308 | \& void av_push(AV* ar, SV* val) | |
309 | .Ve | |
310 | .IP "av_shift" 8 | |
311 | .IX Xref "av_shift" | |
312 | .IX Item "av_shift" | |
313 | Shifts an \s-1SV\s0 off the beginning of the array. | |
314 | .Sp | |
315 | .Vb 1 | |
316 | \& SV* av_shift(AV* ar) | |
317 | .Ve | |
318 | .IP "av_store" 8 | |
319 | .IX Xref "av_store" | |
320 | .IX Item "av_store" | |
321 | Stores an \s-1SV\s0 in an array. The array index is specified as \f(CW\*(C`key\*(C'\fR. The | |
322 | return value will be \s-1NULL\s0 if the operation failed or if the value did not | |
323 | need to be actually stored within the array (as in the case of tied | |
324 | arrays). Otherwise it can be dereferenced to get the original \f(CW\*(C`SV*\*(C'\fR. Note | |
325 | that the caller is responsible for suitably incrementing the reference | |
326 | count of \f(CW\*(C`val\*(C'\fR before the call, and decrementing it if the function | |
327 | returned \s-1NULL\s0. | |
328 | .Sp | |
329 | See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" in perlguts for | |
330 | more information on how to use this function on tied arrays. | |
331 | .Sp | |
332 | .Vb 1 | |
333 | \& SV** av_store(AV* ar, I32 key, SV* val) | |
334 | .Ve | |
335 | .IP "av_undef" 8 | |
336 | .IX Xref "av_undef" | |
337 | .IX Item "av_undef" | |
338 | Undefines the array. Frees the memory used by the array itself. | |
339 | .Sp | |
340 | .Vb 1 | |
341 | \& void av_undef(AV* ar) | |
342 | .Ve | |
343 | .IP "av_unshift" 8 | |
344 | .IX Xref "av_unshift" | |
345 | .IX Item "av_unshift" | |
346 | Unshift the given number of \f(CW\*(C`undef\*(C'\fR values onto the beginning of the | |
347 | array. The array will grow automatically to accommodate the addition. You | |
348 | must then use \f(CW\*(C`av_store\*(C'\fR to assign values to these new elements. | |
349 | .Sp | |
350 | .Vb 1 | |
351 | \& void av_unshift(AV* ar, I32 num) | |
352 | .Ve | |
353 | .IP "get_av" 8 | |
354 | .IX Xref "get_av" | |
355 | .IX Item "get_av" | |
356 | Returns the \s-1AV\s0 of the specified Perl array. If \f(CW\*(C`create\*(C'\fR is set and the | |
357 | Perl variable does not exist then it will be created. If \f(CW\*(C`create\*(C'\fR is not | |
358 | set and the variable does not exist then \s-1NULL\s0 is returned. | |
359 | .Sp | |
360 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
361 | .Sp | |
362 | .Vb 1 | |
363 | \& AV* get_av(const char* name, I32 create) | |
364 | .Ve | |
365 | .IP "newAV" 8 | |
366 | .IX Xref "newAV" | |
367 | .IX Item "newAV" | |
368 | Creates a new \s-1AV\s0. The reference count is set to 1. | |
369 | .Sp | |
370 | .Vb 1 | |
371 | \& AV* newAV() | |
372 | .Ve | |
373 | .IP "sortsv" 8 | |
374 | .IX Xref "sortsv" | |
375 | .IX Item "sortsv" | |
376 | Sort an array. Here is an example: | |
377 | .Sp | |
378 | .Vb 1 | |
379 | \& sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale); | |
380 | .Ve | |
381 | .Sp | |
382 | See lib/sort.pm for details about controlling the sorting algorithm. | |
383 | .Sp | |
384 | .Vb 1 | |
385 | \& void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp) | |
386 | .Ve | |
387 | .SH "Callback Functions" | |
388 | .IX Header "Callback Functions" | |
389 | .IP "call_argv" 8 | |
390 | .IX Xref "call_argv" | |
391 | .IX Item "call_argv" | |
392 | Performs a callback to the specified Perl sub. See perlcall. | |
393 | .Sp | |
394 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
395 | .Sp | |
396 | .Vb 1 | |
397 | \& I32 call_argv(const char* sub_name, I32 flags, char** argv) | |
398 | .Ve | |
399 | .IP "call_method" 8 | |
400 | .IX Xref "call_method" | |
401 | .IX Item "call_method" | |
402 | Performs a callback to the specified Perl method. The blessed object must | |
403 | be on the stack. See perlcall. | |
404 | .Sp | |
405 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
406 | .Sp | |
407 | .Vb 1 | |
408 | \& I32 call_method(const char* methname, I32 flags) | |
409 | .Ve | |
410 | .IP "call_pv" 8 | |
411 | .IX Xref "call_pv" | |
412 | .IX Item "call_pv" | |
413 | Performs a callback to the specified Perl sub. See perlcall. | |
414 | .Sp | |
415 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
416 | .Sp | |
417 | .Vb 1 | |
418 | \& I32 call_pv(const char* sub_name, I32 flags) | |
419 | .Ve | |
420 | .IP "call_sv" 8 | |
421 | .IX Xref "call_sv" | |
422 | .IX Item "call_sv" | |
423 | Performs a callback to the Perl sub whose name is in the \s-1SV\s0. See | |
424 | perlcall. | |
425 | .Sp | |
426 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
427 | .Sp | |
428 | .Vb 1 | |
429 | \& I32 call_sv(SV* sv, I32 flags) | |
430 | .Ve | |
431 | .IP "\s-1ENTER\s0" 8 | |
432 | .IX Xref "ENTER" | |
433 | .IX Item "ENTER" | |
434 | Opening bracket on a callback. See \f(CW\*(C`LEAVE\*(C'\fR and perlcall. | |
435 | .Sp | |
436 | .Vb 1 | |
437 | \& ENTER; | |
438 | .Ve | |
439 | .IP "eval_pv" 8 | |
440 | .IX Xref "eval_pv" | |
441 | .IX Item "eval_pv" | |
442 | Tells Perl to \f(CW\*(C`eval\*(C'\fR the given string and return an SV* result. | |
443 | .Sp | |
444 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
445 | .Sp | |
446 | .Vb 1 | |
447 | \& SV* eval_pv(const char* p, I32 croak_on_error) | |
448 | .Ve | |
449 | .IP "eval_sv" 8 | |
450 | .IX Xref "eval_sv" | |
451 | .IX Item "eval_sv" | |
452 | Tells Perl to \f(CW\*(C`eval\*(C'\fR the string in the \s-1SV\s0. | |
453 | .Sp | |
454 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
455 | .Sp | |
456 | .Vb 1 | |
457 | \& I32 eval_sv(SV* sv, I32 flags) | |
458 | .Ve | |
459 | .IP "\s-1FREETMPS\s0" 8 | |
460 | .IX Xref "FREETMPS" | |
461 | .IX Item "FREETMPS" | |
462 | Closing bracket for temporaries on a callback. See \f(CW\*(C`SAVETMPS\*(C'\fR and | |
463 | perlcall. | |
464 | .Sp | |
465 | .Vb 1 | |
466 | \& FREETMPS; | |
467 | .Ve | |
468 | .IP "\s-1LEAVE\s0" 8 | |
469 | .IX Xref "LEAVE" | |
470 | .IX Item "LEAVE" | |
471 | Closing bracket on a callback. See \f(CW\*(C`ENTER\*(C'\fR and perlcall. | |
472 | .Sp | |
473 | .Vb 1 | |
474 | \& LEAVE; | |
475 | .Ve | |
476 | .IP "\s-1SAVETMPS\s0" 8 | |
477 | .IX Xref "SAVETMPS" | |
478 | .IX Item "SAVETMPS" | |
479 | Opening bracket for temporaries on a callback. See \f(CW\*(C`FREETMPS\*(C'\fR and | |
480 | perlcall. | |
481 | .Sp | |
482 | .Vb 1 | |
483 | \& SAVETMPS; | |
484 | .Ve | |
485 | .SH "Character classes" | |
486 | .IX Header "Character classes" | |
487 | .IP "isALNUM" 8 | |
488 | .IX Xref "isALNUM" | |
489 | .IX Item "isALNUM" | |
490 | Returns a boolean indicating whether the C \f(CW\*(C`char\*(C'\fR is an \s-1ASCII\s0 alphanumeric | |
491 | character (including underscore) or digit. | |
492 | .Sp | |
493 | .Vb 1 | |
494 | \& bool isALNUM(char ch) | |
495 | .Ve | |
496 | .IP "isALPHA" 8 | |
497 | .IX Xref "isALPHA" | |
498 | .IX Item "isALPHA" | |
499 | Returns a boolean indicating whether the C \f(CW\*(C`char\*(C'\fR is an \s-1ASCII\s0 alphabetic | |
500 | character. | |
501 | .Sp | |
502 | .Vb 1 | |
503 | \& bool isALPHA(char ch) | |
504 | .Ve | |
505 | .IP "isDIGIT" 8 | |
506 | .IX Xref "isDIGIT" | |
507 | .IX Item "isDIGIT" | |
508 | Returns a boolean indicating whether the C \f(CW\*(C`char\*(C'\fR is an \s-1ASCII\s0 | |
509 | digit. | |
510 | .Sp | |
511 | .Vb 1 | |
512 | \& bool isDIGIT(char ch) | |
513 | .Ve | |
514 | .IP "isLOWER" 8 | |
515 | .IX Xref "isLOWER" | |
516 | .IX Item "isLOWER" | |
517 | Returns a boolean indicating whether the C \f(CW\*(C`char\*(C'\fR is a lowercase | |
518 | character. | |
519 | .Sp | |
520 | .Vb 1 | |
521 | \& bool isLOWER(char ch) | |
522 | .Ve | |
523 | .IP "isSPACE" 8 | |
524 | .IX Xref "isSPACE" | |
525 | .IX Item "isSPACE" | |
526 | Returns a boolean indicating whether the C \f(CW\*(C`char\*(C'\fR is whitespace. | |
527 | .Sp | |
528 | .Vb 1 | |
529 | \& bool isSPACE(char ch) | |
530 | .Ve | |
531 | .IP "isUPPER" 8 | |
532 | .IX Xref "isUPPER" | |
533 | .IX Item "isUPPER" | |
534 | Returns a boolean indicating whether the C \f(CW\*(C`char\*(C'\fR is an uppercase | |
535 | character. | |
536 | .Sp | |
537 | .Vb 1 | |
538 | \& bool isUPPER(char ch) | |
539 | .Ve | |
540 | .IP "toLOWER" 8 | |
541 | .IX Xref "toLOWER" | |
542 | .IX Item "toLOWER" | |
543 | Converts the specified character to lowercase. | |
544 | .Sp | |
545 | .Vb 1 | |
546 | \& char toLOWER(char ch) | |
547 | .Ve | |
548 | .IP "toUPPER" 8 | |
549 | .IX Xref "toUPPER" | |
550 | .IX Item "toUPPER" | |
551 | Converts the specified character to uppercase. | |
552 | .Sp | |
553 | .Vb 1 | |
554 | \& char toUPPER(char ch) | |
555 | .Ve | |
556 | .SH "Cloning an interpreter" | |
557 | .IX Header "Cloning an interpreter" | |
558 | .IP "perl_clone" 8 | |
559 | .IX Xref "perl_clone" | |
560 | .IX Item "perl_clone" | |
561 | Create and return a new interpreter by cloning the current one. | |
562 | .Sp | |
563 | perl_clone takes these flags as parameters: | |
564 | .Sp | |
565 | CLONEf_COPY_STACKS \- is used to, well, copy the stacks also, | |
566 | without it we only clone the data and zero the stacks, | |
567 | with it we copy the stacks and the new perl interpreter is | |
568 | ready to run at the exact same point as the previous one. | |
569 | The pseudo-fork code uses \s-1COPY_STACKS\s0 while the | |
570 | threads\->new doesn't. | |
571 | .Sp | |
572 | CLONEf_KEEP_PTR_TABLE | |
573 | perl_clone keeps a ptr_table with the pointer of the old | |
574 | variable as a key and the new variable as a value, | |
575 | this allows it to check if something has been cloned and not | |
576 | clone it again but rather just use the value and increase the | |
577 | refcount. If \s-1KEEP_PTR_TABLE\s0 is not set then perl_clone will kill | |
578 | the ptr_table using the function | |
579 | \&\f(CW\*(C`ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;\*(C'\fR, | |
580 | reason to keep it around is if you want to dup some of your own | |
581 | variable who are outside the graph perl scans, example of this | |
582 | code is in threads.xs create | |
583 | .Sp | |
584 | CLONEf_CLONE_HOST | |
585 | This is a win32 thing, it is ignored on unix, it tells perls | |
586 | win32host code (which is c++) to clone itself, this is needed on | |
587 | win32 if you want to run two threads at the same time, | |
588 | if you just want to do some stuff in a separate perl interpreter | |
589 | and then throw it away and return to the original one, | |
590 | you don't need to do anything. | |
591 | .Sp | |
592 | .Vb 1 | |
593 | \& PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags) | |
594 | .Ve | |
595 | .SH "CV Manipulation Functions" | |
596 | .IX Header "CV Manipulation Functions" | |
597 | .IP "CvSTASH" 8 | |
598 | .IX Xref "CvSTASH" | |
599 | .IX Item "CvSTASH" | |
600 | Returns the stash of the \s-1CV\s0. | |
601 | .Sp | |
602 | .Vb 1 | |
603 | \& HV* CvSTASH(CV* cv) | |
604 | .Ve | |
605 | .IP "get_cv" 8 | |
606 | .IX Xref "get_cv" | |
607 | .IX Item "get_cv" | |
608 | Returns the \s-1CV\s0 of the specified Perl subroutine. If \f(CW\*(C`create\*(C'\fR is set and | |
609 | the Perl subroutine does not exist then it will be declared (which has the | |
610 | same effect as saying \f(CW\*(C`sub name;\*(C'\fR). If \f(CW\*(C`create\*(C'\fR is not set and the | |
611 | subroutine does not exist then \s-1NULL\s0 is returned. | |
612 | .Sp | |
613 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
614 | .Sp | |
615 | .Vb 1 | |
616 | \& CV* get_cv(const char* name, I32 create) | |
617 | .Ve | |
618 | .SH "Embedding Functions" | |
619 | .IX Header "Embedding Functions" | |
620 | .IP "cv_undef" 8 | |
621 | .IX Xref "cv_undef" | |
622 | .IX Item "cv_undef" | |
623 | Clear out all the active components of a \s-1CV\s0. This can happen either | |
624 | by an explicit \f(CW\*(C`undef &foo\*(C'\fR, or by the reference count going to zero. | |
625 | In the former case, we keep the CvOUTSIDE pointer, so that any anonymous | |
626 | children can still follow the full lexical scope chain. | |
627 | .Sp | |
628 | .Vb 1 | |
629 | \& void cv_undef(CV* cv) | |
630 | .Ve | |
631 | .IP "load_module" 8 | |
632 | .IX Xref "load_module" | |
633 | .IX Item "load_module" | |
634 | Loads the module whose name is pointed to by the string part of name. | |
635 | Note that the actual module name, not its filename, should be given. | |
636 | Eg, \*(L"Foo::Bar\*(R" instead of \*(L"Foo/Bar.pm\*(R". flags can be any of | |
637 | \&\s-1PERL_LOADMOD_DENY\s0, \s-1PERL_LOADMOD_NOIMPORT\s0, or \s-1PERL_LOADMOD_IMPORT_OPS\s0 | |
638 | (or 0 for no flags). ver, if specified, provides version semantics | |
639 | similar to \f(CW\*(C`use Foo::Bar VERSION\*(C'\fR. The optional trailing SV* | |
640 | arguments can be used to specify arguments to the module's \fIimport()\fR | |
641 | method, similar to \f(CW\*(C`use Foo::Bar VERSION LIST\*(C'\fR. | |
642 | .Sp | |
643 | .Vb 1 | |
644 | \& void load_module(U32 flags, SV* name, SV* ver, ...) | |
645 | .Ve | |
646 | .IP "nothreadhook" 8 | |
647 | .IX Xref "nothreadhook" | |
648 | .IX Item "nothreadhook" | |
649 | Stub that provides thread hook for perl_destruct when there are | |
650 | no threads. | |
651 | .Sp | |
652 | .Vb 1 | |
653 | \& int nothreadhook() | |
654 | .Ve | |
655 | .IP "perl_alloc" 8 | |
656 | .IX Xref "perl_alloc" | |
657 | .IX Item "perl_alloc" | |
658 | Allocates a new Perl interpreter. See perlembed. | |
659 | .Sp | |
660 | .Vb 1 | |
661 | \& PerlInterpreter* perl_alloc() | |
662 | .Ve | |
663 | .IP "perl_construct" 8 | |
664 | .IX Xref "perl_construct" | |
665 | .IX Item "perl_construct" | |
666 | Initializes a new Perl interpreter. See perlembed. | |
667 | .Sp | |
668 | .Vb 1 | |
669 | \& void perl_construct(PerlInterpreter* interp) | |
670 | .Ve | |
671 | .IP "perl_destruct" 8 | |
672 | .IX Xref "perl_destruct" | |
673 | .IX Item "perl_destruct" | |
674 | Shuts down a Perl interpreter. See perlembed. | |
675 | .Sp | |
676 | .Vb 1 | |
677 | \& int perl_destruct(PerlInterpreter* interp) | |
678 | .Ve | |
679 | .IP "perl_free" 8 | |
680 | .IX Xref "perl_free" | |
681 | .IX Item "perl_free" | |
682 | Releases a Perl interpreter. See perlembed. | |
683 | .Sp | |
684 | .Vb 1 | |
685 | \& void perl_free(PerlInterpreter* interp) | |
686 | .Ve | |
687 | .IP "perl_parse" 8 | |
688 | .IX Xref "perl_parse" | |
689 | .IX Item "perl_parse" | |
690 | Tells a Perl interpreter to parse a Perl script. See perlembed. | |
691 | .Sp | |
692 | .Vb 1 | |
693 | \& int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env) | |
694 | .Ve | |
695 | .IP "perl_run" 8 | |
696 | .IX Xref "perl_run" | |
697 | .IX Item "perl_run" | |
698 | Tells a Perl interpreter to run. See perlembed. | |
699 | .Sp | |
700 | .Vb 1 | |
701 | \& int perl_run(PerlInterpreter* interp) | |
702 | .Ve | |
703 | .IP "require_pv" 8 | |
704 | .IX Xref "require_pv" | |
705 | .IX Item "require_pv" | |
706 | Tells Perl to \f(CW\*(C`require\*(C'\fR the file named by the string argument. It is | |
707 | analogous to the Perl code \f(CW\*(C`eval "require '$file'"\*(C'\fR. It's even | |
708 | implemented that way; consider using load_module instead. | |
709 | .Sp | |
710 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
711 | .Sp | |
712 | .Vb 1 | |
713 | \& void require_pv(const char* pv) | |
714 | .Ve | |
715 | .SH "Functions in file pp_pack.c" | |
716 | .IX Header "Functions in file pp_pack.c" | |
717 | .IP "packlist" 8 | |
718 | .IX Xref "packlist" | |
719 | .IX Item "packlist" | |
720 | The engine implementing \fIpack()\fR Perl function. | |
721 | .Sp | |
722 | .Vb 1 | |
723 | \& void packlist(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist) | |
724 | .Ve | |
725 | .IP "pack_cat" 8 | |
726 | .IX Xref "pack_cat" | |
727 | .IX Item "pack_cat" | |
728 | The engine implementing \fIpack()\fR Perl function. Note: parameters next_in_list and | |
729 | flags are not used. This call should not be used; use packlist instead. | |
730 | .Sp | |
731 | .Vb 1 | |
732 | \& void pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) | |
733 | .Ve | |
734 | .IP "unpackstring" 8 | |
735 | .IX Xref "unpackstring" | |
736 | .IX Item "unpackstring" | |
737 | The engine implementing \fIunpack()\fR Perl function. \f(CW\*(C`unpackstring\*(C'\fR puts the | |
738 | extracted list items on the stack and returns the number of elements. | |
739 | Issue \f(CW\*(C`PUTBACK\*(C'\fR before and \f(CW\*(C`SPAGAIN\*(C'\fR after the call to this function. | |
740 | .Sp | |
741 | .Vb 1 | |
742 | \& I32 unpackstring(char *pat, char *patend, char *s, char *strend, U32 flags) | |
743 | .Ve | |
744 | .IP "unpack_str" 8 | |
745 | .IX Xref "unpack_str" | |
746 | .IX Item "unpack_str" | |
747 | The engine implementing \fIunpack()\fR Perl function. Note: parameters strbeg, new_s | |
748 | and ocnt are not used. This call should not be used, use unpackstring instead. | |
749 | .Sp | |
750 | .Vb 1 | |
751 | \& I32 unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags) | |
752 | .Ve | |
753 | .SH "Global Variables" | |
754 | .IX Header "Global Variables" | |
755 | .IP "PL_modglobal" 8 | |
756 | .IX Xref "PL_modglobal" | |
757 | .IX Item "PL_modglobal" | |
758 | \&\f(CW\*(C`PL_modglobal\*(C'\fR is a general purpose, interpreter global \s-1HV\s0 for use by | |
759 | extensions that need to keep information on a per-interpreter basis. | |
760 | In a pinch, it can also be used as a symbol table for extensions | |
761 | to share data among each other. It is a good idea to use keys | |
762 | prefixed by the package name of the extension that owns the data. | |
763 | .Sp | |
764 | .Vb 1 | |
765 | \& HV* PL_modglobal | |
766 | .Ve | |
767 | .IP "PL_na" 8 | |
768 | .IX Xref "PL_na" | |
769 | .IX Item "PL_na" | |
770 | A convenience variable which is typically used with \f(CW\*(C`SvPV\*(C'\fR when one | |
771 | doesn't care about the length of the string. It is usually more efficient | |
772 | to either declare a local variable and use that instead or to use the | |
773 | \&\f(CW\*(C`SvPV_nolen\*(C'\fR macro. | |
774 | .Sp | |
775 | .Vb 1 | |
776 | \& STRLEN PL_na | |
777 | .Ve | |
778 | .IP "PL_sv_no" 8 | |
779 | .IX Xref "PL_sv_no" | |
780 | .IX Item "PL_sv_no" | |
781 | This is the \f(CW\*(C`false\*(C'\fR \s-1SV\s0. See \f(CW\*(C`PL_sv_yes\*(C'\fR. Always refer to this as | |
782 | \&\f(CW&PL_sv_no\fR. | |
783 | .Sp | |
784 | .Vb 1 | |
785 | \& SV PL_sv_no | |
786 | .Ve | |
787 | .IP "PL_sv_undef" 8 | |
788 | .IX Xref "PL_sv_undef" | |
789 | .IX Item "PL_sv_undef" | |
790 | This is the \f(CW\*(C`undef\*(C'\fR \s-1SV\s0. Always refer to this as \f(CW&PL_sv_undef\fR. | |
791 | .Sp | |
792 | .Vb 1 | |
793 | \& SV PL_sv_undef | |
794 | .Ve | |
795 | .IP "PL_sv_yes" 8 | |
796 | .IX Xref "PL_sv_yes" | |
797 | .IX Item "PL_sv_yes" | |
798 | This is the \f(CW\*(C`true\*(C'\fR \s-1SV\s0. See \f(CW\*(C`PL_sv_no\*(C'\fR. Always refer to this as | |
799 | \&\f(CW&PL_sv_yes\fR. | |
800 | .Sp | |
801 | .Vb 1 | |
802 | \& SV PL_sv_yes | |
803 | .Ve | |
804 | .SH "GV Functions" | |
805 | .IX Header "GV Functions" | |
806 | .IP "GvSV" 8 | |
807 | .IX Xref "GvSV" | |
808 | .IX Item "GvSV" | |
809 | Return the \s-1SV\s0 from the \s-1GV\s0. | |
810 | .Sp | |
811 | .Vb 1 | |
812 | \& SV* GvSV(GV* gv) | |
813 | .Ve | |
814 | .IP "gv_fetchmeth" 8 | |
815 | .IX Xref "gv_fetchmeth" | |
816 | .IX Item "gv_fetchmeth" | |
817 | Returns the glob with the given \f(CW\*(C`name\*(C'\fR and a defined subroutine or | |
818 | \&\f(CW\*(C`NULL\*(C'\fR. The glob lives in the given \f(CW\*(C`stash\*(C'\fR, or in the stashes | |
819 | accessible via \f(CW@ISA\fR and \s-1UNIVERSAL::\s0. | |
820 | .Sp | |
821 | The argument \f(CW\*(C`level\*(C'\fR should be either 0 or \-1. If \f(CW\*(C`level==0\*(C'\fR, as a | |
822 | side-effect creates a glob with the given \f(CW\*(C`name\*(C'\fR in the given \f(CW\*(C`stash\*(C'\fR | |
823 | which in the case of success contains an alias for the subroutine, and sets | |
824 | up caching info for this glob. Similarly for all the searched stashes. | |
825 | .Sp | |
826 | This function grants \f(CW"SUPER"\fR token as a postfix of the stash name. The | |
827 | \&\s-1GV\s0 returned from \f(CW\*(C`gv_fetchmeth\*(C'\fR may be a method cache entry, which is not | |
828 | visible to Perl code. So when calling \f(CW\*(C`call_sv\*(C'\fR, you should not use | |
829 | the \s-1GV\s0 directly; instead, you should use the method's \s-1CV\s0, which can be | |
830 | obtained from the \s-1GV\s0 with the \f(CW\*(C`GvCV\*(C'\fR macro. | |
831 | .Sp | |
832 | .Vb 1 | |
833 | \& GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level) | |
834 | .Ve | |
835 | .IP "gv_fetchmethod" 8 | |
836 | .IX Xref "gv_fetchmethod" | |
837 | .IX Item "gv_fetchmethod" | |
838 | See gv_fetchmethod_autoload. | |
839 | .Sp | |
840 | .Vb 1 | |
841 | \& GV* gv_fetchmethod(HV* stash, const char* name) | |
842 | .Ve | |
843 | .IP "gv_fetchmethod_autoload" 8 | |
844 | .IX Xref "gv_fetchmethod_autoload" | |
845 | .IX Item "gv_fetchmethod_autoload" | |
846 | Returns the glob which contains the subroutine to call to invoke the method | |
847 | on the \f(CW\*(C`stash\*(C'\fR. In fact in the presence of autoloading this may be the | |
848 | glob for \*(L"\s-1AUTOLOAD\s0\*(R". In this case the corresponding variable \f(CW$AUTOLOAD\fR is | |
849 | already setup. | |
850 | .Sp | |
851 | The third parameter of \f(CW\*(C`gv_fetchmethod_autoload\*(C'\fR determines whether | |
852 | \&\s-1AUTOLOAD\s0 lookup is performed if the given method is not present: non-zero | |
853 | means yes, look for \s-1AUTOLOAD\s0; zero means no, don't look for \s-1AUTOLOAD\s0. | |
854 | Calling \f(CW\*(C`gv_fetchmethod\*(C'\fR is equivalent to calling \f(CW\*(C`gv_fetchmethod_autoload\*(C'\fR | |
855 | with a non-zero \f(CW\*(C`autoload\*(C'\fR parameter. | |
856 | .Sp | |
857 | These functions grant \f(CW"SUPER"\fR token as a prefix of the method name. Note | |
858 | that if you want to keep the returned glob for a long time, you need to | |
859 | check for it being \*(L"\s-1AUTOLOAD\s0\*(R", since at the later time the call may load a | |
860 | different subroutine due to \f(CW$AUTOLOAD\fR changing its value. Use the glob | |
861 | created via a side effect to do this. | |
862 | .Sp | |
863 | These functions have the same side-effects and as \f(CW\*(C`gv_fetchmeth\*(C'\fR with | |
864 | \&\f(CW\*(C`level==0\*(C'\fR. \f(CW\*(C`name\*(C'\fR should be writable if contains \f(CW':'\fR or \f(CW\*(C`' | |
865 | \&''\*(C'\fR. The warning against passing the \s-1GV\s0 returned by \f(CW\*(C`gv_fetchmeth\*(C'\fR to | |
866 | \&\f(CW\*(C`call_sv\*(C'\fR apply equally to these functions. | |
867 | .Sp | |
868 | .Vb 1 | |
869 | \& GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload) | |
870 | .Ve | |
871 | .IP "gv_fetchmeth_autoload" 8 | |
872 | .IX Xref "gv_fetchmeth_autoload" | |
873 | .IX Item "gv_fetchmeth_autoload" | |
874 | Same as \fIgv_fetchmeth()\fR, but looks for autoloaded subroutines too. | |
875 | Returns a glob for the subroutine. | |
876 | .Sp | |
877 | For an autoloaded subroutine without a \s-1GV\s0, will create a \s-1GV\s0 even | |
878 | if \f(CW\*(C`level < 0\*(C'\fR. For an autoloaded subroutine without a stub, \fIGvCV()\fR | |
879 | of the result may be zero. | |
880 | .Sp | |
881 | .Vb 1 | |
882 | \& GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level) | |
883 | .Ve | |
884 | .IP "gv_stashpv" 8 | |
885 | .IX Xref "gv_stashpv" | |
886 | .IX Item "gv_stashpv" | |
887 | Returns a pointer to the stash for a specified package. \f(CW\*(C`name\*(C'\fR should | |
888 | be a valid \s-1UTF\-8\s0 string and must be null\-terminated. If \f(CW\*(C`create\*(C'\fR is set | |
889 | then the package will be created if it does not already exist. If \f(CW\*(C`create\*(C'\fR | |
890 | is not set and the package does not exist then \s-1NULL\s0 is returned. | |
891 | .Sp | |
892 | .Vb 1 | |
893 | \& HV* gv_stashpv(const char* name, I32 create) | |
894 | .Ve | |
895 | .IP "gv_stashpvn" 8 | |
896 | .IX Xref "gv_stashpvn" | |
897 | .IX Item "gv_stashpvn" | |
898 | Returns a pointer to the stash for a specified package. \f(CW\*(C`name\*(C'\fR should | |
899 | be a valid \s-1UTF\-8\s0 string. The \f(CW\*(C`namelen\*(C'\fR parameter indicates the length of | |
900 | the \f(CW\*(C`name\*(C'\fR, in bytes. If \f(CW\*(C`create\*(C'\fR is set then the package will be | |
901 | created if it does not already exist. If \f(CW\*(C`create\*(C'\fR is not set and the | |
902 | package does not exist then \s-1NULL\s0 is returned. | |
903 | .Sp | |
904 | .Vb 1 | |
905 | \& HV* gv_stashpvn(const char* name, U32 namelen, I32 create) | |
906 | .Ve | |
907 | .IP "gv_stashsv" 8 | |
908 | .IX Xref "gv_stashsv" | |
909 | .IX Item "gv_stashsv" | |
910 | Returns a pointer to the stash for a specified package, which must be a | |
911 | valid \s-1UTF\-8\s0 string. See \f(CW\*(C`gv_stashpv\*(C'\fR. | |
912 | .Sp | |
913 | .Vb 1 | |
914 | \& HV* gv_stashsv(SV* sv, I32 create) | |
915 | .Ve | |
916 | .SH "Handy Values" | |
917 | .IX Header "Handy Values" | |
918 | .IP "Nullav" 8 | |
919 | .IX Xref "Nullav" | |
920 | .IX Item "Nullav" | |
921 | Null \s-1AV\s0 pointer. | |
922 | .IP "Nullch" 8 | |
923 | .IX Xref "Nullch" | |
924 | .IX Item "Nullch" | |
925 | Null character pointer. | |
926 | .IP "Nullcv" 8 | |
927 | .IX Xref "Nullcv" | |
928 | .IX Item "Nullcv" | |
929 | Null \s-1CV\s0 pointer. | |
930 | .IP "Nullhv" 8 | |
931 | .IX Xref "Nullhv" | |
932 | .IX Item "Nullhv" | |
933 | Null \s-1HV\s0 pointer. | |
934 | .IP "Nullsv" 8 | |
935 | .IX Xref "Nullsv" | |
936 | .IX Item "Nullsv" | |
937 | Null \s-1SV\s0 pointer. | |
938 | .SH "Hash Manipulation Functions" | |
939 | .IX Header "Hash Manipulation Functions" | |
940 | .IP "get_hv" 8 | |
941 | .IX Xref "get_hv" | |
942 | .IX Item "get_hv" | |
943 | Returns the \s-1HV\s0 of the specified Perl hash. If \f(CW\*(C`create\*(C'\fR is set and the | |
944 | Perl variable does not exist then it will be created. If \f(CW\*(C`create\*(C'\fR is not | |
945 | set and the variable does not exist then \s-1NULL\s0 is returned. | |
946 | .Sp | |
947 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
948 | .Sp | |
949 | .Vb 1 | |
950 | \& HV* get_hv(const char* name, I32 create) | |
951 | .Ve | |
952 | .IP "HEf_SVKEY" 8 | |
953 | .IX Xref "HEf_SVKEY" | |
954 | .IX Item "HEf_SVKEY" | |
955 | This flag, used in the length slot of hash entries and magic structures, | |
956 | specifies the structure contains an \f(CW\*(C`SV*\*(C'\fR pointer where a \f(CW\*(C`char*\*(C'\fR pointer | |
957 | is to be expected. (For information only\*(--not to be used). | |
958 | .IP "HeHASH" 8 | |
959 | .IX Xref "HeHASH" | |
960 | .IX Item "HeHASH" | |
961 | Returns the computed hash stored in the hash entry. | |
962 | .Sp | |
963 | .Vb 1 | |
964 | \& U32 HeHASH(HE* he) | |
965 | .Ve | |
966 | .IP "HeKEY" 8 | |
967 | .IX Xref "HeKEY" | |
968 | .IX Item "HeKEY" | |
969 | Returns the actual pointer stored in the key slot of the hash entry. The | |
970 | pointer may be either \f(CW\*(C`char*\*(C'\fR or \f(CW\*(C`SV*\*(C'\fR, depending on the value of | |
971 | \&\f(CW\*(C`HeKLEN()\*(C'\fR. Can be assigned to. The \f(CW\*(C`HePV()\*(C'\fR or \f(CW\*(C`HeSVKEY()\*(C'\fR macros are | |
972 | usually preferable for finding the value of a key. | |
973 | .Sp | |
974 | .Vb 1 | |
975 | \& void* HeKEY(HE* he) | |
976 | .Ve | |
977 | .IP "HeKLEN" 8 | |
978 | .IX Xref "HeKLEN" | |
979 | .IX Item "HeKLEN" | |
980 | If this is negative, and amounts to \f(CW\*(C`HEf_SVKEY\*(C'\fR, it indicates the entry | |
981 | holds an \f(CW\*(C`SV*\*(C'\fR key. Otherwise, holds the actual length of the key. Can | |
982 | be assigned to. The \f(CW\*(C`HePV()\*(C'\fR macro is usually preferable for finding key | |
983 | lengths. | |
984 | .Sp | |
985 | .Vb 1 | |
986 | \& STRLEN HeKLEN(HE* he) | |
987 | .Ve | |
988 | .IP "HePV" 8 | |
989 | .IX Xref "HePV" | |
990 | .IX Item "HePV" | |
991 | Returns the key slot of the hash entry as a \f(CW\*(C`char*\*(C'\fR value, doing any | |
992 | necessary dereferencing of possibly \f(CW\*(C`SV*\*(C'\fR keys. The length of the string | |
993 | is placed in \f(CW\*(C`len\*(C'\fR (this is a macro, so do \fInot\fR use \f(CW&len\fR). If you do | |
994 | not care about what the length of the key is, you may use the global | |
995 | variable \f(CW\*(C`PL_na\*(C'\fR, though this is rather less efficient than using a local | |
996 | variable. Remember though, that hash keys in perl are free to contain | |
997 | embedded nulls, so using \f(CW\*(C`strlen()\*(C'\fR or similar is not a good way to find | |
998 | the length of hash keys. This is very similar to the \f(CW\*(C`SvPV()\*(C'\fR macro | |
999 | described elsewhere in this document. | |
1000 | .Sp | |
1001 | .Vb 1 | |
1002 | \& char* HePV(HE* he, STRLEN len) | |
1003 | .Ve | |
1004 | .IP "HeSVKEY" 8 | |
1005 | .IX Xref "HeSVKEY" | |
1006 | .IX Item "HeSVKEY" | |
1007 | Returns the key as an \f(CW\*(C`SV*\*(C'\fR, or \f(CW\*(C`Nullsv\*(C'\fR if the hash entry does not | |
1008 | contain an \f(CW\*(C`SV*\*(C'\fR key. | |
1009 | .Sp | |
1010 | .Vb 1 | |
1011 | \& SV* HeSVKEY(HE* he) | |
1012 | .Ve | |
1013 | .IP "HeSVKEY_force" 8 | |
1014 | .IX Xref "HeSVKEY_force" | |
1015 | .IX Item "HeSVKEY_force" | |
1016 | Returns the key as an \f(CW\*(C`SV*\*(C'\fR. Will create and return a temporary mortal | |
1017 | \&\f(CW\*(C`SV*\*(C'\fR if the hash entry contains only a \f(CW\*(C`char*\*(C'\fR key. | |
1018 | .Sp | |
1019 | .Vb 1 | |
1020 | \& SV* HeSVKEY_force(HE* he) | |
1021 | .Ve | |
1022 | .IP "HeSVKEY_set" 8 | |
1023 | .IX Xref "HeSVKEY_set" | |
1024 | .IX Item "HeSVKEY_set" | |
1025 | Sets the key to a given \f(CW\*(C`SV*\*(C'\fR, taking care to set the appropriate flags to | |
1026 | indicate the presence of an \f(CW\*(C`SV*\*(C'\fR key, and returns the same | |
1027 | \&\f(CW\*(C`SV*\*(C'\fR. | |
1028 | .Sp | |
1029 | .Vb 1 | |
1030 | \& SV* HeSVKEY_set(HE* he, SV* sv) | |
1031 | .Ve | |
1032 | .IP "HeVAL" 8 | |
1033 | .IX Xref "HeVAL" | |
1034 | .IX Item "HeVAL" | |
1035 | Returns the value slot (type \f(CW\*(C`SV*\*(C'\fR) stored in the hash entry. | |
1036 | .Sp | |
1037 | .Vb 1 | |
1038 | \& SV* HeVAL(HE* he) | |
1039 | .Ve | |
1040 | .IP "HvNAME" 8 | |
1041 | .IX Xref "HvNAME" | |
1042 | .IX Item "HvNAME" | |
1043 | Returns the package name of a stash. See \f(CW\*(C`SvSTASH\*(C'\fR, \f(CW\*(C`CvSTASH\*(C'\fR. | |
1044 | .Sp | |
1045 | .Vb 1 | |
1046 | \& char* HvNAME(HV* stash) | |
1047 | .Ve | |
1048 | .IP "hv_clear" 8 | |
1049 | .IX Xref "hv_clear" | |
1050 | .IX Item "hv_clear" | |
1051 | Clears a hash, making it empty. | |
1052 | .Sp | |
1053 | .Vb 1 | |
1054 | \& void hv_clear(HV* tb) | |
1055 | .Ve | |
1056 | .IP "hv_clear_placeholders" 8 | |
1057 | .IX Xref "hv_clear_placeholders" | |
1058 | .IX Item "hv_clear_placeholders" | |
1059 | Clears any placeholders from a hash. If a restricted hash has any of its keys | |
1060 | marked as readonly and the key is subsequently deleted, the key is not actually | |
1061 | deleted but is marked by assigning it a value of &PL_sv_placeholder. This tags | |
1062 | it so it will be ignored by future operations such as iterating over the hash, | |
1063 | but will still allow the hash to have a value reassigned to the key at some | |
1064 | future point. This function clears any such placeholder keys from the hash. | |
1065 | See \fIHash::Util::lock_keys()\fR for an example of its use. | |
1066 | .Sp | |
1067 | .Vb 1 | |
1068 | \& void hv_clear_placeholders(HV* hb) | |
1069 | .Ve | |
1070 | .IP "hv_delete" 8 | |
1071 | .IX Xref "hv_delete" | |
1072 | .IX Item "hv_delete" | |
1073 | Deletes a key/value pair in the hash. The value \s-1SV\s0 is removed from the | |
1074 | hash and returned to the caller. The \f(CW\*(C`klen\*(C'\fR is the length of the key. | |
1075 | The \f(CW\*(C`flags\*(C'\fR value will normally be zero; if set to G_DISCARD then \s-1NULL\s0 | |
1076 | will be returned. | |
1077 | .Sp | |
1078 | .Vb 1 | |
1079 | \& SV* hv_delete(HV* tb, const char* key, I32 klen, I32 flags) | |
1080 | .Ve | |
1081 | .IP "hv_delete_ent" 8 | |
1082 | .IX Xref "hv_delete_ent" | |
1083 | .IX Item "hv_delete_ent" | |
1084 | Deletes a key/value pair in the hash. The value \s-1SV\s0 is removed from the | |
1085 | hash and returned to the caller. The \f(CW\*(C`flags\*(C'\fR value will normally be zero; | |
1086 | if set to G_DISCARD then \s-1NULL\s0 will be returned. \f(CW\*(C`hash\*(C'\fR can be a valid | |
1087 | precomputed hash value, or 0 to ask for it to be computed. | |
1088 | .Sp | |
1089 | .Vb 1 | |
1090 | \& SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash) | |
1091 | .Ve | |
1092 | .IP "hv_exists" 8 | |
1093 | .IX Xref "hv_exists" | |
1094 | .IX Item "hv_exists" | |
1095 | Returns a boolean indicating whether the specified hash key exists. The | |
1096 | \&\f(CW\*(C`klen\*(C'\fR is the length of the key. | |
1097 | .Sp | |
1098 | .Vb 1 | |
1099 | \& bool hv_exists(HV* tb, const char* key, I32 klen) | |
1100 | .Ve | |
1101 | .IP "hv_exists_ent" 8 | |
1102 | .IX Xref "hv_exists_ent" | |
1103 | .IX Item "hv_exists_ent" | |
1104 | Returns a boolean indicating whether the specified hash key exists. \f(CW\*(C`hash\*(C'\fR | |
1105 | can be a valid precomputed hash value, or 0 to ask for it to be | |
1106 | computed. | |
1107 | .Sp | |
1108 | .Vb 1 | |
1109 | \& bool hv_exists_ent(HV* tb, SV* key, U32 hash) | |
1110 | .Ve | |
1111 | .IP "hv_fetch" 8 | |
1112 | .IX Xref "hv_fetch" | |
1113 | .IX Item "hv_fetch" | |
1114 | Returns the \s-1SV\s0 which corresponds to the specified key in the hash. The | |
1115 | \&\f(CW\*(C`klen\*(C'\fR is the length of the key. If \f(CW\*(C`lval\*(C'\fR is set then the fetch will be | |
1116 | part of a store. Check that the return value is non-null before | |
1117 | dereferencing it to an \f(CW\*(C`SV*\*(C'\fR. | |
1118 | .Sp | |
1119 | See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" in perlguts for more | |
1120 | information on how to use this function on tied hashes. | |
1121 | .Sp | |
1122 | .Vb 1 | |
1123 | \& SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval) | |
1124 | .Ve | |
1125 | .IP "hv_fetch_ent" 8 | |
1126 | .IX Xref "hv_fetch_ent" | |
1127 | .IX Item "hv_fetch_ent" | |
1128 | Returns the hash entry which corresponds to the specified key in the hash. | |
1129 | \&\f(CW\*(C`hash\*(C'\fR must be a valid precomputed hash number for the given \f(CW\*(C`key\*(C'\fR, or 0 | |
1130 | if you want the function to compute it. \s-1IF\s0 \f(CW\*(C`lval\*(C'\fR is set then the fetch | |
1131 | will be part of a store. Make sure the return value is non-null before | |
1132 | accessing it. The return value when \f(CW\*(C`tb\*(C'\fR is a tied hash is a pointer to a | |
1133 | static location, so be sure to make a copy of the structure if you need to | |
1134 | store it somewhere. | |
1135 | .Sp | |
1136 | See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" in perlguts for more | |
1137 | information on how to use this function on tied hashes. | |
1138 | .Sp | |
1139 | .Vb 1 | |
1140 | \& HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash) | |
1141 | .Ve | |
1142 | .IP "hv_iterinit" 8 | |
1143 | .IX Xref "hv_iterinit" | |
1144 | .IX Item "hv_iterinit" | |
1145 | Prepares a starting point to traverse a hash table. Returns the number of | |
1146 | keys in the hash (i.e. the same as \f(CW\*(C`HvKEYS(tb)\*(C'\fR). The return value is | |
1147 | currently only meaningful for hashes without tie magic. | |
1148 | .Sp | |
1149 | \&\s-1NOTE:\s0 Before version 5.004_65, \f(CW\*(C`hv_iterinit\*(C'\fR used to return the number of | |
1150 | hash buckets that happen to be in use. If you still need that esoteric | |
1151 | value, you can get it through the macro \f(CW\*(C`HvFILL(tb)\*(C'\fR. | |
1152 | .Sp | |
1153 | .Vb 1 | |
1154 | \& I32 hv_iterinit(HV* tb) | |
1155 | .Ve | |
1156 | .IP "hv_iterkey" 8 | |
1157 | .IX Xref "hv_iterkey" | |
1158 | .IX Item "hv_iterkey" | |
1159 | Returns the key from the current position of the hash iterator. See | |
1160 | \&\f(CW\*(C`hv_iterinit\*(C'\fR. | |
1161 | .Sp | |
1162 | .Vb 1 | |
1163 | \& char* hv_iterkey(HE* entry, I32* retlen) | |
1164 | .Ve | |
1165 | .IP "hv_iterkeysv" 8 | |
1166 | .IX Xref "hv_iterkeysv" | |
1167 | .IX Item "hv_iterkeysv" | |
1168 | Returns the key as an \f(CW\*(C`SV*\*(C'\fR from the current position of the hash | |
1169 | iterator. The return value will always be a mortal copy of the key. Also | |
1170 | see \f(CW\*(C`hv_iterinit\*(C'\fR. | |
1171 | .Sp | |
1172 | .Vb 1 | |
1173 | \& SV* hv_iterkeysv(HE* entry) | |
1174 | .Ve | |
1175 | .IP "hv_iternext" 8 | |
1176 | .IX Xref "hv_iternext" | |
1177 | .IX Item "hv_iternext" | |
1178 | Returns entries from a hash iterator. See \f(CW\*(C`hv_iterinit\*(C'\fR. | |
1179 | .Sp | |
1180 | You may call \f(CW\*(C`hv_delete\*(C'\fR or \f(CW\*(C`hv_delete_ent\*(C'\fR on the hash entry that the | |
1181 | iterator currently points to, without losing your place or invalidating your | |
1182 | iterator. Note that in this case the current entry is deleted from the hash | |
1183 | with your iterator holding the last reference to it. Your iterator is flagged | |
1184 | to free the entry on the next call to \f(CW\*(C`hv_iternext\*(C'\fR, so you must not discard | |
1185 | your iterator immediately else the entry will leak \- call \f(CW\*(C`hv_iternext\*(C'\fR to | |
1186 | trigger the resource deallocation. | |
1187 | .Sp | |
1188 | .Vb 1 | |
1189 | \& HE* hv_iternext(HV* tb) | |
1190 | .Ve | |
1191 | .IP "hv_iternextsv" 8 | |
1192 | .IX Xref "hv_iternextsv" | |
1193 | .IX Item "hv_iternextsv" | |
1194 | Performs an \f(CW\*(C`hv_iternext\*(C'\fR, \f(CW\*(C`hv_iterkey\*(C'\fR, and \f(CW\*(C`hv_iterval\*(C'\fR in one | |
1195 | operation. | |
1196 | .Sp | |
1197 | .Vb 1 | |
1198 | \& SV* hv_iternextsv(HV* hv, char** key, I32* retlen) | |
1199 | .Ve | |
1200 | .IP "hv_iternext_flags" 8 | |
1201 | .IX Xref "hv_iternext_flags" | |
1202 | .IX Item "hv_iternext_flags" | |
1203 | Returns entries from a hash iterator. See \f(CW\*(C`hv_iterinit\*(C'\fR and \f(CW\*(C`hv_iternext\*(C'\fR. | |
1204 | The \f(CW\*(C`flags\*(C'\fR value will normally be zero; if \s-1HV_ITERNEXT_WANTPLACEHOLDERS\s0 is | |
1205 | set the placeholders keys (for restricted hashes) will be returned in addition | |
1206 | to normal keys. By default placeholders are automatically skipped over. | |
1207 | Currently a placeholder is implemented with a value that is | |
1208 | \&\f(CW&Perl_sv_placeholder\fR. Note that the implementation of placeholders and | |
1209 | restricted hashes may change, and the implementation currently is | |
1210 | insufficiently abstracted for any change to be tidy. | |
1211 | .Sp | |
1212 | \&\s-1NOTE:\s0 this function is experimental and may change or be | |
1213 | removed without notice. | |
1214 | .Sp | |
1215 | .Vb 1 | |
1216 | \& HE* hv_iternext_flags(HV* tb, I32 flags) | |
1217 | .Ve | |
1218 | .IP "hv_iterval" 8 | |
1219 | .IX Xref "hv_iterval" | |
1220 | .IX Item "hv_iterval" | |
1221 | Returns the value from the current position of the hash iterator. See | |
1222 | \&\f(CW\*(C`hv_iterkey\*(C'\fR. | |
1223 | .Sp | |
1224 | .Vb 1 | |
1225 | \& SV* hv_iterval(HV* tb, HE* entry) | |
1226 | .Ve | |
1227 | .IP "hv_magic" 8 | |
1228 | .IX Xref "hv_magic" | |
1229 | .IX Item "hv_magic" | |
1230 | Adds magic to a hash. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1231 | .Sp | |
1232 | .Vb 1 | |
1233 | \& void hv_magic(HV* hv, GV* gv, int how) | |
1234 | .Ve | |
1235 | .IP "hv_scalar" 8 | |
1236 | .IX Xref "hv_scalar" | |
1237 | .IX Item "hv_scalar" | |
1238 | Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied. | |
1239 | .Sp | |
1240 | .Vb 1 | |
1241 | \& SV* hv_scalar(HV* hv) | |
1242 | .Ve | |
1243 | .IP "hv_store" 8 | |
1244 | .IX Xref "hv_store" | |
1245 | .IX Item "hv_store" | |
1246 | Stores an \s-1SV\s0 in a hash. The hash key is specified as \f(CW\*(C`key\*(C'\fR and \f(CW\*(C`klen\*(C'\fR is | |
1247 | the length of the key. The \f(CW\*(C`hash\*(C'\fR parameter is the precomputed hash | |
1248 | value; if it is zero then Perl will compute it. The return value will be | |
1249 | \&\s-1NULL\s0 if the operation failed or if the value did not need to be actually | |
1250 | stored within the hash (as in the case of tied hashes). Otherwise it can | |
1251 | be dereferenced to get the original \f(CW\*(C`SV*\*(C'\fR. Note that the caller is | |
1252 | responsible for suitably incrementing the reference count of \f(CW\*(C`val\*(C'\fR before | |
1253 | the call, and decrementing it if the function returned \s-1NULL\s0. Effectively | |
1254 | a successful hv_store takes ownership of one reference to \f(CW\*(C`val\*(C'\fR. This is | |
1255 | usually what you want; a newly created \s-1SV\s0 has a reference count of one, so | |
1256 | if all your code does is create SVs then store them in a hash, hv_store | |
1257 | will own the only reference to the new \s-1SV\s0, and your code doesn't need to do | |
1258 | anything further to tidy up. hv_store is not implemented as a call to | |
1259 | hv_store_ent, and does not create a temporary \s-1SV\s0 for the key, so if your | |
1260 | key data is not already in \s-1SV\s0 form then use hv_store in preference to | |
1261 | hv_store_ent. | |
1262 | .Sp | |
1263 | See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" in perlguts for more | |
1264 | information on how to use this function on tied hashes. | |
1265 | .Sp | |
1266 | .Vb 1 | |
1267 | \& SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash) | |
1268 | .Ve | |
1269 | .IP "hv_store_ent" 8 | |
1270 | .IX Xref "hv_store_ent" | |
1271 | .IX Item "hv_store_ent" | |
1272 | Stores \f(CW\*(C`val\*(C'\fR in a hash. The hash key is specified as \f(CW\*(C`key\*(C'\fR. The \f(CW\*(C`hash\*(C'\fR | |
1273 | parameter is the precomputed hash value; if it is zero then Perl will | |
1274 | compute it. The return value is the new hash entry so created. It will be | |
1275 | \&\s-1NULL\s0 if the operation failed or if the value did not need to be actually | |
1276 | stored within the hash (as in the case of tied hashes). Otherwise the | |
1277 | contents of the return value can be accessed using the \f(CW\*(C`He?\*(C'\fR macros | |
1278 | described here. Note that the caller is responsible for suitably | |
1279 | incrementing the reference count of \f(CW\*(C`val\*(C'\fR before the call, and | |
1280 | decrementing it if the function returned \s-1NULL\s0. Effectively a successful | |
1281 | hv_store_ent takes ownership of one reference to \f(CW\*(C`val\*(C'\fR. This is | |
1282 | usually what you want; a newly created \s-1SV\s0 has a reference count of one, so | |
1283 | if all your code does is create SVs then store them in a hash, hv_store | |
1284 | will own the only reference to the new \s-1SV\s0, and your code doesn't need to do | |
1285 | anything further to tidy up. Note that hv_store_ent only reads the \f(CW\*(C`key\*(C'\fR; | |
1286 | unlike \f(CW\*(C`val\*(C'\fR it does not take ownership of it, so maintaining the correct | |
1287 | reference count on \f(CW\*(C`key\*(C'\fR is entirely the caller's responsibility. hv_store | |
1288 | is not implemented as a call to hv_store_ent, and does not create a temporary | |
1289 | \&\s-1SV\s0 for the key, so if your key data is not already in \s-1SV\s0 form then use | |
1290 | hv_store in preference to hv_store_ent. | |
1291 | .Sp | |
1292 | See \*(L"Understanding the Magic of Tied Hashes and Arrays\*(R" in perlguts for more | |
1293 | information on how to use this function on tied hashes. | |
1294 | .Sp | |
1295 | .Vb 1 | |
1296 | \& HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash) | |
1297 | .Ve | |
1298 | .IP "hv_undef" 8 | |
1299 | .IX Xref "hv_undef" | |
1300 | .IX Item "hv_undef" | |
1301 | Undefines the hash. | |
1302 | .Sp | |
1303 | .Vb 1 | |
1304 | \& void hv_undef(HV* tb) | |
1305 | .Ve | |
1306 | .IP "newHV" 8 | |
1307 | .IX Xref "newHV" | |
1308 | .IX Item "newHV" | |
1309 | Creates a new \s-1HV\s0. The reference count is set to 1. | |
1310 | .Sp | |
1311 | .Vb 1 | |
1312 | \& HV* newHV() | |
1313 | .Ve | |
1314 | .SH "Magical Functions" | |
1315 | .IX Header "Magical Functions" | |
1316 | .IP "mg_clear" 8 | |
1317 | .IX Xref "mg_clear" | |
1318 | .IX Item "mg_clear" | |
1319 | Clear something magical that the \s-1SV\s0 represents. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1320 | .Sp | |
1321 | .Vb 1 | |
1322 | \& int mg_clear(SV* sv) | |
1323 | .Ve | |
1324 | .IP "mg_copy" 8 | |
1325 | .IX Xref "mg_copy" | |
1326 | .IX Item "mg_copy" | |
1327 | Copies the magic from one \s-1SV\s0 to another. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1328 | .Sp | |
1329 | .Vb 1 | |
1330 | \& int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen) | |
1331 | .Ve | |
1332 | .IP "mg_find" 8 | |
1333 | .IX Xref "mg_find" | |
1334 | .IX Item "mg_find" | |
1335 | Finds the magic pointer for type matching the \s-1SV\s0. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1336 | .Sp | |
1337 | .Vb 1 | |
1338 | \& MAGIC* mg_find(SV* sv, int type) | |
1339 | .Ve | |
1340 | .IP "mg_free" 8 | |
1341 | .IX Xref "mg_free" | |
1342 | .IX Item "mg_free" | |
1343 | Free any magic storage used by the \s-1SV\s0. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1344 | .Sp | |
1345 | .Vb 1 | |
1346 | \& int mg_free(SV* sv) | |
1347 | .Ve | |
1348 | .IP "mg_get" 8 | |
1349 | .IX Xref "mg_get" | |
1350 | .IX Item "mg_get" | |
1351 | Do magic after a value is retrieved from the \s-1SV\s0. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1352 | .Sp | |
1353 | .Vb 1 | |
1354 | \& int mg_get(SV* sv) | |
1355 | .Ve | |
1356 | .IP "mg_length" 8 | |
1357 | .IX Xref "mg_length" | |
1358 | .IX Item "mg_length" | |
1359 | Report on the \s-1SV\s0's length. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1360 | .Sp | |
1361 | .Vb 1 | |
1362 | \& U32 mg_length(SV* sv) | |
1363 | .Ve | |
1364 | .IP "mg_magical" 8 | |
1365 | .IX Xref "mg_magical" | |
1366 | .IX Item "mg_magical" | |
1367 | Turns on the magical status of an \s-1SV\s0. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1368 | .Sp | |
1369 | .Vb 1 | |
1370 | \& void mg_magical(SV* sv) | |
1371 | .Ve | |
1372 | .IP "mg_set" 8 | |
1373 | .IX Xref "mg_set" | |
1374 | .IX Item "mg_set" | |
1375 | Do magic after a value is assigned to the \s-1SV\s0. See \f(CW\*(C`sv_magic\*(C'\fR. | |
1376 | .Sp | |
1377 | .Vb 1 | |
1378 | \& int mg_set(SV* sv) | |
1379 | .Ve | |
1380 | .IP "SvGETMAGIC" 8 | |
1381 | .IX Xref "SvGETMAGIC" | |
1382 | .IX Item "SvGETMAGIC" | |
1383 | Invokes \f(CW\*(C`mg_get\*(C'\fR on an \s-1SV\s0 if it has 'get' magic. This macro evaluates its | |
1384 | argument more than once. | |
1385 | .Sp | |
1386 | .Vb 1 | |
1387 | \& void SvGETMAGIC(SV* sv) | |
1388 | .Ve | |
1389 | .IP "SvLOCK" 8 | |
1390 | .IX Xref "SvLOCK" | |
1391 | .IX Item "SvLOCK" | |
1392 | Arranges for a mutual exclusion lock to be obtained on sv if a suitable module | |
1393 | has been loaded. | |
1394 | .Sp | |
1395 | .Vb 1 | |
1396 | \& void SvLOCK(SV* sv) | |
1397 | .Ve | |
1398 | .IP "SvSETMAGIC" 8 | |
1399 | .IX Xref "SvSETMAGIC" | |
1400 | .IX Item "SvSETMAGIC" | |
1401 | Invokes \f(CW\*(C`mg_set\*(C'\fR on an \s-1SV\s0 if it has 'set' magic. This macro evaluates its | |
1402 | argument more than once. | |
1403 | .Sp | |
1404 | .Vb 1 | |
1405 | \& void SvSETMAGIC(SV* sv) | |
1406 | .Ve | |
1407 | .IP "SvSetMagicSV" 8 | |
1408 | .IX Xref "SvSetMagicSV" | |
1409 | .IX Item "SvSetMagicSV" | |
1410 | Like \f(CW\*(C`SvSetSV\*(C'\fR, but does any set magic required afterwards. | |
1411 | .Sp | |
1412 | .Vb 1 | |
1413 | \& void SvSetMagicSV(SV* dsb, SV* ssv) | |
1414 | .Ve | |
1415 | .IP "SvSetMagicSV_nosteal" 8 | |
1416 | .IX Xref "SvSetMagicSV_nosteal" | |
1417 | .IX Item "SvSetMagicSV_nosteal" | |
1418 | Like \f(CW\*(C`SvSetSV_nosteal\*(C'\fR, but does any set magic required afterwards. | |
1419 | .Sp | |
1420 | .Vb 1 | |
1421 | \& void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) | |
1422 | .Ve | |
1423 | .IP "SvSetSV" 8 | |
1424 | .IX Xref "SvSetSV" | |
1425 | .IX Item "SvSetSV" | |
1426 | Calls \f(CW\*(C`sv_setsv\*(C'\fR if dsv is not the same as ssv. May evaluate arguments | |
1427 | more than once. | |
1428 | .Sp | |
1429 | .Vb 1 | |
1430 | \& void SvSetSV(SV* dsb, SV* ssv) | |
1431 | .Ve | |
1432 | .IP "SvSetSV_nosteal" 8 | |
1433 | .IX Xref "SvSetSV_nosteal" | |
1434 | .IX Item "SvSetSV_nosteal" | |
1435 | Calls a non-destructive version of \f(CW\*(C`sv_setsv\*(C'\fR if dsv is not the same as | |
1436 | ssv. May evaluate arguments more than once. | |
1437 | .Sp | |
1438 | .Vb 1 | |
1439 | \& void SvSetSV_nosteal(SV* dsv, SV* ssv) | |
1440 | .Ve | |
1441 | .IP "SvSHARE" 8 | |
1442 | .IX Xref "SvSHARE" | |
1443 | .IX Item "SvSHARE" | |
1444 | Arranges for sv to be shared between threads if a suitable module | |
1445 | has been loaded. | |
1446 | .Sp | |
1447 | .Vb 1 | |
1448 | \& void SvSHARE(SV* sv) | |
1449 | .Ve | |
1450 | .IP "SvUNLOCK" 8 | |
1451 | .IX Xref "SvUNLOCK" | |
1452 | .IX Item "SvUNLOCK" | |
1453 | Releases a mutual exclusion lock on sv if a suitable module | |
1454 | has been loaded. | |
1455 | .Sp | |
1456 | .Vb 1 | |
1457 | \& void SvUNLOCK(SV* sv) | |
1458 | .Ve | |
1459 | .SH "Memory Management" | |
1460 | .IX Header "Memory Management" | |
1461 | .IP "Copy" 8 | |
1462 | .IX Xref "Copy" | |
1463 | .IX Item "Copy" | |
1464 | The XSUB\-writer's interface to the C \f(CW\*(C`memcpy\*(C'\fR function. The \f(CW\*(C`src\*(C'\fR is the | |
1465 | source, \f(CW\*(C`dest\*(C'\fR is the destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and \f(CW\*(C`type\*(C'\fR is | |
1466 | the type. May fail on overlapping copies. See also \f(CW\*(C`Move\*(C'\fR. | |
1467 | .Sp | |
1468 | .Vb 1 | |
1469 | \& void Copy(void* src, void* dest, int nitems, type) | |
1470 | .Ve | |
1471 | .IP "CopyD" 8 | |
1472 | .IX Xref "CopyD" | |
1473 | .IX Item "CopyD" | |
1474 | Like \f(CW\*(C`Copy\*(C'\fR but returns dest. Useful for encouraging compilers to tail-call | |
1475 | optimise. | |
1476 | .Sp | |
1477 | .Vb 1 | |
1478 | \& void * CopyD(void* src, void* dest, int nitems, type) | |
1479 | .Ve | |
1480 | .IP "Move" 8 | |
1481 | .IX Xref "Move" | |
1482 | .IX Item "Move" | |
1483 | The XSUB\-writer's interface to the C \f(CW\*(C`memmove\*(C'\fR function. The \f(CW\*(C`src\*(C'\fR is the | |
1484 | source, \f(CW\*(C`dest\*(C'\fR is the destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and \f(CW\*(C`type\*(C'\fR is | |
1485 | the type. Can do overlapping moves. See also \f(CW\*(C`Copy\*(C'\fR. | |
1486 | .Sp | |
1487 | .Vb 1 | |
1488 | \& void Move(void* src, void* dest, int nitems, type) | |
1489 | .Ve | |
1490 | .IP "MoveD" 8 | |
1491 | .IX Xref "MoveD" | |
1492 | .IX Item "MoveD" | |
1493 | Like \f(CW\*(C`Move\*(C'\fR but returns dest. Useful for encouraging compilers to tail-call | |
1494 | optimise. | |
1495 | .Sp | |
1496 | .Vb 1 | |
1497 | \& void * MoveD(void* src, void* dest, int nitems, type) | |
1498 | .Ve | |
1499 | .IP "Newx" 8 | |
1500 | .IX Xref "Newx" | |
1501 | .IX Item "Newx" | |
1502 | The XSUB\-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function. | |
1503 | .Sp | |
1504 | .Vb 1 | |
1505 | \& void Newx(void* ptr, int nitems, type) | |
1506 | .Ve | |
1507 | .IP "Newxc" 8 | |
1508 | .IX Xref "Newxc" | |
1509 | .IX Item "Newxc" | |
1510 | The XSUB\-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function, with | |
1511 | cast. | |
1512 | .Sp | |
1513 | .Vb 1 | |
1514 | \& void Newxc(void* ptr, int nitems, type, cast) | |
1515 | .Ve | |
1516 | .IP "Newxz" 8 | |
1517 | .IX Xref "Newxz" | |
1518 | .IX Item "Newxz" | |
1519 | The XSUB\-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function. The allocated | |
1520 | memory is zeroed with \f(CW\*(C`memzero\*(C'\fR. | |
1521 | .Sp | |
1522 | In 5.9.3, we removed the 1st parameter, a debug aid, from the api. It | |
1523 | was used to uniquely identify each usage of these allocation | |
1524 | functions, but was deemed unnecessary with the availability of better | |
1525 | memory tracking tools, valgrind for example. | |
1526 | .Sp | |
1527 | .Vb 1 | |
1528 | \& void Newxz(void* ptr, int nitems, type) | |
1529 | .Ve | |
1530 | .IP "Poison" 8 | |
1531 | .IX Xref "Poison" | |
1532 | .IX Item "Poison" | |
1533 | Fill up memory with a pattern (byte 0xAB over and over again) that | |
1534 | hopefully catches attempts to access uninitialized memory. | |
1535 | .Sp | |
1536 | .Vb 1 | |
1537 | \& void Poison(void* dest, int nitems, type) | |
1538 | .Ve | |
1539 | .IP "Renew" 8 | |
1540 | .IX Xref "Renew" | |
1541 | .IX Item "Renew" | |
1542 | The XSUB\-writer's interface to the C \f(CW\*(C`realloc\*(C'\fR function. | |
1543 | .Sp | |
1544 | .Vb 1 | |
1545 | \& void Renew(void* ptr, int nitems, type) | |
1546 | .Ve | |
1547 | .IP "Renewc" 8 | |
1548 | .IX Xref "Renewc" | |
1549 | .IX Item "Renewc" | |
1550 | The XSUB\-writer's interface to the C \f(CW\*(C`realloc\*(C'\fR function, with | |
1551 | cast. | |
1552 | .Sp | |
1553 | .Vb 1 | |
1554 | \& void Renewc(void* ptr, int nitems, type, cast) | |
1555 | .Ve | |
1556 | .IP "Safefree" 8 | |
1557 | .IX Xref "Safefree" | |
1558 | .IX Item "Safefree" | |
1559 | The XSUB\-writer's interface to the C \f(CW\*(C`free\*(C'\fR function. | |
1560 | .Sp | |
1561 | .Vb 1 | |
1562 | \& void Safefree(void* ptr) | |
1563 | .Ve | |
1564 | .IP "savepv" 8 | |
1565 | .IX Xref "savepv" | |
1566 | .IX Item "savepv" | |
1567 | Perl's version of \f(CW\*(C`strdup()\*(C'\fR. Returns a pointer to a newly allocated | |
1568 | string which is a duplicate of \f(CW\*(C`pv\*(C'\fR. The size of the string is | |
1569 | determined by \f(CW\*(C`strlen()\*(C'\fR. The memory allocated for the new string can | |
1570 | be freed with the \f(CW\*(C`Safefree()\*(C'\fR function. | |
1571 | .Sp | |
1572 | .Vb 1 | |
1573 | \& char* savepv(const char* pv) | |
1574 | .Ve | |
1575 | .IP "savepvn" 8 | |
1576 | .IX Xref "savepvn" | |
1577 | .IX Item "savepvn" | |
1578 | Perl's version of what \f(CW\*(C`strndup()\*(C'\fR would be if it existed. Returns a | |
1579 | pointer to a newly allocated string which is a duplicate of the first | |
1580 | \&\f(CW\*(C`len\*(C'\fR bytes from \f(CW\*(C`pv\*(C'\fR. The memory allocated for the new string can be | |
1581 | freed with the \f(CW\*(C`Safefree()\*(C'\fR function. | |
1582 | .Sp | |
1583 | .Vb 1 | |
1584 | \& char* savepvn(const char* pv, I32 len) | |
1585 | .Ve | |
1586 | .IP "savesharedpv" 8 | |
1587 | .IX Xref "savesharedpv" | |
1588 | .IX Item "savesharedpv" | |
1589 | A version of \f(CW\*(C`savepv()\*(C'\fR which allocates the duplicate string in memory | |
1590 | which is shared between threads. | |
1591 | .Sp | |
1592 | .Vb 1 | |
1593 | \& char* savesharedpv(const char* pv) | |
1594 | .Ve | |
1595 | .IP "savesvpv" 8 | |
1596 | .IX Xref "savesvpv" | |
1597 | .IX Item "savesvpv" | |
1598 | A version of \f(CW\*(C`savepv()\*(C'\fR/\f(CW\*(C`savepvn()\*(C'\fR which gets the string to duplicate from | |
1599 | the passed in \s-1SV\s0 using \f(CW\*(C`SvPV()\*(C'\fR | |
1600 | .Sp | |
1601 | .Vb 1 | |
1602 | \& char* savesvpv(SV* sv) | |
1603 | .Ve | |
1604 | .IP "StructCopy" 8 | |
1605 | .IX Xref "StructCopy" | |
1606 | .IX Item "StructCopy" | |
1607 | This is an architecture-independent macro to copy one structure to another. | |
1608 | .Sp | |
1609 | .Vb 1 | |
1610 | \& void StructCopy(type src, type dest, type) | |
1611 | .Ve | |
1612 | .IP "Zero" 8 | |
1613 | .IX Xref "Zero" | |
1614 | .IX Item "Zero" | |
1615 | The XSUB\-writer's interface to the C \f(CW\*(C`memzero\*(C'\fR function. The \f(CW\*(C`dest\*(C'\fR is the | |
1616 | destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and \f(CW\*(C`type\*(C'\fR is the type. | |
1617 | .Sp | |
1618 | .Vb 1 | |
1619 | \& void Zero(void* dest, int nitems, type) | |
1620 | .Ve | |
1621 | .IP "ZeroD" 8 | |
1622 | .IX Xref "ZeroD" | |
1623 | .IX Item "ZeroD" | |
1624 | Like \f(CW\*(C`Zero\*(C'\fR but returns dest. Useful for encouraging compilers to tail-call | |
1625 | optimise. | |
1626 | .Sp | |
1627 | .Vb 1 | |
1628 | \& void * ZeroD(void* dest, int nitems, type) | |
1629 | .Ve | |
1630 | .SH "Miscellaneous Functions" | |
1631 | .IX Header "Miscellaneous Functions" | |
1632 | .IP "fbm_compile" 8 | |
1633 | .IX Xref "fbm_compile" | |
1634 | .IX Item "fbm_compile" | |
1635 | Analyses the string in order to make fast searches on it using \fIfbm_instr()\fR | |
1636 | \&\*(-- the Boyer-Moore algorithm. | |
1637 | .Sp | |
1638 | .Vb 1 | |
1639 | \& void fbm_compile(SV* sv, U32 flags) | |
1640 | .Ve | |
1641 | .IP "fbm_instr" 8 | |
1642 | .IX Xref "fbm_instr" | |
1643 | .IX Item "fbm_instr" | |
1644 | Returns the location of the \s-1SV\s0 in the string delimited by \f(CW\*(C`str\*(C'\fR and | |
1645 | \&\f(CW\*(C`strend\*(C'\fR. It returns \f(CW\*(C`Nullch\*(C'\fR if the string can't be found. The \f(CW\*(C`sv\*(C'\fR | |
1646 | does not have to be fbm_compiled, but the search will not be as fast | |
1647 | then. | |
1648 | .Sp | |
1649 | .Vb 1 | |
1650 | \& char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags) | |
1651 | .Ve | |
1652 | .IP "form" 8 | |
1653 | .IX Xref "form" | |
1654 | .IX Item "form" | |
1655 | Takes a sprintf-style format pattern and conventional | |
1656 | (non\-SV) arguments and returns the formatted string. | |
1657 | .Sp | |
1658 | .Vb 1 | |
1659 | \& (char *) Perl_form(pTHX_ const char* pat, ...) | |
1660 | .Ve | |
1661 | .Sp | |
1662 | can be used any place a string (char *) is required: | |
1663 | .Sp | |
1664 | .Vb 1 | |
1665 | \& char * s = Perl_form("%d.%d",major,minor); | |
1666 | .Ve | |
1667 | .Sp | |
1668 | Uses a single private buffer so if you want to format several strings you | |
1669 | must explicitly copy the earlier strings away (and free the copies when you | |
1670 | are done). | |
1671 | .Sp | |
1672 | .Vb 1 | |
1673 | \& char* form(const char* pat, ...) | |
1674 | .Ve | |
1675 | .IP "getcwd_sv" 8 | |
1676 | .IX Xref "getcwd_sv" | |
1677 | .IX Item "getcwd_sv" | |
1678 | Fill the sv with current working directory | |
1679 | .Sp | |
1680 | .Vb 1 | |
1681 | \& int getcwd_sv(SV* sv) | |
1682 | .Ve | |
1683 | .IP "strEQ" 8 | |
1684 | .IX Xref "strEQ" | |
1685 | .IX Item "strEQ" | |
1686 | Test two strings to see if they are equal. Returns true or false. | |
1687 | .Sp | |
1688 | .Vb 1 | |
1689 | \& bool strEQ(char* s1, char* s2) | |
1690 | .Ve | |
1691 | .IP "strGE" 8 | |
1692 | .IX Xref "strGE" | |
1693 | .IX Item "strGE" | |
1694 | Test two strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is greater than or equal to | |
1695 | the second, \f(CW\*(C`s2\*(C'\fR. Returns true or false. | |
1696 | .Sp | |
1697 | .Vb 1 | |
1698 | \& bool strGE(char* s1, char* s2) | |
1699 | .Ve | |
1700 | .IP "strGT" 8 | |
1701 | .IX Xref "strGT" | |
1702 | .IX Item "strGT" | |
1703 | Test two strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is greater than the second, | |
1704 | \&\f(CW\*(C`s2\*(C'\fR. Returns true or false. | |
1705 | .Sp | |
1706 | .Vb 1 | |
1707 | \& bool strGT(char* s1, char* s2) | |
1708 | .Ve | |
1709 | .IP "strLE" 8 | |
1710 | .IX Xref "strLE" | |
1711 | .IX Item "strLE" | |
1712 | Test two strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is less than or equal to the | |
1713 | second, \f(CW\*(C`s2\*(C'\fR. Returns true or false. | |
1714 | .Sp | |
1715 | .Vb 1 | |
1716 | \& bool strLE(char* s1, char* s2) | |
1717 | .Ve | |
1718 | .IP "strLT" 8 | |
1719 | .IX Xref "strLT" | |
1720 | .IX Item "strLT" | |
1721 | Test two strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is less than the second, | |
1722 | \&\f(CW\*(C`s2\*(C'\fR. Returns true or false. | |
1723 | .Sp | |
1724 | .Vb 1 | |
1725 | \& bool strLT(char* s1, char* s2) | |
1726 | .Ve | |
1727 | .IP "strNE" 8 | |
1728 | .IX Xref "strNE" | |
1729 | .IX Item "strNE" | |
1730 | Test two strings to see if they are different. Returns true or | |
1731 | false. | |
1732 | .Sp | |
1733 | .Vb 1 | |
1734 | \& bool strNE(char* s1, char* s2) | |
1735 | .Ve | |
1736 | .IP "strnEQ" 8 | |
1737 | .IX Xref "strnEQ" | |
1738 | .IX Item "strnEQ" | |
1739 | Test two strings to see if they are equal. The \f(CW\*(C`len\*(C'\fR parameter indicates | |
1740 | the number of bytes to compare. Returns true or false. (A wrapper for | |
1741 | \&\f(CW\*(C`strncmp\*(C'\fR). | |
1742 | .Sp | |
1743 | .Vb 1 | |
1744 | \& bool strnEQ(char* s1, char* s2, STRLEN len) | |
1745 | .Ve | |
1746 | .IP "strnNE" 8 | |
1747 | .IX Xref "strnNE" | |
1748 | .IX Item "strnNE" | |
1749 | Test two strings to see if they are different. The \f(CW\*(C`len\*(C'\fR parameter | |
1750 | indicates the number of bytes to compare. Returns true or false. (A | |
1751 | wrapper for \f(CW\*(C`strncmp\*(C'\fR). | |
1752 | .Sp | |
1753 | .Vb 1 | |
1754 | \& bool strnNE(char* s1, char* s2, STRLEN len) | |
1755 | .Ve | |
1756 | .IP "sv_nolocking" 8 | |
1757 | .IX Xref "sv_nolocking" | |
1758 | .IX Item "sv_nolocking" | |
1759 | Dummy routine which \*(L"locks\*(R" an \s-1SV\s0 when there is no locking module present. | |
1760 | Exists to avoid test for a \s-1NULL\s0 function pointer and because it could potentially warn under | |
1761 | some level of strict\-ness. | |
1762 | .Sp | |
1763 | .Vb 1 | |
1764 | \& void sv_nolocking(SV *) | |
1765 | .Ve | |
1766 | .IP "sv_nosharing" 8 | |
1767 | .IX Xref "sv_nosharing" | |
1768 | .IX Item "sv_nosharing" | |
1769 | Dummy routine which \*(L"shares\*(R" an \s-1SV\s0 when there is no sharing module present. | |
1770 | Exists to avoid test for a \s-1NULL\s0 function pointer and because it could potentially warn under | |
1771 | some level of strict\-ness. | |
1772 | .Sp | |
1773 | .Vb 1 | |
1774 | \& void sv_nosharing(SV *) | |
1775 | .Ve | |
1776 | .IP "sv_nounlocking" 8 | |
1777 | .IX Xref "sv_nounlocking" | |
1778 | .IX Item "sv_nounlocking" | |
1779 | Dummy routine which \*(L"unlocks\*(R" an \s-1SV\s0 when there is no locking module present. | |
1780 | Exists to avoid test for a \s-1NULL\s0 function pointer and because it could potentially warn under | |
1781 | some level of strict\-ness. | |
1782 | .Sp | |
1783 | .Vb 1 | |
1784 | \& void sv_nounlocking(SV *) | |
1785 | .Ve | |
1786 | .SH "Numeric functions" | |
1787 | .IX Header "Numeric functions" | |
1788 | .IP "grok_bin" 8 | |
1789 | .IX Xref "grok_bin" | |
1790 | .IX Item "grok_bin" | |
1791 | converts a string representing a binary number to numeric form. | |
1792 | .Sp | |
1793 | On entry \fIstart\fR and \fI*len\fR give the string to scan, \fI*flags\fR gives | |
1794 | conversion flags, and \fIresult\fR should be \s-1NULL\s0 or a pointer to an \s-1NV\s0. | |
1795 | The scan stops at the end of the string, or the first invalid character. | |
1796 | Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \fI*flags\fR, encountering an | |
1797 | invalid character will also trigger a warning. | |
1798 | On return \fI*len\fR is set to the length of the scanned string, | |
1799 | and \fI*flags\fR gives output flags. | |
1800 | .Sp | |
1801 | If the value is <= \f(CW\*(C`UV_MAX\*(C'\fR it is returned as a \s-1UV\s0, the output flags are clear, | |
1802 | and nothing is written to \fI*result\fR. If the value is > \s-1UV_MAX\s0 \f(CW\*(C`grok_bin\*(C'\fR | |
1803 | returns \s-1UV_MAX\s0, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags, | |
1804 | and writes the value to \fI*result\fR (or the value is discarded if \fIresult\fR | |
1805 | is \s-1NULL\s0). | |
1806 | .Sp | |
1807 | The binary number may optionally be prefixed with \*(L"0b\*(R" or \*(L"b\*(R" unless | |
1808 | \&\f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR is set in \fI*flags\fR on entry. If | |
1809 | \&\f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \fI*flags\fR then the binary | |
1810 | number may use '_' characters to separate digits. | |
1811 | .Sp | |
1812 | .Vb 1 | |
1813 | \& UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result) | |
1814 | .Ve | |
1815 | .IP "grok_hex" 8 | |
1816 | .IX Xref "grok_hex" | |
1817 | .IX Item "grok_hex" | |
1818 | converts a string representing a hex number to numeric form. | |
1819 | .Sp | |
1820 | On entry \fIstart\fR and \fI*len\fR give the string to scan, \fI*flags\fR gives | |
1821 | conversion flags, and \fIresult\fR should be \s-1NULL\s0 or a pointer to an \s-1NV\s0. | |
1822 | The scan stops at the end of the string, or the first invalid character. | |
1823 | Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \fI*flags\fR, encountering an | |
1824 | invalid character will also trigger a warning. | |
1825 | On return \fI*len\fR is set to the length of the scanned string, | |
1826 | and \fI*flags\fR gives output flags. | |
1827 | .Sp | |
1828 | If the value is <= \s-1UV_MAX\s0 it is returned as a \s-1UV\s0, the output flags are clear, | |
1829 | and nothing is written to \fI*result\fR. If the value is > \s-1UV_MAX\s0 \f(CW\*(C`grok_hex\*(C'\fR | |
1830 | returns \s-1UV_MAX\s0, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags, | |
1831 | and writes the value to \fI*result\fR (or the value is discarded if \fIresult\fR | |
1832 | is \s-1NULL\s0). | |
1833 | .Sp | |
1834 | The hex number may optionally be prefixed with \*(L"0x\*(R" or \*(L"x\*(R" unless | |
1835 | \&\f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR is set in \fI*flags\fR on entry. If | |
1836 | \&\f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \fI*flags\fR then the hex | |
1837 | number may use '_' characters to separate digits. | |
1838 | .Sp | |
1839 | .Vb 1 | |
1840 | \& UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result) | |
1841 | .Ve | |
1842 | .IP "grok_number" 8 | |
1843 | .IX Xref "grok_number" | |
1844 | .IX Item "grok_number" | |
1845 | Recognise (or not) a number. The type of the number is returned | |
1846 | (0 if unrecognised), otherwise it is a bit-ORed combination of | |
1847 | \&\s-1IS_NUMBER_IN_UV\s0, \s-1IS_NUMBER_GREATER_THAN_UV_MAX\s0, \s-1IS_NUMBER_NOT_INT\s0, | |
1848 | \&\s-1IS_NUMBER_NEG\s0, \s-1IS_NUMBER_INFINITY\s0, \s-1IS_NUMBER_NAN\s0 (defined in perl.h). | |
1849 | .Sp | |
1850 | If the value of the number can fit an in \s-1UV\s0, it is returned in the *valuep | |
1851 | \&\s-1IS_NUMBER_IN_UV\s0 will be set to indicate that *valuep is valid, \s-1IS_NUMBER_IN_UV\s0 | |
1852 | will never be set unless *valuep is valid, but *valuep may have been assigned | |
1853 | to during processing even though \s-1IS_NUMBER_IN_UV\s0 is not set on return. | |
1854 | If valuep is \s-1NULL\s0, \s-1IS_NUMBER_IN_UV\s0 will be set for the same cases as when | |
1855 | valuep is non\-NULL, but no actual assignment (or \s-1SEGV\s0) will occur. | |
1856 | .Sp | |
1857 | \&\s-1IS_NUMBER_NOT_INT\s0 will be set with \s-1IS_NUMBER_IN_UV\s0 if trailing decimals were | |
1858 | seen (in which case *valuep gives the true value truncated to an integer), and | |
1859 | \&\s-1IS_NUMBER_NEG\s0 if the number is negative (in which case *valuep holds the | |
1860 | absolute value). \s-1IS_NUMBER_IN_UV\s0 is not set if e notation was used or the | |
1861 | number is larger than a \s-1UV\s0. | |
1862 | .Sp | |
1863 | .Vb 1 | |
1864 | \& int grok_number(const char *pv, STRLEN len, UV *valuep) | |
1865 | .Ve | |
1866 | .IP "grok_numeric_radix" 8 | |
1867 | .IX Xref "grok_numeric_radix" | |
1868 | .IX Item "grok_numeric_radix" | |
1869 | Scan and skip for a numeric decimal separator (radix). | |
1870 | .Sp | |
1871 | .Vb 1 | |
1872 | \& bool grok_numeric_radix(const char **sp, const char *send) | |
1873 | .Ve | |
1874 | .IP "grok_oct" 8 | |
1875 | .IX Xref "grok_oct" | |
1876 | .IX Item "grok_oct" | |
1877 | converts a string representing an octal number to numeric form. | |
1878 | .Sp | |
1879 | On entry \fIstart\fR and \fI*len\fR give the string to scan, \fI*flags\fR gives | |
1880 | conversion flags, and \fIresult\fR should be \s-1NULL\s0 or a pointer to an \s-1NV\s0. | |
1881 | The scan stops at the end of the string, or the first invalid character. | |
1882 | Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \fI*flags\fR, encountering an | |
1883 | invalid character will also trigger a warning. | |
1884 | On return \fI*len\fR is set to the length of the scanned string, | |
1885 | and \fI*flags\fR gives output flags. | |
1886 | .Sp | |
1887 | If the value is <= \s-1UV_MAX\s0 it is returned as a \s-1UV\s0, the output flags are clear, | |
1888 | and nothing is written to \fI*result\fR. If the value is > \s-1UV_MAX\s0 \f(CW\*(C`grok_oct\*(C'\fR | |
1889 | returns \s-1UV_MAX\s0, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags, | |
1890 | and writes the value to \fI*result\fR (or the value is discarded if \fIresult\fR | |
1891 | is \s-1NULL\s0). | |
1892 | .Sp | |
1893 | If \f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \fI*flags\fR then the octal | |
1894 | number may use '_' characters to separate digits. | |
1895 | .Sp | |
1896 | .Vb 1 | |
1897 | \& UV grok_oct(char* start, STRLEN* len_p, I32* flags, NV *result) | |
1898 | .Ve | |
1899 | .IP "scan_bin" 8 | |
1900 | .IX Xref "scan_bin" | |
1901 | .IX Item "scan_bin" | |
1902 | For backwards compatibility. Use \f(CW\*(C`grok_bin\*(C'\fR instead. | |
1903 | .Sp | |
1904 | .Vb 1 | |
1905 | \& NV scan_bin(char* start, STRLEN len, STRLEN* retlen) | |
1906 | .Ve | |
1907 | .IP "scan_hex" 8 | |
1908 | .IX Xref "scan_hex" | |
1909 | .IX Item "scan_hex" | |
1910 | For backwards compatibility. Use \f(CW\*(C`grok_hex\*(C'\fR instead. | |
1911 | .Sp | |
1912 | .Vb 1 | |
1913 | \& NV scan_hex(char* start, STRLEN len, STRLEN* retlen) | |
1914 | .Ve | |
1915 | .IP "scan_oct" 8 | |
1916 | .IX Xref "scan_oct" | |
1917 | .IX Item "scan_oct" | |
1918 | For backwards compatibility. Use \f(CW\*(C`grok_oct\*(C'\fR instead. | |
1919 | .Sp | |
1920 | .Vb 1 | |
1921 | \& NV scan_oct(char* start, STRLEN len, STRLEN* retlen) | |
1922 | .Ve | |
1923 | .SH "Optree Manipulation Functions" | |
1924 | .IX Header "Optree Manipulation Functions" | |
1925 | .IP "cv_const_sv" 8 | |
1926 | .IX Xref "cv_const_sv" | |
1927 | .IX Item "cv_const_sv" | |
1928 | If \f(CW\*(C`cv\*(C'\fR is a constant sub eligible for inlining. returns the constant | |
1929 | value returned by the sub. Otherwise, returns \s-1NULL\s0. | |
1930 | .Sp | |
1931 | Constant subs can be created with \f(CW\*(C`newCONSTSUB\*(C'\fR or as described in | |
1932 | \&\*(L"Constant Functions\*(R" in perlsub. | |
1933 | .Sp | |
1934 | .Vb 1 | |
1935 | \& SV* cv_const_sv(CV* cv) | |
1936 | .Ve | |
1937 | .IP "newCONSTSUB" 8 | |
1938 | .IX Xref "newCONSTSUB" | |
1939 | .IX Item "newCONSTSUB" | |
1940 | Creates a constant sub equivalent to Perl \f(CW\*(C`sub FOO () { 123 }\*(C'\fR which is | |
1941 | eligible for inlining at compile\-time. | |
1942 | .Sp | |
1943 | .Vb 1 | |
1944 | \& CV* newCONSTSUB(HV* stash, char* name, SV* sv) | |
1945 | .Ve | |
1946 | .IP "newXS" 8 | |
1947 | .IX Xref "newXS" | |
1948 | .IX Item "newXS" | |
1949 | Used by \f(CW\*(C`xsubpp\*(C'\fR to hook up XSUBs as Perl subs. | |
1950 | .SH "Pad Data Structures" | |
1951 | .IX Header "Pad Data Structures" | |
1952 | .IP "pad_sv" 8 | |
1953 | .IX Xref "pad_sv" | |
1954 | .IX Item "pad_sv" | |
1955 | Get the value at offset po in the current pad. | |
1956 | Use macro \s-1PAD_SV\s0 instead of calling this function directly. | |
1957 | .Sp | |
1958 | .Vb 1 | |
1959 | \& SV* pad_sv(PADOFFSET po) | |
1960 | .Ve | |
1961 | .SH "Stack Manipulation Macros" | |
1962 | .IX Header "Stack Manipulation Macros" | |
1963 | .IP "dMARK" 8 | |
1964 | .IX Xref "dMARK" | |
1965 | .IX Item "dMARK" | |
1966 | Declare a stack marker variable, \f(CW\*(C`mark\*(C'\fR, for the \s-1XSUB\s0. See \f(CW\*(C`MARK\*(C'\fR and | |
1967 | \&\f(CW\*(C`dORIGMARK\*(C'\fR. | |
1968 | .Sp | |
1969 | .Vb 1 | |
1970 | \& dMARK; | |
1971 | .Ve | |
1972 | .IP "dORIGMARK" 8 | |
1973 | .IX Xref "dORIGMARK" | |
1974 | .IX Item "dORIGMARK" | |
1975 | Saves the original stack mark for the \s-1XSUB\s0. See \f(CW\*(C`ORIGMARK\*(C'\fR. | |
1976 | .Sp | |
1977 | .Vb 1 | |
1978 | \& dORIGMARK; | |
1979 | .Ve | |
1980 | .IP "dSP" 8 | |
1981 | .IX Xref "dSP" | |
1982 | .IX Item "dSP" | |
1983 | Declares a local copy of perl's stack pointer for the \s-1XSUB\s0, available via | |
1984 | the \f(CW\*(C`SP\*(C'\fR macro. See \f(CW\*(C`SP\*(C'\fR. | |
1985 | .Sp | |
1986 | .Vb 1 | |
1987 | \& dSP; | |
1988 | .Ve | |
1989 | .IP "\s-1EXTEND\s0" 8 | |
1990 | .IX Xref "EXTEND" | |
1991 | .IX Item "EXTEND" | |
1992 | Used to extend the argument stack for an \s-1XSUB\s0's return values. Once | |
1993 | used, guarantees that there is room for at least \f(CW\*(C`nitems\*(C'\fR to be pushed | |
1994 | onto the stack. | |
1995 | .Sp | |
1996 | .Vb 1 | |
1997 | \& void EXTEND(SP, int nitems) | |
1998 | .Ve | |
1999 | .IP "\s-1MARK\s0" 8 | |
2000 | .IX Xref "MARK" | |
2001 | .IX Item "MARK" | |
2002 | Stack marker variable for the \s-1XSUB\s0. See \f(CW\*(C`dMARK\*(C'\fR. | |
2003 | .IP "mPUSHi" 8 | |
2004 | .IX Xref "mPUSHi" | |
2005 | .IX Item "mPUSHi" | |
2006 | Push an integer onto the stack. The stack must have room for this element. | |
2007 | Handles 'set' magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW\*(C`PUSHi\*(C'\fR, \f(CW\*(C`mXPUSHi\*(C'\fR | |
2008 | and \f(CW\*(C`XPUSHi\*(C'\fR. | |
2009 | .Sp | |
2010 | .Vb 1 | |
2011 | \& void mPUSHi(IV iv) | |
2012 | .Ve | |
2013 | .IP "mPUSHn" 8 | |
2014 | .IX Xref "mPUSHn" | |
2015 | .IX Item "mPUSHn" | |
2016 | Push a double onto the stack. The stack must have room for this element. | |
2017 | Handles 'set' magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW\*(C`PUSHn\*(C'\fR, \f(CW\*(C`mXPUSHn\*(C'\fR | |
2018 | and \f(CW\*(C`XPUSHn\*(C'\fR. | |
2019 | .Sp | |
2020 | .Vb 1 | |
2021 | \& void mPUSHn(NV nv) | |
2022 | .Ve | |
2023 | .IP "mPUSHp" 8 | |
2024 | .IX Xref "mPUSHp" | |
2025 | .IX Item "mPUSHp" | |
2026 | Push a string onto the stack. The stack must have room for this element. | |
2027 | The \f(CW\*(C`len\*(C'\fR indicates the length of the string. Handles 'set' magic. Does | |
2028 | not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW\*(C`PUSHp\*(C'\fR, \f(CW\*(C`mXPUSHp\*(C'\fR and \f(CW\*(C`XPUSHp\*(C'\fR. | |
2029 | .Sp | |
2030 | .Vb 1 | |
2031 | \& void mPUSHp(char* str, STRLEN len) | |
2032 | .Ve | |
2033 | .IP "mPUSHu" 8 | |
2034 | .IX Xref "mPUSHu" | |
2035 | .IX Item "mPUSHu" | |
2036 | Push an unsigned integer onto the stack. The stack must have room for this | |
2037 | element. Handles 'set' magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW\*(C`PUSHu\*(C'\fR, | |
2038 | \&\f(CW\*(C`mXPUSHu\*(C'\fR and \f(CW\*(C`XPUSHu\*(C'\fR. | |
2039 | .Sp | |
2040 | .Vb 1 | |
2041 | \& void mPUSHu(UV uv) | |
2042 | .Ve | |
2043 | .IP "mXPUSHi" 8 | |
2044 | .IX Xref "mXPUSHi" | |
2045 | .IX Item "mXPUSHi" | |
2046 | Push an integer onto the stack, extending the stack if necessary. Handles | |
2047 | \&'set' magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW\*(C`XPUSHi\*(C'\fR, \f(CW\*(C`mPUSHi\*(C'\fR and | |
2048 | \&\f(CW\*(C`PUSHi\*(C'\fR. | |
2049 | .Sp | |
2050 | .Vb 1 | |
2051 | \& void mXPUSHi(IV iv) | |
2052 | .Ve | |
2053 | .IP "mXPUSHn" 8 | |
2054 | .IX Xref "mXPUSHn" | |
2055 | .IX Item "mXPUSHn" | |
2056 | Push a double onto the stack, extending the stack if necessary. Handles | |
2057 | \&'set' magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW\*(C`XPUSHn\*(C'\fR, \f(CW\*(C`mPUSHn\*(C'\fR and | |
2058 | \&\f(CW\*(C`PUSHn\*(C'\fR. | |
2059 | .Sp | |
2060 | .Vb 1 | |
2061 | \& void mXPUSHn(NV nv) | |
2062 | .Ve | |
2063 | .IP "mXPUSHp" 8 | |
2064 | .IX Xref "mXPUSHp" | |
2065 | .IX Item "mXPUSHp" | |
2066 | Push a string onto the stack, extending the stack if necessary. The \f(CW\*(C`len\*(C'\fR | |
2067 | indicates the length of the string. Handles 'set' magic. Does not use | |
2068 | \&\f(CW\*(C`TARG\*(C'\fR. See also \f(CW\*(C`XPUSHp\*(C'\fR, \f(CW\*(C`mPUSHp\*(C'\fR and \f(CW\*(C`PUSHp\*(C'\fR. | |
2069 | .Sp | |
2070 | .Vb 1 | |
2071 | \& void mXPUSHp(char* str, STRLEN len) | |
2072 | .Ve | |
2073 | .IP "mXPUSHu" 8 | |
2074 | .IX Xref "mXPUSHu" | |
2075 | .IX Item "mXPUSHu" | |
2076 | Push an unsigned integer onto the stack, extending the stack if necessary. | |
2077 | Handles 'set' magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW\*(C`XPUSHu\*(C'\fR, \f(CW\*(C`mPUSHu\*(C'\fR | |
2078 | and \f(CW\*(C`PUSHu\*(C'\fR. | |
2079 | .Sp | |
2080 | .Vb 1 | |
2081 | \& void mXPUSHu(UV uv) | |
2082 | .Ve | |
2083 | .IP "\s-1ORIGMARK\s0" 8 | |
2084 | .IX Xref "ORIGMARK" | |
2085 | .IX Item "ORIGMARK" | |
2086 | The original stack mark for the \s-1XSUB\s0. See \f(CW\*(C`dORIGMARK\*(C'\fR. | |
2087 | .IP "POPi" 8 | |
2088 | .IX Xref "POPi" | |
2089 | .IX Item "POPi" | |
2090 | Pops an integer off the stack. | |
2091 | .Sp | |
2092 | .Vb 1 | |
2093 | \& IV POPi | |
2094 | .Ve | |
2095 | .IP "POPl" 8 | |
2096 | .IX Xref "POPl" | |
2097 | .IX Item "POPl" | |
2098 | Pops a long off the stack. | |
2099 | .Sp | |
2100 | .Vb 1 | |
2101 | \& long POPl | |
2102 | .Ve | |
2103 | .IP "POPn" 8 | |
2104 | .IX Xref "POPn" | |
2105 | .IX Item "POPn" | |
2106 | Pops a double off the stack. | |
2107 | .Sp | |
2108 | .Vb 1 | |
2109 | \& NV POPn | |
2110 | .Ve | |
2111 | .IP "POPp" 8 | |
2112 | .IX Xref "POPp" | |
2113 | .IX Item "POPp" | |
2114 | Pops a string off the stack. Deprecated. New code should use POPpx. | |
2115 | .Sp | |
2116 | .Vb 1 | |
2117 | \& char* POPp | |
2118 | .Ve | |
2119 | .IP "POPpbytex" 8 | |
2120 | .IX Xref "POPpbytex" | |
2121 | .IX Item "POPpbytex" | |
2122 | Pops a string off the stack which must consist of bytes i.e. characters < 256. | |
2123 | .Sp | |
2124 | .Vb 1 | |
2125 | \& char* POPpbytex | |
2126 | .Ve | |
2127 | .IP "POPpx" 8 | |
2128 | .IX Xref "POPpx" | |
2129 | .IX Item "POPpx" | |
2130 | Pops a string off the stack. | |
2131 | .Sp | |
2132 | .Vb 1 | |
2133 | \& char* POPpx | |
2134 | .Ve | |
2135 | .IP "POPs" 8 | |
2136 | .IX Xref "POPs" | |
2137 | .IX Item "POPs" | |
2138 | Pops an \s-1SV\s0 off the stack. | |
2139 | .Sp | |
2140 | .Vb 1 | |
2141 | \& SV* POPs | |
2142 | .Ve | |
2143 | .IP "PUSHi" 8 | |
2144 | .IX Xref "PUSHi" | |
2145 | .IX Item "PUSHi" | |
2146 | Push an integer onto the stack. The stack must have room for this element. | |
2147 | Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be | |
2148 | called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to | |
2149 | return lists from \s-1XSUB\s0's \- see \f(CW\*(C`mPUSHi\*(C'\fR instead. See also \f(CW\*(C`XPUSHi\*(C'\fR and | |
2150 | \&\f(CW\*(C`mXPUSHi\*(C'\fR. | |
2151 | .Sp | |
2152 | .Vb 1 | |
2153 | \& void PUSHi(IV iv) | |
2154 | .Ve | |
2155 | .IP "\s-1PUSHMARK\s0" 8 | |
2156 | .IX Xref "PUSHMARK" | |
2157 | .IX Item "PUSHMARK" | |
2158 | Opening bracket for arguments on a callback. See \f(CW\*(C`PUTBACK\*(C'\fR and | |
2159 | perlcall. | |
2160 | .Sp | |
2161 | .Vb 1 | |
2162 | \& void PUSHMARK(SP) | |
2163 | .Ve | |
2164 | .IP "PUSHmortal" 8 | |
2165 | .IX Xref "PUSHmortal" | |
2166 | .IX Item "PUSHmortal" | |
2167 | Push a new mortal \s-1SV\s0 onto the stack. The stack must have room for this | |
2168 | element. Does not handle 'set' magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also | |
2169 | \&\f(CW\*(C`PUSHs\*(C'\fR, \f(CW\*(C`XPUSHmortal\*(C'\fR and \f(CW\*(C`XPUSHs\*(C'\fR. | |
2170 | .Sp | |
2171 | .Vb 1 | |
2172 | \& void PUSHmortal() | |
2173 | .Ve | |
2174 | .IP "PUSHn" 8 | |
2175 | .IX Xref "PUSHn" | |
2176 | .IX Item "PUSHn" | |
2177 | Push a double onto the stack. The stack must have room for this element. | |
2178 | Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be | |
2179 | called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to | |
2180 | return lists from \s-1XSUB\s0's \- see \f(CW\*(C`mPUSHn\*(C'\fR instead. See also \f(CW\*(C`XPUSHn\*(C'\fR and | |
2181 | \&\f(CW\*(C`mXPUSHn\*(C'\fR. | |
2182 | .Sp | |
2183 | .Vb 1 | |
2184 | \& void PUSHn(NV nv) | |
2185 | .Ve | |
2186 | .IP "PUSHp" 8 | |
2187 | .IX Xref "PUSHp" | |
2188 | .IX Item "PUSHp" | |
2189 | Push a string onto the stack. The stack must have room for this element. | |
2190 | The \f(CW\*(C`len\*(C'\fR indicates the length of the string. Handles 'set' magic. Uses | |
2191 | \&\f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to declare it. Do not | |
2192 | call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists from \s-1XSUB\s0's \- see | |
2193 | \&\f(CW\*(C`mPUSHp\*(C'\fR instead. See also \f(CW\*(C`XPUSHp\*(C'\fR and \f(CW\*(C`mXPUSHp\*(C'\fR. | |
2194 | .Sp | |
2195 | .Vb 1 | |
2196 | \& void PUSHp(char* str, STRLEN len) | |
2197 | .Ve | |
2198 | .IP "PUSHs" 8 | |
2199 | .IX Xref "PUSHs" | |
2200 | .IX Item "PUSHs" | |
2201 | Push an \s-1SV\s0 onto the stack. The stack must have room for this element. | |
2202 | Does not handle 'set' magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW\*(C`PUSHmortal\*(C'\fR, | |
2203 | \&\f(CW\*(C`XPUSHs\*(C'\fR and \f(CW\*(C`XPUSHmortal\*(C'\fR. | |
2204 | .Sp | |
2205 | .Vb 1 | |
2206 | \& void PUSHs(SV* sv) | |
2207 | .Ve | |
2208 | .IP "PUSHu" 8 | |
2209 | .IX Xref "PUSHu" | |
2210 | .IX Item "PUSHu" | |
2211 | Push an unsigned integer onto the stack. The stack must have room for this | |
2212 | element. Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR | |
2213 | should be called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented | |
2214 | macros to return lists from \s-1XSUB\s0's \- see \f(CW\*(C`mPUSHu\*(C'\fR instead. See also | |
2215 | \&\f(CW\*(C`XPUSHu\*(C'\fR and \f(CW\*(C`mXPUSHu\*(C'\fR. | |
2216 | .Sp | |
2217 | .Vb 1 | |
2218 | \& void PUSHu(UV uv) | |
2219 | .Ve | |
2220 | .IP "\s-1PUTBACK\s0" 8 | |
2221 | .IX Xref "PUTBACK" | |
2222 | .IX Item "PUTBACK" | |
2223 | Closing bracket for \s-1XSUB\s0 arguments. This is usually handled by \f(CW\*(C`xsubpp\*(C'\fR. | |
2224 | See \f(CW\*(C`PUSHMARK\*(C'\fR and perlcall for other uses. | |
2225 | .Sp | |
2226 | .Vb 1 | |
2227 | \& PUTBACK; | |
2228 | .Ve | |
2229 | .IP "\s-1SP\s0" 8 | |
2230 | .IX Xref "SP" | |
2231 | .IX Item "SP" | |
2232 | Stack pointer. This is usually handled by \f(CW\*(C`xsubpp\*(C'\fR. See \f(CW\*(C`dSP\*(C'\fR and | |
2233 | \&\f(CW\*(C`SPAGAIN\*(C'\fR. | |
2234 | .IP "\s-1SPAGAIN\s0" 8 | |
2235 | .IX Xref "SPAGAIN" | |
2236 | .IX Item "SPAGAIN" | |
2237 | Refetch the stack pointer. Used after a callback. See perlcall. | |
2238 | .Sp | |
2239 | .Vb 1 | |
2240 | \& SPAGAIN; | |
2241 | .Ve | |
2242 | .IP "XPUSHi" 8 | |
2243 | .IX Xref "XPUSHi" | |
2244 | .IX Item "XPUSHi" | |
2245 | Push an integer onto the stack, extending the stack if necessary. Handles | |
2246 | \&'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to | |
2247 | declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists | |
2248 | from \s-1XSUB\s0's \- see \f(CW\*(C`mXPUSHi\*(C'\fR instead. See also \f(CW\*(C`PUSHi\*(C'\fR and \f(CW\*(C`mPUSHi\*(C'\fR. | |
2249 | .Sp | |
2250 | .Vb 1 | |
2251 | \& void XPUSHi(IV iv) | |
2252 | .Ve | |
2253 | .IP "XPUSHmortal" 8 | |
2254 | .IX Xref "XPUSHmortal" | |
2255 | .IX Item "XPUSHmortal" | |
2256 | Push a new mortal \s-1SV\s0 onto the stack, extending the stack if necessary. Does | |
2257 | not handle 'set' magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW\*(C`XPUSHs\*(C'\fR, | |
2258 | \&\f(CW\*(C`PUSHmortal\*(C'\fR and \f(CW\*(C`PUSHs\*(C'\fR. | |
2259 | .Sp | |
2260 | .Vb 1 | |
2261 | \& void XPUSHmortal() | |
2262 | .Ve | |
2263 | .IP "XPUSHn" 8 | |
2264 | .IX Xref "XPUSHn" | |
2265 | .IX Item "XPUSHn" | |
2266 | Push a double onto the stack, extending the stack if necessary. Handles | |
2267 | \&'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to | |
2268 | declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists | |
2269 | from \s-1XSUB\s0's \- see \f(CW\*(C`mXPUSHn\*(C'\fR instead. See also \f(CW\*(C`PUSHn\*(C'\fR and \f(CW\*(C`mPUSHn\*(C'\fR. | |
2270 | .Sp | |
2271 | .Vb 1 | |
2272 | \& void XPUSHn(NV nv) | |
2273 | .Ve | |
2274 | .IP "XPUSHp" 8 | |
2275 | .IX Xref "XPUSHp" | |
2276 | .IX Item "XPUSHp" | |
2277 | Push a string onto the stack, extending the stack if necessary. The \f(CW\*(C`len\*(C'\fR | |
2278 | indicates the length of the string. Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so | |
2279 | \&\f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to declare it. Do not call | |
2280 | multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists from \s-1XSUB\s0's \- see | |
2281 | \&\f(CW\*(C`mXPUSHp\*(C'\fR instead. See also \f(CW\*(C`PUSHp\*(C'\fR and \f(CW\*(C`mPUSHp\*(C'\fR. | |
2282 | .Sp | |
2283 | .Vb 1 | |
2284 | \& void XPUSHp(char* str, STRLEN len) | |
2285 | .Ve | |
2286 | .IP "XPUSHs" 8 | |
2287 | .IX Xref "XPUSHs" | |
2288 | .IX Item "XPUSHs" | |
2289 | Push an \s-1SV\s0 onto the stack, extending the stack if necessary. Does not | |
2290 | handle 'set' magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW\*(C`XPUSHmortal\*(C'\fR, | |
2291 | \&\f(CW\*(C`PUSHs\*(C'\fR and \f(CW\*(C`PUSHmortal\*(C'\fR. | |
2292 | .Sp | |
2293 | .Vb 1 | |
2294 | \& void XPUSHs(SV* sv) | |
2295 | .Ve | |
2296 | .IP "XPUSHu" 8 | |
2297 | .IX Xref "XPUSHu" | |
2298 | .IX Item "XPUSHu" | |
2299 | Push an unsigned integer onto the stack, extending the stack if necessary. | |
2300 | Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be | |
2301 | called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to | |
2302 | return lists from \s-1XSUB\s0's \- see \f(CW\*(C`mXPUSHu\*(C'\fR instead. See also \f(CW\*(C`PUSHu\*(C'\fR and | |
2303 | \&\f(CW\*(C`mPUSHu\*(C'\fR. | |
2304 | .Sp | |
2305 | .Vb 1 | |
2306 | \& void XPUSHu(UV uv) | |
2307 | .Ve | |
2308 | .IP "\s-1XSRETURN\s0" 8 | |
2309 | .IX Xref "XSRETURN" | |
2310 | .IX Item "XSRETURN" | |
2311 | Return from \s-1XSUB\s0, indicating number of items on the stack. This is usually | |
2312 | handled by \f(CW\*(C`xsubpp\*(C'\fR. | |
2313 | .Sp | |
2314 | .Vb 1 | |
2315 | \& void XSRETURN(int nitems) | |
2316 | .Ve | |
2317 | .IP "\s-1XSRETURN_EMPTY\s0" 8 | |
2318 | .IX Xref "XSRETURN_EMPTY" | |
2319 | .IX Item "XSRETURN_EMPTY" | |
2320 | Return an empty list from an \s-1XSUB\s0 immediately. | |
2321 | .Sp | |
2322 | .Vb 1 | |
2323 | \& XSRETURN_EMPTY; | |
2324 | .Ve | |
2325 | .IP "\s-1XSRETURN_IV\s0" 8 | |
2326 | .IX Xref "XSRETURN_IV" | |
2327 | .IX Item "XSRETURN_IV" | |
2328 | Return an integer from an \s-1XSUB\s0 immediately. Uses \f(CW\*(C`XST_mIV\*(C'\fR. | |
2329 | .Sp | |
2330 | .Vb 1 | |
2331 | \& void XSRETURN_IV(IV iv) | |
2332 | .Ve | |
2333 | .IP "\s-1XSRETURN_NO\s0" 8 | |
2334 | .IX Xref "XSRETURN_NO" | |
2335 | .IX Item "XSRETURN_NO" | |
2336 | Return \f(CW&PL_sv_no\fR from an \s-1XSUB\s0 immediately. Uses \f(CW\*(C`XST_mNO\*(C'\fR. | |
2337 | .Sp | |
2338 | .Vb 1 | |
2339 | \& XSRETURN_NO; | |
2340 | .Ve | |
2341 | .IP "\s-1XSRETURN_NV\s0" 8 | |
2342 | .IX Xref "XSRETURN_NV" | |
2343 | .IX Item "XSRETURN_NV" | |
2344 | Return a double from an \s-1XSUB\s0 immediately. Uses \f(CW\*(C`XST_mNV\*(C'\fR. | |
2345 | .Sp | |
2346 | .Vb 1 | |
2347 | \& void XSRETURN_NV(NV nv) | |
2348 | .Ve | |
2349 | .IP "\s-1XSRETURN_PV\s0" 8 | |
2350 | .IX Xref "XSRETURN_PV" | |
2351 | .IX Item "XSRETURN_PV" | |
2352 | Return a copy of a string from an \s-1XSUB\s0 immediately. Uses \f(CW\*(C`XST_mPV\*(C'\fR. | |
2353 | .Sp | |
2354 | .Vb 1 | |
2355 | \& void XSRETURN_PV(char* str) | |
2356 | .Ve | |
2357 | .IP "\s-1XSRETURN_UNDEF\s0" 8 | |
2358 | .IX Xref "XSRETURN_UNDEF" | |
2359 | .IX Item "XSRETURN_UNDEF" | |
2360 | Return \f(CW&PL_sv_undef\fR from an \s-1XSUB\s0 immediately. Uses \f(CW\*(C`XST_mUNDEF\*(C'\fR. | |
2361 | .Sp | |
2362 | .Vb 1 | |
2363 | \& XSRETURN_UNDEF; | |
2364 | .Ve | |
2365 | .IP "\s-1XSRETURN_UV\s0" 8 | |
2366 | .IX Xref "XSRETURN_UV" | |
2367 | .IX Item "XSRETURN_UV" | |
2368 | Return an integer from an \s-1XSUB\s0 immediately. Uses \f(CW\*(C`XST_mUV\*(C'\fR. | |
2369 | .Sp | |
2370 | .Vb 1 | |
2371 | \& void XSRETURN_UV(IV uv) | |
2372 | .Ve | |
2373 | .IP "\s-1XSRETURN_YES\s0" 8 | |
2374 | .IX Xref "XSRETURN_YES" | |
2375 | .IX Item "XSRETURN_YES" | |
2376 | Return \f(CW&PL_sv_yes\fR from an \s-1XSUB\s0 immediately. Uses \f(CW\*(C`XST_mYES\*(C'\fR. | |
2377 | .Sp | |
2378 | .Vb 1 | |
2379 | \& XSRETURN_YES; | |
2380 | .Ve | |
2381 | .IP "XST_mIV" 8 | |
2382 | .IX Xref "XST_mIV" | |
2383 | .IX Item "XST_mIV" | |
2384 | Place an integer into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. The | |
2385 | value is stored in a new mortal \s-1SV\s0. | |
2386 | .Sp | |
2387 | .Vb 1 | |
2388 | \& void XST_mIV(int pos, IV iv) | |
2389 | .Ve | |
2390 | .IP "XST_mNO" 8 | |
2391 | .IX Xref "XST_mNO" | |
2392 | .IX Item "XST_mNO" | |
2393 | Place \f(CW&PL_sv_no\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the | |
2394 | stack. | |
2395 | .Sp | |
2396 | .Vb 1 | |
2397 | \& void XST_mNO(int pos) | |
2398 | .Ve | |
2399 | .IP "XST_mNV" 8 | |
2400 | .IX Xref "XST_mNV" | |
2401 | .IX Item "XST_mNV" | |
2402 | Place a double into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. The value | |
2403 | is stored in a new mortal \s-1SV\s0. | |
2404 | .Sp | |
2405 | .Vb 1 | |
2406 | \& void XST_mNV(int pos, NV nv) | |
2407 | .Ve | |
2408 | .IP "XST_mPV" 8 | |
2409 | .IX Xref "XST_mPV" | |
2410 | .IX Item "XST_mPV" | |
2411 | Place a copy of a string into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. | |
2412 | The value is stored in a new mortal \s-1SV\s0. | |
2413 | .Sp | |
2414 | .Vb 1 | |
2415 | \& void XST_mPV(int pos, char* str) | |
2416 | .Ve | |
2417 | .IP "XST_mUNDEF" 8 | |
2418 | .IX Xref "XST_mUNDEF" | |
2419 | .IX Item "XST_mUNDEF" | |
2420 | Place \f(CW&PL_sv_undef\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the | |
2421 | stack. | |
2422 | .Sp | |
2423 | .Vb 1 | |
2424 | \& void XST_mUNDEF(int pos) | |
2425 | .Ve | |
2426 | .IP "XST_mYES" 8 | |
2427 | .IX Xref "XST_mYES" | |
2428 | .IX Item "XST_mYES" | |
2429 | Place \f(CW&PL_sv_yes\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the | |
2430 | stack. | |
2431 | .Sp | |
2432 | .Vb 1 | |
2433 | \& void XST_mYES(int pos) | |
2434 | .Ve | |
2435 | .SH "SV Flags" | |
2436 | .IX Header "SV Flags" | |
2437 | .IP "svtype" 8 | |
2438 | .IX Xref "svtype" | |
2439 | .IX Item "svtype" | |
2440 | An enum of flags for Perl types. These are found in the file \fBsv.h\fR | |
2441 | in the \f(CW\*(C`svtype\*(C'\fR enum. Test these flags with the \f(CW\*(C`SvTYPE\*(C'\fR macro. | |
2442 | .IP "SVt_IV" 8 | |
2443 | .IX Xref "SVt_IV" | |
2444 | .IX Item "SVt_IV" | |
2445 | Integer type flag for scalars. See \f(CW\*(C`svtype\*(C'\fR. | |
2446 | .IP "SVt_NV" 8 | |
2447 | .IX Xref "SVt_NV" | |
2448 | .IX Item "SVt_NV" | |
2449 | Double type flag for scalars. See \f(CW\*(C`svtype\*(C'\fR. | |
2450 | .IP "SVt_PV" 8 | |
2451 | .IX Xref "SVt_PV" | |
2452 | .IX Item "SVt_PV" | |
2453 | Pointer type flag for scalars. See \f(CW\*(C`svtype\*(C'\fR. | |
2454 | .IP "SVt_PVAV" 8 | |
2455 | .IX Xref "SVt_PVAV" | |
2456 | .IX Item "SVt_PVAV" | |
2457 | Type flag for arrays. See \f(CW\*(C`svtype\*(C'\fR. | |
2458 | .IP "SVt_PVCV" 8 | |
2459 | .IX Xref "SVt_PVCV" | |
2460 | .IX Item "SVt_PVCV" | |
2461 | Type flag for code refs. See \f(CW\*(C`svtype\*(C'\fR. | |
2462 | .IP "SVt_PVHV" 8 | |
2463 | .IX Xref "SVt_PVHV" | |
2464 | .IX Item "SVt_PVHV" | |
2465 | Type flag for hashes. See \f(CW\*(C`svtype\*(C'\fR. | |
2466 | .IP "SVt_PVMG" 8 | |
2467 | .IX Xref "SVt_PVMG" | |
2468 | .IX Item "SVt_PVMG" | |
2469 | Type flag for blessed scalars. See \f(CW\*(C`svtype\*(C'\fR. | |
2470 | .SH "SV Manipulation Functions" | |
2471 | .IX Header "SV Manipulation Functions" | |
2472 | .IP "get_sv" 8 | |
2473 | .IX Xref "get_sv" | |
2474 | .IX Item "get_sv" | |
2475 | Returns the \s-1SV\s0 of the specified Perl scalar. If \f(CW\*(C`create\*(C'\fR is set and the | |
2476 | Perl variable does not exist then it will be created. If \f(CW\*(C`create\*(C'\fR is not | |
2477 | set and the variable does not exist then \s-1NULL\s0 is returned. | |
2478 | .Sp | |
2479 | \&\s-1NOTE:\s0 the perl_ form of this function is deprecated. | |
2480 | .Sp | |
2481 | .Vb 1 | |
2482 | \& SV* get_sv(const char* name, I32 create) | |
2483 | .Ve | |
2484 | .IP "looks_like_number" 8 | |
2485 | .IX Xref "looks_like_number" | |
2486 | .IX Item "looks_like_number" | |
2487 | Test if the content of an \s-1SV\s0 looks like a number (or is a number). | |
2488 | \&\f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`Infinity\*(C'\fR are treated as numbers (so will not issue a | |
2489 | non-numeric warning), even if your \fIatof()\fR doesn't grok them. | |
2490 | .Sp | |
2491 | .Vb 1 | |
2492 | \& I32 looks_like_number(SV* sv) | |
2493 | .Ve | |
2494 | .IP "newRV_inc" 8 | |
2495 | .IX Xref "newRV_inc" | |
2496 | .IX Item "newRV_inc" | |
2497 | Creates an \s-1RV\s0 wrapper for an \s-1SV\s0. The reference count for the original \s-1SV\s0 is | |
2498 | incremented. | |
2499 | .Sp | |
2500 | .Vb 1 | |
2501 | \& SV* newRV_inc(SV* sv) | |
2502 | .Ve | |
2503 | .IP "newRV_noinc" 8 | |
2504 | .IX Xref "newRV_noinc" | |
2505 | .IX Item "newRV_noinc" | |
2506 | Creates an \s-1RV\s0 wrapper for an \s-1SV\s0. The reference count for the original | |
2507 | \&\s-1SV\s0 is \fBnot\fR incremented. | |
2508 | .Sp | |
2509 | .Vb 1 | |
2510 | \& SV* newRV_noinc(SV *sv) | |
2511 | .Ve | |
2512 | .IP "\s-1NEWSV\s0" 8 | |
2513 | .IX Xref "NEWSV" | |
2514 | .IX Item "NEWSV" | |
2515 | Creates a new \s-1SV\s0. A non-zero \f(CW\*(C`len\*(C'\fR parameter indicates the number of | |
2516 | bytes of preallocated string space the \s-1SV\s0 should have. An extra byte for a | |
2517 | tailing \s-1NUL\s0 is also reserved. (SvPOK is not set for the \s-1SV\s0 even if string | |
2518 | space is allocated.) The reference count for the new \s-1SV\s0 is set to 1. | |
2519 | \&\f(CW\*(C`id\*(C'\fR is an integer id between 0 and 1299 (used to identify leaks). | |
2520 | .Sp | |
2521 | .Vb 1 | |
2522 | \& SV* NEWSV(int id, STRLEN len) | |
2523 | .Ve | |
2524 | .IP "newSV" 8 | |
2525 | .IX Xref "newSV" | |
2526 | .IX Item "newSV" | |
2527 | Create a new null \s-1SV\s0, or if len > 0, create a new empty SVt_PV type \s-1SV\s0 | |
2528 | with an initial \s-1PV\s0 allocation of len+1. Normally accessed via the \f(CW\*(C`NEWSV\*(C'\fR | |
2529 | macro. | |
2530 | .Sp | |
2531 | .Vb 1 | |
2532 | \& SV* newSV(STRLEN len) | |
2533 | .Ve | |
2534 | .IP "newSVhek" 8 | |
2535 | .IX Xref "newSVhek" | |
2536 | .IX Item "newSVhek" | |
2537 | Creates a new \s-1SV\s0 from the hash key structure. It will generate scalars that | |
2538 | point to the shared string table where possible. Returns a new (undefined) | |
2539 | \&\s-1SV\s0 if the hek is \s-1NULL\s0. | |
2540 | .Sp | |
2541 | .Vb 1 | |
2542 | \& SV* newSVhek(const HEK *hek) | |
2543 | .Ve | |
2544 | .IP "newSViv" 8 | |
2545 | .IX Xref "newSViv" | |
2546 | .IX Item "newSViv" | |
2547 | Creates a new \s-1SV\s0 and copies an integer into it. The reference count for the | |
2548 | \&\s-1SV\s0 is set to 1. | |
2549 | .Sp | |
2550 | .Vb 1 | |
2551 | \& SV* newSViv(IV i) | |
2552 | .Ve | |
2553 | .IP "newSVnv" 8 | |
2554 | .IX Xref "newSVnv" | |
2555 | .IX Item "newSVnv" | |
2556 | Creates a new \s-1SV\s0 and copies a floating point value into it. | |
2557 | The reference count for the \s-1SV\s0 is set to 1. | |
2558 | .Sp | |
2559 | .Vb 1 | |
2560 | \& SV* newSVnv(NV n) | |
2561 | .Ve | |
2562 | .IP "newSVpv" 8 | |
2563 | .IX Xref "newSVpv" | |
2564 | .IX Item "newSVpv" | |
2565 | Creates a new \s-1SV\s0 and copies a string into it. The reference count for the | |
2566 | \&\s-1SV\s0 is set to 1. If \f(CW\*(C`len\*(C'\fR is zero, Perl will compute the length using | |
2567 | \&\fIstrlen()\fR. For efficiency, consider using \f(CW\*(C`newSVpvn\*(C'\fR instead. | |
2568 | .Sp | |
2569 | .Vb 1 | |
2570 | \& SV* newSVpv(const char* s, STRLEN len) | |
2571 | .Ve | |
2572 | .IP "newSVpvf" 8 | |
2573 | .IX Xref "newSVpvf" | |
2574 | .IX Item "newSVpvf" | |
2575 | Creates a new \s-1SV\s0 and initializes it with the string formatted like | |
2576 | \&\f(CW\*(C`sprintf\*(C'\fR. | |
2577 | .Sp | |
2578 | .Vb 1 | |
2579 | \& SV* newSVpvf(const char* pat, ...) | |
2580 | .Ve | |
2581 | .IP "newSVpvn" 8 | |
2582 | .IX Xref "newSVpvn" | |
2583 | .IX Item "newSVpvn" | |
2584 | Creates a new \s-1SV\s0 and copies a string into it. The reference count for the | |
2585 | \&\s-1SV\s0 is set to 1. Note that if \f(CW\*(C`len\*(C'\fR is zero, Perl will create a zero length | |
2586 | string. You are responsible for ensuring that the source string is at least | |
2587 | \&\f(CW\*(C`len\*(C'\fR bytes long. If the \f(CW\*(C`s\*(C'\fR argument is \s-1NULL\s0 the new \s-1SV\s0 will be undefined. | |
2588 | .Sp | |
2589 | .Vb 1 | |
2590 | \& SV* newSVpvn(const char* s, STRLEN len) | |
2591 | .Ve | |
2592 | .IP "newSVpvn_share" 8 | |
2593 | .IX Xref "newSVpvn_share" | |
2594 | .IX Item "newSVpvn_share" | |
2595 | Creates a new \s-1SV\s0 with its SvPVX_const pointing to a shared string in the string | |
2596 | table. If the string does not already exist in the table, it is created | |
2597 | first. Turns on \s-1READONLY\s0 and \s-1FAKE\s0. The string's hash is stored in the \s-1UV\s0 | |
2598 | slot of the \s-1SV\s0; if the \f(CW\*(C`hash\*(C'\fR parameter is non\-zero, that value is used; | |
2599 | otherwise the hash is computed. The idea here is that as the string table | |
2600 | is used for shared hash keys these strings will have SvPVX_const == HeKEY and | |
2601 | hash lookup will avoid string compare. | |
2602 | .Sp | |
2603 | .Vb 1 | |
2604 | \& SV* newSVpvn_share(const char* s, I32 len, U32 hash) | |
2605 | .Ve | |
2606 | .IP "newSVrv" 8 | |
2607 | .IX Xref "newSVrv" | |
2608 | .IX Item "newSVrv" | |
2609 | Creates a new \s-1SV\s0 for the \s-1RV\s0, \f(CW\*(C`rv\*(C'\fR, to point to. If \f(CW\*(C`rv\*(C'\fR is not an \s-1RV\s0 then | |
2610 | it will be upgraded to one. If \f(CW\*(C`classname\*(C'\fR is non-null then the new \s-1SV\s0 will | |
2611 | be blessed in the specified package. The new \s-1SV\s0 is returned and its | |
2612 | reference count is 1. | |
2613 | .Sp | |
2614 | .Vb 1 | |
2615 | \& SV* newSVrv(SV* rv, const char* classname) | |
2616 | .Ve | |
2617 | .IP "newSVsv" 8 | |
2618 | .IX Xref "newSVsv" | |
2619 | .IX Item "newSVsv" | |
2620 | Creates a new \s-1SV\s0 which is an exact duplicate of the original \s-1SV\s0. | |
2621 | (Uses \f(CW\*(C`sv_setsv\*(C'\fR). | |
2622 | .Sp | |
2623 | .Vb 1 | |
2624 | \& SV* newSVsv(SV* old) | |
2625 | .Ve | |
2626 | .IP "newSVuv" 8 | |
2627 | .IX Xref "newSVuv" | |
2628 | .IX Item "newSVuv" | |
2629 | Creates a new \s-1SV\s0 and copies an unsigned integer into it. | |
2630 | The reference count for the \s-1SV\s0 is set to 1. | |
2631 | .Sp | |
2632 | .Vb 1 | |
2633 | \& SV* newSVuv(UV u) | |
2634 | .Ve | |
2635 | .IP "SvCUR" 8 | |
2636 | .IX Xref "SvCUR" | |
2637 | .IX Item "SvCUR" | |
2638 | Returns the length of the string which is in the \s-1SV\s0. See \f(CW\*(C`SvLEN\*(C'\fR. | |
2639 | .Sp | |
2640 | .Vb 1 | |
2641 | \& STRLEN SvCUR(SV* sv) | |
2642 | .Ve | |
2643 | .IP "SvCUR_set" 8 | |
2644 | .IX Xref "SvCUR_set" | |
2645 | .IX Item "SvCUR_set" | |
2646 | Set the current length of the string which is in the \s-1SV\s0. See \f(CW\*(C`SvCUR\*(C'\fR | |
2647 | and \f(CW\*(C`SvIV_set\*(C'\fR. | |
2648 | .Sp | |
2649 | .Vb 1 | |
2650 | \& void SvCUR_set(SV* sv, STRLEN len) | |
2651 | .Ve | |
2652 | .IP "SvEND" 8 | |
2653 | .IX Xref "SvEND" | |
2654 | .IX Item "SvEND" | |
2655 | Returns a pointer to the last character in the string which is in the \s-1SV\s0. | |
2656 | See \f(CW\*(C`SvCUR\*(C'\fR. Access the character as *(SvEND(sv)). | |
2657 | .Sp | |
2658 | .Vb 1 | |
2659 | \& char* SvEND(SV* sv) | |
2660 | .Ve | |
2661 | .IP "SvGROW" 8 | |
2662 | .IX Xref "SvGROW" | |
2663 | .IX Item "SvGROW" | |
2664 | Expands the character buffer in the \s-1SV\s0 so that it has room for the | |
2665 | indicated number of bytes (remember to reserve space for an extra trailing | |
2666 | \&\s-1NUL\s0 character). Calls \f(CW\*(C`sv_grow\*(C'\fR to perform the expansion if necessary. | |
2667 | Returns a pointer to the character buffer. | |
2668 | .Sp | |
2669 | .Vb 1 | |
2670 | \& char * SvGROW(SV* sv, STRLEN len) | |
2671 | .Ve | |
2672 | .IP "SvIOK" 8 | |
2673 | .IX Xref "SvIOK" | |
2674 | .IX Item "SvIOK" | |
2675 | Returns a boolean indicating whether the \s-1SV\s0 contains an integer. | |
2676 | .Sp | |
2677 | .Vb 1 | |
2678 | \& bool SvIOK(SV* sv) | |
2679 | .Ve | |
2680 | .IP "SvIOKp" 8 | |
2681 | .IX Xref "SvIOKp" | |
2682 | .IX Item "SvIOKp" | |
2683 | Returns a boolean indicating whether the \s-1SV\s0 contains an integer. Checks | |
2684 | the \fBprivate\fR setting. Use \f(CW\*(C`SvIOK\*(C'\fR. | |
2685 | .Sp | |
2686 | .Vb 1 | |
2687 | \& bool SvIOKp(SV* sv) | |
2688 | .Ve | |
2689 | .IP "SvIOK_notUV" 8 | |
2690 | .IX Xref "SvIOK_notUV" | |
2691 | .IX Item "SvIOK_notUV" | |
2692 | Returns a boolean indicating whether the \s-1SV\s0 contains a signed integer. | |
2693 | .Sp | |
2694 | .Vb 1 | |
2695 | \& bool SvIOK_notUV(SV* sv) | |
2696 | .Ve | |
2697 | .IP "SvIOK_off" 8 | |
2698 | .IX Xref "SvIOK_off" | |
2699 | .IX Item "SvIOK_off" | |
2700 | Unsets the \s-1IV\s0 status of an \s-1SV\s0. | |
2701 | .Sp | |
2702 | .Vb 1 | |
2703 | \& void SvIOK_off(SV* sv) | |
2704 | .Ve | |
2705 | .IP "SvIOK_on" 8 | |
2706 | .IX Xref "SvIOK_on" | |
2707 | .IX Item "SvIOK_on" | |
2708 | Tells an \s-1SV\s0 that it is an integer. | |
2709 | .Sp | |
2710 | .Vb 1 | |
2711 | \& void SvIOK_on(SV* sv) | |
2712 | .Ve | |
2713 | .IP "SvIOK_only" 8 | |
2714 | .IX Xref "SvIOK_only" | |
2715 | .IX Item "SvIOK_only" | |
2716 | Tells an \s-1SV\s0 that it is an integer and disables all other \s-1OK\s0 bits. | |
2717 | .Sp | |
2718 | .Vb 1 | |
2719 | \& void SvIOK_only(SV* sv) | |
2720 | .Ve | |
2721 | .IP "SvIOK_only_UV" 8 | |
2722 | .IX Xref "SvIOK_only_UV" | |
2723 | .IX Item "SvIOK_only_UV" | |
2724 | Tells and \s-1SV\s0 that it is an unsigned integer and disables all other \s-1OK\s0 bits. | |
2725 | .Sp | |
2726 | .Vb 1 | |
2727 | \& void SvIOK_only_UV(SV* sv) | |
2728 | .Ve | |
2729 | .IP "SvIOK_UV" 8 | |
2730 | .IX Xref "SvIOK_UV" | |
2731 | .IX Item "SvIOK_UV" | |
2732 | Returns a boolean indicating whether the \s-1SV\s0 contains an unsigned integer. | |
2733 | .Sp | |
2734 | .Vb 1 | |
2735 | \& bool SvIOK_UV(SV* sv) | |
2736 | .Ve | |
2737 | .IP "SvIsCOW" 8 | |
2738 | .IX Xref "SvIsCOW" | |
2739 | .IX Item "SvIsCOW" | |
2740 | Returns a boolean indicating whether the \s-1SV\s0 is Copy\-On\-Write. (either shared | |
2741 | hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for | |
2742 | \&\s-1COW\s0) | |
2743 | .Sp | |
2744 | .Vb 1 | |
2745 | \& bool SvIsCOW(SV* sv) | |
2746 | .Ve | |
2747 | .IP "SvIsCOW_shared_hash" 8 | |
2748 | .IX Xref "SvIsCOW_shared_hash" | |
2749 | .IX Item "SvIsCOW_shared_hash" | |
2750 | Returns a boolean indicating whether the \s-1SV\s0 is Copy-On-Write shared hash key | |
2751 | scalar. | |
2752 | .Sp | |
2753 | .Vb 1 | |
2754 | \& bool SvIsCOW_shared_hash(SV* sv) | |
2755 | .Ve | |
2756 | .IP "SvIV" 8 | |
2757 | .IX Xref "SvIV" | |
2758 | .IX Item "SvIV" | |
2759 | Coerces the given \s-1SV\s0 to an integer and returns it. See \f(CW\*(C`SvIVx\*(C'\fR for a | |
2760 | version which guarantees to evaluate sv only once. | |
2761 | .Sp | |
2762 | .Vb 1 | |
2763 | \& IV SvIV(SV* sv) | |
2764 | .Ve | |
2765 | .IP "SvIVX" 8 | |
2766 | .IX Xref "SvIVX" | |
2767 | .IX Item "SvIVX" | |
2768 | Returns the raw value in the \s-1SV\s0's \s-1IV\s0 slot, without checks or conversions. | |
2769 | Only use when you are sure SvIOK is true. See also \f(CW\*(C`SvIV()\*(C'\fR. | |
2770 | .Sp | |
2771 | .Vb 1 | |
2772 | \& IV SvIVX(SV* sv) | |
2773 | .Ve | |
2774 | .IP "SvIVx" 8 | |
2775 | .IX Xref "SvIVx" | |
2776 | .IX Item "SvIVx" | |
2777 | Coerces the given \s-1SV\s0 to an integer and returns it. Guarantees to evaluate | |
2778 | sv only once. Use the more efficient \f(CW\*(C`SvIV\*(C'\fR otherwise. | |
2779 | .Sp | |
2780 | .Vb 1 | |
2781 | \& IV SvIVx(SV* sv) | |
2782 | .Ve | |
2783 | .IP "SvIV_set" 8 | |
2784 | .IX Xref "SvIV_set" | |
2785 | .IX Item "SvIV_set" | |
2786 | Set the value of the \s-1IV\s0 pointer in sv to val. It is possible to perform | |
2787 | the same function of this macro with an lvalue assignment to \f(CW\*(C`SvIVX\*(C'\fR. | |
2788 | With future Perls, however, it will be more efficient to use | |
2789 | \&\f(CW\*(C`SvIV_set\*(C'\fR instead of the lvalue assignment to \f(CW\*(C`SvIVX\*(C'\fR. | |
2790 | .Sp | |
2791 | .Vb 1 | |
2792 | \& void SvIV_set(SV* sv, IV val) | |
2793 | .Ve | |
2794 | .IP "SvLEN" 8 | |
2795 | .IX Xref "SvLEN" | |
2796 | .IX Item "SvLEN" | |
2797 | Returns the size of the string buffer in the \s-1SV\s0, not including any part | |
2798 | attributable to \f(CW\*(C`SvOOK\*(C'\fR. See \f(CW\*(C`SvCUR\*(C'\fR. | |
2799 | .Sp | |
2800 | .Vb 1 | |
2801 | \& STRLEN SvLEN(SV* sv) | |
2802 | .Ve | |
2803 | .IP "SvLEN_set" 8 | |
2804 | .IX Xref "SvLEN_set" | |
2805 | .IX Item "SvLEN_set" | |
2806 | Set the actual length of the string which is in the \s-1SV\s0. See \f(CW\*(C`SvIV_set\*(C'\fR. | |
2807 | .Sp | |
2808 | .Vb 1 | |
2809 | \& void SvLEN_set(SV* sv, STRLEN len) | |
2810 | .Ve | |
2811 | .IP "SvMAGIC_set" 8 | |
2812 | .IX Xref "SvMAGIC_set" | |
2813 | .IX Item "SvMAGIC_set" | |
2814 | Set the value of the \s-1MAGIC\s0 pointer in sv to val. See \f(CW\*(C`SvIV_set\*(C'\fR. | |
2815 | .Sp | |
2816 | .Vb 1 | |
2817 | \& void SvMAGIC_set(SV* sv, MAGIC* val) | |
2818 | .Ve | |
2819 | .IP "SvNIOK" 8 | |
2820 | .IX Xref "SvNIOK" | |
2821 | .IX Item "SvNIOK" | |
2822 | Returns a boolean indicating whether the \s-1SV\s0 contains a number, integer or | |
2823 | double. | |
2824 | .Sp | |
2825 | .Vb 1 | |
2826 | \& bool SvNIOK(SV* sv) | |
2827 | .Ve | |
2828 | .IP "SvNIOKp" 8 | |
2829 | .IX Xref "SvNIOKp" | |
2830 | .IX Item "SvNIOKp" | |
2831 | Returns a boolean indicating whether the \s-1SV\s0 contains a number, integer or | |
2832 | double. Checks the \fBprivate\fR setting. Use \f(CW\*(C`SvNIOK\*(C'\fR. | |
2833 | .Sp | |
2834 | .Vb 1 | |
2835 | \& bool SvNIOKp(SV* sv) | |
2836 | .Ve | |
2837 | .IP "SvNIOK_off" 8 | |
2838 | .IX Xref "SvNIOK_off" | |
2839 | .IX Item "SvNIOK_off" | |
2840 | Unsets the \s-1NV/IV\s0 status of an \s-1SV\s0. | |
2841 | .Sp | |
2842 | .Vb 1 | |
2843 | \& void SvNIOK_off(SV* sv) | |
2844 | .Ve | |
2845 | .IP "SvNOK" 8 | |
2846 | .IX Xref "SvNOK" | |
2847 | .IX Item "SvNOK" | |
2848 | Returns a boolean indicating whether the \s-1SV\s0 contains a double. | |
2849 | .Sp | |
2850 | .Vb 1 | |
2851 | \& bool SvNOK(SV* sv) | |
2852 | .Ve | |
2853 | .IP "SvNOKp" 8 | |
2854 | .IX Xref "SvNOKp" | |
2855 | .IX Item "SvNOKp" | |
2856 | Returns a boolean indicating whether the \s-1SV\s0 contains a double. Checks the | |
2857 | \&\fBprivate\fR setting. Use \f(CW\*(C`SvNOK\*(C'\fR. | |
2858 | .Sp | |
2859 | .Vb 1 | |
2860 | \& bool SvNOKp(SV* sv) | |
2861 | .Ve | |
2862 | .IP "SvNOK_off" 8 | |
2863 | .IX Xref "SvNOK_off" | |
2864 | .IX Item "SvNOK_off" | |
2865 | Unsets the \s-1NV\s0 status of an \s-1SV\s0. | |
2866 | .Sp | |
2867 | .Vb 1 | |
2868 | \& void SvNOK_off(SV* sv) | |
2869 | .Ve | |
2870 | .IP "SvNOK_on" 8 | |
2871 | .IX Xref "SvNOK_on" | |
2872 | .IX Item "SvNOK_on" | |
2873 | Tells an \s-1SV\s0 that it is a double. | |
2874 | .Sp | |
2875 | .Vb 1 | |
2876 | \& void SvNOK_on(SV* sv) | |
2877 | .Ve | |
2878 | .IP "SvNOK_only" 8 | |
2879 | .IX Xref "SvNOK_only" | |
2880 | .IX Item "SvNOK_only" | |
2881 | Tells an \s-1SV\s0 that it is a double and disables all other \s-1OK\s0 bits. | |
2882 | .Sp | |
2883 | .Vb 1 | |
2884 | \& void SvNOK_only(SV* sv) | |
2885 | .Ve | |
2886 | .IP "SvNV" 8 | |
2887 | .IX Xref "SvNV" | |
2888 | .IX Item "SvNV" | |
2889 | Coerce the given \s-1SV\s0 to a double and return it. See \f(CW\*(C`SvNVx\*(C'\fR for a version | |
2890 | which guarantees to evaluate sv only once. | |
2891 | .Sp | |
2892 | .Vb 1 | |
2893 | \& NV SvNV(SV* sv) | |
2894 | .Ve | |
2895 | .IP "SvNVX" 8 | |
2896 | .IX Xref "SvNVX" | |
2897 | .IX Item "SvNVX" | |
2898 | Returns the raw value in the \s-1SV\s0's \s-1NV\s0 slot, without checks or conversions. | |
2899 | Only use when you are sure SvNOK is true. See also \f(CW\*(C`SvNV()\*(C'\fR. | |
2900 | .Sp | |
2901 | .Vb 1 | |
2902 | \& NV SvNVX(SV* sv) | |
2903 | .Ve | |
2904 | .IP "SvNVx" 8 | |
2905 | .IX Xref "SvNVx" | |
2906 | .IX Item "SvNVx" | |
2907 | Coerces the given \s-1SV\s0 to a double and returns it. Guarantees to evaluate | |
2908 | sv only once. Use the more efficient \f(CW\*(C`SvNV\*(C'\fR otherwise. | |
2909 | .Sp | |
2910 | .Vb 1 | |
2911 | \& NV SvNVx(SV* sv) | |
2912 | .Ve | |
2913 | .IP "SvNV_set" 8 | |
2914 | .IX Xref "SvNV_set" | |
2915 | .IX Item "SvNV_set" | |
2916 | Set the value of the \s-1NV\s0 pointer in sv to val. See \f(CW\*(C`SvIV_set\*(C'\fR. | |
2917 | .Sp | |
2918 | .Vb 1 | |
2919 | \& void SvNV_set(SV* sv, NV val) | |
2920 | .Ve | |
2921 | .IP "SvOK" 8 | |
2922 | .IX Xref "SvOK" | |
2923 | .IX Item "SvOK" | |
2924 | Returns a boolean indicating whether the value is an \s-1SV\s0. It also tells | |
2925 | whether the value is defined or not. | |
2926 | .Sp | |
2927 | .Vb 1 | |
2928 | \& bool SvOK(SV* sv) | |
2929 | .Ve | |
2930 | .IP "SvOOK" 8 | |
2931 | .IX Xref "SvOOK" | |
2932 | .IX Item "SvOOK" | |
2933 | Returns a boolean indicating whether the SvIVX is a valid offset value for | |
2934 | the SvPVX. This hack is used internally to speed up removal of characters | |
2935 | from the beginning of a SvPV. When SvOOK is true, then the start of the | |
2936 | allocated string buffer is really (SvPVX \- SvIVX). | |
2937 | .Sp | |
2938 | .Vb 1 | |
2939 | \& bool SvOOK(SV* sv) | |
2940 | .Ve | |
2941 | .IP "SvPOK" 8 | |
2942 | .IX Xref "SvPOK" | |
2943 | .IX Item "SvPOK" | |
2944 | Returns a boolean indicating whether the \s-1SV\s0 contains a character | |
2945 | string. | |
2946 | .Sp | |
2947 | .Vb 1 | |
2948 | \& bool SvPOK(SV* sv) | |
2949 | .Ve | |
2950 | .IP "SvPOKp" 8 | |
2951 | .IX Xref "SvPOKp" | |
2952 | .IX Item "SvPOKp" | |
2953 | Returns a boolean indicating whether the \s-1SV\s0 contains a character string. | |
2954 | Checks the \fBprivate\fR setting. Use \f(CW\*(C`SvPOK\*(C'\fR. | |
2955 | .Sp | |
2956 | .Vb 1 | |
2957 | \& bool SvPOKp(SV* sv) | |
2958 | .Ve | |
2959 | .IP "SvPOK_off" 8 | |
2960 | .IX Xref "SvPOK_off" | |
2961 | .IX Item "SvPOK_off" | |
2962 | Unsets the \s-1PV\s0 status of an \s-1SV\s0. | |
2963 | .Sp | |
2964 | .Vb 1 | |
2965 | \& void SvPOK_off(SV* sv) | |
2966 | .Ve | |
2967 | .IP "SvPOK_on" 8 | |
2968 | .IX Xref "SvPOK_on" | |
2969 | .IX Item "SvPOK_on" | |
2970 | Tells an \s-1SV\s0 that it is a string. | |
2971 | .Sp | |
2972 | .Vb 1 | |
2973 | \& void SvPOK_on(SV* sv) | |
2974 | .Ve | |
2975 | .IP "SvPOK_only" 8 | |
2976 | .IX Xref "SvPOK_only" | |
2977 | .IX Item "SvPOK_only" | |
2978 | Tells an \s-1SV\s0 that it is a string and disables all other \s-1OK\s0 bits. | |
2979 | Will also turn off the \s-1UTF\-8\s0 status. | |
2980 | .Sp | |
2981 | .Vb 1 | |
2982 | \& void SvPOK_only(SV* sv) | |
2983 | .Ve | |
2984 | .IP "SvPOK_only_UTF8" 8 | |
2985 | .IX Xref "SvPOK_only_UTF8" | |
2986 | .IX Item "SvPOK_only_UTF8" | |
2987 | Tells an \s-1SV\s0 that it is a string and disables all other \s-1OK\s0 bits, | |
2988 | and leaves the \s-1UTF\-8\s0 status as it was. | |
2989 | .Sp | |
2990 | .Vb 1 | |
2991 | \& void SvPOK_only_UTF8(SV* sv) | |
2992 | .Ve | |
2993 | .IP "SvPV" 8 | |
2994 | .IX Xref "SvPV" | |
2995 | .IX Item "SvPV" | |
2996 | Returns a pointer to the string in the \s-1SV\s0, or a stringified form of | |
2997 | the \s-1SV\s0 if the \s-1SV\s0 does not contain a string. The \s-1SV\s0 may cache the | |
2998 | stringified version becoming \f(CW\*(C`SvPOK\*(C'\fR. Handles 'get' magic. See also | |
2999 | \&\f(CW\*(C`SvPVx\*(C'\fR for a version which guarantees to evaluate sv only once. | |
3000 | .Sp | |
3001 | .Vb 1 | |
3002 | \& char* SvPV(SV* sv, STRLEN len) | |
3003 | .Ve | |
3004 | .IP "SvPVbyte" 8 | |
3005 | .IX Xref "SvPVbyte" | |
3006 | .IX Item "SvPVbyte" | |
3007 | Like \f(CW\*(C`SvPV\*(C'\fR, but converts sv to byte representation first if necessary. | |
3008 | .Sp | |
3009 | .Vb 1 | |
3010 | \& char* SvPVbyte(SV* sv, STRLEN len) | |
3011 | .Ve | |
3012 | .IP "SvPVbytex" 8 | |
3013 | .IX Xref "SvPVbytex" | |
3014 | .IX Item "SvPVbytex" | |
3015 | Like \f(CW\*(C`SvPV\*(C'\fR, but converts sv to byte representation first if necessary. | |
3016 | Guarantees to evaluate sv only once; use the more efficient \f(CW\*(C`SvPVbyte\*(C'\fR | |
3017 | otherwise. | |
3018 | .Sp | |
3019 | .Vb 1 | |
3020 | \& char* SvPVbytex(SV* sv, STRLEN len) | |
3021 | .Ve | |
3022 | .IP "SvPVbytex_force" 8 | |
3023 | .IX Xref "SvPVbytex_force" | |
3024 | .IX Item "SvPVbytex_force" | |
3025 | Like \f(CW\*(C`SvPV_force\*(C'\fR, but converts sv to byte representation first if necessary. | |
3026 | Guarantees to evaluate sv only once; use the more efficient \f(CW\*(C`SvPVbyte_force\*(C'\fR | |
3027 | otherwise. | |
3028 | .Sp | |
3029 | .Vb 1 | |
3030 | \& char* SvPVbytex_force(SV* sv, STRLEN len) | |
3031 | .Ve | |
3032 | .IP "SvPVbyte_force" 8 | |
3033 | .IX Xref "SvPVbyte_force" | |
3034 | .IX Item "SvPVbyte_force" | |
3035 | Like \f(CW\*(C`SvPV_force\*(C'\fR, but converts sv to byte representation first if necessary. | |
3036 | .Sp | |
3037 | .Vb 1 | |
3038 | \& char* SvPVbyte_force(SV* sv, STRLEN len) | |
3039 | .Ve | |
3040 | .IP "SvPVbyte_nolen" 8 | |
3041 | .IX Xref "SvPVbyte_nolen" | |
3042 | .IX Item "SvPVbyte_nolen" | |
3043 | Like \f(CW\*(C`SvPV_nolen\*(C'\fR, but converts sv to byte representation first if necessary. | |
3044 | .Sp | |
3045 | .Vb 1 | |
3046 | \& char* SvPVbyte_nolen(SV* sv) | |
3047 | .Ve | |
3048 | .IP "SvPVutf8" 8 | |
3049 | .IX Xref "SvPVutf8" | |
3050 | .IX Item "SvPVutf8" | |
3051 | Like \f(CW\*(C`SvPV\*(C'\fR, but converts sv to utf8 first if necessary. | |
3052 | .Sp | |
3053 | .Vb 1 | |
3054 | \& char* SvPVutf8(SV* sv, STRLEN len) | |
3055 | .Ve | |
3056 | .IP "SvPVutf8x" 8 | |
3057 | .IX Xref "SvPVutf8x" | |
3058 | .IX Item "SvPVutf8x" | |
3059 | Like \f(CW\*(C`SvPV\*(C'\fR, but converts sv to utf8 first if necessary. | |
3060 | Guarantees to evaluate sv only once; use the more efficient \f(CW\*(C`SvPVutf8\*(C'\fR | |
3061 | otherwise. | |
3062 | .Sp | |
3063 | .Vb 1 | |
3064 | \& char* SvPVutf8x(SV* sv, STRLEN len) | |
3065 | .Ve | |
3066 | .IP "SvPVutf8x_force" 8 | |
3067 | .IX Xref "SvPVutf8x_force" | |
3068 | .IX Item "SvPVutf8x_force" | |
3069 | Like \f(CW\*(C`SvPV_force\*(C'\fR, but converts sv to utf8 first if necessary. | |
3070 | Guarantees to evaluate sv only once; use the more efficient \f(CW\*(C`SvPVutf8_force\*(C'\fR | |
3071 | otherwise. | |
3072 | .Sp | |
3073 | .Vb 1 | |
3074 | \& char* SvPVutf8x_force(SV* sv, STRLEN len) | |
3075 | .Ve | |
3076 | .IP "SvPVutf8_force" 8 | |
3077 | .IX Xref "SvPVutf8_force" | |
3078 | .IX Item "SvPVutf8_force" | |
3079 | Like \f(CW\*(C`SvPV_force\*(C'\fR, but converts sv to utf8 first if necessary. | |
3080 | .Sp | |
3081 | .Vb 1 | |
3082 | \& char* SvPVutf8_force(SV* sv, STRLEN len) | |
3083 | .Ve | |
3084 | .IP "SvPVutf8_nolen" 8 | |
3085 | .IX Xref "SvPVutf8_nolen" | |
3086 | .IX Item "SvPVutf8_nolen" | |
3087 | Like \f(CW\*(C`SvPV_nolen\*(C'\fR, but converts sv to utf8 first if necessary. | |
3088 | .Sp | |
3089 | .Vb 1 | |
3090 | \& char* SvPVutf8_nolen(SV* sv) | |
3091 | .Ve | |
3092 | .IP "SvPVX" 8 | |
3093 | .IX Xref "SvPVX" | |
3094 | .IX Item "SvPVX" | |
3095 | Returns a pointer to the physical string in the \s-1SV\s0. The \s-1SV\s0 must contain a | |
3096 | string. | |
3097 | .Sp | |
3098 | .Vb 1 | |
3099 | \& char* SvPVX(SV* sv) | |
3100 | .Ve | |
3101 | .IP "SvPVx" 8 | |
3102 | .IX Xref "SvPVx" | |
3103 | .IX Item "SvPVx" | |
3104 | A version of \f(CW\*(C`SvPV\*(C'\fR which guarantees to evaluate sv only once. | |
3105 | .Sp | |
3106 | .Vb 1 | |
3107 | \& char* SvPVx(SV* sv, STRLEN len) | |
3108 | .Ve | |
3109 | .IP "SvPV_force" 8 | |
3110 | .IX Xref "SvPV_force" | |
3111 | .IX Item "SvPV_force" | |
3112 | Like \f(CW\*(C`SvPV\*(C'\fR but will force the \s-1SV\s0 into containing just a string | |
3113 | (\f(CW\*(C`SvPOK_only\*(C'\fR). You want force if you are going to update the \f(CW\*(C`SvPVX\*(C'\fR | |
3114 | directly. | |
3115 | .Sp | |
3116 | .Vb 1 | |
3117 | \& char* SvPV_force(SV* sv, STRLEN len) | |
3118 | .Ve | |
3119 | .IP "SvPV_force_nomg" 8 | |
3120 | .IX Xref "SvPV_force_nomg" | |
3121 | .IX Item "SvPV_force_nomg" | |
3122 | Like \f(CW\*(C`SvPV\*(C'\fR but will force the \s-1SV\s0 into containing just a string | |
3123 | (\f(CW\*(C`SvPOK_only\*(C'\fR). You want force if you are going to update the \f(CW\*(C`SvPVX\*(C'\fR | |
3124 | directly. Doesn't process magic. | |
3125 | .Sp | |
3126 | .Vb 1 | |
3127 | \& char* SvPV_force_nomg(SV* sv, STRLEN len) | |
3128 | .Ve | |
3129 | .IP "SvPV_nolen" 8 | |
3130 | .IX Xref "SvPV_nolen" | |
3131 | .IX Item "SvPV_nolen" | |
3132 | Returns a pointer to the string in the \s-1SV\s0, or a stringified form of | |
3133 | the \s-1SV\s0 if the \s-1SV\s0 does not contain a string. The \s-1SV\s0 may cache the | |
3134 | stringified form becoming \f(CW\*(C`SvPOK\*(C'\fR. Handles 'get' magic. | |
3135 | .Sp | |
3136 | .Vb 1 | |
3137 | \& char* SvPV_nolen(SV* sv) | |
3138 | .Ve | |
3139 | .IP "SvPV_set" 8 | |
3140 | .IX Xref "SvPV_set" | |
3141 | .IX Item "SvPV_set" | |
3142 | Set the value of the \s-1PV\s0 pointer in sv to val. See \f(CW\*(C`SvIV_set\*(C'\fR. | |
3143 | .Sp | |
3144 | .Vb 1 | |
3145 | \& void SvPV_set(SV* sv, char* val) | |
3146 | .Ve | |
3147 | .IP "SvREFCNT" 8 | |
3148 | .IX Xref "SvREFCNT" | |
3149 | .IX Item "SvREFCNT" | |
3150 | Returns the value of the object's reference count. | |
3151 | .Sp | |
3152 | .Vb 1 | |
3153 | \& U32 SvREFCNT(SV* sv) | |
3154 | .Ve | |
3155 | .IP "SvREFCNT_dec" 8 | |
3156 | .IX Xref "SvREFCNT_dec" | |
3157 | .IX Item "SvREFCNT_dec" | |
3158 | Decrements the reference count of the given \s-1SV\s0. | |
3159 | .Sp | |
3160 | .Vb 1 | |
3161 | \& void SvREFCNT_dec(SV* sv) | |
3162 | .Ve | |
3163 | .IP "SvREFCNT_inc" 8 | |
3164 | .IX Xref "SvREFCNT_inc" | |
3165 | .IX Item "SvREFCNT_inc" | |
3166 | Increments the reference count of the given \s-1SV\s0. | |
3167 | .Sp | |
3168 | .Vb 1 | |
3169 | \& SV* SvREFCNT_inc(SV* sv) | |
3170 | .Ve | |
3171 | .IP "SvROK" 8 | |
3172 | .IX Xref "SvROK" | |
3173 | .IX Item "SvROK" | |
3174 | Tests if the \s-1SV\s0 is an \s-1RV\s0. | |
3175 | .Sp | |
3176 | .Vb 1 | |
3177 | \& bool SvROK(SV* sv) | |
3178 | .Ve | |
3179 | .IP "SvROK_off" 8 | |
3180 | .IX Xref "SvROK_off" | |
3181 | .IX Item "SvROK_off" | |
3182 | Unsets the \s-1RV\s0 status of an \s-1SV\s0. | |
3183 | .Sp | |
3184 | .Vb 1 | |
3185 | \& void SvROK_off(SV* sv) | |
3186 | .Ve | |
3187 | .IP "SvROK_on" 8 | |
3188 | .IX Xref "SvROK_on" | |
3189 | .IX Item "SvROK_on" | |
3190 | Tells an \s-1SV\s0 that it is an \s-1RV\s0. | |
3191 | .Sp | |
3192 | .Vb 1 | |
3193 | \& void SvROK_on(SV* sv) | |
3194 | .Ve | |
3195 | .IP "SvRV" 8 | |
3196 | .IX Xref "SvRV" | |
3197 | .IX Item "SvRV" | |
3198 | Dereferences an \s-1RV\s0 to return the \s-1SV\s0. | |
3199 | .Sp | |
3200 | .Vb 1 | |
3201 | \& SV* SvRV(SV* sv) | |
3202 | .Ve | |
3203 | .IP "SvRV_set" 8 | |
3204 | .IX Xref "SvRV_set" | |
3205 | .IX Item "SvRV_set" | |
3206 | Set the value of the \s-1RV\s0 pointer in sv to val. See \f(CW\*(C`SvIV_set\*(C'\fR. | |
3207 | .Sp | |
3208 | .Vb 1 | |
3209 | \& void SvRV_set(SV* sv, SV* val) | |
3210 | .Ve | |
3211 | .IP "SvSTASH" 8 | |
3212 | .IX Xref "SvSTASH" | |
3213 | .IX Item "SvSTASH" | |
3214 | Returns the stash of the \s-1SV\s0. | |
3215 | .Sp | |
3216 | .Vb 1 | |
3217 | \& HV* SvSTASH(SV* sv) | |
3218 | .Ve | |
3219 | .IP "SvSTASH_set" 8 | |
3220 | .IX Xref "SvSTASH_set" | |
3221 | .IX Item "SvSTASH_set" | |
3222 | Set the value of the \s-1STASH\s0 pointer in sv to val. See \f(CW\*(C`SvIV_set\*(C'\fR. | |
3223 | .Sp | |
3224 | .Vb 1 | |
3225 | \& void SvSTASH_set(SV* sv, STASH* val) | |
3226 | .Ve | |
3227 | .IP "SvTAINT" 8 | |
3228 | .IX Xref "SvTAINT" | |
3229 | .IX Item "SvTAINT" | |
3230 | Taints an \s-1SV\s0 if tainting is enabled. | |
3231 | .Sp | |
3232 | .Vb 1 | |
3233 | \& void SvTAINT(SV* sv) | |
3234 | .Ve | |
3235 | .IP "SvTAINTED" 8 | |
3236 | .IX Xref "SvTAINTED" | |
3237 | .IX Item "SvTAINTED" | |
3238 | Checks to see if an \s-1SV\s0 is tainted. Returns \s-1TRUE\s0 if it is, \s-1FALSE\s0 if | |
3239 | not. | |
3240 | .Sp | |
3241 | .Vb 1 | |
3242 | \& bool SvTAINTED(SV* sv) | |
3243 | .Ve | |
3244 | .IP "SvTAINTED_off" 8 | |
3245 | .IX Xref "SvTAINTED_off" | |
3246 | .IX Item "SvTAINTED_off" | |
3247 | Untaints an \s-1SV\s0. Be \fIvery\fR careful with this routine, as it short-circuits | |
3248 | some of Perl's fundamental security features. \s-1XS\s0 module authors should not | |
3249 | use this function unless they fully understand all the implications of | |
3250 | unconditionally untainting the value. Untainting should be done in the | |
3251 | standard perl fashion, via a carefully crafted regexp, rather than directly | |
3252 | untainting variables. | |
3253 | .Sp | |
3254 | .Vb 1 | |
3255 | \& void SvTAINTED_off(SV* sv) | |
3256 | .Ve | |
3257 | .IP "SvTAINTED_on" 8 | |
3258 | .IX Xref "SvTAINTED_on" | |
3259 | .IX Item "SvTAINTED_on" | |
3260 | Marks an \s-1SV\s0 as tainted if tainting is enabled. | |
3261 | .Sp | |
3262 | .Vb 1 | |
3263 | \& void SvTAINTED_on(SV* sv) | |
3264 | .Ve | |
3265 | .IP "SvTRUE" 8 | |
3266 | .IX Xref "SvTRUE" | |
3267 | .IX Item "SvTRUE" | |
3268 | Returns a boolean indicating whether Perl would evaluate the \s-1SV\s0 as true or | |
3269 | false, defined or undefined. Does not handle 'get' magic. | |
3270 | .Sp | |
3271 | .Vb 1 | |
3272 | \& bool SvTRUE(SV* sv) | |
3273 | .Ve | |
3274 | .IP "SvTYPE" 8 | |
3275 | .IX Xref "SvTYPE" | |
3276 | .IX Item "SvTYPE" | |
3277 | Returns the type of the \s-1SV\s0. See \f(CW\*(C`svtype\*(C'\fR. | |
3278 | .Sp | |
3279 | .Vb 1 | |
3280 | \& svtype SvTYPE(SV* sv) | |
3281 | .Ve | |
3282 | .IP "SvUOK" 8 | |
3283 | .IX Xref "SvUOK" | |
3284 | .IX Item "SvUOK" | |
3285 | Returns a boolean indicating whether the \s-1SV\s0 contains an unsigned integer. | |
3286 | .Sp | |
3287 | .Vb 1 | |
3288 | \& void SvUOK(SV* sv) | |
3289 | .Ve | |
3290 | .IP "SvUPGRADE" 8 | |
3291 | .IX Xref "SvUPGRADE" | |
3292 | .IX Item "SvUPGRADE" | |
3293 | Used to upgrade an \s-1SV\s0 to a more complex form. Uses \f(CW\*(C`sv_upgrade\*(C'\fR to | |
3294 | perform the upgrade if necessary. See \f(CW\*(C`svtype\*(C'\fR. | |
3295 | .Sp | |
3296 | .Vb 1 | |
3297 | \& void SvUPGRADE(SV* sv, svtype type) | |
3298 | .Ve | |
3299 | .IP "SvUTF8" 8 | |
3300 | .IX Xref "SvUTF8" | |
3301 | .IX Item "SvUTF8" | |
3302 | Returns a boolean indicating whether the \s-1SV\s0 contains \s-1UTF\-8\s0 encoded data. | |
3303 | .Sp | |
3304 | .Vb 1 | |
3305 | \& bool SvUTF8(SV* sv) | |
3306 | .Ve | |
3307 | .IP "SvUTF8_off" 8 | |
3308 | .IX Xref "SvUTF8_off" | |
3309 | .IX Item "SvUTF8_off" | |
3310 | Unsets the \s-1UTF\-8\s0 status of an \s-1SV\s0. | |
3311 | .Sp | |
3312 | .Vb 1 | |
3313 | \& void SvUTF8_off(SV *sv) | |
3314 | .Ve | |
3315 | .IP "SvUTF8_on" 8 | |
3316 | .IX Xref "SvUTF8_on" | |
3317 | .IX Item "SvUTF8_on" | |
3318 | Turn on the \s-1UTF\-8\s0 status of an \s-1SV\s0 (the data is not changed, just the flag). | |
3319 | Do not use frivolously. | |
3320 | .Sp | |
3321 | .Vb 1 | |
3322 | \& void SvUTF8_on(SV *sv) | |
3323 | .Ve | |
3324 | .IP "SvUV" 8 | |
3325 | .IX Xref "SvUV" | |
3326 | .IX Item "SvUV" | |
3327 | Coerces the given \s-1SV\s0 to an unsigned integer and returns it. See \f(CW\*(C`SvUVx\*(C'\fR | |
3328 | for a version which guarantees to evaluate sv only once. | |
3329 | .Sp | |
3330 | .Vb 1 | |
3331 | \& UV SvUV(SV* sv) | |
3332 | .Ve | |
3333 | .IP "SvUVX" 8 | |
3334 | .IX Xref "SvUVX" | |
3335 | .IX Item "SvUVX" | |
3336 | Returns the raw value in the \s-1SV\s0's \s-1UV\s0 slot, without checks or conversions. | |
3337 | Only use when you are sure SvIOK is true. See also \f(CW\*(C`SvUV()\*(C'\fR. | |
3338 | .Sp | |
3339 | .Vb 1 | |
3340 | \& UV SvUVX(SV* sv) | |
3341 | .Ve | |
3342 | .IP "SvUVx" 8 | |
3343 | .IX Xref "SvUVx" | |
3344 | .IX Item "SvUVx" | |
3345 | Coerces the given \s-1SV\s0 to an unsigned integer and returns it. Guarantees to | |
3346 | evaluate sv only once. Use the more efficient \f(CW\*(C`SvUV\*(C'\fR otherwise. | |
3347 | .Sp | |
3348 | .Vb 1 | |
3349 | \& UV SvUVx(SV* sv) | |
3350 | .Ve | |
3351 | .IP "SvUV_set" 8 | |
3352 | .IX Xref "SvUV_set" | |
3353 | .IX Item "SvUV_set" | |
3354 | Set the value of the \s-1UV\s0 pointer in sv to val. See \f(CW\*(C`SvIV_set\*(C'\fR. | |
3355 | .Sp | |
3356 | .Vb 1 | |
3357 | \& void SvUV_set(SV* sv, UV val) | |
3358 | .Ve | |
3359 | .IP "sv_2bool" 8 | |
3360 | .IX Xref "sv_2bool" | |
3361 | .IX Item "sv_2bool" | |
3362 | This function is only called on magical items, and is only used by | |
3363 | \&\fIsv_true()\fR or its macro equivalent. | |
3364 | .Sp | |
3365 | .Vb 1 | |
3366 | \& bool sv_2bool(SV* sv) | |
3367 | .Ve | |
3368 | .IP "sv_2cv" 8 | |
3369 | .IX Xref "sv_2cv" | |
3370 | .IX Item "sv_2cv" | |
3371 | Using various gambits, try to get a \s-1CV\s0 from an \s-1SV\s0; in addition, try if | |
3372 | possible to set \f(CW*st\fR and \f(CW*gvp\fR to the stash and \s-1GV\s0 associated with it. | |
3373 | .Sp | |
3374 | .Vb 1 | |
3375 | \& CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref) | |
3376 | .Ve | |
3377 | .IP "sv_2io" 8 | |
3378 | .IX Xref "sv_2io" | |
3379 | .IX Item "sv_2io" | |
3380 | Using various gambits, try to get an \s-1IO\s0 from an \s-1SV:\s0 the \s-1IO\s0 slot if its a | |
3381 | \&\s-1GV\s0; or the recursive result if we're an \s-1RV\s0; or the \s-1IO\s0 slot of the symbol | |
3382 | named after the \s-1PV\s0 if we're a string. | |
3383 | .Sp | |
3384 | .Vb 1 | |
3385 | \& IO* sv_2io(SV* sv) | |
3386 | .Ve | |
3387 | .IP "sv_2iv" 8 | |
3388 | .IX Xref "sv_2iv" | |
3389 | .IX Item "sv_2iv" | |
3390 | Return the integer value of an \s-1SV\s0, doing any necessary string conversion, | |
3391 | magic etc. Normally used via the \f(CW\*(C`SvIV(sv)\*(C'\fR and \f(CW\*(C`SvIVx(sv)\*(C'\fR macros. | |
3392 | .Sp | |
3393 | .Vb 1 | |
3394 | \& IV sv_2iv(SV* sv) | |
3395 | .Ve | |
3396 | .IP "sv_2mortal" 8 | |
3397 | .IX Xref "sv_2mortal" | |
3398 | .IX Item "sv_2mortal" | |
3399 | Marks an existing \s-1SV\s0 as mortal. The \s-1SV\s0 will be destroyed \*(L"soon\*(R", either | |
3400 | by an explicit call to \s-1FREETMPS\s0, or by an implicit call at places such as | |
3401 | statement boundaries. \fISvTEMP()\fR is turned on which means that the \s-1SV\s0's | |
3402 | string buffer can be \*(L"stolen\*(R" if this \s-1SV\s0 is copied. See also \f(CW\*(C`sv_newmortal\*(C'\fR | |
3403 | and \f(CW\*(C`sv_mortalcopy\*(C'\fR. | |
3404 | .Sp | |
3405 | .Vb 1 | |
3406 | \& SV* sv_2mortal(SV* sv) | |
3407 | .Ve | |
3408 | .IP "sv_2nv" 8 | |
3409 | .IX Xref "sv_2nv" | |
3410 | .IX Item "sv_2nv" | |
3411 | Return the num value of an \s-1SV\s0, doing any necessary string or integer | |
3412 | conversion, magic etc. Normally used via the \f(CW\*(C`SvNV(sv)\*(C'\fR and \f(CW\*(C`SvNVx(sv)\*(C'\fR | |
3413 | macros. | |
3414 | .Sp | |
3415 | .Vb 1 | |
3416 | \& NV sv_2nv(SV* sv) | |
3417 | .Ve | |
3418 | .IP "sv_2pvbyte" 8 | |
3419 | .IX Xref "sv_2pvbyte" | |
3420 | .IX Item "sv_2pvbyte" | |
3421 | Return a pointer to the byte-encoded representation of the \s-1SV\s0, and set *lp | |
3422 | to its length. May cause the \s-1SV\s0 to be downgraded from \s-1UTF\-8\s0 as a | |
3423 | side\-effect. | |
3424 | .Sp | |
3425 | Usually accessed via the \f(CW\*(C`SvPVbyte\*(C'\fR macro. | |
3426 | .Sp | |
3427 | .Vb 1 | |
3428 | \& char* sv_2pvbyte(SV* sv, STRLEN* lp) | |
3429 | .Ve | |
3430 | .IP "sv_2pvbyte_nolen" 8 | |
3431 | .IX Xref "sv_2pvbyte_nolen" | |
3432 | .IX Item "sv_2pvbyte_nolen" | |
3433 | Return a pointer to the byte-encoded representation of the \s-1SV\s0. | |
3434 | May cause the \s-1SV\s0 to be downgraded from \s-1UTF\-8\s0 as a side\-effect. | |
3435 | .Sp | |
3436 | Usually accessed via the \f(CW\*(C`SvPVbyte_nolen\*(C'\fR macro. | |
3437 | .Sp | |
3438 | .Vb 1 | |
3439 | \& char* sv_2pvbyte_nolen(SV* sv) | |
3440 | .Ve | |
3441 | .IP "sv_2pvutf8" 8 | |
3442 | .IX Xref "sv_2pvutf8" | |
3443 | .IX Item "sv_2pvutf8" | |
3444 | Return a pointer to the UTF\-8\-encoded representation of the \s-1SV\s0, and set *lp | |
3445 | to its length. May cause the \s-1SV\s0 to be upgraded to \s-1UTF\-8\s0 as a side\-effect. | |
3446 | .Sp | |
3447 | Usually accessed via the \f(CW\*(C`SvPVutf8\*(C'\fR macro. | |
3448 | .Sp | |
3449 | .Vb 1 | |
3450 | \& char* sv_2pvutf8(SV* sv, STRLEN* lp) | |
3451 | .Ve | |
3452 | .IP "sv_2pvutf8_nolen" 8 | |
3453 | .IX Xref "sv_2pvutf8_nolen" | |
3454 | .IX Item "sv_2pvutf8_nolen" | |
3455 | Return a pointer to the UTF\-8\-encoded representation of the \s-1SV\s0. | |
3456 | May cause the \s-1SV\s0 to be upgraded to \s-1UTF\-8\s0 as a side\-effect. | |
3457 | .Sp | |
3458 | Usually accessed via the \f(CW\*(C`SvPVutf8_nolen\*(C'\fR macro. | |
3459 | .Sp | |
3460 | .Vb 1 | |
3461 | \& char* sv_2pvutf8_nolen(SV* sv) | |
3462 | .Ve | |
3463 | .IP "sv_2pv_flags" 8 | |
3464 | .IX Xref "sv_2pv_flags" | |
3465 | .IX Item "sv_2pv_flags" | |
3466 | Returns a pointer to the string value of an \s-1SV\s0, and sets *lp to its length. | |
3467 | If flags includes \s-1SV_GMAGIC\s0, does an \fImg_get()\fR first. Coerces sv to a string | |
3468 | if necessary. | |
3469 | Normally invoked via the \f(CW\*(C`SvPV_flags\*(C'\fR macro. \f(CW\*(C`sv_2pv()\*(C'\fR and \f(CW\*(C`sv_2pv_nomg\*(C'\fR | |
3470 | usually end up here too. | |
3471 | .Sp | |
3472 | .Vb 1 | |
3473 | \& char* sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags) | |
3474 | .Ve | |
3475 | .IP "sv_2pv_nolen" 8 | |
3476 | .IX Xref "sv_2pv_nolen" | |
3477 | .IX Item "sv_2pv_nolen" | |
3478 | Like \f(CW\*(C`sv_2pv()\*(C'\fR, but doesn't return the length too. You should usually | |
3479 | use the macro wrapper \f(CW\*(C`SvPV_nolen(sv)\*(C'\fR instead. | |
3480 | char* sv_2pv_nolen(SV* sv) | |
3481 | .IP "sv_2uv" 8 | |
3482 | .IX Xref "sv_2uv" | |
3483 | .IX Item "sv_2uv" | |
3484 | Return the unsigned integer value of an \s-1SV\s0, doing any necessary string | |
3485 | conversion, magic etc. Normally used via the \f(CW\*(C`SvUV(sv)\*(C'\fR and \f(CW\*(C`SvUVx(sv)\*(C'\fR | |
3486 | macros. | |
3487 | .Sp | |
3488 | .Vb 1 | |
3489 | \& UV sv_2uv(SV* sv) | |
3490 | .Ve | |
3491 | .IP "sv_backoff" 8 | |
3492 | .IX Xref "sv_backoff" | |
3493 | .IX Item "sv_backoff" | |
3494 | Remove any string offset. You should normally use the \f(CW\*(C`SvOOK_off\*(C'\fR macro | |
3495 | wrapper instead. | |
3496 | .Sp | |
3497 | .Vb 1 | |
3498 | \& int sv_backoff(SV* sv) | |
3499 | .Ve | |
3500 | .IP "sv_bless" 8 | |
3501 | .IX Xref "sv_bless" | |
3502 | .IX Item "sv_bless" | |
3503 | Blesses an \s-1SV\s0 into a specified package. The \s-1SV\s0 must be an \s-1RV\s0. The package | |
3504 | must be designated by its stash (see \f(CW\*(C`gv_stashpv()\*(C'\fR). The reference count | |
3505 | of the \s-1SV\s0 is unaffected. | |
3506 | .Sp | |
3507 | .Vb 1 | |
3508 | \& SV* sv_bless(SV* sv, HV* stash) | |
3509 | .Ve | |
3510 | .IP "sv_catpv" 8 | |
3511 | .IX Xref "sv_catpv" | |
3512 | .IX Item "sv_catpv" | |
3513 | Concatenates the string onto the end of the string which is in the \s-1SV\s0. | |
3514 | If the \s-1SV\s0 has the \s-1UTF\-8\s0 status set, then the bytes appended should be | |
3515 | valid \s-1UTF\-8\s0. Handles 'get' magic, but not 'set' magic. See \f(CW\*(C`sv_catpv_mg\*(C'\fR. | |
3516 | .Sp | |
3517 | .Vb 1 | |
3518 | \& void sv_catpv(SV* sv, const char* ptr) | |
3519 | .Ve | |
3520 | .IP "sv_catpvf" 8 | |
3521 | .IX Xref "sv_catpvf" | |
3522 | .IX Item "sv_catpvf" | |
3523 | Processes its arguments like \f(CW\*(C`sprintf\*(C'\fR and appends the formatted | |
3524 | output to an \s-1SV\s0. If the appended data contains \*(L"wide\*(R" characters | |
3525 | (including, but not limited to, SVs with a \s-1UTF\-8\s0 \s-1PV\s0 formatted with \f(CW%s\fR, | |
3526 | and characters >255 formatted with \f(CW%c\fR), the original \s-1SV\s0 might get | |
3527 | upgraded to \s-1UTF\-8\s0. Handles 'get' magic, but not 'set' magic. See | |
3528 | \&\f(CW\*(C`sv_catpvf_mg\*(C'\fR. If the original \s-1SV\s0 was \s-1UTF\-8\s0, the pattern should be | |
3529 | valid \s-1UTF\-8\s0; if the original \s-1SV\s0 was bytes, the pattern should be too. | |
3530 | .Sp | |
3531 | .Vb 1 | |
3532 | \& void sv_catpvf(SV* sv, const char* pat, ...) | |
3533 | .Ve | |
3534 | .IP "sv_catpvf_mg" 8 | |
3535 | .IX Xref "sv_catpvf_mg" | |
3536 | .IX Item "sv_catpvf_mg" | |
3537 | Like \f(CW\*(C`sv_catpvf\*(C'\fR, but also handles 'set' magic. | |
3538 | .Sp | |
3539 | .Vb 1 | |
3540 | \& void sv_catpvf_mg(SV *sv, const char* pat, ...) | |
3541 | .Ve | |
3542 | .IP "sv_catpvn" 8 | |
3543 | .IX Xref "sv_catpvn" | |
3544 | .IX Item "sv_catpvn" | |
3545 | Concatenates the string onto the end of the string which is in the \s-1SV\s0. The | |
3546 | \&\f(CW\*(C`len\*(C'\fR indicates number of bytes to copy. If the \s-1SV\s0 has the \s-1UTF\-8\s0 | |
3547 | status set, then the bytes appended should be valid \s-1UTF\-8\s0. | |
3548 | Handles 'get' magic, but not 'set' magic. See \f(CW\*(C`sv_catpvn_mg\*(C'\fR. | |
3549 | .Sp | |
3550 | .Vb 1 | |
3551 | \& void sv_catpvn(SV* sv, const char* ptr, STRLEN len) | |
3552 | .Ve | |
3553 | .IP "sv_catpvn_flags" 8 | |
3554 | .IX Xref "sv_catpvn_flags" | |
3555 | .IX Item "sv_catpvn_flags" | |
3556 | Concatenates the string onto the end of the string which is in the \s-1SV\s0. The | |
3557 | \&\f(CW\*(C`len\*(C'\fR indicates number of bytes to copy. If the \s-1SV\s0 has the \s-1UTF\-8\s0 | |
3558 | status set, then the bytes appended should be valid \s-1UTF\-8\s0. | |
3559 | If \f(CW\*(C`flags\*(C'\fR has \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, will \f(CW\*(C`mg_get\*(C'\fR on \f(CW\*(C`dsv\*(C'\fR if | |
3560 | appropriate, else not. \f(CW\*(C`sv_catpvn\*(C'\fR and \f(CW\*(C`sv_catpvn_nomg\*(C'\fR are implemented | |
3561 | in terms of this function. | |
3562 | .Sp | |
3563 | .Vb 1 | |
3564 | \& void sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags) | |
3565 | .Ve | |
3566 | .IP "sv_catpvn_mg" 8 | |
3567 | .IX Xref "sv_catpvn_mg" | |
3568 | .IX Item "sv_catpvn_mg" | |
3569 | Like \f(CW\*(C`sv_catpvn\*(C'\fR, but also handles 'set' magic. | |
3570 | .Sp | |
3571 | .Vb 1 | |
3572 | \& void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len) | |
3573 | .Ve | |
3574 | .IP "sv_catpvn_nomg" 8 | |
3575 | .IX Xref "sv_catpvn_nomg" | |
3576 | .IX Item "sv_catpvn_nomg" | |
3577 | Like \f(CW\*(C`sv_catpvn\*(C'\fR but doesn't process magic. | |
3578 | .Sp | |
3579 | .Vb 1 | |
3580 | \& void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len) | |
3581 | .Ve | |
3582 | .IP "sv_catpv_mg" 8 | |
3583 | .IX Xref "sv_catpv_mg" | |
3584 | .IX Item "sv_catpv_mg" | |
3585 | Like \f(CW\*(C`sv_catpv\*(C'\fR, but also handles 'set' magic. | |
3586 | .Sp | |
3587 | .Vb 1 | |
3588 | \& void sv_catpv_mg(SV *sv, const char *ptr) | |
3589 | .Ve | |
3590 | .IP "sv_catsv" 8 | |
3591 | .IX Xref "sv_catsv" | |
3592 | .IX Item "sv_catsv" | |
3593 | Concatenates the string from \s-1SV\s0 \f(CW\*(C`ssv\*(C'\fR onto the end of the string in | |
3594 | \&\s-1SV\s0 \f(CW\*(C`dsv\*(C'\fR. Modifies \f(CW\*(C`dsv\*(C'\fR but not \f(CW\*(C`ssv\*(C'\fR. Handles 'get' magic, but | |
3595 | not 'set' magic. See \f(CW\*(C`sv_catsv_mg\*(C'\fR. | |
3596 | .Sp | |
3597 | .Vb 1 | |
3598 | \& void sv_catsv(SV* dsv, SV* ssv) | |
3599 | .Ve | |
3600 | .IP "sv_catsv_flags" 8 | |
3601 | .IX Xref "sv_catsv_flags" | |
3602 | .IX Item "sv_catsv_flags" | |
3603 | Concatenates the string from \s-1SV\s0 \f(CW\*(C`ssv\*(C'\fR onto the end of the string in | |
3604 | \&\s-1SV\s0 \f(CW\*(C`dsv\*(C'\fR. Modifies \f(CW\*(C`dsv\*(C'\fR but not \f(CW\*(C`ssv\*(C'\fR. If \f(CW\*(C`flags\*(C'\fR has \f(CW\*(C`SV_GMAGIC\*(C'\fR | |
3605 | bit set, will \f(CW\*(C`mg_get\*(C'\fR on the SVs if appropriate, else not. \f(CW\*(C`sv_catsv\*(C'\fR | |
3606 | and \f(CW\*(C`sv_catsv_nomg\*(C'\fR are implemented in terms of this function. | |
3607 | .Sp | |
3608 | .Vb 1 | |
3609 | \& void sv_catsv_flags(SV* dsv, SV* ssv, I32 flags) | |
3610 | .Ve | |
3611 | .IP "sv_catsv_mg" 8 | |
3612 | .IX Xref "sv_catsv_mg" | |
3613 | .IX Item "sv_catsv_mg" | |
3614 | Like \f(CW\*(C`sv_catsv\*(C'\fR, but also handles 'set' magic. | |
3615 | .Sp | |
3616 | .Vb 1 | |
3617 | \& void sv_catsv_mg(SV *dstr, SV *sstr) | |
3618 | .Ve | |
3619 | .IP "sv_catsv_nomg" 8 | |
3620 | .IX Xref "sv_catsv_nomg" | |
3621 | .IX Item "sv_catsv_nomg" | |
3622 | Like \f(CW\*(C`sv_catsv\*(C'\fR but doesn't process magic. | |
3623 | .Sp | |
3624 | .Vb 1 | |
3625 | \& void sv_catsv_nomg(SV* dsv, SV* ssv) | |
3626 | .Ve | |
3627 | .IP "sv_chop" 8 | |
3628 | .IX Xref "sv_chop" | |
3629 | .IX Item "sv_chop" | |
3630 | Efficient removal of characters from the beginning of the string buffer. | |
3631 | SvPOK(sv) must be true and the \f(CW\*(C`ptr\*(C'\fR must be a pointer to somewhere inside | |
3632 | the string buffer. The \f(CW\*(C`ptr\*(C'\fR becomes the first character of the adjusted | |
3633 | string. Uses the \*(L"\s-1OOK\s0 hack\*(R". | |
3634 | Beware: after this function returns, \f(CW\*(C`ptr\*(C'\fR and SvPVX_const(sv) may no longer | |
3635 | refer to the same chunk of data. | |
3636 | .Sp | |
3637 | .Vb 1 | |
3638 | \& void sv_chop(SV* sv, char* ptr) | |
3639 | .Ve | |
3640 | .IP "sv_clear" 8 | |
3641 | .IX Xref "sv_clear" | |
3642 | .IX Item "sv_clear" | |
3643 | Clear an \s-1SV:\s0 call any destructors, free up any memory used by the body, | |
3644 | and free the body itself. The \s-1SV\s0's head is \fInot\fR freed, although | |
3645 | its type is set to all 1's so that it won't inadvertently be assumed | |
3646 | to be live during global destruction etc. | |
3647 | This function should only be called when \s-1REFCNT\s0 is zero. Most of the time | |
3648 | you'll want to call \f(CW\*(C`sv_free()\*(C'\fR (or its macro wrapper \f(CW\*(C`SvREFCNT_dec\*(C'\fR) | |
3649 | instead. | |
3650 | .Sp | |
3651 | .Vb 1 | |
3652 | \& void sv_clear(SV* sv) | |
3653 | .Ve | |
3654 | .IP "sv_cmp" 8 | |
3655 | .IX Xref "sv_cmp" | |
3656 | .IX Item "sv_cmp" | |
3657 | Compares the strings in two SVs. Returns \-1, 0, or 1 indicating whether the | |
3658 | string in \f(CW\*(C`sv1\*(C'\fR is less than, equal to, or greater than the string in | |
3659 | \&\f(CW\*(C`sv2\*(C'\fR. Is \s-1UTF\-8\s0 and 'use bytes' aware, handles get magic, and will | |
3660 | coerce its args to strings if necessary. See also \f(CW\*(C`sv_cmp_locale\*(C'\fR. | |
3661 | .Sp | |
3662 | .Vb 1 | |
3663 | \& I32 sv_cmp(SV* sv1, SV* sv2) | |
3664 | .Ve | |
3665 | .IP "sv_cmp_locale" 8 | |
3666 | .IX Xref "sv_cmp_locale" | |
3667 | .IX Item "sv_cmp_locale" | |
3668 | Compares the strings in two SVs in a locale-aware manner. Is \s-1UTF\-8\s0 and | |
3669 | \&'use bytes' aware, handles get magic, and will coerce its args to strings | |
3670 | if necessary. See also \f(CW\*(C`sv_cmp_locale\*(C'\fR. See also \f(CW\*(C`sv_cmp\*(C'\fR. | |
3671 | .Sp | |
3672 | .Vb 1 | |
3673 | \& I32 sv_cmp_locale(SV* sv1, SV* sv2) | |
3674 | .Ve | |
3675 | .IP "sv_collxfrm" 8 | |
3676 | .IX Xref "sv_collxfrm" | |
3677 | .IX Item "sv_collxfrm" | |
3678 | Add Collate Transform magic to an \s-1SV\s0 if it doesn't already have it. | |
3679 | .Sp | |
3680 | Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the | |
3681 | scalar data of the variable, but transformed to such a format that a normal | |
3682 | memory comparison can be used to compare the data according to the locale | |
3683 | settings. | |
3684 | .Sp | |
3685 | .Vb 1 | |
3686 | \& char* sv_collxfrm(SV* sv, STRLEN* nxp) | |
3687 | .Ve | |
3688 | .IP "sv_copypv" 8 | |
3689 | .IX Xref "sv_copypv" | |
3690 | .IX Item "sv_copypv" | |
3691 | Copies a stringified representation of the source \s-1SV\s0 into the | |
3692 | destination \s-1SV\s0. Automatically performs any necessary mg_get and | |
3693 | coercion of numeric values into strings. Guaranteed to preserve | |
3694 | \&\s-1UTF\-8\s0 flag even from overloaded objects. Similar in nature to | |
3695 | sv_2pv[_flags] but operates directly on an \s-1SV\s0 instead of just the | |
3696 | string. Mostly uses sv_2pv_flags to do its work, except when that | |
3697 | would lose the \s-1UTF\-8\s0'ness of the \s-1PV\s0. | |
3698 | .Sp | |
3699 | .Vb 1 | |
3700 | \& void sv_copypv(SV* dsv, SV* ssv) | |
3701 | .Ve | |
3702 | .IP "sv_dec" 8 | |
3703 | .IX Xref "sv_dec" | |
3704 | .IX Item "sv_dec" | |
3705 | Auto-decrement of the value in the \s-1SV\s0, doing string to numeric conversion | |
3706 | if necessary. Handles 'get' magic. | |
3707 | .Sp | |
3708 | .Vb 1 | |
3709 | \& void sv_dec(SV* sv) | |
3710 | .Ve | |
3711 | .IP "sv_derived_from" 8 | |
3712 | .IX Xref "sv_derived_from" | |
3713 | .IX Item "sv_derived_from" | |
3714 | Returns a boolean indicating whether the \s-1SV\s0 is derived from the specified | |
3715 | class. This is the function that implements \f(CW\*(C`UNIVERSAL::isa\*(C'\fR. It works | |
3716 | for class names as well as for objects. | |
3717 | .Sp | |
3718 | .Vb 1 | |
3719 | \& bool sv_derived_from(SV* sv, const char* name) | |
3720 | .Ve | |
3721 | .IP "sv_eq" 8 | |
3722 | .IX Xref "sv_eq" | |
3723 | .IX Item "sv_eq" | |
3724 | Returns a boolean indicating whether the strings in the two SVs are | |
3725 | identical. Is \s-1UTF\-8\s0 and 'use bytes' aware, handles get magic, and will | |
3726 | coerce its args to strings if necessary. | |
3727 | .Sp | |
3728 | .Vb 1 | |
3729 | \& I32 sv_eq(SV* sv1, SV* sv2) | |
3730 | .Ve | |
3731 | .IP "sv_force_normal" 8 | |
3732 | .IX Xref "sv_force_normal" | |
3733 | .IX Item "sv_force_normal" | |
3734 | Undo various types of fakery on an \s-1SV:\s0 if the \s-1PV\s0 is a shared string, make | |
3735 | a private copy; if we're a ref, stop refing; if we're a glob, downgrade to | |
3736 | an xpvmg. See also \f(CW\*(C`sv_force_normal_flags\*(C'\fR. | |
3737 | .Sp | |
3738 | .Vb 1 | |
3739 | \& void sv_force_normal(SV *sv) | |
3740 | .Ve | |
3741 | .IP "sv_force_normal_flags" 8 | |
3742 | .IX Xref "sv_force_normal_flags" | |
3743 | .IX Item "sv_force_normal_flags" | |
3744 | Undo various types of fakery on an \s-1SV:\s0 if the \s-1PV\s0 is a shared string, make | |
3745 | a private copy; if we're a ref, stop refing; if we're a glob, downgrade to | |
3746 | an xpvmg. The \f(CW\*(C`flags\*(C'\fR parameter gets passed to \f(CW\*(C`sv_unref_flags()\*(C'\fR | |
3747 | when unrefing. \f(CW\*(C`sv_force_normal\*(C'\fR calls this function with flags set to 0. | |
3748 | .Sp | |
3749 | .Vb 1 | |
3750 | \& void sv_force_normal_flags(SV *sv, U32 flags) | |
3751 | .Ve | |
3752 | .IP "sv_free" 8 | |
3753 | .IX Xref "sv_free" | |
3754 | .IX Item "sv_free" | |
3755 | Decrement an \s-1SV\s0's reference count, and if it drops to zero, call | |
3756 | \&\f(CW\*(C`sv_clear\*(C'\fR to invoke destructors and free up any memory used by | |
3757 | the body; finally, deallocate the \s-1SV\s0's head itself. | |
3758 | Normally called via a wrapper macro \f(CW\*(C`SvREFCNT_dec\*(C'\fR. | |
3759 | .Sp | |
3760 | .Vb 1 | |
3761 | \& void sv_free(SV* sv) | |
3762 | .Ve | |
3763 | .IP "sv_gets" 8 | |
3764 | .IX Xref "sv_gets" | |
3765 | .IX Item "sv_gets" | |
3766 | Get a line from the filehandle and store it into the \s-1SV\s0, optionally | |
3767 | appending to the currently-stored string. | |
3768 | .Sp | |
3769 | .Vb 1 | |
3770 | \& char* sv_gets(SV* sv, PerlIO* fp, I32 append) | |
3771 | .Ve | |
3772 | .IP "sv_grow" 8 | |
3773 | .IX Xref "sv_grow" | |
3774 | .IX Item "sv_grow" | |
3775 | Expands the character buffer in the \s-1SV\s0. If necessary, uses \f(CW\*(C`sv_unref\*(C'\fR and | |
3776 | upgrades the \s-1SV\s0 to \f(CW\*(C`SVt_PV\*(C'\fR. Returns a pointer to the character buffer. | |
3777 | Use the \f(CW\*(C`SvGROW\*(C'\fR wrapper instead. | |
3778 | .Sp | |
3779 | .Vb 1 | |
3780 | \& char* sv_grow(SV* sv, STRLEN newlen) | |
3781 | .Ve | |
3782 | .IP "sv_inc" 8 | |
3783 | .IX Xref "sv_inc" | |
3784 | .IX Item "sv_inc" | |
3785 | Auto-increment of the value in the \s-1SV\s0, doing string to numeric conversion | |
3786 | if necessary. Handles 'get' magic. | |
3787 | .Sp | |
3788 | .Vb 1 | |
3789 | \& void sv_inc(SV* sv) | |
3790 | .Ve | |
3791 | .IP "sv_insert" 8 | |
3792 | .IX Xref "sv_insert" | |
3793 | .IX Item "sv_insert" | |
3794 | Inserts a string at the specified offset/length within the \s-1SV\s0. Similar to | |
3795 | the Perl \fIsubstr()\fR function. | |
3796 | .Sp | |
3797 | .Vb 1 | |
3798 | \& void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen) | |
3799 | .Ve | |
3800 | .IP "sv_isa" 8 | |
3801 | .IX Xref "sv_isa" | |
3802 | .IX Item "sv_isa" | |
3803 | Returns a boolean indicating whether the \s-1SV\s0 is blessed into the specified | |
3804 | class. This does not check for subtypes; use \f(CW\*(C`sv_derived_from\*(C'\fR to verify | |
3805 | an inheritance relationship. | |
3806 | .Sp | |
3807 | .Vb 1 | |
3808 | \& int sv_isa(SV* sv, const char* name) | |
3809 | .Ve | |
3810 | .IP "sv_isobject" 8 | |
3811 | .IX Xref "sv_isobject" | |
3812 | .IX Item "sv_isobject" | |
3813 | Returns a boolean indicating whether the \s-1SV\s0 is an \s-1RV\s0 pointing to a blessed | |
3814 | object. If the \s-1SV\s0 is not an \s-1RV\s0, or if the object is not blessed, then this | |
3815 | will return false. | |
3816 | .Sp | |
3817 | .Vb 1 | |
3818 | \& int sv_isobject(SV* sv) | |
3819 | .Ve | |
3820 | .IP "sv_iv" 8 | |
3821 | .IX Xref "sv_iv" | |
3822 | .IX Item "sv_iv" | |
3823 | A private implementation of the \f(CW\*(C`SvIVx\*(C'\fR macro for compilers which can't | |
3824 | cope with complex macro expressions. Always use the macro instead. | |
3825 | .Sp | |
3826 | .Vb 1 | |
3827 | \& IV sv_iv(SV* sv) | |
3828 | .Ve | |
3829 | .IP "sv_len" 8 | |
3830 | .IX Xref "sv_len" | |
3831 | .IX Item "sv_len" | |
3832 | Returns the length of the string in the \s-1SV\s0. Handles magic and type | |
3833 | coercion. See also \f(CW\*(C`SvCUR\*(C'\fR, which gives raw access to the xpv_cur slot. | |
3834 | .Sp | |
3835 | .Vb 1 | |
3836 | \& STRLEN sv_len(SV* sv) | |
3837 | .Ve | |
3838 | .IP "sv_len_utf8" 8 | |
3839 | .IX Xref "sv_len_utf8" | |
3840 | .IX Item "sv_len_utf8" | |
3841 | Returns the number of characters in the string in an \s-1SV\s0, counting wide | |
3842 | \&\s-1UTF\-8\s0 bytes as a single character. Handles magic and type coercion. | |
3843 | .Sp | |
3844 | .Vb 1 | |
3845 | \& STRLEN sv_len_utf8(SV* sv) | |
3846 | .Ve | |
3847 | .IP "sv_magic" 8 | |
3848 | .IX Xref "sv_magic" | |
3849 | .IX Item "sv_magic" | |
3850 | Adds magic to an \s-1SV\s0. First upgrades \f(CW\*(C`sv\*(C'\fR to type \f(CW\*(C`SVt_PVMG\*(C'\fR if necessary, | |
3851 | then adds a new magic item of type \f(CW\*(C`how\*(C'\fR to the head of the magic list. | |
3852 | .Sp | |
3853 | See \f(CW\*(C`sv_magicext\*(C'\fR (which \f(CW\*(C`sv_magic\*(C'\fR now calls) for a description of the | |
3854 | handling of the \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`namlen\*(C'\fR arguments. | |
3855 | .Sp | |
3856 | You need to use \f(CW\*(C`sv_magicext\*(C'\fR to add magic to SvREADONLY SVs and also | |
3857 | to add more than one instance of the same 'how'. | |
3858 | .Sp | |
3859 | .Vb 1 | |
3860 | \& void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen) | |
3861 | .Ve | |
3862 | .IP "sv_magicext" 8 | |
3863 | .IX Xref "sv_magicext" | |
3864 | .IX Item "sv_magicext" | |
3865 | Adds magic to an \s-1SV\s0, upgrading it if necessary. Applies the | |
3866 | supplied vtable and returns a pointer to the magic added. | |
3867 | .Sp | |
3868 | Note that \f(CW\*(C`sv_magicext\*(C'\fR will allow things that \f(CW\*(C`sv_magic\*(C'\fR will not. | |
3869 | In particular, you can add magic to SvREADONLY SVs, and add more than | |
3870 | one instance of the same 'how'. | |
3871 | .Sp | |
3872 | If \f(CW\*(C`namlen\*(C'\fR is greater than zero then a \f(CW\*(C`savepvn\*(C'\fR \fIcopy\fR of \f(CW\*(C`name\*(C'\fR is | |
3873 | stored, if \f(CW\*(C`namlen\*(C'\fR is zero then \f(CW\*(C`name\*(C'\fR is stored as-is and \- as another | |
3874 | special case \- if \f(CW\*(C`(name && namlen == HEf_SVKEY)\*(C'\fR then \f(CW\*(C`name\*(C'\fR is assumed | |
3875 | to contain an \f(CW\*(C`SV*\*(C'\fR and is stored as-is with its \s-1REFCNT\s0 incremented. | |
3876 | .Sp | |
3877 | (This is now used as a subroutine by \f(CW\*(C`sv_magic\*(C'\fR.) | |
3878 | .Sp | |
3879 | .Vb 1 | |
3880 | \& MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen) | |
3881 | .Ve | |
3882 | .IP "sv_mortalcopy" 8 | |
3883 | .IX Xref "sv_mortalcopy" | |
3884 | .IX Item "sv_mortalcopy" | |
3885 | Creates a new \s-1SV\s0 which is a copy of the original \s-1SV\s0 (using \f(CW\*(C`sv_setsv\*(C'\fR). | |
3886 | The new \s-1SV\s0 is marked as mortal. It will be destroyed \*(L"soon\*(R", either by an | |
3887 | explicit call to \s-1FREETMPS\s0, or by an implicit call at places such as | |
3888 | statement boundaries. See also \f(CW\*(C`sv_newmortal\*(C'\fR and \f(CW\*(C`sv_2mortal\*(C'\fR. | |
3889 | .Sp | |
3890 | .Vb 1 | |
3891 | \& SV* sv_mortalcopy(SV* oldsv) | |
3892 | .Ve | |
3893 | .IP "sv_newmortal" 8 | |
3894 | .IX Xref "sv_newmortal" | |
3895 | .IX Item "sv_newmortal" | |
3896 | Creates a new null \s-1SV\s0 which is mortal. The reference count of the \s-1SV\s0 is | |
3897 | set to 1. It will be destroyed \*(L"soon\*(R", either by an explicit call to | |
3898 | \&\s-1FREETMPS\s0, or by an implicit call at places such as statement boundaries. | |
3899 | See also \f(CW\*(C`sv_mortalcopy\*(C'\fR and \f(CW\*(C`sv_2mortal\*(C'\fR. | |
3900 | .Sp | |
3901 | .Vb 1 | |
3902 | \& SV* sv_newmortal() | |
3903 | .Ve | |
3904 | .IP "sv_newref" 8 | |
3905 | .IX Xref "sv_newref" | |
3906 | .IX Item "sv_newref" | |
3907 | Increment an \s-1SV\s0's reference count. Use the \f(CW\*(C`SvREFCNT_inc()\*(C'\fR wrapper | |
3908 | instead. | |
3909 | .Sp | |
3910 | .Vb 1 | |
3911 | \& SV* sv_newref(SV* sv) | |
3912 | .Ve | |
3913 | .IP "sv_nv" 8 | |
3914 | .IX Xref "sv_nv" | |
3915 | .IX Item "sv_nv" | |
3916 | A private implementation of the \f(CW\*(C`SvNVx\*(C'\fR macro for compilers which can't | |
3917 | cope with complex macro expressions. Always use the macro instead. | |
3918 | .Sp | |
3919 | .Vb 1 | |
3920 | \& NV sv_nv(SV* sv) | |
3921 | .Ve | |
3922 | .IP "sv_pos_b2u" 8 | |
3923 | .IX Xref "sv_pos_b2u" | |
3924 | .IX Item "sv_pos_b2u" | |
3925 | Converts the value pointed to by offsetp from a count of bytes from the | |
3926 | start of the string, to a count of the equivalent number of \s-1UTF\-8\s0 chars. | |
3927 | Handles magic and type coercion. | |
3928 | .Sp | |
3929 | .Vb 1 | |
3930 | \& void sv_pos_b2u(SV* sv, I32* offsetp) | |
3931 | .Ve | |
3932 | .IP "sv_pos_u2b" 8 | |
3933 | .IX Xref "sv_pos_u2b" | |
3934 | .IX Item "sv_pos_u2b" | |
3935 | Converts the value pointed to by offsetp from a count of \s-1UTF\-8\s0 chars from | |
3936 | the start of the string, to a count of the equivalent number of bytes; if | |
3937 | lenp is non\-zero, it does the same to lenp, but this time starting from | |
3938 | the offset, rather than from the start of the string. Handles magic and | |
3939 | type coercion. | |
3940 | .Sp | |
3941 | .Vb 1 | |
3942 | \& void sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp) | |
3943 | .Ve | |
3944 | .IP "sv_pv" 8 | |
3945 | .IX Xref "sv_pv" | |
3946 | .IX Item "sv_pv" | |
3947 | Use the \f(CW\*(C`SvPV_nolen\*(C'\fR macro instead | |
3948 | .Sp | |
3949 | .Vb 1 | |
3950 | \& char* sv_pv(SV *sv) | |
3951 | .Ve | |
3952 | .IP "sv_pvbyte" 8 | |
3953 | .IX Xref "sv_pvbyte" | |
3954 | .IX Item "sv_pvbyte" | |
3955 | Use \f(CW\*(C`SvPVbyte_nolen\*(C'\fR instead. | |
3956 | .Sp | |
3957 | .Vb 1 | |
3958 | \& char* sv_pvbyte(SV *sv) | |
3959 | .Ve | |
3960 | .IP "sv_pvbyten" 8 | |
3961 | .IX Xref "sv_pvbyten" | |
3962 | .IX Item "sv_pvbyten" | |
3963 | A private implementation of the \f(CW\*(C`SvPVbyte\*(C'\fR macro for compilers | |
3964 | which can't cope with complex macro expressions. Always use the macro | |
3965 | instead. | |
3966 | .Sp | |
3967 | .Vb 1 | |
3968 | \& char* sv_pvbyten(SV *sv, STRLEN *len) | |
3969 | .Ve | |
3970 | .IP "sv_pvbyten_force" 8 | |
3971 | .IX Xref "sv_pvbyten_force" | |
3972 | .IX Item "sv_pvbyten_force" | |
3973 | A private implementation of the \f(CW\*(C`SvPVbytex_force\*(C'\fR macro for compilers | |
3974 | which can't cope with complex macro expressions. Always use the macro | |
3975 | instead. | |
3976 | .Sp | |
3977 | .Vb 1 | |
3978 | \& char* sv_pvbyten_force(SV* sv, STRLEN* lp) | |
3979 | .Ve | |
3980 | .IP "sv_pvn" 8 | |
3981 | .IX Xref "sv_pvn" | |
3982 | .IX Item "sv_pvn" | |
3983 | A private implementation of the \f(CW\*(C`SvPV\*(C'\fR macro for compilers which can't | |
3984 | cope with complex macro expressions. Always use the macro instead. | |
3985 | .Sp | |
3986 | .Vb 1 | |
3987 | \& char* sv_pvn(SV *sv, STRLEN *len) | |
3988 | .Ve | |
3989 | .IP "sv_pvn_force" 8 | |
3990 | .IX Xref "sv_pvn_force" | |
3991 | .IX Item "sv_pvn_force" | |
3992 | Get a sensible string out of the \s-1SV\s0 somehow. | |
3993 | A private implementation of the \f(CW\*(C`SvPV_force\*(C'\fR macro for compilers which | |
3994 | can't cope with complex macro expressions. Always use the macro instead. | |
3995 | .Sp | |
3996 | .Vb 1 | |
3997 | \& char* sv_pvn_force(SV* sv, STRLEN* lp) | |
3998 | .Ve | |
3999 | .IP "sv_pvn_force_flags" 8 | |
4000 | .IX Xref "sv_pvn_force_flags" | |
4001 | .IX Item "sv_pvn_force_flags" | |
4002 | Get a sensible string out of the \s-1SV\s0 somehow. | |
4003 | If \f(CW\*(C`flags\*(C'\fR has \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, will \f(CW\*(C`mg_get\*(C'\fR on \f(CW\*(C`sv\*(C'\fR if | |
4004 | appropriate, else not. \f(CW\*(C`sv_pvn_force\*(C'\fR and \f(CW\*(C`sv_pvn_force_nomg\*(C'\fR are | |
4005 | implemented in terms of this function. | |
4006 | You normally want to use the various wrapper macros instead: see | |
4007 | \&\f(CW\*(C`SvPV_force\*(C'\fR and \f(CW\*(C`SvPV_force_nomg\*(C'\fR | |
4008 | .Sp | |
4009 | .Vb 1 | |
4010 | \& char* sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags) | |
4011 | .Ve | |
4012 | .IP "sv_pvutf8" 8 | |
4013 | .IX Xref "sv_pvutf8" | |
4014 | .IX Item "sv_pvutf8" | |
4015 | Use the \f(CW\*(C`SvPVutf8_nolen\*(C'\fR macro instead | |
4016 | .Sp | |
4017 | .Vb 1 | |
4018 | \& char* sv_pvutf8(SV *sv) | |
4019 | .Ve | |
4020 | .IP "sv_pvutf8n" 8 | |
4021 | .IX Xref "sv_pvutf8n" | |
4022 | .IX Item "sv_pvutf8n" | |
4023 | A private implementation of the \f(CW\*(C`SvPVutf8\*(C'\fR macro for compilers | |
4024 | which can't cope with complex macro expressions. Always use the macro | |
4025 | instead. | |
4026 | .Sp | |
4027 | .Vb 1 | |
4028 | \& char* sv_pvutf8n(SV *sv, STRLEN *len) | |
4029 | .Ve | |
4030 | .IP "sv_pvutf8n_force" 8 | |
4031 | .IX Xref "sv_pvutf8n_force" | |
4032 | .IX Item "sv_pvutf8n_force" | |
4033 | A private implementation of the \f(CW\*(C`SvPVutf8_force\*(C'\fR macro for compilers | |
4034 | which can't cope with complex macro expressions. Always use the macro | |
4035 | instead. | |
4036 | .Sp | |
4037 | .Vb 1 | |
4038 | \& char* sv_pvutf8n_force(SV* sv, STRLEN* lp) | |
4039 | .Ve | |
4040 | .IP "sv_reftype" 8 | |
4041 | .IX Xref "sv_reftype" | |
4042 | .IX Item "sv_reftype" | |
4043 | Returns a string describing what the \s-1SV\s0 is a reference to. | |
4044 | .Sp | |
4045 | .Vb 1 | |
4046 | \& char* sv_reftype(SV* sv, int ob) | |
4047 | .Ve | |
4048 | .IP "sv_replace" 8 | |
4049 | .IX Xref "sv_replace" | |
4050 | .IX Item "sv_replace" | |
4051 | Make the first argument a copy of the second, then delete the original. | |
4052 | The target \s-1SV\s0 physically takes over ownership of the body of the source \s-1SV\s0 | |
4053 | and inherits its flags; however, the target keeps any magic it owns, | |
4054 | and any magic in the source is discarded. | |
4055 | Note that this is a rather specialist \s-1SV\s0 copying operation; most of the | |
4056 | time you'll want to use \f(CW\*(C`sv_setsv\*(C'\fR or one of its many macro front\-ends. | |
4057 | .Sp | |
4058 | .Vb 1 | |
4059 | \& void sv_replace(SV* sv, SV* nsv) | |
4060 | .Ve | |
4061 | .IP "sv_report_used" 8 | |
4062 | .IX Xref "sv_report_used" | |
4063 | .IX Item "sv_report_used" | |
4064 | Dump the contents of all SVs not yet freed. (Debugging aid). | |
4065 | .Sp | |
4066 | .Vb 1 | |
4067 | \& void sv_report_used() | |
4068 | .Ve | |
4069 | .IP "sv_reset" 8 | |
4070 | .IX Xref "sv_reset" | |
4071 | .IX Item "sv_reset" | |
4072 | Underlying implementation for the \f(CW\*(C`reset\*(C'\fR Perl function. | |
4073 | Note that the perl-level function is vaguely deprecated. | |
4074 | .Sp | |
4075 | .Vb 1 | |
4076 | \& void sv_reset(char* s, HV* stash) | |
4077 | .Ve | |
4078 | .IP "sv_rvweaken" 8 | |
4079 | .IX Xref "sv_rvweaken" | |
4080 | .IX Item "sv_rvweaken" | |
4081 | Weaken a reference: set the \f(CW\*(C`SvWEAKREF\*(C'\fR flag on this \s-1RV\s0; give the | |
4082 | referred-to \s-1SV\s0 \f(CW\*(C`PERL_MAGIC_backref\*(C'\fR magic if it hasn't already; and | |
4083 | push a back-reference to this \s-1RV\s0 onto the array of backreferences | |
4084 | associated with that magic. | |
4085 | .Sp | |
4086 | .Vb 1 | |
4087 | \& SV* sv_rvweaken(SV *sv) | |
4088 | .Ve | |
4089 | .IP "sv_setiv" 8 | |
4090 | .IX Xref "sv_setiv" | |
4091 | .IX Item "sv_setiv" | |
4092 | Copies an integer into the given \s-1SV\s0, upgrading first if necessary. | |
4093 | Does not handle 'set' magic. See also \f(CW\*(C`sv_setiv_mg\*(C'\fR. | |
4094 | .Sp | |
4095 | .Vb 1 | |
4096 | \& void sv_setiv(SV* sv, IV num) | |
4097 | .Ve | |
4098 | .IP "sv_setiv_mg" 8 | |
4099 | .IX Xref "sv_setiv_mg" | |
4100 | .IX Item "sv_setiv_mg" | |
4101 | Like \f(CW\*(C`sv_setiv\*(C'\fR, but also handles 'set' magic. | |
4102 | .Sp | |
4103 | .Vb 1 | |
4104 | \& void sv_setiv_mg(SV *sv, IV i) | |
4105 | .Ve | |
4106 | .IP "sv_setnv" 8 | |
4107 | .IX Xref "sv_setnv" | |
4108 | .IX Item "sv_setnv" | |
4109 | Copies a double into the given \s-1SV\s0, upgrading first if necessary. | |
4110 | Does not handle 'set' magic. See also \f(CW\*(C`sv_setnv_mg\*(C'\fR. | |
4111 | .Sp | |
4112 | .Vb 1 | |
4113 | \& void sv_setnv(SV* sv, NV num) | |
4114 | .Ve | |
4115 | .IP "sv_setnv_mg" 8 | |
4116 | .IX Xref "sv_setnv_mg" | |
4117 | .IX Item "sv_setnv_mg" | |
4118 | Like \f(CW\*(C`sv_setnv\*(C'\fR, but also handles 'set' magic. | |
4119 | .Sp | |
4120 | .Vb 1 | |
4121 | \& void sv_setnv_mg(SV *sv, NV num) | |
4122 | .Ve | |
4123 | .IP "sv_setpv" 8 | |
4124 | .IX Xref "sv_setpv" | |
4125 | .IX Item "sv_setpv" | |
4126 | Copies a string into an \s-1SV\s0. The string must be null\-terminated. Does not | |
4127 | handle 'set' magic. See \f(CW\*(C`sv_setpv_mg\*(C'\fR. | |
4128 | .Sp | |
4129 | .Vb 1 | |
4130 | \& void sv_setpv(SV* sv, const char* ptr) | |
4131 | .Ve | |
4132 | .IP "sv_setpvf" 8 | |
4133 | .IX Xref "sv_setpvf" | |
4134 | .IX Item "sv_setpvf" | |
4135 | Works like \f(CW\*(C`sv_catpvf\*(C'\fR but copies the text into the \s-1SV\s0 instead of | |
4136 | appending it. Does not handle 'set' magic. See \f(CW\*(C`sv_setpvf_mg\*(C'\fR. | |
4137 | .Sp | |
4138 | .Vb 1 | |
4139 | \& void sv_setpvf(SV* sv, const char* pat, ...) | |
4140 | .Ve | |
4141 | .IP "sv_setpvf_mg" 8 | |
4142 | .IX Xref "sv_setpvf_mg" | |
4143 | .IX Item "sv_setpvf_mg" | |
4144 | Like \f(CW\*(C`sv_setpvf\*(C'\fR, but also handles 'set' magic. | |
4145 | .Sp | |
4146 | .Vb 1 | |
4147 | \& void sv_setpvf_mg(SV *sv, const char* pat, ...) | |
4148 | .Ve | |
4149 | .IP "sv_setpviv" 8 | |
4150 | .IX Xref "sv_setpviv" | |
4151 | .IX Item "sv_setpviv" | |
4152 | Copies an integer into the given \s-1SV\s0, also updating its string value. | |
4153 | Does not handle 'set' magic. See \f(CW\*(C`sv_setpviv_mg\*(C'\fR. | |
4154 | .Sp | |
4155 | .Vb 1 | |
4156 | \& void sv_setpviv(SV* sv, IV num) | |
4157 | .Ve | |
4158 | .IP "sv_setpviv_mg" 8 | |
4159 | .IX Xref "sv_setpviv_mg" | |
4160 | .IX Item "sv_setpviv_mg" | |
4161 | Like \f(CW\*(C`sv_setpviv\*(C'\fR, but also handles 'set' magic. | |
4162 | .Sp | |
4163 | .Vb 1 | |
4164 | \& void sv_setpviv_mg(SV *sv, IV iv) | |
4165 | .Ve | |
4166 | .IP "sv_setpvn" 8 | |
4167 | .IX Xref "sv_setpvn" | |
4168 | .IX Item "sv_setpvn" | |
4169 | Copies a string into an \s-1SV\s0. The \f(CW\*(C`len\*(C'\fR parameter indicates the number of | |
4170 | bytes to be copied. If the \f(CW\*(C`ptr\*(C'\fR argument is \s-1NULL\s0 the \s-1SV\s0 will become | |
4171 | undefined. Does not handle 'set' magic. See \f(CW\*(C`sv_setpvn_mg\*(C'\fR. | |
4172 | .Sp | |
4173 | .Vb 1 | |
4174 | \& void sv_setpvn(SV* sv, const char* ptr, STRLEN len) | |
4175 | .Ve | |
4176 | .IP "sv_setpvn_mg" 8 | |
4177 | .IX Xref "sv_setpvn_mg" | |
4178 | .IX Item "sv_setpvn_mg" | |
4179 | Like \f(CW\*(C`sv_setpvn\*(C'\fR, but also handles 'set' magic. | |
4180 | .Sp | |
4181 | .Vb 1 | |
4182 | \& void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len) | |
4183 | .Ve | |
4184 | .IP "sv_setpv_mg" 8 | |
4185 | .IX Xref "sv_setpv_mg" | |
4186 | .IX Item "sv_setpv_mg" | |
4187 | Like \f(CW\*(C`sv_setpv\*(C'\fR, but also handles 'set' magic. | |
4188 | .Sp | |
4189 | .Vb 1 | |
4190 | \& void sv_setpv_mg(SV *sv, const char *ptr) | |
4191 | .Ve | |
4192 | .IP "sv_setref_iv" 8 | |
4193 | .IX Xref "sv_setref_iv" | |
4194 | .IX Item "sv_setref_iv" | |
4195 | Copies an integer into a new \s-1SV\s0, optionally blessing the \s-1SV\s0. The \f(CW\*(C`rv\*(C'\fR | |
4196 | argument will be upgraded to an \s-1RV\s0. That \s-1RV\s0 will be modified to point to | |
4197 | the new \s-1SV\s0. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the | |
4198 | blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`Nullch\*(C'\fR to avoid the blessing. The new \s-1SV\s0 | |
4199 | will have a reference count of 1, and the \s-1RV\s0 will be returned. | |
4200 | .Sp | |
4201 | .Vb 1 | |
4202 | \& SV* sv_setref_iv(SV* rv, const char* classname, IV iv) | |
4203 | .Ve | |
4204 | .IP "sv_setref_nv" 8 | |
4205 | .IX Xref "sv_setref_nv" | |
4206 | .IX Item "sv_setref_nv" | |
4207 | Copies a double into a new \s-1SV\s0, optionally blessing the \s-1SV\s0. The \f(CW\*(C`rv\*(C'\fR | |
4208 | argument will be upgraded to an \s-1RV\s0. That \s-1RV\s0 will be modified to point to | |
4209 | the new \s-1SV\s0. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the | |
4210 | blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`Nullch\*(C'\fR to avoid the blessing. The new \s-1SV\s0 | |
4211 | will have a reference count of 1, and the \s-1RV\s0 will be returned. | |
4212 | .Sp | |
4213 | .Vb 1 | |
4214 | \& SV* sv_setref_nv(SV* rv, const char* classname, NV nv) | |
4215 | .Ve | |
4216 | .IP "sv_setref_pv" 8 | |
4217 | .IX Xref "sv_setref_pv" | |
4218 | .IX Item "sv_setref_pv" | |
4219 | Copies a pointer into a new \s-1SV\s0, optionally blessing the \s-1SV\s0. The \f(CW\*(C`rv\*(C'\fR | |
4220 | argument will be upgraded to an \s-1RV\s0. That \s-1RV\s0 will be modified to point to | |
4221 | the new \s-1SV\s0. If the \f(CW\*(C`pv\*(C'\fR argument is \s-1NULL\s0 then \f(CW\*(C`PL_sv_undef\*(C'\fR will be placed | |
4222 | into the \s-1SV\s0. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the | |
4223 | blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`Nullch\*(C'\fR to avoid the blessing. The new \s-1SV\s0 | |
4224 | will have a reference count of 1, and the \s-1RV\s0 will be returned. | |
4225 | .Sp | |
4226 | Do not use with other Perl types such as \s-1HV\s0, \s-1AV\s0, \s-1SV\s0, \s-1CV\s0, because those | |
4227 | objects will become corrupted by the pointer copy process. | |
4228 | .Sp | |
4229 | Note that \f(CW\*(C`sv_setref_pvn\*(C'\fR copies the string while this copies the pointer. | |
4230 | .Sp | |
4231 | .Vb 1 | |
4232 | \& SV* sv_setref_pv(SV* rv, const char* classname, void* pv) | |
4233 | .Ve | |
4234 | .IP "sv_setref_pvn" 8 | |
4235 | .IX Xref "sv_setref_pvn" | |
4236 | .IX Item "sv_setref_pvn" | |
4237 | Copies a string into a new \s-1SV\s0, optionally blessing the \s-1SV\s0. The length of the | |
4238 | string must be specified with \f(CW\*(C`n\*(C'\fR. The \f(CW\*(C`rv\*(C'\fR argument will be upgraded to | |
4239 | an \s-1RV\s0. That \s-1RV\s0 will be modified to point to the new \s-1SV\s0. The \f(CW\*(C`classname\*(C'\fR | |
4240 | argument indicates the package for the blessing. Set \f(CW\*(C`classname\*(C'\fR to | |
4241 | \&\f(CW\*(C`Nullch\*(C'\fR to avoid the blessing. The new \s-1SV\s0 will have a reference count | |
4242 | of 1, and the \s-1RV\s0 will be returned. | |
4243 | .Sp | |
4244 | Note that \f(CW\*(C`sv_setref_pv\*(C'\fR copies the pointer while this copies the string. | |
4245 | .Sp | |
4246 | .Vb 1 | |
4247 | \& SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n) | |
4248 | .Ve | |
4249 | .IP "sv_setref_uv" 8 | |
4250 | .IX Xref "sv_setref_uv" | |
4251 | .IX Item "sv_setref_uv" | |
4252 | Copies an unsigned integer into a new \s-1SV\s0, optionally blessing the \s-1SV\s0. The \f(CW\*(C`rv\*(C'\fR | |
4253 | argument will be upgraded to an \s-1RV\s0. That \s-1RV\s0 will be modified to point to | |
4254 | the new \s-1SV\s0. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the | |
4255 | blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`Nullch\*(C'\fR to avoid the blessing. The new \s-1SV\s0 | |
4256 | will have a reference count of 1, and the \s-1RV\s0 will be returned. | |
4257 | .Sp | |
4258 | .Vb 1 | |
4259 | \& SV* sv_setref_uv(SV* rv, const char* classname, UV uv) | |
4260 | .Ve | |
4261 | .IP "sv_setsv" 8 | |
4262 | .IX Xref "sv_setsv" | |
4263 | .IX Item "sv_setsv" | |
4264 | Copies the contents of the source \s-1SV\s0 \f(CW\*(C`ssv\*(C'\fR into the destination \s-1SV\s0 | |
4265 | \&\f(CW\*(C`dsv\*(C'\fR. The source \s-1SV\s0 may be destroyed if it is mortal, so don't use this | |
4266 | function if the source \s-1SV\s0 needs to be reused. Does not handle 'set' magic. | |
4267 | Loosely speaking, it performs a copy\-by\-value, obliterating any previous | |
4268 | content of the destination. | |
4269 | .Sp | |
4270 | You probably want to use one of the assortment of wrappers, such as | |
4271 | \&\f(CW\*(C`SvSetSV\*(C'\fR, \f(CW\*(C`SvSetSV_nosteal\*(C'\fR, \f(CW\*(C`SvSetMagicSV\*(C'\fR and | |
4272 | \&\f(CW\*(C`SvSetMagicSV_nosteal\*(C'\fR. | |
4273 | .Sp | |
4274 | .Vb 1 | |
4275 | \& void sv_setsv(SV* dsv, SV* ssv) | |
4276 | .Ve | |
4277 | .IP "sv_setsv_flags" 8 | |
4278 | .IX Xref "sv_setsv_flags" | |
4279 | .IX Item "sv_setsv_flags" | |
4280 | Copies the contents of the source \s-1SV\s0 \f(CW\*(C`ssv\*(C'\fR into the destination \s-1SV\s0 | |
4281 | \&\f(CW\*(C`dsv\*(C'\fR. The source \s-1SV\s0 may be destroyed if it is mortal, so don't use this | |
4282 | function if the source \s-1SV\s0 needs to be reused. Does not handle 'set' magic. | |
4283 | Loosely speaking, it performs a copy\-by\-value, obliterating any previous | |
4284 | content of the destination. | |
4285 | If the \f(CW\*(C`flags\*(C'\fR parameter has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, will \f(CW\*(C`mg_get\*(C'\fR on | |
4286 | \&\f(CW\*(C`ssv\*(C'\fR if appropriate, else not. If the \f(CW\*(C`flags\*(C'\fR parameter has the | |
4287 | \&\f(CW\*(C`NOSTEAL\*(C'\fR bit set then the buffers of temps will not be stolen. <sv_setsv> | |
4288 | and \f(CW\*(C`sv_setsv_nomg\*(C'\fR are implemented in terms of this function. | |
4289 | .Sp | |
4290 | You probably want to use one of the assortment of wrappers, such as | |
4291 | \&\f(CW\*(C`SvSetSV\*(C'\fR, \f(CW\*(C`SvSetSV_nosteal\*(C'\fR, \f(CW\*(C`SvSetMagicSV\*(C'\fR and | |
4292 | \&\f(CW\*(C`SvSetMagicSV_nosteal\*(C'\fR. | |
4293 | .Sp | |
4294 | This is the primary function for copying scalars, and most other | |
4295 | copy-ish functions and macros use this underneath. | |
4296 | .Sp | |
4297 | .Vb 1 | |
4298 | \& void sv_setsv_flags(SV* dsv, SV* ssv, I32 flags) | |
4299 | .Ve | |
4300 | .IP "sv_setsv_mg" 8 | |
4301 | .IX Xref "sv_setsv_mg" | |
4302 | .IX Item "sv_setsv_mg" | |
4303 | Like \f(CW\*(C`sv_setsv\*(C'\fR, but also handles 'set' magic. | |
4304 | .Sp | |
4305 | .Vb 1 | |
4306 | \& void sv_setsv_mg(SV *dstr, SV *sstr) | |
4307 | .Ve | |
4308 | .IP "sv_setsv_nomg" 8 | |
4309 | .IX Xref "sv_setsv_nomg" | |
4310 | .IX Item "sv_setsv_nomg" | |
4311 | Like \f(CW\*(C`sv_setsv\*(C'\fR but doesn't process magic. | |
4312 | .Sp | |
4313 | .Vb 1 | |
4314 | \& void sv_setsv_nomg(SV* dsv, SV* ssv) | |
4315 | .Ve | |
4316 | .IP "sv_setuv" 8 | |
4317 | .IX Xref "sv_setuv" | |
4318 | .IX Item "sv_setuv" | |
4319 | Copies an unsigned integer into the given \s-1SV\s0, upgrading first if necessary. | |
4320 | Does not handle 'set' magic. See also \f(CW\*(C`sv_setuv_mg\*(C'\fR. | |
4321 | .Sp | |
4322 | .Vb 1 | |
4323 | \& void sv_setuv(SV* sv, UV num) | |
4324 | .Ve | |
4325 | .IP "sv_setuv_mg" 8 | |
4326 | .IX Xref "sv_setuv_mg" | |
4327 | .IX Item "sv_setuv_mg" | |
4328 | Like \f(CW\*(C`sv_setuv\*(C'\fR, but also handles 'set' magic. | |
4329 | .Sp | |
4330 | .Vb 1 | |
4331 | \& void sv_setuv_mg(SV *sv, UV u) | |
4332 | .Ve | |
4333 | .IP "sv_taint" 8 | |
4334 | .IX Xref "sv_taint" | |
4335 | .IX Item "sv_taint" | |
4336 | Taint an \s-1SV\s0. Use \f(CW\*(C`SvTAINTED_on\*(C'\fR instead. | |
4337 | void sv_taint(SV* sv) | |
4338 | .IP "sv_tainted" 8 | |
4339 | .IX Xref "sv_tainted" | |
4340 | .IX Item "sv_tainted" | |
4341 | Test an \s-1SV\s0 for taintedness. Use \f(CW\*(C`SvTAINTED\*(C'\fR instead. | |
4342 | bool sv_tainted(SV* sv) | |
4343 | .IP "sv_true" 8 | |
4344 | .IX Xref "sv_true" | |
4345 | .IX Item "sv_true" | |
4346 | Returns true if the \s-1SV\s0 has a true value by Perl's rules. | |
4347 | Use the \f(CW\*(C`SvTRUE\*(C'\fR macro instead, which may call \f(CW\*(C`sv_true()\*(C'\fR or may | |
4348 | instead use an in-line version. | |
4349 | .Sp | |
4350 | .Vb 1 | |
4351 | \& I32 sv_true(SV *sv) | |
4352 | .Ve | |
4353 | .IP "sv_unmagic" 8 | |
4354 | .IX Xref "sv_unmagic" | |
4355 | .IX Item "sv_unmagic" | |
4356 | Removes all magic of type \f(CW\*(C`type\*(C'\fR from an \s-1SV\s0. | |
4357 | .Sp | |
4358 | .Vb 1 | |
4359 | \& int sv_unmagic(SV* sv, int type) | |
4360 | .Ve | |
4361 | .IP "sv_unref" 8 | |
4362 | .IX Xref "sv_unref" | |
4363 | .IX Item "sv_unref" | |
4364 | Unsets the \s-1RV\s0 status of the \s-1SV\s0, and decrements the reference count of | |
4365 | whatever was being referenced by the \s-1RV\s0. This can almost be thought of | |
4366 | as a reversal of \f(CW\*(C`newSVrv\*(C'\fR. This is \f(CW\*(C`sv_unref_flags\*(C'\fR with the \f(CW\*(C`flag\*(C'\fR | |
4367 | being zero. See \f(CW\*(C`SvROK_off\*(C'\fR. | |
4368 | .Sp | |
4369 | .Vb 1 | |
4370 | \& void sv_unref(SV* sv) | |
4371 | .Ve | |
4372 | .IP "sv_unref_flags" 8 | |
4373 | .IX Xref "sv_unref_flags" | |
4374 | .IX Item "sv_unref_flags" | |
4375 | Unsets the \s-1RV\s0 status of the \s-1SV\s0, and decrements the reference count of | |
4376 | whatever was being referenced by the \s-1RV\s0. This can almost be thought of | |
4377 | as a reversal of \f(CW\*(C`newSVrv\*(C'\fR. The \f(CW\*(C`cflags\*(C'\fR argument can contain | |
4378 | \&\f(CW\*(C`SV_IMMEDIATE_UNREF\*(C'\fR to force the reference count to be decremented | |
4379 | (otherwise the decrementing is conditional on the reference count being | |
4380 | different from one or the reference being a readonly \s-1SV\s0). | |
4381 | See \f(CW\*(C`SvROK_off\*(C'\fR. | |
4382 | .Sp | |
4383 | .Vb 1 | |
4384 | \& void sv_unref_flags(SV* sv, U32 flags) | |
4385 | .Ve | |
4386 | .IP "sv_untaint" 8 | |
4387 | .IX Xref "sv_untaint" | |
4388 | .IX Item "sv_untaint" | |
4389 | Untaint an \s-1SV\s0. Use \f(CW\*(C`SvTAINTED_off\*(C'\fR instead. | |
4390 | void sv_untaint(SV* sv) | |
4391 | .IP "sv_upgrade" 8 | |
4392 | .IX Xref "sv_upgrade" | |
4393 | .IX Item "sv_upgrade" | |
4394 | Upgrade an \s-1SV\s0 to a more complex form. Generally adds a new body type to the | |
4395 | \&\s-1SV\s0, then copies across as much information as possible from the old body. | |
4396 | You generally want to use the \f(CW\*(C`SvUPGRADE\*(C'\fR macro wrapper. See also \f(CW\*(C`svtype\*(C'\fR. | |
4397 | .Sp | |
4398 | .Vb 1 | |
4399 | \& bool sv_upgrade(SV* sv, U32 mt) | |
4400 | .Ve | |
4401 | .IP "sv_usepvn" 8 | |
4402 | .IX Xref "sv_usepvn" | |
4403 | .IX Item "sv_usepvn" | |
4404 | Tells an \s-1SV\s0 to use \f(CW\*(C`ptr\*(C'\fR to find its string value. Normally the string is | |
4405 | stored inside the \s-1SV\s0 but sv_usepvn allows the \s-1SV\s0 to use an outside string. | |
4406 | The \f(CW\*(C`ptr\*(C'\fR should point to memory that was allocated by \f(CW\*(C`malloc\*(C'\fR. The | |
4407 | string length, \f(CW\*(C`len\*(C'\fR, must be supplied. This function will realloc the | |
4408 | memory pointed to by \f(CW\*(C`ptr\*(C'\fR, so that pointer should not be freed or used by | |
4409 | the programmer after giving it to sv_usepvn. Does not handle 'set' magic. | |
4410 | See \f(CW\*(C`sv_usepvn_mg\*(C'\fR. | |
4411 | .Sp | |
4412 | .Vb 1 | |
4413 | \& void sv_usepvn(SV* sv, char* ptr, STRLEN len) | |
4414 | .Ve | |
4415 | .IP "sv_usepvn_mg" 8 | |
4416 | .IX Xref "sv_usepvn_mg" | |
4417 | .IX Item "sv_usepvn_mg" | |
4418 | Like \f(CW\*(C`sv_usepvn\*(C'\fR, but also handles 'set' magic. | |
4419 | .Sp | |
4420 | .Vb 1 | |
4421 | \& void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len) | |
4422 | .Ve | |
4423 | .IP "sv_utf8_decode" 8 | |
4424 | .IX Xref "sv_utf8_decode" | |
4425 | .IX Item "sv_utf8_decode" | |
4426 | If the \s-1PV\s0 of the \s-1SV\s0 is an octet sequence in \s-1UTF\-8\s0 | |
4427 | and contains a multiple-byte character, the \f(CW\*(C`SvUTF8\*(C'\fR flag is turned on | |
4428 | so that it looks like a character. If the \s-1PV\s0 contains only single-byte | |
4429 | characters, the \f(CW\*(C`SvUTF8\*(C'\fR flag stays being off. | |
4430 | Scans \s-1PV\s0 for validity and returns false if the \s-1PV\s0 is invalid \s-1UTF\-8\s0. | |
4431 | .Sp | |
4432 | \&\s-1NOTE:\s0 this function is experimental and may change or be | |
4433 | removed without notice. | |
4434 | .Sp | |
4435 | .Vb 1 | |
4436 | \& bool sv_utf8_decode(SV *sv) | |
4437 | .Ve | |
4438 | .IP "sv_utf8_downgrade" 8 | |
4439 | .IX Xref "sv_utf8_downgrade" | |
4440 | .IX Item "sv_utf8_downgrade" | |
4441 | Attempts to convert the \s-1PV\s0 of an \s-1SV\s0 from characters to bytes. | |
4442 | If the \s-1PV\s0 contains a character beyond byte, this conversion will fail; | |
4443 | in this case, either returns false or, if \f(CW\*(C`fail_ok\*(C'\fR is not | |
4444 | true, croaks. | |
4445 | .Sp | |
4446 | This is not as a general purpose Unicode to byte encoding interface: | |
4447 | use the Encode extension for that. | |
4448 | .Sp | |
4449 | \&\s-1NOTE:\s0 this function is experimental and may change or be | |
4450 | removed without notice. | |
4451 | .Sp | |
4452 | .Vb 1 | |
4453 | \& bool sv_utf8_downgrade(SV *sv, bool fail_ok) | |
4454 | .Ve | |
4455 | .IP "sv_utf8_encode" 8 | |
4456 | .IX Xref "sv_utf8_encode" | |
4457 | .IX Item "sv_utf8_encode" | |
4458 | Converts the \s-1PV\s0 of an \s-1SV\s0 to \s-1UTF\-8\s0, but then turns the \f(CW\*(C`SvUTF8\*(C'\fR | |
4459 | flag off so that it looks like octets again. | |
4460 | .Sp | |
4461 | .Vb 1 | |
4462 | \& void sv_utf8_encode(SV *sv) | |
4463 | .Ve | |
4464 | .IP "sv_utf8_upgrade" 8 | |
4465 | .IX Xref "sv_utf8_upgrade" | |
4466 | .IX Item "sv_utf8_upgrade" | |
4467 | Converts the \s-1PV\s0 of an \s-1SV\s0 to its UTF\-8\-encoded form. | |
4468 | Forces the \s-1SV\s0 to string form if it is not already. | |
4469 | Always sets the SvUTF8 flag to avoid future validity checks even | |
4470 | if all the bytes have hibit clear. | |
4471 | .Sp | |
4472 | This is not as a general purpose byte encoding to Unicode interface: | |
4473 | use the Encode extension for that. | |
4474 | .Sp | |
4475 | .Vb 1 | |
4476 | \& STRLEN sv_utf8_upgrade(SV *sv) | |
4477 | .Ve | |
4478 | .IP "sv_utf8_upgrade_flags" 8 | |
4479 | .IX Xref "sv_utf8_upgrade_flags" | |
4480 | .IX Item "sv_utf8_upgrade_flags" | |
4481 | Converts the \s-1PV\s0 of an \s-1SV\s0 to its UTF\-8\-encoded form. | |
4482 | Forces the \s-1SV\s0 to string form if it is not already. | |
4483 | Always sets the SvUTF8 flag to avoid future validity checks even | |
4484 | if all the bytes have hibit clear. If \f(CW\*(C`flags\*(C'\fR has \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, | |
4485 | will \f(CW\*(C`mg_get\*(C'\fR on \f(CW\*(C`sv\*(C'\fR if appropriate, else not. \f(CW\*(C`sv_utf8_upgrade\*(C'\fR and | |
4486 | \&\f(CW\*(C`sv_utf8_upgrade_nomg\*(C'\fR are implemented in terms of this function. | |
4487 | .Sp | |
4488 | This is not as a general purpose byte encoding to Unicode interface: | |
4489 | use the Encode extension for that. | |
4490 | .Sp | |
4491 | .Vb 1 | |
4492 | \& STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags) | |
4493 | .Ve | |
4494 | .IP "sv_uv" 8 | |
4495 | .IX Xref "sv_uv" | |
4496 | .IX Item "sv_uv" | |
4497 | A private implementation of the \f(CW\*(C`SvUVx\*(C'\fR macro for compilers which can't | |
4498 | cope with complex macro expressions. Always use the macro instead. | |
4499 | .Sp | |
4500 | .Vb 1 | |
4501 | \& UV sv_uv(SV* sv) | |
4502 | .Ve | |
4503 | .IP "sv_vcatpvf" 8 | |
4504 | .IX Xref "sv_vcatpvf" | |
4505 | .IX Item "sv_vcatpvf" | |
4506 | Processes its arguments like \f(CW\*(C`vsprintf\*(C'\fR and appends the formatted output | |
4507 | to an \s-1SV\s0. Does not handle 'set' magic. See \f(CW\*(C`sv_vcatpvf_mg\*(C'\fR. | |
4508 | .Sp | |
4509 | Usually used via its frontend \f(CW\*(C`sv_catpvf\*(C'\fR. | |
4510 | .Sp | |
4511 | .Vb 1 | |
4512 | \& void sv_vcatpvf(SV* sv, const char* pat, va_list* args) | |
4513 | .Ve | |
4514 | .IP "sv_vcatpvfn" 8 | |
4515 | .IX Xref "sv_vcatpvfn" | |
4516 | .IX Item "sv_vcatpvfn" | |
4517 | Processes its arguments like \f(CW\*(C`vsprintf\*(C'\fR and appends the formatted output | |
4518 | to an \s-1SV\s0. Uses an array of SVs if the C style variable argument list is | |
4519 | missing (\s-1NULL\s0). When running with taint checks enabled, indicates via | |
4520 | \&\f(CW\*(C`maybe_tainted\*(C'\fR if results are untrustworthy (often due to the use of | |
4521 | locales). | |
4522 | .Sp | |
4523 | \&\s-1XXX\s0 Except that it maybe_tainted is never assigned to. | |
4524 | .Sp | |
4525 | Usually used via one of its frontends \f(CW\*(C`sv_vcatpvf\*(C'\fR and \f(CW\*(C`sv_vcatpvf_mg\*(C'\fR. | |
4526 | .Sp | |
4527 | .Vb 1 | |
4528 | \& void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) | |
4529 | .Ve | |
4530 | .IP "sv_vcatpvf_mg" 8 | |
4531 | .IX Xref "sv_vcatpvf_mg" | |
4532 | .IX Item "sv_vcatpvf_mg" | |
4533 | Like \f(CW\*(C`sv_vcatpvf\*(C'\fR, but also handles 'set' magic. | |
4534 | .Sp | |
4535 | Usually used via its frontend \f(CW\*(C`sv_catpvf_mg\*(C'\fR. | |
4536 | .Sp | |
4537 | .Vb 1 | |
4538 | \& void sv_vcatpvf_mg(SV* sv, const char* pat, va_list* args) | |
4539 | .Ve | |
4540 | .IP "sv_vsetpvf" 8 | |
4541 | .IX Xref "sv_vsetpvf" | |
4542 | .IX Item "sv_vsetpvf" | |
4543 | Works like \f(CW\*(C`sv_vcatpvf\*(C'\fR but copies the text into the \s-1SV\s0 instead of | |
4544 | appending it. Does not handle 'set' magic. See \f(CW\*(C`sv_vsetpvf_mg\*(C'\fR. | |
4545 | .Sp | |
4546 | Usually used via its frontend \f(CW\*(C`sv_setpvf\*(C'\fR. | |
4547 | .Sp | |
4548 | .Vb 1 | |
4549 | \& void sv_vsetpvf(SV* sv, const char* pat, va_list* args) | |
4550 | .Ve | |
4551 | .IP "sv_vsetpvfn" 8 | |
4552 | .IX Xref "sv_vsetpvfn" | |
4553 | .IX Item "sv_vsetpvfn" | |
4554 | Works like \f(CW\*(C`sv_vcatpvfn\*(C'\fR but copies the text into the \s-1SV\s0 instead of | |
4555 | appending it. | |
4556 | .Sp | |
4557 | Usually used via one of its frontends \f(CW\*(C`sv_vsetpvf\*(C'\fR and \f(CW\*(C`sv_vsetpvf_mg\*(C'\fR. | |
4558 | .Sp | |
4559 | .Vb 1 | |
4560 | \& void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) | |
4561 | .Ve | |
4562 | .IP "sv_vsetpvf_mg" 8 | |
4563 | .IX Xref "sv_vsetpvf_mg" | |
4564 | .IX Item "sv_vsetpvf_mg" | |
4565 | Like \f(CW\*(C`sv_vsetpvf\*(C'\fR, but also handles 'set' magic. | |
4566 | .Sp | |
4567 | Usually used via its frontend \f(CW\*(C`sv_setpvf_mg\*(C'\fR. | |
4568 | .Sp | |
4569 | .Vb 1 | |
4570 | \& void sv_vsetpvf_mg(SV* sv, const char* pat, va_list* args) | |
4571 | .Ve | |
4572 | .SH "Unicode Support" | |
4573 | .IX Header "Unicode Support" | |
4574 | .IP "bytes_from_utf8" 8 | |
4575 | .IX Xref "bytes_from_utf8" | |
4576 | .IX Item "bytes_from_utf8" | |
4577 | Converts a string \f(CW\*(C`s\*(C'\fR of length \f(CW\*(C`len\*(C'\fR from \s-1UTF\-8\s0 into byte encoding. | |
4578 | Unlike \f(CW\*(C`utf8_to_bytes\*(C'\fR but like \f(CW\*(C`bytes_to_utf8\*(C'\fR, returns a pointer to | |
4579 | the newly-created string, and updates \f(CW\*(C`len\*(C'\fR to contain the new | |
4580 | length. Returns the original string if no conversion occurs, \f(CW\*(C`len\*(C'\fR | |
4581 | is unchanged. Do nothing if \f(CW\*(C`is_utf8\*(C'\fR points to 0. Sets \f(CW\*(C`is_utf8\*(C'\fR to | |
4582 | 0 if \f(CW\*(C`s\*(C'\fR is converted or contains all 7bit characters. | |
4583 | .Sp | |
4584 | \&\s-1NOTE:\s0 this function is experimental and may change or be | |
4585 | removed without notice. | |
4586 | .Sp | |
4587 | .Vb 1 | |
4588 | \& U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8) | |
4589 | .Ve | |
4590 | .IP "bytes_to_utf8" 8 | |
4591 | .IX Xref "bytes_to_utf8" | |
4592 | .IX Item "bytes_to_utf8" | |
4593 | Converts a string \f(CW\*(C`s\*(C'\fR of length \f(CW\*(C`len\*(C'\fR from \s-1ASCII\s0 into \s-1UTF\-8\s0 encoding. | |
4594 | Returns a pointer to the newly-created string, and sets \f(CW\*(C`len\*(C'\fR to | |
4595 | reflect the new length. | |
4596 | .Sp | |
4597 | If you want to convert to \s-1UTF\-8\s0 from other encodings than \s-1ASCII\s0, | |
4598 | see \fIsv_recode_to_utf8()\fR. | |
4599 | .Sp | |
4600 | \&\s-1NOTE:\s0 this function is experimental and may change or be | |
4601 | removed without notice. | |
4602 | .Sp | |
4603 | .Vb 1 | |
4604 | \& U8* bytes_to_utf8(U8 *s, STRLEN *len) | |
4605 | .Ve | |
4606 | .IP "ibcmp_utf8" 8 | |
4607 | .IX Xref "ibcmp_utf8" | |
4608 | .IX Item "ibcmp_utf8" | |
4609 | Return true if the strings s1 and s2 differ case\-insensitively, false | |
4610 | if not (if they are equal case\-insensitively). If u1 is true, the | |
4611 | string s1 is assumed to be in UTF\-8\-encoded Unicode. If u2 is true, | |
4612 | the string s2 is assumed to be in UTF\-8\-encoded Unicode. If u1 or u2 | |
4613 | are false, the respective string is assumed to be in native 8\-bit | |
4614 | encoding. | |
4615 | .Sp | |
4616 | If the pe1 and pe2 are non\-NULL, the scanning pointers will be copied | |
4617 | in there (they will point at the beginning of the \fInext\fR character). | |
4618 | If the pointers behind pe1 or pe2 are non\-NULL, they are the end | |
4619 | pointers beyond which scanning will not continue under any | |
4620 | circumstances. If the byte lengths l1 and l2 are non\-zero, s1+l1 and | |
4621 | s2+l2 will be used as goal end pointers that will also stop the scan, | |
4622 | and which qualify towards defining a successful match: all the scans | |
4623 | that define an explicit length must reach their goal pointers for | |
4624 | a match to succeed). | |
4625 | .Sp | |
4626 | For case\-insensitiveness, the \*(L"casefolding\*(R" of Unicode is used | |
4627 | instead of upper/lowercasing both the characters, see | |
4628 | http://www.unicode.org/unicode/reports/tr21/ (Case Mappings). | |
4629 | .Sp | |
4630 | .Vb 1 | |
4631 | \& I32 ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2) | |
4632 | .Ve | |
4633 | .IP "is_utf8_char" 8 | |
4634 | .IX Xref "is_utf8_char" | |
4635 | .IX Item "is_utf8_char" | |
4636 | Tests if some arbitrary number of bytes begins in a valid \s-1UTF\-8\s0 | |
4637 | character. Note that an \s-1INVARIANT\s0 (i.e. \s-1ASCII\s0) character is a valid | |
4638 | \&\s-1UTF\-8\s0 character. The actual number of bytes in the \s-1UTF\-8\s0 character | |
4639 | will be returned if it is valid, otherwise 0. | |
4640 | .Sp | |
4641 | .Vb 1 | |
4642 | \& STRLEN is_utf8_char(U8 *p) | |
4643 | .Ve | |
4644 | .IP "is_utf8_string" 8 | |
4645 | .IX Xref "is_utf8_string" | |
4646 | .IX Item "is_utf8_string" | |
4647 | Returns true if first \f(CW\*(C`len\*(C'\fR bytes of the given string form a valid | |
4648 | \&\s-1UTF\-8\s0 string, false otherwise. Note that 'a valid \s-1UTF\-8\s0 string' does | |
4649 | not mean 'a string that contains code points above 0x7F encoded in \s-1UTF\-8\s0' | |
4650 | because a valid \s-1ASCII\s0 string is a valid \s-1UTF\-8\s0 string. | |
4651 | .Sp | |
4652 | See also \fIis_utf8_string_loclen()\fR and \fIis_utf8_string_loc()\fR. | |
4653 | .Sp | |
4654 | .Vb 1 | |
4655 | \& bool is_utf8_string(U8 *s, STRLEN len) | |
4656 | .Ve | |
4657 | .IP "is_utf8_string_loc" 8 | |
4658 | .IX Xref "is_utf8_string_loc" | |
4659 | .IX Item "is_utf8_string_loc" | |
4660 | Like \fIis_utf8_string()\fR but stores the location of the failure (in the | |
4661 | case of \*(L"utf8ness failure\*(R") or the location s+len (in the case of | |
4662 | \&\*(L"utf8ness success\*(R") in the \f(CW\*(C`ep\*(C'\fR. | |
4663 | .Sp | |
4664 | See also \fIis_utf8_string_loclen()\fR and \fIis_utf8_string()\fR. | |
4665 | .Sp | |
4666 | .Vb 1 | |
4667 | \& bool is_utf8_string_loc(U8 *s, STRLEN len, U8 **p) | |
4668 | .Ve | |
4669 | .IP "is_utf8_string_loclen" 8 | |
4670 | .IX Xref "is_utf8_string_loclen" | |
4671 | .IX Item "is_utf8_string_loclen" | |
4672 | Like \fIis_utf8_string()\fR but stores the location of the failure (in the | |
4673 | case of \*(L"utf8ness failure\*(R") or the location s+len (in the case of | |
4674 | \&\*(L"utf8ness success\*(R") in the \f(CW\*(C`ep\*(C'\fR, and the number of \s-1UTF\-8\s0 | |
4675 | encoded characters in the \f(CW\*(C`el\*(C'\fR. | |
4676 | .Sp | |
4677 | See also \fIis_utf8_string_loc()\fR and \fIis_utf8_string()\fR. | |
4678 | .Sp | |
4679 | .Vb 1 | |
4680 | \& bool is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el) | |
4681 | .Ve | |
4682 | .IP "pv_uni_display" 8 | |
4683 | .IX Xref "pv_uni_display" | |
4684 | .IX Item "pv_uni_display" | |
4685 | Build to the scalar dsv a displayable version of the string spv, | |
4686 | length len, the displayable version being at most pvlim bytes long | |
4687 | (if longer, the rest is truncated and \*(L"...\*(R" will be appended). | |
4688 | .Sp | |
4689 | The flags argument can have \s-1UNI_DISPLAY_ISPRINT\s0 set to display | |
4690 | \&\fIisPRINT()\fRable characters as themselves, \s-1UNI_DISPLAY_BACKSLASH\s0 | |
4691 | to display the \e\e[nrfta\e\e] as the backslashed versions (like '\en') | |
4692 | (\s-1UNI_DISPLAY_BACKSLASH\s0 is preferred over \s-1UNI_DISPLAY_ISPRINT\s0 for \e\e). | |
4693 | \&\s-1UNI_DISPLAY_QQ\s0 (and its alias \s-1UNI_DISPLAY_REGEX\s0) have both | |
4694 | \&\s-1UNI_DISPLAY_BACKSLASH\s0 and \s-1UNI_DISPLAY_ISPRINT\s0 turned on. | |
4695 | .Sp | |
4696 | The pointer to the \s-1PV\s0 of the dsv is returned. | |
4697 | .Sp | |
4698 | .Vb 1 | |
4699 | \& char* pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags) | |
4700 | .Ve | |
4701 | .IP "sv_cat_decode" 8 | |
4702 | .IX Xref "sv_cat_decode" | |
4703 | .IX Item "sv_cat_decode" | |
4704 | The encoding is assumed to be an Encode object, the \s-1PV\s0 of the ssv is | |
4705 | assumed to be octets in that encoding and decoding the input starts | |
4706 | from the position which (\s-1PV\s0 + *offset) pointed to. The dsv will be | |
4707 | concatenated the decoded \s-1UTF\-8\s0 string from ssv. Decoding will terminate | |
4708 | when the string tstr appears in decoding output or the input ends on | |
4709 | the \s-1PV\s0 of the ssv. The value which the offset points will be modified | |
4710 | to the last input position on the ssv. | |
4711 | .Sp | |
4712 | Returns \s-1TRUE\s0 if the terminator was found, else returns \s-1FALSE\s0. | |
4713 | .Sp | |
4714 | .Vb 1 | |
4715 | \& bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen) | |
4716 | .Ve | |
4717 | .IP "sv_recode_to_utf8" 8 | |
4718 | .IX Xref "sv_recode_to_utf8" | |
4719 | .IX Item "sv_recode_to_utf8" | |
4720 | The encoding is assumed to be an Encode object, on entry the \s-1PV\s0 | |
4721 | of the sv is assumed to be octets in that encoding, and the sv | |
4722 | will be converted into Unicode (and \s-1UTF\-8\s0). | |
4723 | .Sp | |
4724 | If the sv already is \s-1UTF\-8\s0 (or if it is not \s-1POK\s0), or if the encoding | |
4725 | is not a reference, nothing is done to the sv. If the encoding is not | |
4726 | an \f(CW\*(C`Encode::XS\*(C'\fR Encoding object, bad things will happen. | |
4727 | (See \fIlib/encoding.pm\fR and Encode). | |
4728 | .Sp | |
4729 | The \s-1PV\s0 of the sv is returned. | |
4730 | .Sp | |
4731 | .Vb 1 | |
4732 | \& char* sv_recode_to_utf8(SV* sv, SV *encoding) | |
4733 | .Ve | |
4734 | .IP "sv_uni_display" 8 | |
4735 | .IX Xref "sv_uni_display" | |
4736 | .IX Item "sv_uni_display" | |
4737 | Build to the scalar dsv a displayable version of the scalar sv, | |
4738 | the displayable version being at most pvlim bytes long | |
4739 | (if longer, the rest is truncated and \*(L"...\*(R" will be appended). | |
4740 | .Sp | |
4741 | The flags argument is as in \fIpv_uni_display()\fR. | |
4742 | .Sp | |
4743 | The pointer to the \s-1PV\s0 of the dsv is returned. | |
4744 | .Sp | |
4745 | .Vb 1 | |
4746 | \& char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags) | |
4747 | .Ve | |
4748 | .IP "to_utf8_case" 8 | |
4749 | .IX Xref "to_utf8_case" | |
4750 | .IX Item "to_utf8_case" | |
4751 | The \*(L"p\*(R" contains the pointer to the \s-1UTF\-8\s0 string encoding | |
4752 | the character that is being converted. | |
4753 | .Sp | |
4754 | The \*(L"ustrp\*(R" is a pointer to the character buffer to put the | |
4755 | conversion result to. The \*(L"lenp\*(R" is a pointer to the length | |
4756 | of the result. | |
4757 | .Sp | |
4758 | The \*(L"swashp\*(R" is a pointer to the swash to use. | |
4759 | .Sp | |
4760 | Both the special and normal mappings are stored lib/unicore/To/Foo.pl, | |
4761 | and loaded by \s-1SWASHGET\s0, using lib/utf8_heavy.pl. The special (usually, | |
4762 | but not always, a multicharacter mapping), is tried first. | |
4763 | .Sp | |
4764 | The \*(L"special\*(R" is a string like \*(L"utf8::ToSpecLower\*(R", which means the | |
4765 | hash \f(CW%utf8::ToSpecLower\fR. The access to the hash is through | |
4766 | \&\fIPerl_to_utf8_case()\fR. | |
4767 | .Sp | |
4768 | The \*(L"normal\*(R" is a string like \*(L"ToLower\*(R" which means the swash | |
4769 | \&\f(CW%utf8::ToLower\fR. | |
4770 | .Sp | |
4771 | .Vb 1 | |
4772 | \& UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, char *normal, char *special) | |
4773 | .Ve | |
4774 | .IP "to_utf8_fold" 8 | |
4775 | .IX Xref "to_utf8_fold" | |
4776 | .IX Item "to_utf8_fold" | |
4777 | Convert the \s-1UTF\-8\s0 encoded character at p to its foldcase version and | |
4778 | store that in \s-1UTF\-8\s0 in ustrp and its length in bytes in lenp. Note | |
4779 | that the ustrp needs to be at least \s-1UTF8_MAXBYTES_CASE+1\s0 bytes since the | |
4780 | foldcase version may be longer than the original character (up to | |
4781 | three characters). | |
4782 | .Sp | |
4783 | The first character of the foldcased version is returned | |
4784 | (but note, as explained above, that there may be more.) | |
4785 | .Sp | |
4786 | .Vb 1 | |
4787 | \& UV to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp) | |
4788 | .Ve | |
4789 | .IP "to_utf8_lower" 8 | |
4790 | .IX Xref "to_utf8_lower" | |
4791 | .IX Item "to_utf8_lower" | |
4792 | Convert the \s-1UTF\-8\s0 encoded character at p to its lowercase version and | |
4793 | store that in \s-1UTF\-8\s0 in ustrp and its length in bytes in lenp. Note | |
4794 | that the ustrp needs to be at least \s-1UTF8_MAXBYTES_CASE+1\s0 bytes since the | |
4795 | lowercase version may be longer than the original character. | |
4796 | .Sp | |
4797 | The first character of the lowercased version is returned | |
4798 | (but note, as explained above, that there may be more.) | |
4799 | .Sp | |
4800 | .Vb 1 | |
4801 | \& UV to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp) | |
4802 | .Ve | |
4803 | .IP "to_utf8_title" 8 | |
4804 | .IX Xref "to_utf8_title" | |
4805 | .IX Item "to_utf8_title" | |
4806 | Convert the \s-1UTF\-8\s0 encoded character at p to its titlecase version and | |
4807 | store that in \s-1UTF\-8\s0 in ustrp and its length in bytes in lenp. Note | |
4808 | that the ustrp needs to be at least \s-1UTF8_MAXBYTES_CASE+1\s0 bytes since the | |
4809 | titlecase version may be longer than the original character. | |
4810 | .Sp | |
4811 | The first character of the titlecased version is returned | |
4812 | (but note, as explained above, that there may be more.) | |
4813 | .Sp | |
4814 | .Vb 1 | |
4815 | \& UV to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp) | |
4816 | .Ve | |
4817 | .IP "to_utf8_upper" 8 | |
4818 | .IX Xref "to_utf8_upper" | |
4819 | .IX Item "to_utf8_upper" | |
4820 | Convert the \s-1UTF\-8\s0 encoded character at p to its uppercase version and | |
4821 | store that in \s-1UTF\-8\s0 in ustrp and its length in bytes in lenp. Note | |
4822 | that the ustrp needs to be at least \s-1UTF8_MAXBYTES_CASE+1\s0 bytes since | |
4823 | the uppercase version may be longer than the original character. | |
4824 | .Sp | |
4825 | The first character of the uppercased version is returned | |
4826 | (but note, as explained above, that there may be more.) | |
4827 | .Sp | |
4828 | .Vb 1 | |
4829 | \& UV to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp) | |
4830 | .Ve | |
4831 | .IP "utf8n_to_uvchr" 8 | |
4832 | .IX Xref "utf8n_to_uvchr" | |
4833 | .IX Item "utf8n_to_uvchr" | |
4834 | Returns the native character value of the first character in the string \f(CW\*(C`s\*(C'\fR | |
4835 | which is assumed to be in \s-1UTF\-8\s0 encoding; \f(CW\*(C`retlen\*(C'\fR will be set to the | |
4836 | length, in bytes, of that character. | |
4837 | .Sp | |
4838 | Allows length and flags to be passed to low level routine. | |
4839 | .Sp | |
4840 | .Vb 1 | |
4841 | \& UV utf8n_to_uvchr(U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags) | |
4842 | .Ve | |
4843 | .IP "utf8n_to_uvuni" 8 | |
4844 | .IX Xref "utf8n_to_uvuni" | |
4845 | .IX Item "utf8n_to_uvuni" | |
4846 | Bottom level \s-1UTF\-8\s0 decode routine. | |
4847 | Returns the unicode code point value of the first character in the string \f(CW\*(C`s\*(C'\fR | |
4848 | which is assumed to be in \s-1UTF\-8\s0 encoding and no longer than \f(CW\*(C`curlen\*(C'\fR; | |
4849 | \&\f(CW\*(C`retlen\*(C'\fR will be set to the length, in bytes, of that character. | |
4850 | .Sp | |
4851 | If \f(CW\*(C`s\*(C'\fR does not point to a well-formed \s-1UTF\-8\s0 character, the behaviour | |
4852 | is dependent on the value of \f(CW\*(C`flags\*(C'\fR: if it contains \s-1UTF8_CHECK_ONLY\s0, | |
4853 | it is assumed that the caller will raise a warning, and this function | |
4854 | will silently just set \f(CW\*(C`retlen\*(C'\fR to \f(CW\*(C`\-1\*(C'\fR and return zero. If the | |
4855 | \&\f(CW\*(C`flags\*(C'\fR does not contain \s-1UTF8_CHECK_ONLY\s0, warnings about | |
4856 | malformations will be given, \f(CW\*(C`retlen\*(C'\fR will be set to the expected | |
4857 | length of the \s-1UTF\-8\s0 character in bytes, and zero will be returned. | |
4858 | .Sp | |
4859 | The \f(CW\*(C`flags\*(C'\fR can also contain various flags to allow deviations from | |
4860 | the strict \s-1UTF\-8\s0 encoding (see \fIutf8.h\fR). | |
4861 | .Sp | |
4862 | Most code should use \fIutf8_to_uvchr()\fR rather than call this directly. | |
4863 | .Sp | |
4864 | .Vb 1 | |
4865 | \& UV utf8n_to_uvuni(U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags) | |
4866 | .Ve | |
4867 | .IP "utf8_distance" 8 | |
4868 | .IX Xref "utf8_distance" | |
4869 | .IX Item "utf8_distance" | |
4870 | Returns the number of \s-1UTF\-8\s0 characters between the \s-1UTF\-8\s0 pointers \f(CW\*(C`a\*(C'\fR | |
4871 | and \f(CW\*(C`b\*(C'\fR. | |
4872 | .Sp | |
4873 | \&\s-1WARNING:\s0 use only if you *know* that the pointers point inside the | |
4874 | same \s-1UTF\-8\s0 buffer. | |
4875 | .Sp | |
4876 | .Vb 1 | |
4877 | \& IV utf8_distance(U8 *a, U8 *b) | |
4878 | .Ve | |
4879 | .IP "utf8_hop" 8 | |
4880 | .IX Xref "utf8_hop" | |
4881 | .IX Item "utf8_hop" | |
4882 | Return the \s-1UTF\-8\s0 pointer \f(CW\*(C`s\*(C'\fR displaced by \f(CW\*(C`off\*(C'\fR characters, either | |
4883 | forward or backward. | |
4884 | .Sp | |
4885 | \&\s-1WARNING:\s0 do not use the following unless you *know* \f(CW\*(C`off\*(C'\fR is within | |
4886 | the \s-1UTF\-8\s0 data pointed to by \f(CW\*(C`s\*(C'\fR *and* that on entry \f(CW\*(C`s\*(C'\fR is aligned | |
4887 | on the first byte of character or just after the last byte of a character. | |
4888 | .Sp | |
4889 | .Vb 1 | |
4890 | \& U8* utf8_hop(U8 *s, I32 off) | |
4891 | .Ve | |
4892 | .IP "utf8_length" 8 | |
4893 | .IX Xref "utf8_length" | |
4894 | .IX Item "utf8_length" | |
4895 | Return the length of the \s-1UTF\-8\s0 char encoded string \f(CW\*(C`s\*(C'\fR in characters. | |
4896 | Stops at \f(CW\*(C`e\*(C'\fR (inclusive). If \f(CW\*(C`e < s\*(C'\fR or if the scan would end | |
4897 | up past \f(CW\*(C`e\*(C'\fR, croaks. | |
4898 | .Sp | |
4899 | .Vb 1 | |
4900 | \& STRLEN utf8_length(U8* s, U8 *e) | |
4901 | .Ve | |
4902 | .IP "utf8_to_bytes" 8 | |
4903 | .IX Xref "utf8_to_bytes" | |
4904 | .IX Item "utf8_to_bytes" | |
4905 | Converts a string \f(CW\*(C`s\*(C'\fR of length \f(CW\*(C`len\*(C'\fR from \s-1UTF\-8\s0 into byte encoding. | |
4906 | Unlike \f(CW\*(C`bytes_to_utf8\*(C'\fR, this over-writes the original string, and | |
4907 | updates len to contain the new length. | |
4908 | Returns zero on failure, setting \f(CW\*(C`len\*(C'\fR to \-1. | |
4909 | .Sp | |
4910 | \&\s-1NOTE:\s0 this function is experimental and may change or be | |
4911 | removed without notice. | |
4912 | .Sp | |
4913 | .Vb 1 | |
4914 | \& U8* utf8_to_bytes(U8 *s, STRLEN *len) | |
4915 | .Ve | |
4916 | .IP "utf8_to_uvchr" 8 | |
4917 | .IX Xref "utf8_to_uvchr" | |
4918 | .IX Item "utf8_to_uvchr" | |
4919 | Returns the native character value of the first character in the string \f(CW\*(C`s\*(C'\fR | |
4920 | which is assumed to be in \s-1UTF\-8\s0 encoding; \f(CW\*(C`retlen\*(C'\fR will be set to the | |
4921 | length, in bytes, of that character. | |
4922 | .Sp | |
4923 | If \f(CW\*(C`s\*(C'\fR does not point to a well-formed \s-1UTF\-8\s0 character, zero is | |
4924 | returned and retlen is set, if possible, to \-1. | |
4925 | .Sp | |
4926 | .Vb 1 | |
4927 | \& UV utf8_to_uvchr(U8 *s, STRLEN *retlen) | |
4928 | .Ve | |
4929 | .IP "utf8_to_uvuni" 8 | |
4930 | .IX Xref "utf8_to_uvuni" | |
4931 | .IX Item "utf8_to_uvuni" | |
4932 | Returns the Unicode code point of the first character in the string \f(CW\*(C`s\*(C'\fR | |
4933 | which is assumed to be in \s-1UTF\-8\s0 encoding; \f(CW\*(C`retlen\*(C'\fR will be set to the | |
4934 | length, in bytes, of that character. | |
4935 | .Sp | |
4936 | This function should only be used when returned \s-1UV\s0 is considered | |
4937 | an index into the Unicode semantic tables (e.g. swashes). | |
4938 | .Sp | |
4939 | If \f(CW\*(C`s\*(C'\fR does not point to a well-formed \s-1UTF\-8\s0 character, zero is | |
4940 | returned and retlen is set, if possible, to \-1. | |
4941 | .Sp | |
4942 | .Vb 1 | |
4943 | \& UV utf8_to_uvuni(U8 *s, STRLEN *retlen) | |
4944 | .Ve | |
4945 | .IP "uvchr_to_utf8" 8 | |
4946 | .IX Xref "uvchr_to_utf8" | |
4947 | .IX Item "uvchr_to_utf8" | |
4948 | Adds the \s-1UTF\-8\s0 representation of the Native codepoint \f(CW\*(C`uv\*(C'\fR to the end | |
4949 | of the string \f(CW\*(C`d\*(C'\fR; \f(CW\*(C`d\*(C'\fR should be have at least \f(CW\*(C`UTF8_MAXBYTES+1\*(C'\fR free | |
4950 | bytes available. The return value is the pointer to the byte after the | |
4951 | end of the new character. In other words, | |
4952 | .Sp | |
4953 | .Vb 1 | |
4954 | \& d = uvchr_to_utf8(d, uv); | |
4955 | .Ve | |
4956 | .Sp | |
4957 | is the recommended wide native character-aware way of saying | |
4958 | .Sp | |
4959 | .Vb 1 | |
4960 | \& *(d++) = uv; | |
4961 | .Ve | |
4962 | .Sp | |
4963 | .Vb 1 | |
4964 | \& U8* uvchr_to_utf8(U8 *d, UV uv) | |
4965 | .Ve | |
4966 | .IP "uvuni_to_utf8_flags" 8 | |
4967 | .IX Xref "uvuni_to_utf8_flags" | |
4968 | .IX Item "uvuni_to_utf8_flags" | |
4969 | Adds the \s-1UTF\-8\s0 representation of the Unicode codepoint \f(CW\*(C`uv\*(C'\fR to the end | |
4970 | of the string \f(CW\*(C`d\*(C'\fR; \f(CW\*(C`d\*(C'\fR should be have at least \f(CW\*(C`UTF8_MAXBYTES+1\*(C'\fR free | |
4971 | bytes available. The return value is the pointer to the byte after the | |
4972 | end of the new character. In other words, | |
4973 | .Sp | |
4974 | .Vb 1 | |
4975 | \& d = uvuni_to_utf8_flags(d, uv, flags); | |
4976 | .Ve | |
4977 | .Sp | |
4978 | or, in most cases, | |
4979 | .Sp | |
4980 | .Vb 1 | |
4981 | \& d = uvuni_to_utf8(d, uv); | |
4982 | .Ve | |
4983 | .Sp | |
4984 | (which is equivalent to) | |
4985 | .Sp | |
4986 | .Vb 1 | |
4987 | \& d = uvuni_to_utf8_flags(d, uv, 0); | |
4988 | .Ve | |
4989 | .Sp | |
4990 | is the recommended Unicode-aware way of saying | |
4991 | .Sp | |
4992 | .Vb 1 | |
4993 | \& *(d++) = uv; | |
4994 | .Ve | |
4995 | .Sp | |
4996 | .Vb 1 | |
4997 | \& U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags) | |
4998 | .Ve | |
4999 | .ie n .SH "Variables created by ""xsubpp""\fP and \f(CW""xsubpp"" internal functions" | |
5000 | .el .SH "Variables created by \f(CWxsubpp\fP and \f(CWxsubpp\fP internal functions" | |
5001 | .IX Header "Variables created by xsubpp and xsubpp internal functions" | |
5002 | .IP "ax" 8 | |
5003 | .IX Xref "ax" | |
5004 | .IX Item "ax" | |
5005 | Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the stack base offset, | |
5006 | used by the \f(CW\*(C`ST\*(C'\fR, \f(CW\*(C`XSprePUSH\*(C'\fR and \f(CW\*(C`XSRETURN\*(C'\fR macros. The \f(CW\*(C`dMARK\*(C'\fR macro | |
5007 | must be called prior to setup the \f(CW\*(C`MARK\*(C'\fR variable. | |
5008 | .Sp | |
5009 | .Vb 1 | |
5010 | \& I32 ax | |
5011 | .Ve | |
5012 | .IP "\s-1CLASS\s0" 8 | |
5013 | .IX Xref "CLASS" | |
5014 | .IX Item "CLASS" | |
5015 | Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the | |
5016 | class name for a \*(C+ \s-1XS\s0 constructor. This is always a \f(CW\*(C`char*\*(C'\fR. See \f(CW\*(C`THIS\*(C'\fR. | |
5017 | .Sp | |
5018 | .Vb 1 | |
5019 | \& char* CLASS | |
5020 | .Ve | |
5021 | .IP "dAX" 8 | |
5022 | .IX Xref "dAX" | |
5023 | .IX Item "dAX" | |
5024 | Sets up the \f(CW\*(C`ax\*(C'\fR variable. | |
5025 | This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR. | |
5026 | .Sp | |
5027 | .Vb 1 | |
5028 | \& dAX; | |
5029 | .Ve | |
5030 | .IP "dAXMARK" 8 | |
5031 | .IX Xref "dAXMARK" | |
5032 | .IX Item "dAXMARK" | |
5033 | Sets up the \f(CW\*(C`ax\*(C'\fR variable and stack marker variable \f(CW\*(C`mark\*(C'\fR. | |
5034 | This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR. | |
5035 | .Sp | |
5036 | .Vb 1 | |
5037 | \& dAXMARK; | |
5038 | .Ve | |
5039 | .IP "dITEMS" 8 | |
5040 | .IX Xref "dITEMS" | |
5041 | .IX Item "dITEMS" | |
5042 | Sets up the \f(CW\*(C`items\*(C'\fR variable. | |
5043 | This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR. | |
5044 | .Sp | |
5045 | .Vb 1 | |
5046 | \& dITEMS; | |
5047 | .Ve | |
5048 | .IP "dXSARGS" 8 | |
5049 | .IX Xref "dXSARGS" | |
5050 | .IX Item "dXSARGS" | |
5051 | Sets up stack and mark pointers for an \s-1XSUB\s0, calling dSP and dMARK. | |
5052 | Sets up the \f(CW\*(C`ax\*(C'\fR and \f(CW\*(C`items\*(C'\fR variables by calling \f(CW\*(C`dAX\*(C'\fR and \f(CW\*(C`dITEMS\*(C'\fR. | |
5053 | This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR. | |
5054 | .Sp | |
5055 | .Vb 1 | |
5056 | \& dXSARGS; | |
5057 | .Ve | |
5058 | .IP "dXSI32" 8 | |
5059 | .IX Xref "dXSI32" | |
5060 | .IX Item "dXSI32" | |
5061 | Sets up the \f(CW\*(C`ix\*(C'\fR variable for an \s-1XSUB\s0 which has aliases. This is usually | |
5062 | handled automatically by \f(CW\*(C`xsubpp\*(C'\fR. | |
5063 | .Sp | |
5064 | .Vb 1 | |
5065 | \& dXSI32; | |
5066 | .Ve | |
5067 | .IP "items" 8 | |
5068 | .IX Xref "items" | |
5069 | .IX Item "items" | |
5070 | Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the number of | |
5071 | items on the stack. See \*(L"Variable\-length Parameter Lists\*(R" in perlxs. | |
5072 | .Sp | |
5073 | .Vb 1 | |
5074 | \& I32 items | |
5075 | .Ve | |
5076 | .IP "ix" 8 | |
5077 | .IX Xref "ix" | |
5078 | .IX Item "ix" | |
5079 | Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate which of an | |
5080 | \&\s-1XSUB\s0's aliases was used to invoke it. See \*(L"The \s-1ALIAS:\s0 Keyword\*(R" in perlxs. | |
5081 | .Sp | |
5082 | .Vb 1 | |
5083 | \& I32 ix | |
5084 | .Ve | |
5085 | .IP "newXSproto" 8 | |
5086 | .IX Xref "newXSproto" | |
5087 | .IX Item "newXSproto" | |
5088 | Used by \f(CW\*(C`xsubpp\*(C'\fR to hook up XSUBs as Perl subs. Adds Perl prototypes to | |
5089 | the subs. | |
5090 | .IP "\s-1RETVAL\s0" 8 | |
5091 | .IX Xref "RETVAL" | |
5092 | .IX Item "RETVAL" | |
5093 | Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to hold the return value for an | |
5094 | \&\s-1XSUB\s0. This is always the proper type for the \s-1XSUB\s0. See | |
5095 | \&\*(L"The \s-1RETVAL\s0 Variable\*(R" in perlxs. | |
5096 | .Sp | |
5097 | .Vb 1 | |
5098 | \& (whatever) RETVAL | |
5099 | .Ve | |
5100 | .IP "\s-1ST\s0" 8 | |
5101 | .IX Xref "ST" | |
5102 | .IX Item "ST" | |
5103 | Used to access elements on the \s-1XSUB\s0's stack. | |
5104 | .Sp | |
5105 | .Vb 1 | |
5106 | \& SV* ST(int ix) | |
5107 | .Ve | |
5108 | .IP "\s-1THIS\s0" 8 | |
5109 | .IX Xref "THIS" | |
5110 | .IX Item "THIS" | |
5111 | Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to designate the object in a \*(C+ | |
5112 | \&\s-1XSUB\s0. This is always the proper type for the \*(C+ object. See \f(CW\*(C`CLASS\*(C'\fR and | |
5113 | \&\*(L"Using \s-1XS\s0 With \*(C+\*(R" in perlxs. | |
5114 | .Sp | |
5115 | .Vb 1 | |
5116 | \& (whatever) THIS | |
5117 | .Ve | |
5118 | .IP "\s-1XS\s0" 8 | |
5119 | .IX Xref "XS" | |
5120 | .IX Item "XS" | |
5121 | Macro to declare an \s-1XSUB\s0 and its C parameter list. This is handled by | |
5122 | \&\f(CW\*(C`xsubpp\*(C'\fR. | |
5123 | .IP "\s-1XS_VERSION\s0" 8 | |
5124 | .IX Xref "XS_VERSION" | |
5125 | .IX Item "XS_VERSION" | |
5126 | The version identifier for an \s-1XS\s0 module. This is usually | |
5127 | handled automatically by \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR. See \f(CW\*(C`XS_VERSION_BOOTCHECK\*(C'\fR. | |
5128 | .IP "\s-1XS_VERSION_BOOTCHECK\s0" 8 | |
5129 | .IX Xref "XS_VERSION_BOOTCHECK" | |
5130 | .IX Item "XS_VERSION_BOOTCHECK" | |
5131 | Macro to verify that a \s-1PM\s0 module's \f(CW$VERSION\fR variable matches the \s-1XS\s0 | |
5132 | module's \f(CW\*(C`XS_VERSION\*(C'\fR variable. This is usually handled automatically by | |
5133 | \&\f(CW\*(C`xsubpp\*(C'\fR. See \*(L"The \s-1VERSIONCHECK:\s0 Keyword\*(R" in perlxs. | |
5134 | .Sp | |
5135 | .Vb 1 | |
5136 | \& XS_VERSION_BOOTCHECK; | |
5137 | .Ve | |
5138 | .SH "Warning and Dieing" | |
5139 | .IX Header "Warning and Dieing" | |
5140 | .IP "croak" 8 | |
5141 | .IX Xref "croak" | |
5142 | .IX Item "croak" | |
5143 | This is the XSUB\-writer's interface to Perl's \f(CW\*(C`die\*(C'\fR function. | |
5144 | Normally call this function the same way you call the C \f(CW\*(C`printf\*(C'\fR | |
5145 | function. Calling \f(CW\*(C`croak\*(C'\fR returns control directly to Perl, | |
5146 | sidestepping the normal C order of execution. See \f(CW\*(C`warn\*(C'\fR. | |
5147 | .Sp | |
5148 | If you want to throw an exception object, assign the object to | |
5149 | \&\f(CW$@\fR and then pass \f(CW\*(C`Nullch\*(C'\fR to \fIcroak()\fR: | |
5150 | .Sp | |
5151 | .Vb 3 | |
5152 | \& errsv = get_sv("@", TRUE); | |
5153 | \& sv_setsv(errsv, exception_object); | |
5154 | \& croak(Nullch); | |
5155 | .Ve | |
5156 | .Sp | |
5157 | .Vb 1 | |
5158 | \& void croak(const char* pat, ...) | |
5159 | .Ve | |
5160 | .IP "warn" 8 | |
5161 | .IX Xref "warn" | |
5162 | .IX Item "warn" | |
5163 | This is the XSUB\-writer's interface to Perl's \f(CW\*(C`warn\*(C'\fR function. Call this | |
5164 | function the same way you call the C \f(CW\*(C`printf\*(C'\fR function. See \f(CW\*(C`croak\*(C'\fR. | |
5165 | .Sp | |
5166 | .Vb 1 | |
5167 | \& void warn(const char* pat, ...) | |
5168 | .Ve | |
5169 | .SH "AUTHORS" | |
5170 | .IX Header "AUTHORS" | |
5171 | Until May 1997, this document was maintained by Jeff Okamoto | |
5172 | <okamoto@corp.hp.com>. It is now maintained as part of Perl itself. | |
5173 | .PP | |
5174 | With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, | |
5175 | Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil | |
5176 | Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, | |
5177 | Stephen McCamant, and Gurusamy Sarathy. | |
5178 | .PP | |
5179 | \&\s-1API\s0 Listing originally by Dean Roehrich <roehrich@cray.com>. | |
5180 | .PP | |
5181 | Updated to be autogenerated from comments in the source by Benjamin Stuhl. | |
5182 | .SH "SEE ALSO" | |
5183 | .IX Header "SEE ALSO" | |
5184 | \&\fIperlguts\fR\|(1), \fIperlxs\fR\|(1), \fIperlxstut\fR\|(1), \fIperlintern\fR\|(1) |