Foam::stringOps Namespace Reference

Collection of static functions for various string-related operations. More...

Classes

struct  natural_sort
 Encapsulation of natural order sorting for algorithms. More...
 

Functions

std::string::size_type count (const std::string &s, const char c)
 Count the number of occurrences of the specified character. More...
 
std::string::size_type count (const char *s, const char c)
 Count the number of occurrences of the specified character. More...
 
bool match (const UList< wordRe > &patterns, const std::string &text)
 Return true if text matches one of the regular expressions. More...
 
template<class StringType , class UnaryPredicate >
StringType quotemeta (const StringType &str, const UnaryPredicate &meta, const char quote='\\')
 Quote any meta-characters in given string. More...
 
string expand (const std::string &s, const HashTable< string > &mapping, const char sigil='$')
 
void inplaceExpand (std::string &s, const HashTable< string > &mapping, const char sigil='$')
 
void inplaceExpand (std::string &s, const dictionary &dict, const bool allowEnv, const bool allowEmpty, const bool allowSubDict=false, const char sigil='$')
 
string expand (const std::string &s, const dictionary &dict, const char sigil='$')
 Expand occurrences of dictionary or environment variables. More...
 
void inplaceExpand (std::string &s, const dictionary &dict, const char sigil='$')
 Inplace expand occurrences of dictionary or environment variables. More...
 
string expand (const std::string &s, const bool allowEmpty=false)
 
void inplaceExpand (std::string &s, const bool allowEmpty=false)
 
bool inplaceReplaceVar (std::string &s, const word &varName)
 Replace environment variable contents with its name. More...
 
template<class StringType , class UnaryPredicate >
StringType validate (const std::string &str, const UnaryPredicate &accept, const bool invert=false)
 Return a copy of the input string with validated characters. More...
 
std::pair< size_t, size_t > findTrim (const std::string &s, size_t pos=0, size_t len=std::string::npos)
 Find (first, last) non-space locations in string or sub-string. More...
 
string trimLeft (const std::string &s)
 Return string trimmed of leading whitespace. More...
 
void inplaceTrimLeft (std::string &s)
 Trim leading whitespace inplace. More...
 
string trimRight (const std::string &s)
 Return string trimmed of trailing whitespace. More...
 
void inplaceTrimRight (std::string &s)
 Trim trailing whitespace inplace. More...
 
string trim (const std::string &s)
 Return string trimmed of leading and trailing whitespace. More...
 
void inplaceTrim (std::string &s)
 Trim leading and trailing whitespace inplace. More...
 
void inplaceRemoveSpace (std::string &s)
 Eliminate whitespace inplace. More...
 
string removeComments (const std::string &s)
 Return string with C/C++ comments removed. More...
 
void inplaceRemoveComments (std::string &s)
 Remove C/C++ comments inplace. More...
 
string lower (const std::string &s)
 Return string copy transformed with std::tolower on each character. More...
 
void inplaceLower (std::string &s)
 Inplace transform string with std::tolower on each character. More...
 
string upper (const std::string &s)
 Return string copy transformed with std::toupper on each character. More...
 
void inplaceUpper (std::string &s)
 Inplace transform string with std::toupper on each character. More...
 
label splitFunctionArgs (const std::string &str, wordRes &args, List< Tuple2< word, string > > &namedArgs)
 Split out arguments (named or unnamed) from an input string. More...
 
template<class StringType >
Foam::SubStrings< StringType > split (const StringType &str, const char delim, const bool keepEmpty=false)
 Split string into sub-strings at the delimiter character. More...
 
template<class StringType >
Foam::SubStrings< StringType > split (const StringType &str, const std::string &delim, const bool keepEmpty=false)
 Split string into sub-strings using delimiter string. More...
 
template<class StringType >
Foam::SubStrings< StringType > splitAny (const StringType &str, const std::string &delim)
 Split string into sub-strings using any characters in delimiter. More...
 
template<class StringType >
Foam::SubStrings< StringType > splitFixed (const StringType &str, const std::string::size_type width, const std::string::size_type start=0)
 Split string into sub-strings using a fixed field width. More...
 
template<class StringType >
Foam::SubStrings< StringType > splitSpace (const StringType &str)
 Split string into sub-strings at whitespace (TAB, NL, VT, FF, CR, SPC) More...
 
void writeWrapped (OSstream &os, const std::string &str, const std::string::size_type width, const std::string::size_type indent=0, const bool escape=false)
 Output string with text wrapping. More...
 
