E-MailRelay
goptionmap.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2024 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file goptionmap.h
19///
20
21#ifndef G_OPTION_MAP_H
22#define G_OPTION_MAP_H
23
24#include "gdef.h"
25#include "goptionvalue.h"
26#include "gstringview.h"
27#include <string>
28#include <map>
29#include <algorithm>
30#include <functional> // std::less
31
32namespace G
33{
34 class OptionMap ;
35}
36
37//| \class G::OptionMap
38/// A multimap-like container for command-line options and their values.
39/// The values are G::OptionValue objects, so they can be valued with a
40/// string value or unvalued with an on/off status, and they can have
41/// a repeat-count. Normally populated by G::OptionParser.
42///
44{
45public:
46 using Map = std::multimap<std::string,OptionValue,std::less<std::string>> ; // NOLINT modernize-use-transparent-functors
47 using value_type = Map::value_type ;
48 using iterator = Map::iterator ;
49 using const_iterator = Map::const_iterator ;
50
51public:
52 void insert( const Map::value_type & ) ;
53 ///< Inserts the key/value pair into the map. The ordering of values
54 ///< in the map with the same key is in the order of insert()ion.
55
56 void replace( std::string_view key , const std::string & value ) ;
57 ///< Replaces all matching values with a single value.
58
59 void increment( std::string_view key ) noexcept ;
60 ///< Increments the repeat count for the given entry.
61
62 const_iterator begin() const noexcept ;
63 ///< Returns the begin iterator.
64
65 const_iterator cbegin() const noexcept ;
66 ///< Returns the begin iterator.
67
68 const_iterator end() const noexcept ;
69 ///< Returns the off-the-end iterator.
70
71 const_iterator cend() const noexcept ;
72 ///< Returns the off-the-end iterator.
73
74 const_iterator find( std::string_view ) const noexcept ;
75 ///< Finds the map entry with the given key.
76
77 void clear() ;
78 ///< Clears the map.
79
80 bool contains( std::string_view ) const noexcept ;
81 ///< Returns true if the map contains the given key, but ignoring 'off'
82 ///< option-values.
83
84 bool contains( const char * ) const noexcept ;
85 ///< Overload for c-string.
86
87 bool contains( const std::string & ) const noexcept ;
88 ///< Overload for std-string.
89
90 std::size_t count( std::string_view key ) const noexcept ;
91 ///< Returns the total repeat count for all matching entries.
92 ///< See G::OptionValue::count().
93
94 std::string value( std::string_view key , std::string_view default_ = {} ) const ;
95 ///< Returns the matching value, with concatentation into a comma-separated
96 ///< list if multivalued (with no escaping). If there are any on/off
97 ///< option-values matching the key then a single value is returned
98 ///< corresponding to the first one, being G::Str::positive() if 'on'
99 ///< or the supplied default if 'off'.
100
101 unsigned int number( std::string_view key , unsigned int default_ ) const noexcept ;
102 ///< Returns the matching value as a number.
103
104private:
105 using Range = std::pair<Map::const_iterator,Map::const_iterator> ;
106 Range findRange( std::string_view key ) const noexcept ;
107 Map::iterator findFirst( std::string_view key ) noexcept ;
108 static std::string join( Map::const_iterator , Map::const_iterator , std::string_view ) ;
109
110private:
111 Map m_map ;
112} ;
113
114#endif
A multimap-like container for command-line options and their values.
Definition: goptionmap.h:44
const_iterator find(std::string_view) const noexcept
Finds the map entry with the given key.
Definition: goptionmap.cpp:52
const_iterator begin() const noexcept
Returns the begin iterator.
Definition: goptionmap.cpp:76
void increment(std::string_view key) noexcept
Increments the repeat count for the given entry.
Definition: goptionmap.cpp:66
void replace(std::string_view key, const std::string &value)
Replaces all matching values with a single value.
Definition: goptionmap.cpp:58
const_iterator cend() const noexcept
Returns the off-the-end iterator.
Definition: goptionmap.cpp:94
const_iterator end() const noexcept
Returns the off-the-end iterator.
Definition: goptionmap.cpp:88
bool contains(std::string_view) const noexcept
Returns true if the map contains the given key, but ignoring 'off' option-values.
Definition: goptionmap.cpp:105
const_iterator cbegin() const noexcept
Returns the begin iterator.
Definition: goptionmap.cpp:82
unsigned int number(std::string_view key, unsigned int default_) const noexcept
Returns the matching value as a number.
Definition: goptionmap.cpp:161
void clear()
Clears the map.
Definition: goptionmap.cpp:100
std::string value(std::string_view key, std::string_view default_={}) const
Returns the matching value, with concatentation into a comma-separated list if multivalued (with no e...
Definition: goptionmap.cpp:136
std::size_t count(std::string_view key) const noexcept
Returns the total repeat count for all matching entries.
Definition: goptionmap.cpp:127
void insert(const Map::value_type &)
Inserts the key/value pair into the map.
Definition: goptionmap.cpp:27
Low-level classes.
Definition: garg.h:36