Kea  2.3.3-git
isc::util::str Namespace Reference

Classes

class  StringSanitizer
 Implements a regular expression based string scrubber. More...
 
class  StringSanitizerImpl
 
class  StringTokenError
 A Set of C++ Utilities for Manipulating Strings. More...
 

Typedefs

typedef boost::shared_ptr< StringSanitizerImplStringSanitizerImplPtr
 Type representing the pointer to the StringSanitizerImpl. More...
 
typedef boost::shared_ptr< StringSanitizerStringSanitizerPtr
 Type representing the pointer to the StringSanitizer. More...
 

Functions

void decodeColonSeparatedHexString (const std::string &hex_string, std::vector< uint8_t > &binary)
 Converts a string of hexadecimal digits with colons into a vector. More...
 
void decodeFormattedHexString (const std::string &hex_string, std::vector< uint8_t > &binary)
 Converts a formatted string of hexadecimal digits into a vector. More...
 
void decodeSeparatedHexString (const std::string &hex_string, const std::string &sep, std::vector< uint8_t > &binary)
 Converts a string of separated hexadecimal digits into a vector. More...
 
std::string dumpAsHex (const uint8_t *data, size_t length)
 Dumps a buffer of bytes as a string of hexadecimal digits. More...
 
std::string format (const std::string &format, const std::vector< std::string > &args)
 Apply Formatting. More...
 
std::string getToken (std::istringstream &iss)
 Returns one token from the given stringstream. More...
 
bool isPrintable (const std::string &content)
 Check if a string is printable. More...
 
bool isPrintable (const std::vector< uint8_t > &content)
 Check if a byte vector is printable. More...
 
void lowercase (std::string &text)
 Lowercase String. More...
 
void normalizeSlash (std::string &name)
 Normalize Backslash. More...
 
std::vector< uint8_t > quotedStringToBinary (const std::string &quoted_string)
 Converts a string in quotes into vector. More...
 
template<typename Iterator >
Iterator seekTrimmed (Iterator begin, Iterator end, uint8_t trim_val)
 Finds the "trimmed" end of a buffer. More...
 
vector< string > tokens (const std::string &text, const std::string &delim=std::string(" \\"), bool escape=false)
 Split String into Tokens. More...
 
template<typename NumType , int BitSize>
NumType tokenToNum (const std::string &num_token)
 Converts a string token to an unsigned integer. More...
 
char toLower (char chr)
 Lowercase Character. More...
 
char toUpper (char chr)
 Uppercase Character. More...
 
string trim (const std::string &instring)
 Trim Leading and Trailing Spaces. More...
 
void uppercase (std::string &text)
 Uppercase String. More...
 

Typedef Documentation

◆ StringSanitizerImplPtr

Type representing the pointer to the StringSanitizerImpl.

Definition at line 300 of file strutil.h.

◆ StringSanitizerPtr

Type representing the pointer to the StringSanitizer.

Definition at line 359 of file strutil.h.

Function Documentation

◆ decodeColonSeparatedHexString()

void isc::util::str::decodeColonSeparatedHexString ( const std::string &  hex_string,
std::vector< uint8_t > &  binary 
)

Converts a string of hexadecimal digits with colons into a vector.

Convenience method which calls decodeSeparatedHexString() passing in a colon for the separator.

Parameters
hex_stringInput string.
binaryVector receiving converted string into binary.
Exceptions
isc::BadValueif the format of the input string is invalid.

Definition at line 215 of file strutil.cc.

References decodeSeparatedHexString().

Referenced by isc::dhcp::HWAddr::fromText(), and tokenToNum().

+ Here is the call graph for this function:

◆ decodeFormattedHexString()

void isc::util::str::decodeFormattedHexString ( const std::string &  hex_string,
std::vector< uint8_t > &  binary 
)

Converts a formatted string of hexadecimal digits into a vector.

This function supports the following formats:

  • yy:yy:yy:yy or yy yy yy yy - octets delimited by colons or spaces, see decodeSeparatedHexString
  • yyyyyyyyyy
  • 0xyyyyyyyyyy

If there is an odd number of hexadecimal digits in the input string, the '0' is prepended to the string before decoding.

Parameters
hex_stringInput string.
binaryVector receiving converted string into binary.
Exceptions
isc::BadValueif the format of the input string is invalid.

Definition at line 273 of file strutil.cc.

References isc::util::encode::decodeHex(), decodeSeparatedHexString(), and isc_throw.

Referenced by isc::dhcp::OptionDataParser::createOption(), isc::dhcp::DUID::fromText(), isc::dhcp::ClientId::fromText(), isc::dhcp::Host::setIdentifier(), tokenToNum(), isc::dhcp::LeaseMgr::upgradeLease4ExtendedInfo(), and isc::dhcp::LeaseMgr::upgradeLease6ExtendedInfo().

