File Coverage

blib/lib/Convert/Scalar.pm
Criterion Covered Total %
statement 8 8 100.0
branch n/a
condition n/a
subroutine 1 1 100.0
pod n/a
total 9 9 100.0


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Convert::Scalar - convert between different representations of perl scalars
4              
5             =head1 SYNOPSIS
6              
7             use Convert::Scalar;
8              
9             =head1 DESCRIPTION
10              
11             This module exports various internal perl methods that change the internal
12             representation or state of a perl scalar. All of these work in-place, that
13             is, they modify their scalar argument. No functions are exported by default.
14              
15             The following export tags exist:
16              
17             :utf8 all functions with utf8 in their name
18             :taint all functions with taint in their name
19             :refcnt all functions with refcnt in their name
20             :ok all *ok-functions.
21              
22             =over 4
23              
24             =cut
25              
26             package Convert::Scalar;
27              
28             BEGIN {
29 4     4   4660 $VERSION = '1.1';
30 4         59 @ISA = qw(Exporter);
31 4         16 @EXPORT_OK = qw(readonly readonly_on readonly_off weaken unmagic len grow extend);
32 4         32 %EXPORT_TAGS = (
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)],
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)],
37             );
38              
39 4         24 require Exporter;
40 4         271 Exporter::export_ok_tags(keys %EXPORT_TAGS);
41              
42 4         21 require XSLoader;
43 4         2995 XSLoader::load Convert::Scalar, $VERSION;
44             }
45              
46             =item utf8 scalar[, mode]
47              
48             Returns true when the given scalar is marked as utf8, false otherwise. If
49             the optional mode argument is given, also forces the interpretation of the
50             string to utf8 (mode true) or plain bytes (mode false). The actual (byte-)
51             content is not changed. The return value always reflects the state before
52             any modification is done.
53              
54             This function is useful when you "import" utf8-data into perl, or when
55             some external function (e.g. storing/retrieving from a database) removes
56             the utf8-flag.
57              
58             =item utf8_on scalar
59              
60             Similar to C, but additionally returns the scalar (the
61             argument is still modified in-place).
62              
63             =item utf8_off scalar
64              
65             Similar to C, but additionally returns the scalar (the
66             argument is still modified in-place).
67              
68             =item utf8_valid scalar [Perl 5.7]
69              
70             Returns true if the bytes inside the scalar form a valid utf8 string,
71             false otherwise (the check is independent of the actual encoding perl
72             thinks the string is in).
73              
74             =item utf8_upgrade scalar
75              
76             Convert the string content of the scalar in-place to its UTF8-encoded form
77             (and also returns it).
78              
79             =item utf8_downgrade scalar[, fail_ok=0]
80              
81             Attempt to convert the string content of the scalar from UTF8-encoded to
82             ISO-8859-1. This may not be possible if the string contains characters
83             that cannot be represented in a single byte; if this is the case, it
84             leaves the scalar unchanged and either returns false or, if C is
85             not true (the default), croaks.
86              
87             =item utf8_encode scalar
88              
89             Convert the string value of the scalar to UTF8-encoded, but then turn off
90             the C flag so that it looks like bytes to perl again. (Might be
91             removed in future versions).
92              
93             =item utf8_length scalar
94              
95             Returns the number of characters in the string, counting wide UTF8
96             characters as a single character, independent of wether the scalar is
97             marked as containing bytes or mulitbyte characters.
98              
99             =item $old = readonly scalar[, $new]
100              
101             Returns whether the scalar is currently readonly, and sets or clears the
102             readonly status if a new status is given.
103              
104             =item readonly_on scalar
105              
106             Sets the readonly flag on the scalar.
107              
108             =item readonly_off scalar
109              
110             Clears the readonly flag on the scalar.
111              
112             =item unmagic scalar, type
113              
114             Remove the specified magic from the scalar (DANGEROUS!).
115              
116             =item weaken scalar
117              
118             Weaken a reference. (See also L).
119              
120             =item taint scalar
121              
122             Taint the scalar.
123              
124             =item tainted scalar
125              
126             returns true when the scalar is tainted, false otherwise.
127              
128             =item untaint scalar
129              
130             Remove the tainted flag from the specified scalar.
131              
132             =item length = len scalar
133              
134             Returns SvLEN (scalar), that is, the actual number of bytes allocated to
135             the string value, or C, is the scalar has no string value.
136              
137             =item scalar = grow scalar, newlen
138              
139             Sets the memory area used for the scalar to the given length, if the
140             current length is less than the new value. This does not affect the
141             contents of the scalar, but is only useful to "pre-allocate" memory space
142             if you know the scalar will grow. The return value is the modified scalar
143             (the scalar is modified in-place).
144              
145             =item scalar = extend scalar, addlen
146              
147             Reserves enough space in the scalar so that addlen bytes can be appended
148             without reallocating it. The actual contents of the scalar will not be
149             affected. The modified scalar will also be returned.
150              
151             This function is meant to make append workloads efficient - if you append
152             a short string to a scalar many times (millions of times), then perl will
153             have to reallocate and copy the scalar basically every time.
154              
155             If you instead use C, then
156             Convert::Scalar will use a "size to next power of two, roughly" algorithm,
157             so as the scalar grows, perl will have to resize and copy it less and less
158             often.
159              
160             =item refcnt scalar[, newrefcnt]
161              
162             Returns the current reference count of the given scalar and optionally sets it to
163             the given reference count.
164              
165             =item refcnt_inc scalar
166              
167             Increments the reference count of the given scalar inplace.
168              
169             =item refcnt_dec scalar
170              
171             Decrements the reference count of the given scalar inplace. Use C
172             instead if you understand what this function is fore. Better yet: don't
173             use this module in this case.
174              
175             =item refcnt_rv scalar[, newrefcnt]
176              
177             Works like C, but dereferences the given reference first. This is
178             useful to find the reference count of arrays or hashes, which cnanot be
179             passed directly. Remember that taking a reference of some object increases
180             it's reference count, so the reference count used by the C<*_rv>-functions
181             tend to be one higher.
182              
183             =item refcnt_inc_rv scalar
184              
185             Works like C, but dereferences the given reference first.
186              
187             =item refcnt_dec_rv scalar
188              
189             Works like C, but dereferences the given reference first.
190              
191             =item ok scalar
192              
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              
203             Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given scalar,
204             respectively.
205              
206             =cut
207              
208             1;
209              
210             =back
211              
212             =head2 CANDIDATES FOR FUTURE RELEASES
213              
214             The following API functions (L) are considered for future
215             inclusion in this module If you want them, write me.
216              
217             sv_upgrade
218             sv_pvn_force
219             sv_pvutf8n_force
220             the sv2xx family
221              
222             =head1 AUTHOR
223              
224             Marc Lehmann
225             http://home.schmorp.de/
226              
227             =cut
228