ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Convert-Scalar/Scalar.pm
(Generate patch)

Comparing Convert-Scalar/Scalar.pm (file contents):
Revision 1.14 by root, Thu Aug 18 19:07:04 2011 UTC vs.
Revision 1.18 by root, Wed Jul 25 22:34:28 2018 UTC

… …
24=cut 24=cut
25 25
26package Convert::Scalar; 26package Convert::Scalar;
27 27
28BEGIN { 28BEGIN {
29 $VERSION = '1.1'; 29 $VERSION = 1.12;
30 @ISA = qw(Exporter); 30 @ISA = qw(Exporter);
31 @EXPORT_OK = qw(readonly readonly_on readonly_off weaken unmagic len grow extend); 31 @EXPORT_OK = qw(readonly readonly_on readonly_off weaken unmagic len grow extend extend_read readall writeall);
32 %EXPORT_TAGS = ( 32 %EXPORT_TAGS = (
33 taint => [qw(taint untaint tainted)], 33 taint => [qw(taint untaint tainted)],
34 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)],
35 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)], 36 ok => [qw(ok uok rok pok nok niok)],
… …
91removed in future versions). 91removed in future versions).
92 92
93=item utf8_length scalar 93=item utf8_length scalar
94 94
95Returns the number of characters in the string, counting wide UTF8 95Returns the number of characters in the string, counting wide UTF8
96characters as a single character, independent of wether the scalar is 96characters as a single character, independent of whether the scalar is
97marked as containing bytes or mulitbyte characters. 97marked as containing bytes or mulitbyte characters.
98 98
99=item $old = readonly scalar[, $new] 99=item $old = readonly scalar[, $new]
100 100
101Returns whether the scalar is currently readonly, and sets or clears the 101Returns whether the scalar is currently readonly, and sets or clears the
… …
140current length is less than the new value. This does not affect the 140current length is less than the new value. This does not affect the
141contents of the scalar, but is only useful to "pre-allocate" memory space 141contents of the scalar, but is only useful to "pre-allocate" memory space
142if you know the scalar will grow. The return value is the modified scalar 142if you know the scalar will grow. The return value is the modified scalar
143(the scalar is modified in-place). 143(the scalar is modified in-place).
144 144
145=item scalar = extend scalar, addlen 145=item scalar = extend scalar, addlen=64
146 146
147Reserves enough space in the scalar so that addlen bytes can be appended 147Reserves enough space in the scalar so that addlen bytes can be appended
148without reallocating it. The actual contents of the scalar will not be 148without reallocating it. The actual contents of the scalar will not be
149affected. The modified scalar will also be returned. 149affected. The modified scalar will also be returned.
150 150
… …
155If you instead use C<extend $scalar, length $shortstring>, then 155If you instead use C<extend $scalar, length $shortstring>, then
156Convert::Scalar will use a "size to next power of two, roughly" algorithm, 156Convert::Scalar will use a "size to next power of two, roughly" algorithm,
157so as the scalar grows, perl will have to resize and copy it less and less 157so as the scalar grows, perl will have to resize and copy it less and less
158often. 158often.
159 159
160=item nread = extend_read fh, scalar, addlen=64
161
162Calls C<extend scalar, addlen> to ensure some space is available, then
163do the equivalent of C<sysread> to the end, to try to fill the extra
164space. Returns how many bytes have been read, C<0> on EOF or undef> on
165error, just like C<sysread>.
166
167This function is useful to implement many protocols where you read some
168data, see if it is enough to decode, and if not, read some more, where the
169naive or easy way of doing this would result in bad performance.
170
171=item nread = read_all fh, scalar, length
172
173Tries to read C<length> bytes into C<scalar>. Unlike C<read> or
174C<sysread>, it will try to read more bytes if not all bytes could be read
175in one go (this is often called C<xread> in C).
176
177Returns the total nunmber of bytes read (normally C<length>, unless an
178error or EOF occurred), C<0> on EOF and C<undef> on errors.
179
180=item nwritten = write_all fh, scalar
181
182Like C<readall>, but for writes - the equivalent of the C<xwrite> function
183often seen in C.
184
160=item refcnt scalar[, newrefcnt] 185=item refcnt scalar[, newrefcnt]
161 186
162Returns the current reference count of the given scalar and optionally sets it to 187Returns the current reference count of the given scalar and optionally sets it to
163the given reference count. 188the given reference count.
164 189
… …
173use this module in this case. 198use this module in this case.
174 199
175=item refcnt_rv scalar[, newrefcnt] 200=item refcnt_rv scalar[, newrefcnt]
176 201
177Works like C<refcnt>, but dereferences the given reference first. This is 202Works like C<refcnt>, but dereferences the given reference first. This is
178useful to find the reference count of arrays or hashes, which cnanot be 203useful to find the reference count of arrays or hashes, which cannot be
179passed directly. Remember that taking a reference of some object increases 204passed directly. Remember that taking a reference of some object increases
180it's reference count, so the reference count used by the C<*_rv>-functions 205it's reference count, so the reference count used by the C<*_rv>-functions
181tend to be one higher. 206tend to be one higher.
182 207
183=item refcnt_inc_rv scalar 208=item refcnt_inc_rv scalar
… …
200 225
201=item niok scalar 226=item niok scalar
202 227
203Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given scalar, 228Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given scalar,
204respectively. 229respectively.
205
206=cut
207
2081;
209 230
210=back 231=back
211 232
212=head2 CANDIDATES FOR FUTURE RELEASES 233=head2 CANDIDATES FOR FUTURE RELEASES
213 234
… …
224 Marc Lehmann <schmorp@schmorp.de> 245 Marc Lehmann <schmorp@schmorp.de>
225 http://home.schmorp.de/ 246 http://home.schmorp.de/
226 247
227=cut 248=cut
228 249
2501
251

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines