Convert-Scalar/Scalar.pm

=head1 NAME

Convert::Scalar - convert between different representations of perl scalars

=head1 SYNOPSIS

 use Convert::Scalar;

=head1 DESCRIPTION

This module exports various internal perl methods that change the internal
representation or state of a perl scalar. All of these work in-place, that
is, they modify their scalar argument. No functions are exported by default.

The following export tags exist:

 :utf8   all functions with utf8 in their name
 :taint  all functions with taint in their name
 :refcnt all functions with refcnt in their name
 :ok     all *ok-functions.

=over 4

=cut

package Convert::Scalar;

BEGIN {
   $VERSION = 1.12;
   @ISA = qw(Exporter);
   @EXPORT_OK = qw(readonly readonly_on readonly_off weaken unmagic len grow extend extend_read readall writeall);
   %EXPORT_TAGS = (
      taint  => [qw(taint untaint tainted)],
      utf8   => [qw(utf8 utf8_on utf8_off utf8_valid utf8_upgrade utf8_downgrade utf8_encode utf8_decode utf8_length)],
      refcnt => [qw(refcnt refcnt_inc refcnt_dec refcnt_rv refcnt_inc_rv refcnt_dec_rv)],
      ok     => [qw(ok uok rok pok nok niok)],
   );

   require Exporter;
   Exporter::export_ok_tags(keys %EXPORT_TAGS);

   require XSLoader;
   XSLoader::load Convert::Scalar, $VERSION;
}

=item utf8 scalar[, mode]

Returns true when the given scalar is marked as utf8, false otherwise. If
the optional mode argument is given, also forces the interpretation of the
string to utf8 (mode true) or plain bytes (mode false). The actual (byte-)
content is not changed. The return value always reflects the state before
any modification is done.

This function is useful when you "import" utf8-data into perl, or when
some external function (e.g. storing/retrieving from a database) removes
the utf8-flag.

=item utf8_on scalar

Similar to C<utf8 scalar, 1>, but additionally returns the scalar (the
argument is still modified in-place).

=item utf8_off scalar

Similar to C<utf8 scalar, 0>, but additionally returns the scalar (the
argument is still modified in-place).

=item utf8_valid scalar [Perl 5.7]

Returns true if the bytes inside the scalar form a valid utf8 string,
false otherwise (the check is independent of the actual encoding perl
thinks the string is in).

=item utf8_upgrade scalar

Convert the string content of the scalar in-place to its UTF8-encoded form
(and also returns it).

=item utf8_downgrade scalar[, fail_ok=0]

Attempt to convert the string content of the scalar from UTF8-encoded to
ISO-8859-1. This may not be possible if the string contains characters
that cannot be represented in a single byte; if this is the case, it
leaves the scalar unchanged and either returns false or, if C<fail_ok> is
not true (the default), croaks.

=item utf8_encode scalar

Convert the string value of the scalar to UTF8-encoded, but then turn off
the C<SvUTF8> flag so that it looks like bytes to perl again. (Might be
removed in future versions).

=item utf8_length scalar

Returns the number of characters in the string, counting wide UTF8
characters as a single character, independent of whether the scalar is
marked as containing bytes or mulitbyte characters.

=item $old = readonly scalar[, $new]

Returns whether the scalar is currently readonly, and sets or clears the
readonly status if a new status is given.

=item readonly_on scalar

Sets the readonly flag on the scalar.

=item readonly_off scalar

Clears the readonly flag on the scalar.

=item unmagic scalar, type

Remove the specified magic from the scalar (DANGEROUS!).

=item weaken scalar

Weaken a reference. (See also L<WeakRef>).

=item taint scalar

Taint the scalar.

=item tainted scalar

returns true when the scalar is tainted, false otherwise.

=item untaint scalar

Remove the tainted flag from the specified scalar.

=item length = len scalar

Returns SvLEN (scalar), that is, the actual number of bytes allocated to
the string value, or C<undef>, is the scalar has no string value.

=item scalar = grow scalar, newlen

Sets the memory area used for the scalar to the given length, if the
current length is less than the new value. This does not affect the
contents of the scalar, but is only useful to "pre-allocate" memory space
if you know the scalar will grow. The return value is the modified scalar
(the scalar is modified in-place).

=item scalar = extend scalar, addlen=64

Reserves enough space in the scalar so that addlen bytes can be appended
without reallocating it. The actual contents of the scalar will not be
affected. The modified scalar will also be returned.

This function is meant to make append workloads efficient - if you append
a short string to a scalar many times (millions of times), then perl will
have to reallocate and copy the scalar basically every time.

If you instead use C<extend $scalar, length $shortstring>, then
Convert::Scalar will use a "size to next power of two, roughly" algorithm,
so as the scalar grows, perl will have to resize and copy it less and less
often.

=item nread = extend_read fh, scalar, addlen=64

Calls C<extend scalar, addlen> to ensure some space is available, then
do the equivalent of C<sysread> to the end, to try to fill the extra
space. Returns how many bytes have been read, C<0> on EOF or undef> on
error, just like C<sysread>.

This function is useful to implement many protocols where you read some
data, see if it is enough to decode, and if not, read some more, where the
naive or easy way of doing this would result in bad performance.

=item nread = read_all fh, scalar, length

