next(PythonObject) -- retrieve the next item from a python iterator

Description

This function works just like its Python counterpart. In particular, it retrieves the next item from an iterator.

i1 : builtins = import "builtins"

o1 = <module 'builtins' (built-in)>

o1 : PythonObject of class module

i2 : x = builtins@@range 3

o2 = range(0, 3)

o2 : PythonObject of class range

i3 : i = iterator x

o3 = <range_iterator object at 0x7f809fe32bb0>

o3 : PythonObject of class range_iterator

i4 : next i

o4 = 0

o4 : PythonObject of class int

i5 : next i

o5 = 1

o5 : PythonObject of class int

i6 : next i

o6 = 2

o6 : PythonObject of class int

When the iterator is exhausted, StopIteration is returned.

i7 : next i

o7 = StopIteration

o7 : Symbol

The source of this document is in Python/doc.m2:325:0.