=head1 TITLE

Common vtable format for all variables

=head1 VERSION

=head2 CURRENT

   Maintainer: Dan Sugalski <dan@sidhe.org>
   Class: Internals
   PDD Number: 2
   Version: 1
   Status: Developing
   Last Modified: 05 February 2001
   PDD Format: 1
   Language: English

=head2 HISTORY

None. First version

=head1 CHANGES

None. First version

=head1 ABSTRACT

This RFC presents the vtable entries, and their order, that all
variables MUST provide.

=head1 DESCRIPTION

All perl variables hide their guts behind a magic perl structure
generally referred to as a PMC, or Perl Magic Cookie. Nothing outside
the core of perl (in fact, nothing outside the data type's vtable
routines) should infer anything about a PMC. (hence the Magic part)

The first parameter to all of these should be the destination PMC.

vtables are neat because they decouple the interface and
implementation of various object functions. This does mean, though,
that you need to either know what functions are available and what
they do, or have some method of finding out. It's faster if you know
which vtable entry does what, so that's the method perl's using.

=head1 IMPLEMENTATION

=head2 Core datatypes

For ease of use, we define the following semi-abstract data types

=over 4

=item INT

This is a generic integral value

=item NUM

This is a generic floating point value

=item STR

This is a generic string value

=item BOOL

This is a generic boolean value

=back

See the PDD specifying perl's internal data types for more details,
but in a nutshell they are:

=head3 Integer data types

=over 4

=item IV

This is a platform-native integer. Probably 32 or 64 bits, though
there's no guarantee made.

=item bigint

This is perl's big integer format. It's an infinite (more or less,
until you run out of memory) precision integer.

=back

=head3 Floating point data types

=over 4

=item NV

The platform-native floating point value. Probably around 80 bits
(with 53 bits of precision) though that will vary from system to system.

=item bigfloat

Perl's big floating point format. Again potentially infinite
precision, within the limits of available memory.

=back

=head3 String data types

All perl strings are counted, of course, so we don't have any
forbidden characters and take steps against buffer overruns reasonably
easily.

=over 4

=item binary buffer

This is a buffer of binary data. Perl makes no assumptions about its
contents, and won't ever implicitly translate it to any other representation.

=item UTF-32 string

This is a Unicode string in UTF-32 format.

=item Native string

This is a string in platform native format.

=item Foreign string

This is a string in a non-native format for the platform that perl
still knows how to deal with.

=back

=head2 vtable functions

The following functions are defined:

   IV            type(PMC[, subtype]);
   STR          name(PMC[, key]);
   void         new(PMC[, key]);
   void         clone(PMC, PMC[, flags[,key]);
   void         morph(PMC, type[, key]);
   BOOL         move_to(void *, PMC);
   IV           real_size(PMC[, key]);
   void         destroy(PMC[, key]);
   INT          get_integer(PMC[, key]); ##
   NUM           get_number(PMC[, key]); ##
   STR          get_string(PMC[, key]); ##
   BOOL         get_bool(PMC[, key]); ##
   void *       get_value(PMC[, key]);
   BOOL         is_same(PMC, PMC[, key]);
   void         set_integer(PMC, INT[, key]); ##
   void         set_number(PMC, NUM[, key]); ##
   void         set_string(PMC, STR[, key]); ##
   void         set_value(PMC, void *[, key]);
   void         add(PMC, PMC, PMC[, key]); ##
   void         subtract(PMC, PMC, PMC[, key]); ##
   void         multiply(PMC, PMC, PMC[, key]); ##
   void         divide(PMC, PMC, PMC[, key]); ##
   void         modulus(PMC, PMC, PMC[, key]); ##
   void         concatenate(PMC, PMC, PMC[, key]); ##
   BOOL         is_equal(PMC, PMC[,key]); ##
   void         logical_or(PMC, PMC, PMC[, key]); ##
   void         logical_and(PMC, PMC, PMC[, key]); ##
   void         logical_not(PMC, PMC[,key]); ##
   void         match(PMC, PMC, REGEX[, key]);
   void         repeat(PMC, PMC, PMC[, key]); ##
   void         nextkey(PMC, PMC, start_key[, key]);
   BOOL         exists(PMC[, key]);

All the functions marked with ## must have multiple forms, one for
each possible form of a data type. (IV, bigint, etc) Perl will
automatically produce conversion code if a v it isn't.

=item get_value

   void *       get_value(PMC[, key]);

Returns a pointer to the beginning of currently "OK" data; the type of
this data must be determined by examining the PMCs C<type>. This must
only be used by other vtable functions inside the core, and must never
be used if the PMC is of a type defined by a user outside the core,
unless you know what you're doing. (eg, comparing C<get_value>s from two
PMCs of the same type, or C<set_value(PMC1,get_valu