:right-sidebar: True Iterator =================================================================== .. currentmodule:: gi.repository.Gst .. class:: Iterator(*args, **kwargs) :no-contents-entry: :Constructors: :: Iterator() new_single(type:GType, object:GObject.Value) -> Gst.Iterator Constructors ------------ .. rst-class:: interim-class .. class:: Iterator :no-index: .. classmethod:: new_single(type: type, object: ~typing.Any) -> ~gi.repository.Gst.Iterator This :obj:`~gi.repository.Gst.Iterator` is a convenient iterator for the common case where a :obj:`~gi.repository.Gst.Iterator` needs to be returned but only a single object has to be considered. This happens often for the :obj:`~gi.repository.Gst.PadIterIntLinkFunction`. :param type: :obj:`~gi.repository.GObject.Type` of the passed object :param object: object that this iterator should return Methods ------- .. rst-class:: interim-class .. class:: Iterator :no-index: .. method:: filter(func: ~typing.Callable[[None, None], int], user_data: ~typing.Any) -> ~gi.repository.Gst.Iterator Create a new iterator from an existing iterator. The new iterator will only return those elements that match the given compare function ``func``. The first parameter that is passed to ``func`` is the :obj:`~gi.repository.GObject.Value` of the current iterator element and the second parameter is ``user_data``. ``func`` should return 0 for elements that should be included in the filtered iterator. When this iterator is freed, ``it`` will also be freed. :param func: the compare function to select elements :param user_data: user data passed to the compare function .. method:: find_custom(func: ~typing.Callable[[...], int], *user_data: ~typing.Any) -> tuple[bool, ~typing.Any] Find the first element in ``it`` that matches the compare function ``func``. ``func`` should return 0 when the element is found. The first parameter to ``func`` will be the current element of the iterator and the second parameter will be ``user_data``. The result will be stored in ``elem`` if a result is found. The iterator will not be freed. This function will return :const:`False` if an error happened to the iterator or if the element wasn't found. :param func: the compare function to use :param user_data: user data passed to the compare function .. method:: fold(func: ~typing.Callable[[...], bool], ret: ~typing.Any, *user_data: ~typing.Any) -> ~gi.repository.Gst.IteratorResult Folds ``func`` over the elements of ``iter``. That is to say, ``func`` will be called as ``func`` (object, ``ret``, ``user_data``) for each object in ``it``. The normal use of this procedure is to accumulate the results of operating on the objects in ``ret``. This procedure can be used (and is used internally) to implement the :func:`~gi.repository.Gst.Iterator.foreach` and :func:`~gi.repository.Gst.Iterator.find_custom` operations. The fold will proceed as long as ``func`` returns :const:`True`. When the iterator has no more arguments, :const:`~gi.repository.Gst.IteratorResult.DONE` will be returned. If ``func`` returns :const:`False`, the fold will stop, and :const:`~gi.repository.Gst.IteratorResult.OK` will be returned. Errors or resyncs will cause fold to return :const:`~gi.repository.Gst.IteratorResult.ERROR` or :const:`~gi.repository.Gst.IteratorResult.RESYNC` as appropriate. The iterator will not be freed. :param func: the fold function :param ret: the seed value passed to the fold function :param user_data: user data passed to the fold function .. method:: foreach(func: ~typing.Callable[[...], None], *user_data: ~typing.Any) -> ~gi.repository.Gst.IteratorResult Iterate over all element of ``it`` and call the given function ``func`` for each element. :param func: the function to call for each element. :param user_data: user data passed to the function .. method:: free() -> None Free the iterator. MT safe. .. method:: next() -> tuple[~gi.repository.Gst.IteratorResult, ~typing.Any] Get the next item from the iterator in ``elem``. Only when this function returns :const:`~gi.repository.Gst.IteratorResult.OK`, ``elem`` will contain a valid value. ``elem`` must have been initialized to the type of the iterator or initialized to zeroes with :func:`~gi.repository.GObject.Value.unset`. The caller is responsible for unsetting or resetting ``elem`` with :func:`~gi.repository.GObject.Value.unset` or :func:`~gi.repository.GObject.Value.reset` after usage. When this function returns :const:`~gi.repository.Gst.IteratorResult.DONE`, no more elements can be retrieved from ``it``. A return value of :const:`~gi.repository.Gst.IteratorResult.RESYNC` indicates that the element list was concurrently updated. The user of ``it`` should call :func:`~gi.repository.Gst.Iterator.resync` to get the newly updated list. A return value of :const:`~gi.repository.Gst.IteratorResult.ERROR` indicates an unrecoverable fatal error. .. method:: push(other: ~gi.repository.Gst.Iterator) -> None Pushes ``other`` iterator onto ``it``. All calls performed on ``it`` are forwarded to ``other``. If ``other`` returns :const:`~gi.repository.Gst.IteratorResult.DONE`, it is popped again and calls are handled by ``it`` again. This function is mainly used by objects implementing the iterator next function to recurse into substructures. When :func:`~gi.repository.Gst.Iterator.resync` is called on ``it``, ``other`` will automatically be popped. MT safe. :param other: The :obj:`~gi.repository.Gst.Iterator` to push .. method:: resync() -> None Resync the iterator. this function is mostly called after :func:`~gi.repository.Gst.Iterator.next` returned :const:`~gi.repository.Gst.IteratorResult.RESYNC`. When an iterator was pushed on ``it``, it will automatically be popped again with this function. MT safe. Fields ------ .. rst-class:: interim-class .. class:: Iterator :no-index: .. attribute:: cookie The cookie; the value of the master_cookie when this iterator was created. .. attribute:: item The function to be called for each item retrieved .. attribute:: lock The lock protecting the data structure and the cookie. .. attribute:: master_cookie A pointer to the master cookie. .. attribute:: pushed The iterator that is currently pushed with :func:`~gi.repository.Gst.Iterator.push` .. attribute:: size The size of the iterator .. attribute:: type The type of the object that this iterator will return