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

struct::set(n) 3 doc "Tcl Data Structures"

Name

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

Table Of Contents

Synopsis

Description

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 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.

::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 elements. 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 sets 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 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.

::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 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.

::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 sets 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 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:

  1. add, include, set, and union

  2. 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

Changes

Changes for version 2

Version 2 introduces incompatible changes to the API of stack objects, therefore the change to the major version number.

The changes in detail are:

  1. Version 2 requires Tcl 8.5 or higher. Tcl 8.4 or less is not supported anymore.

  2. 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]
    
  3. Method getr has been dropped. Use

    	lreverse [FOO get]	
    

    instead, assuming that FOO is a stack instance.

  4. The methods peek and peekr have been renamed to top and bottom, respectively.

  5. The method at is new.

License

This package, written by Andreas Kupries, is BSD licensed.

Bugs, Ideas, Feedback

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.

Keywords

cardinality, data structures, difference, emptiness, exclusion, inclusion, intersection, membership, set, symmetric difference, union

Category

Data structures