# .tgt.sets.module_sets

## Name

  ## module_sets

## Synopsis

  Methods
    mutnodeset( [elements`:` iterable+]) -> MutNodeSet
    immnodeset( [elements`:` iterable+]) -> ImmNodeSet

## Methods

  mutnodeset( [elements`:` iterable+]) -> MutNodeSet
    Returns a new mutable nodeset with specified elements.
  immnodeset( [elements`:` iterable+]) -> ImmNodeSet
    Returns a new immutable nodeset with specified elements.

# .tgt.kindnames.CommonSet

## Name

  ## CommonSet

## Synopsis

  Conditions
    cond:contains(x, y)
    cond:empty(x)
    cond:equalset(x, y)
    cond:istrue(x)
    cond:subset(x, y)

## Conditions

cond:contains(x, y)
  True if the set x contains the element y.
  Python code: `y in x`
cond:empty(x)
  True if the set x is empty.
  Python code: `not x`
cond:equalset(x, y)
  True if x contains the same elements as y.
  Python code: `immnodeset(x) == immnodeset(y)`
    in context: `from guppy.sets import immnodeset`
cond:istrue(x)
  True if the argument is true in the Python sense.
  Python code: `bool(x)`
cond:subset(x, y)
  True if x represents a non-strict subset of y:
  all elements in x are also in y.
  Python code: `immnodeset(x) <= immnodeset(y)`
    in context: `from guppy.sets import immnodeset`

# .tgt.kindnames.NodeSet

## Name

  ## NodeSet

## Synopsis

  ### For any object x of kind NodeSet:

  Operators
    # x & y`:` iterable+ -> ImmNodeSet
    # x | y`:` iterable+ -> ImmNodeSet
    # x ^ y`:` iterable+ -> ImmNodeSet
    # x - y`:` iterable+ -> ImmNodeSet
    # x &= y`:` iterable+ -> NodeSet
    # x |= y`:` iterable+ -> NodeSet
    # x ^= y`:` iterable+ -> NodeSet
    # x -= y`:` iterable+ -> NodeSet
    # y`:` Any+ in x -> boolean
    # x == y`:` NodeSet+ -> boolean
    # x != y`:` NodeSet+ -> boolean
    # x <= y`:` NodeSet+ -> boolean
    # x < y`:` NodeSet+ -> boolean
    # x >= y`:` NodeSet+ -> boolean
    # x > y`:` NodeSet+ -> boolean
    iter(x) -> iterator
    len(x) -> int

## Description

  A nodeset is a set of objects with equality based on heap address.

## Operators

  x & y`:` iterable+ -> ImmNodeSet
    Intersection: the set of objects that are in both x and y.
    Postconditions
      CommonSet.cond:subset(returned value, x)
      CommonSet.cond:subset(returned value, y)
  x | y`:` iterable+ -> ImmNodeSet
    Union: the set of objects that are in either x or y.
    Postconditions
      CommonSet.cond:subset(x, returned value)
      CommonSet.cond:subset(y, returned value)
  x ^ y`:` iterable+ -> ImmNodeSet
    Symmetric set difference: the set of objects that are in exactly one of x and y.
  x - y`:` iterable+ -> ImmNodeSet
    Set difference: the set of objects that are in x but not in y.
  x &= y`:` iterable+ -> NodeSet
    In-place intersection.
    Postconditions
      CommonSet.cond:subset(returned value, x)
      CommonSet.cond:subset(returned value, y)
  x |= y`:` iterable+ -> NodeSet
    In-place union.
    Postconditions
      CommonSet.cond:subset(x, returned value)
      CommonSet.cond:subset(y, returned value)
  x ^= y`:` iterable+ -> NodeSet
    In-place symmetric set difference.
  x -= y`:` iterable+ -> NodeSet
    In-place set difference.
  y`:` Any+ in x -> boolean
    Inclusion test.
  x == y`:` NodeSet+ -> boolean
    Equal: x and y contain the same elements.
  x != y`:` NodeSet+ -> boolean
    Not equal: x and y do not contain the same elements.
  x <= y`:` NodeSet+ -> boolean
    Subset, non-strict: all elements in x are also in y.
  x < y`:` NodeSet+ -> boolean
    Subset, strict: all elements in x are also in y, and y contains some element not in x.
  x >= y`:` NodeSet+ -> boolean
    Superset, non-strict: all elements in y are also in x.
  x > y`:` NodeSet+ -> boolean
    Superset, strict: all elements in y are also in x, and x contains some element not in y.
  iter(x) -> iterator
    Iteration
    Returns an iterator yielding the elements of x.
      (The order is implementation dependent.)
    Postcondition
      CommonSet.cond:equalset(returned value, x)
  len(x) -> int
    Length
    Returns the number of elements in x.

