BDE 4.14.0 Production release
Loading...
Searching...
No Matches
bdlb_string.h
Go to the documentation of this file.
1/// @file bdlb_string.h
2///
3/// The content of this file has been pre-processed for Doxygen.
4///
5
6
7// bdlb_string.h -*-C++-*-
8#ifndef INCLUDED_BDLB_STRING
9#define INCLUDED_BDLB_STRING
10
11#include <bsls_ident.h>
12BSLS_IDENT("$Id: $")
13
14/// @defgroup bdlb_string bdlb_string
15/// @brief Provide utility functions on STL-style and C-style strings.
16/// @addtogroup bdl
17/// @{
18/// @addtogroup bdlb
19/// @{
20/// @addtogroup bdlb_string
21/// @{
22///
23/// <h1> Outline </h1>
24/// * <a href="#bdlb_string-purpose"> Purpose</a>
25/// * <a href="#bdlb_string-classes"> Classes </a>
26/// * <a href="#bdlb_string-description"> Description </a>
27/// * <a href="#bdlb_string-synopsis"> Synopsis </a>
28/// * <a href="#bdlb_string-utf-8"> UTF-8 </a>
29/// * <a href="#bdlb_string-usage"> Usage </a>
30/// * <a href="#bdlb_string-example-1-tbd"> Example 1: TBD </a>
31///
32/// # Purpose {#bdlb_string-purpose}
33/// Provide utility functions on STL-style and C-style strings.
34///
35/// # Classes {#bdlb_string-classes}
36///
37/// - bdlb::String: namespace for functions on STL-style and C-style strings
38///
39/// @see bdlb_stringviewutil
40///
41/// # Description {#bdlb_string-description}
42/// This component defines a utility `struct`, `bdlb::String`, that
43/// provides a suite of functions operating on STL-style strings (`bsl::string`,
44/// `std::string`, `std::pmr::string`), C-style strings (necessarily
45/// null-terminated), and strings specified by a `(const char *, int)` or
46/// `(char *, int)` pair.
47///
48/// Unlike C-style strings, strings specified via `(const char *, int)` or
49/// `(char *, int)` need not be null-terminated and may contain embedded null
50/// ('\0') characters. Note that if a string is specified by a `const char *`
51/// and a length, the string address may be null only if 0 is supplied for the
52/// length; this is the only case where a null string argument is accepted by
53/// the functions of this utility. In particular, for strings specified by a
54/// `char *` (to non-`const`) and a length, the string address must not be null
55/// even if 0 is supplied for the length.
56///
57/// ## Synopsis {#bdlb_string-synopsis}
58///
59///
60/// This component provides several kinds of utility functions, including both
61/// case-sensitive and case-insensitive comparisons, case conversions, trimming
62/// functions, and other length-related operations. Most of the methods are
63/// overloaded to work on three string styles: (1) STL-style (`bsl::string`,
64/// `std::string`, `std::pmr::string`), (2) C-style, and (3) a
65/// `(const char *, int)` or `(char *, int)` pair. These overloaded methods are
66/// indicated schematically with a pseudo-argument `STR` representing any of the
67/// three possible string styles. Note that the pseudo-signature
68/// `foo(STR, STR)` represents nine overloaded signatures, not three.
69/// @code
70/// Method Purpose
71/// -------------------------- --------------------------------------------
72/// areEqualCaseless(STR, STR) case-insensitive equality comparison
73/// lowerCaseCmp(STR, STR) lexical comparison of lower-cased strings
74/// upperCaseCmp(STR, STR) lexical comparison of upper-cased strings
75///
76/// ltrim(STR) remove leading whitespace
77/// rtrim(STR) remove trailing whitespace
78/// trim(STR) remove both leading and trailing whitespace
79///
80/// toLower(STR) convert to lower case
81/// toUpper(STR) convert to upper case
82///
83/// strnlen(const char *, int) null-terminated length, but bounded by `int`
84/// toFixedLength(...) fixed-length copy with padding character
85/// pad(...) append padding `char` up to specified length
86/// @endcode
87///
88/// ## UTF-8 {#bdlb_string-utf-8}
89///
90///
91/// Note that functions involving the case and classification of characters deal
92/// with base ASCII *only*. For example, for strings encoded in UTF-8, the
93/// functions behave as expected for the ASCII subset of UTF-8 but do *not*
94/// provide full Unicode support.
95///
96/// ## Usage {#bdlb_string-usage}
97///
98///
99/// This section illustrates intended use of this component.
100///
101/// ### Example 1: TBD {#bdlb_string-example-1-tbd}
102///
103///
104/// TBD
105/// @}
106/** @} */
107/** @} */
108
109/** @addtogroup bdl
110 * @{
111 */
112/** @addtogroup bdlb
113 * @{
114 */
115/** @addtogroup bdlb_string
116 * @{
117 */
118
119#include <bdlscm_version.h>
120
121#include <bslma_allocator.h>
122
123#include <bsls_assert.h>
124#include <bsls_libraryfeatures.h>
125#include <bsls_review.h>
126
127#include <bsl_climits.h> // 'INT_MAX'
128#include <bsl_cstddef.h>
129#include <bsl_cstring.h>
130#include <bsl_string.h>
131
132#include <string>
133
134
135namespace bdlb {
136
137 // =============
138 // struct String
139 // =============
140
141/// This `struct` provides a namespace for a suite of functions on STL-style
142/// strings (`bsl::string`, `std::string`, `std::pmr::string`), C-style
143/// strings, and strings specified by a `(const char *, int)` or
144/// `(char *, int)` pair.
145struct String {
146
147 // CLASS METHODS
148
149 static bool areEqualCaseless(const char *lhsString, const char *rhsString);
150 static bool areEqualCaseless(const char *lhsString,
151 const char *rhsString,
152 int rhsLength);
153 static bool areEqualCaseless(const char *lhsString,
154 const bsl::string& rhsString);
155 static bool areEqualCaseless(const char *lhsString,
156 int lhsLength,
157 const char *rhsString);
158 static bool areEqualCaseless(const char *lhsString,
159 int lhsLength,
160 const char *rhsString,
161 int rhsLength);
162 static bool areEqualCaseless(const char *lhsString,
163 int lhsLength,
164 const bsl::string& rhsString);
165 static bool areEqualCaseless(const bsl::string& lhsString,
166 const char *rhsString);
167 static bool areEqualCaseless(const bsl::string& lhsString,
168 const char *rhsString,
169 int rhsLength);
170 /// Compare for equality the specified `lhsString` and `rhsString`
171 /// having the optionally specified `lhsLength` and `rhsLength`,
172 /// respectively, *as if* the strings were converted to lower case
173 /// before the equality comparison. Return `true` if `lhsString` is
174 /// equal to `rhsString`, and `false` otherwise. The behavior is
175 /// undefined unless `0 <= lhsLength` and `0 <= rhsLength` (if
176 /// specified), and `lhsString.size() <= INT_MAX` and
177 /// `rhsString.size() <= INT_MAX` (if applicable). See
178 /// @ref bdlb_stringviewutil for an identically named method having the
179 /// same semantics taking `bsl::string_view`.
180 static bool areEqualCaseless(const bsl::string& lhsString,
181 const bsl::string& rhsString);
182
183 /// Create a null-terminated copy of the specified `string`, using the
184 /// specified `basicAllocator` to supply memory, and return the address
185 /// of the newly-created modifiable string. The string that is returned
186 /// is owned by the caller. The behavior is undefined unless
187 /// `bsl::strlen(string) <= INT_MAX` and `basicAllocator` is non-null.
188 static char *copy(const char *string, bslma::Allocator *basicAllocator);
189
190 /// Create a null-terminated copy of the specified `string` having the
191 /// specified `length` (in bytes), using the specified `basicAllocator`
192 /// to supply memory, and return the address of the newly-created
193 /// modifiable string. The string that is returned is owned by the
194 /// caller. The behavior is undefined unless `0 <= length` and
195 /// `basicAllocator` is non-null. Note that if `string` contains any
196 /// embedded null ('\0') characters they will be propagated to the copy.
197 static char *copy(const char *string,
198 int length,
199 bslma::Allocator *basicAllocator);
200
201 /// Create a null-terminated copy of the specified `string`, using the
202 /// specified `basicAllocator` to supply memory, and return the address
203 /// of the newly-created modifiable string. The string that is returned
204 /// is owned by the caller. The behavior is undefined unless
205 /// `string.size() <= INT_MAX` and `basicAllocator` is non-null. Note
206 /// that if `string` contains any embedded null ('\0') characters they
207 /// will be propagated to the copy.
208 static char *copy(const bsl::string& string,
209 bslma::Allocator *basicAllocator);
210
211 static int lowerCaseCmp(const char *lhsString, const char *rhsString);
212 static int lowerCaseCmp(const char *lhsString,
213 const char *rhsString,
214 int rhsLength);
215 static int lowerCaseCmp(const char *lhsString,
216 const bsl::string& rhsString);
217
218 static int lowerCaseCmp(const char *lhsString,
219 int lhsLength,
220 const char *rhsString);
221 static int lowerCaseCmp(const char *lhsString,
222 int lhsLength,
223 const char *rhsString,
224 int rhsLength);
225 static int lowerCaseCmp(const char *lhsString,
226 int lhsLength,
227 const bsl::string& rhsString);
228
229 static int lowerCaseCmp(const bsl::string& lhsString,
230 const char *rhsString);
231 static int lowerCaseCmp(const bsl::string& lhsString,
232 const char *rhsString,
233 int rhsLength);
234 /// Compare the specified `lhsString` and `rhsString` having the
235 /// optionally specified `lhsLength` and `rhsLength`, respectively.
236 /// Return 1 if, after conversion to lower case, `lhsString` is
237 /// lexically greater than `rhsString`, 0 if they are equal up to a case
238 /// conversion, and -1 otherwise. The behavior is undefined unless
239 /// `0 <= lhsLength` and `0 <= rhsLength` (if specified), and
240 /// `lhsString.size() <= INT_MAX` and `rhsString.size() <= INT_MAX` (if
241 /// applicable). See @ref bdlb_stringviewutil for an identically named
242 /// method having the same semantics taking `bsl::string_view`.
243 static int lowerCaseCmp(const bsl::string& lhsString,
244 const bsl::string& rhsString);
245
246 static void ltrim(char *string);
247 static void ltrim(bsl::string *string);
248 /// Remove all leading whitespace characters from the specified
249 /// `string`. If `string` consists of only whitespace then it will be
250 /// empty (i.e., have 0 length) after this operation. The behavior is
251 /// undefined unless `string->size() <= INT_MAX` (if applicable). See
252 /// @ref bdlb_stringviewutil for an identically named method having
253 /// similar semantics taking (and returning) `bsl::string_view`.
254 static void ltrim(std::string *string);
255#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
256 static void ltrim(std::pmr::string *string);
257#endif
258
259 /// Remove all leading whitespace characters from the specified `string`
260 /// having the specified `length`, and load into `length` the number of
261 /// characters in the resulting (trimmed) string. If `string` consists
262 /// of only whitespace then it will be empty (i.e., have 0 length) after
263 /// this operation. The behavior is undefined unless `0 <= *length`.
264 /// Note that `length` is both an input and output parameter. See
265 /// @ref bdlb_stringviewutil for an identically named method having
266 /// similar semantics taking (and returning) `bsl::string_view`.
267 static void ltrim(char *string, int *length);
268
269 static void pad(bsl::string *string, int length, char padChar = ' ');
270 /// Append repeatedly to the specified `string` the optionally specified
271 /// `padChar` until `string` has the specified `length`. If `padChar`
272 /// is not specified the space (` `) character is appended. This
273 /// operation has no effect if `string.size() >= length`. The behavior
274 /// is undefined unless `0 <= length`.
275 static void pad(std::string *string, int length, char padChar = ' ');
276
277#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
278 /// Append repeatedly to the specified `string` the optionally specified
279 /// `padChar` until `string` has the specified `length`. If `padChar`
280 /// is not specified the space (` `) character is appended. This
281 /// operation has no effect if `string.size() >= length`.
282 static void pad(std::pmr::string *string,
283 std::pmr::string::size_type length,
284 char padChar = ' ');
285#endif
286
287 static void rtrim(char *string);
288 static void rtrim(bsl::string *string);
289 /// Remove all trailing whitespace characters from the specified
290 /// `string`. If `string` consists of only whitespace then it will be
291 /// empty (i.e., have 0 length) after this operation. The behavior is
292 /// undefined unless `string->size() <= INT_MAX` (if applicable). See
293 /// @ref bdlb_stringviewutil for an identically named method having
294 /// similar semantics taking (and returning) `bsl::string_view`.
295 static void rtrim(std::string *string);
296#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
297 static void rtrim(std::pmr::string *string);
298#endif
299
300 /// Determine the number of characters that the specified `string`
301 /// having the specified `length` would have if all trailing whitespace
302 /// characters were removed and load the result into `*length`.
303 /// `string` is *not* modified. The behavior is undefined unless
304 /// `0 <= *length`. Note that `length` is both an input and output
305 /// parameter.
306 static void rtrim(const char *string, int *length);
307
308 /// Return the address providing non-modifiable access to the first
309 /// position in the specified `string` having `stringLen` characters at
310 /// which the specified `subString` having `subStringLen` characters is
311 /// found, or 0 if there is no such position. If `subStringLen` is 0,
312 /// `subString` may be null and `string` is returned. The behavior is
313 /// undefined unless `0 <= stringLen` and `0 <= subStringLen`. See
314 /// @ref bdlb_stringviewutil for an identically named method having
315 /// similar semantics taking (and returning) `bsl::string_view`.
316 static const char *strstr(const char *string,
317 int stringLen,
318 const char *subString,
319 int subStringLen);
320
321 /// Return the address providing non-modifiable access to the first
322 /// position in the specified `string` having `stringLen` characters at
323 /// which the specified `subString` having `subStringLen` characters is
324 /// found using case-insensitive comparison, or 0 if there is no such
325 /// position. If `subStringLen` is 0, `subString` may be null and
326 /// `string` is returned. The behavior is undefined unless
327 /// `0 <= stringLen` and `0 <= subStringLen`. See
328 /// @ref bdlb_stringviewutil for an identically named method having
329 /// similar semantics taking (and returning) `bsl::string_view`.
330 static const char *strstrCaseless(const char *string,
331 int stringLen,
332 const char *subString,
333 int subStringLen);
334
335 /// Return the address providing non-modifiable access to the last
336 /// position in the specified `string` having `stringLen` characters at
337 /// which the specified `subString` having `subStringLen` characters is
338 /// found, or 0 if there is no such position. If `subStringLen` is 0,
339 /// `subString` may be null and `string + stringLen` is returned. The
340 /// behavior is undefined unless `0 <= stringLen` and
341 /// `0 <= subStringLen`. See @ref bdlb_stringviewutil for an identically
342 /// named method having similar semantics taking (and returning)
343 /// `bsl::string_view`.
344 static const char *strrstr(const char *string,
345 int stringLen,
346 const char *subString,
347 int subStringLen);
348
349 /// Return the address providing non-modifiable access to the last
350 /// position in the specified `string` having `stringLen` characters at
351 /// which the specified `subString` having `subStringLen` characters is
352 /// found using case-insensitive comparison, or 0 if there is no such
353 /// position. If `subStringLen` is 0, `subString` may be null and
354 /// `string + stringLen` is returned. The behavior is undefined unless
355 /// `0 <= stringLen` and `0 <= subStringLen`. See
356 /// @ref bdlb_stringviewutil for an identically named method having
357 /// similar semantics taking (and returning) `bsl::string_view`.
358 static const char *strrstrCaseless(const char *string,
359 int stringLen,
360 const char *subString,
361 int subStringLen);
362
363 /// Return the minimum of the length of the specified `string` and the
364 /// specified `maximumLength`. If `maximumLength` is 0, `string` may be
365 /// null and 0 is returned. The behavior is undefined unless
366 /// `0 <= maximumLength`.
367 static int strnlen(const char *string, int maximumLength);
368
369 /// Copy into the specified `dstString` at most the specified leading
370 /// `dstLength` characters from the specified `srcString` having the
371 /// specified `srcLength`. If `srcLength < dstLength`, after
372 /// `srcString` is copied to `dstString` repeatedly append to
373 /// `dstString` the optionally specified `padChar` until the total
374 /// number of characters written to `dstString` is `dstLength`. If
375 /// `padChar` is not specified the space (` `) character is appended.
376 /// The behavior is undefined unless `0 <= dstLength` and
377 /// `0 <= srcLength`.
378 static void toFixedLength(char *dstString,
379 int dstLength,
380 const char *srcString,
381 int srcLength,
382 char padChar = ' ');
383
384 static void toLower(char *string);
385 static void toLower(char *string, int length);
386 static void toLower(bsl::string *string);
387 /// Replace all upper case characters in the specified `string` having
388 /// the optionally specified `length` with their lower-case equivalent.
389 /// The behavior is undefined unless `0 <= length` (if specified) and
390 /// `string->size() <= INT_MAX` (if applicable).
391 static void toLower(std::string *string);
392#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
393 static void toLower(std::pmr::string *string);
394#endif
395
396 static void toUpper(char *string);
397 static void toUpper(char *string, int length);
398 static void toUpper(bsl::string *string);
399 /// Replace all lower case characters in the specified `string` having
400 /// the optionally specified `length` with their upper-case equivalent.
401 /// The behavior is undefined unless `0 <= length` (if specified) and
402 /// `string->size() <= INT_MAX` (if applicable).
403 static void toUpper(std::string *string);
404#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
405 static void toUpper(std::pmr::string *string);
406#endif
407
408 static void trim(char *string);
409 static void trim(bsl::string *string);
410 /// Remove all leading and trailing whitespace characters from the
411 /// specified `string`. If `string` consists of only whitespace then it
412 /// will be empty (i.e., have 0 length) after this operation. The
413 /// behavior is undefined unless `string->size() <= INT_MAX` (if
414 /// applicable). See @ref bdlb_stringviewutil for an identically named
415 /// method having similar semantics taking (and returning)
416 /// `bsl::string_view`.
417 static void trim(std::string *string);
418#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
419 static void trim(std::pmr::string *string);
420#endif
421
422 /// Remove all leading and trailing whitespace characters from the
423 /// specified `string` having the specified `length`, and load into
424 /// `length` the number of characters in the resulting (trimmed) string.
425 /// If `string` consists of only whitespace then it will be empty (i.e.,
426 /// have 0 length) after this operation. The behavior is undefined
427 /// unless `0 <= *length`. Note that `length` is both an input and
428 /// output parameter. See @ref bdlb_stringviewutil for an identically
429 /// named method having similar semantics taking (and returning)
430 /// `bsl::string_view`.
431 static void trim(char *string, int *length);
432
433 /// Skip leading and trailing whitespace characters in the string
434 /// indicated by the specified `*begin` and `*end` iterators by
435 /// appropriately advancing `*begin` and regressing `*end`. If the
436 /// indicated string is empty, or consists solely of whitespace
437 /// characters, `*begin` is unchanged and `*end` is regressed to
438 /// `*begin`. Otherwise, advance `*begin` to the first non-whitespace
439 /// character whose position is greater than or equal to `*begin` and
440 /// regress `*end` to one past the position of the last non-whitespace
441 /// character whose position is less than `*end`. The indicated string
442 /// need not be null-terminated and may contain embedded null ('\0')
443 /// characters. The behavior is undefined unless `*begin <= *end`.
444 /// Note that since `*begin` and `*end` are iterators, `*end` refers to
445 /// the character one past the end of the subject string.
446 static void skipLeadingTrailing(const char **begin, const char **end);
447
448 static int upperCaseCmp(const char *lhsString, const char *rhsString);
449 static int upperCaseCmp(const char *lhsString,
450 const char *rhsString,
451 int rhsLength);
452 static int upperCaseCmp(const char *lhsString,
453 const bsl::string& rhsString);
454
455 static int upperCaseCmp(const char *lhsString,
456 int lhsLength,
457 const char *rhsString);
458 static int upperCaseCmp(const char *lhsString,
459 int lhsLength,
460 const char *rhsString,
461 int rhsLength);
462 static int upperCaseCmp(const char *lhsString,
463 int lhsLength,
464 const bsl::string& rhsString);
465 static int upperCaseCmp(const bsl::string& lhsString,
466 const char *rhsString);
467 static int upperCaseCmp(const bsl::string& lhsString,
468 const char *rhsString,
469 int rhsLength);
470 /// Compare the specified `lhsString` and `rhsString` having the
471 /// optionally specified `lhsLength` and `rhsLength`, respectively, *as*
472 /// *if* the strings were converted to upper case before the comparison.
473 /// Return 1 if `lhsString` is lexically greater than `rhsString`, 0 if
474 /// they are equal, and -1 otherwise. The behavior is undefined unless
475 /// `0 <= lhsLength` and `0 <= rhsLength` (if specified), and
476 /// `lhsString.size() <= INT_MAX` and `rhsString.size() <= INT_MAX` (if
477 /// applicable). See @ref bdlb_stringviewutil for an identically named
478 /// method having the same semantics taking `bsl::string_view`.
479 static int upperCaseCmp(const bsl::string& lhsString,
480 const bsl::string& rhsString);
481};
482
483// ============================================================================
484// INLINE DEFINITIONS
485// ============================================================================
486
487 // -------------
488 // struct String
489 // -------------
490
491// CLASS METHODS
492inline
493bool String::areEqualCaseless(const char *lhsString,
494 const bsl::string& rhsString)
495{
496 BSLS_ASSERT(lhsString);
497 BSLS_ASSERT(rhsString.size() <= INT_MAX);
498
499 return areEqualCaseless(lhsString,
500 &rhsString[0],
501 static_cast<int>(rhsString.size()));
502}
503
504inline
505bool String::areEqualCaseless(const char *lhsString,
506 int lhsLength,
507 const char *rhsString)
508{
509 BSLS_ASSERT(lhsString || 0 == lhsLength);
510 BSLS_ASSERT(0 <= lhsLength);
511 BSLS_ASSERT(rhsString);
512
513 return areEqualCaseless(rhsString, lhsString, lhsLength);
514}
515
516inline
517bool String::areEqualCaseless(const char *lhsString,
518 int lhsLength,
519 const bsl::string& rhsString)
520{
521 BSLS_ASSERT(lhsString || 0 == lhsLength);
522 BSLS_ASSERT(0 <= lhsLength);
523 BSLS_ASSERT(rhsString.size() <= INT_MAX);
524
525 return areEqualCaseless(lhsString,
526 lhsLength,
527 rhsString.data(),
528 static_cast<int>(rhsString.size()));
529}
530
531inline
532bool String::areEqualCaseless(const bsl::string& lhsString,
533 const char *rhsString)
534{
535 BSLS_ASSERT(lhsString.size() <= INT_MAX);
536 BSLS_ASSERT(rhsString);
537
538 return areEqualCaseless(rhsString,
539 lhsString.data(),
540 static_cast<int>(lhsString.size()));
541}
542
543inline
544bool String::areEqualCaseless(const bsl::string& lhsString,
545 const char *rhsString,
546 int rhsLength)
547{
548 BSLS_ASSERT(lhsString.size() <= INT_MAX);
549 BSLS_ASSERT(rhsString || 0 == rhsLength);
550 BSLS_ASSERT(0 <= rhsLength);
551
552 return areEqualCaseless(lhsString.data(),
553 static_cast<int>(lhsString.size()),
554 rhsString,
555 rhsLength);
556}
557
558inline
559bool String::areEqualCaseless(const bsl::string& lhsString,
560 const bsl::string& rhsString)
561{
562 BSLS_ASSERT(lhsString.size() <= INT_MAX);
563 BSLS_ASSERT(rhsString.size() <= INT_MAX);
564
565 return areEqualCaseless(lhsString.data(),
566 static_cast<int>(lhsString.size()),
567 rhsString.data(),
568 static_cast<int>(rhsString.size()));
569}
570
571inline
572char *String::copy(const char *string, bslma::Allocator *basicAllocator)
573{
574 BSLS_ASSERT(string);
575 BSLS_ASSERT(bsl::strlen(string) <= INT_MAX);
576 BSLS_ASSERT(basicAllocator);
577
578 return copy(string,
579 static_cast<int>(bsl::strlen(string)),
580 basicAllocator);
581}
582
583inline
584char *String::copy(const bsl::string& string,
585 bslma::Allocator *basicAllocator)
586{
587 BSLS_ASSERT(string.size() <= INT_MAX);
588 BSLS_ASSERT(basicAllocator);
589
590 return copy(string.data(),
591 static_cast<int>(string.size()),
592 basicAllocator);
593}
594
595inline
596int String::lowerCaseCmp(const char *lhsString,
597 const bsl::string& rhsString)
598{
599 BSLS_ASSERT(lhsString);
600 BSLS_ASSERT(rhsString.size() <= INT_MAX);
601
602 return lowerCaseCmp(lhsString,
603 &rhsString[0],
604 static_cast<int>(rhsString.size()));
605}
606
607inline
608int String::lowerCaseCmp(const char *lhsString,
609 int lhsLength,
610 const char *rhsString)
611{
612 BSLS_ASSERT(lhsString || 0 == lhsLength);
613 BSLS_ASSERT(0 <= lhsLength);
614 BSLS_ASSERT(rhsString);
615
616 return -lowerCaseCmp(rhsString, lhsString, lhsLength);
617}
618
619inline
620int String::lowerCaseCmp(const char *lhsString,
621 int lhsLength,
622 const bsl::string& rhsString)
623{
624 BSLS_ASSERT(lhsString || 0 == lhsLength);
625 BSLS_ASSERT(0 <= lhsLength);
626 BSLS_ASSERT(rhsString.size() <= INT_MAX);
627
628 return lowerCaseCmp(lhsString,
629 lhsLength,
630 rhsString.data(),
631 static_cast<int>(rhsString.size()));
632}
633
634inline
635int String::lowerCaseCmp(const bsl::string& lhsString,
636 const char *rhsString)
637{
638 BSLS_ASSERT(lhsString.size() <= INT_MAX);
639 BSLS_ASSERT(rhsString);
640
641 return -lowerCaseCmp(rhsString,
642 lhsString.data(),
643 static_cast<int>(lhsString.size()));
644}
645
646inline
647int String::lowerCaseCmp(const bsl::string& lhsString,
648 const char *rhsString,
649 int rhsLength)
650{
651 BSLS_ASSERT(lhsString.size() <= INT_MAX);
652 BSLS_ASSERT(rhsString || 0 == rhsLength);
653 BSLS_ASSERT(0 <= rhsLength);
654
655 return lowerCaseCmp(lhsString.data(),
656 static_cast<int>(lhsString.size()),
657 rhsString,
658 rhsLength);
659}
660
661inline
662int String::lowerCaseCmp(const bsl::string& lhsString,
663 const bsl::string& rhsString)
664{
665 BSLS_ASSERT(lhsString.size() <= INT_MAX);
666 BSLS_ASSERT(rhsString.size() <= INT_MAX);
667
668 return lowerCaseCmp(lhsString.data(),
669 static_cast<int>(lhsString.size()),
670 rhsString.data(),
671 static_cast<int>(rhsString.size()));
672}
673
674inline
675void String::ltrim(bsl::string *string)
676{
677 BSLS_ASSERT(string);
678 BSLS_ASSERT(string->size() <= INT_MAX);
679
680 int length = static_cast<int>(string->size());
681
682 ltrim(&(*string)[0], &length);
683 string->resize(length);
684}
685
686inline
687void String::ltrim(std::string *string)
688{
689 BSLS_ASSERT(string);
690 BSLS_ASSERT(string->size() <= INT_MAX);
691
692 int length = static_cast<int>(string->size());
693
694 ltrim(&(*string)[0], &length);
695 string->resize(length);
696}
697
698#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
699inline
700void String::ltrim(std::pmr::string *string)
701{
702 BSLS_ASSERT(string);
703 BSLS_ASSERT(string->size() <= INT_MAX);
704
705 int length = static_cast<int>(string->size());
706
707 ltrim(&(*string)[0], &length);
708 string->resize(length);
709}
710#endif
711
712inline
713void String::pad(bsl::string *string, int length, char padChar)
714{
715 BSLS_ASSERT(string);
716 BSLS_ASSERT(0 <= length);
717
718 if (string->size() < static_cast<bsl::size_t>(length)) {
719 string->resize(length, padChar);
720 }
721}
722
723inline
724void String::pad(std::string *string, int length, char padChar)
725{
726 BSLS_ASSERT(string);
727 BSLS_ASSERT(0 <= length);
728
729 if (string->size() < static_cast<bsl::size_t>(length)) {
730 string->resize(length, padChar);
731 }
732}
733
734#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
735inline
736void String::pad(std::pmr::string *string,
737 std::pmr::string::size_type length,
738 char padChar)
739{
740 BSLS_ASSERT(string);
741
742 if (string->size() < length) {
743 string->resize(length, padChar);
744 }
745}
746#endif
747
748inline
749void String::rtrim(bsl::string *string)
750{
751 BSLS_ASSERT(string);
752 BSLS_ASSERT(string->size() <= INT_MAX);
753
754 int length = static_cast<int>(string->size());
755
756 rtrim(&(*string)[0], &length);
757 string->resize(length);
758}
759
760inline
761void String::rtrim(std::string *string)
762{
763 BSLS_ASSERT(string);
764 BSLS_ASSERT(string->size() <= INT_MAX);
765
766 int length = static_cast<int>(string->size());
767
768 rtrim(&(*string)[0], &length);
769 string->resize(length);
770}
771
772#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
773inline
774void String::rtrim(std::pmr::string *string)
775{
776 BSLS_ASSERT(string);
777 BSLS_ASSERT(string->size() <= INT_MAX);
778
779 int length = static_cast<int>(string->size());
780
781 rtrim(&(*string)[0], &length);
782 string->resize(length);
783}
784#endif
785
786inline
787void String::toLower(bsl::string *string)
788{
789 BSLS_ASSERT(string);
790 BSLS_ASSERT(string->size() <= INT_MAX);
791
792 toLower(&(*string)[0], static_cast<int>(string->size()));
793}
794
795inline
796void String::toLower(std::string *string)
797{
798 BSLS_ASSERT(string);
799 BSLS_ASSERT(string->size() <= INT_MAX);
800
801 toLower(&(*string)[0], static_cast<int>(string->size()));
802}
803
804#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
805inline
806void String::toLower(std::pmr::string *string)
807{
808 BSLS_ASSERT(string);
809 BSLS_ASSERT(string->size() <= INT_MAX);
810
811 toLower(&(*string)[0], static_cast<int>(string->size()));
812}
813#endif
814
815inline
816void String::toUpper(bsl::string *string)
817{
818 BSLS_ASSERT(string);
819 BSLS_ASSERT(string->size() <= INT_MAX);
820
821 toUpper(&(*string)[0], static_cast<int>(string->size()));
822}
823
824inline
825void String::toUpper(std::string *string)
826{
827 BSLS_ASSERT(string);
828 BSLS_ASSERT(string->size() <= INT_MAX);
829
830 toUpper(&(*string)[0], static_cast<int>(string->size()));
831}
832
833#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
834inline
835void String::toUpper(std::pmr::string *string)
836{
837 BSLS_ASSERT(string);
838 BSLS_ASSERT(string->size() <= INT_MAX);
839
840 toUpper(&(*string)[0], static_cast<int>(string->size()));
841}
842#endif
843
844inline
845void String::trim(char *string, int *length)
846{
847 BSLS_ASSERT(string);
848 BSLS_ASSERT(length);
849 BSLS_ASSERT(0 <= *length);
850
851 rtrim(string, length);
852 ltrim(string, length);
853}
854
855inline
856void String::trim(bsl::string *string)
857{
858 BSLS_ASSERT(string);
859 BSLS_ASSERT(string->size() <= INT_MAX);
860
861 int length = static_cast<int>(string->size());
862
863 rtrim(&(*string)[0], &length);
864 ltrim(&(*string)[0], &length);
865 string->resize(length);
866}
867
868inline
869void String::trim(std::string *string)
870{
871 BSLS_ASSERT(string);
872 BSLS_ASSERT(string->size() <= INT_MAX);
873
874 int length = static_cast<int>(string->size());
875
876 rtrim(&(*string)[0], &length);
877 ltrim(&(*string)[0], &length);
878 string->resize(length);
879}
880
881#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
882inline
883void String::trim(std::pmr::string *string)
884{
885 BSLS_ASSERT(string);
886 BSLS_ASSERT(string->size() <= INT_MAX);
887
888 int length = static_cast<int>(string->size());
889
890 rtrim(&(*string)[0], &length);
891 ltrim(&(*string)[0], &length);
892 string->resize(length);
893}
894#endif
895
896inline
897int String::upperCaseCmp(const char *lhsString,
898 const bsl::string& rhsString)
899{
900 BSLS_ASSERT(lhsString);
901 BSLS_ASSERT(rhsString.size() <= INT_MAX);
902
903 return upperCaseCmp(lhsString,
904 &rhsString[0],
905 static_cast<int>(rhsString.size()));
906}
907
908inline
909int String::upperCaseCmp(const char *lhsString,
910 int lhsLength,
911 const char *rhsString)
912{
913 BSLS_ASSERT(lhsString || 0 == lhsLength);
914 BSLS_ASSERT(0 <= lhsLength);
915 BSLS_ASSERT(rhsString);
916
917 return -upperCaseCmp(rhsString, lhsString, lhsLength);
918}
919
920inline
921int String::upperCaseCmp(const char *lhsString,
922 int lhsLength,
923 const bsl::string& rhsString)
924{
925 BSLS_ASSERT(lhsString || 0 == lhsLength);
926 BSLS_ASSERT(0 <= lhsLength);
927 BSLS_ASSERT(rhsString.size() <= INT_MAX);
928
929 return upperCaseCmp(lhsString,
930 lhsLength,
931 rhsString.data(),
932 static_cast<int>(rhsString.size()));
933}
934
935inline
936int String::upperCaseCmp(const bsl::string& lhsString,
937 const char *rhsString)
938{
939 BSLS_ASSERT(lhsString.size() <= INT_MAX);
940 BSLS_ASSERT(rhsString);
941
942 return -upperCaseCmp(rhsString,
943 lhsString.data(),
944 static_cast<int>(lhsString.size()));
945}
946
947inline
948int String::upperCaseCmp(const bsl::string& lhsString,
949 const char *rhsString,
950 int rhsLength)
951{
952 BSLS_ASSERT(lhsString.size() <= INT_MAX);
953 BSLS_ASSERT(rhsString || 0 == rhsLength);
954 BSLS_ASSERT(0 <= rhsLength);
955
956 return upperCaseCmp(lhsString.data(),
957 static_cast<int>(lhsString.size()),
958 rhsString,
959 rhsLength);
960}
961
962inline
963int String::upperCaseCmp(const bsl::string& lhsString,
964 const bsl::string& rhsString)
965{
966 BSLS_ASSERT(lhsString.size() <= INT_MAX);
967 BSLS_ASSERT(rhsString.size() <= INT_MAX);
968
969 return upperCaseCmp(lhsString.data(),
970 static_cast<int>(lhsString.size()),
971 rhsString.data(),
972 static_cast<int>(rhsString.size()));
973}
974
975} // close package namespace
976
977
978#endif
979
980// ----------------------------------------------------------------------------
981// Copyright 2015 Bloomberg Finance L.P.
982//
983// Licensed under the Apache License, Version 2.0 (the "License");
984// you may not use this file except in compliance with the License.
985// You may obtain a copy of the License at
986//
987// http://www.apache.org/licenses/LICENSE-2.0
988//
989// Unless required by applicable law or agreed to in writing, software
990// distributed under the License is distributed on an "AS IS" BASIS,
991// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
992// See the License for the specific language governing permissions and
993// limitations under the License.
994// ----------------------------- END-OF-FILE ----------------------------------
995
996/** @} */
997/** @} */
998/** @} */
bslma_allocator.h
bsls_assert.h
bsls_ident.h
bsls_libraryfeatures.h
bsls_review.h
bsl::basic_string
Definition bslstl_string.h:1281
bsl::basic_string::size
size_type size() const BSLS_KEYWORD_NOEXCEPT
Definition bslstl_string.h:6592
bsl::basic_string::data
CHAR_TYPE * data() BSLS_KEYWORD_NOEXCEPT
Definition bslstl_string.h:6477
bslma::Allocator
Definition bslma_allocator.h:457
BSLS_ASSERT
#define BSLS_ASSERT(X)
Definition bsls_assert.h:1804
BSLS_IDENT
#define BSLS_IDENT(str)
Definition bsls_ident.h:195
bdlb
Definition bdlb_algorithmworkaroundutil.h:74
bdlb::String
Definition bdlb_string.h:145
bdlb::String::copy
static char * copy(const char *string, int length, bslma::Allocator *basicAllocator)
bdlb::String::areEqualCaseless
static bool areEqualCaseless(const char *lhsString, int lhsLength, const char *rhsString, int rhsLength)
bdlb::String::toFixedLength
static void toFixedLength(char *dstString, int dstLength, const char *srcString, int srcLength, char padChar=' ')
bdlb::String::toLower
static void toLower(char *string)
bdlb::String::skipLeadingTrailing
static void skipLeadingTrailing(const char **begin, const char **end)
bdlb::String::strrstr
static const char * strrstr(const char *string, int stringLen, const char *subString, int subStringLen)
bdlb::String::copy
static char * copy(const char *string, bslma::Allocator *basicAllocator)
Definition bdlb_string.h:572
bdlb::String::ltrim
static void ltrim(char *string)
bdlb::String::areEqualCaseless
static bool areEqualCaseless(const char *lhsString, const char *rhsString)
bdlb::String::toUpper
static void toUpper(char *string)
bdlb::String::strstr
static const char * strstr(const char *string, int stringLen, const char *subString, int subStringLen)
bdlb::String::trim
static void trim(char *string)
bdlb::String::pad
static void pad(bsl::string *string, int length, char padChar=' ')
Definition bdlb_string.h:713
bdlb::String::lowerCaseCmp
static int lowerCaseCmp(const char *lhsString, const char *rhsString, int rhsLength)
bdlb::String::areEqualCaseless
static bool areEqualCaseless(const char *lhsString, const char *rhsString, int rhsLength)
bdlb::String::strrstrCaseless
static const char * strrstrCaseless(const char *string, int stringLen, const char *subString, int subStringLen)
bdlb::String::rtrim
static void rtrim(const char *string, int *length)
bdlb::String::toUpper
static void toUpper(char *string, int length)
bdlb::String::lowerCaseCmp
static int lowerCaseCmp(const char *lhsString, int lhsLength, const char *rhsString, int rhsLength)
bdlb::String::upperCaseCmp
static int upperCaseCmp(const char *lhsString, int lhsLength, const char *rhsString, int rhsLength)
bdlb::String::lowerCaseCmp
static int lowerCaseCmp(const char *lhsString, const char *rhsString)
bdlb::String::upperCaseCmp
static int upperCaseCmp(const char *lhsString, const char *rhsString, int rhsLength)
bdlb::String::strstrCaseless
static const char * strstrCaseless(const char *string, int stringLen, const char *subString, int subStringLen)
bdlb::String::rtrim
static void rtrim(char *string)
bdlb::String::toLower
static void toLower(char *string, int length)
bdlb::String::upperCaseCmp
static int upperCaseCmp(const char *lhsString, const char *rhsString)
bdlb::String::ltrim
static void ltrim(char *string, int *length)
bdlb::String::strnlen
static int strnlen(const char *string, int maximumLength)