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 |
$old = readonly scalar[, $new] |
67 |
Returns whether the scalar is currently readonly, and sets or clears |
68 |
the readonly status if a new status is given. |
69 |
|
70 |
readonly_on scalar |
71 |
Sets the readonly flag on the scalar. |
72 |
|
73 |
readonly_off scalar |
74 |
Clears the readonly flag on the scalar. |
75 |
|
76 |
unmagic scalar, type |
77 |
Remove the specified magic from the scalar (DANGEROUS!). |
78 |
|
79 |
weaken scalar |
80 |
Weaken a reference. (See also WeakRef). |
81 |
|
82 |
taint scalar |
83 |
Taint the scalar. |
84 |
|
85 |
tainted scalar |
86 |
returns true when the scalar is tainted, false otherwise. |
87 |
|
88 |
untaint scalar |
89 |
Remove the tainted flag from the specified scalar. |
90 |
|
91 |
length = len scalar |
92 |
Returns SvLEN (scalar), that is, the actual number of bytes |
93 |
allocated to the string value, or "undef", is the scalar has no |
94 |
string value. |
95 |
|
96 |
scalar = grow scalar, newlen |
97 |
Sets the memory area used for the scalar to the given length, if the |
98 |
current length is less than the new value. This does not affect the |
99 |
contents of the scalar, but is only useful to "pre-allocate" memory |
100 |
space if you know the scalar will grow. The return value is the |
101 |
modified scalar (the scalar is modified in-place). |
102 |
|
103 |
scalar = extend scalar, addlen |
104 |
Reserves enough space in the scalar so that addlen bytes can be |
105 |
appended without reallocating it. The actual contents of the scalar |
106 |
will not be affected. The modified scalar will also be returned. |
107 |
|
108 |
This function is meant to make append workloads efficient - if you |
109 |
append a short string to a scalar many times (millions of times), |
110 |
then perl will have to reallocate and copy the scalar basically |
111 |
every time. |
112 |
|
113 |
If you instead use "extend $scalar, length $shortstring", then |
114 |
Convert::Scalar will use a "size to next power of two, roughly" |
115 |
algorithm, so as the scalar grows, perl will have to resize and copy |
116 |
it less and less often. |
117 |
|
118 |
refcnt scalar[, newrefcnt] |
119 |
Returns the current reference count of the given scalar and |
120 |
optionally sets it to the given reference count. |
121 |
|
122 |
refcnt_inc scalar |
123 |
Increments the reference count of the given scalar inplace. |
124 |
|
125 |
refcnt_dec scalar |
126 |
Decrements the reference count of the given scalar inplace. Use |
127 |
"weaken" instead if you understand what this function is fore. |
128 |
Better yet: don't use this module in this case. |
129 |
|
130 |
refcnt_rv scalar[, newrefcnt] |
131 |
Works like "refcnt", but dereferences the given reference first. |
132 |
This is useful to find the reference count of arrays or hashes, |
133 |
which cannot be passed directly. Remember that taking a reference of |
134 |
some object increases it's reference count, so the reference count |
135 |
used by the *_rv-functions tend to be one higher. |
136 |
|
137 |
refcnt_inc_rv scalar |
138 |
Works like "refcnt_inc", but dereferences the given reference first. |
139 |
|
140 |
refcnt_dec_rv scalar |
141 |
Works like "refcnt_dec", but dereferences the given reference first. |
142 |
|
143 |
ok scalar |
144 |
uok scalar |
145 |
rok scalar |
146 |
pok scalar |
147 |
nok scalar |
148 |
niok scalar |
149 |
Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given |
150 |
scalar, respectively. |
151 |
|
152 |
CANDIDATES FOR FUTURE RELEASES |
153 |
The following API functions (perlapi) are considered for future |
154 |
inclusion in this module If you want them, write me. |
155 |
|
156 |
sv_upgrade |
157 |
sv_pvn_force |
158 |
sv_pvutf8n_force |
159 |
the sv2xx family |
160 |
|
161 |
AUTHOR |
162 |
Marc Lehmann <schmorp@schmorp.de> |
163 |
http://home.schmorp.de/ |
164 |
|