+ Here is the call graph for this function:

◆ decodeSeparatedHexString()

void isc::util::str::decodeSeparatedHexString ( const std::string &  hex_string,
const std::string &  sep,
std::vector< uint8_t > &  binary 
)

Converts a string of separated hexadecimal digits into a vector.

Octets may contain 1 or 2 digits. For example, using a colon for a separator all of the following are valid:

  • yy:yy:yy:yy:yy
  • y:y:y:y:y
  • y:yy:yy:y:y

If the decoded string doesn't match any of the supported formats, an exception is thrown.

Parameters
hex_stringInput string.
sepcharacter to use as a separator.
binaryVector receiving converted string into binary.
Exceptions
isc::BadValueif the format of the input string is invalid.

Definition at line 221 of file strutil.cc.

References isc_throw.

Referenced by decodeColonSeparatedHexString(), decodeFormattedHexString(), and tokenToNum().

◆ dumpAsHex()

std::string isc::util::str::dumpAsHex ( const uint8_t *  data,
size_t  length 
)

Dumps a buffer of bytes as a string of hexadecimal digits.

Parameters
datapointer to the data to dump
lengthnumber of bytes to dump. Caller should ensure the length does not exceed the buffer.

Definition at line 451 of file strutil.cc.

Referenced by isPrintable(), and isc::tcp::TcpStreamRequest::logFormatRequest().

◆ format()

std::string isc::util::str::format ( const std::string &  format,
const std::vector< std::string > &  args 
)

Apply Formatting.

Given a printf-style format string containing only "%s" place holders (others are ignored) and a vector of strings, this produces a single string with the placeholders replaced.

Parameters
formatFormat string
argsVector of argument strings
Returns
Resultant string

Definition at line 157 of file strutil.cc.

Referenced by isc::db::PsqlBindArray::add(), isc::db::PgSqlExchange::dumpRow(), isc::http::HttpDateTime::fromAny(), isc::http::HttpDateTime::getPtime(), and lowercase().

◆ getToken()

std::string isc::util::str::getToken ( std::istringstream &  iss)

Returns one token from the given stringstream.

Using the >> operator, with basic error checking

Exceptions
StringTokenErrorif the token cannot be read from the stream
Parameters
issstringstream to read one token from
Returns
the first token read from the stringstream

Definition at line 186 of file strutil.cc.

References isc_throw.

Referenced by lowercase().

◆ isPrintable() [1/2]

bool isc::util::str::isPrintable ( const std::string &  content)
inline

Check if a string is printable.

Parameters
contentString to check for printable characters
Returns
True if empty or contains only printable characters, False otherwise

Definition at line 367 of file strutil.h.

Referenced by isc::flex_option::FlexOptionImpl::logAction(), and isc::flex_option::FlexOptionImpl::logSubAction().

◆ isPrintable() [2/2]

bool isc::util::str::isPrintable ( const std::vector< uint8_t > &  content)
inline

Check if a byte vector is printable.

Parameters
contentVector to check for printable characters
Returns
True if empty or contains only printable characters, False otherwise

Definition at line 382 of file strutil.h.

References dumpAsHex().

+ Here is the call graph for this function:

◆ lowercase()

void isc::util::str::lowercase ( std::string &  text)
inline

Lowercase String.

A convenience function to lowercase a string

Parameters
textString to be lower-cased.

Definition at line 152 of file strutil.h.

References format(), getToken(), and toLower().

Referenced by isc::http::BasicHttpAuthConfig::checkAuth(), isc::http::HttpHeader::getLowerCaseName(), isc::http::HttpHeader::getLowerCaseValue(), and isc::http::HttpHeader::isValueEqual().

+ Here is the call graph for this function:

◆ normalizeSlash()

void isc::util::str::normalizeSlash ( std::string &  name)

Normalize Backslash.

Only relevant to Windows, this replaces all "\" in a string with "/" and returns the result. On other systems it is a no-op. Note that Windows does recognize file names with the "\" replaced by "/" (at least in system calls, if not the command line).

Parameters
nameName to be substituted

Definition at line 41 of file strutil.cc.

Referenced by isc::util::Filename::expandWithDefault(), isc::util::Filename::setName(), isc::util::str::StringTokenError::StringTokenError(), and isc::util::Filename::useAsDefault().

◆ quotedStringToBinary()

std::vector< uint8_t > isc::util::str::quotedStringToBinary ( const std::string &  quoted_string)

Converts a string in quotes into vector.

A converted string is first trimmed. If a trimmed string is in quotes, the quotes are removed and the resulting string is copied into a vector. If the string is not in quotes, an empty vector is returned.

