arbitrary_element

arbitrary_element(iterable)

Returns an arbitrary element of iterable without removing it.

This is most useful for “peeking” at an arbitrary element of a set, but can be used for any list, dictionary, etc., as well.

Parameters

iterableabc.collections.Iterable instance

Any object that implements __iter__, e.g. set, dict, list, tuple, etc.

Returns

The object that results from next(iter(iterable))

Raises

ValueError

If iterable is an iterator (because the current implementation of this function would consume an element from the iterator).

Notes

This function does not return a random element. If iterable is ordered, sequential calls will return the same value:

>>> l = [1, 2, 3]
>>> nx.utils.arbitrary_element(l)
1
>>> nx.utils.arbitrary_element(l)
1

Examples

Arbitrary elements from common Iterable objects:

>>> nx.utils.arbitrary_element([1, 2, 3])  # list
1
>>> nx.utils.arbitrary_element((1, 2, 3))  # tuple
1
>>> nx.utils.arbitrary_element({1, 2, 3})  # set
1
>>> d = {k: v for k, v in zip([1, 2, 3], [3, 2, 1])}
>>> nx.utils.arbitrary_element(d)  # dict_keys
1
>>> nx.utils.arbitrary_element(d.values())   # dict values
3

str is also an Iterable:

>>> nx.utils.arbitrary_element("hello")
'h'

ValueError is raised if iterable is an iterator:

>>> iterator = iter([1, 2, 3])  # Iterator, *not* Iterable
>>> nx.utils.arbitrary_element(iterator)
Traceback (most recent call last):
    ...
ValueError: cannot return an arbitrary item from an iterator