Skip to content

Bag

Download Python Files

Bag Specification

IBag

Bases: ABC, Generic[T]

Interface for a Bag (MultiSet) data structure.

Source code in src/datastructures/ibag.py 
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
class IBag(ABC, Generic[T]):
    """
    Interface for a Bag (MultiSet) data structure.
    """

    @abstractmethod
    def __init__(self, *items: Optional[Iterable[T]]) -> None:
        """
        Initializes the Bag.
        """
        pass

    @abstractmethod
    def add(self, item: T) -> None:
        """
        Adds an item to the Bag.

        Args:
            item (T): The item to add.

        Returns:
            None

        Raises:
            TypeError: If the item is None.

        Examples:
            >>> bag: Bag[int] = Bag()
            >>> bag.add(1)
            >>> bag.add(2)
            >>> bag.add(1)

            >>> bag.count(1)
            2
            >>> bag.count(2)
            1
            >>> bag.add(None)
            TypeError: Item cannot be None
        """
        pass

    @abstractmethod
    def remove(self, item: T) -> None:
        """
        Removes one occurrence of the item from the Bag.

        Args:
            item (T): The item to remove.

        Returns:
            None

        Raises:
            ValueError: If the item is not present in the Bag.

        Examples:
            >>> bag: Bag[int] = Bag()
            >>> bag.add(1)
            >>> bag.add(2)
            >>> bag.add(1)

            >>> bag.remove(1)
            >>> bag.count(1)
            1
            >>> bag.remove(1)
            >>> bag.count(1)
            0
            >>> bag.remove(1)
            ValueError: Item not found in Bag
        """
        pass

    @abstractmethod
    def count(self, item: T) -> int:
        """
        Returns the number of occurrences of the item in the Bag.

        Args:
            item (T): The item to count.

        Returns:
            int: The number of occurrences of the item.

        Examples:
            >>> bag: Bag[int] = Bag()
            >>> bag.add(1)
            >>> bag.add(2)
            >>> bag.add(1)

            >>> bag.count(1)
            2
            >>> bag.count(2)
            1
            >>> bag.count(3)
            0
        """
        pass

    @abstractmethod
    def __len__(self) -> int:
        """
        Returns the total number of items in the Bag (including duplicates).

        Returns:
            int: The total number of items in the Bag.

        Examples:
            >>> bag: Bag[int] = Bag()
            >>> bag.add(1)
            >>> bag.add(2)
            >>> bag.add(1)

            >>> bag.size()
            3
        """
        pass

    @abstractmethod
    def distinct_items(self) -> Iterable[T]:
        """
        Returns an iterable of the distinct items in the Bag.

        Returns:
            Iterable[T]: An iterable of the distinct items in the Bag.
        """
        pass

    @abstractmethod
    def __contains__(self, item: T) -> bool:
        """
        Checks if the Bag contains the specified item.

        Args:
            item (T): The item to check for.

        Returns:
            bool: True if the item is present in the Bag, False otherwise.

        Examples:
            >>> bag: Bag[int] = Bag()
            >>> bag.add(1)
            >>> bag.add(2)
            >>> bag.add(1)

            >>> bag.contains(1)
            True
            >>> bag.contains(2)
            True
            >>> bag.contains(3)
            False
        """
        pass

    @abstractmethod
    def clear(self) -> None:
        """
        Removes all items from the Bag.
        """
        pass

__contains__(item) abstractmethod

Checks if the Bag contains the specified item.

Parameters:

Name Type Description Default
item T

The item to check for.

 required

Returns:

Name Type Description
bool bool

True if the item is present in the Bag, False otherwise.

Examples:

>>> bag: Bag[int] = Bag()
>>> bag.add(1)
>>> bag.add(2)
>>> bag.add(1)

>>> bag.contains(1)
True
>>> bag.contains(2)
True
>>> bag.contains(3)
False
Source code in src/datastructures/ibag.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
@abstractmethod
def __contains__(self, item: T) -> bool:
    """
    Checks if the Bag contains the specified item.

    Args:
        item (T): The item to check for.

    Returns:
        bool: True if the item is present in the Bag, False otherwise.

    Examples:
        >>> bag: Bag[int] = Bag()
        >>> bag.add(1)
        >>> bag.add(2)
        >>> bag.add(1)

        >>> bag.contains(1)
        True
        >>> bag.contains(2)
        True
        >>> bag.contains(3)
        False
    """
    pass

__init__(*items) abstractmethod

Initializes the Bag.

Source code in src/datastructures/ibag.py 
11
12
13
14
15
16
@abstractmethod
def __init__(self, *items: Optional[Iterable[T]]) -> None:
    """
    Initializes the Bag.
    """
    pass

__len__() abstractmethod

