1 |
NAME |
2 |
Convert::Scalar - convert between different representations of perl |
3 |
scalars |
4 |
|
5 |
SYNOPSIS |
6 |
use Convert::Scalar; |
7 |
|
8 |
DESCRIPTION |
9 |
This module exports various internal perl methods that change the |
10 |
internal representation or state of a perl scalar. All of these work |
11 |
in-place, that is, they modify their scalar argument. No functions are |
12 |
exported by default. |
13 |
|
14 |
The following export tags exist: |
15 |
|
16 |
:utf8 all functions with utf8 in their name |
17 |
:taint all functions with taint in their name |
18 |
:refcnt all functions with refcnt in their name |
19 |
:ok all *ok-functions. |
20 |
|
21 |
utf8 scalar[, mode] |
22 |
Returns true when the given scalar is marked as utf8, false |
23 |
otherwise. If the optional mode argument is given, also forces the |
24 |
interpretation of the string to utf8 (mode true) or plain bytes |
25 |
(mode false). The actual (byte-) content is not changed. The return |
26 |
value always reflects the state before any modification is done. |
27 |
|
28 |
This function is useful when you "import" utf8-data into perl, or |
29 |
when some external function (e.g. storing/retrieving from a |
30 |
database) removes the utf8-flag. |
31 |
|
32 |
utf8_on scalar |
33 |
Similar to "utf8 scalar, 1", but additionally returns the scalar |
34 |
(the argument is still modified in-place). |
35 |
|
36 |
utf8_off scalar |
37 |
Similar to "utf8 scalar, 0", but additionally returns the scalar |
38 |
(the argument is still modified in-place). |
39 |
|
40 |
utf8_valid scalar [Perl 5.7] |
41 |
Returns true if the bytes inside the scalar form a valid utf8 |
42 |
string, false otherwise (the check is independent of the actual |
43 |
encoding perl thinks the string is in). |
44 |
|
45 |
utf8_upgrade scalar |
46 |
Convert the string content of the scalar in-place to its |
47 |
UTF8-encoded form (and also returns it). |
48 |
|
49 |
utf8_downgrade scalar[, fail_ok=0] |
50 |
Attempt to convert the string content of the scalar from |
51 |
UTF8-encoded to ISO-8859-1. This may not be possible if the string |
52 |
contains characters that cannot be represented in a single byte; if |
53 |
this is the case, it leaves the scalar unchanged and either returns |
54 |
false or, if "fail_ok" is not true (the default), croaks. |
55 |
|
56 |
utf8_encode scalar |
57 |
Convert the string value of the scalar to UTF8-encoded, but then |
58 |
turn off the "SvUTF8" flag so that it looks like bytes to perl |
59 |
again. (Might be removed in future versions). |
60 |
|
61 |
utf8_length scalar |
62 |
Returns the number of characters in the string, counting wide UTF8 |
63 |
characters as a single character, independent of wether the scalar |
64 |
is marked as containing bytes or mulitbyte characters. |
65 |
|
66 |
unmagic scalar, type |
67 |
Remove the specified magic from the scalar (DANGEROUS!). |
68 |
|
69 |
weaken scalar |
70 |
Weaken a reference. (See also WeakRef). |
71 |
|
72 |
taint scalar |
73 |
Taint the scalar. |
74 |
|
75 |
tainted scalar |
76 |
returns true when the scalar is tainted, false otherwise. |
77 |
|
78 |
untaint scalar |
79 |
Remove the tainted flag from the specified scalar. |
80 |
|
81 |
grow scalar, newlen |
82 |
Sets the memory area used for the scalar to the given length, if the |
83 |
current length is less than the new value. This does not affect the |
84 |
contents of the scalar, but is only useful to "pre-allocate" memory |
85 |
space if you know the scalar will grow. The return value is the |
86 |
modified scalar (the scalar is modified in-place). |
87 |
|
88 |
refcnt scalar[, newrefcnt] |
89 |
Returns the current reference count of the given scalar and |
90 |
optionally sets it to the given reference count. |
91 |
|
92 |
refcnt_inc scalar |
93 |
Increments the reference count of the given scalar inplace. |
94 |
|
95 |
refcnt_dec scalar |
96 |
Decrements the reference count of the given scalar inplace. Use |
97 |
"weaken" instead if you understand what this function is fore. |
98 |
Better yet: don't use this module in this case. |
99 |
|
100 |
refcnt_rv scalar[, newrefcnt] |
101 |
Works like "refcnt", but dereferences the given reference first. |
102 |
This is useful to find the reference count of arrays or hashes, |
103 |
which cnanot be passed directly. Remember that taking a reference of |
104 |
some object increases it's reference count, so the reference count |
105 |
used by the *_rv-functions tend to be one higher. |
106 |
|
107 |
refcnt_inc_rv scalar |
108 |
Works like "refcnt_inc", but dereferences the given reference first. |
109 |
|
110 |
refcnt_dec_rv scalar |
111 |
Works like "refcnt_dec", but dereferences the given reference first. |
112 |
|
113 |
ok scalar |
114 |
uok scalar |
115 |
rok scalar |
116 |
pok scalar |
117 |
nok scalar |
118 |
niok scalar |
119 |
Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given |
120 |
scalar, respectively. |
121 |
|
122 |
CANDIDATES FOR FUTURE RELEASES |
123 |
The following API functions (perlapi) are considered for future |
124 |
inclusion in this module If you want them, write me. |
125 |
|
126 |
sv_upgrade |
127 |
sv_pvn_force |
128 |
sv_pvutf8n_force |
129 |
the sv2xx family |
130 |
|
131 |
AUTHOR |
132 |
Marc Lehmann <schmorp@schmorp.de> |
133 |
http://home.schmorp.de/ |
134 |
|