string evaluate (label fieldWidth, const std::string &s, size_t pos=0, size_t len=std::string::npos)
 String evaluation with specified (positive, non-zero) field width. More...
 
string evaluate (const std::string &s, size_t pos=0, size_t len=std::string::npos)
 
int natstrcmp (const char *s1, const char *s2)
 'Natural' compare for C-strings More...
 

Detailed Description

Collection of static functions for various string-related operations.

Source files

Function Documentation

◆ count() [1/2]

std::string::size_type count ( const std::string &  s,
const char  c 
)

Count the number of occurrences of the specified character.

Definition at line 696 of file stringOps.C.

References s().

Referenced by string::count(), ensightSurfaceReader::replaceMask(), OSstream::write(), and OSstream::writeQuoted().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ count() [2/2]

std::string::size_type count ( const char *  s,
const char  c 
)

Count the number of occurrences of the specified character.

Correctly handles nullptr.

Definition at line 706 of file stringOps.C.

References s().

Here is the call graph for this function:

◆ match()

bool match ( const UList< wordRe > &  patterns,
const std::string &  text 
)
inline

Return true if text matches one of the regular expressions.

Definition at line 76 of file stringOps.H.

Referenced by functionObjectList::execute().

Here is the caller graph for this function:

◆ quotemeta()

StringType quotemeta ( const StringType &  str,
const UnaryPredicate &  meta,
const char  quote = '\\' 
)

Quote any meta-characters in given string.

Definition at line 31 of file stringOpsTemplates.C.

Referenced by ddt2::read().

Here is the caller graph for this function:

◆ expand() [1/3]

Foam::string expand ( const std::string &  s,
const HashTable< string > &  mapping,
const char  sigil = '$' 
)

Expand occurrences of variables according to the mapping and return the expanded string.

See also
stringOps::inplaceExpand() for details

Definition at line 717 of file stringOps.C.

References inplaceExpand(), and s().

Referenced by dynamicCode::copyOrCreateFiles(), argList::displayDoc(), and functionObjectList::findDict().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ inplaceExpand() [1/4]

void inplaceExpand ( std::string &  s,
const HashTable< string > &  mapping,
const char  sigil = '$' 
)

Inplace expand occurrences of variables according to the mapping. Does not use environment values.

Expansion includes:

  1. Variables
    • $VAR
    • ${VAR}
  2. Default and alternative values as per the POSIX shell:
    • ${parameter:-defValue} If parameter is unset or null, the defValue is substituted. Otherwise, the value of parameter is substituted.
    • ${parameter:+altValue} If parameter is unset or null, nothing is substituted. Otherwise the altValue is substituted.

General behaviour:

  • Unknown entries are removed silently.
  • Malformed entries (eg, brace mismatch, sigil followed by unknown characters) are left as is.
Parameters
[in,out]sThe string to modify inplace.
mappingThe lookup table
sigilThe leading sigil. Can be changed to avoid conflict with other string expansions. (default: '$')
Expansion behaviour
  • alternatives = True
  • environment = False
  • allow empty = True
  • subDict = Not applicable
Note
Currently only used by Foam::dynamicCode.

Definition at line 730 of file stringOps.C.

References HashTable< T, Key, Hash >::cfind(), findParameterAlternative(), and s().

Referenced by dynamicCode::copyAndFilter(), string::expand(), expand(), expressionEntry::inplaceExpand(), dynamicCodeContext::inplaceExpand(), entry::New(), includeEtcEntry::resolveEtcFile(), and includeEntry::resolveFile().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ inplaceExpand() [2/4]

void inplaceExpand ( std::string &  s,
const dictionary dict,
const bool  allowEnv,
const bool  allowEmpty,
const bool  allowSubDict = false,
const char  sigil = '$' 
)

Inplace expand occurrences of variables according to the dictionary and (optionally) environment variables.

Expansion includes:

  1. Dictionary variables and (optionally) environment variables
    • $VAR
    • ${VAR}
    • ${VAR:-defValue}
    • ${VAR:+altValue}
  2. Mathematical evaluation using stringOps::evaluate
    • ${{EXPR}}
  3. Current directory
  4. Leading tag expansion for commonly used directories
    • <etc>/ : user/group/other OpenFOAM etc directory
    • <etc:[ugoa]+)>/ : user/group/other etc with specified location mode
    • <case>/ : The $FOAM_CASE directory
    • <constant>/ : The $FOAM_CASE/constant directory
    • <system>/ : The $FOAM_CASE/system directory
  5. Tilde expansion
    • leading "~/" : home directory
    • leading "~user" : home directory for specified user
  6. Default and alternative values as per the POSIX shell:
    • ${parameter:-defValue} If parameter is unset or null, the defValue is substituted. Otherwise, the value of parameter is substituted.
    • ${parameter:+altValue} If parameter is unset or null, nothing is substituted. Otherwise the altValue is substituted.

