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