The resulting string is copied to a vector and returned.

This function is intended to be used by the server configuration parsers to convert string values surrounded with quotes into binary form.

Parameters
quoted_stringString to be converted.
Returns
Vector containing converted string or empty string if input string didn't contain expected quote characters.

Definition at line 196 of file strutil.cc.

References trim().

Referenced by isc::dhcp::OptionDataParser::createOption(), isc::yang::AdaptorHost::quoteIdentifier(), isc::dhcp::Host::setIdentifier(), and tokenToNum().

+ Here is the call graph for this function:

◆ seekTrimmed()

template<typename Iterator >
Iterator isc::util::str::seekTrimmed ( Iterator  begin,
Iterator  end,
uint8_t  trim_val 
)

Finds the "trimmed" end of a buffer.

Works backward from the end of the buffer, looking for the first character not equal to the trim value, and returns an iterator pointing that that position.

Parameters
begin- Forward iterator pointing to the beginning of the buffer to trim
end- Forward iterator pointing to the untrimmed end of the buffer to trim
trim_val- byte value to trim off
Returns
Iterator pointing the first character from the end of the buffer not equal to the trim value

Definition at line 73 of file strutil.h.

References tokens().

Referenced by isc::dhcp::OptionDataTypeUtil::readString(), isc::dhcp::OptionString::setValue(), and isc::dhcp::OptionString::unpack().

+ Here is the call graph for this function:

◆ tokens()

std::vector< std::string > isc::util::str::tokens ( const std::string &  text,
const std::string &  delim = std::string(" \\"),
bool  escape = false 
)

Split String into Tokens.

Splits a string into tokens (the tokens being delimited by one or more of the delimiter characters) and returns the tokens in a vector array. Note that adjacent delimiters are considered to be a single delimiter.

Special 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.

Parameters
textString to be split. Passed by value as the internal copy is altered during the processing.
delimDelimiter characters
escapeUse backslash to escape delimiter characters
Returns
Vector of tokens.

Definition at line 77 of file strutil.cc.

Referenced by isc::dhcp::OptionDataParser::createOption(), isc::log::MessageReader::getNotAdded(), isc::db::DatabaseConnection::parse(), isc::dhcp::OptionDefParser::parse(), isc::flex_option::FlexOptionImpl::process(), isc::log::MessageReader::processLine(), seekTrimmed(), and splitNamespace().

◆ tokenToNum()

template<typename NumType , int BitSize>
NumType isc::util::str::tokenToNum ( const std::string &  num_token)

Converts a string token to an unsigned integer.

The value is converted using a lexical cast, with error and bounds checking.

NumType is a signed integral type (e.g. int32_t) that is sufficiently wide to store resulting integers.

BitSize is the maximum number of bits that the resulting integer can take. This function first checks whether the given token can be converted to an integer of NumType type. It then confirms the conversion result is within the valid range, i.e., [0, 2^BitSize - 1]. The second check is necessary because lexical_cast<T> where T is an unsigned integer type doesn't correctly reject negative numbers when compiled with SunStudio.

Exceptions
StringTokenErrorif the value is out of range, or if it could not be converted
Parameters
num_tokenthe string token to convert
Returns
the converted value, of type NumType

Definition at line 205 of file strutil.h.

References decodeColonSeparatedHexString(), decodeFormattedHexString(), decodeSeparatedHexString(), isc_throw, and quotedStringToBinary().

+ Here is the call graph for this function:

◆ toLower()

char isc::util::str::toLower ( char  chr)
inline

Lowercase Character.

Used in lowercase() to pass as an argument to std::transform(). The function std::tolower() can't be used as it takes an "int" as its argument; this confuses the template expansion mechanism because dereferencing a string::iterator returns a char.

Parameters
chrCharacter to be lower-cased.
Returns
Lowercase version of the argument

Definition at line 143 of file strutil.h.

Referenced by lowercase().

◆ toUpper()

char isc::util::str::toUpper ( char  chr)
inline

Uppercase Character.

Used in uppercase() to pass as an argument to std::transform(). The function std::toupper() can't be used as it takes an "int" as its argument; this confuses the template expansion mechanism because dereferencing a string::iterator returns a char.

Parameters
chrCharacter to be upper-cased.
Returns
Uppercase version of the argument

Definition at line 119 of file strutil.h.

Referenced by uppercase().

◆ trim()

◆ uppercase()

void isc::util::str::uppercase ( std::string &  text)
inline

Uppercase String.

A convenience function to uppercase a string.

Parameters
textString to be upper-cased.

Definition at line 128 of file strutil.h.

References toUpper().

Referenced by isc::log::MessageReader::processLine(), and sentinel().

+ Here is the call graph for this function: