ICU 74.1 74.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:
icu::UMemory

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
stra 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
stra 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
pnullptr
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 ( 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();
};
const char * data() const
Returns the string pointer.
Definition: stringpiece.h:189
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
strthe 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
offseta const char * pointer (need not be terminated)
lenthe 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
stra const char8_t * pointer (need not be terminated)
lenthe 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
xthe other StringPiece
posstart 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
xthe other StringPiece
posstart position in x; must be non-negative and <= x.length().
lenlength 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
otherThe 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
needleThe string for which to search.
offsetWhere 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
nprefix 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
nsuffix 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
stra 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
xdatapointer the new string data. Need not be nul terminated.
lenthe 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
stra 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
xdatapointer the new string data. Need not be NUL-terminated.
lenthe 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
posstart position; must be non-negative and <= length().
lenlength 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: