NAME
docs/pdds/pdd17_basic_types.pod - Parrot's Core PMC types
{{ NOTE: could use a better name to differentiate it from PDD 04 datatypes. Possibly pdd17_core_pmcs.pod. }}
ABSTRACT
This PDD documents the core Parrot PMC types and their behavior.
VERSION
$Revision: 15037 $
DESCRIPTION
Parrot has a number of core PMC types that all programs can guarantee will be available to them. (With the possible exception of Parrot programs executing on an embedded device or other restricted environment)
IMPLEMENTATION
Scalar types
- Undef
-
This is the generic no-value type. It has a numeric value of zero, a string value of empty string, and a boolean value of false. It will, on assignment, turn itself into a PMC of the source type, or if assigned a basic type will turn itself into one of the wrapper PMC types (detailed below) for the basic types.
- Integer
-
The PMC wrapper for Parrot's low-level integer type. Always an integer, with other types auto-converted to an integer when stored into this PMC. The range and behaviour of the Integer PMC is identical to the platform low-level integer.
The boolean value for an Integer is false if zero, otherwise true.
Floating point, string, and bignum values assigned to an Integer PMC round to the nearest integer. Floats, or strings which resolve to numbers, cap at the platform maximum or minimum integer value.
Integer PMCs take on a value of 1 if a boolean true is assigned, and a value of 0 if a boolean false is assigned.
If an out-of-range value is assigned to an Integer PMC, the PMC will throw an exception if exact math is enabled.
- Float
-
The PMC wrapper for Parrot's low-level floating point type. Always a float, with other types autoconverted to a float when stored into this PMC.
The boolean value for a Float is false if exactly zero, otherwise true.
When converted to an integer, floats round to the closest integer, capping at the platform maximum or minimum integer value.
When converting to a string, floats use the platform default snprintf format.
- String
-
The PMC wrapper for Parrot's low-level string type. Always a simple string, with other types autoconverted to a string when stored into this PMC.
The boolean value for a String is false if empty or the string '0' (a one character string holding a zero) otherwise true. This PMC autoconverts to an integer or float when its integer or float value is fetched.
- Boolean
-
A true/false value. Returns 0 for false, 1 for true when fetched as an integer or float, empty string for false and '1' for true when fetched as a string.
{{ IMPLEMENTATION NOTE: move the definitions of the Python constants "True" and "False" out of src/pmc/boolean.pmc. They belong in HLL-specific code, not in the core boolean type. }}
- BigInt
-
An arbitrary precision integer.
- BigNum
-
The PMC wrapper for Parrot's low-level BigNum type. {{ NOTE: this type doesn't seem to exist. }}
- Complex
-
A complex number, consisting of a real part and an imaginary part. {{ NOTE: is this a complete and useful implementation of complex numbers? }}
- ParrotClass
-
The PMC for Parrot's class. (Note that this may go away if we ultimately make all classes just objects)
- ParrotObject
-
The PMC for Parrot's base object type.
- Ref
-
The PMC that represents a reference to another PMC. Delegates all functions to the referred-to PMC.
- AggregateElementRef
-
This PMC represents a reference to an element contained in an aggregate PMC type, such as an array or hash. It is initialized with the key being referenced and the aggregate PMC containing that key.
Note that assigning to the reference PMC will be equivalent to a keyed set on the referenced aggregate PMC - that is, it modifies the element rather than doing a v-table call on the element itself. It is important to be aware of this when assigning a PMC through this reference; it is not the same behaviour as the Ref PMC.
- WeakRegisterRef
-
This PMC represents a weak reference to a register. Should the reference live beyond the context containing the register that it references, any attempt to use the reference will throw an exception.
A weak register reference can only be created by the
register_ref
opcode. Any assignment to the register will behave like a set instruction. That is, when assigning a PMC using a WeakRegisterRef PMC, the register will be updated to reference that PMC rather than calling the assign v-table call on the PMC in that register. This is not the same behaviour as the Ref PMC. - Random
-
A singleton PMC that generates a random number. {{ NOTE: Why do we have this? }}
Array types
Note that for the following types you can set the size of the array by using the VTABLE_set_integer_native() method. Assigning an integer to the array as a whole sets the array to that size.
Size-changing operations (such as push, pop, shift, unshift, and splice) on statically-sized arrays will throw an exception.
- Array
-
The base class for all array types (a statically sized array for any arbitrary type). New array types can be derived from the base Array. In user code it is recommended to use one of the specific array types below, rather than the base type.
- FixedBooleanArray
-
A statically sized array which holds only Boolean values.
- ResizableBooleanArray
-
A dynamically sized array which holds only Boolean values.
- FixedIntegerArray
-
A statically sized array which holds only Integer values.
- ResizableIntegerArray
-
A dynamically sized array which holds only Integer values.
- FixedFloatArray
-
A statically sized array which holds only Float values.
- ResizableFloatArray
-
A dynamically sized array which holds only Float values.
- FixedPMCArray
-
A statically sized array which holds only PMC values.
- ResizablePMCArray
-
A dynamically sized array which holds only PMC values.
- FixedStringArray
-
A statically sized array which holds only String values.
- ResizableStringArray
-
A dynamically sized array which holds only String values.
- Exception
Hash types
- Hash
-
A container with key-value semantics. The values are PMCs.
- Env
-
Env is a singleton PMC class, that is there is only one Env PMC in any interpreter. This PMC gives access to the process' environment variables--reading from it returns the value of the named process environment variable, while writing to it sets the value of a process environment variable. For example, to retrieve the current value of TERM (the terminal type on most Unix systems):
new P1, .Env set S1, P1['TERM']
Note that an embedding system may override this behavior.
- Namespace
- OrderedHash
- AddrRegistry
-
Simulates reference counting for dead-object detection and garbage collection.
Subroutine types
- Sub
- Closure
-
A closure: subroutine object plus captured lexical scope.
- Coroutine
- Continuation
- CSub
- Eval
- Exception_Handler
- MultiSub
- NCI
-
A native call interface wrapper around a C function.
- Bound_NCI
-
An internal NCI method call bound to a particular call instance. {{ NOTE: where are these used? }}
- Compiler
-
A subroutine implementing a language compiler. (Derived from NCI.)
Binary Math operations
{{ NOTE: this section is barely a stub, and not particularly useful. I suggest deleting it. Any objections? }}
The following is a list of what should happen with the basic types when used in a binary math operation:
LANGUAGE NOTES
FOOTNOTES
List of footnotes to the text.
REFERENCES
src/pmc/*.pmc