<commit_before># Copyright (C) 2001-2006, The Perl Foundation.
# $Id$

=head1 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. }}

=head1 ABSTRACT

This PDD documents the core Parrot PMC types and their behavior.

=head1 VERSION

$Revision$

=head1 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)

=head1 IMPLEMENTATION

=head2 Scalar types

=over 4

=item 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.

=item 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.

=item 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.

=item 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.

=item 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. }}

=item BigInt

An arbitrary precision integer.

=item BigNum

The PMC wrapper for Parrot's low-level BigNum type.
{{ NOTE: this type doesn't seem to exist. }}

=item Complex

A complex number, consisting of a real part and an imaginary part.
{{ NOTE: is this a complete and useful implementation of complex
numbers? }}

=item ParrotClass

The PMC for Parrot's class. (Note that this may go away if we ultimately make
all classes just objects)

=item ParrotObject

The PMC for Parrot's base object type.

=item Ref

The PMC that represents a reference to another PMC. Delegates all functions to
the referred-to PMC.

=item Random

A singleton PMC that generates a random number. {{ NOTE: Why do we have
this? }}
<commit_msg>Add two new reference PMCs to the Basic Types PDD.<commit_after># Copyright (C) 2001-2006, The Perl Foundation.
# $Id$

=head1 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. }}

=head1 ABSTRACT

This PDD documents the core Parrot PMC types and their behavior.

=head1 VERSION

$Revision$

=head1 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)

=head1 IMPLEMENTATION

=head2 Scalar types

=over 4

=item 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.

=item 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.

=item 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.

=item 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.

=item 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. }}

=item BigInt

An arbitrary precision integer.

=item BigNum

The PMC wrapper for Parrot's low-level BigNum type.
{{ NOTE: this type doesn't seem to exist. }}

=item Complex

A complex number, consisting of a real part and an imaginary part.
{{ NOTE: is this a complete and useful implementation of complex
numbers? }}

=item ParrotClass

The PMC for Parrot's class. (Note that this may go away if we ultimately make
all classes just objects)

=item ParrotObject

The PMC for Parrot's base object type.

=item Ref

The PMC that represents a reference to another PMC. Delegates all functions to
the referred-to PMC.

=item 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.

=item 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 C<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.

=item Random

A singleton PMC that generates a random number. {{ NOTE: Why do we have
this? }}

{'fraction_non_alphanumeric': 0.04184000950909307, 'fraction_numerical': 0.0064186378224176865, 'mean_word_length': 4.146177370030581, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 4, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2474763', 'n_tokens_mistral': 2342, 'n_tokens_neox': 2263, 'n_words': 1379}