BDE 4.39.x 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.
145///
146/// See @ref bdlb_string
147struct String {
148
149 // CLASS METHODS
150
151 /// Compare for equality the specified `lhsString` and `rhsString`
152 /// having the optionally specified `lhsLength` and `rhsLength`,
153 /// respectively, *as if* the strings were converted to lower case
154 /// before the equality comparison. Return `true` if `lhsString` is
155 /// equal to `rhsString`, and `false` otherwise.
156 ///
157 /// \pre The behavior is undefined unless `0 <= lhsLength` and `0 <= rhsLength` (if
158 /// specified), and `lhsString.size() <= INT_MAX` and
159 /// `rhsString.size() <= INT_MAX` (if applicable). See
160 /// @ref bdlb_stringviewutil for an identically named method having the
161 /// same semantics taking `bsl::string_view`.
162 static bool areEqualCaseless(const char *lhsString, const char *rhsString);
163 static bool areEqualCaseless(const char *lhsString,
164 const char *rhsString,
165 int rhsLength);
166 static bool areEqualCaseless(const char *lhsString,
167 const bsl::string& rhsString);
168 static bool areEqualCaseless(const char *lhsString,
169 int lhsLength,
170 const char *rhsString);
171 static bool areEqualCaseless(const char *lhsString,
172 int lhsLength,
173 const char *rhsString,
174 int rhsLength);
175 static bool areEqualCaseless(const char *lhsString,
176 int lhsLength,
177 const bsl::string& rhsString);
178 static bool areEqualCaseless(const bsl::string& lhsString,
179 const char *rhsString);
180 static bool areEqualCaseless(const bsl::string& lhsString,
181 const char *rhsString,
182 int rhsLength);
183 static bool areEqualCaseless(const bsl::string& lhsString,
184 const bsl::string& rhsString);
185
186 /// Create a null-terminated copy of the specified `string`, using the
187 /// specified `basicAllocator` to supply memory, and return the address
188 /// of the newly-created modifiable string. The string that is returned is owned by the caller.
189 ///
190 /// \pre The behavior is undefined unless
191 /// `bsl::strlen(string) <= INT_MAX` and `basicAllocator` is non-null.
192 static char *copy(const char *string, bslma::Allocator *basicAllocator);
193
194 /// Create a null-terminated copy of the specified `string` having the
195 /// specified `length` (in bytes), using the specified `basicAllocator`
196 /// to supply memory, and return the address of the newly-created
197 /// modifiable string. The string that is returned is owned by the caller.
198 ///
199 /// \pre The behavior is undefined unless `0 <= length` and `basicAllocator` is non-null.
200 ///
201 /// \note Note that if `string` contains any
202 /// embedded null ('\0') characters they will be propagated to the copy.
203 static char *copy(const char *string,
204 int length,
205 bslma::Allocator *basicAllocator);
206
207 /// Create a null-terminated copy of the specified `string`, using the
208 /// specified `basicAllocator` to supply memory, and return the address
209 /// of the newly-created modifiable string. The string that is returned is owned by the caller.
210 ///
211 /// \pre The behavior is undefined unless
212 /// `string.size() <= INT_MAX` and `basicAllocator` is non-null.
213 ///
214 /// \note Note that if `string` contains any embedded null ('\0') characters they
215 /// will be propagated to the copy.
216 static char *copy(const bsl::string& string,
217 bslma::Allocator *basicAllocator);
218
219 /// Compare the specified `lhsString` and `rhsString` having the
220 /// optionally specified `lhsLength` and `rhsLength`, respectively.
221 /// Return 1 if, after conversion to lower case, `lhsString` is
222 /// lexically greater than `rhsString`, 0 if they are equal up to a case conversion, and -1 otherwise.
223 ///
224 /// \pre The behavior is undefined unless
225 /// `0 <= lhsLength` and `0 <= rhsLength` (if specified), and
226 /// `lhsString.size() <= INT_MAX` and `rhsString.size() <= INT_MAX` (if
227 /// applicable). See @ref bdlb_stringviewutil for an identically named
228 /// method having the same semantics taking `bsl::string_view`.
229 static int lowerCaseCmp(const char *lhsString, const char *rhsString);
230 static int lowerCaseCmp(const char *lhsString,
231 const char *rhsString,
232 int rhsLength);
233 static int lowerCaseCmp(const char *lhsString,
234 const bsl::string& rhsString);
235
236 static int lowerCaseCmp(const char *lhsString,
237 int lhsLength,
238 const char *rhsString);
239 static int lowerCaseCmp(const char *lhsString,
240 int lhsLength,
241 const char *rhsString,
242 int rhsLength);
243 static int lowerCaseCmp(const char *lhsString,
244 int lhsLength,
245 const bsl::string& rhsString);
246 static int lowerCaseCmp(const bsl::string& lhsString,
247 const char *rhsString);
248 static int lowerCaseCmp(const bsl::string& lhsString,
249 const char *rhsString,
250 int rhsLength);
251 static int lowerCaseCmp(const bsl::string& lhsString,
252 const bsl::string& rhsString);
253
254 /// Remove all leading whitespace characters from the specified
255 /// `string`. If `string` consists of only whitespace then it will be
256 /// empty (i.e., have 0 length) after this operation.
257 ///
258 /// \pre The behavior is undefined unless `string->size() <= INT_MAX` (if applicable). See
259 /// @ref bdlb_stringviewutil for an identically named method having
260 /// similar semantics taking (and returning) `bsl::string_view`.
261 static void ltrim(char *string);
262 static void ltrim(bsl::string *string);
263 static void ltrim(std::string *string);
264#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
265 static void ltrim(std::pmr::string *string);
266#endif
267
268 /// Remove all leading whitespace characters from the specified `string`
269 /// having the specified `length`, and load into `length` the number of
270 /// characters in the resulting (trimmed) string. If `string` consists
271 /// of only whitespace then it will be empty (i.e., have 0 length) after this operation.
272 ///
273 /// \pre The behavior is undefined unless `0 <= *length`.
274 ///
275 /// \note Note that `length` is both an input and output parameter. See
276 /// @ref bdlb_stringviewutil for an identically named method having
277 /// similar semantics taking (and returning) `bsl::string_view`.
278 static void ltrim(char *string, int *length);
279
280 /// Append repeatedly to the specified `string` the optionally specified
281 /// `padChar` until `string` has the specified `length`. If `padChar`
282 /// is not specified the space (` `) character is appended. This
283 /// operation has no effect if `string.size() >= length`.
284 ///
285 /// \pre The behavior is undefined unless `0 <= length`.
286 static void pad(bsl::string *string, int length, char padChar = ' ');
287 static void pad(std::string *string, int length, char padChar = ' ');
288
289#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
290 /// Append repeatedly to the specified `string` the optionally specified
291 /// `padChar` until `string` has the specified `length`. If `padChar`
292 /// is not specified the space (` `) character is appended. This
293 /// operation has no effect if `string.size() >= length`.
294 static void pad(std::pmr::string *string,
295 std::pmr::string::size_type length,
296 char padChar = ' ');
297#endif
298
299 /// Remove all trailing whitespace characters from the specified
300 /// `string`. If `string` consists of only whitespace then it will be
301 /// empty (i.e., have 0 length) after this operation.
302 ///
303 /// \pre The behavior is undefined unless `string->size() <= INT_MAX` (if applicable). See
304 /// @ref bdlb_stringviewutil for an identically named method having
305 /// similar semantics taking (and returning) `bsl::string_view`.
306 static void rtrim(char *string);
307 static void rtrim(bsl::string *string);
308 static void rtrim(std::string *string);
309#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
310 static void rtrim(std::pmr::string *string);
311#endif
312
313 /// Determine the number of characters that the specified `string`
314 /// having the specified `length` would have if all trailing whitespace
315 /// characters were removed and load the result into `*length`. `string` is *not* modified.
316 ///
317 /// \pre The behavior is undefined unless `0 <= *length`.
318 ///
319 /// \note Note that `length` is both an input and output
320 /// parameter.
321 static void rtrim(const char *string, int *length);
322
323 /// Return the address providing non-modifiable access to the first
324 /// position in the specified `string` having `stringLen` characters at
325 /// which the specified `subString` having `subStringLen` characters is
326 /// found, or 0 if there is no such position. If `subStringLen` is 0,
327 /// `subString` may be null and `string` is returned.
328 ///
329 /// \pre The behavior is undefined unless `0 <= stringLen` and `0 <= subStringLen`. See
330 /// @ref bdlb_stringviewutil for an identically named method having
331 /// similar semantics taking (and returning) `bsl::string_view`.
332 static const char *strstr(const char *string,
333 int stringLen,
334 const char *subString,
335 int subStringLen);
336
337 /// Return the address providing non-modifiable access to the first
338 /// position in the specified `string` having `stringLen` characters at
339 /// which the specified `subString` having `subStringLen` characters is
340 /// found using case-insensitive comparison, or 0 if there is no such
341 /// position. If `subStringLen` is 0, `subString` may be null and `string` is returned.
342 ///
343 /// \pre The behavior is undefined unless
344 /// `0 <= stringLen` and `0 <= subStringLen`. See
345 /// @ref bdlb_stringviewutil for an identically named method having
346 /// similar semantics taking (and returning) `bsl::string_view`.
347 static const char *strstrCaseless(const char *string,
348 int stringLen,
349 const char *subString,
350 int subStringLen);
351
352 /// Return the address providing non-modifiable access to the last
353 /// position in the specified `string` having `stringLen` characters at
354 /// which the specified `subString` having `subStringLen` characters is
355 /// found, or 0 if there is no such position. If `subStringLen` is 0,
356 /// `subString` may be null and `string + stringLen` is returned.
357 ///
358 /// \pre The behavior is undefined unless `0 <= stringLen` and
359 /// `0 <= subStringLen`. See @ref bdlb_stringviewutil for an identically
360 /// named method having similar semantics taking (and returning)
361 /// `bsl::string_view`.
362 static const char *strrstr(const char *string,
363 int stringLen,
364 const char *subString,
365 int subStringLen);
366
367 /// Return the address providing non-modifiable access to the last
368 /// position in the specified `string` having `stringLen` characters at
369 /// which the specified `subString` having `subStringLen` characters is
370 /// found using case-insensitive comparison, or 0 if there is no such
371 /// position. If `subStringLen` is 0, `subString` may be null and `string + stringLen` is returned.
372 ///
373 /// \pre The behavior is undefined unless
374 /// `0 <= stringLen` and `0 <= subStringLen`. See
375 /// @ref bdlb_stringviewutil for an identically named method having
376 /// similar semantics taking (and returning) `bsl::string_view`.
377 static const char *strrstrCaseless(const char *string,
378 int stringLen,
379 const char *subString,
380 int subStringLen);
381
382 /// Return the minimum of the length of the specified `string` and the
383 /// specified `maximumLength`. If `maximumLength` is 0, `string` may be null and 0 is returned.
384 ///
385 /// \pre The behavior is undefined unless
386 /// `0 <= maximumLength`.
387 static int strnlen(const char *string, int maximumLength);
388
389 /// Copy into the specified `dstString` at most the specified leading
390 /// `dstLength` characters from the specified `srcString` having the
391 /// specified `srcLength`. If `srcLength < dstLength`, after
392 /// `srcString` is copied to `dstString` repeatedly append to
393 /// `dstString` the optionally specified `padChar` until the total
394 /// number of characters written to `dstString` is `dstLength`. If
395 /// `padChar` is not specified the space (` `) character is appended.
396 ///
397 /// \pre The behavior is undefined unless `0 <= dstLength` and
398 /// `0 <= srcLength`.
399 static void toFixedLength(char *dstString,
400 int dstLength,
401 const char *srcString,
402 int srcLength,
403 char padChar = ' ');
404
405 /// Replace all upper case characters in the specified `string` having
406 /// the optionally specified `length` with their lower-case equivalent.
407 ///
408 /// \pre The behavior is undefined unless `0 <= length` (if specified) and
409 /// `string->size() <= INT_MAX` (if applicable).
410 static void toLower(char *string);
411 static void toLower(char *string, int length);
412 static void toLower(bsl::string *string);
413 static void toLower(std::string *string);
414#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
415 static void toLower(std::pmr::string *string);
416#endif
417
418 /// Replace all lower case characters in the specified `string` having
419 /// the optionally specified `length` with their upper-case equivalent.
420 ///
421 /// \pre The behavior is undefined unless `0 <= length` (if specified) and
422 /// `string->size() <= INT_MAX` (if applicable).
423 static void toUpper(char *string);
424 static void toUpper(char *string, int length);
425 static void toUpper(bsl::string *string);
426 static void toUpper(std::string *string);
427#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
428 static void toUpper(std::pmr::string *string);
429#endif
430
431 /// Remove all leading and trailing whitespace characters from the
432 /// specified `string`. If `string` consists of only whitespace then it
433 /// will be empty (i.e., have 0 length) after this operation.
434 ///
435 /// \pre The behavior is undefined unless `string->size() <= INT_MAX` (if
436 /// applicable). See @ref bdlb_stringviewutil for an identically named
437 /// method having similar semantics taking (and returning)
438 /// `bsl::string_view`.
439 static void trim(char *string);
440 static void trim(bsl::string *string);
441 static void trim(std::string *string);
442#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
443 static void trim(std::pmr::string *string);
444#endif
445
446 /// Remove all leading and trailing whitespace characters from the
447 /// specified `string` having the specified `length`, and load into
448 /// `length` the number of characters in the resulting (trimmed) string.
449 /// If `string` consists of only whitespace then it will be empty (i.e.,
450 /// have 0 length) after this operation.
451 ///
452 /// \pre The behavior is undefined unless `0 <= *length`.
453 /// \note Note that `length` is both an input and
454 /// output parameter. See @ref bdlb_stringviewutil for an identically
455 /// named method having similar semantics taking (and returning)
456 /// `bsl::string_view`.
457 static void trim(char *string, int *length);
458
459 /// Skip leading and trailing whitespace characters in the string
460 /// indicated by the specified `*begin` and `*end` iterators by
461 /// appropriately advancing `*begin` and regressing `*end`. If the
462 /// indicated string is empty, or consists solely of whitespace
463 /// characters, `*begin` is unchanged and `*end` is regressed to
464 /// `*begin`. Otherwise, advance `*begin` to the first non-whitespace
465 /// character whose position is greater than or equal to `*begin` and
466 /// regress `*end` to one past the position of the last non-whitespace
467 /// character whose position is less than `*end`. The indicated string
468 /// need not be null-terminated and may contain embedded null ('\0') characters.
469 ///
470 /// \pre The behavior is undefined unless `*begin <= *end`.
471 ///
472 /// \note Note that since `*begin` and `*end` are iterators, `*end` refers to
473 /// the character one past the end of the subject string.
474 static void skipLeadingTrailing(const char **begin, const char **end);
475
476 /// Compare the specified `lhsString` and `rhsString` having the
477 /// optionally specified `lhsLength` and `rhsLength`, respectively, *as*
478 /// *if* the strings were converted to upper case before the comparison.
479 /// Return 1 if `lhsString` is lexically greater than `rhsString`, 0 if they are equal, and -1 otherwise.
480 ///
481 /// \pre The behavior is undefined unless
482 /// `0 <= lhsLength` and `0 <= rhsLength` (if specified), and
483 /// `lhsString.size() <= INT_MAX` and `rhsString.size() <= INT_MAX` (if
484 /// applicable). See @ref bdlb_stringviewutil for an identically named
485 /// method having the same semantics taking `bsl::string_view`.
486 static int upperCaseCmp(const char *lhsString, const char *rhsString);
487 static int upperCaseCmp(const char *lhsString,
488 const char *rhsString,
489 int rhsLength);
490 static int upperCaseCmp(const char *lhsString,
491 const bsl::string& rhsString);
492
493 static int upperCaseCmp(const char *lhsString,
494 int lhsLength,
495 const char *rhsString);
496 static int upperCaseCmp(const char *lhsString,
497 int lhsLength,
498 const char *rhsString,
499 int rhsLength);
500 static int upperCaseCmp(const char *lhsString,
501 int lhsLength,
502 const bsl::string& rhsString);
503 static int upperCaseCmp(const bsl::string& lhsString,
504 const char *rhsString);
505 static int upperCaseCmp(const bsl::string& lhsString,
506 const char *rhsString,
507 int rhsLength);
508 static int upperCaseCmp(const bsl::string& lhsString,
509 const bsl::string& rhsString);
510};
511
512// ============================================================================
513// INLINE DEFINITIONS
514// ============================================================================
515
516 // -------------
517 // struct String
518 // -------------
519
520// CLASS METHODS
521inline
522bool String::areEqualCaseless(const char *lhsString,
523 const bsl::string& rhsString)
524{
525 BSLS_ASSERT(lhsString);
526 BSLS_ASSERT(rhsString.size() <= INT_MAX);
527
528 return areEqualCaseless(lhsString,
529 &rhsString[0],
530 static_cast<int>(rhsString.size()));
531}
532
533inline
534bool String::areEqualCaseless(const char *lhsString,
535 int lhsLength,
536 const char *rhsString)
537{
538 BSLS_ASSERT(lhsString || 0 == lhsLength);
539 BSLS_ASSERT(0 <= lhsLength);
540 BSLS_ASSERT(rhsString);
541
542 return areEqualCaseless(rhsString, lhsString, lhsLength);
543}
544
545inline
546bool String::areEqualCaseless(const char *lhsString,
547 int lhsLength,
548 const bsl::string& rhsString)
549{
550 BSLS_ASSERT(lhsString || 0 == lhsLength);
551 BSLS_ASSERT(0 <= lhsLength);
552 BSLS_ASSERT(rhsString.size() <= INT_MAX);
553
554 return areEqualCaseless(lhsString,
555 lhsLength,
556 rhsString.data(),
557 static_cast<int>(rhsString.size()));
558}
559
560inline
561bool String::areEqualCaseless(const bsl::string& lhsString,
562 const char *rhsString)
563{
564 BSLS_ASSERT(lhsString.size() <= INT_MAX);
565 BSLS_ASSERT(rhsString);
566
567 return areEqualCaseless(rhsString,
568 lhsString.data(),
569 static_cast<int>(lhsString.size()));
570}
571
572inline
573bool String::areEqualCaseless(const bsl::string& lhsString,
574 const char *rhsString,
575 int rhsLength)
576{
577 BSLS_ASSERT(lhsString.size() <= INT_MAX);
578 BSLS_ASSERT(rhsString || 0 == rhsLength);
579 BSLS_ASSERT(0 <= rhsLength);
580
581 return areEqualCaseless(lhsString.data(),
582 static_cast<int>(lhsString.size()),
583 rhsString,
584 rhsLength);
585}
586
587inline
588bool String::areEqualCaseless(const bsl::string& lhsString,
589 const bsl::string& rhsString)
590{
591 BSLS_ASSERT(lhsString.size() <= INT_MAX);
592 BSLS_ASSERT(rhsString.size() <= INT_MAX);
593
594 return areEqualCaseless(lhsString.data(),
595 static_cast<int>(lhsString.size()),
596 rhsString.data(),
597 static_cast<int>(rhsString.size()));
598}
599
600inline
601char *String::copy(const char *string, bslma::Allocator *basicAllocator)
602{
603 BSLS_ASSERT(string);
604 BSLS_ASSERT(bsl::strlen(string) <= INT_MAX);
605 BSLS_ASSERT(basicAllocator);
606
607 return copy(string,
608 static_cast<int>(bsl::strlen(string)),
609 basicAllocator);
610}
611
612inline
613char *String::copy(const bsl::string& string,
614 bslma::Allocator *basicAllocator)
615{
616 BSLS_ASSERT(string.size() <= INT_MAX);
617 BSLS_ASSERT(basicAllocator);
618
619 return copy(string.data(),
620 static_cast<int>(string.size()),
621 basicAllocator);
622}
623
624inline
625int String::lowerCaseCmp(const char *lhsString,
626 const bsl::string& rhsString)
627{
628 BSLS_ASSERT(lhsString);
629 BSLS_ASSERT(rhsString.size() <= INT_MAX);
630
631 return lowerCaseCmp(lhsString,
632 &rhsString[0],
633 static_cast<int>(rhsString.size()));
634}
635
636inline
637int String::lowerCaseCmp(const char *lhsString,
638 int lhsLength,
639 const char *rhsString)
640{
641 BSLS_ASSERT(lhsString || 0 == lhsLength);
642 BSLS_ASSERT(0 <= lhsLength);
643 BSLS_ASSERT(rhsString);
644
645 return -lowerCaseCmp(rhsString, lhsString, lhsLength);
646}
647
648inline
649int String::lowerCaseCmp(const char *lhsString,
650 int lhsLength,
651 const bsl::string& rhsString)
652{
653 BSLS_ASSERT(lhsString || 0 == lhsLength);
654 BSLS_ASSERT(0 <= lhsLength);
655 BSLS_ASSERT(rhsString.size() <= INT_MAX);
656
657 return lowerCaseCmp(lhsString,
658 lhsLength,
659 rhsString.data(),
660 static_cast<int>(rhsString.size()));
661}
662
663inline
664int String::lowerCaseCmp(const bsl::string& lhsString,
665 const char *rhsString)
666{
667 BSLS_ASSERT(lhsString.size() <= INT_MAX);
668 BSLS_ASSERT(rhsString);
669
670 return -lowerCaseCmp(rhsString,
671 lhsString.data(),
672 static_cast<int>(lhsString.size()));
673}
674
675inline
676int String::lowerCaseCmp(const bsl::string& lhsString,
677 const char *rhsString,
678 int rhsLength)
679{
680 BSLS_ASSERT(lhsString.size() <= INT_MAX);
681 BSLS_ASSERT(rhsString || 0 == rhsLength);
682 BSLS_ASSERT(0 <= rhsLength);
683
684 return lowerCaseCmp(lhsString.data(),
685 static_cast<int>(lhsString.size()),
686 rhsString,
687 rhsLength);
688}
689
690inline
691int String::lowerCaseCmp(const bsl::string& lhsString,
692 const bsl::string& rhsString)
693{
694 BSLS_ASSERT(lhsString.size() <= INT_MAX);
695 BSLS_ASSERT(rhsString.size() <= INT_MAX);
696
697 return lowerCaseCmp(lhsString.data(),
698 static_cast<int>(lhsString.size()),
699 rhsString.data(),
700 static_cast<int>(rhsString.size()));
701}
702
703inline
704void String::ltrim(bsl::string *string)
705{
706 BSLS_ASSERT(string);
707 BSLS_ASSERT(string->size() <= INT_MAX);
708
709 int length = static_cast<int>(string->size());
710
711 ltrim(&(*string)[0], &length);
712 string->resize(length);
713}
714
715inline
716void String::ltrim(std::string *string)
717{
718 BSLS_ASSERT(string);
719 BSLS_ASSERT(string->size() <= INT_MAX);
720
721 int length = static_cast<int>(string->size());
722
723 ltrim(&(*string)[0], &length);
724 string->resize(length);
725}
726
727#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
728inline
729void String::ltrim(std::pmr::string *string)
730{
731 BSLS_ASSERT(string);
732 BSLS_ASSERT(string->size() <= INT_MAX);
733
734 int length = static_cast<int>(string->size());
735
736 ltrim(&(*string)[0], &length);
737 string->resize(length);
738}
739#endif
740
741inline
742void String::pad(bsl::string *string, int length, char padChar)
743{
744 BSLS_ASSERT(string);
745 BSLS_ASSERT(0 <= length);
746
747 if (string->size() < static_cast<bsl::size_t>(length)) {
748 string->resize(length, padChar);
749 }
750}
751
752inline
753void String::pad(std::string *string, int length, char padChar)
754{
755 BSLS_ASSERT(string);
756 BSLS_ASSERT(0 <= length);
757
758 if (string->size() < static_cast<bsl::size_t>(length)) {
759 string->resize(length, padChar);
760 }
761}
762
763#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
764inline
765void String::pad(std::pmr::string *string,
766 std::pmr::string::size_type length,
767 char padChar)
768{
769 BSLS_ASSERT(string);
770
771 if (string->size() < length) {
772 string->resize(length, padChar);
773 }
774}
775#endif
776
777inline
778void String::rtrim(bsl::string *string)
779{
780 BSLS_ASSERT(string);
781 BSLS_ASSERT(string->size() <= INT_MAX);
782
783 int length = static_cast<int>(string->size());
784
785 rtrim(&(*string)[0], &length);
786 string->resize(length);
787}
788
789inline
790void String::rtrim(std::string *string)
791{
792 BSLS_ASSERT(string);
793 BSLS_ASSERT(string->size() <= INT_MAX);
794
795 int length = static_cast<int>(string->size());
796
797 rtrim(&(*string)[0], &length);
798 string->resize(length);
799}
800
801#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
802inline
803void String::rtrim(std::pmr::string *string)
804{
805 BSLS_ASSERT(string);
806 BSLS_ASSERT(string->size() <= INT_MAX);
807
808 int length = static_cast<int>(string->size());
809
810 rtrim(&(*string)[0], &length);
811 string->resize(length);
812}
813#endif
814
815inline
816void String::toLower(bsl::string *string)
817{
818 BSLS_ASSERT(string);
819 BSLS_ASSERT(string->size() <= INT_MAX);
820
821 toLower(&(*string)[0], static_cast<int>(string->size()));
822}
823
824inline
825void String::toLower(std::string *string)
826{
827 BSLS_ASSERT(string);
828 BSLS_ASSERT(string->size() <= INT_MAX);
829
830 toLower(&(*string)[0], static_cast<int>(string->size()));
831}
832
833#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
834inline
835void String::toLower(std::pmr::string *string)
836{
837 BSLS_ASSERT(string);
838 BSLS_ASSERT(string->size() <= INT_MAX);
839
840 toLower(&(*string)[0], static_cast<int>(string->size()));
841}
842#endif
843
844inline
845void String::toUpper(bsl::string *string)
846{
847 BSLS_ASSERT(string);
848 BSLS_ASSERT(string->size() <= INT_MAX);
849
850 toUpper(&(*string)[0], static_cast<int>(string->size()));
851}
852
853inline
854void String::toUpper(std::string *string)
855{
856 BSLS_ASSERT(string);
857 BSLS_ASSERT(string->size() <= INT_MAX);
858
859 toUpper(&(*string)[0], static_cast<int>(string->size()));
860}
861
862#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
863inline
864void String::toUpper(std::pmr::string *string)
865{
866 BSLS_ASSERT(string);
867 BSLS_ASSERT(string->size() <= INT_MAX);
868
869 toUpper(&(*string)[0], static_cast<int>(string->size()));
870}
871#endif
872
873inline
874void String::trim(char *string, int *length)
875{
876 BSLS_ASSERT(string);
877 BSLS_ASSERT(length);
878 BSLS_ASSERT(0 <= *length);
879
880 rtrim(string, length);
881 ltrim(string, length);
882}
883
884inline
885void String::trim(bsl::string *string)
886{
887 BSLS_ASSERT(string);
888 BSLS_ASSERT(string->size() <= INT_MAX);
889
890 int length = static_cast<int>(string->size());
891
892 rtrim(&(*string)[0], &length);
893 ltrim(&(*string)[0], &length);
894 string->resize(length);
895}
896
897inline
898void String::trim(std::string *string)
899{
900 BSLS_ASSERT(string);
901 BSLS_ASSERT(string->size() <= INT_MAX);
902
903 int length = static_cast<int>(string->size());
904
905 rtrim(&(*string)[0], &length);
906 ltrim(&(*string)[0], &length);
907 string->resize(length);
908}
909
910#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR_STRING
911inline
912void String::trim(std::pmr::string *string)
913{
914 BSLS_ASSERT(string);
915 BSLS_ASSERT(string->size() <= INT_MAX);
916
917 int length = static_cast<int>(string->size());
918
919 rtrim(&(*string)[0], &length);
920 ltrim(&(*string)[0], &length);
921 string->resize(length);
922}
923#endif
924
925inline
926int String::upperCaseCmp(const char *lhsString,
927 const bsl::string& rhsString)
928{
929 BSLS_ASSERT(lhsString);
930 BSLS_ASSERT(rhsString.size() <= INT_MAX);
931
932 return upperCaseCmp(lhsString,
933 &rhsString[0],
934 static_cast<int>(rhsString.size()));
935}
936
937inline
938int String::upperCaseCmp(const char *lhsString,
939 int lhsLength,
940 const char *rhsString)
941{
942 BSLS_ASSERT(lhsString || 0 == lhsLength);
943 BSLS_ASSERT(0 <= lhsLength);
944 BSLS_ASSERT(rhsString);
945
946 return -upperCaseCmp(rhsString, lhsString, lhsLength);
947}
948
949inline
950int String::upperCaseCmp(const char *lhsString,
951 int lhsLength,
952 const bsl::string& rhsString)
953{
954 BSLS_ASSERT(lhsString || 0 == lhsLength);
955 BSLS_ASSERT(0 <= lhsLength);
956 BSLS_ASSERT(rhsString.size() <= INT_MAX);
957
958 return upperCaseCmp(lhsString,
959 lhsLength,
960 rhsString.data(),
961 static_cast<int>(rhsString.size()));
962}
963
964inline
965int String::upperCaseCmp(const bsl::string& lhsString,
966 const char *rhsString)
967{
968 BSLS_ASSERT(lhsString.size() <= INT_MAX);
969 BSLS_ASSERT(rhsString);
970
971 return -upperCaseCmp(rhsString,
972 lhsString.data(),
973 static_cast<int>(lhsString.size()));
974}
975
976inline
977int String::upperCaseCmp(const bsl::string& lhsString,
978 const char *rhsString,
979 int rhsLength)
980{
981 BSLS_ASSERT(lhsString.size() <= INT_MAX);
982 BSLS_ASSERT(rhsString || 0 == rhsLength);
983 BSLS_ASSERT(0 <= rhsLength);
984
985 return upperCaseCmp(lhsString.data(),
986 static_cast<int>(lhsString.size()),
987 rhsString,
988 rhsLength);
989}
990
991inline
992int String::upperCaseCmp(const bsl::string& lhsString,
993 const bsl::string& rhsString)
994{
995 BSLS_ASSERT(lhsString.size() <= INT_MAX);
996 BSLS_ASSERT(rhsString.size() <= INT_MAX);
997
998 return upperCaseCmp(lhsString.data(),
999 static_cast<int>(lhsString.size()),
1000 rhsString.data(),
1001 static_cast<int>(rhsString.size()));
1002}
1003
1004} // close package namespace
1005
1006
1007#endif
1008
1009// ----------------------------------------------------------------------------
1010// Copyright 2015 Bloomberg Finance L.P.
1011//
1012// Licensed under the Apache License, Version 2.0 (the "License");
1013// you may not use this file except in compliance with the License.
1014// You may obtain a copy of the License at
1015//
1016// http://www.apache.org/licenses/LICENSE-2.0
1017//
1018// Unless required by applicable law or agreed to in writing, software
1019// distributed under the License is distributed on an "AS IS" BASIS,
1020// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1021// See the License for the specific language governing permissions and
1022// limitations under the License.
1023// ----------------------------- END-OF-FILE ----------------------------------
1024
1025/** @} */
1026/** @} */
1027/** @} */
bslma_allocator.h
bsls_assert.h
bsls_ident.h
bsls_libraryfeatures.h
bsls_review.h
bsl::basic_string
Definition bslstl_string.h:1252
bsl::basic_string::size
size_type size() const BSLS_KEYWORD_NOEXCEPT
Definition bslstl_string.h:7292
bsl::basic_string::data
CHAR_TYPE * data() BSLS_KEYWORD_NOEXCEPT
Definition bslstl_string.h:7177
bslma::Allocator
Definition bslma_allocator.h:545
BSLS_ASSERT
#define BSLS_ASSERT(X)
Definition bsls_assert.h:1976
BSLS_IDENT
#define BSLS_IDENT(str)
BSLS_IDENT() - insert string into .comment binary segment (if supported)
Definition bsls_ident.h:238
bdlb
Definition bdlb_algorithmworkaroundutil.h:74
bdlb::String
Definition bdlb_string.h:147
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:601
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:742
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)