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

Comparing cvsroot/Convert-Scalar/Scalar.pm (file contents):
Revision 1.2 by root, Sun Jan 20 04:23:59 2002 UTC vs.
Revision 1.17 by root, Tue Aug 15 07:29:06 2017 UTC

… …
15The following export tags exist: 15The 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
25package Convert::Scalar; 26package Convert::Scalar;
26 27
27BEGIN { 28BEGIN {
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
93Returns the number of characters in the string, counting wide UTF8 95Returns the number of characters in the string, counting wide UTF8
94characters as a single character, independent of wether the scalar is 96characters as a single character, independent of wether the scalar is
95marked as containing bytes or mulitbyte characters. 97marked as containing bytes or mulitbyte characters.
96 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
97=item unmagic scalar 112=item unmagic scalar, type
98 113
99Removes magic from the scalar. 114Remove the specified magic from the scalar (DANGEROUS!).
100 115
101=item weaken scalar 116=item weaken scalar
102 117
103Weaken a reference. (See also L<WeakRef>). 118Weaken a reference. (See also L<WeakRef>).
104 119
… …
108 123
109=item tainted scalar 124=item tainted scalar
110 125
111returns true when the scalar is tainted, false otherwise. 126returns true when the scalar is tainted, false otherwise.
112 127
113=item untaint scalar, type 128=item untaint scalar
114 129
115Remove the specified magic from the scalar 130Remove the tainted flag from the specified scalar.
116(DANGEROUS!), L<perlguts>. L<Untaint>, for a similar but different
117interface.
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
165eror, 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 occured), 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 refference 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
132=item refcnt_inc scalar 190=item refcnt_inc scalar
133 191
134Increments the reference count of the given scalar inplace. 192Increments the reference count of the given scalar inplace.
… …
139instead if you understand what this function is fore. Better yet: don't 197instead if you understand what this function is fore. Better yet: don't
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. Remember 202Works like C<refcnt>, but dereferences the given reference first. This is
145that taking a reference of some object increases it's reference count, so 203useful to find the reference count of arrays or hashes, which cannot be
146the reference count used by the C<*_rv>-funtions tend to be one higher. 204passed directly. Remember that taking a reference of some object increases
205it's reference count, so the reference count used by the C<*_rv>-functions
206tend to be one higher.
147 207
148=item refcnt_inc_rv scalar 208=item refcnt_inc_rv scalar
149 209
150Works like C<refcnt_inc>, but dereferences the given reference first. 210Works 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
154Works like C<refcnt_dec>, but dereferences the given reference first. 214Works like C<refcnt_dec>, but dereferences the given reference first.
155 215
156=cut 216=item ok scalar
157 217
1581; 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
228Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given scalar,
229respectively.
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
2501
251

Diff Legend

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