Tries to read C<length> bytes into C<scalar>. Unlike C<read> or
C<sysread>, it will try to read more bytes if not all bytes could be read
in one go (this is often called C<xread> in C).

Returns the total nunmber of bytes read (normally C<length>, unless an
error or EOF occurred), C<0> on EOF and C<undef> on errors.

=item nwritten = write_all fh, scalar

Like C<readall>, but for writes - the equivalent of the C<xwrite> function
often seen in C.

=item refcnt scalar[, newrefcnt]

Returns the current reference count of the given scalar and optionally sets it to
the given reference count.

=item refcnt_inc scalar

Increments the reference count of the given scalar inplace.

=item refcnt_dec scalar

Decrements the reference count of the given scalar inplace. Use C<weaken>
instead if you understand what this function is fore. Better yet: don't
use this module in this case.

=item refcnt_rv scalar[, newrefcnt]

Works like C<refcnt>, but dereferences the given reference first. This is
useful to find the reference count of arrays or hashes, which cannot be
passed directly. Remember that taking a reference of some object increases
it's reference count, so the reference count used by the C<*_rv>-functions
tend to be one higher.

=item refcnt_inc_rv scalar

Works like C<refcnt_inc>, but dereferences the given reference first.

=item refcnt_dec_rv scalar

Works like C<refcnt_dec>, but dereferences the given reference first.

=item ok scalar

=item uok scalar

=item rok scalar

=item pok scalar

=item nok scalar

=item niok scalar

Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given scalar,
respectively.

=back

=head2 CANDIDATES FOR FUTURE RELEASES

The following API functions (L<perlapi>) are considered for future
inclusion in this module If you want them, write me.

 sv_upgrade
 sv_pvn_force
 sv_pvutf8n_force
 the sv2xx family

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

1

Revision:	1.18
Committed:	Wed Jul 25 22:34:28 2018 UTC (5 years, 9 months ago) by root
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.17:	+3 -3 lines
Log Message:	* empty log message *
#	Content
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	$VERSION = 1.12;
30	@ISA = qw(Exporter);
31	@EXPORT_OK = qw(readonly readonly_on readonly_off weaken unmagic len grow extend extend_read readall writeall);
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	require Exporter;
40	Exporter::export_ok_tags(keys %EXPORT_TAGS);
41
42	require XSLoader;
43	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<utf8 scalar, 1>, but additionally returns the scalar (the
61	argument is still modified in-place).
62
63	=item utf8_off scalar
64
65	Similar to C<utf8 scalar, 0>, 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<fail_ok> 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<SvUTF8> 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 whether 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<WeakRef>).
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<undef>, 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=64
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<extend $scalar, length $shortstring>, 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 nread = extend_read fh, scalar, addlen=64
161
162	Calls C<extend scalar, addlen> to ensure some space is available, then
163	do the equivalent of C<sysread> to the end, to try to fill the extra
164	space. Returns how many bytes have been read, C<0> on EOF or undef> on
165	error, just like C<sysread>.
166
167	This function is useful to implement many protocols where you read some
168	data, see if it is enough to decode, and if not, read some more, where the
169	naive or easy way of doing this would result in bad performance.
170
171	=item nread = read_all fh, scalar, length
172
173	Tries to read C<length> bytes into C<scalar>. Unlike C<read> or
174	C<sysread>, it will try to read more bytes if not all bytes could be read
175	in one go (this is often called C<xread> in C).
176
177	Returns the total nunmber of bytes read (normally C<length>, unless an
178	error or EOF occurred), C<0> on EOF and C<undef> on errors.
179
180	=item nwritten = write_all fh, scalar
181
182	Like C<readall>, but for writes - the equivalent of the C<xwrite> function
183	often seen in C.
184
185	=item refcnt scalar[, newrefcnt]
186
187	Returns the current reference count of the given scalar and optionally sets it to
188	the given reference count.
189
190	=item refcnt_inc scalar
191
192	Increments the reference count of the given scalar inplace.
193
194	=item refcnt_dec scalar
195
196	Decrements the reference count of the given scalar inplace. Use C<weaken>
197	instead if you understand what this function is fore. Better yet: don't
198	use this module in this case.
199
200	=item refcnt_rv scalar[, newrefcnt]
201
202	Works like C<refcnt>, but dereferences the given reference first. This is
203	useful to find the reference count of arrays or hashes, which cannot be
204	passed directly. Remember that taking a reference of some object increases
205	it's reference count, so the reference count used by the C<*_rv>-functions
206	tend to be one higher.
207
208	=item refcnt_inc_rv scalar
209
210	Works like C<refcnt_inc>, but dereferences the given reference first.
211
212	=item refcnt_dec_rv scalar
213
214	Works like C<refcnt_dec>, but dereferences the given reference first.
215
216	=item ok scalar
217
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
228	Calls SvOK, SvUOK, SvROK, SvPOK, SvNOK or SvNIOK on the given scalar,
229	respectively.
230
231	=back
232
233	=head2 CANDIDATES FOR FUTURE RELEASES
234
235	The following API functions (L<perlapi>) are considered for future
236	inclusion in this module If you want them, write me.
237
238	sv_upgrade
239	sv_pvn_force
240	sv_pvutf8n_force
241	the sv2xx family
242
243	=head1 AUTHOR
244
245	Marc Lehmann <schmorp@schmorp.de>
246	http://home.schmorp.de/
247
248	=cut
249
250	1
251