donner::RcStringOrRef Class Reference

An in-transit type that can hold either an RcString or std::string_view, to enable transferring the RcString reference or also accepting a non-owning std::string_view from API surfaces. More...

#include "donner/base/RcStringOrRef.h"

Public Types
using	iterator = char*
	String iterator.
using	const_iterator = const char*
	Const string iterator.

Public Member Functions
constexpr	RcStringOrRef ()=default
	Create an empty string.
	~RcStringOrRef ()=default
	Destructor.
constexpr	RcStringOrRef (std::string_view value UTILS_LIFETIME_BOUND)
	Constructs a new RcStringOrRef containing a non-owning std::string_view.
constexpr	RcStringOrRef (const RcString &value)
	Constructs a new RcStringOrRef containing a transferrable RcString.
constexpr	RcStringOrRef (const char *value UTILS_LIFETIME_BOUND, size_t len=npos)
	Constructs a new RcStringOrRef object from a C-style string reference and optional length.
constexpr	RcStringOrRef (const RcStringOrRef &other)=default
	Copy constructor.
constexpr	RcStringOrRef (RcStringOrRef &&other) noexcept
	Move constructor.
RcStringOrRef &	operator= (const RcStringOrRef &other)=default
	Copy assignment operator.
RcStringOrRef &	operator= (RcStringOrRef &&other) noexcept
	Move assignment operator.
RcStringOrRef &	operator= (const char *value)
	Assignment operator from a C-style string.
RcStringOrRef &	operator= (std::string_view value)
	Assignment operator from a std::string_view.
RcStringOrRef &	operator= (const RcString &value)
	Assignment operator from an RcString.
	operator std::string_view () const UTILS_LIFETIME_BOUND
	Cast operator to std::string_view. The returned view aliases this object's storage, so it must not outlive the RcStringOrRef. Annotated with UTILS_LIFETIME_BOUND so Clang's -Wdangling and clang-tidy flag binding the view to a temporary RcStringOrRef (see AGENTS.md "Non-owning view return types").
	operator RcString () const
	Cast operator to RcString. If the internal storage is a long RcString, it will increment the refcount without copying.
const char *	data () const UTILS_LIFETIME_BOUND
bool	empty () const
size_t	size () const
std::string	str () const
RcStringOrRef	substr (size_t pos, size_t len=npos) const
	Returns a substring of the string.
const_iterator	begin () const noexcept UTILS_LIFETIME_BOUND
	Begin iterator.
const_iterator	end () const noexcept UTILS_LIFETIME_BOUND
	End iterator.
const_iterator	cbegin () const noexcept UTILS_LIFETIME_BOUND
	Begin iterator.
const_iterator	cend () const noexcept UTILS_LIFETIME_BOUND
	End iterator.
bool	equalsLowercase (std::string_view lowercaseOther) const
	Returns true if the string equals another all-lowercase string, with a case insensitive comparison.
bool	equalsIgnoreCase (std::string_view other) const
	Returns true if the string equals another string with a case-insensitive comparison.

Static Public Attributes
static constexpr size_t	npos = std::string_view::npos
	Sentinel value for the maximum value of size_t, used to indicate when the size is not known.

Friends
std::ostream &	operator<< (std::ostream &os, const RcStringOrRef &self)
	Ostream output operator.
Comparison
auto	operator<=> (const RcStringOrRef &lhs, const RcStringOrRef &rhs)
	Spaceship equality operator to another RcStringOrRef.
template<StringLike StringT>
auto	operator<=> (const RcStringOrRef &lhs, const StringT &rhs)
	Spaceship equality operator to a StringLike type such as std::string_view or RcString.
template<StringLike StringT>
auto	operator<=> (const StringT &lhs, const RcStringOrRef &rhs)
	Spaceship equality operator to a StringLike type such as std::string_view or RcString.
bool	operator== (const RcStringOrRef &lhs, const RcStringOrRef &rhs)
	Equality operator to another RcString.
template<StringLike StringT>
bool	operator== (const RcStringOrRef &lhs, const StringT &rhs)
	Equality operator to a StringLike type such as std::string_view or RcString.
