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.13 by root, Fri Mar 7 10:33:46 2008 UTC vs.
Revision 1.14 by root, Thu Aug 18 19:07:04 2011 UTC

… …
24=cut 24=cut
25 25
26package Convert::Scalar; 26package Convert::Scalar;
27 27
28BEGIN { 28BEGIN {
29 $VERSION = '1.04'; 29 $VERSION = '1.1';
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);
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)],
… …
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 wether 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
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

Diff Legend

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