ICU 69.1: icu::StringPiece Class Reference

ICU 69.1 69.1

Public Member Functions | Static Public Attributes
icu::StringPiece Class Reference

A string-like object that points to a sized piece of memory. More...

`#include <stringpiece.h>`

Inheritance diagram for icu::StringPiece:

## Public Member Functions
| StringPiece ()
| Default constructor, creates an empty StringPiece. More...
| StringPiece (const char *str)
| Constructs from a NUL-terminated const char * pointer. More...
| StringPiece (const char8_t *str)
| Constructs from a NUL-terminated const char8_t * pointer. More...
| StringPiece (std::nullptr_t p)
| Constructs an empty StringPiece. More...
| StringPiece (const std::string &str)
| Constructs from a std::string. More...
| StringPiece (const std::u8string &str)
| Constructs from a std::u8string. More...
template<typename T , typename = typename std::enable_if< (std::is_same<decltype(T().data()), const char*>::value ) && std::is_same<decltype(T().size()), size_t>::value>::type>
| StringPiece (T str)
| Constructs from some other implementation of a string piece class, from any C++ record type that has these two methods: More...
| StringPiece (const char *offset, int32_t len)
| Constructs from a const char * pointer and a specified length. More...
| StringPiece (const char8_t *str, int32_t len)
| Constructs from a const char8_t * pointer and a specified length. More...
| StringPiece (const StringPiece &x, int32_t pos)
| Substring of another StringPiece. More...
| StringPiece (const StringPiece &x, int32_t pos, int32_t len)
| Substring of another StringPiece. More...
const char * | data () const
| Returns the string pointer. More...
int32_t | size () const
| Returns the string length. More...
int32_t | length () const
| Returns the string length. More...
UBool | empty () const
| Returns whether the string is empty. More...
void | clear ()
| Sets to an empty string. More...
void | set (const char *xdata, int32_t len)
| Reset the stringpiece to refer to new data. More...
void | set (const char *str)
| Reset the stringpiece to refer to new data. More...
void | set (const char8_t *xdata, int32_t len)
| Resets the stringpiece to refer to new data. More...
void | set (const char8_t *str)
| Resets the stringpiece to refer to new data. More...
void | remove_prefix (int32_t n)
| Removes the first n string units. More...
void | remove_suffix (int32_t n)
| Removes the last n string units. More...
int32_t | find (StringPiece needle, int32_t offset)
| Searches the StringPiece for the given search string (needle);. More...
int32_t | compare (StringPiece other)
| Compares this StringPiece with the other StringPiece, with semantics similar to std::string::compare(). More...
StringPiece | substr (int32_t pos, int32_t len=npos) const
| Returns a substring of this StringPiece. More...

## Static Public Attributes
static const int32_t | npos
| Maximum integer, used as a default value for substring methods. More...

## Detailed Description

A string-like object that points to a sized piece of memory.

We provide non-explicit singleton constructors so users can pass in a "const char*" or a "string" wherever a "StringPiece" is expected.

Functions or methods may use StringPiece parameters to accept either a "const char*" or a "string" value that will be implicitly converted to a StringPiece.

Systematic usage of StringPiece is encouraged as it will reduce unnecessary conversions from "const char*" to "string" and back again.

Stable:
  ICU 4.2

Definition at line 60 of file stringpiece.h.

## Constructor & Destructor Documentation

## ◆ StringPiece() [1/11]

icu::StringPiece::StringPiece | ( |  | ) |
| inline

Default constructor, creates an empty StringPiece.

Stable:
  ICU 4.2

Definition at line 70 of file stringpiece.h.

## ◆ StringPiece() [2/11]

icu::StringPiece::StringPiece | ( | const char * | str | ) |

Constructs from a NUL-terminated const char * pointer.

Parameters

  str | a NUL-terminated const char * pointer

Stable:
  ICU 4.2

## ◆ StringPiece() [3/11]

icu::StringPiece::StringPiece | ( | const char8_t * | str | ) |
| inline

Constructs from a NUL-terminated const char8_t * pointer.

