Python Set add()

Python’s set.add(element) method adds the element to this set. If the element is already present in the set, the method returns without any side effect.

Here’s a minimal example where we add element 4 to an existing set:

>>> s = {1, 2, 3}
>>> s.add(4)
>>> s
{1, 2, 3, 4}

Syntax

Let’s dive into the formal syntax of the set.add() method.

set.add(element)

Return Value of Set add()

The return value of set.add() is None.

What is a Hashable Object?

You can only add hashable objects to a set. But what does it mean for an object to be hashable?

Hashing an object means that you put it through a hash function that assigns an integer to the object. Python does this by means of the object.__hash__() “dunder” or “double-underscore” method. This method defines the behavior for an object if you pass it into Python’s built-in hash() function.

? Python’s built-in hash(object) function takes one object as an argument and returns its hash value. As the hash value is calculated based on the object’s data, two different but equal objects must have the same hash value.

You can learn everything about it in this video:

Why is it important for an object to be hashable?

The reason is simple: the set and dictionary data structures are based on a so-called hash table data structure. This data structure allows for quick retrieval of any given object just by calling its hash function. Think of it this way: the return value of the hash function hints on the location of the element in the container data structure.

This is the primary reason that the set and dictionary data structures are so efficient in terms of the membership and retrieval operations.

In other words, hashability allows an object to be used as part of a set or dictionary because of the proper implementation of the discussed hash functions.

However, not all objects can be passed into the hash() function—only hashable objects. The condition on hashable objects is that they never change, have implemented the __hash__() method, and they can be compared to objects by implementing the dunder __eq__() method as well.

• An object with implemented __hash__() method but not implemented __eq__() method is not hashable.
• An object with implemented __eq__() method but not implemented __hash__() method is not hashable.
• An object with implemented __hash__() and __eq__() methods is hashable.
• An object with implemented __hash__() and __eq__() methods but that is mutable is not hashable. The reason is that mutability allows for a change of the objects data values which could result in a change of the return value of __hash__() which could break the code because it could lead to a behavior where an element is at one time part of the data structure and at another time not.

Furthermore, if two hashable objects have the same hash values as returned by the __hash__() method, they must also compare equal in regards to the __eq__() method.

How to Add an Element to a Set?

To add a hashable element to a set, call set.add(element). If the element is already a member of the set, the set doesn’t change.

>>> fruits = {'banana', 'apple'}
>>> fruits.add('strawberry')
>>> fruits
{'apple', 'banana', 'strawberry'}
>>> fruits.add('strawberry')
>>> fruits
{'apple', 'banana', 'strawberry'}

👉 Recommended Tutorial: How to Add Elements to a Python Set?

How to Add to an Empty Set in Python?

To add a hashable element to an empty set, call set.add(element).

>>> fruits = set()
>>> fruits.add('strawberry')
>>> fruits
{'strawberry'}

How to Add Multiple Elements to a Set?

To add multiple or all elements to a set that are stored in a given iterable, pass the iterable in the function set.update(iterable).

>>> fruits = {'apple', 'banana'}
>>> basket_to_add = ['strawberry', 'cocos']
>>> fruits.update(basket_to_add)
>>> fruits
{'apple', 'cocos', 'banana', 'strawberry'}

How to Add a List to a Set?

Given a set and a list. To add all list elements to a set, pass the iterable in the function set.update(iterable).

>>> fruits = {'apple', 'banana'}
>>> basket_to_add = ['strawberry', 'cocos']
>>> fruits.update(basket_to_add)
>>> fruits
{'apple', 'cocos', 'banana', 'strawberry'}

Python Set add() vs update()

The difference between set.add(element) and set.update(elements) is that the former adds a single element to a set and the latter adds multiple elements to a set.

In other words:

• set.add() adds an element to this set.
• set.update() adds all elements that are in any of the specified set arguments.

This code example shows both functions in action:

>>> fruits = {'apple', 'banana'}
>>> basket_to_add = ['strawberry', 'cocos']
>>> fruits.update(basket_to_add)
>>> fruits
{'apple', 'cocos', 'banana', 'strawberry'}
>>> fruits.add('berry')
>>> fruits
{'berry', 'strawberry', 'banana', 'apple', 'cocos'}

What is the Time Complexity of Set add()?

The runtime complexity of the set.add() function is O(1) because Python’s set data structure is implemented as a hash table and you can expect lookup, insert, and delete operations to have constant runtime complexity. However, this is only an average—from time to time you may run into collisions which could cause the runtime complexity to increase to O(n) due to the collision handling. On average, though, the runtime complexity of set.add() remains O(1).

You can see this in the following simple experiment where we run the set method multiple times for an increasing number of set elements.

I ran this experiment on my Acer Aspire 5 notebook (I know) with Intel Core i7 (8th Gen) processor and 16GB of memory. Here’s the code of the experiment:

import matplotlib.pyplot as plt
import random
import time

sizes = [10**3, 10**4, 10**5, 10**6, 10**7]
runtimes = []

for size in sizes:
    s = set(range(size))

    # Start track time ...
    t1 = time.time()
    s.add(9999999999999)
    s.add(42)
    t2 = time.time()
    # ... end track time
    
    runtimes.append(t2-t1)


plt.plot(sizes, runtimes)
plt.ylabel('Runtime (s)')
plt.xlabel('Set Size')

plt.show()

Other Python Set Methods

All set methods are called on a given set. For example, if you created a set s = {1, 2, 3}, you’d call s.clear() to remove all elements of the set. We use the term “this set” to refer to the set on which the method is executed.