Class DS_HASH_TABLE

note

description:

    "Hash tables, implemented with arrays. %
    %Keys are hashed using hash_code from HASHABLE."

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

class interface

DS_HASH_TABLE [G, K -> HASHABLE]

inherit

DS_SPARSE_TABLE [G, K]
    DS_TABLE [G, K]
        DS_CONTAINER [G]
    DS_BILINEAR [G]
        DS_LINEAR [G]
            DS_TRAVERSABLE [G]
                DS_CONTAINER [G]
            DS_SEARCHABLE [G]
                DS_CONTAINER [G]
    DS_RESIZABLE [G]
        DS_CONTAINER [G]

create

make (n: INTEGER)
        -- Create an empty table and allocate memory space
        -- for at least n items.
        -- Use `=' as comparison criterion for items.
        -- Use equal as comparison criterion for keys.
        -- (From DS_SPARSE_TABLE.)
    require
        positive_n: n >= 0
    ensure
        empty: is_empty
        capacity_set: capacity = n
        before: before

make_equal (n: INTEGER)
        -- Create an empty table and allocate memory space
        -- for at least n items.
        -- Use equal as comparison criterion for items.
        -- Use equal as comparison criterion for keys.
        -- (From DS_SPARSE_TABLE.)
    require
        positive_n: n >= 0
    ensure
        empty: is_empty
        capacity_set: capacity = n
        before: before

make_default
        -- Create an empty table and allocate memory space
        -- for at least default_capacity items.
        -- Use `=' as comparison criterion for items.
        -- Use equal as comparison criterion for keys.
        -- (From DS_CONTAINER.)
    ensure
        empty: is_empty
        capacity_set: capacity = default_capacity
        before: before

make_map (n: INTEGER)
        -- Create an empty table and allocate memory space
        -- for at least n items.
        -- Use `=' as comparison criterion for items.
        -- Use `=' as comparison criterion for keys.
        -- (From DS_SPARSE_TABLE.)
    require
        positive_n: n >= 0
    ensure
        empty: is_empty
        capacity_set: capacity = n
        before: before

