tuple - Operators for the Tuple data type
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 must be one of the types listed below:
string
int
long
wideInt
bignum
double
boolean
list
dict
bytearray
Tuple
Relation
If the attribute data type is Tuple or Relation, then the data type specifier must be a list of two elements, the first being the type name Tuple or Relation and the second being another list contain the tuple or relation heading. Tuples and relations thus may contain tuple-value or relation-valued attributes.
These types have the same name as the corresponding Tcl type and the Tcl type is used for the values. The bignum and dict types are only available in Tcl 8.5. Any value associated with an attribute must be coercible to the stated type. Since string is the univeral Tcl type, then any attribute of type string effectively has no type check. Some Tuple operations result in expressions being evaluated on the attribute value. All operations are carried out in the stated data type. So for example, determining the relative order of two attributes whose type is double will be carried out in double arithmetic even if the string representation of the value could be construed to be a different 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.
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.
There 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 two elements:
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 must be one of those listed above.
The tuple values are also specified by a list consisting of an even number of elements. The even indexed elements are attribute names and the odd index elements give the corresponding attribute value. Note that the ordering of two lists is arbitrary in that attribute name / value pairs need not be in the same order as the attribute name / type pairs.
The following is a literal string representation of a tuple with three attributes.
{Name string Breed string Age int} {Name Fido Breed Terrier Age 2}
The following is a string representation that is equivalent to the same tuple.
{Name string Breed string Age int} {Breed Terrier Name Fido Age 2}
The assign subcommand provides a convenient way to place the values of the attributes of a tuple into Tcl variables. The assign subcommand can place all the attributes into variables or only a subset of the attributes. The variables may be named the same as the attribute name or values may be placed in variables of a specified name. If no optional arguments are given, then assign places the value of each attribute of a tuple into a Tcl variable that has the same name as the attribute. If any optional arguments are present, then only the given attributes are assigned to variables. Each optional argument is considered as a list containing one or two elements. If the argument is of the form attrName, i.e. a single element list, then it is taken as an attribute name and the corresponding value is placed in a Tcl variable by the same name. If the argument is of the form attr-var-pair then it is taken as a two element list consisting of an attribute / variable name pair and the corresponding attribute value is assigned to a variable with the given name. Assignments are made in left to right order and it is not an error to assign the same attribute multiple times or to assign the same attribute to multple variables. Any existing variables that have the same name are assigned a new value. Variables are created as necessary. All variables are created in the local scope. The assign subcommand returns the number of variables assigned to which necessarily is equal to either the degree of the tuple or the number of optional arguments given.
% tuple assign {{Name string Age int} {Name John Age 25}}
2
% set Name
John
% set Age
25
The attributes subcommand returns a list of the attribute names of tupleValue.
% tuple attributes {{Name string Age int} {Name John Age 25}}
Name Age
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 is the same form of list 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.
% tuple create {Number int Street string Zip string} {Number 100 Zip 90214 Street Elm}
{Number int Street string Zip string} {Number 100 Street Elm Zip 90214}
% tuple create {Number int Street string Zip string} {Number hundred Zip 90214 Street Elm}
bad value type for value, "hundred"
% tuple create {Number int Street string Zip string} {Number 100 Zip 90214}
wrong number of attributes specified, "Number 100 Zip 90214"
% tuple create {Number int Street string Zip string} {Number 100 Zip 90214 Number 100}
duplicate attribute name, "Number"
% tuple create {Number int Street string Zip string} {Number 100 Zip 90214 Street Elm Email john@net.net}
wrong number of attributes specified, "Number 100 Zip 90214 Street Elm Email john@net.net"
The degree subcommand returns the degree of the tuple which is the number of attributes the tuple has.
% tuple degree {{Name string Age int} {Name John Age 25}}
2
% tuple degree {{} {}}
0
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.
% set t1 [tuple create {Name string Age int} {Name John Age 25}]
{Name string Age int} {Name John Age 25}
% tuple eliminate $t1
{Name string Age int} {Name John Age 25}
% tuple eliminate $t1 Name
{Age int} {Age 25}
% tuple eliminate $t1 Street
unknown attribute name, "Street"
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 [tuple create {Name string Status int} {Name Fred Status 20}]
{Name string Status int} {Name Fred Status 20}
% set t2 [tuple create {Status int Name string} {Name Fred Status 20}]
{Status int Name string} {Status 20 Name Fred}
% tuple equal $t1 $t2
1
This implies that only tuple equal can reliably determine tuple equality. Using string equal (or any other string based comparison operations) to determine tuple equality is not reliable and should not be used
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. The extension arguments of name-type-value must come in groups of three. The three arguments are a new attribute name, attribute data type and attribute value in that order. 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.
% set t1 [tuple create {Name string} {Name Fred}]
{Name string} {Name Fred}
% tuple extend $t1 Age int 30 Sex string Male
{Name string Age int Sex string} {Name Fred Age 30 Sex Male}
% tuple extend $t1 Name string Jane
duplicate attribute name, "Name"
% tuple extend $t1 Age int Thirty
bad value type for value, "Thirty"
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.
% set t1 [tuple create {Name string Age int} {Name {Fred Jones} Age 27}]
{Name string Age int} {Name {Fred Jones} Age 27}
% tuple extract $t1 Name
Fred Jones
% tuple extract $t1 Age Name
27 {Fred Jones}
% tuple extract $t1 Status
unknown attribute name, "Status"
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. The form of the list returned may also be used directly the dict command.
% set t1 {{Name string Age int} {Name {Fred Jones} Age 27}}
{Name string Age int} {Name {Fred Jones} Age 27}
% set tinfo [tuple get $t1]
Name {Fred Jones} Age 27
% array set ainfo $tinfo
% parray ainfo
ainfo(Age) = 27
ainfo(Name) = Fred Jones
% dict keys $tinfo
Age Name
The heading subcommand returns the heading of the given tupleValue. The heading of a tuple is a list consisting of two elements. The first element is the keyword Tuple and the second is list with an even number of elements consisting of alternating attribute names and attribute data types.
% set t {{Name string Age int} {Name {Fred Jones} Age 27}}
{Name string Age int} {Name {Fred Jones} Age 27}
% tuple heading $t
{Name string Age int}
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.
% set t {{Name string Age int} {Name {Fred Jones} Age 27}}
{Name string Age int} {Name {Fred Jones} Age 27}
% tuple project $t Age
{Age int} {Age 27}
% tuple project $t
{} {}
The relation subcommand returns a new relation value that contains tupleValue as its only tuple. The heading of the returned relation value is the same as that of tupleValue. This subcommand corresponds to the ::ral::relation tuple command.
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 give 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.
% set t {{Name string Age int} {Name {Fred Jones} Age 27}}
{Name string Age int} {Name {Fred Jones} Age 27}
% tuple rename $t Name Person Age Status
{Person string Status int} {Person {Fred Jones} Status 27}
% tuple rename $t Name Person Person Name
{Name string Age int} {Name {Fred Jones} Age 27}
% tuple rename $t Name Person Name Nomen
unknown attribute name, "Name"
% tuple rename $t Name Age
duplicate attribute name, "Age"
% tuple rename $t
{Name string Age int} {Name {Fred Jones} Age 27}
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:
% set t {{Name string Address {Tuple {Number int Street string}}} {Name Fred Address {Number 100 Street Elm}}}
{Name string Address {Tuple {Number int Street string}}} {Name Fred Address {Number 100 Street Elm}}
% tuple unwrap $t Address
{Name string Number int Street string} {Name Fred Number 100 Street Elm}
% tuple unwrap $t Name
attribute must be of a Tuple type, "Name"
% set u {{Name string Address {Tuple {Number int Name string}}} {Name Fred Address {Number 100 Name Elm}}}
{Name string Address {Tuple {Number int Name string}}} {Name Fred Address {Number 100 Name Elm}}
% tuple unwrap $u Address
duplicate attribute name, "while unwrapping tuple"
The update subcommand returns a new tuple that has the same heading as tupleValue and that is modified by replacing the attribute values given by the attrN arguments with their corresponding values as given by the valueN arguments. modifies the attribute values of a tuple in place. It is an error to attempt to update an attribute that does exist, i.e. the structure of the tuple may not be changed by this command.
% set t {{Name string Age int} {Name {Fred Jones} Age 27}}
{Name string Age int} {Name {Fred Jones} Age 27}
% tuple update $t Name {Jane Jones}
{Name string Age int} {Name {Jane Jones} Age 27}
% tuple update $t Status 20
unknown attribute name, "Status"
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 attrN arguments are the names of attributes that will be placed in the new tuple valued attribute. Referring to the example from the tuple unwrap command above:
% set t {{Name string Number int Street string} {Name Fred Number 100 Street Elm}}
{Name string Number int Street string} {Name Fred Number 100 Street Elm}
% tuple wrap $t Address Number Street
{Name string Address {Tuple {Number int Street string}}} {Name Fred Address {Number 100 Street Elm}}
Copyright © 2004 - 2010 by G. Andrew Mangogna