General behaviour:

  • Malformed entries (eg, brace mismatch, sigil followed by unknown characters) are left as is.
  • Supports recursive variable expansions. For example, "${var${num}}" and "${{100 + ${var}}}"
Parameters
[in,out]sThe string to modify inplace
dictThe dictionary context for the expansion
allowEnvAllow use of environment values as fallback
allowEmptyAllow empty expansions, or treat as Fatal
allowSubDictAllow expansion of subDict entries as well as primitive entries (default: false)
sigilThe leading sigil. Can be changed to avoid conflict with other string expansions. (default: '$')
See also
Foam::findEtcEntry(), Foam::findEtcEntries(), stringOps::evaluate()
Expansion behaviour
  • alternatives = True
  • environment = Given by parameter
  • allow empty = Given by parameter
  • subDict = Given by parameter (default: False)
Note
This function has too many parameters and should generally be avoided in user coding.

Definition at line 855 of file stringOps.C.

References dict, Foam::expandString(), and s().

Here is the call graph for this function:

◆ expand() [2/3]

Foam::string expand ( const std::string &  s,
const dictionary dict,
const char  sigil = '$' 
)

Expand occurrences of dictionary or environment variables.

Empty expansions are allowed. Serialization of subDict entries is permitted.

See also
stringOps::inplaceExpand(std::string&, const dictionary&, char)

Definition at line 842 of file stringOps.C.

References dict, inplaceExpand(), and s().

Here is the call graph for this function:

◆ inplaceExpand() [3/4]

void inplaceExpand ( std::string &  s,
const dictionary dict,
const char  sigil = '$' 
)

Inplace expand occurrences of dictionary or environment variables.

Empty expansions are allowed. Serialization of subDict entries is permitted.

See also
stringOps::inplaceExpand (std::string&, const dictionary&, bool, bool, bool, char)
Expansion behaviour
  • alternatives = True
  • environment = True
  • allow empty = True
  • subDict = True

Definition at line 869 of file stringOps.C.

References dict, Foam::expandString(), and s().

Here is the call graph for this function:

◆ expand() [3/3]

Foam::string expand ( const std::string &  s,
const bool  allowEmpty = false 
)

Expand initial tags, tildes, and all occurrences of environment variables.

See also
stringOps::inplaceExpand(std::string&, bool);

Definition at line 882 of file stringOps.C.

References inplaceExpand(), and s().

Here is the call graph for this function:

◆ inplaceExpand() [4/4]

void inplaceExpand ( std::string &  s,
const bool  allowEmpty = false 
)

Expand initial tags, tildes, and all occurrences of environment variables

The expansion behaviour is identical to stringOps::inplaceExpand (std::string&, const dictionary&, bool, bool, bool, char) except that there is no dictionary and the environment variables are always enabled.

Expansion behaviour
  • alternatives = True
  • environment = True
  • allow empty = Given by parameter (default: False)
  • subDict = Not applicable

Definition at line 894 of file stringOps.C.

References Foam::expandString(), and s().

Here is the call graph for this function:

◆ inplaceReplaceVar()

bool inplaceReplaceVar ( std::string &  s,
const word varName 
)

Replace environment variable contents with its name.

This is essentially the inverse operation for inplaceExpand for a single element. Return true if a replacement was successful.

Definition at line 906 of file stringOps.C.

References Foam::getEnv(), and s().

Here is the call graph for this function:

◆ validate()

StringType validate ( const std::string &  str,
const UnaryPredicate &  accept,
const bool  invert = false 
)

Return a copy of the input string with validated characters.

Parameters
invertInvert the test logic

Definition at line 70 of file stringOpsTemplates.C.

References Foam::invert().

Here is the call graph for this function:

◆ findTrim()

std::pair< size_t, size_t > findTrim ( const std::string &  s,
size_t  pos = 0,
size_t  len = std::string::npos 
)

Find (first, last) non-space locations in string or sub-string.

This may change to std::string_view in the future.

◆ trimLeft()

Foam::string trimLeft ( const std::string &  s)

Return string trimmed of leading whitespace.

Definition at line 930 of file stringOps.C.

References Foam::pos(), and s().

Here is the call graph for this function:

◆ inplaceTrimLeft()

