=pod

=encoding utf8

=head1 NAME

Muldis::D::Ext::QTuple -
Muldis D extension adding more generic q/tuple operators

=head1 VERSION

This document is Muldis::D::Ext::QTuple version 0.73.0.

=head1 PREFACE

This document is part of the Muldis D language specification, whose root
document is L<Muldis::D>; you should read that root document
before you read this one, which provides subservient details.

=head1 DESCRIPTION

Muldis D has a mandatory core set of system-defined (eternally available)
entities, which is referred to as the I<Muldis D core> or the I<core>; they
are the minimal entities that all Muldis D implementations need to provide;
they are mutually self-describing and are used to bootstrap the language;
any entities outside the core, called I<Muldis D extensions>, are
non-mandatory and are defined in terms of the core or each other, but the
reverse isn't true.

This current C<QTuple> document describes the system-defined I<Muldis D
QTuple Extension>, which consists of extra operators for generic q/tuples,
adding to the minimum few defined in the language core.

This current document does not describe the polymorphic operators that all
types, or some types including core types, have defined over them; said
operators are defined once for all types in L<Muldis::D::Core>.

I<This documentation is pending.>

=head1 SYSTEM-DEFINED GENERIC QUASI-/TUPLE-CONCERNING FUNCTIONS

These functions are applicable to mainly q/tuple types, but are generic
in that they typically work with any q/tuple types.

=head2 sys.std.QTuple.degree

C<< function sys.std.QTuple.degree (NNInt <-- QTuple $topic) >>

This function results in the degree of its argument (that is, the count of
attributes it has).

=head2 sys.std.QTuple.is_nullary

C<< function sys.std.QTuple.is_nullary (Bool <-- QTuple $topic) >>

This function results in C<Bool:true> iff its argument has a degree of zero
(that is, it has zero attributes), and C<Bool:false> otherwise.  By
definition, the only 1 q/tuple value for which this function would result
in C<Bool:true> is the value C<Tuple:d0>.

=head2 sys.std.QTuple.is_not_nullary

C<< function sys.std.QTuple.is_not_nullary (Bool <-- QTuple $topic) >>

This function is exactly the same as C<sys.std.QTuple.is_nullary> except
that it results in the opposite boolean value when given the same argument.

=head2 sys.std.QTuple.has_attrs

C<< function sys.std.QTuple.has_attrs (Bool <-- QTuple $topic,
set_of.Name $attr_names) >>

This function results in C<Bool:true> iff, for every one of the attribute
names specified by its C<attr_names> argument, its C<topic> argument has an
attribute with that name; otherwise it results in C<Bool:false>.  As a
trivial case, this function's result is C<Bool:true> if C<attr_names> is
empty.

=head2 sys.std.QTuple.attr_names

C<< function sys.std.QTuple.attr_names (set_of.Name <-- QTuple $topic) >>

This function results in the set of the names of the attributes of its
argument.

=head2 sys.std.QTuple.attr_from_QTuple

C<< function sys.std.QTuple.attr_from_QTuple (Universal <-- QTuple $topic)
>>

This function results in the q/scalar or q/nonscalar value of the sole
attribute of its argument.  This function will fail if its argument is not
of degree 1.

=head2 sys.std.QTuple.QTuple_from_attr

C<< function sys.std.QTuple.QTuple_from_attr (QTuple <-- Name $name,
Universal $value) >>

This function results in the C<QTuple> value which has just one attribute
whose name is given by C<name> and whose value is given by C<value>.

=head2 sys.std.QTuple.order_by_attr_names

C<< function sys.std.QTuple.order_by_attr_names (Order <-- QTuple $topic,
QTuple $other, QTuple $assuming, Bool $is_reverse_order?) >>

This C<order_determination> function provides convenient short-hand for the
common case of ordering q/tuples of a q/relation on a sequential list of
its named attributes, and the type of each of those attributes is a subtype
of a single q/scalar root type having a type-default C<order_determination>
function, which is used to order on that attribute.  This function takes an
C<array_of.OrderByName> as the C<order_by> sole attribute of its
C<assuming> argument.  This function is a short-hand for invoking
C<sys.std.Core.Cat.Order.reduction> on an C<Array> each of whose C<Order>
elements is the result of invoking C<sys.std.Core.QScalar.order> on the
corresponding attributes of C<topic> and C<other> whose names are given in
C<order_by>; the C<Array> given to C<Order.reduction> has the same number
of elements as C<order_by> has.  For each element value in C<order_by>, the
C<name> attribute specifies the attribute name of each of C<topic> and
C<order> to be compared, and the comparison operator's C<is_reverse_order>
argument is supplied by the C<is_reverse_order> attribute.  This function
will fail if C<topic> and C<other> don't have an identical degree and
attribute names, or if C<order_by> specifies any attribute names that
C<topic|other> doesn't have, or if for any attribute named to be ordered
by, that attribute's value for either of C<topic> and C<other> isn't a
member of a q/scalar root type having a type-default ordering function, or
if said root type isn't identical for both C<topic> and <other>.  The
C<order_by_attr_names> function's C<is_reverse_order> argument is optional
and defaults to C<Bool:false>, meaning it has no further effect on the
function's behaviour; but if this argument is C<Bool:true>, then this
function will result in the opposite C<Order> value that it otherwise would
have when given all the same other argument values.  It is expected that
for any q/relation whose q/tuples are to be ordered using
C<order_by_attr_names>, the C<order_by> constitutes a key or superkey.

=head2 sys.std.QTuple.subst_in_default

C<< function sys.std.QTuple.subst_in_default (QTuple <-- TypeRef $of,
QTuple $subst) >>

This function results in the q/tuple value that is the default value of the
q/tuple data type whose name is given in the C<of> argument, but that zero
or more of its attribute values have been substituted by values given in
the C<subst> argument.  This function is a short-hand for
C<sys.std.Core.QTuple.multi_update> on the result of
C<sys.std.Core.Universal.default>.  This function will fail if either
C<default> would fail for the same C<of> argument, or if its result isn't a
q/tuple type, or if the heading of C<subst> isn't a subset of the heading
of the default.  The purpose of this function is to support greater brevity
in Muldis D coding such that users can define just part of a desired
q/tuple value and have the remainder filled in from defaults for them;
particularly useful with q/tuples that conceptually have some optional
attributes.

=head1 SEE ALSO

Go to L<Muldis::D> for the majority of distribution-internal
references, and L<Muldis::D::SeeAlso> for the majority of
distribution-external references.

=head1 AUTHOR

Darren Duncan (C<perl@DarrenDuncan.net>)

=head1 LICENSE AND COPYRIGHT

This file is part of the formal specification of the Muldis D language.

Muldis D is Copyright © 2002-2009, Muldis Data Systems, Inc.

See the LICENSE AND COPYRIGHT of L<Muldis::D> for details.

=head1 TRADEMARK POLICY

The TRADEMARK POLICY in L<Muldis::D> applies to this file too.

=head1 ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in L<Muldis::D> apply to this file too.

=cut