template<StringLike StringT>
bool	operator== (const StringT &lhs, const RcStringOrRef &rhs)
	Reversed equality operator to a StringLike type such as std::string_view or RcString.
Concatenation
std::string	operator+ (const RcStringOrRef &lhs, const RcStringOrRef &rhs)
	Concatenation operator with another RcStringOrRef.
std::string	operator+ (const RcStringOrRef &lhs, const char *rhs)
	Concatenation operator with a C-style string.
std::string	operator+ (const RcStringOrRef &lhs, std::string_view rhs)
	Concatenation operator with a std::string_view.
std::string	operator+ (std::string_view lhs, const RcStringOrRef &rhs)
	Reversed concatenation operator with a C-style string.
std::string	operator+ (const char *lhs, const RcStringOrRef &rhs)
	Reversed concatenation operator with a std::string_view.

Detailed Description

An in-transit type that can hold either an RcString or std::string_view, to enable transferring the RcString reference or also accepting a non-owning std::string_view from API surfaces.

This can be used either for function arguments, or as a key value for a std::map-like type.

As a function:

void setString(const RcStringOrRef& param) {
  // Addrefs if an RcString was passed in
 RcString storedStr = param;
 // ...
}
 
 
// Passing either an RcString or std::string_view works.
setString("test");
setString(RcString("will addref if this is larger than the small string optimization");

As a map key:

std::map<RcStringOrRef, int> myMap;
myMap[RcString("key")] = 1; // Danger! The key lifetime must remain valid.
 
// Lookups are possible with a `std::string_view` or string literal.
auto it = myMap.find("key");
const bool found = it != myMap.end();
assert(found);

Constructor & Destructor Documentation

RcStringOrRef() [1/3]

donner::RcStringOrRef::RcStringOrRef ( std::string_view value UTILS_LIFETIME_BOUND )

inlineconstexpr

Constructs a new RcStringOrRef containing a non-owning std::string_view.

Parameters

value

Input string to reference.

RcStringOrRef() [2/3]

donner::RcStringOrRef::RcStringOrRef ( const RcString & value )

inlineconstexpr

Constructs a new RcStringOrRef containing a transferrable RcString.

Parameters

value

Input string to own.

RcStringOrRef() [3/3]

donner::RcStringOrRef::RcStringOrRef ( const char *value UTILS_LIFETIME_BOUND, size_t len = npos )

inlineconstexpr

Constructs a new RcStringOrRef object from a C-style string reference and optional length.

Parameters

value	C-style string.
len	Length of the string, or npos to automatically measure, which requires that data is null-terminated.

Member Function Documentation

data()

const char * donner::RcStringOrRef::data ( ) const

inline

Returns

a pointer to the string data. The pointer aliases this object's storage and must not outlive the RcStringOrRef (annotated UTILS_LIFETIME_BOUND).

empty()

bool donner::RcStringOrRef::empty ( ) const

inline

Returns

if the string is empty.

equalsIgnoreCase()

bool donner::RcStringOrRef::equalsIgnoreCase ( std::string_view other ) const

inline

Returns true if the string equals another string with a case-insensitive comparison.

Parameters

other

string to compare to.

Returns

true If the strings are equal (case insensitive).

equalsLowercase()

bool donner::RcStringOrRef::equalsLowercase ( std::string_view lowercaseOther ) const

inline

Returns true if the string equals another all-lowercase string, with a case insensitive comparison.

Example:

RcString("EXAMPLe").equalsLowercase("example"); // true

Parameters

lowercaseOther

string to compare to, must be lowercase.

Returns

true If the strings are equal (case insensitive).

size()

size_t donner::RcStringOrRef::size ( ) const

inline

Returns

the length of the string.

str()

std::string donner::RcStringOrRef::str ( ) const

inline

Returns

the string as a std::string.

substr()

RcStringOrRef donner::RcStringOrRef::substr ( size_t pos, size_t len = npos ) const

inline

Returns a substring of the string.

Parameters

pos	The position to start the substring.
len	The length of the substring, or RcStringOrRef::npos to return the whole string.

Returns

An RcStringOrRef containing the substring.

---

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

• donner/base/RcStringOrRef.h