[ Main Table Of Contents | Table Of Contents | Keyword Index ]

struct::set - Create and manipulate Tcl set values, Tcl implementation

- package require
**Tcl 8.5** - package require
**struct::set ?3?**

**::struct set****add***svar*?*set*...?**::struct set****contains***set**element***::struct set****create**?*element*...?**::struct set****difference***S*?*Si*...?**::struct set****empty***set***::struct set****equal***set1**set2***::struct set****exclude***set*?*element*...?**::struct set****include***set*?*element*...?**::struct set****intersect**?*set*...?**::struct set****intersect3***set1**set2***::struct set****set***svar*?*element*...?**::struct set****size***set***::struct set****subset***A**B***::struct set****subtract***svar*?*set*...?**::struct set****superset***A**B***::struct set****symdifference***A**B***::struct set****union**?*set*...?**::struct set****unset***svar*?*element*...?

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:

**::struct set****add***svar*?*set*...?This method manipulates the variable

*svar*, adding all elements of the*set*s 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**.**::struct set****contains***set**element*This method returns a boolean value indicating if the

*set*value contains the named*element*(**true**), or not (**false**).**::struct set****create**?*element*...?This method returns a set containing the specified

*element*s. Duplicates in the argumnts are removed.**::struct set****difference***S*?*Si*...?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**.**::struct set****empty***set*This method returns a boolean value indicating if the

*set*value is an empty set (**true**), or not (**false**).**::struct set****equal***set1**set2*This method returns a boolean value indicating if the two set values contain the same set (

**true**) or not (**false**).**::struct set****exclude***set*?*element*...?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**.**::struct set****include***set*?*element*...?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**.**::struct set****intersect**?*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*set*s are specified.**::struct set****intersect3***set1**set2*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.**::struct set****set***svar*?*element*...?This method manipulates the variable

*svar*, adding the specified*element*s 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**.**::struct set****size***set*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.**::struct set****subset***A**B*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.**::struct set****subtract***svar*?*set*...?This method manipulates the variable

*svar*, removing all elements of the*set*s 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**.**::struct set****superset***A**B*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.**::struct set****symdifference***A**B*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.**::struct set****union**?*set*...?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

*set*s are specified.See also the related methods

**add**,**include**, and**set**.**::struct set****unset***svar*?*element*...?This method manipulates the variable

*svar*, removing the specified*element*s 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. Uselreverse [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 <andreas_kupries@users.sourceforge.net>