// 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 <exceptions/exceptions.h>
-
-#include <boost/shared_ptr.hpp>
-
+#include <cstdint>
+#include <cstdlib>
#include <cstring>
-#include <stdint.h>
-#include <stdlib.h>
+#include <vector>
#include <vector>
-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 <boost/shared_ptr.hpp>
+#include <exceptions/exceptions.h>
+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
/// 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
/// "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
/// this class internally holds (a notion of) where the next read
/// operation should start. We call it the <em>current pointer</em>
/// 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.
: base_(static_cast<const uint8_t*>(data)), current_(base_),
end_(base_ + len) {
}
-
/// @brief Return the length of the data stored in the buffer.
size_t getLength() const {
return (static_cast<size_t>(end_ - base_));
size_t getPosition() const {
return (static_cast<size_t>(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) {
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<uint16_t>(current_[0])) << 8;
ret |= (static_cast<uint16_t>(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<uint32_t>(current_[0])) << 24;
ret |= (static_cast<uint32_t>(current_[1])) << 16;
ret |= (static_cast<uint32_t>(current_[2])) << 8;
ret |= (static_cast<uint32_t>(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<void>(std::memmove(data, current_, len));
- }
+ isc_throw(OutOfRange, "InputBuffer::peekData read beyond end of buffer");}
+ static_cast<void>(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.
}
/// @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<uint8_t>& 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<uint8_t>& data, size_t len) {
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<InputBuffer> 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,
-/// <em>safe</em> 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, <em>safe</em> 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
/// 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
/// 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
/// 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
/// 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();
/// @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_;
}
/// @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 {
}
/// @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<uint8_t>& 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() {
}
/// @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<uint8_t>((data & 0xff00U) >> 8));
- buffer_.push_back(static_cast<uint8_t>(data & 0x00ffU));
- }
+ buffer_.push_back(static_cast<uint8_t>(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, <code>pos + 2 <
/// getLength()</code>; 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<uint8_t>((data & 0xff00U) >> 8);
- buffer_[pos + 1] = static_cast<uint8_t>(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<uint8_t>((data & 0xff00U) >> 8);
+ buffer_[position + 1] = static_cast<uint8_t>(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<uint8_t>((data & 0xff000000) >> 24));
buffer_.push_back(static_cast<uint8_t>((data & 0x00ff0000) >> 16));
buffer_.push_back(static_cast<uint8_t>((data & 0x0000ff00) >> 8));
- buffer_.push_back(static_cast<uint8_t>(data & 0x000000ff));
- }
+ buffer_.push_back(static_cast<uint8_t>(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<uint8_t>((data & 0xff00000000000000) >> 56));
buffer_.push_back(static_cast<uint8_t>((data & 0x00000000ff000000) >> 24));
buffer_.push_back(static_cast<uint8_t>((data & 0x0000000000ff0000) >> 16));
buffer_.push_back(static_cast<uint8_t>((data & 0x000000000000ff00) >> 8));
- buffer_.push_back(static_cast<uint8_t>(data & 0x00000000000000ff));
+ buffer_.push_back(static_cast<uint8_t>(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<const uint8_t*>(data);
- buffer_.insert(buffer_.end(), ptr, ptr + len);
- }
-
-private:
+ buffer_.insert(buffer_.end(), ptr, ptr + len);}
+private: // lgcrfctr
/// The actual data.
- std::vector<uint8_t> buffer_;
-};
-
+ std::vector<uint8_t> buffer_;};
/// @brief Type of pointers to output buffers.
-typedef boost::shared_ptr<OutputBuffer> OutputBufferPtr;
-
-} // end of namespace util
-} // end of namespace isc
-
-#endif // BUFFER_H
+typedef boost::shared_ptr<OutputBuffer> OutputBufferPtr; // lgcrfctr
+} // namespace isc::util
+#endif // BUFFER_H
// 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 <exceptions/exceptions.h>
-
-#include <algorithm>
+#include <vector>
#include <cstddef>
#include <cstdint>
+#include <algorithm>
#include <memory>
#include <sstream>
#include <string>
-#include <vector>
#include <boost/lexical_cast.hpp>
-
-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
};
/// @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
}
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<std::string>
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);
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
projects / thirdparty / kea.git / commitdiff
