TITLE

Common vtable format for all variables

VERSION

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

CHANGES

None. First version

ABSTRACT

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

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.

IMPLEMENTATION

Core datatypes

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

INT: This is a generic integral value
NUM: This is a generic floating point value
STR: This is a generic string value
BOOL: This is a generic boolean value

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

Integer data types

IV: This is a platform-native integer. Probably 32 or 64 bits, though there's no guarantee made.
bigint: This is perl's big integer format. It's an infinite (more or less, until you run out of memory) precision integer.

Floating point data types

NV: The platform-native floating point value. Probably around 80 bits (with 53 bits of precision) though that will vary from system to system.
bigfloat: Perl's big floating point format. Again potentially infinite precision, within the limits of available memory.

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.

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.
UTF-32 string: This is a Unicode string in UTF-32 format.
Native string: This is a string in platform native format.
Foreign string: This is a string in a non-native format for the platform that perl still knows how to deal with.

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.

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 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 get_values from two PMCs of the same type, or set_value(PMC1,get_valu