# .tgt.kindnames.MutNodeSet

## Name

  ## MutNodeSet

## Synopsis

  Subkind of`:` NodeSet
  Constructor
    module_sets`.`mutnodeset( [elements`:` iterable+]) -> MutNodeSet

  ### For any object S of kind MutNodeSet:

  Methods
    S`.`add(e`:` Any+)
    S`.`append(e`:` Any+)
    S`.`clear()
    S`.`discard(e`:` Any+)
    S`.`pop()
    S`.`remove(e`:` Any+)
    S`.`tas(e`:` Any+) -> boolean
    S`.`tac(e`:` Any+) -> boolean

## Description

  A mutable nodeset is a nodeset object that can be updated in place.

## Subkind of`:` NodeSet

  All operations from the NodeSet kind are inherited.
  The in-place operators (&=, |= etc) update the target set in place and return the same object.
  It is unspecified what happens when trying to update a mutable nodeset for which an iterator object (from the iter() function) is active.

## Methods

  S`.`add(e`:` Any+)
    Add e to S; no effect if e was already in S.
    Postconditions
      CommonSet.cond:contains(S, e)
      not CommonSet.cond:empty(S)
  S`.`append(e`:` Any+)
    Add e to S, or raise ValueError if e was already in S.
    Precondition
      not CommonSet.cond:contains(S, e)
    Postconditions
      CommonSet.cond:contains(S, e)
      not CommonSet.cond:empty(S)
  S`.`clear()
    Remove all elements from S, and compact its storage.
    Postcondition
      CommonSet.cond:empty(S)
  S`.`discard(e`:` Any+)
    Remove e from S; no effect if e was not in S.
    Postcondition
      not CommonSet.cond:contains(S, e)
  S`.`pop()
    Remove and return some object from S, or raise ValueError if S was empty.
    Precondition
      not CommonSet.cond:empty(S)
    Postcondition
      not CommonSet.cond:contains(S, returned value)
  S`.`remove(e`:` Any+)
    Remove e from S, or raise ValueError if e was not in S.
    Precondition
      CommonSet.cond:contains(S, e)
    Postcondition
      not CommonSet.cond:contains(S, e)
  S`.`tas(e`:` Any+) -> boolean
    Test and Set.
    If e is in S return True,
    else add e to S and return False.
    Postconditions
      CommonSet.cond:contains(S, e)
      not CommonSet.cond:empty(S)
    Equation
      pre: CommonSet.cond:contains(S, e) == post: CommonSet.cond:istrue(returned value)
  S`.`tac(e`:` Any+) -> boolean
    Test and Clear.
    If e is in S, remove e from S and return True,
    else return False.
    Postcondition
      not CommonSet.cond:contains(S, e)
    Equation
      pre: CommonSet.cond:contains(S, e) == post: CommonSet.cond:istrue(returned value)

# .tgt.kindnames.ImmNodeSet

## Name

  ## ImmNodeSet

## Synopsis

  Subkind of`:` NodeSet
  Constructor
    module_sets`.`immnodeset( [elements`:` iterable+]) -> ImmNodeSet

  ### For any object x of kind ImmNodeSet:

  Operator
    hash(x) -> int

## Description

  An immutable nodeset is a nodeset object that is guaranteed to always contain the same elements after it has been created.

## Subkind of`:` NodeSet

  An immutable nodeset inherits the operations defined for NodeSet.
  The in-place operations (&=, |= etc) will not really update the target set in place, but will return an updated copy. It is yet formally unspecified whether this returned copy is mutable or immutable.

## Operator

  hash(x) -> int
    Hashing
    Returns a hash value based on the addresses of the elements.

Generated by GSL-HTML 3.0.1 on Sat Aug 17 13:29:53 2019