Class DS

Class DS_SET

note

description:

    "Data structures whose items appear only once"

library:    "Gobo Eiffel Structure Library"
author:     "Eric Bezault <ericb@gobosoft.com>"
copyright:  "Copyright (c) 2001, Eric Bezault and others"
license:    "MIT License"

deferred class interface

DS_SET [G]

inherit

DS_LINEAR [G]
    DS_TRAVERSABLE [G]
        DS_CONTAINER [G]
    DS_SEARCHABLE [G]
        DS_CONTAINER [G]

feature {NONE} -- Initialization

make_default
        -- Create an empty container.
        -- (From DS_CONTAINER.)
    deferred
    ensure
        empty: is_empty

feature -- Access

infix "@", item (v: G): G
        -- Item equal to v held in set
        -- (Use equality_tester's comparison criterion
        -- if not void, use `=' criterion otherwise.)
    require
        has_v: has (v)
    deferred
    ensure
        definition: same_items (Result, v)

item_for_iteration: G
        -- Item at internal cursor position
        -- (From DS_TRAVERSABLE.)
    require
        not_off: not off

first: G
        -- First item in container
        -- (From DS_LINEAR.)
    require
        not_empty: not is_empty
    deferred
    ensure
        has_first: has (Result)

new_cursor: DS_SET_CURSOR [G]
        -- New external cursor for traversal
        -- (From DS_TRAVERSABLE.)
    deferred
    ensure
        cursor_not_void: Result /= Void
        valid_cursor: valid_cursor (Result)

equality_tester: DS_EQUALITY_TESTER [G]
        -- Equality tester;
        -- A void equality tester means that `='
        -- will be used as comparison criterion.
        -- (From DS_SEARCHABLE.)

feature -- Measurement

count: INTEGER
        -- Number of items in container
        -- (From DS_CONTAINER.)
    deferred

occurrences (v: G): INTEGER
        -- Number of times v appears in set
        -- (Use equality_tester's comparison criterion
        -- if not void, use `=' criterion otherwise.)
        -- (From DS_SEARCHABLE.)
    ensure
        positive: Result >= 0
        has: has (v) implies Result >= 1
        has_v: has (v) implies (Result = 1)
        not_has_v: not has (v) implies (Result = 0)

feature -- Status report

has (v: G): BOOLEAN
        -- Does container include v?
        -- (Use equality_tester's comparison criterion
        -- if not void, use `=' criterion otherwise.)
        -- (From DS_SEARCHABLE.)
    ensure
        not_empty: Result implies not is_empty

is_subset (other: DS_SET [G]): BOOLEAN
        -- Are all items of current set included in other?
        -- (Use equality_tester's comparison criterion
        -- if not void, use `=' criterion otherwise.)
    require
        other_not_void: other /= Void
        same_equality_tester: same_equality_tester (other)
    deferred

is_superset (other: DS_SET [G]): BOOLEAN
        -- Does current set include all items of other?
        -- (Use equality_tester's comparison criterion
        -- if not void, use `=' criterion otherwise.)
    require
        other_not_void: other /= Void
        same_equality_tester: same_equality_tester (other)
    ensure
        definition Result = other.is_subset (Current)

is_disjoint (other: DS_SET [G]): BOOLEAN
        -- Are none of the items of current set included in other?
        -- (Use equality_tester's comparison criterion
        -- if not void, use `=' criterion otherwise.)
    require
        other_not_void: other /= Void
        same_equality_tester: same_equality_tester (other)
    deferred

is_empty: BOOLEAN
        -- Is container empty?
        -- (From DS_CONTAINER.)

is_first: BOOLEAN
        -- Is internal cursor on first item?
        -- (From DS_LINEAR.)
    ensure
        not_empty: Result implies not is_empty
        not_off: Result implies not off
        definition: Result implies (item_for_iteration = first)

after: BOOLEAN
        -- Is there no valid position to right of internal cursor?
        -- (From DS_LINEAR.)

off: BOOLEAN
        -- Is there no item at internal cursor position?
        -- (From DS_TRAVERSABLE.)

same_position (a_cursor: like new_cursor): BOOLEAN
        -- Is internal cursor at same position as a_cursor?
        -- (From DS_TRAVERSABLE.)
    require
        a_cursor_not_void: a_cursor /= Void

valid_cursor (a_cursor: DS_CURSOR [G]): BOOLEAN
        -- Is a_cursor a valid cursor?
        -- (From DS_TRAVERSABLE.)
    require
        a_cursor_not_void: a_cursor /= Void

same_items (v, u: G): BOOLEAN
        -- Are v and u considered equal?
        -- (Use equality_tester's comparison criterion
        -- if not void, use `=' criterion otherwise.)
        -- (From DS_SEARCHABLE.)

same_equality_tester (other: DS_SEARCHABLE [G]): BOOLEAN
        -- Does container use the same comparison
        -- criterion as other?
        -- (From DS_SEARCHABLE.)
    require
        other_not_void: other /= Void

equality_tester_settable (a_tester: like equality_tester): BOOLEAN
        -- Can set_equality_tester be called with a_tester
        -- as argument in current state of container?
        -- (Answer: the set has to be empty.)
        -- (From DS_SEARCHABLE.)

feature -- Comparison

is_equal (other: like Current): BOOLEAN
        -- Is current container equal to other?
        -- (From GENERAL.)
    require
        other_not_void: other /= Void
    deferred
    ensure
        consistent: standard_is_equal (other) implies Result
        same_type: Result implies same_type (other)
        symmetric: Result implies other.is_equal (Current)
        same_count: Result implies count = other.count

feature -- Duplication

copy (other: like Current)
        -- Copy other to current container.
        -- (From GENERAL.)
    require
        other_not_void: other /= Void
        type_identity: same_type (other)
    deferred
    ensure
        is_equal: is_equal (other)

feature -- Setting

set_equality_tester (a_tester: like equality_tester)
        -- Set equality_tester to a_tester.
        -- A void equality tester means that `='
        -- will be used as comparison criterion.
        -- (From DS_SEARCHABLE.)
    require
        equality_tester_settable: equality_tester_settable (a_tester)
    ensure
        equality_tester_set: equality_tester = a_tester

feature -- Cursor movement

start
        -- Move internal cursor to first position.
        -- (From DS_LINEAR.)
    ensure
        empty_behavior: is_empty implies after
        not_empty_behavior: not is_empty implies is_first

forth
        -- Move internal cursor to next position.
        -- (From DS_LINEAR.)
    require
        not_after: not after

search_forth (v: G)
        -- Move internal cursor to first position at or after current
        -- position where item_for_iteration and v are equal.
        -- (Use equality_tester's comparison criterion
        -- if not void, use `=' criterion otherwise.)
        -- Move after if not found.
        -- (From DS_LINEAR.)
    require
        not_off: not off or after

go_after
        -- Move cursor to after position.
        -- (From DS_LINEAR.)
    ensure
        after: after

go_to (a_cursor: like new_cursor)
        -- Move internal cursor to a_cursor's position.
        -- (From DS_TRAVERSABLE.)
    require
        cursor_not_void: a_cursor /= Void
        valid_cursor: valid_cursor (a_cursor)
    ensure
        same_position: same_position (a_cursor)

feature -- Element change

put (v: G)
        -- Add v to set, replacing any existing item.
        -- (Use equality_tester's comparison criterion
        -- if not void, use `=' criterion otherwise.)
    deferred
    ensure
        inserted: has (v) and then item (v) = v
        same_count: (old has (v)) implies (count = old count)
        one_more: (not old has (v)) implies (count = old count + 1)

feature -- Removal

remove (v: G)
        -- Remove item equal to v from set.
        -- (Use equality_tester's comparison criterion
        -- if not void, use `=' criterion otherwise.)
    deferred
    ensure
        same_count: (not old has (v)) implies (count = old count)
        one_less: (old has (v)) implies (count = old count - 1)
        removed: not has (v)

wipe_out
        -- Remove all items from container.
        -- (From DS_CONTAINER.)
    deferred
    ensure
        wiped_out: is_empty

feature -- Basic operations

append (other: DS_SET [G])
        -- Add all items of other to current set.
        -- (Use equality_tester's comparison criterion
        -- if not void, use `=' criterion otherwise.)
    require
        other_not_void: other /= Void
        same_equality_tester: same_equality_tester (other)
    deferred
    ensure
        is_superset: is_superset (other)

intersect (other: DS_SET [G])
        -- Remove all items not included in other.
        -- (Use equality_tester's comparison criterion
        -- if not void, use `=' criterion otherwise.)
    require
        other_not_void: other /= Void
        same_equality_tester: same_equality_tester (other)
    deferred
    ensure
        is_subset: is_subset (other)

subtract (other: DS_SET [G])
        -- Remove all items also included in other.
        -- (Use equality_tester's comparison criterion
        -- if not void, use `=' criterion otherwise.)
    require
        other_not_void: other /= Void
        same_equality_tester: same_equality_tester (other)
    deferred
    ensure
        is_disjoint: is_disjoint (other)

symdif (other: DS_SET [G])
        -- Add items of other which are not included
        -- in current set and remove those which are.
        -- (Use equality_tester's comparison criterion
        -- if not void, use `=' criterion otherwise.)
    require
        other_not_void: other /= Void
        same_equality_tester: same_equality_tester (other)
    deferred

invariant

positive_count: count >= 0
empty_definition: is_empty = (count = 0)
    -- (From DS_CONTAINER.)

empty_constraint: is_empty implies off
    -- (From DS_TRAVERSABLE.)

after_constraint: after implies off
    -- (From DS_LINEAR.)

end -- class DS_SET