struct::set - Create and manipulate Tcl set values, Tcl implementation
Welcome to Struct, a set of packages providing various data structures to Tcl, and additional operations for existing Tcl structures.
This manpage documents the Tcl implementation of the struct::set package. It provides the same API as the C implementation, although details like the exact wording of error messages may differ. The ::struct namespace contains a single ensemble command set with multiple methods for the manipulation of set values. These methods are:
This method manipulates the variable svar, adding all elements of the sets to the set stored in this variable. If no sets are specified the variable is not changed. This has precendence over the next statement.
If the variable named by svar does not exist it will be created.
The result of the method is the empty string.
See also the related methods include, set, and union.
This method returns a boolean value indicating if the set value contains the named element (true), or not (false).
This method returns a set containing the specified elements. Duplicates in the argumnts are removed.
This method computes the set difference of set value S and the set values S1, S2, ..., i.e. "(S - S1) - S2 ..." and returns it as the result of the method.
If no sets Si are specified then S is returned.
See also the related methods exclude, subtract, and unset.
This method returns a boolean value indicating if the set value is an empty set (true), or not (false).
This method returns a boolean value indicating if the two set values contain the same set (true) or not (false).
This method removes the specified elements from the set value and returns the reduced set as the result of the method.
If no elements are specified then set is returned.
See also the related methods difference, subtract, and unset.
This method adds the specified elements to the set value and returns the extended set as the result of the method.
If no elements are specified then set is returned.
See also the related methods add, union, and set.
This method computes the intersection of all the specified set values and returns it as the result of the method. An empty set is returned if no sets are specified.
This method is a combination of the methods intersect and difference. Its result is a three-element list containing "set1*set2", "set1-set2", and "set2-set1", in this order. In other words, the intersection of the two arguments, and their differences.
This method manipulates the variable svar, adding the specified elements to the set stored in this variable. If no elements are specified the variable is not changed. This has precendence over the next statement.
If the variable named by svar does not exist it will be created.
The result of the method is the number of elements actually added to the set in svar.
See also the related methods add, include, and union.
This method returns the cardinalty of the set value, i.e. the number of elements contained in the set. This is an integer number greater than or equal to zero.
This method returns a boolean value indicating if the set value A is a subset of the set value B (true), or not (false).
Note that a set A equal to B is a subset too.
This method manipulates the variable svar, removing all elements of the sets from the set stored in this variable. If no sets are specified the variable is not changed. This has precendence over the next statement.
If the variable named by svar does not exist and error will be thrown.
The result of the method is the empty string.
See also the related methods difference, exclude, and unset.
This method returns a boolean value indicating if the set value A is a superset of the set value B (true), or not (false).
Note that a set A equal to B is a superset too.
This method computes the symmetric difference of the sets A and B, i.e. ("(A - B) + (B - A)") and returns it as the result of the command.
This method computes the union of set values i.e. "(S1 + S2) + S3 ..." and returns it as the result of the method.
An empty set is returned if no sets are specified.
See also the related methods add, include, and set.
This method manipulates the variable svar, removing the specified elements from the set stored in this variable. If no elements are specified the variable is not changed. This has precendence over the next statement.
If the variable named by svar does not exist an error will be thrown.
The result of the method is the number of elements actually removed from to the set in svar.
See also the related methods difference, exclude, and subtract.
Two groups of 4 methods deserve some additional attention to explain the similarities and differences between them. These are:
add, include, set, and union
difference, exclude, subtract, and unset
Each can be organized into a 2x2 table with one axis showing the type of the first argument (set value, or set variable), and the types of the other arguments (elements, or set values). See below.
Value Variable
----- --------
union add | Sets
include set | Elements
Value Variable
----- --------
difference subtract | Sets
exclude unset | Elements
Version 2 introduces incompatible changes to the API of stack objects, therefore the change to the major version number.
The changes in detail are:
Version 2 requires Tcl 8.5 or higher. Tcl 8.4 or less is not supported anymore.
Instance creation syntax has changed. For comparison, the old syntax is
struct::stack FOO ; # or set foo [struct::stack]
whereas the new is
struct stack create FOO ; # or set foo [struct stack new]
Method getr has been dropped. Use
lreverse [FOO get]
instead, assuming that FOO is a stack instance.
The methods peek and peekr have been renamed to top and bottom, respectively.
The method at is new.
This package, written by Andreas Kupries, is BSD licensed.
This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such at the Struct Tracker. Please also report any ideas for enhancements you may have for either package and/or documentation.
cardinality, data structures, difference, emptiness, exclusion, inclusion, intersection, membership, set, symmetric difference, union
Data structures
Copyright © 2004-2012 Andreas Kupries <[email protected]>