.TH "FBB::LinearMap" "3bobcat" "2005\-2023" "libbobcat\-dev_6\&.04\&.00" "Linear\-search based mapping container" .PP .SH "NAME" FBB::LinearMap \- A mapping container using linear searching .PP .SH "SYNOPSIS" \fB#include \fP .br .PP .SH "DESCRIPTION" The class template \fBLinearMap\fP implements a mapping container using a linear searching algorithm\&. A mapping container using linear searching is less complex than either the sorted \fIstd::map\fP or the unsorted \fIstd::unordered_map\fP container\&. For relative small number of elements the linear search algorithm is also faster than the binary search or hashing\-based searching algorithms\&. .PP \fBLinearMap\fP implements all of the members which are also found in the standard \fIstd::map\fP, except for the \fIkey_comp\fP and \fIvalue_comp\fP members\&. These latter two members are not available as ordering the keys is not an issue with the unordered, linear searching method which is used by \fBLinearMap\fP\&. .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 "INHERITS (PRIVATELY) FROM" \fIstd::vector\fP .PP .SH "TEMPLATE TYPES" The full template type definition of \fBLinearMap\fP is: .nf template < typename Key, typename Value > .fi The \fIKey\fP type must offer \fIbool operator==\fP\&. Furthermore, \fIKey\fP and \fIValue\fP types must support default and copy constructors and overloaded (copy) assignment operators\&. .PP .SH "USING SPECIFICATIONS" .IP o \fIusing value_type = std::pair\fP; .IP o \fIiterator\fP \- an iterator to a \fBLinearMap\fP object\(cq\&s elements; .IP o \fIconst_iterator\fP \- a \fIconst_iterator\fP to a \fBLinearMap\fP object\(cq\&s elements; .IP o \fIreverse_iterator\fP \- a \fIreverse_iterator\fP to a \fBLinearMap\fP object\(cq\&s elements; .IP o \fIconst_reverse_iterator\fP \- a \fIconst_reverse_iterator\fP to a \fBLinearMap\fP object\(cq\&s elements\&. .PP .SH "CONSTRUCTORS" .IP o \fBLinearMap(Iterator begin, Iterator end)\fP: .br The constructor is initialized using the iterator range \fI[begin, end)\fP, where \fIIterator\fP is any iterator type pointing to \fIvalue_type\fP objects\&. If identical keys \fIK\fP are used then only the first occurrence of the \fIvalue_type\fP object using key \fIK\fP is inserted\&. .IP .IP o \fBLinearMap(std:initializer_list initial)\fP: .br The constructor is initialized with the values stored in the \fIstd::initializer_list\fP of \fIvalue_type\fP objects\&. If identical keys \fIK\fP are used then only the first occurrence of the \fIvalue_type\fP object using key \fIK\fP is inserted\&. .PP Default, copy and move constructors (and copy and move assignment operators) are available\&. .PP .SH "OVERLOADED OPERATORS" .IP o \fBValue &operator[](Key const &key)\fP: .br A reference to the \fIValue\fP associated with \fIkey\fP is returned\&. If \fIkey\fP was not available prior to the call of the index operator a \fIvalue_map(key, Value()) object is inserted\&. \fP .IP .SH "MEMBER FUNCTIONS" Note that the members of \fIstd::vector\fP are not automatically available, as \fBLinearMap\fP is privately inherited from \fIstd::vector\fP\&. .IP \fBLinearMap\fP offers the following member functions: .IP o \fBValue &at(int idx)\fP: .br returns a reference to the \fBLinearMap\fP\(cq\&s \fIValue\fP that is associated with \fIkey\fP\&. If the \fIkey\fP is not stored in the \fBLinearMap\fP then an \fBstd::out_of_range\fP exception is thrown\&. .IP .IP o \fBiterator begin()\fP: .br returns an iterator pointing to the \fBLinearMap\fP\(cq\&s first element\&. .IP .IP o \fBsize_t capacity()\fP: .br returns the number of elements that can be stored in the \fBLinearMap\fP before its capacity is enlarged\&. .IP .IP o \fBconst_iterator cbegin() const\fP: .br returns a \fIconst_iterator\fP pointing to the \fBLinearMap\fP\(cq\&s first element\&. .IP .IP o \fBconst_iterator cend() const\fP: .br returns a \fIconst_iterator\fP pointing beyond the \fBLinearMap\fP\(cq\&s last element\&. .IP .IP o \fBvoid clear()\fP: .br erases all elements from the \fBLinearMap\fP\&. .IP .IP o \fBsize_t count(key)\fP: .br returns 1 if the provided key is available in the \fBLinearMap\fP, otherwise 0 is returned\&. .IP .IP o \fBconst_reverse_iterator crbegin() const\fP: .br returns a \fIconst_reverse_iterator\fP pointing to a \fBLinearMap\fP object\(cq\&s last element\&. .IP .IP o \fBconst_reverse_iterator crend() const\fP: .br returns a \fIconst_reverse_iterator\fP pointing before a \fBLinearMap\fP object\(cq\&s first element\&. .IP .IP o \fBstd::pair emplace(Args &&\&.\&.\&.args)\fP: .br a \fIvalue_type\fP object is constructed from \fIemplace\fP\(cq\&s arguments\&. A \fIstd::pair\fP is returned containing an iterator pointing to the object using that key\&. If the \fBLinearMap\fP already contains an object having the provided \fIKey\fP value then the returned \fIstd::pair\(cq\&s bool\fP value is \fIfalse\fP\&. If the provided \fIkey\fP was not found, then the newly constructed object is inserted into the \fBLinearMap\fP, and the returned \fIstd::pair\(cq\&s bool\fP value is \fItrue\fP\&. .IP .IP o \fBbool empty()\fP: .br returns \fItrue\fP if the \fBLinearMap\fP contains no elements\&. .IP .IP o \fBiterator end()\fP: .br returns an iterator pointing beyond the \fBLinearMap\fP\(cq\&s last element\&. .IP .IP o \fBstd::pair equal_range(key)\fP: .br returns a pair of iterators, being respectively the return values of the member functions \fIlower_bound\fP and \fIupper_bound\fP\&. .IP .IP o \fBbool erase(Key const &key)\fP: .br erases the element having the given \fIkey\fP from the \fBLinearMap\fP\&. \fITrue\fP is returned if the value was removed, \fIfalse\fP if the \fBLinearMap\fP did not contain an element using the given \fIkey\fP\&. .IP .IP o \fBvoid erase(iterator pos)\fP: .br erases the element at iterator position \fIpos\fP\&. .IP .IP o \fBvoid erase(iterator begin, iterator end)\fP: .br erases all elements indicated by the iterator range \fI[first, beyond)\fP\&. .IP .IP o \fBiterator find(Key const &key)\fP: .br returns an iterator to the element having the given key\&. If the element isn\(cq\&t available, \fIend\fP is returned\&. .IP .IP o \fBconst_iterator find(Key const &key) const\fP: .br returns a \fIconst_iterator\fP to the element having the given key\&. If the element isn\(cq\&t available, \fIend\fP is returned\&. .IP .IP o \fBallocator_type get_allocator() const\fP: .br returns a copy of the allocator object used by the \fI\fBLinearMap\fP\fP object\&. .IP .IP o \fBstd::pair insert(value_type const &keyValue)\fP: .br tries to inserts a new \fIvalue_type\fP object into the \fBLinearMap\fP, returning a \fIstd::pair\fP\&. If the returned ti(bool) field is \fItrue\fP, \fIkeyValue\fP was inserted into the \fBLinearMap\fP\&. The value \fIfalse\fP indicates that the specified key was already available, and \fIkeyvalue\fP was not inserted into the \fBLinearMap\fP\&. In both cases the \fIiterator\fP field points to the data element having the specified \fIkey\fP\&. .IP .IP o \fBiterator insert(iterator pos, value_type const &keyValue)\fP: .br tries to insert \fIkeyValue\fP into the \fBLinearMap\fP\&. \fIPos\fP is ignored, and an iterator to the element having \fIkeyValue\fP\(cq\&s key value is returned\&. If the specified key was already present, \fIkeyValue\fP is not inserted into the \fBLinearMap\fP\&. .IP .IP o \fBvoid insert(Iterator begin, Iterator end)\fP: .br tries to insert the \fIvalue_type\fP elements pointed at by the iterator range \fI[begin, end)\fP objects into the \fBLinearMap\fP\&. \fIIterator\fP is any iterator type pointing to \fIvalue_type\fP objects\&. Already existing \fIvalue_type\fP elements having keys equal to the keys of the elements pointed at by the iterator range are not replaced\&. .IP .IP o \fBiterator lower_bound(Key const &key)\fP: .br returns an iterator pointing to the \fIkeyvalue\fP element having the specified \fIkey\fP\&. If no such element exists, \fIend\fP is returned\&. .IP .IP o \fBconst_iterator lower_bound(Key const &key) const\fP: .br returns a \fIconst_iterator\fP pointing to the \fIkeyvalue\fP element having the specified \fIkey\fP\&. If no such element exists, \fIend\fP is returned\&. .IP .IP o \fBsize_t max_size() const\fP: .br returns the maximum number of elements this \fI\fBLinearMap\fP\fP may contain\&. .IP .IP o \fBreverse_iterator rbegin()\fP: .br returns a \fIreverse_iterator\fP pointing to the \fBLinearMap\fP object\(cq\&s last element\&. .IP .IP o \fBconst_reverse_iterator rbegin() const\fP: .br returns a \fIconst_reverse_iterator\fP pointing to the \fBLinearMap\fP object\(cq\&s last element\&. .IP .IP o \fBreverse_iterator rend()\fP: .br returns a \fIreverse_iterator\fP pointing before the \fBLinearMap\fP object\(cq\&s first element\&. .IP .IP o \fBconst_reverse_iterator rbegin() const\fP: .br returns a \fIconst_reverse_iterator\fP pointing before the \fBLinearMap\fP object\(cq\&s first element\&. .IP .IP o \fBsize_t size() const\fP: .br returns the number of elements in the \fBLinearMap\fP\&. .IP .IP o \fBvoid swap(LinearMap &other)\fP: .br swaps two \fBLinearMap\fPs using identical \fIKey\fP and \fIValue\fP types\&. .IP .IP o \fBiterator upper_bound(Key const &key)\fP: .br returns an iterator pointing to the \fIkeyvalue\fP element having the specified \fIkey\fP\&. If no such element exists, \fIend\fP is returned\&. .IP .IP o \fBconst_iterator upper_bound(Key const &key) const\fP: .br returns a \fIconst_iterator\fP pointing to the \fIkeyvalue\fP element having the specified \fIkey\fP\&. If no such element exists, \fIend\fP is returned\&. .PP .SH "EXAMPLE" .nf #include #include #include #include using namespace std; using namespace FBB; int main() { typedef LinearMap LM; // constructors: LM lm; LM lm2 = { {\(dq\&one\(dq\&, \(dq\&value 1\(dq\&}, {\(dq\&two\(dq\&, \(dq\&value 2\(dq\&} }; LM lm3(lm2); LM lm4(lm3\&.begin(), lm3\&.end()); // assignment: lm = lm2; // some members: lm[\(dq\&key\(dq\&] = \(dq\&value\(dq\&; cout << lm[\(dq\&key\(dq\&] << \(cq\&\en\(cq\&; cout << lm\&.find(\(dq\&key\(dq\&)\->second << \(cq\&\en\(cq\&; for (auto value: lm) cout << \(dq\&For loop: \(dq\& << value\&.first << \(dq\&, \(dq\& << value\&.second << \(cq\&\en\(cq\&; cerr << \(dq\&# times \(cq\&key\(cq\& is stored: \(dq\& << lm\&.count(\(dq\&key\(dq\&) << \(dq\&\en\(dq\& \(dq\&# times \(cq\&value is stored: \(dq\& << lm\&.count(\(dq\&value\(dq\&) << \(cq\&\en\(cq\&; lm4 = lm2; cout << \(dq\&lm4\(cq\&s size after assignment: \(dq\& << lm4\&.size() << \(cq\&\en\(cq\&; lm4\&.clear(); cout << \(dq\&lm4\(cq\&s size after clear: \(dq\& << lm4\&.size() << \(cq\&\en\(cq\&; }; .fi .PP .SH "FILES" \fIbobcat/linearmap\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_6\&.04\&.00\-x\&.dsc\fP: detached signature; .IP o \fIbobcat_6\&.04\&.00\-x\&.tar\&.gz\fP: source archive; .IP o \fIbobcat_6\&.04\&.00\-x_i386\&.changes\fP: change log; .IP o \fIlibbobcat1_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the libraries; .IP o \fIlibbobcat1\-dev_6\&.04\&.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