1 |
root |
1.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 |
root |
1.2 |
$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 |
root |
1.1 |
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 |
root |
1.2 |
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 |
root |
1.1 |
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 |
root |
1.4 |
scalar = extend scalar, addlen=64 |
104 |
root |
1.2 |
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 |
root |
1.4 |
nread = extend_read fh, scalar, addlen=64 |
119 |
|
|
Calls "extend scalar, addlen" to ensure some space is available, |
120 |
|
|
then do the equivalent of "sysread" to the end, to try to fill the |
121 |
|
|
extra space. Returns how many bytes have been read, 0 on EOF or |
122 |
|
|
undef> on eror, just like "sysread". |
123 |
|
|
|
124 |
|
|
This function is useful to implement many protocols where you read |
125 |
|
|
some data, see if it is enough to decode, and if not, read some |
126 |
|
|
more, where the naive or easy way of doing this would result in bad |
127 |
|
|
performance. |
128 |
|
|
|
129 |
|
|
nread = read_all fh, scalar, length |
130 |
|
|
Tries to read "length" bytes into "scalar". Unlike "read" or |
131 |
|
|
"sysread", it will try to read more bytes if not all bytes could be |
132 |
|
|
read in one go (this is often called "xread" in C). |
133 |
|
|
|
134 |
|
|
Returns the total nunmber of bytes read (normally "length", unless |
135 |
|
|
an error or EOF occured), 0 on EOF and "undef" on errors. |
136 |
|
|
|
137 |
|
|
nwritten = write_all fh, scalar |
138 |
|
|
Like "readall", but for writes - the equivalent of the "xwrite" |
139 |
|
|
function often seen in C. |
140 |
|
|
|
141 |
root |
1.1 |
refcnt scalar[, newrefcnt] |
142 |
|
|
Returns the current reference count of the given scalar and |
143 |
|
|
optionally sets it to the given reference count. |
144 |
|
|
|
145 |
|
|
refcnt_inc scalar |
146 |
|
|
Increments the reference count of the given scalar inplace. |
147 |
|
|
|
148 |
|
|
refcnt_dec scalar |
149 |
|
|
Decrements the reference count of the given scalar inplace. Use |
150 |
|
|
"weaken" instead if you understand what this function is fore. |
151 |
|
|
Better yet: don't use this module in this case. |
152 |
|
|
|
153 |
|
|
refcnt_rv scalar[, newrefcnt] |
154 |
|
|
Works like "refcnt", but dereferences the given reference first. |
155 |
|
|
This is useful to find the reference count of arrays or hashes, |
156 |
root |
1.3 |
which cannot be passed directly. Remember that taking a reference of |
157 |
root |
1.1 |
some object increases it's reference count, so the reference count |
158 |
|
|
used by the *_rv-functions tend to be one higher. |
159 |
|
|
|
160 |
|
|
refcnt_inc_rv scalar |
161 |
|
|
Works like "refcnt_inc", but dereferences the given reference first. |
162 |
|
|
|
163 |
|
|
refcnt_dec_rv scalar |
164 |
|
|
Works like "refcnt_dec", but dereferences the given reference first. |
165 |
|
|
|
166 |
|
|
ok scalar |
167 |
|
|
uok scalar |
168 |
|
|
rok scalar |
169 |
|
|
pok scalar |
170 |
|
|
nok scalar |
171 |
|
|
niok scalar |
172 |
|
|
Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given |
173 |
|
|
scalar, respectively. |
174 |
|
|
|
175 |
|
|
CANDIDATES FOR FUTURE RELEASES |
176 |
|
|
The following API functions (perlapi) are considered for future |
177 |
|
|
inclusion in this module If you want them, write me. |
178 |
|
|
|
179 |
|
|
sv_upgrade |
180 |
|
|
sv_pvn_force |
181 |
|
|
sv_pvutf8n_force |
182 |
|
|
the sv2xx family |
183 |
|
|
|
184 |
|
|
AUTHOR |
185 |
|
|
Marc Lehmann <schmorp@schmorp.de> |
186 |
|
|
http://home.schmorp.de/ |
187 |
|
|
|