This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
GDBM_File must cast fatal_func appropriately for the version of gdbm.h
[perl5.git] / cpan / List-Util / lib / Scalar / Util.pm
CommitLineData
f4a2945e
JH
1# Scalar::Util.pm
2#
2ff28616 3# Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
f4a2945e
JH
4# This program is free software; you can redistribute it and/or
5# modify it under the same terms as Perl itself.
6
7package Scalar::Util;
8
4984adac 9use strict;
f4a2945e
JH
10require Exporter;
11require List::Util; # List::Util loads the XS
12
3630f57e
CBW
13our @ISA = qw(Exporter);
14our @EXPORT_OK = qw(blessed dualvar reftype weaken isweak tainted readonly openhandle refaddr isvstring looks_like_number set_prototype);
2a5bd873 15our $VERSION = "1.25_01";
09c2a9b8
GB
16$VERSION = eval $VERSION;
17
3630f57e
CBW
18our @EXPORT_FAIL;
19
20unless (defined &weaken) {
21 push @EXPORT_FAIL, qw(weaken);
22}
23unless (defined &isweak) {
24 push @EXPORT_FAIL, qw(isweak isvstring);
25}
26unless (defined &isvstring) {
27 push @EXPORT_FAIL, qw(isvstring);
2ff28616
GB
28}
29
09c2a9b8 30sub export_fail {
3630f57e 31 if (grep { /^(?:weaken|isweak)$/ } @_ ) {
09c2a9b8
GB
32 require Carp;
33 Carp::croak("Weak references are not implemented in the version of perl");
34 }
2ff28616 35
3630f57e 36 if (grep { /^isvstring$/ } @_ ) {
09c2a9b8
GB
37 require Carp;
38 Carp::croak("Vstrings are not implemented in the version of perl");
39 }
09c2a9b8
GB
40
41 @_;
42}
f4a2945e 43
f4a2945e
JH
441;
45
46__END__
47
48=head1 NAME
49
50Scalar::Util - A selection of general-utility scalar subroutines
51
52=head1 SYNOPSIS
53
4984adac
GB
54 use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted
55 weaken isvstring looks_like_number set_prototype);
2ff28616 56 # and other useful utils appearing below
f4a2945e
JH
57
58=head1 DESCRIPTION
59
60C<Scalar::Util> contains a selection of subroutines that people have
61expressed would be nice to have in the perl core, but the usage would
62not really be high enough to warrant the use of a keyword, and the size
63so small such that being individual extensions would be wasteful.
64
65By default C<Scalar::Util> does not export any subroutines. The
66subroutines defined are
67
68=over 4
69
70=item blessed EXPR
71
72If EXPR evaluates to a blessed reference the name of the package
73that it is blessed into is returned. Otherwise C<undef> is returned.
74
c29e891d
GB
75 $scalar = "foo";
76 $class = blessed $scalar; # undef
77
78 $ref = [];
79 $class = blessed $ref; # undef
80
81 $obj = bless [], "Foo";
82 $class = blessed $obj; # "Foo"
83
f4a2945e
JH
84=item dualvar NUM, STRING
85
86Returns a scalar that has the value NUM in a numeric context and the
87value STRING in a string context.
88
89 $foo = dualvar 10, "Hello";
c29e891d
GB
90 $num = $foo + 2; # 12
91 $str = $foo . " world"; # Hello world
f4a2945e 92
60f3865b
GB
93=item isvstring EXPR
94
95If EXPR is a scalar which was coded as a vstring the result is true.
96
97 $vs = v49.46.48;
98 $fmt = isvstring($vs) ? "%vd" : "%s"; #true
99 printf($fmt,$vs);
100
f4a2945e
JH
101=item isweak EXPR
102
103If EXPR is a scalar which is a weak reference the result is true.
104
c29e891d
GB
105 $ref = \$foo;
106 $weak = isweak($ref); # false
107 weaken($ref);
108 $weak = isweak($ref); # true
109
4984adac
GB
110B<NOTE>: Copying a weak reference creates a normal, strong, reference.
111
112 $copy = $ref;
2ff28616 113 $weak = isweak($copy); # false
4984adac 114
9e7deb6c
GB
115=item looks_like_number EXPR
116
117Returns true if perl thinks EXPR is a number. See
118L<perlapi/looks_like_number>.
119
c0f790df
GB
120=item openhandle FH
121
122Returns FH if FH may be used as a filehandle and is open, or FH is a tied
123handle. Otherwise C<undef> is returned.
124
125 $fh = openhandle(*STDIN); # \*STDIN
126 $fh = openhandle(\*STDIN); # \*STDIN
127 $fh = openhandle(*NOTOPEN); # undef
128 $fh = openhandle("scalar"); # undef
129
ee4ffb48
JH
130=item readonly SCALAR
131
132Returns true if SCALAR is readonly.
133
c29e891d
GB
134 sub foo { readonly($_[0]) }
135
136 $readonly = foo($bar); # false
137 $readonly = foo(0); # true
138
60f3865b
GB
139=item refaddr EXPR
140
141If EXPR evaluates to a reference the internal memory address of
142the referenced value is returned. Otherwise C<undef> is returned.
143
144 $addr = refaddr "string"; # undef
145 $addr = refaddr \$var; # eg 12345678
146 $addr = refaddr []; # eg 23456784
147
148 $obj = bless {}, "Foo";
149 $addr = refaddr $obj; # eg 88123488
150
f4a2945e
JH
151=item reftype EXPR
152
153If EXPR evaluates to a reference the type of the variable referenced
154is returned. Otherwise C<undef> is returned.
155
c29e891d
GB
156 $type = reftype "string"; # undef
157 $type = reftype \$var; # SCALAR
158 $type = reftype []; # ARRAY
159
160 $obj = bless {}, "Foo";
161 $type = reftype $obj; # HASH
162
97605c51
GB
163=item set_prototype CODEREF, PROTOTYPE
164
165Sets the prototype of the given function, or deletes it if PROTOTYPE is
166undef. Returns the CODEREF.
167
168 set_prototype \&foo, '$$';
169
ee4ffb48
JH
170=item tainted EXPR
171
172Return true if the result of EXPR is tainted
173
c29e891d
GB
174 $taint = tainted("constant"); # false
175 $taint = tainted($ENV{PWD}); # true if running under -T
176
f4a2945e
JH
177=item weaken REF
178
179REF will be turned into a weak reference. This means that it will not
180hold a reference count on the object it references. Also when the reference
181count on that object reaches zero, REF will be set to undef.
182
183This is useful for keeping copies of references , but you don't want to
022735b4 184prevent the object being DESTROY-ed at its usual time.
f4a2945e 185
c29e891d
GB
186 {
187 my $var;
188 $ref = \$var;
189 weaken($ref); # Make $ref a weak reference
190 }
191 # $ref is now undef
192
cf083cf9
GB
193Note that if you take a copy of a scalar with a weakened reference,
194the copy will be a strong reference.
195
196 my $var;
197 my $foo = \$var;
198 weaken($foo); # Make $foo a weak reference
199 my $bar = $foo; # $bar is now a strong reference
200
201This may be less obvious in other situations, such as C<grep()>, for instance
202when grepping through a list of weakened references to objects that may have
203been destroyed already:
204
205 @object = grep { defined } @object;
206
207This will indeed remove all references to destroyed objects, but the remaining
208references to objects will be strong, causing the remaining objects to never
209be destroyed because there is now always a strong reference to them in the
210@object array.
211
f4a2945e
JH
212=back
213
2ff28616
GB
214=head1 DIAGNOSTICS
215
216Module use may give one of the following errors during import.
217
218=over
219
220=item Weak references are not implemented in the version of perl
221
222The version of perl that you are using does not implement weak references, to use
223C<isweak> or C<weaken> you will need to use a newer release of perl.
224
225=item Vstrings are not implemented in the version of perl
226
227The version of perl that you are using does not implement Vstrings, to use
228C<isvstring> you will need to use a newer release of perl.
229
230=item C<NAME> is only available with the XS version of Scalar::Util
231
232C<Scalar::Util> contains both perl and C implementations of many of its functions
233so that those without access to a C compiler may still use it. However some of the functions
234are only available when a C compiler was available to compile the XS version of the extension.
235
236At present that list is: weaken, isweak, dualvar, isvstring, set_prototype
237
238=back
239
9c3c560b
JH
240=head1 KNOWN BUGS
241
242There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will
243show up as tests 8 and 9 of dualvar.t failing
244
ddf53ba4
GB
245=head1 SEE ALSO
246
247L<List::Util>
248
f4a2945e
JH
249=head1 COPYRIGHT
250
2ff28616 251Copyright (c) 1997-2007 Graham Barr <gbarr@pobox.com>. All rights reserved.
c29e891d 252This program is free software; you can redistribute it and/or modify it
f4a2945e
JH
253under the same terms as Perl itself.
254
c29e891d 255Except weaken and isweak which are
f4a2945e
JH
256
257Copyright (c) 1999 Tuomas J. Lukka <lukka@iki.fi>. All rights reserved.
258This program is free software; you can redistribute it and/or modify it
259under the same terms as perl itself.
260
f4a2945e 261=cut