void inplaceTrimLeft ( std::string &  s)

Trim leading whitespace inplace.

Definition at line 952 of file stringOps.C.

References Foam::pos(), and s().

Referenced by inplaceTrim().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ trimRight()

Foam::string trimRight ( const std::string &  s)

Return string trimmed of trailing whitespace.

Definition at line 972 of file stringOps.C.

References s().

Here is the call graph for this function:

◆ inplaceTrimRight()

void inplaceTrimRight ( std::string &  s)

Trim trailing whitespace inplace.

Definition at line 992 of file stringOps.C.

References s().

Referenced by inplaceTrim(), and ensightSurfaceReader::readLine().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ trim()

Foam::string trim ( const std::string &  s)

Return string trimmed of leading and trailing whitespace.

Definition at line 1046 of file stringOps.C.

References Foam::pos(), and s().

Referenced by exprDriver::addVariables().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ inplaceTrim()

void inplaceTrim ( std::string &  s)

Trim leading and trailing whitespace inplace.

Definition at line 1067 of file stringOps.C.

References inplaceTrimLeft(), inplaceTrimRight(), and s().

Referenced by exprDriver::addVariables(), expressionEntry::inplaceExpand(), dynamicCodeContext::inplaceExpand(), Foam::recursiveExpand(), and exprString::trim().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ inplaceRemoveSpace()

void inplaceRemoveSpace ( std::string &  s)

Eliminate whitespace inplace.

Definition at line 1074 of file stringOps.C.

References s().

Referenced by Foam::getIdentifier().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ removeComments()

Foam::string removeComments ( const std::string &  s)

Return string with C/C++ comments removed.

Definition at line 1080 of file stringOps.C.

References inplaceRemoveComments(), and s().

Here is the call graph for this function:

◆ inplaceRemoveComments()

void inplaceRemoveComments ( std::string &  s)

Remove C/C++ comments inplace.

Definition at line 1088 of file stringOps.C.

References n, and s().

Referenced by exprString::inplaceExpand(), and removeComments().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ lower()

Foam::string lower ( const std::string &  s)

Return string copy transformed with std::tolower on each character.

Definition at line 1184 of file stringOps.C.

References s().

Referenced by STLAsciiParseManual::execute().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ inplaceLower()

void inplaceLower ( std::string &  s)

Inplace transform string with std::tolower on each character.

Definition at line 1194 of file stringOps.C.

References s().

Referenced by STARCDMeshReader::readBoundary().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ upper()

Foam::string upper ( const std::string &  s)

Return string copy transformed with std::toupper on each character.

Definition at line 1200 of file stringOps.C.

References s().

Referenced by ABAQUSCore::readHelper::addNewElset(), Foam::getIdentifier(), argList::printMan(), ABAQUSCore::readHelper::read(), ABAQUSCore::readHelper::readSurfaceElements(), and Foam::writeCoordHeader().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ inplaceUpper()

void inplaceUpper ( std::string &  s)

Inplace transform string with std::toupper on each character.

Definition at line 1210 of file stringOps.C.

References s().

Here is the call graph for this function:

◆ splitFunctionArgs()

Foam::label splitFunctionArgs ( const std::string &  str,
wordRes args,
List< Tuple2< word, string > > &  namedArgs 
)

Split out arguments (named or unnamed) from an input string.

For example,

(U)
    -> named = ()
    -> unnamed = (U)

(patch=inlet, p)
    -> named = ((patch inlet))
    -> unnamed = (p)

testing, start=100, stop=200
    -> named = ((start 100)(stop 200))
    -> unnamed = (testing)
Returns
total number of arguments

Definition at line 56 of file stringOpsSplit.C.

References args, Foam::name(), Foam::pos(), and argList::size().

Referenced by functionObjectList::readFunctionObject().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ split() [1/2]

Foam::SubStrings< StringType > split ( const StringType &  str,
const char  delim,
const bool  keepEmpty = false 
)

Split string into sub-strings at the delimiter character.

Empty sub-strings are normally suppressed. Behaviour is ill-defined if delim is a NUL character.

Definition at line 97 of file stringOpsTemplates.C.

References SubStrings< StringType >::append().

Referenced by dictionary::makeScopedDict().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ split() [2/2]

Foam::SubStrings< StringType > split ( const StringType &  str,
const std::string &  delim,
const bool  keepEmpty = false 
)

Split string into sub-strings using delimiter string.

Empty sub-strings are normally suppressed.

Definition at line 133 of file stringOpsTemplates.C.

