bdlb_string

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Synopsis
  • UTF-8
  • Usage
    • Example 1: TBD

Purpose

Provide utility functions on STL-style and C-style strings.

Classes

• bdlb::String: namespace for functions on STL-style and C-style strings

See also

bdlb_stringviewutil

Description

This component defines a utility struct, bdlb::String, that provides a suite of functions operating on STL-style strings (bsl::string, std::string, std::pmr::string), C-style strings (necessarily null-terminated), and strings specified by a (const char *, int) or (char *, int) pair.

Unlike C-style strings, strings specified via (const char *, int) or (char *, int) need not be null-terminated and may contain embedded null ('\0') characters. Note that if a string is specified by a const char * and a length, the string address may be null only if 0 is supplied for the length; this is the only case where a null string argument is accepted by the functions of this utility. In particular, for strings specified by a char * (to non-const) and a length, the string address must not be null even if 0 is supplied for the length.

Synopsis

This component provides several kinds of utility functions, including both case-sensitive and case-insensitive comparisons, case conversions, trimming functions, and other length-related operations. Most of the methods are overloaded to work on three string styles: (1) STL-style (bsl::string, std::string, std::pmr::string), (2) C-style, and (3) a (const char *, int) or (char *, int) pair. These overloaded methods are indicated schematically with a pseudo-argument STR representing any of the three possible string styles. Note that the pseudo-signature foo(STR, STR) represents nine overloaded signatures, not three.

Method                        Purpose
--------------------------    --------------------------------------------
areEqualCaseless(STR, STR)    case-insensitive equality comparison
lowerCaseCmp(STR, STR)        lexical comparison of lower-cased strings
upperCaseCmp(STR, STR)        lexical comparison of upper-cased strings
 
ltrim(STR)                    remove leading whitespace
rtrim(STR)                    remove trailing whitespace
trim(STR)                     remove both leading and trailing whitespace
 
toLower(STR)                  convert to lower case
toUpper(STR)                  convert to upper case
 
strnlen(const char *, int)    null-terminated length, but bounded by `int`
toFixedLength(...)            fixed-length copy with padding character
pad(...)                      append padding `char` up to specified length

UTF-8

Note that functions involving the case and classification of characters deal with base ASCII only. For example, for strings encoded in UTF-8, the functions behave as expected for the ASCII subset of UTF-8 but do not provide full Unicode support.

Usage

This section illustrates intended use of this component.

Example 1: TBD

TBD