.TH "FBB::Ranger" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Error handler"

.PP 
.SH "NAME"
FBB::Ranger \- generalizes ranges for range\-based for\-loops
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/ranger>\fP
.br 

.PP 
.SH "DESCRIPTION"

.PP 
The \fIRanger\fP 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 \fIbegin\fP and \fIend\fP 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\&. 
.PP 
\fIRanger\fP 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\&.
.PP 
\fIRanger\fP is a class template requiring one template type parameter:
\fIIterator\fP, an iterator or pointer type reaching the data when dereferenced\&.
.PP 
\fIRanger\fP\(cq\&s users don\(cq\&t have to specify \fIRanger\fP\(cq\&s template type\&. The
function template \fIranger\fP returns the appropriate \fIRanger\fP object\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "FREE FUNCTION"
When using the following free functions, any (subrange) of iterators or
pointers can be used\&. With iterators subranges of \fIreverse iterators\fP can
also be specified\&. The \fBEXAMPLE\fP section below illustrates the use of the
\fIranger\fP function templates\&.
.IP o 
\fBRanger<Iterator> ranger(Iterator &&begin, Iterator &&end)\fP:
.br 
this function template returns a \fIRanger\fP object for the (sub)range
defined by two (reverse) iterators;
.IP o 
\fBRanger<Iterator> ranger(Iterator &&begin, size_t count)\fP:
.br 
this function template returns a \fIRanger\fP object for the (sub)range
defined by the (reverse) iterator range \fIbegin\fP and \fIbegin +
count\fP;
.IP o 
\fBRanger<Data *> ranger(Data *begin, Data *end)\fP:
.br 
this function template returns a \fIRanger\fP object for the (sub)range
defined by the two pointers \fIbegin\fP and \fIend\fP;
.IP o 
\fBRanger<Data *> ranger(Data *begin, size_t count)\fP:
.br 
this function template returns a \fIRanger\fP object for the (sub)range
defined by the two pointers \fIbegin\fP and \fIbegin + count\fP\&. 

.PP 
.SH "CONSTRUCTORS"
Below, \fIIterator\fP refers to the \fIRanger\fP class template\(cq\&s type
parameter\&. Although named \(cq\&Iterator\(cq\& it can also be a pointer to some data
type (e\&.g\&., \fIstd::string *\fP)\&.
.IP o 
\fBRanger(Iterator const &begin, Iterator const &end)\fP:
.br 
A \fIRanger\fP 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\&.

.PP 
Copy and move constructors (and assignment operators) are available\&.
.PP 
.SH "MEMBER FUNCTIONS"
.IP o 
\fBIterator const &begin() const\fP:
.br 
returns (a copy of) the \fIbegin\fP iterator passed to the \fIRanger\fP\(cq\&s
constructor\&. Note that if \fIIterator\fP was a pointer type (like \fIint *\fP) the
data to which the iterator returned by \fIbegin()\fP can actually be modified,
as the member\(cq\&s return type (using \fIint *\fP for \fIIterator\fP) becomes \fIint
* const &\fP, so a reference to a constant pointer to an \fIint\fP\&. This is
perfectly OK: if the data themselves should be immutable, then the data type
must be defined as \fIint const\fP, which is automatically the case when passing
\fIint const *\fP data\&. See the \fBEXAMPLE\fP section for an illustration\&.
.IP o 
\fBIterator const &end() const\fP:
.br 
returns (a copy of) the \fIend\fP iterator passed to the \fIRanger\fP\(cq\&s
constructor\&. 
If reverse iterators are passed to \fIRanger\fP\(cq\&s constructor, then 
the \fIbegin\fP and \fIend\fP members return \fIreverse iterators\fP\&. Since 
the intended use of \fIRanger\fP objects is to define a range for range\-base
for\-loops, members like \fIrbegin\fP and \fIrend\fP can be omitted from
\fIRanger\fP\&.
.PP 
.SH "EXAMPLE"
.nf 
#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++ << \(cq\& \(cq\&;
    cout << \(cq\&\en\(cq\&;
                                    // display a reversed range
    for(auto &el: ranger(iv\&.rbegin() + 1, iv\&.rend() \- 1))
        cout << el << \(cq\& \(cq\&;
    cout << \(cq\&\en\(cq\&;
                                    // same: display using a count
    for(auto &el: ranger(iv\&.rbegin() + 1, 3))
        cout << el << \(cq\& \(cq\&;
    cout << \(cq\&\en\(cq\&;

    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++ << \(cq\& \(cq\&;
    cout << \(cq\&\en\(cq\&;
                                    // data now modified
    for(auto &el: ranger(intArray + 1, intArray + 3))
        cout << el << \(cq\& \(cq\&;
    cout << \(cq\&\en\(cq\&;
                                    // using a count rather than an
                                    // end\-pointer
    for(auto &el: ranger(intArray + 1, 3))
        cout << el << \(cq\& \(cq\&;
    cout << \(cq\&\en\(cq\&;

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

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


.fi 

.PP 
.SH "FILES"
\fIbobcat/ranger\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7)
.PP 
.SH "BUGS"
None Reported\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the 
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP