:right-sidebar: True Iterator =================================================================== .. currentmodule:: gi.repository.Gst .. class:: Iterator(*args, **kwargs) :no-contents-entry: A GstIterator is used to retrieve multiple objects from another object in a threadsafe way. Various GStreamer objects provide access to their internal structures using an iterator. Note that if calling a GstIterator function results in your code receiving a refcounted object (with, say, :func:`~gi.repository.GObject.Value.get_object`), the refcount for that object will not be increased. Your code is responsible for taking a reference if it wants to continue using it later. The basic use pattern of an iterator is as follows: .. code-block:: C :dedent: GstIterator *it = _get_iterator(object); GValue item = G_VALUE_INIT; done = FALSE; while (!done) { switch (gst_iterator_next (it, &item)) { case GST_ITERATOR_OK: ...get/use/change item here... g_value_reset (&item); break; case GST_ITERATOR_RESYNC: ...rollback changes to items... gst_iterator_resync (it); break; case GST_ITERATOR_ERROR: ...wrong parameters were given... done = TRUE; break; case GST_ITERATOR_DONE: done = TRUE; break; } } g_value_unset (&item); gst_iterator_free (it); Constructors ------------ .. rst-class:: interim-class .. class:: Iterator :no-index: .. classmethod:: new_single(type: ~gobject.GType, object: ~gi.repository.GObject.Value) -> ~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[[~typing.Any, ~typing.Any], int], user_data: ~gi.repository.GObject.Value) -> ~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[[~typing.Any, ~typing.Any], int], user_data: ~typing.Any = None) -> ~typing.Tuple[bool, ~gi.repository.GObject.Value] 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[[~gi.repository.GObject.Value, ~gi.repository.GObject.Value, ~typing.Any], bool], ret: ~gi.repository.GObject.Value, user_data: ~typing.Any = None) -> ~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[[~gi.repository.GObject.Value, ~typing.Any], None], user_data: ~typing.Any = None) -> ~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() -> ~typing.Tuple[~gi.repository.Gst.IteratorResult, ~gi.repository.GObject.Value] 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