Skip to main content
`Ctrl`+`K`

# 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:
    iterable `abc.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