References SubStrings< StringType >::append().

Here is the call graph for this function:

◆ splitAny()

Foam::SubStrings< StringType > splitAny ( const StringType &  str,
const std::string &  delim 
)

Split string into sub-strings using any characters in delimiter.

Empty sub-strings are normally suppressed. Behaviour is ill-defined if delim is an empty string.

Definition at line 169 of file stringOpsTemplates.C.

References SubStrings< StringType >::append(), and Foam::pos().

Referenced by scalarRanges::parse(), and splitSpace().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ splitFixed()

Foam::SubStrings< StringType > splitFixed ( const StringType &  str,
const std::string::size_type  width,
const std::string::size_type  start = 0 
)

Split string into sub-strings using a fixed field width.

Behaviour is ill-defined if width is zero.

Parameters
strthe string to be split
widththe fixed field width for each sub-string
startthe optional offset of where to start the splitting. Any text prior to start is ignored in the operation.

Definition at line 210 of file stringOpsTemplates.C.

References SubStrings< StringType >::append(), and Foam::pos().

Here is the call graph for this function:

◆ splitSpace()

Foam::SubStrings< StringType > splitSpace ( const StringType &  str)

Split string into sub-strings at whitespace (TAB, NL, VT, FF, CR, SPC)

Empty sub-strings are suppressed.

Definition at line 245 of file stringOpsTemplates.C.

References splitAny().

Referenced by argList::displayDoc(), OBJedgeFormat::read(), and ensightSurfaceReader::readCase().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ writeWrapped()

void writeWrapped ( OSstream os,
const std::string &  str,
const std::string::size_type  width,
const std::string::size_type  indent = 0,
const bool  escape = false 
)

Output string with text wrapping.

Always includes a trailing newline, unless the string itself is empty.

Parameters
osthe output stream
strthe text to be output
widththe max-width before wrapping
indentindentation for continued lines
escapeescape any backslashes on output

Definition at line 1216 of file stringOps.C.

References Foam::indent(), Foam::isspace(), Foam::nl, os(), and Foam::pos().

Referenced by argList::printMan(), Foam::printManOption(), argList::printNotes(), and Foam::printOptionUsage().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ evaluate() [1/2]

Foam::string evaluate ( label  fieldWidth,
const std::string &  s,
size_t  pos = 0,
size_t  len = std::string::npos 
)

String evaluation with specified (positive, non-zero) field width.

InfoErr<< "Evaluate " << str.substr(pos, len) << nl;

InfoErr<< "Evaluate " << str.substr(pos, len) << nl;

Definition at line 36 of file stringOpsEvaluate.C.

References exprResult::hasValue(), Foam::InfoErr, Foam::nl, os(), parseDriver::parse(), Foam::pos(), exprDriver::result(), exprResult::size(), exprResult::writeField(), and exprResult::writeValue().

Referenced by Foam::recursiveExpand().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ evaluate() [2/2]

Foam::string evaluate ( const std::string &  s,
size_t  pos = 0,
size_t  len = std::string::npos 
)

A simple string evaluation that handles various basic expressions. For trivial input, use readScalar instead (faster).

The evaluation supports the following:

  • operations: - + * / %
  • functions: exp, log, log10, pow, sqrt, cbrt, sqr, mag, magSqr
  • trigonometric: sin, cos, tan, asin, acos, atan, atan2, hypot
  • hyperbolic: sinh, cosh, tanh
  • conversions: degToRad, radToDeg
  • type conversion: bool, mag
  • constants: pi(), true, false
  • limits: neg, pos, neg0, pos0, sign, floor, ceil, round
  • other: rand, rand(seed)
  • logic: ! ? : == != <= => < >
Note
Unlike C/C++, the ternary and logical operations are not short-circuiting. So additional guards may be required.
The rand() function returns a uniform scalar on [0-1] interval and uses a constant seed.

Definition at line 93 of file stringOpsEvaluate.C.

References Foam::pos().

Here is the call graph for this function:

◆ natstrcmp()

int natstrcmp ( const char *  s1,
const char *  s2 
)

'Natural' compare for C-strings

Uses algorithm and code from Jan-Marten Spit jmspi.nosp@m.t@eu.nosp@m.ronet.nosp@m..nl

In the 'natural' comparison, strings are compared alphabetically and numerically. Thus 'file010.txt' sorts after 'file2.txt'

Parameters
s1left string
s2right string
Returns
-1 when s1 < s2, 0 when s1 == s2, 1 when s1 > s2

Definition at line 118 of file stringOpsSort.C.