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.3 by root, Fri Jul 5 11:44:55 2002 UTC vs.
Revision 1.16 by root, Thu Jun 25 14:04:32 2015 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.08; 29 $VERSION = 1.11;
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);
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
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
127=item refcnt scalar[, newrefcnt] 160=item refcnt scalar[, newrefcnt]
128 161
129Returns the current reference count of the given scalar and optionally sets it to 162Returns the current reference count of the given scalar and optionally sets it to
130the given reference count. 163the given reference count.
131 164
… …
139instead if you understand what this function is fore. Better yet: don't 172instead if you understand what this function is fore. Better yet: don't
140use this module in this case. 173use this module in this case.
141 174
142=item refcnt_rv scalar[, newrefcnt] 175=item refcnt_rv scalar[, newrefcnt]
143 176
144Works like C<refcnt>, but dereferences the given reference first. Remember 177Works like C<refcnt>, but dereferences the given reference first. This is
145that taking a reference of some object increases it's reference count, so 178useful 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. 179passed directly. Remember that taking a reference of some object increases
180it's reference count, so the reference count used by the C<*_rv>-functions
181tend to be one higher.
147 182
148=item refcnt_inc_rv scalar 183=item refcnt_inc_rv scalar
149 184
150Works like C<refcnt_inc>, but dereferences the given reference first. 185Works like C<refcnt_inc>, but dereferences the given reference first.
151 186
152=item refcnt_dec_rv scalar 187=item refcnt_dec_rv scalar
153 188
154Works like C<refcnt_dec>, but dereferences the given reference first. 189Works like C<refcnt_dec>, but dereferences the given reference first.
155 190
156=cut 191=item ok scalar
157 192
1581; 193=item uok scalar
194
195=item rok scalar
196
197=item pok scalar
198
199=item nok scalar
200
201=item niok scalar
202
203Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given scalar,
204respectively.
159 205
160=back 206=back
161 207
162=head2 CANDIDATES FOR FUTURE RELEASES 208=head2 CANDIDATES FOR FUTURE RELEASES
163 209
… …
169 sv_pvutf8n_force 215 sv_pvutf8n_force
170 the sv2xx family 216 the sv2xx family
171 217
172=head1 AUTHOR 218=head1 AUTHOR
173 219
174 Marc Lehmann <pcg@goof.com> 220 Marc Lehmann <schmorp@schmorp.de>
175 http://www.goof.com/pcg/marc/ 221 http://home.schmorp.de/
176 222
177=cut 223=cut
178 224
2251
226

Diff Legend

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