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 names
 :taint  all functions with taint in their names

=over 4

=cut

package Convert::Scalar;

BEGIN {
   $VERSION = 0.06;
   @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)],
   );

   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).

=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.1
Committed:	Thu Sep 27 18:32:22 2001 UTC (22 years, 7 months ago) by root
Branch:	MAIN
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.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 names
18			:taint all functions with taint in their names
19
20			=over 4
21
22			=cut
23
24			package Convert::Scalar;
25
26			BEGIN {
27			$VERSION = 0.06;
28			@ISA = qw(Exporter);
29			@EXPORT_OK = qw(weaken unmagic grow);
30			%EXPORT_TAGS = (
31			taint => [qw(taint untaint tainted)],
32			utf8 => [qw(utf8 utf8_on utf8_off utf8_valid utf8_upgrade utf8_downgrade utf8_encode utf8_decode utf8_length)],
33			);
34
35			require Exporter;
36			Exporter::export_ok_tags(keys %EXPORT_TAGS);
37
38			require XSLoader;
39			XSLoader::load Convert::Scalar, $VERSION;
40			}
41
42			=item utf8 scalar[, mode]
43
44			Returns true when the given scalar is marked as utf8, false otherwise. If
45			the optional mode argument is given, also forces the interpretation of the
46			string to utf8 (mode true) or plain bytes (mode false). The actual (byte-)
47			content is not changed. The return value always reflects the state before
48			any modification is done.
49
50			This function is useful when you "import" utf8-data into perl, or when
51			some external function (e.g. storing/retrieving from a database) removes
52			the utf8-flag.
53
54			=item utf8_on scalar
55
56			Similar to C<utf8 scalar, 1>, but additionally returns the scalar (the
57			argument is still modified in-place).
58
59			=item utf8_off scalar
60
61			Similar to C<utf8 scalar, 0>, but additionally returns the scalar (the
62			argument is still modified in-place).
63
64			=item utf8_valid scalar [Perl 5.7]
65
66			Returns true if the bytes inside the scalar form a valid utf8 string,
67			false otherwise (the check is independent of the actual encoding perl
68			thinks the string is in).
69
70			=item utf8_upgrade scalar
71
72			Convert the string content of the scalar in-place to its UTF8-encoded form
73			(and also returns it).
74
75			=item utf8_downgrade scalar[, fail_ok=0]
76
77			Attempt to convert the string content of the scalar from UTF8-encoded to
78			ISO-8859-1. This may not be possible if the string contains characters
79			that cannot be represented in a single byte; if this is the case, it
80			leaves the scalar unchanged and either returns false or, if C<fail_ok> is
81			not true (the default), croaks.
82
83			=item utf8_encode scalar
84
85			Convert the string value of the scalar to UTF8-encoded, but then turn off
86			the C<SvUTF8> flag so that it looks like bytes to perl again. (Might be
87			removed in future versions).
88
89			=item utf8_length scalar
90
91			Returns the number of characters in the string, counting wide UTF8
92			characters as a single character, independent of wether the scalar is
93			marked as containing bytes or mulitbyte characters.
94
95			=item unmagic scalar
96
97			Removes magic from the scalar.
98
99			=item weaken scalar
100
101			Weaken a reference. (See also L<WeakRef>).
102
103			=item taint scalar
104
105			Taint the scalar.
106
107			=item tainted scalar
108
109			returns true when the scalar is tainted, false otherwise.
110
111			=item untaint scalar, type
112
113			Remove the specified magic from the scalar
114			(DANGEROUS!), L<perlguts>. L<Untaint>, for a similar but different
115			interface.
116
117			=item grow scalar, newlen
118
119			Sets the memory area used for the scalar to the given length, if the
120			current length is less than the new value. This does not affect the
121			contents of the scalar, but is only useful to "pre-allocate" memory space
122			if you know the scalar will grow. The return value is the modified scalar
123			(the scalar is modified in-place).
124
125			=cut
126
127			1;
128
129			=back
130
131			=head2 CANDIDATES FOR FUTURE RELEASES
132
133			The following API functions (L<perlapi>) are considered for future
134			inclusion in this module If you want them, write me.
135
136			sv_upgrade
137			sv_pvn_force
138			sv_pvutf8n_force
139			the sv2xx family
140
141			=head1 AUTHOR
142
143			Marc Lehmann <pcg@goof.com>
144			http://www.goof.com/pcg/marc/
145
146			=cut
147