.TH "FBB::String" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Operations on std::string objects" .PP .SH "NAME" FBB::String \- Several operations on \fBstd::string\fP objects .PP .SH "SYNOPSIS" \fB#include \fP .br Linking option: \fI\-lbobcat\fP .PP .SH "DESCRIPTION" This class offers facilities for often used transformations on \fIstd::string\fP objects, which are not supported by the \fIstd::string\fP class itself\&. All members of \fBFBB::String\fP are static\&. .PP Initially this class was derived from \fBstd::string\fP\&. Deriving from \fIstd::string\fP, however, is considerd bad design as \fIstd::string\fP was not designed as a base\-class\&. .PP \fBFBB::String\fP offers a series of \fIstatic\fP member functions providing the facilities originally implemented as non\-static members\&. One of these members is the (overloaded) \fIsplit\fP member, splitting a string into elements separated by one or more configurable characters\&. These elements may contain or consist of double\- or single\-quoted (sub) strings and escape characters\&. Escape characters are converted to their implied byte\-values (e\&.g\&., \fI\en\fP is converted to byte value 10) unless they are embedded in single\-quoted (sub) strings\&. Quotes surrounding double\- and single\-quoted (sub) strings are removed from the elements returned by the \fIsplit\fP members\&. .PP .SH "NAMESPACE" \fBFBB\fP .br All constructors, members, operators and manipulators, mentioned in this man\-page, are defined in the namespace \fBFBB\fP\&. .PP .SH "INHERITS FROM" \-\- .PP .SH "ENUMERATIONS" .IP o \fBType\fP: .br This enumeration indicates the nature of the content of an element in the array returned by the overloaded \fIsplit\fP members (see below)\&. .IP \fBDQUOTE\fP, a subset of the characters in the matching \fIstring\fP element was delimited by double quotes in the in the string that was parsed by the \fIsplit\fP members\&. .IP \fBDQUOTE_UNTERMINATED\fP, the content of the string that was parsed by the \fIsplit\fP members started at some point with a double quote, but the matching ending double quote was lacking\&. .IP \fBESCAPED_END\fP, the content of the string that was parsed by the \fIsplit\fP members ended in a mere backslash\&. .IP \fBNORMAL\fP, a normal string; .IP \fBSEPARATOR\fP, a separator; .IP \fBSQUOTE\fP, a subset of the characters in the matching \fIstring\fP element was delimited by quotes in the in the string that was parsed by the \fIsplit\fP members\&. .IP \fBSQUOTE_UNTERMINATED\fP, the content of the string that was parsed by the \fIsplit\fP members started at some point with a quote, but the matching ending quote was lacking\&. .IP o \fBSplitType\fP: .br This enumeration is used to specify how \fIsplit\fP members should split the information in the string objects that are passed to these members: .IP \fBTOK\fP: the \fIsplit\fP member acts like the standard \fBC\fP function \fBstrtok\fP(3)\&. The essence here is that no empty elements are returned\&. E\&.g\&., a string containing \fI\(dq\&a,,\(dq\&\fP which is processed using the \fITOK\fP mode returns a \fINORMAL\fP element containing \fI\(dq\&a\(dq\&\fP\&. .IP \fBTOKSEP\fP: the \fIsplit\fP member acts like the standard \fBC\fP function \fBstrtok\fP(3), also returning information about encountered separators\&. Since \fIstrtok\fP doesn\(cq\&t return empty elements, \fITOKSEP\fP uses empty elements to indicate the occurrence of separators\&. E\&.g\&., a string containing \fI\(dq\&a,,\(dq\&\fP which is processed using the \fITOKSEP\fP mode returns a \fINORMAL\fP element containing \fI\(dq\&a\(dq\&\fP, followed by two empty \fISEPARATOR\fP elements\&. .IP \fBSTR\fP: the \fIsplit\fP member acts like the standard \fBC\fP function \fBstrstr\fP(3)\&. The essence here is that empty elements are also returned\&. E\&.g\&., a string containing \fI\(dq\&a,,\(dq\&\fP which is processed using the \fISTR\fP mode returns an element containing \fI\(dq\&a\(dq\&\fP, followed by two empty \fINORMAL\fP elements\&. .IP \fBSTRSEP\fP: the \fIsplit\fP member acts like the standard \fBC\fP function \fBstrstr\fP(3), also returning information about encountered separators\&. E\&.g\&., a string containing \fI\(dq\&a,,\(dq\&\fP which is processed using the \fISTRSEP\fP mode returns a \fINORMAL\fP element containing \fI\(dq\&a\(dq\&\fP, followed by a \fISEPARATOR\fP element containing \fI\(dq\&,\(dq\&\fP, followed by a \fINORMAL\fP empty element, followed by a \fISEPARATOR\fP element containing \fI\(dq\&,\(dq\&\fP, and finally followed by a \fINORMAL\fP empty element, .PP .SH "TYPEDEF" .PP The \fBtypedef SplitPair\fP represents \fBstd::pair\fP and is used by some overloaded \fBsplit\fP members (see below)\&. .PP .SH "STATIC MEMBER FUNCTIONS" .IP .IP o \fBchar const **argv(std::vector const &words)\fP: .br Returns a pointer to an allocated series of pointers to the \fBC\fP strings stored in the vector \fIwords\fP\&. The caller is responsible for returning the array of pointers to the common pool, but should \fInot\fP delete the \fBC\fP\-strings to which the pointers point\&. The last element of the returned array is guaranteed to be a 0\-pointer\&. .IP .IP o \fBint casecmp(std::string const &lhs, std::string const &rhs)\fP: .br Performs a case\-insensitive comparison of the content of two \fIstd::string\fP objects\&. A negative value is returned if \fIlhs\fP should be ordered before \fIrhs\fP; 0 is returned if the two strings have identical content; a positive value is returned if the \fIlhs\fP object should be ordered beyond \fIrhs\fP\&. .IP .IP o \fBstd::string escape(std::string const &str, char const *series = \(dq\&\(cq\&\e\(dq\&\e\e\(dq\&)\fP: .br Returns a copy of \fIstr\fP in which all characters in \fIseries\fP are prefixed by a backslash character\&. .IP .IP o \fBstd::string join(std::vector const &words, char sep)\fP: .br The elements of the \fIwords\fP vector are returned as one string, separated from each other by the \fIsep\fP character; .IP .IP o \fBstd::string join(std::vector const &entries, char sep, bool all = true)\fP: .br The \fIfirst\fP fields of the elements in \fIentries\fP are returned as one string, separated from each other by the \fIsep\fP character\&. If the parameter \fIall\fP is specified as \fIfalse\fP then elements whose \fIsecond\fP fields are equal to \fIString::SEPARATOR\fP are ignored\&. .IP .IP o \fBstd::string lc(std::string const &str) const\fP: .br Returns a copy of \fIstr\fP in which all letters were transformed to lower case letters\&. .IP .IP o \fBstd::vector split(std::string const &str, SplitType mode, char const *sep = \(dq\& \et\(dq\&)\fP: .br The string \fIstr\fP is split into substrings, separated by any of the characters in \fIsep\fP\&. The substrings are returned in a vector of \fISplitPair\fP elements, using the specified \fISplitType\fP mode (cf\&. the description of the various \fISplitPair\fP values and their effects in the \fIENUMERATIONS\fP section)\&. .IP .IP o \fBstd::vector split(std::string const &str, char const *separators = \(dq\& \et\(dq\&, bool addEmpty = false)\fP: .br This member acts like the previous one, using \fIaddEmpty == false\fP to select \fImode TOK\fP and \fIaddEmpty == true\fP to select \fImode TOKSEP\fP\&. .IP .IP o \fBsize_t split(std::vector *entries, std::string const &str, SplitType mode, char const *sep = \(dq\& \et\(dq\&)\fP: .br Same functionality as the first \fIsplit\fP member, but this member stores the \fISplitPair\fP elements in the vector pointed at by the \fIentries\fP parameter, first clearing the vector\&. This member returns the new value of \fIentries\->size()\fP\&. .IP .IP o \fBsize_t split(std::vector *entries, std::string const &str, char const *sep = \(dq\& \et\(dq\&, bool addEmpty = false)\fP: .br This member acts like the previous one, using \fIaddEmpty == false\fP to select \fImode TOK\fP and \fIaddEmpty == true\fP to select \fImode TOKSEP\fP\&. .IP .IP o \fBstd::vector split(Type *type, std::string const &str, SplitType stype, char const *sep = \(dq\& \et\(dq\&)\fP: .br Same functionality as the first \fIsplit\fP member, but this member merely stores the \fIfirst\fP fields of the \fISplitPair\fP elements in the returned vector\&. The \fIString::Type\fP variable whose address is passed to the \fItype\fP parameter is set to \fINORMAL\fP if the final entry was successfully determined; to \fIDQUOTE_UNTERMINATED\fP if a final closing double quote could not be found; to \fISQUOTE_UNTERMINATED\fP if a final closing single quote could not be found; and to \fIESCAPE_END\fP if the final character in \fIstr\fP is a backslash character\&. .IP .IP o \fBstd::vector split(Type *type, std::string const &str, char const *sep = \(dq\& \et\(dq\&, bool addEmpty = false)\fP: .br This member acts like the previous one, using \fIaddEmpty == false\fP to select \fImode TOK\fP and \fIaddEmpty == true\fP to select \fImode TOKSEP\fP\&. .IP .IP o \fBsize_t split(std::vector *words, std::string const &str, SplitType stype, char const *sep = \(dq\& \et\(dq\&)\fP: .br Same functionality as the first \fIsplit\fP member, but this member merely stores the \fIfirst\fP fields of the encountered \fISplitPair\fP elements in the vector pointed at by \fIwords\fP, first clearing the vector\&. This member returns the new value of \fIwords\->size()\fP\&. .IP .IP o \fBsize_t split(std::vector *words, std::string const &str, char const *sep = \(dq\& \et\(dq\&, bool addEmpty = false)\fP: .br This member acts like the previous one, using \fIaddEmpty == false\fP to select \fImode TOK\fP and \fIaddEmpty == true\fP to select \fImode TOKSEP\fP\&. .IP .IP o \fBstd::string trim(std::string const &str)\fP: .br Returns a copy of \fIstr\fP from which leading and trailing blank characters were removed\&. .IP .IP o \fBstd::string uc(std::string const &str)\fP: .br Returns a copy of \fIstr\fP in which all letters were capitalized\&. .IP .IP o \fBstd::string unescape(std::string const &str)\fP: .br Returns a copy of \fIstr\fP in which the escaped (i\&.e\&., prefixed by a backslash) characters were interpreted\&. All standard escape characters (\fI\ea\fP, \fI\eb\fP, \fI\ef\fP, \fI\en\fP, \fI\er\fP, \fI\et\fP, \fI\ev\fP) are recognized\&. If an escape character is followed by \fIx\fP at most the next two characters are interpreted as a hexadecimal number\&. If an escape character is followed by an octal digit, then at most the next three characters following the \fIbackslash\fP are interpreted as an octal number\&. In all other cases, the backslash is removed and the character following the backslash is kept\&. .IP .IP o \fBstd::string urlDecode(std::string const &str)\fP: .br URL specifications use \fI%xx\fP encoding to encode characters, except for alpha\-numeric characters and the characters \fI\- _ \&.\fP and \fI~\fP, which are kept as\-is\&. Other characters are encode by a \fI%\fP character, followed by two hexadecimal characters representing those characters\(cq\& byte value\&. E\&.g\&., a blank space is encoded as \fI%20\fP, a plus character is encoded as \fI%2B\fP\&. The member \fIurlDecode\fP returns a \fIstd::string\fP containing the decoded characters of the url\-encoded string that is passed as argument to this member\&. .IP .IP o \fBstd::string urlEncode(std::string const &str)\fP: .br See the member \fIurlDecode\fP: \fIurlEncode\fP returns a \fIstd::string\fP containing the url\-encoded characters of the characters in the string that is passed as argument to this member\&. .PP .SH "EXAMPLE" .PP .nf #include #include #include using namespace std; using namespace FBB; static char const *type[] = { \(dq\&DQUOTE_UNTERMINATED\(dq\&, \(dq\&SQUOTE_UNTERMINATED\(dq\&, \(dq\&ESCAPED_END\(dq\&, \(dq\&SEPARATOR\(dq\&, \(dq\&NORMAL\(dq\&, \(dq\&DQUOTE\(dq\&, \(dq\&SQUOTE\(dq\&, }; int main(int argc, char **argv) { cout << \(dq\&Program\(cq\&s name in uppercase: \(dq\& << String::uc(argv[0]) << \(dq\&\en\en\(dq\&; vector splitpair; string text{ \(dq\&one, two, \(cq\&thr\e\ex65\e\e145\(cq\&\(dq\& }; string encoded{ String::urlEncode(text) }; cout << \(dq\&The string `\(dq\& << text << \(dq\&\(cq\&\en\(dq\& \(dq\& as url\-encoded string: `\(dq\& << encoded << \(dq\&\(cq\&\en\(dq\& \(dq\& and the latter string url\-decoded: \(dq\& << String::urlDecode(encoded) << \(dq\&\en\(dq\& \(dq\&\en\(dq\& \(dq\&Splitting `\(dq\& << text << \(dq\&\(cq\& into \(dq\& << String::split(&splitpair, text, String::STRSEP, \(dq\&, \(dq\&) << \(dq\& fields\en\(dq\&; for (auto it = splitpair\&.begin(); it != splitpair\&.end(); ++it) cout << (it \- splitpair\&.begin() + 1) << \(dq\&: \(dq\& << type[it\->second] << \(dq\&: `\(dq\& << it\->first << \(dq\&\(cq\&, unescaped: `\(dq\& << String::unescape(it\->first) << \(dq\&\(cq\&\en\(dq\&; cout << \(cq\&\en\(cq\& << text << \(dq\&:\en\(dq\& \(dq\& upper case: \(dq\& << String::uc(text) << \(dq\&,\en\(dq\& \(dq\& lower case: \(dq\& << String::lc(text) << \(cq\&\en\(cq\&; } /* Calling the program as driver\(cq\& results in the following output: Program\(cq\&s name in uppercase: DRIVER Splitting `one, two, \(cq\&thr\ex65\e145\(cq\&\(cq\& into 9 fields 1: NORMAL: `one\(cq\&, unescaped: `one\(cq\& 2: SEPARATOR: `,\(cq\&, unescaped: `,\(cq\& 3: NORMAL: `\(cq\&, unescaped: `\(cq\& 4: SEPARATOR: ` \(cq\&, unescaped: ` \(cq\& 5: NORMAL: `two\(cq\&, unescaped: `two\(cq\& 6: SEPARATOR: `,\(cq\&, unescaped: `,\(cq\& 7: NORMAL: `\(cq\&, unescaped: `\(cq\& 8: SEPARATOR: ` \(cq\&, unescaped: ` \(cq\& 9: SQUOTE: `thr\ex65\e145\(cq\&, unescaped: `three\(cq\& one, two, \(cq\&thr\ex65\e145\(cq\&: upper case: ONE, TWO, \(cq\&THR\eX65\e145\(cq\&, lower case: one, two, \(cq\&thr\ex65\e145\(cq\& */ .fi .PP .SH "FILES" \fIbobcat/string\fP \- defines the class interface .PP .SH "SEE ALSO" \fBbobcat\fP(7) .PP .SH "BUGS" None Reported\&. .PP .SH "BOBCAT PROJECT FILES" .PP .IP o \fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page; .IP o \fIbobcat_5\&.07\&.00\-x\&.dsc\fP: detached signature; .IP o \fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive; .IP o \fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log; .IP o \fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the libraries; .IP o \fIlibbobcat1\-dev_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the libraries, headers and manual pages; .PP .SH "BOBCAT" Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&. .PP .SH "COPYRIGHT" This is free software, distributed under the terms of the GNU General Public License (GPL)\&. .PP .SH "AUTHOR" Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&. .PP