Returns the total number of items in the Bag (including duplicates).

Returns:

Name Type Description
int int

The total number of items in the Bag.

Examples:

>>> bag: Bag[int] = Bag()
>>> bag.add(1)
>>> bag.add(2)
>>> bag.add(1)

>>> bag.size()
3
Source code in src/datastructures/ibag.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
@abstractmethod
def __len__(self) -> int:
    """
    Returns the total number of items in the Bag (including duplicates).

    Returns:
        int: The total number of items in the Bag.

    Examples:
        >>> bag: Bag[int] = Bag()
        >>> bag.add(1)
        >>> bag.add(2)
        >>> bag.add(1)

        >>> bag.size()
        3
    """
    pass

add(item) abstractmethod

Adds an item to the Bag.

Parameters:

Name Type Description Default
item T

The item to add.

 required

Returns:

Type Description
None

None

Raises:

Type Description
TypeError

If the item is None.

Examples:

>>> bag: Bag[int] = Bag()
>>> bag.add(1)
>>> bag.add(2)
>>> bag.add(1)

>>> bag.count(1)
2
>>> bag.count(2)
1
>>> bag.add(None)
TypeError: Item cannot be None
Source code in src/datastructures/ibag.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
@abstractmethod
def add(self, item: T) -> None:
    """
    Adds an item to the Bag.

    Args:
        item (T): The item to add.

    Returns:
        None

    Raises:
        TypeError: If the item is None.

    Examples:
        >>> bag: Bag[int] = Bag()
        >>> bag.add(1)
        >>> bag.add(2)
        >>> bag.add(1)

        >>> bag.count(1)
        2
        >>> bag.count(2)
        1
        >>> bag.add(None)
        TypeError: Item cannot be None
    """
    pass

clear() abstractmethod

Removes all items from the Bag.

Source code in src/datastructures/ibag.py 
159
160
161
162
163
164
@abstractmethod
def clear(self) -> None:
    """
    Removes all items from the Bag.
    """
    pass

count(item) abstractmethod

Returns the number of occurrences of the item in the Bag.

Parameters:

Name Type Description Default
item T

The item to count.

 required

Returns:

Name Type Description
int int

The number of occurrences of the item.

Examples:

>>> bag: Bag[int] = Bag()
>>> bag.add(1)
>>> bag.add(2)
>>> bag.add(1)

>>> bag.count(1)
2
>>> bag.count(2)
1
>>> bag.count(3)
0
Source code in src/datastructures/ibag.py 
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
@abstractmethod
def count(self, item: T) -> int:
    """
    Returns the number of occurrences of the item in the Bag.

    Args:
        item (T): The item to count.

    Returns:
        int: The number of occurrences of the item.

    Examples:
        >>> bag: Bag[int] = Bag()
        >>> bag.add(1)
        >>> bag.add(2)
        >>> bag.add(1)

        >>> bag.count(1)
        2
        >>> bag.count(2)
        1
        >>> bag.count(3)
        0
    """
    pass

distinct_items() abstractmethod

Returns an iterable of the distinct items in the Bag.

Returns:

Type Description
Iterable[T]

Iterable[T]: An iterable of the distinct items in the Bag.
Source code in src/datastructures/ibag.py 
123
124
125
126
127
128
129
130
131
@abstractmethod
def distinct_items(self) -> Iterable[T]:
    """
    Returns an iterable of the distinct items in the Bag.

    Returns:
        Iterable[T]: An iterable of the distinct items in the Bag.
    """
    pass

remove(item) abstractmethod

Removes one occurrence of the item from the Bag.

Parameters:

Name Type Description Default
item T

The item to remove.

 required

Returns:

Type Description
None

None

Raises:

Type Description
ValueError

If the item is not present in the Bag.

Examples:

>>> bag: Bag[int] = Bag()
>>> bag.add(1)
>>> bag.add(2)
>>> bag.add(1)

>>> bag.remove(1)
>>> bag.count(1)
1
>>> bag.remove(1)
>>> bag.count(1)
0
>>> bag.remove(1)
ValueError: Item not found in Bag
Source code in src/datastructures/ibag.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
@abstractmethod
def remove(self, item: T) -> None:
    """
    Removes one occurrence of the item from the Bag.

    Args:
        item (T): The item to remove.

    Returns:
        None

    Raises:
        ValueError: If the item is not present in the Bag.

    Examples:
        >>> bag: Bag[int] = Bag()
        >>> bag.add(1)
        >>> bag.add(2)
        >>> bag.add(1)

        >>> bag.remove(1)
        >>> bag.count(1)
        1
        >>> bag.remove(1)
        >>> bag.count(1)
        0
        >>> bag.remove(1)
        ValueError: Item not found in Bag
    """
    pass