make_map_equal (n: INTEGER)
        -- Create an empty table and allocate memory space
        -- for at least n items.
        -- Use equal as comparison criterion for items.
        -- Use `=' as comparison criterion for keys.
        -- (From DS_SPARSE_TABLE.)
    require
        positive_n: n >= 0
    ensure
        empty: is_empty
        capacity_set: capacity = n
        before: before

make_map_default
        -- Create an empty table and allocate memory space
        -- for at least default_capacity items.
        -- Use `=' as comparison criterion for items.
        -- Use `=' as comparison criterion for keys.
        -- (From DS_SPARSE_TABLE.)
    ensure
        empty: is_empty
        capacity_set: capacity = default_capacity
        before: before

make_with_equality_testers (n: INTEGER;
    an_item_tester: like equality_tester;
    a_key_tester: like key_equality_tester)
        -- Create an empty table and allocate memory space for at
        -- least n items.
        -- Use an_item_tester as comparison criterion for items.
        -- Use a_key_tester as comparison criterion for keys.
        -- (From DS_SPARSE_TABLE.)
    require
        positive_n: n >= 0
    ensure
        empty: is_empty
        capacity_set: capacity = default_capacity
        before: before
        equality_tester_set: equality_tester = an_item_tester
        key_equality_tester_set: key_equality_tester = a_key_tester

feature -- Access

infix "@", item (k: K): G
        -- Item associated with k
        -- (From DS_TABLE.)
    require
        valid_entry: has (k)

key (k: K): K
        -- Key associated with k
        -- (From DS_SPARSE_TABLE.)
    require
        has_k: has (k)

found_item: G
        -- Item found by last call to search
        -- (From DS_SPARSE_TABLE.)
    require
        item_found: found

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

key_for_iteration: K
        -- Key at internal cursor position
        -- (From DS_SPARSE_TABLE.)
    require
        not_off: not off

first: G
        -- First item in hash table
        -- (From DS_LINEAR.)
    require
        not_empty: not is_empty
    ensure
        has_first: has_item (Result)

last: G
        -- Last item in container
        -- (From DS_BILINEAR.)
    require
        not_empty: not is_empty
    ensure
        has_last: has_item (Result)

new_cursor: DS_HASH_TABLE_CURSOR [G, K]
        -- New external cursor for traversal
        -- (From DS_TRAVERSABLE.)
    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 hash table
        -- (From DS_CONTAINER.)

capacity: INTEGER
        -- Maximum number of items in hash table
        -- (From DS_RESIZABLE.)

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

feature -- Status report

has (k: K): BOOLEAN
        -- Is there an item associated with k?
        -- (From in DS_TABLE.)
    ensure
        valid_key: Result implies valid_key (k)

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

found: BOOLEAN
        -- Did last call to search succeed?
        -- (From DS_SPARSE_TABLE.)

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

is_full: BOOLEAN
        -- Is hash table full?
        -- (From DS_RESIZABLE.)

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)

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

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

before: BOOLEAN
        -- Is there no valid position to left of internal cursor?
        -- (From DS_BILINEAR.)

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

valid_key (k: K): BOOLEAN
        -- Is k a valid key?
        -- (From DS_TABLE.)
    ensure
        defintion: Result = True

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

feature -- Search

search (k: K)
        -- Search for item at key k.
        -- If found, set found to true, and set
        -- found_item to item associated with k.
        -- (From DS_SPARSE_TABLE.)
    ensure
        found_set: found = has (k)
        found_item_set: found implies (found_item = item (k))

feature -- Comparison

is_equal (other: like Current): BOOLEAN
        -- Is current hash table equal to other?
        -- Do not take cursor positions, capacity
        -- nor equality_tester into account.
        -- (From GENERAL.)
    require
        other_not_void: other /= Void
    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 hash table.
        -- Move all cursors off (unless other = Current).
        -- (From GENERAL.)
    require
        other_not_void: other /= Void
        type_identity: same_type (other)
    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.)
    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

finish
        -- Move internal cursor to last position.
        -- (From DS_BILINEAR.)
    ensure
        empty_behavior: is_empty implies before
        not_empty_behavior: not is_empty implies is_last

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

back
        -- Move internal cursor to previous position.
        -- (From DS_BILINEAR.)
    require
        not_before: not before

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

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

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

go_before
        -- Move cursor to before position.
        -- (From DS_BILINEAR.)
    ensure
        before: before

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

replace (v: G; k: K)
        -- Replace item associated with k by v.
        -- Do not move cursors.
        -- (From DS_TABLE.)
    require
        valid_entry: has (k)
    ensure
        replaced: item (k) = v
        same_count: count = old count

replace_found_item (v: G)
        -- Replace item associated with
        -- the key of found_item by v.
        -- Do not move cursors.
        -- (From DS_SPARSE_TABLE.)
    require
        item_found: found
    ensure
        replaced: found_item = v
        same_count: count = old count

put (v: G; k: K)
        -- Associate v with key k.
        -- Do not move cursors.
        -- (From DS_SPARSE_TABLE.)
    require
        not_full: not is_full
        valid_key: valid_key (k)
    ensure
        inserted: has (k) and then item (k) = v
        same_count: (old has (k)) implies (count = old count)
        one_more: (not old has (k)) implies (count = old count + 1)

put_new (v: G; k: K)
        -- Associate v with key k.
        -- Do not move cursors.
        -- (From DS_SPARSE_TABLE.)
    require
        not_full: not is_full
        valid_key: valid_key (k)
        new_item: not has (k)
    ensure
        one_more: count = old count + 1
        inserted: has (k) and then item (k) = v

force (v: G; k: K)
        -- Associate v with key k.
        -- Resize hash table if necessary.
        -- Move cursors off when resizing.
        -- (From put in DS_TABLE.)
    require
        valid_key: valid_key (k)
    ensure
        inserted: has (k) and then item (k) = v
        same_count: (old has (k)) implies (count = old count)
        one_more: (not old has (k)) implies (count = old count + 1)

force_new (v: G; k: K)
        -- Associate v with key k.
        -- Resize table if necessary.
        -- Move cursors off when resizing.
        -- (From put_new in DS_TABLE.)
    require
        valid_key: valid_key (k)
        new_item: not has (k)
    ensure
        one_more: count = old count + 1
        inserted: has (k) and then item (k) = v

swap (k, l: K)
        -- Exchange items associated with k and l.
        -- (From DS_TABLE.)
    require
        valid_k: has (k)
        valid_l: has (l)
    ensure
        same_count: count = old count
        new_k: item (k) = old item (l)
        new_l: item (l) = old item (k)

feature -- Removal

remove (k: K)
        -- Remove item associated with k.
        -- Move any cursors at this position forth.
        -- (From DS_TABLE.)
    require
        valid_key: valid_key (k)
    ensure
        same_count: (not old has (k)) implies (count = old count)
        one_less: (old has (k)) implies (count = old count - 1)
        removed: not has (k)

wipe_out
        -- Remove all items from hash table.
        -- Move all cursors off.
        -- (From DS_CONTAINER.)
    ensure
        wiped_out: is_empty

feature -- Resizing

resize (n: INTEGER)
        -- Resize hash table so that it can contain
        -- at least n items. Do not lose any item.
        -- Move all cursors off.
        -- (From DS_RESIZABLE.)
    require
        n_large_enough: n >= capacity
    ensure
        capacity_set: capacity = n

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

not_both: not (after and before)
before_constraint: before implies off
    -- (From DS_BILINEAR.)

count_constraint: count <= capacity
full_definition: is_full = (count = capacity)
    -- (From DS_RESIZABLE.)

end -- class DS_HASH_TABLE

Copyright © 2000, Eric Bezault mailto:ericb@gobosoft.com http://www.gobosoft.com Last Updated: 16 April 2000