FBB::Ranger - generalizes ranges for range-based for-loops

       Frank B. Brokken (f.b.brokken@rug.nl).

libbobcat-dev_6.07.01                               2005-2025                               FBB::Ranger(3bobcat)

       Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

       o      https://fbb-git.gitlab.io/bobcat/: gitlab project page;

       Debian Bobcat project files:

       o      libbobcat6: debian package containing the shared library, changelog and copyright note;

       o      libbobcat-dev: debian package containing the static library, headers, manual pages, and  developer
              info;

       None Reported.

       Below,  Iterator  refers  to the Ranger class template’s type parameter. Although named ’Iterator’ it can
       also be a pointer to some data type (e.g., std::string*).

       o      Ranger(Iteratorconst&begin,Iteratorconst&end):
              A Ranger object can be passed as range-specifier in a range-based for-loop. All  elements  defined
              by the range will subsequently be visited by the range-based for-loop.

       Copy and move constructors (and assignment operators) are available.

       This is free software, distributed under the terms of the GNU General Public License (GPL).

       The  Ranger  class  template  defines  ranges  that  can be used with range-based for-loops. The standard
       range-based for-loop requires for its range-specificiation an array or an iterator range as  offered  by,
       e.g.,  containers  (through  their  begin  and end members). Ranges defined by a pair of pointers or by a
       subrange defined by iterator expressions  cannot  currently  be  used  in  combination  with  range-based
       for-loops.

       Ranger  extends  the  applicability  of  range-based  for-loops  by turning pairs of pointers, an initial
       pointer and a pointer count, or a pair of iterators  into  a  range  that  can  be  used  by  range-based
       for-loops.

       Ranger  is  a class template requiring one template type parameter: Iterator, an iterator or pointer type
       reaching the data when dereferenced.

       Ranger’s users don’t have to specify Ranger’s template type. The function  template  ranger  returns  the
       appropriate Ranger object.

       #include <vector>
       #include <iostream>

       #include <bobcat/ranger>

       using namespace std;
       using namespace FBB;

       int main()
       {
           vector<int> iv {1, 2, 3, 4, 5};
                                           // display and modify a subrange
           for(auto &el: ranger(iv.rbegin() + 1, iv.rend() - 1))
               cout << el++ << ’ ’;
           cout << ’\n’;
                                           // display a reversed range
           for(auto &el: ranger(iv.rbegin() + 1, iv.rend() - 1))
               cout << el << ’ ’;
           cout << ’\n’;
                                           // same: display using a count
           for(auto &el: ranger(iv.rbegin() + 1, 3))
               cout << el << ’ ’;
           cout << ’\n’;

           int intArray[] = {1, 2, 3, 4, 5};
                                           // display and modify elements
                                           // in a pointer-based range
           for(auto &el: ranger(intArray + 1, intArray + 3))
               cout << el++ << ’ ’;
           cout << ’\n’;
                                           // data now modified
           for(auto &el: ranger(intArray + 1, intArray + 3))
               cout << el << ’ ’;
           cout << ’\n’;
                                           // using a count rather than an
                                           // end-pointer
           for(auto &el: ranger(intArray + 1, 3))
               cout << el << ’ ’;
           cout << ’\n’;

           int const constInts[] = {1, 2, 3, 4, 5};

                                           // data can’t be modified
           for(auto &el: ranger(constInts + 1, constInts + 3))
               cout << el << ’ ’;
           cout << ’\n’;
       }

bobcat/ranger - defines the class interface

       When using the following free functions, any (subrange) of  iterators  or  pointers  can  be  used.  With
       iterators subranges of reverseiterators can also be specified. The EXAMPLE section below illustrates the
       use of the ranger function templates.

       o      Ranger<Iterator>ranger(Iterator&&begin,Iterator&&end):
              this  function  template  returns  a  Ranger  object  for  the (sub)range defined by two (reverse)
              iterators;

       o      Ranger<Iterator>ranger(Iterator&&begin,size_tcount):
              this function template returns a Ranger  object  for  the  (sub)range  defined  by  the  (reverse)
              iterator range begin and begin+count;

       o      Ranger<Data*>ranger(Data*begin,Data*end):
              this  function  template  returns  a  Ranger object for the (sub)range defined by the two pointers
              begin and end;

       o      Ranger<Data*>ranger(Data*begin,size_tcount):
              this function template returns a Ranger object for the (sub)range  defined  by  the  two  pointers
              begin and begin+count.

       o      Iteratorconst&begin()const:
              returns  (a  copy of) the begin iterator passed to the Ranger’s constructor. Note that if Iterator
              was a pointer type (like int*) the data to which the iterator returned by begin() can actually be
              modified, as the member’s return type (using int* for Iterator) becomes  int*const&,  so  a
              reference  to a constant pointer to an int. This is perfectly OK: if the data themselves should be
              immutable, then the data type must be defined as intconst, which is automatically the  case  when
              passing intconst* data. See the EXAMPLE section for an illustration.

       o      Iteratorconst&end()const:
              returns (a copy of) the end iterator passed to the Ranger’s constructor.  If reverse iterators are
              passed to Ranger’s constructor, then the begin and end members return reverseiterators. Since the
              intended  use of Ranger objects is to define a range for range-base for-loops, members like rbegin
              and rend can be omitted from Ranger.

       FBB::Ranger - generalizes ranges for range-based for-loops

FBB
       All  constructors,  members,  operators  and manipulators, mentioned in this man-page, are defined in the
       namespace FBB.

bobcat(7), reverse(3bobcat)

#include<bobcat/ranger>