view release on metacpan or  search on metacpan

lib/Tupelo/Munge.pm  view on Meta::CPAN

C<OBJECT> when given a reference to one.  Correspondingly, the
L<C<ref>|perlfunc/ref> function will return C<OBJECT> if given a reference
to an unblessed tuple, and the default stringification of a reference to a
tuple will include C<OBJECT>.  Beware that this usage of the word "object"
is confusing: it was already a somewhat overloaded term before the tuple
data type existed, so it makes a poor way to identify the tuple data type.

Via this module, a tuple can be constructed from a list of slot values,
and the slot values in a tuple can be read and written.  This module
represents each slot value in the form of a reference value (for a slot
referencing an object) or an undefined value (for an empty slot).

=head2 Core class system

The L<Perl core class system|perlclass> (introduced alongside tuples in
Perl 5.37.9) uses tuples as the representation format for its classful
objects.  This class system is not the subject of this module, but it
has a special relationship to the tuple data type, which is worthy of
comment.  Beware that the core documentation overloads the term "class",
using it both to refer to Perl classes in general (i.e., packages into
which objects get blessed) and to refer specifically to the classes of

lib/Tupelo/Munge.pm  view on Meta::CPAN

=head1 FUNCTIONS

=head2 Construction

=over

=item pure_tuple(REF ...)

Returns a reference to an immutable tuple.  The tuple is composed of
the slot values supplied by the I<REF>s, each of which must be either
a reference or undefined.  The tuple is not necessarily fresh.

=item constant_tuple(REF ...)

Creates a fresh immutable tuple and returns a reference to it.  The tuple
is composed of the slot values supplied by the I<REF>s, each of which
must be either a reference or undefined.

=item variable_tuple(REF ...)

Creates a fresh mutable tuple and returns a reference to it.  The tuple
is initialised to contain the slot values supplied by the I<REF>s,
each of which must be either a reference or undefined.

=back

=head2 Examination

=over

=item tuple_mutable(TUPLE)

I<TUPLE> must be a reference to a tuple.  Returns a truth value indicating
whether the tuple is mutable.

=item tuple_length(TUPLE)

I<TUPLE> must be a reference to a tuple.  Returns the number of slots
that the tuple currently has.

=item tuple_slot(TUPLE, INDEX)

I<TUPLE> must be a reference to a tuple.  Returns the slot value (either a
reference or undefined) in the tuple's slot identified by the zero-based
index I<INDEX>.  C<die>s if the index is out of bounds (less than zero,
or greater than or equal to the number of slots).

=item tuple_slots(TUPLE)

I<TUPLE> must be a reference to a tuple.  Returns a list of the slot
values (each either a reference or undefined) in all the slots of
the tuple.  C<die>s if called in scalar context.

=back

=head2 Mutation

=over

=item tuple_set_slot(TUPLE, INDEX, REF)

I<TUPLE> must be a reference to a mutable tuple.  Sets the tuple's slot
identified by the zero-based index I<INDEX> to contain the slot value
supplied by I<REF>, which must be either a reference or undefined.
Returns the new slot value (i.e., a copy of I<REF>).  C<die>s if the
index is out of bounds (less than zero, or greater than or equal to the
number of slots).

=item tuple_set_slots(TUPLE, REF ...)

I<TUPLE> must be a reference to a mutable tuple.  Sets the tuple's
complete slot sequence to contain the slot values supplied by the I<REF>s,
each of which must be either a reference or undefined.  Returns no
useful value.  This function is capable of changing the number of slots
in a tuple, but doing so is a relatively expensive operation, so avoid
doing that routinely.

=item tuple_seal(TUPLE)

I<TUPLE> must be a reference to a mutable tuple.  Makes the tuple
immutable.  Returns a reference to the tuple (i.e., a copy of I<TUPLE>).

=back