tuple -
Operators for the Tuple data type
package require ral 0.7
::ral::tuple assign tupleValue
::ral::tuple create heading name-value-list
::ral::tuple degree tupleValue
::ral::tuple equal tuple1 tuple2
::ral::tuple eliminate tupleValue ? attr ... ?
::ral::tuple extend tupleValue ? name-type-value ... ?
::ral::tuple extract tupleValue attr ? attr2 ... ?
::ral::tuple get tupleValue
::ral::tuple heading tupleValue
::ral::tuple project tupleValue ? attr ... ?
::ral::tuple rename tupleValue ? oldname newname ... ?
::ral::tuple unwrap tupleValue attr
::ral::tuple update tupleVarName name-value-list
::ral::tuple wrap tupleValue newAttr oldAttrList
This manpage describes the
tuple
command.
The
tuple
command is part of the Tcl Relational Algebra Library (ral) package.
The ral package introduces an new Tcl data type called
Tuple
and this command provides the operators for the Tuple data type.
Formally,
a tuple is a set of components.
Each component consists of an attribute name, an attribute data type
and an attribute value.
The attribute name may be any Tcl string, although attribute names that
contain embedded blanks are particularly inconvenient.
The attribute data type may be any valid Tcl internal data type.
Tcl uses many different internal types for many different purposes.
The ones most useful are:
-
string
-
int
-
double
-
wideInt
-
boolean
-
list
-
bytearray
-
Tuple
Any attribute value assigned to a particular attribute is coerced into the
attribute data type for that attribute and it is an error if the value
string assigned to an attribute does not represent a valid value of the
attribute data type.
Tuples are similar in many ways to other Tcl data types such as dict,
::struct::record or keyed lists from TclX.
However, the tuple type was built to operate specfically in conjunction
with the Relation type and does have some specific rules that the other
types do not have.
Tuples are sets of components and as such have the following rules.
-
All attribute names must be unique.
-
The is no inherent left to right ordering in tuples.
Clearly, the implementation may store components in a particular order
and any string representation must have some left to right ordering to it
(since I write in a Latin alphabet which is left to right ordered),
but the operations on Tuples do not expose or depend upon any ordering of
components.
Consequently, using string and list operators on the string representation
of a Tuple are not guaranteed to yield the correct result.
The implementation is free to choose any internal order and any ordering
of the string representation it wishes as long as the Tuple operators function
as described.
Like any Tcl value, tuples have a string representation.
The string representation of a tuple is a specially formatted list
consisting of three elements:
-
The keyword Tuple.
-
The tuple heading.
-
The tuple values.
The tuple heading is an even numbered list consisting alternately of
an attribute name and an attribute data type.
Data types may be any valid Tcl object type.
The tuple values are also specified by a list consisting of an even
number of elements.
This list is of the same form as that accepted by the array set
command.
The even indexed elements are attribute names and the odd index elements
give the corresponding attribute value.
The following is a literal string representation of a tuple with
three attributes.
{Tuple {Name string Breed string Age int} {Name Fido Breed Terrier Age 2}}
-
::ral::tuple assign tupleValue
-
The assign subcommand provides a convenient way to place the values
of the attributes of a tuple into Tcl variables.
The assign subcommand places the value of each attribute
of a tuple into Tcl variables that have the same name as the
attribute names of the tuple.
Any existing variable that has the same name as an attribute is assigned a
new value.
Variables are created as necessary.
All variables are created in the local scope.
The assign subcommand returns the empty string.
-
::ral::tuple create heading name-value-list
-
The create subcommand creates a new tuple that has a heading
given by the heading argument and values given by the
name-value-list argument and returns the value of the new tuple.
The heading is specified by a list containing an even number of elements.
The heading list consists of alternating attribute names and
attribute data types.
The name-value-list must have an even number of elements and the
elements are treated as pairs.
The first element of a pair is taken to be an attribute name and the second is
taken as the corresponding value for the attribute.
This are the same forms of lists accepted by the array set command.
When a tuple is created each value is converted to the underlying data
type specified in the heading of the tuple.
It is an error if the conversion fails.
It is also an error not to supply a value for every attribute or to attempt
to supply the value of any attribute more than once.
-
::ral::tuple degree tupleValue
-
The degree subcommand returns the degree of the tuple which is
the number of attributes the tuple has.
-
::ral::tuple equal tuple1 tuple2
-
The equal subcommands returns "1" if tuple1 is equal to
tuple2 and "0" otherwise.
Two tuples are equal if they the same attribute names,
the corresponding attributes have the same type and
the corresponding attribute values are equal.
Because there is no inherent order to the attributes of a tuple,
there are many ways to specify the same tuple.
For example, the following tuples are equal.
set t1 [::ral::tuple create {{Name string} {Status int}} {Name Fred Status 20}]
set t2 [::ral::tuple create {{Status int} {Name string}} {Name Fred Status 20}]
This implies that only tuple equal can reliably determine
tuple equality.
Using string equal to determine tuple equality is not reliable and
should be avoided.
-
::ral::tuple eliminate tupleValue ? attr ... ?
-
The eliminate subcommand returns a new tuple with the same
heading and values as tupleValue except that those attributes given
in the argument list are not present.
It is an error to attempt to eliminate attributes that are not part of
tupleValue.
-
::ral::tuple extend tupleValue ? name-type-value ... ?
-
The extend subcommand returns a new tuple with the same heading and
values as the tupleValue argument except that the new attributes given by
the name-type-value arguments are included.
Each name-type-value argument is a list consisting of two or
three elements.
If name-type-value list contains three elements then
they are taken as a new attribute name, attribute data type and attribute
value in that order.
If only two elements are given, then they are
taken as the attribute name and attribute value and the attribute data
type is taken as "string".
It is an error to attempt to extend a tuple with an attribute name
that is already contained in tupleValue.
Each new attribute value is converted to the appropriate type and it is
an error if that conversion fails.
-
::ral::tuple extract tupleValue attr ? attr2 ... ?
-
The extract subcommand returns the value of one or more attributes.
If only a single attr is requested, then the attribute value
is the return value of the command.
If multiple attr are requested, then a list of attribute values
is returned.
The order of the returned list is the same as the order of the attr
arguments.
-
::ral::tuple get tupleValue
-
The get subcommand returns a list consisting of pairs of elements.
The first element of each pair is an attribute name and the second
is the attribute value.
The form of the list is the same as that returned by the array get
command and accepted by the array set command.
The get subcommand provides a convenient means to move tuple
values into an array.
-
::ral::tuple heading tupleValue
-
The heading subcommand returns the heading of the given tupleValue.
The heading of a tuple is an even numbered list consisting alternately of
attribute names and attribute data types.
-
::ral::tuple project tupleValue ? attr ... ?
-
The project subcommand returns a new tuple that consists of only the
attributes given by the attr arguments
with the corresponding values taken from tupleValue.
It is not an error to project zero attributes (the nullary tuple projection),
the result being the tuple with no attributes.
-
::ral::tuple rename tupleValue ? oldname newname ... ?
-
The rename subcommand returns a new tuple where oldname is
replaced by newname.
The tupleValue argument is not modified.
Many pairs of oldname/newname arguments may be given.
It is an error to attempt to given an oldname that is not an attribute
name in the tuple or to attempt to change the name of an attribute to be
one that already exists in the tuple.
-
::ral::tuple unwrap tupleValue attr
-
The unwrap subcommand creates a new tuple that expands the attributes of
a tuple valued attribute.
The tupleValue argument must be of Tuple type and
the attr argument must also be of Tuple type.
The returned tuple value will consists of all the attributes of the
original tuple minus the attr attribute plus all the attributes
of the attr attribute itself.
The unwrap subcommand is useful for un-nesting tuples that
have tuple valued attributes.
For example, the tuple:
tuple unwrap\
{Tuple {{Name string} {Address {Tuple {{Num string} {Street string}}}}}\
{Name Fred Address {Num 100 Street Main}}} Address
returns:
{Tuple {{Name string} {Num string} {Street string}}\
{Name Fred Num 100 Street Main}}
-
::ral::tuple update tupleVarName name-value-list
-
The update subcommand modifies the values of a tuple in place.
The tupleVarName argument is the name of a variable that contains a
tuple value.
The name-value-list is a list of pairs giving the attribute name and the
new value to which that attribute is to be set.
The command modifies the attributes in place
and returns the updated tuple.
-
::ral::tuple wrap tupleValue newAttr oldAttrList
-
The wrap subcommand creates a new tuple where some of the attributes
are contained in a Tuple valued attribute.
This command provides a means to create nested tuples, i.e.
tuples that contain tuple valued attributes.
The tupleValue argument must be a tuple and newAttr is the name the
the new tuple valued attribute will be given.
The oldAttrList argument is a list of attribute names that will be placed
in the new tuple valued attribute.
Referring to the example from the tuple unwrap command above:
tuple wrap\
{Tuple {{Name string} {Num string} {Street string}}\
{Name Fred Num 100 Street Main}} Address {Num Street}
returns:
{Tuple {{Name string} {Address {Tuple {{Num string} {Street string}}}}}\
{Name Fred Address {Num 100 Street Main}}} Address
relvar, relation
tuple, relation, relvar