From: Piotrek Zadroga Date: Mon, 15 Apr 2024 20:33:27 +0000 (+0200) Subject: [#3319] lib util doxygen refactor X-Git-Tag: Kea-2.5.8~64 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9b2d9218ba46f7f62ce73519193c9ff4a9929a30;p=thirdparty%2Fkea.git [#3319] lib util doxygen refactor - also imports reorder --- diff --git a/src/lib/util/buffer.h b/src/lib/util/buffer.h index 7ae841e0d9..ee6ac1c1f4 100644 --- a/src/lib/util/buffer.h +++ b/src/lib/util/buffer.h @@ -1,49 +1,37 @@ // Copyright (C) 2009-2024 Internet Systems Consortium, Inc. ("ISC") -// // This Source Code Form is subject to the terms of the Mozilla Public // License, v. 2.0. If a copy of the MPL was not distributed with this // file, You can obtain one at http://mozilla.org/MPL/2.0/. - #ifndef BUFFER_H #define BUFFER_H - -#include - -#include - +#include +#include #include -#include -#include +#include #include -namespace isc { -namespace util { - -/// @brief The @c InputBuffer class is a buffer abstraction for -/// manipulating read-only data. -/// -/// The main purpose of this class is to provide a safe placeholder +#include +#include +namespace isc::util { +/// @brief The @c InputBuffer class is a buffer abstraction for manipulating read-only data. +/// @details The main purpose of this class is to provide a safe placeholder /// for examining wire-format data received from a network. -/// /// Applications normally use this class only in a limited situation: /// as an interface between legacy I/O operation (such as receiving /// data from a BSD socket) and the rest of the Kea DNS library. One /// common usage of this class for an application would therefore be /// something like this: -/// -/// @code -/// unsigned char buf[1024]; -/// struct sockaddr addr; -/// socklen_t addrlen = sizeof(addr); -/// int cc = recvfrom(s, buf, sizeof(buf), 0, &addr, &addrlen); -/// InputBuffer buffer(buf, cc); -/// // pass the buffer to a DNS message object to parse the message +/// @code{.cpp} +/// unsigned char buffer[1024]; +/// struct sockaddr address; +/// socklen_t address_len = sizeof(address); +/// int cc = recvfrom(s, buffer, sizeof(buffer), 0, &address, &address_len); +/// InputBuffer buffer(buffer, cc); +/// // pass the buffer to a DNS message object to parse the message /// @endcode -/// /// Other Kea DNS classes will then use methods of this class to get /// access to the data, but the application normally doesn't have to /// care about the details. -/// /// An @c InputBuffer object internally holds a reference to the given /// data, rather than make a local copy of the data. Also, it does /// not have an ownership of the given data. It is application's @@ -54,7 +42,6 @@ namespace util { /// reference to it, the result is undefined. The application will /// also be responsible for releasing the data when it's not needed if /// it was dynamically acquired. -/// /// This is a deliberate design choice: although it's safer to make a /// local copy of the given data on construction, it would cause /// unacceptable performance overhead, especially considering that a @@ -66,7 +53,6 @@ namespace util { /// "read-only" stuff as a writable memory region. Since there /// doesn't seem to be a perfect solution, we have adopted what we /// thought a "least bad" one. -/// /// Methods for reading data from the buffer generally work like an /// input stream: it begins with the head of the data, and once some /// length of data is read from the buffer, the next read operation @@ -74,16 +60,14 @@ namespace util { /// this class internally holds (a notion of) where the next read /// operation should start. We call it the current pointer /// in this document. -/// /// The inequality base_ <= current_ <= end_ is enforced, current_ == /// base_ at the initial state, current_ == end_ when the whole buffer /// was read. Even the difference of two pointers is a std::ptrdiff_t /// it is safe to cast to a size_t because of the inequality. -class InputBuffer { -public: +class InputBuffer { // lgcrfctr +public: // lgcrfctr /// @brief Constructor. - /// - /// It is caller's responsibility to ensure that the data is valid + /// @details It is caller's responsibility to ensure that the data is valid /// as long as the buffer exists. /// @param data A pointer to the data stored in the buffer. /// @param len The length of the data in bytes. @@ -91,7 +75,6 @@ public: : base_(static_cast(data)), current_(base_), end_(base_ + len) { } - /// @brief Return the length of the data stored in the buffer. size_t getLength() const { return (static_cast(end_ - base_)); @@ -101,12 +84,9 @@ public: size_t getPosition() const { return (static_cast(current_ - base_)); } - /// @brief Set the read position of the buffer to the given value. - /// - /// The new position must be in the valid range of the buffer; + /// @details The new position must be in the valid range of the buffer; /// otherwise an exception of class @c isc::OutOfRange will be thrown. - /// /// @param position The new position (offset from the beginning of /// the buffer). void setPosition(size_t position) { @@ -114,115 +94,82 @@ public: isc_throw(OutOfRange, "InputBuffer::setPosition position is too large"); } - current_ = base_ + position; - } - + current_ = base_ + position;} /// @brief Peek an unsigned 8-bit integer from the buffer and return it. - /// - /// If the remaining length of the buffer is smaller than 8-bit, + /// @details If the remaining length of the buffer is smaller than 8-bit, /// an exception of class @c isc::OutOfRange will be thrown. uint8_t peekUint8() { if (current_ + sizeof(uint8_t) > end_) { - isc_throw(OutOfRange, - "InputBuffer::peekUint8 read beyond end of buffer"); + isc_throw(OutOfRange, "InputBuffer::peekUint8 read beyond end of buffer"); } - return (*current_); } /// @brief Read an unsigned 8-bit integer from the buffer and return it. - /// - /// If the remaining length of the buffer is smaller than 8-bit, + /// @details If the remaining length of the buffer is smaller than 8-bit, /// an exception of class @c isc::OutOfRange will be thrown. uint8_t readUint8() { uint8_t ret = peekUint8(); current_ += sizeof(uint8_t); - return (ret); } - /// @brief Peek an unsigned 16-bit integer in network byte order - /// from the buffer, and return it. - /// - /// If the remaining length of the buffer is smaller than 16-bit, + /// @brief Peek an unsigned 16-bit integer in network byte order from the buffer, and return it. + /// @details If the remaining length of the buffer is smaller than 16-bit, /// an exception of class @c isc::OutOfRange will be thrown. uint16_t peekUint16() { if (current_ + sizeof(uint16_t) > end_) { - isc_throw(OutOfRange, - "InputBuffer::peekUint16 read beyond end of buffer"); - } - + isc_throw(OutOfRange, "InputBuffer::peekUint16 read beyond end of buffer");} uint16_t ret; ret = (static_cast(current_[0])) << 8; ret |= (static_cast(current_[1])); - - return (ret); - } + return (ret);} /// @brief Read an unsigned 16-bit integer in network byte order /// from the buffer, and return it. - /// - /// If the remaining length of the buffer is smaller than 16-bit, + /// @details If the remaining length of the buffer is smaller than 16-bit, /// an exception of class @c isc::OutOfRange will be thrown. uint16_t readUint16() { uint16_t ret = peekUint16(); current_ += sizeof(uint16_t); - return (ret); } - /// @brief Read an unsigned 32-bit integer in network byte order /// from the buffer, and return it. - /// - /// If the remaining length of the buffer is smaller than 32-bit, + /// @details If the remaining length of the buffer is smaller than 32-bit, /// an exception of class @c isc::OutOfRange will be thrown. uint32_t peekUint32() { if (current_ + sizeof(uint32_t) > end_) { - isc_throw(OutOfRange, - "InputBuffer::peekUint32 read beyond end of buffer"); - } - + isc_throw(OutOfRange, "InputBuffer::peekUint32 read beyond end of buffer");} uint32_t ret; ret = (static_cast(current_[0])) << 24; ret |= (static_cast(current_[1])) << 16; ret |= (static_cast(current_[2])) << 8; ret |= (static_cast(current_[3])); - - return (ret); - } + return (ret);} /// @brief Read an unsigned 32-bit integer in network byte order /// from the buffer, and return it. - /// - /// If the remaining length of the buffer is smaller than 32-bit, + /// @details If the remaining length of the buffer is smaller than 32-bit, /// an exception of class @c isc::OutOfRange will be thrown. uint32_t readUint32() { uint32_t ret = peekUint32(); current_ += sizeof(uint32_t); - - return (ret); - } - + return (ret);} /// @brief Peek data of the specified length from the buffer and /// copy it to the caller supplied buffer. - /// - /// The data is copied as stored in the buffer; no conversion is + /// @details The data is copied as stored in the buffer; no conversion is /// performed. If the remaining length of the buffer is smaller /// than the specified length, an exception of class @c isc::OutOfRange /// will be thrown. void peekData(void* data, size_t len) { if (current_ + len > end_) { - isc_throw(OutOfRange, - "InputBuffer::peekData read beyond end of buffer"); - } - - static_cast(std::memmove(data, current_, len)); - } + isc_throw(OutOfRange, "InputBuffer::peekData read beyond end of buffer");} + static_cast(std::memmove(data, current_, len));} /// @brief Read data of the specified length from the buffer and /// copy it to the caller supplied buffer. - /// - /// The data is copied as stored in the buffer; no conversion is + /// @details The data is copied as stored in the buffer; no conversion is /// performed. If the remaining length of the buffer is smaller /// than the specified length, an exception of class @c isc::OutOfRange /// will be thrown. @@ -232,31 +179,22 @@ public: } /// @brief Peek specified number of bytes as a vector. - /// - /// If specified buffer is too short, it will be expanded using + /// @details If specified buffer is too short, it will be expanded using /// vector::resize() method. If the remaining length of the buffer /// is smaller than the specified length, an exception of class /// @c isc::OutOfRange will be thrown. - /// /// @param data Reference to a buffer (data will be stored there). /// @param len Size specified number of bytes to read in a vector. void peekVector(std::vector& data, size_t len) { if (current_ + len > end_) { - isc_throw(OutOfRange, - "InputBuffer::peekVector read beyond end of buffer"); - } - + isc_throw(OutOfRange, "InputBuffer::peekVector read beyond end of buffer");} data.resize(len); - peekData(&data[0], len); - } - + peekData(&data[0], len);} /// @brief Read specified number of bytes as a vector. - /// - /// If specified buffer is too short, it will be expanded using + /// @details If specified buffer is too short, it will be expanded using /// vector::resize() method. If the remaining length of the buffer /// is smaller than the specified length, an exception of class /// @c isc::OutOfRange will be thrown. - /// /// @param data Reference to a buffer (data will be stored there). /// @param len Size specified number of bytes to read in a vector. void readVector(std::vector& data, size_t len) { @@ -264,40 +202,32 @@ public: current_ += len; } -private: +private: // lgcrfctr /// @brief Base of the buffer. const uint8_t* base_; /// @brief Current poisition in the buffer. const uint8_t* current_; - /// @brief End of the buffer (address of the byte after). - const uint8_t* end_; -}; - + const uint8_t* end_;}; /// @brief Type of pointers to input buffer. typedef boost::shared_ptr InputBufferPtr; /// @brief The @c OutputBuffer class is a buffer abstraction for /// manipulating mutable data. -/// -/// The main purpose of this class is to provide a safe workplace for -/// constructing wire-format data to be sent out to a network. Here, -/// safe means that it automatically allocates necessary +/// @details The main purpose of this class is to provide a safe workplace for +/// constructing wire-format data to be sent out to a network. +/// Here, safe means that it automatically allocates necessary /// memory and avoid buffer overrun. -/// /// Like for the @c InputBuffer class, applications normally use this /// class only in a limited situation. One common usage of this class /// for an application would be something like this: -/// /// @code -/// OutputBuffer buffer(4096); // give a sufficiently large initial size -/// // pass the buffer to a DNS message object to construct a wire-format -/// // DNS message. -/// struct sockaddr to; -/// sendto(s, buffer.getDataAsVoidPtr(), buffer.getLength(), 0, &to, sizeof(to)); +/// OutputBuffer buffer(4096); // give a sufficiently large initial size +/// // Pass the buffer to a DNS message object to construct a wire-format DNS message. +/// struct sockaddr to_address; +/// sendto(s, buffer.getDataAsVoidPtr(), buffer.getLength(), 0, &to_address, sizeof(to_address)); /// @endcode -/// /// where the @c getData() (in fact @c getDataAsVoidPtr()) method gives /// a reference to the internal memory region stored in the @c buffer /// object. This is a suboptimal design in that it exposes an @@ -309,7 +239,6 @@ typedef boost::shared_ptr InputBufferPtr; /// such a special circumstance. It should also be noted that the /// memory region returned by @c getData() may be invalidated after a /// subsequent write operation. -/// /// An @c OutputBuffer class object automatically extends its memory /// region when data is written beyond the end of the current buffer. /// However, it will involve performance overhead such as reallocating @@ -318,7 +247,6 @@ typedef boost::shared_ptr InputBufferPtr; /// size. The @c getCapacity() method provides the current maximum /// size of data (including the portion already written) that can be /// written into the buffer without causing memory reallocation. -/// /// Methods for writing data into the buffer generally work like an /// output stream: it begins with the head of the buffer, and once /// some length of data is written into the buffer, the next write @@ -330,7 +258,6 @@ typedef boost::shared_ptr InputBufferPtr; /// writing multi-GB data, a separate exception (e.g., @c /// std::bad_alloc) may be thrown by the system. This also applies to /// the constructor with a very large initial size. -/// /// Note to developers: it may make more sense to introduce an /// abstract base class for the @c OutputBuffer and define the simple /// implementation as a concrete derived class. That way we can @@ -338,25 +265,23 @@ typedef boost::shared_ptr InputBufferPtr; /// buffer implementation or allowing users to have their own /// customized version without modifying the source code. We in fact /// considered that option, but at the moment chose the simpler -/// approach with a single concrete class because it may make the +/// approach with a single concrete class, because it may make the /// implementation unnecessarily complicated while we were still not /// certain if we really want that flexibility. We may revisit the /// class design as we see more applications of the class. The same /// considerations apply to the @c InputBuffer and @c MessageRenderer /// classes. -class OutputBuffer { -public: +class OutputBuffer { // lgcrfctr +public: // lgcrfctr /// @brief Constructor. - /// /// @param len The initial allocated length of the buffer in bytes. - OutputBuffer(size_t len) : buffer_() { + explicit OutputBuffer(size_t len) : buffer_() { if (len != 0) { buffer_.reserve(len); } } /// @brief Copy constructor. - /// /// @param other Source object from which to make a copy. OutputBuffer(const OutputBuffer& other) : buffer_(other.buffer_) { size_t len = other.buffer_.capacity(); @@ -367,11 +292,9 @@ public: /// @brief Destructor. ~OutputBuffer() = default; - /// @brief Assignment operator. - /// /// @param other Object to copy into "this". - OutputBuffer& operator =(const OutputBuffer& other) { + OutputBuffer& operator=(const OutputBuffer& other) { if (this != &other) { // Not self-assignment. buffer_ = other.buffer_; @@ -389,10 +312,8 @@ public: } /// @brief Return a pointer to the head of the data stored in the buffer. - /// - /// The caller can assume that the subsequent @c getLength() bytes + /// @details The caller can assume that the subsequent @c getLength() bytes /// are identical to the stored data of the buffer. - /// /// Note: The pointer returned by this method may be invalidated /// after a subsequent write operation. const uint8_t* getData() const { @@ -414,54 +335,39 @@ public: } /// @brief Return the value of the buffer at the specified position. - /// - /// @c pos must specify the valid position of the buffer; + /// @details @c pos must specify the valid position of the buffer; /// otherwise an exception class of @c isc::OutOfRange will /// be thrown. - /// - /// @param pos The position in the buffer to be returned. - uint8_t operator[](size_t pos) const { - if (pos >= buffer_.size()) { + /// @param position The position in the buffer to be returned. + uint8_t operator[](size_t position) const { + if (position >= buffer_.size()) { isc_throw(OutOfRange, - "OutputBuffer::[]: pos (" << pos - << ") >= size (" << buffer_.size() << ")"); - } - return (buffer_[pos]); - } + "OutputBuffer::[]: pos (" << position << ") >= size (" << buffer_.size() << ")");} + return (buffer_[position]);} /// @brief Return the buffer. - /// /// @note The main use is to avoid a copy. const std::vector& getVector() const { return (buffer_); } - /// @brief Insert a specified length of gap at the end of the buffer. - /// - /// The caller should not assume any particular value to be + /// @details The caller should not assume any particular value to be /// inserted. This method is provided as a shortcut to make a /// hole in the buffer that is to be filled in later, e.g, by /// @ref writeUint16At(). - /// /// @param len The length of the gap to be inserted in bytes. void skip(size_t len) { buffer_.resize(buffer_.size() + len); } - /// @brief Trim the specified length of data from the end of the buffer. - /// - /// The specified length must not exceed the current data size of + /// @details The specified length must not exceed the current data size of /// the buffer; otherwise an exception of class @c isc::OutOfRange /// will be thrown. - /// /// @param len The length of data that should be trimmed. void trim(size_t len) { if (len > buffer_.size()) { - isc_throw(OutOfRange, - "OutputBuffer::trim length too large from output buffer"); - } - buffer_.resize(buffer_.size() - len); - } + isc_throw(OutOfRange, "OutputBuffer::trim length too large from output buffer");} + buffer_.resize(buffer_.size() - len);} /// @brief Clear buffer content. void clear() { @@ -469,72 +375,53 @@ public: } /// @brief Write an unsigned 8-bit integer into the buffer. - /// /// @param data The 8-bit integer to be written into the buffer. void writeUint8(uint8_t data) { buffer_.push_back(data); } - /// @brief Write an unsigned 8-bit integer into the buffer. - /// - /// The position must be lower than the size of the buffer, + /// @details The position must be lower than the size of the buffer, /// otherwise an exception of class @c isc::OutOfRange will /// be thrown. - /// /// @param data The 8-bit integer to be written into the buffer. - /// @param pos The position in the buffer to write the data. - void writeUint8At(uint8_t data, size_t pos) { - if (pos + sizeof(data) > buffer_.size()) { - isc_throw(OutOfRange, - "OutputBuffer::writeUint8At write at invalid position"); - } - buffer_[pos] = data; - } - + /// @param position The position in the buffer to write the data. + void writeUint8At(uint8_t data, size_t position) { + if (position + sizeof(data) > buffer_.size()) { + isc_throw(OutOfRange, "OutputBuffer::writeUint8At write at invalid position");} + buffer_[position] = data;} /// @brief Write an unsigned 16-bit integer in host byte order /// into the buffer in network byte order. - /// /// @param data The 16-bit integer to be written into the buffer. void writeUint16(uint16_t data) { buffer_.push_back(static_cast((data & 0xff00U) >> 8)); - buffer_.push_back(static_cast(data & 0x00ffU)); - } + buffer_.push_back(static_cast(data & 0x00ffU));} /// @brief Write an unsigned 16-bit integer in host byte order at /// the specified position of the buffer in network byte order. - /// - /// The buffer must have a sufficient room to store the given data + /// @details The buffer must have a sufficient room to store the given data /// at the given position, that is, pos + 2 < /// getLength(); otherwise an exception of class /// @c isc::OutOfRange will be thrown. - /// Note also that this method never extends the buffer. - /// + /// Note also, that this method never extends the buffer. /// @param data The 16-bit integer to be written into the buffer. - /// @param pos The beginning position in the buffer to write the data. - void writeUint16At(uint16_t data, size_t pos) { - if (pos + sizeof(data) > buffer_.size()) { - isc_throw(OutOfRange, - "OutputBuffer::writeUint16At write at invalid position"); - } - - buffer_[pos] = static_cast((data & 0xff00U) >> 8); - buffer_[pos + 1] = static_cast(data & 0x00ffU); - } - - /// @brief Write an unsigned 32-bit integer in host byte order - /// into the buffer in network byte order. - /// + /// @param position The beginning position in the buffer to write the data. + void writeUint16At(uint16_t data, size_t position) { + if (position + sizeof(data) > buffer_.size()) { + isc_throw(OutOfRange, "OutputBuffer::writeUint16At write at invalid position");} + buffer_[position] = static_cast((data & 0xff00U) >> 8); + buffer_[position + 1] = static_cast(data & 0x00ffU);} + + /// @brief Write an unsigned 32-bit integer in host byte order into the buffer + /// in network byte order. /// @param data The 32-bit integer to be written into the buffer. void writeUint32(uint32_t data) { buffer_.push_back(static_cast((data & 0xff000000) >> 24)); buffer_.push_back(static_cast((data & 0x00ff0000) >> 16)); buffer_.push_back(static_cast((data & 0x0000ff00) >> 8)); - buffer_.push_back(static_cast(data & 0x000000ff)); - } + buffer_.push_back(static_cast(data & 0x000000ff));} /// @brief Write an unsigned 64-bit integer in host byte order /// into the buffer in network byte order. - /// /// @param data The 64-bit integer to be written into the buffer. void writeUint64(uint64_t data) { buffer_.push_back(static_cast((data & 0xff00000000000000) >> 56)); @@ -544,33 +431,23 @@ public: buffer_.push_back(static_cast((data & 0x00000000ff000000) >> 24)); buffer_.push_back(static_cast((data & 0x0000000000ff0000) >> 16)); buffer_.push_back(static_cast((data & 0x000000000000ff00) >> 8)); - buffer_.push_back(static_cast(data & 0x00000000000000ff)); + buffer_.push_back(static_cast(data & 0x00000000000000ff)); } /// @brief Copy an arbitrary length of data into the buffer. - /// - /// No conversion on the copied data is performed. - /// + /// @details No conversion on the copied data is performed. /// @param data A pointer to the data to be copied into the buffer. /// @param len The length of the data in bytes. - void writeData(const void *data, size_t len) { + void writeData(const void* data, size_t len) { if (len == 0) { return; } - const uint8_t* ptr = static_cast(data); - buffer_.insert(buffer_.end(), ptr, ptr + len); - } - -private: + buffer_.insert(buffer_.end(), ptr, ptr + len);} +private: // lgcrfctr /// The actual data. - std::vector buffer_; -}; - + std::vector buffer_;}; /// @brief Type of pointers to output buffers. -typedef boost::shared_ptr OutputBufferPtr; - -} // end of namespace util -} // end of namespace isc - -#endif // BUFFER_H +typedef boost::shared_ptr OutputBufferPtr; // lgcrfctr +} // namespace isc::util +#endif // BUFFER_H diff --git a/src/lib/util/str.h b/src/lib/util/str.h index 1e5d4c405f..8897468f03 100644 --- a/src/lib/util/str.h +++ b/src/lib/util/str.h @@ -1,30 +1,22 @@ // Copyright (C) 2011-2024 Internet Systems Consortium, Inc. ("ISC") -// // This Source Code Form is subject to the terms of the Mozilla Public // License, v. 2.0. If a copy of the MPL was not distributed with this // file, You can obtain one at http://mozilla.org/MPL/2.0/. - #ifndef KEA_UTIL_STR_H #define KEA_UTIL_STR_H #include - -#include +#include #include #include +#include #include #include #include -#include #include - -namespace isc { -namespace util { -namespace str { - +namespace isc::util::str { /// @brief A Set of C++ Utilities for Manipulating Strings - /// /// @brief A standard string util exception that is thrown if getToken or /// numToToken are called with bad input data @@ -36,16 +28,12 @@ public: }; /// @brief Trim leading and trailing spaces. -/// -/// Returns a copy of the input string but with any leading or trailing spaces -/// or tabs removed. -/// +/// @details Returns a copy of the input string but with any leading +/// or trailing spaces or tabs removed. /// @param input Input string to modify. -/// /// @return String with leading and trailing spaces removed. std::string trim(const std::string& input); - /// @brief Finds the "trimmed" end of a buffer /// /// Works backward from the end of the buffer, looking for the first @@ -68,71 +56,55 @@ seekTrimmed(Iterator const& begin, Iterator end, uint8_t const trim_val) { } return (end); } - /// @brief Split string into tokens. -/// -/// Splits a string into tokens (the tokens being delimited by one or more of +/// @details Splits a string into tokens (the tokens being delimited by one or more of /// the delimiter characters) and returns the tokens in a vector. /// Adjacent delimiters are considered to be a single delimiter. -/// -/// Special cases are: -/// -# The empty string is considered to be zero tokens. -/// -# A string comprising nothing but delimiters is considered to be zero -/// tokens. -/// -/// The reasoning behind this is that the string can be thought of as having -/// invisible leading and trailing delimiter characters. Therefore both cases -/// reduce to a set of contiguous delimiters, which are considered a single -/// delimiter (so getting rid of the string). -/// Optional escape allows to escape delimiter characters (and *only* them -/// and the escape character itself) using backslash. -/// -/// We could use Boost for this, but this (simple) function eliminates one -/// dependency in the code. -/// -/// @param text String to be split. Passed by value as the internal copy is -/// altered during the processing. +/// Special use cases are: +/// 1. The empty string is considered to be zero tokens. +/// 2. A string comprising nothing but delimiters +/// is considered to be zero tokens. + +/// The reasoning behind this is that the string can be thought of +/// as having invisible leading and trailing delimiter characters. +/// Therefore both cases reduce to a set of contiguous delimiters, +/// which are considered a single delimiter (so getting rid of the +/// string). Optional escape allows to escape delimiter characters +/// (and *only* them and the escape character itself) using backslash. +/// We could use Boost for this, but this (simple) function eliminates +/// one dependency in the code. + +/// @param text String to be split. Passed by value as the internal +/// copy is altered during the processing. /// @param delim Delimiter characters /// @param escape Use backslash to escape delimiter characters -/// + /// @return Vector of tokens. std::vector tokens(const std::string& text, const std::string& delim = " \t\n", bool escape = false); - /// @brief Convert character to uppercase. -/// -/// Used in uppercase() to pass as a parameter to std::transform(). The -/// function std::toupper() can't be used as it takes an "int" as its parameter; -/// this confuses the template expansion mechanism because dereferencing a -/// string::iterator returns a char. -/// +/// @details Used in uppercase() to pass as a parameter to std::transform(). +/// The function std::toupper() can't be used as it takes an "int" as its +/// parameter; this confuses the template expansion mechanism because +/// dereferencing a string::iterator returns a char. /// @param chr Character to be upper-cased. -/// /// @return Uppercase version of the input character. char toUpper(char const chr); - /// @brief Convert string to uppercase. -/// /// @param text String to be upper-cased. void uppercase(std::string& text); - /// @brief Convert character to lowercase. -/// -/// Used in lowercase() to pass as a parameter to std::transform(). The -/// function std::tolower() can't be used as it takes an "int" as its parameter; -/// this confuses the template expansion mechanism because dereferencing a -/// string::iterator returns a char. -/// +/// @details Used in lowercase() to pass as a parameter to std::transform(). +/// The function std::tolower() can't be used as it takes an "int" as its +/// parameter; this confuses the template expansion mechanism because +/// dereferencing a string::iterator returns a char. /// @param chr Character to be lower-cased. -/// /// @return Lowercase version of the input character. char toLower(char const chr); - /// @brief Convert string to lowercase. -/// /// @param text String to be lower-cased. void lowercase(std::string& text); @@ -285,8 +257,5 @@ isPrintable(const std::vector& content); std::string dumpAsHex(const uint8_t* data, size_t length); -} // namespace str -} // namespace util -} // namespace isc - +} // namespace isc::util::str #endif // KEA_UTIL_STR_H