1.. _module-pw_containers-utilities: 2 3========= 4Utilities 5========= 6.. pigweed-module-subpage:: 7 :name: pw_containers 8 9In addition to containers, this module includes some types and functions for 10working with containers and the data within them. 11 12---------------------------- 13pw::containers::FilteredView 14---------------------------- 15.. doxygenclass:: pw::containers::FilteredView 16 17------------------------------- 18pw::containers::WrappedIterator 19------------------------------- 20``pw::containers::WrappedIterator`` is a class that makes it easy to wrap an 21existing iterator type. It reduces boilerplate by providing ``operator++``, 22``operator--``, ``operator==``, ``operator!=``, and the standard iterator 23aliases (``difference_type``, ``value_type``, etc.). It does not provide the 24dereference operator; that must be supplied by a derived class. 25 26======= 27Example 28======= 29To use it, create a class that derives from ``WrappedIterator`` and define 30``operator*()`` and ``operator->()`` as appropriate. The new iterator might 31apply a transformation to or access a member of the values provided by the 32original iterator. The following example defines an iterator that multiplies the 33values in an array by 2. 34 35.. literalinclude:: examples/wrapped_iterator.cc 36 :language: cpp 37 :linenos: 38 :start-after: [pw_containers-wrapped_iterator] 39 :end-before: [pw_containers-wrapped_iterator] 40 41============================ 42Basic functional programming 43============================ 44``WrappedIterator`` may be used in concert with ``FilteredView`` to create a 45view that iterates over a matching values in a container and applies a 46transformation to the values. For example, it could be used with 47``FilteredView`` to filter a list of packets and yield only one field from the 48packet. 49 50The combination of ``FilteredView`` and ``WrappedIterator`` provides some basic 51functional programming features similar to (though much more cumbersome than) 52`generator expressions <https://www.python.org/dev/peps/pep-0289/>`_ (or `filter 53<https://docs.python.org/3/library/functions.html#filter>`_/`map 54<https://docs.python.org/3/library/functions.html#map>`_) in Python or streams 55in Java 8. ``WrappedIterator`` and ``FilteredView`` require no memory 56allocation, which is helpful when memory is too constrained to process the items 57into a new container. 58 59------------------------ 60pw::containers::to_array 61------------------------ 62``pw::containers::to_array`` is a C++14-compatible implementation of C++20's 63`std::to_array <https://en.cppreference.com/w/cpp/container/array/to_array>`_. 64In C++20, it is an alias for ``std::to_array``. It converts a C array to a 65``std::array``. 66 67------------------------- 68pw_containers/algorithm.h 69------------------------- 70.. doxygenfile:: pw_containers/algorithm.h 71 :sections: detaileddescription 72 73.. doxygenfunction:: pw::containers::AllOf 74.. doxygenfunction:: pw::containers::AnyOf 75.. doxygenfunction:: pw::containers::NoneOf 76.. doxygenfunction:: pw::containers::ForEach 77.. doxygenfunction:: pw::containers::Find 78.. doxygenfunction:: pw::containers::FindIf 79.. doxygenfunction:: pw::containers::FindIfNot 80.. doxygenfunction:: pw::containers::FindEnd(Sequence1 &sequence, Sequence2 &subsequence) 81.. doxygenfunction:: pw::containers::FindEnd(Sequence1 &sequence, Sequence2 &subsequence, BinaryPredicate &&pred) 82.. doxygenfunction:: pw::containers::FindFirstOf(C1& container, C2& options) 83.. doxygenfunction:: pw::containers::FindFirstOf(C1& container, C2& options, BinaryPredicate&& pred) 84.. doxygenfunction:: pw::containers::AdjacentFind(Sequence& sequence) 85.. doxygenfunction:: pw::containers::AdjacentFind(Sequence& sequence, BinaryPredicate&& pred) 86.. doxygenfunction:: pw::containers::Count 87.. doxygenfunction:: pw::containers::CountIf 88.. doxygenfunction:: pw::containers::Mismatch(C1& c1, C2& c2) 89.. doxygenfunction:: pw::containers::Mismatch(C1& c1, C2& c2, BinaryPredicate pred) 90.. doxygenfunction:: pw::containers::Equal(const C1& c1, const C2& c2) 91.. doxygenfunction:: pw::containers::Equal(const C1& c1, const C2& c2, BinaryPredicate&& pred) 92.. doxygenfunction:: pw::containers::IsPermutation(const C1& c1, const C2& c2) 93.. doxygenfunction:: pw::containers::IsPermutation(const C1& c1, const C2& c2, BinaryPredicate&& pred) 94.. doxygenfunction:: pw::containers::Search(Sequence1& sequence, Sequence2& subsequence) 95.. doxygenfunction:: pw::containers::Search(Sequence1& sequence, Sequence2& subsequence, BinaryPredicate&& pred) 96.. doxygenfunction:: pw::containers::SearchN(Sequence& sequence, Size count, T&& value) 97.. doxygenfunction:: pw::containers::SearchN(Sequence& sequence, Size count, T&& value, BinaryPredicate&& pred) 98