set.lua
-------------

This adds a new data type Set.

To make this class available include this file at the beginning
of a script via:

.. code-block:: lua

   include "scripting/set.lua"



.. class:: Set(iteratable)

   A set is a collection of items. Each item must compare uniquely
   in the set, otherwise it is discarded; that is a Set never contains
   the same item more than once.

   It works with all types that are either unique (strings) or provide a
   __hash property. :class:`wl.map.Field` and :class:`wl.map.MapObject`
   implement such a property

   .. attribute:: size

      (RO) Due to a bug in Lua 5.1, one cannot use the '#' operator to get
      the number of items in a set. Use this property instead.


   .. method:: add(item)

      Add this item to the set

   .. method:: discard(item)

      Remove this item from the set. Does nothing if the item is not in the
      set.

   .. method:: contains(item)

      Returns :const:`true` if the item is contained in this set,
      :const:`false` otherwise

   .. method:: pop_at(n)

      Returns the n-th item of this set and removes it. Note that the only
      way to get to this item is by iterating, so this function scales
      linearly with n.

   .. method:: items

      Iterator function that allows easy iterating of all items.

      .. code-block:: lua

         s = Set:new{"a","b","c"}
         for i in s:items() do print(i) end

   .. method:: union(other_set)

      Returns a new set that is the union of both sets. This is
      also overloaded to the '+' operator

   .. method:: subtract(other_set)

      Returns a new set that contains all values of this set that
      are not in other_set. This is also overloaded to the '-' operator.

   .. method:: intersection(other_set)

      Returns a new set that contains all values of this set that are also
      in other_set. This is also overloaded to the '*' operator.