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.10 by root, Fri Nov 26 21:05:13 2004 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.02'; 29 $VERSION = 1.12;
30 @ISA = qw(Exporter); 30 @ISA = qw(Exporter);
31 @EXPORT_OK = qw(weaken unmagic grow); 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]
100
101Returns whether the scalar is currently readonly, and sets or clears the
102readonly status if a new status is given.
103
104=item readonly_on scalar
105
106Sets the readonly flag on the scalar.
107
108=item readonly_off scalar
109
110Clears the readonly flag on the scalar.
111
99=item unmagic scalar, type 112=item unmagic scalar, type
100 113
101Remove the specified magic from the scalar (DANGEROUS!). 114Remove the specified magic from the scalar (DANGEROUS!).
102 115
103=item weaken scalar 116=item weaken scalar
… …
114 127
115=item untaint scalar 128=item untaint scalar
116 129
117Remove the tainted flag from the specified scalar. 130Remove the tainted flag from the specified scalar.
118 131
132=item length = len scalar
133
134Returns SvLEN (scalar), that is, the actual number of bytes allocated to
135the 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
121Sets the memory area used for the scalar to the given length, if the 139Sets the memory area used for the scalar to the given length, if the
122current 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
123contents 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
124if 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
125(the scalar is modified in-place). 143(the scalar is modified in-place).
126 144
145=item scalar = extend scalar, addlen=64
146
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
149affected. The modified scalar will also be returned.
150
151This function is meant to make append workloads efficient - if you append
152a short string to a scalar many times (millions of times), then perl will
153have to reallocate and copy the scalar basically every time.
154
155If you instead use C<extend $scalar, length $shortstring>, then
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
158often.
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
127=item refcnt scalar[, newrefcnt] 185=item refcnt scalar[, newrefcnt]
128 186
129Returns 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
130the given reference count. 188the given reference count.
131 189
… …
140use this module in this case. 198use this module in this case.
141 199
142=item refcnt_rv scalar[, newrefcnt] 200=item refcnt_rv scalar[, newrefcnt]
143 201
144Works like C<refcnt>, but dereferences the given reference first. This is 202Works like C<refcnt>, but dereferences the given reference first. This is
145useful 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
146passed directly. Remember that taking a reference of some object increases 204passed directly. Remember that taking a reference of some object increases
147it'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
148tend to be one higher. 206tend to be one higher.
149 207
150=item refcnt_inc_rv scalar 208=item refcnt_inc_rv scalar
… …
167 225
168=item niok scalar 226=item niok scalar
169 227
170Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given scalar, 228Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given scalar,
171respectively. 229respectively.
172
173=cut
174
1751;
176 230
177=back 231=back
178 232
179=head2 CANDIDATES FOR FUTURE RELEASES 233=head2 CANDIDATES FOR FUTURE RELEASES
180 234
… …
186 sv_pvutf8n_force 240 sv_pvutf8n_force
187 the sv2xx family 241 the sv2xx family
188 242
189=head1 AUTHOR 243=head1 AUTHOR
190 244
191 Marc Lehmann <pcg@goof.com> 245 Marc Lehmann <schmorp@schmorp.de>
192 http://www.goof.com/pcg/marc/ 246 http://home.schmorp.de/
193 247
194=cut 248=cut
195 249
2501
251

Diff Legend

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