Parameters

  str | a NUL-terminated const char8_t * pointer

Stable:
  ICU 67

Definition at line 84 of file stringpiece.h.

## ◆ StringPiece() [4/11]

icu::StringPiece::StringPiece | ( | std::nullptr_t | p | ) |
| inline

Constructs an empty StringPiece.

Needed for type disambiguation from multiple other overloads.

Parameters

  p | nullptr

Stable:
  ICU 67

Definition at line 92 of file stringpiece.h.

## ◆ StringPiece() [5/11]

icu::StringPiece::StringPiece | ( | const std::string & | str | ) |
| inline

Constructs from a std::string.

Stable:
  ICU 4.2

Definition at line 98 of file stringpiece.h.

## ◆ StringPiece() [6/11]

icu::StringPiece::StringPiece | ( | const std::u8string & | str | ) |
| inline

Constructs from a std::u8string.

Stable:
  ICU 67

Definition at line 105 of file stringpiece.h.

## ◆ StringPiece() [7/11]

template<typename T , typename = typename std::enable_if< (std::is_same<decltype(T().data()), const char*>::value ) && std::is_same<decltype(T().size()), size_t>::value>::type>

icu::StringPiece::StringPiece | ( | T | str | ) |
| inline

Constructs from some other implementation of a string piece class, from any C++ record type that has these two methods:

struct OtherStringPieceClass {
const char* data(); // or const char8_t*
size_t size();
};
icu::StringPiece::data
const char * data() const
Returns the string pointer.
Definition: stringpiece.h:189
icu::StringPiece::size
int32_t size() const
Returns the string length.
Definition: stringpiece.h:195

The other string piece class will typically be std::string_view from C++17 or absl::string_view from Abseil.

Starting with C++20, data() may also return a const char8_t* pointer, as from std::u8string_view.

Parameters

  str | the other string piece

Stable:
  ICU 65

Definition at line 140 of file stringpiece.h.

## ◆ StringPiece() [8/11]

icu::StringPiece::StringPiece | ( | const char * | offset,
|  | int32_t | len
| ) |  |
| inline

Constructs from a const char * pointer and a specified length.

Parameters

  offset | a const char * pointer (need not be terminated)
  len | the length of the string; must be non-negative

Stable:
  ICU 4.2

Definition at line 150 of file stringpiece.h.

## ◆ StringPiece() [9/11]

icu::StringPiece::StringPiece | ( | const char8_t * | str,
|  | int32_t | len
| ) |  |
| inline

Constructs from a const char8_t * pointer and a specified length.

Parameters

  str | a const char8_t * pointer (need not be terminated)
  len | the length of the string; must be non-negative

Stable:
  ICU 67

Definition at line 158 of file stringpiece.h.

## ◆ StringPiece() [10/11]

icu::StringPiece::StringPiece | ( | const StringPiece & | x,
|  | int32_t | pos
| ) |  |

Substring of another StringPiece.

Parameters

  x | the other StringPiece
  pos | start position in x; must be non-negative and <= x.length().

Stable:
  ICU 4.2

## ◆ StringPiece() [11/11]

icu::StringPiece::StringPiece | ( | const StringPiece & | x,
|  | int32_t | pos,
|  | int32_t | len
| ) |  |

Substring of another StringPiece.

Parameters

  x | the other StringPiece
  pos | start position in x; must be non-negative and <= x.length().
  len | length of the substring; must be non-negative and will be pinned to at most x.length() - pos.

Stable:
  ICU 4.2

## Member Function Documentation

## ◆ clear()

void icu::StringPiece::clear | ( |  | ) |
| inline

Sets to an empty string.

Stable:
  ICU 4.2

Definition at line 213 of file stringpiece.h.

## ◆ compare()

int32_t icu::StringPiece::compare | ( | StringPiece | other | ) |

Compares this StringPiece with the other StringPiece, with semantics similar to std::string::compare().

Parameters

  other | The string to compare to.

Returns
  below zero if this < other; above zero if this > other; 0 if this == other.

Stable:
  ICU 67

## ◆ data()

const char* icu::StringPiece::data | ( |  | ) | const
| inline

