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

=over 4

=cut

package Convert::Scalar;

BEGIN {
   $VERSION = 0.08;
   @ISA = qw(Exporter);
   @EXPORT_OK = qw(weaken unmagic grow);
   %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)],
   );

   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 wether the scalar is
marked as containing bytes or mulitbyte characters.

=item unmagic scalar

Removes magic from the scalar.

=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, type

Remove the specified magic from the scalar
(DANGEROUS!), L<perlguts>. L<Untaint>, for a similar but different
interface.

=item 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 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. Remember
that taking a reference of some object increases it's reference count, so
the reference count used by the C<*_rv>-funtions 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.

=cut

1;

=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 <pcg@goof.com>
 http://www.goof.com/pcg/marc/

=cut

Revision:	1.3
Committed:	Fri Jul 5 11:44:55 2002 UTC (21 years, 10 months ago) by root
Branch:	MAIN
Changes since 1.2:	+2 -2 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
21	=over 4
22
23	=cut
24
25	package Convert::Scalar;
26
27	BEGIN {
28	$VERSION = 0.08;
29	@ISA = qw(Exporter);
30	@EXPORT_OK = qw(weaken unmagic grow);
31	%EXPORT_TAGS = (
32	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	refcnt => [qw(refcnt refcnt_inc refcnt_dec refcnt_rv refcnt_inc_rv refcnt_dec_rv)],
35	);
36
37	require Exporter;
38	Exporter::export_ok_tags(keys %EXPORT_TAGS);
39
40	require XSLoader;
41	XSLoader::load Convert::Scalar, $VERSION;
42	}
43
44	=item utf8 scalar[, mode]
45
46	Returns true when the given scalar is marked as utf8, false otherwise. If
47	the optional mode argument is given, also forces the interpretation of the
48	string to utf8 (mode true) or plain bytes (mode false). The actual (byte-)
49	content is not changed. The return value always reflects the state before
50	any modification is done.
51
52	This function is useful when you "import" utf8-data into perl, or when
53	some external function (e.g. storing/retrieving from a database) removes
54	the utf8-flag.
55
56	=item utf8_on scalar
57
58	Similar to C<utf8 scalar, 1>, but additionally returns the scalar (the
59	argument is still modified in-place).
60
61	=item utf8_off scalar
62
63	Similar to C<utf8 scalar, 0>, but additionally returns the scalar (the
64	argument is still modified in-place).
65
66	=item utf8_valid scalar [Perl 5.7]
67
68	Returns true if the bytes inside the scalar form a valid utf8 string,
69	false otherwise (the check is independent of the actual encoding perl
70	thinks the string is in).
71
72	=item utf8_upgrade scalar
73
74	Convert the string content of the scalar in-place to its UTF8-encoded form
75	(and also returns it).
76
77	=item utf8_downgrade scalar[, fail_ok=0]
78
79	Attempt to convert the string content of the scalar from UTF8-encoded to
80	ISO-8859-1. This may not be possible if the string contains characters
81	that cannot be represented in a single byte; if this is the case, it
82	leaves the scalar unchanged and either returns false or, if C<fail_ok> is
83	not true (the default), croaks.
84
85	=item utf8_encode scalar
86
87	Convert the string value of the scalar to UTF8-encoded, but then turn off
88	the C<SvUTF8> flag so that it looks like bytes to perl again. (Might be
89	removed in future versions).
90
91	=item utf8_length scalar
92
93	Returns the number of characters in the string, counting wide UTF8
94	characters as a single character, independent of wether the scalar is
95	marked as containing bytes or mulitbyte characters.
96
97	=item unmagic scalar
98
99	Removes magic from the scalar.
100
101	=item weaken scalar
102
103	Weaken a reference. (See also L<WeakRef>).
104
105	=item taint scalar
106
107	Taint the scalar.
108
109	=item tainted scalar
110
111	returns true when the scalar is tainted, false otherwise.
112
113	=item untaint scalar, type
114
115	Remove the specified magic from the scalar
116	(DANGEROUS!), L<perlguts>. L<Untaint>, for a similar but different
117	interface.
118
119	=item grow scalar, newlen
120
121	Sets the memory area used for the scalar to the given length, if the
122	current length is less than the new value. This does not affect the
123	contents of the scalar, but is only useful to "pre-allocate" memory space
124	if you know the scalar will grow. The return value is the modified scalar
125	(the scalar is modified in-place).
126
127	=item refcnt scalar[, newrefcnt]
128
129	Returns the current reference count of the given scalar and optionally sets it to
130	the given reference count.
131
132	=item refcnt_inc scalar
133
134	Increments the reference count of the given scalar inplace.
135
136	=item refcnt_dec scalar
137
138	Decrements the reference count of the given scalar inplace. Use C<weaken>
139	instead if you understand what this function is fore. Better yet: don't
140	use this module in this case.
141
142	=item refcnt_rv scalar[, newrefcnt]
143
144	Works like C<refcnt>, but dereferences the given reference first. Remember
145	that taking a reference of some object increases it's reference count, so
146	the reference count used by the C<*_rv>-funtions tend to be one higher.
147
148	=item refcnt_inc_rv scalar
149
150	Works like C<refcnt_inc>, but dereferences the given reference first.
151
152	=item refcnt_dec_rv scalar
153
154	Works like C<refcnt_dec>, but dereferences the given reference first.
155
156	=cut
157
158	1;
159
160	=back
161
162	=head2 CANDIDATES FOR FUTURE RELEASES
163
164	The following API functions (L<perlapi>) are considered for future
165	inclusion in this module If you want them, write me.
166
167	sv_upgrade
168	sv_pvn_force
169	sv_pvutf8n_force
170	the sv2xx family
171
172	=head1 AUTHOR
173
174	Marc Lehmann <pcg@goof.com>
175	http://www.goof.com/pcg/marc/
176
177	=cut
178