… | |
… | |
15 | The following export tags exist: |
15 | The following export tags exist: |
16 | |
16 | |
17 | :utf8 all functions with utf8 in their name |
17 | :utf8 all functions with utf8 in their name |
18 | :taint all functions with taint in their name |
18 | :taint all functions with taint in their name |
19 | :refcnt all functions with refcnt in their name |
19 | :refcnt all functions with refcnt in their name |
|
|
20 | :ok all *ok-functions. |
20 | |
21 | |
21 | =over 4 |
22 | =over 4 |
22 | |
23 | |
23 | =cut |
24 | =cut |
24 | |
25 | |
25 | package Convert::Scalar; |
26 | package Convert::Scalar; |
26 | |
27 | |
27 | BEGIN { |
28 | BEGIN { |
28 | $VERSION = 0.07; |
29 | $VERSION = 1.12; |
29 | @ISA = qw(Exporter); |
30 | @ISA = qw(Exporter); |
30 | @EXPORT_OK = qw(weaken unmagic grow); |
31 | @EXPORT_OK = qw(readonly readonly_on readonly_off weaken unmagic len grow extend extend_read readall writeall); |
31 | %EXPORT_TAGS = ( |
32 | %EXPORT_TAGS = ( |
32 | taint => [qw(taint untaint tainted)], |
33 | taint => [qw(taint untaint tainted)], |
33 | utf8 => [qw(utf8 utf8_on utf8_off utf8_valid utf8_upgrade utf8_downgrade utf8_encode utf8_decode utf8_length)], |
34 | utf8 => [qw(utf8 utf8_on utf8_off utf8_valid utf8_upgrade utf8_downgrade utf8_encode utf8_decode utf8_length)], |
34 | refcnt => [qw(refcnt refcnt_inc refcnt_dec refcnt_rv refcnt_inc_rv refcnt_dec_rv)], |
35 | refcnt => [qw(refcnt refcnt_inc refcnt_dec refcnt_rv refcnt_inc_rv refcnt_dec_rv)], |
|
|
36 | ok => [qw(ok uok rok pok nok niok)], |
35 | ); |
37 | ); |
36 | |
38 | |
37 | require Exporter; |
39 | require Exporter; |
38 | Exporter::export_ok_tags(keys %EXPORT_TAGS); |
40 | Exporter::export_ok_tags(keys %EXPORT_TAGS); |
39 | |
41 | |
… | |
… | |
92 | |
94 | |
93 | Returns the number of characters in the string, counting wide UTF8 |
95 | Returns the number of characters in the string, counting wide UTF8 |
94 | characters as a single character, independent of wether the scalar is |
96 | characters as a single character, independent of wether the scalar is |
95 | marked as containing bytes or mulitbyte characters. |
97 | marked as containing bytes or mulitbyte characters. |
96 | |
98 | |
|
|
99 | =item $old = readonly scalar[, $new] |
|
|
100 | |
|
|
101 | Returns whether the scalar is currently readonly, and sets or clears the |
|
|
102 | readonly status if a new status is given. |
|
|
103 | |
|
|
104 | =item readonly_on scalar |
|
|
105 | |
|
|
106 | Sets the readonly flag on the scalar. |
|
|
107 | |
|
|
108 | =item readonly_off scalar |
|
|
109 | |
|
|
110 | Clears the readonly flag on the scalar. |
|
|
111 | |
97 | =item unmagic scalar |
112 | =item unmagic scalar, type |
98 | |
113 | |
99 | Removes magic from the scalar. |
114 | Remove the specified magic from the scalar (DANGEROUS!). |
100 | |
115 | |
101 | =item weaken scalar |
116 | =item weaken scalar |
102 | |
117 | |
103 | Weaken a reference. (See also L<WeakRef>). |
118 | Weaken a reference. (See also L<WeakRef>). |
104 | |
119 | |
… | |
… | |
108 | |
123 | |
109 | =item tainted scalar |
124 | =item tainted scalar |
110 | |
125 | |
111 | returns true when the scalar is tainted, false otherwise. |
126 | returns true when the scalar is tainted, false otherwise. |
112 | |
127 | |
113 | =item untaint scalar, type |
128 | =item untaint scalar |
114 | |
129 | |
115 | Remove the specified magic from the scalar |
130 | Remove the tainted flag from the specified scalar. |
116 | (DANGEROUS!), L<perlguts>. L<Untaint>, for a similar but different |
|
|
117 | interface. |
|
|
118 | |
131 | |
|
|
132 | =item length = len scalar |
|
|
133 | |
|
|
134 | Returns SvLEN (scalar), that is, the actual number of bytes allocated to |
|
|
135 | the string value, or C<undef>, is the scalar has no string value. |
|
|
136 | |
119 | =item grow scalar, newlen |
137 | =item scalar = grow scalar, newlen |
120 | |
138 | |
121 | Sets the memory area used for the scalar to the given length, if the |
139 | Sets the memory area used for the scalar to the given length, if the |
122 | current length is less than the new value. This does not affect the |
140 | current length is less than the new value. This does not affect the |
123 | contents of the scalar, but is only useful to "pre-allocate" memory space |
141 | contents of the scalar, but is only useful to "pre-allocate" memory space |
124 | if you know the scalar will grow. The return value is the modified scalar |
142 | if you know the scalar will grow. The return value is the modified scalar |
125 | (the scalar is modified in-place). |
143 | (the scalar is modified in-place). |
126 | |
144 | |
|
|
145 | =item scalar = extend scalar, addlen=64 |
|
|
146 | |
|
|
147 | Reserves enough space in the scalar so that addlen bytes can be appended |
|
|
148 | without reallocating it. The actual contents of the scalar will not be |
|
|
149 | affected. The modified scalar will also be returned. |
|
|
150 | |
|
|
151 | This function is meant to make append workloads efficient - if you append |
|
|
152 | a short string to a scalar many times (millions of times), then perl will |
|
|
153 | have to reallocate and copy the scalar basically every time. |
|
|
154 | |
|
|
155 | If you instead use C<extend $scalar, length $shortstring>, then |
|
|
156 | Convert::Scalar will use a "size to next power of two, roughly" algorithm, |
|
|
157 | so as the scalar grows, perl will have to resize and copy it less and less |
|
|
158 | often. |
|
|
159 | |
|
|
160 | =item nread = extend_read fh, scalar, addlen=64 |
|
|
161 | |
|
|
162 | Calls C<extend scalar, addlen> to ensure some space is available, then |
|
|
163 | do the equivalent of C<sysread> to the end, to try to fill the extra |
|
|
164 | space. Returns how many bytes have been read, C<0> on EOF or undef> on |
|
|
165 | eror, just like C<sysread>. |
|
|
166 | |
|
|
167 | This function is useful to implement many protocols where you read some |
|
|
168 | data, see if it is enough to decode, and if not, read some more, where the |
|
|
169 | naive or easy way of doing this would result in bad performance. |
|
|
170 | |
|
|
171 | =item nread = read_all fh, scalar, length |
|
|
172 | |
|
|
173 | Tries to read C<length> bytes into C<scalar>. Unlike C<read> or |
|
|
174 | C<sysread>, it will try to read more bytes if not all bytes could be read |
|
|
175 | in one go (this is often called C<xread> in C). |
|
|
176 | |
|
|
177 | Returns the total nunmber of bytes read (normally C<length>, unless an |
|
|
178 | error or EOF occured), C<0> on EOF and C<undef> on errors. |
|
|
179 | |
|
|
180 | =item nwritten = write_all fh, scalar |
|
|
181 | |
|
|
182 | Like C<readall>, but for writes - the equivalent of the C<xwrite> function |
|
|
183 | often seen in C. |
|
|
184 | |
127 | =item refcnt scalar[, newrefcnt] |
185 | =item refcnt scalar[, newrefcnt] |
128 | |
186 | |
129 | Returns the current refference count of the given scalar and optionally sets it to |
187 | Returns the current reference count of the given scalar and optionally sets it to |
130 | the given reference count. |
188 | the given reference count. |
131 | |
189 | |
132 | =item refcnt_inc scalar |
190 | =item refcnt_inc scalar |
133 | |
191 | |
134 | Increments the reference count of the given scalar inplace. |
192 | Increments the reference count of the given scalar inplace. |
… | |
… | |
139 | instead if you understand what this function is fore. Better yet: don't |
197 | instead if you understand what this function is fore. Better yet: don't |
140 | use this module in this case. |
198 | use this module in this case. |
141 | |
199 | |
142 | =item refcnt_rv scalar[, newrefcnt] |
200 | =item refcnt_rv scalar[, newrefcnt] |
143 | |
201 | |
144 | Works like C<refcnt>, but dereferences the given reference first. Remember |
202 | Works like C<refcnt>, but dereferences the given reference first. This is |
145 | that taking a reference of some object increases it's reference count, so |
203 | useful to find the reference count of arrays or hashes, which cannot be |
146 | the reference count used by the C<*_rv>-funtions tend to be one higher. |
204 | passed directly. Remember that taking a reference of some object increases |
|
|
205 | it's reference count, so the reference count used by the C<*_rv>-functions |
|
|
206 | tend to be one higher. |
147 | |
207 | |
148 | =item refcnt_inc_rv scalar |
208 | =item refcnt_inc_rv scalar |
149 | |
209 | |
150 | Works like C<refcnt_inc>, but dereferences the given reference first. |
210 | Works like C<refcnt_inc>, but dereferences the given reference first. |
151 | |
211 | |
152 | =item refcnt_dec_rv scalar |
212 | =item refcnt_dec_rv scalar |
153 | |
213 | |
154 | Works like C<refcnt_dec>, but dereferences the given reference first. |
214 | Works like C<refcnt_dec>, but dereferences the given reference first. |
155 | |
215 | |
156 | =cut |
216 | =item ok scalar |
157 | |
217 | |
158 | 1; |
218 | =item uok scalar |
|
|
219 | |
|
|
220 | =item rok scalar |
|
|
221 | |
|
|
222 | =item pok scalar |
|
|
223 | |
|
|
224 | =item nok scalar |
|
|
225 | |
|
|
226 | =item niok scalar |
|
|
227 | |
|
|
228 | Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given scalar, |
|
|
229 | respectively. |
159 | |
230 | |
160 | =back |
231 | =back |
161 | |
232 | |
162 | =head2 CANDIDATES FOR FUTURE RELEASES |
233 | =head2 CANDIDATES FOR FUTURE RELEASES |
163 | |
234 | |
… | |
… | |
169 | sv_pvutf8n_force |
240 | sv_pvutf8n_force |
170 | the sv2xx family |
241 | the sv2xx family |
171 | |
242 | |
172 | =head1 AUTHOR |
243 | =head1 AUTHOR |
173 | |
244 | |
174 | Marc Lehmann <pcg@goof.com> |
245 | Marc Lehmann <schmorp@schmorp.de> |
175 | http://www.goof.com/pcg/marc/ |
246 | http://home.schmorp.de/ |
176 | |
247 | |
177 | =cut |
248 | =cut |
178 | |
249 | |
|
|
250 | 1 |
|
|
251 | |