Returns the string pointer.

May be nullptr if it is empty.

data() may return a pointer to a buffer with embedded NULs, and the returned buffer may or may not be null terminated. Therefore it is typically a mistake to pass data() to a routine that expects a NUL terminated string.

Returns
  the string pointer

Stable:
  ICU 4.2

Definition at line 189 of file stringpiece.h.

## ◆ empty()

UBool icu::StringPiece::empty | ( |  | ) | const
| inline

Returns whether the string is empty.

Returns
  true if the string is empty

Stable:
  ICU 4.2

Definition at line 207 of file stringpiece.h.

## ◆ find()

int32_t icu::StringPiece::find | ( | StringPiece | needle,
|  | int32_t | offset
| ) |  |

Searches the StringPiece for the given search string (needle);.

Parameters

  needle | The string for which to search.
  offset | Where to start searching within this string (haystack).

Returns
  The offset of needle in haystack, or -1 if not found.

Stable:
  ICU 67

## ◆ length()

int32_t icu::StringPiece::length | ( | void |  | ) | const
| inline

Returns the string length.

Same as size().

Returns
  the string length

Stable:
  ICU 4.2

Definition at line 201 of file stringpiece.h.

## ◆ remove_prefix()

void icu::StringPiece::remove_prefix | ( | int32_t | n | ) |
| inline

Removes the first n string units.

Parameters

  n | prefix length, must be non-negative and <=length()

Stable:
  ICU 4.2

Definition at line 256 of file stringpiece.h.

## ◆ remove_suffix()

void icu::StringPiece::remove_suffix | ( | int32_t | n | ) |
| inline

Removes the last n string units.

Parameters

  n | suffix length, must be non-negative and <=length()

Stable:
  ICU 4.2

Definition at line 271 of file stringpiece.h.

## ◆ set() [1/4]

void icu::StringPiece::set | ( | const char * | str | ) |

Reset the stringpiece to refer to new data.

Parameters

  str | a pointer to a NUL-terminated string.

Stable:
  ICU 4.8

## ◆ set() [2/4]

void icu::StringPiece::set | ( | const char * | xdata,
|  | int32_t | len
| ) |  |
| inline

Reset the stringpiece to refer to new data.

Parameters

  xdata | pointer the new string data. Need not be nul terminated.
  len | the length of the new data

Stable:
  ICU 4.8

Definition at line 221 of file stringpiece.h.

## ◆ set() [3/4]

void icu::StringPiece::set | ( | const char8_t * | str | ) |
| inline

Resets the stringpiece to refer to new data.

Parameters

  str | a pointer to a NUL-terminated string.

Stable:
  ICU 67

Definition at line 246 of file stringpiece.h.

## ◆ set() [4/4]

void icu::StringPiece::set | ( | const char8_t * | xdata,
|  | int32_t | len
| ) |  |
| inline

Resets the stringpiece to refer to new data.

Parameters

  xdata | pointer the new string data. Need not be NUL-terminated.
  len | the length of the new data

Stable:
  ICU 67

Definition at line 237 of file stringpiece.h.

## ◆ size()

int32_t icu::StringPiece::size | ( |  | ) | const
| inline

Returns the string length.

Same as length().

Returns
  the string length

Stable:
  ICU 4.2

Definition at line 195 of file stringpiece.h.

## ◆ substr()

StringPiece icu::StringPiece::substr | ( | int32_t | pos,
|  | int32_t | len = `npos`
| ) |  | const
| inline

Returns a substring of this StringPiece.

Parameters

  pos | start position; must be non-negative and <= length().
  len | length of the substring; must be non-negative and will be pinned to at most length() - pos.

Returns
  the substring StringPiece

Stable:
  ICU 4.2

Definition at line 313 of file stringpiece.h.

## Field Documentation

## ◆ npos

const int32_t icu::StringPiece::npos
| static

Maximum integer, used as a default value for substring methods.

Stable:
  ICU 4.2

Definition at line 303 of file stringpiece.h.

The documentation for this class was generated from the following file:

- stringpiece.h