cart
====

.. module:: cart

Short for Cartesian, the :func:`~.cart` gear combines data from its inputs, at least one of which is of the :class:`~.Queue` type. It combines each element of the data received at its second input with whole data value received at its first input. 

.. py:function:: cart(*din)

   Most often the :func:`~.cart` gear is used to combine a :class:`~.Queue` and some other non-Queue data, so that the non-Queue data is replicated for each element of the :class:`~.Queue`.

   Imagine if we have a :class:`~.Queue` of ``x`` coordinates ``[10, 11, 12]``, and we would like to attach to each of them an ``y`` coordinate to form a point. The ``y`` coordinate is generated by a source which does not know how long our :class:`~.Queue` -s are so it only outputs a single value ``0``, which is than replicated by the :func:`~.cart` gear for each element of the :class:`~.Queue` carrying the ``x`` coordinate. The result of the :func:`~.cart` operation is a :class:`~.Queue` of points ``[(10, 0), (11, 0), (12, 0)]``. Observe how the value ``0``, received at ``din1`` input of the :func:`~.cart` gear is acknowledged only after it has been combined with all the elements of the :class:`~.Queue` (in the third cycle).

   .. pg-example:: examples/cart_point
      :lines: 4-7

   Next example has identical data types as the previous one, only its driving sequence is longer.  

   .. pg-example:: examples/cart_one_queue
      :lines: 4-7

   Finally, this example shows how two :class:`~.Queue` -s are combined using the :class:`~.cart` gear. 

   .. pg-example:: examples/cart_two_queue
      :lines: 4-7


.. py:function:: cart_sync(*din)

   Performs the same operation as the :func:`~.cart` gear regarding the data replication, however it does not combine the data at the output, but outputs each of the data via separate interface. 

   .. pg-example:: examples/cart_sync
      :lines: 4-9

.. py:function:: cart_sync_with(sync_in, din) -> din

   Performs the same operation as the :func:`~.cart` gear regarding the data replication, however it does not combine the data at the output, but outputs only the interface whose data has been replicated. Useful if we don't need the data combination, just the replication.

   .. pg-example:: examples/cart_sync_with
      :lines: 4-8