ext/Data/Util/lib/Data/Util.pm

   1 package Data::Util;
   2
   3 require Exporter;
   4 require DynaLoader;
   5
   6 our @ISA        = qw(Exporter DynaLoader);
   7 our @EXPORT_OK  = qw(sv_readonly_flag);
   8 our $VERSION    = 0.04;
   9
  10 bootstrap Data::Util $VERSION;
  11
  12 1;
  13
  14 __END__
  15
  16 =head1 NAME
  17
  18 Data::Util - A selection of general-utility data subroutines
  19
  20 =head1 SYNOPSIS
  21
  22   use Data::Util qw(sv_readonly_flag);
  23
  24   my $sv_readonly = sv_readonly_flag(%some_data);
  25
  26   sv_readonly_flag(@some_data, 1);  # Set the sv_readonly flag on
  27                                     # @some_data to true.
  28
  29 =head1 DESCRIPTION
  30
  31 C<Data::Util> contains a selection of subroutines which are useful on
  32 scalars, hashes and lists (and thus wouldn't fit into Scalar, Hash or
  33 List::Util).  All of the routines herein will work equally well on a
  34 scalar, hash, list or even hash & list elements.
  35
  36     sv_readonly_flag($some_data);
  37     sv_readonly_flag(@some_data);
  38     sv_readonly_flag(%some_data);
  39     sv_readonly_flag($some_data{key});
  40     sv_readonly_flag($some_data[3]);
  41
  42 We'll just refer to the conglomeration as "DATA".
  43
  44 By default C<Data::Util> does not export any subroutines.  You can ask
  45 for...
  46
  47 =over 4
  48
  49 =item sv_readonly_flag
  50
  51   my $sv_readonly = sv_readonly_flag(DATA);
  52   sv_readonly_flag(DATA, 1);    # set sv_readonly true
  53   sv_readonly_flag(DATA, 0);    # set sv_readonly false
  54
  55 This gets/sets the sv_readonly flag on the given DATA.  When setting
  56 it returns the previous state of the flag.  This is intended for
  57 people I<that know what they're doing.>
  58
  59 The exact behavior exhibited by a piece of DATA when sv_readonly is
  60 set depends on what type of data it is.  B<It doesn't even necessarily
  61 make the data readonly!>  Look for specific functions in Scalar::Util,
  62 List::Util and Hash::Util for making those respective types readonly.
  63
  64 =head1 AUTHOR
  65
  66 Michael G Schwern <schwern@pobox.com> using XS code by Nick Ing-Simmons.
  67
  68 =head1 SEE ALSO
  69
  70 L<Scalar::Util>, L<List::Util>, L<Hash::Util>
  71
  72 =cut
  73