RStringUKey#

Fully qualified name: carb::RStringUKey

Defined in carb/RString.h

class RStringUKey : public carb::detail::RStringTraits<true, detail::RStringKeyBase>#

A case-insensitive registered string key.

See RString for high-level information about the registered string system.

RStringUKey is formed by appending a numeric component to an “un-cased” (i.e. case-insensitive) registered string. This numeric component can be used as a unique instance identifier alongside the registered string. Additionally, the RStringUKey::toString() function will append a non-zero numeric component following an underscore.

Public Functions

constexpr RStringUKey() noexcept#

Default constructor.

isEmpty() will report true and getNumber() will return 0.

constexpr RStringUKey(
eRString staticString,
int32_t number = 0,
) noexcept#

Initializes this registered string to one of the static pre-defined registered strings.

Parameters:

  • staticString – The pre-defined registered string to use.

  • number – The number that will be returned by getNumber().

RStringUKey(const char *str, RStringOp op = RStringOp::eRegister)#

Finds or registers a new case-insensitive string.

Note

The casing of the string actually used may be different than str when reported by c_str() or toString().

Parameters:

  • str – The string to find or register.

  • op – The operation to perform. If directed to RStringOp::eFindExisting and the string has not been previously registered, *this is initialized as if with the default constructor.

RStringUKey(
int32_t number,
const char *str,
RStringOp op = RStringOp::eRegister,
)#

Finds or registers a new string with a given number component.

Parameters:

  • number – The number that will be returned by getNumber().

  • str – The string to find or register.

  • op – The operation to perform. If directed to RStringOp::eFindExisting and the string has not been previously registered, *this is initialized as if with the default constructor.

explicit RStringUKey(
const char *str,
size_t len,
RStringOp op = RStringOp::eRegister,
)#

Finds or registers a new counted case-insensitive string.

Note

While generally not recommended, passing len allows the given string to contain embedded NUL (‘\0’) characters.

Note

The casing of the string actually used may be different than str when reported by c_str() or toString().

Parameters:

  • str – The string to find or register.

  • len – The number of characters of str to include.

  • op – The operation to perform. If directed to RStringOp::eFindExisting and the string has not been previously registered, *this is initialized as if with the default constructor.

explicit RStringUKey(
int32_t number,
const char *str,
size_t len,
RStringOp op = RStringOp::eRegister,
)#

Finds or registers a new counted case-insensitive string with a given number component.

Note

While generally not recommended, passing len allows the given string to contain embedded NUL (‘\0’) characters.

Note

The casing of the string actually used may be different than str when reported by c_str() or toString().

Parameters:

  • number – The number that will be returned by getNumber().

  • str – The string to find or register.

  • len – The number of characters of str to include.

  • op – The operation to perform. If directed to RStringOp::eFindExisting and the string has not been previously registered, *this is initialized as if with the default constructor.

explicit RStringUKey(
const std::string &str,
RStringOp op = RStringOp::eRegister,
)#

Finds or registers a new case-insensitive std::string.

Note

If str contains embedded NUL (‘\0’) characters, the RString will contain the embedded NUL characters as well.

Note

The casing of the string actually used may be different than str when reported by c_str() or toString().

Parameters:

  • str – The std::string to find or register.

  • op – The operation to perform. If directed to RStringOp::eFindExisting and the string has not been previously registered, *this is initialized as if with the default constructor.

explicit RStringUKey(
int32_t number,
const std::string &str,
RStringOp op = RStringOp::eRegister,
)#

Finds or registers a new case-insensitive std::string with a number component.

Note

If str contains embedded NUL (‘\0’) characters, the RString will contain the embedded NUL characters as well.

Note

The casing of the string actually used may be different than str when reported by c_str() or toString().

Parameters:

  • number – The number that will be returned by getNumber().

  • str – The std::string to find or register.

  • op – The operation to perform. If directed to RStringOp::eFindExisting and the string has not been previously registered, *this is initialized as if with the default constructor.

RStringUKey(const RStringU &str, int32_t number = 0)#

Appends a number component to a registered string to form a key.

Parameters:

  • str – The registered string to decorate.

  • number – The number that will be returned by getNumber().

explicit RStringUKey(const RStringKey &other)#

Converts a registered string key into an “un-cased” (i.e.

case-insensitive) registered string key.

Parameters:

other – The RStringKey to convert. The number component is maintained.

RStringUKey toUncased() const noexcept#

Returns a copy of this registered string key.

Note

This function exists for compatibility with the RStringKey interface.

Returns:

*this since this string is already “un-cased” (i.e. case-insensitive). The number component will be the same as the number for *this.

RStringU truncate() const noexcept#

Returns a registered string without the number component.

Returns:

A registered string that matches *this without a number component.

bool operator==(const RStringUKey &other) const noexcept#

Equality comparison between this registered string key and another.

Note

A case-insensitive compare is performed.

Parameters:

other – Another registered string.

Returns:

true if *this and other represent the same registered string and have matching number components; false otherwise.

bool operator!=(const RStringUKey &other) const noexcept#

Inequality comparison between this registered string key and another.

Note

A case-insensitive compare is performed.

Parameters:

other – Another registered string.

Returns:

false if *this and other represent the same registered string and have matching number components; true otherwise.

bool owner_before(const RStringUKey &other) const noexcept#

Checks whether this registered string key is stably (but not lexicographically) ordered before another registered string.

The number component is also compared and keys with a lower number component will be ordered before.

This ordering is to make registered strings usable as keys in ordered associative containers in O(1) time.

Note

This is NOT a lexicographical comparison; for that use one of the compare() functions. To reduce ambiguity between a strict ordering and lexicographical comparison there is no operator< function for this string class. While a lexicographical comparison would be O(n), this comparison is O(1).

Parameters:

other – Another registered string.

Returns:

true if *this should be ordered-before other; false otherwise.

std::string toString() const#

Returns a string containing the registered string, and if getNumber() is not zero, the number appended.

Example: RStringUKey(eRString::RS_carb, 1).toString() would produce “carb_1”.

Returns:

A string containing the registered string. If getNumber() is non-zero, an underscore and the number are appended.

int32_t getNumber() const noexcept#

Returns the number component of this key.

Returns:

The number component previously specified in the constructor or with setNumber() or via number().

void setNumber(int32_t num) noexcept#

Sets the number component of this key.

Parameters:

num – The new number component.

int32_t &number() noexcept#

Direct access to the number component for manipulation or atomic operations via atomic_ref.

Returns:

A reference to the number component.

bool isValid() const noexcept#

Checks to see if this registered string has been corrupted.

Note

It is not possible for this registered string to become corrupted through normal use of the API. It could be caused by bad casts or use-after-free.

Returns:

true if *this represents a valid registered string; false if *this is corrupted.

constexpr bool isEmpty() const noexcept#

Checks to see if this registered string represents the “” (empty) value.

Returns:

true if *this is default-initialized or initialized to eRString::Empty; false otherwise.

constexpr bool isUncased() const noexcept#

Checks to see if this registered string represents an “un-cased” (i.e.

case-insensitive) registered string.

Returns:

true if *this is “un-cased” (i.e. case-insensitive); false if case-sensitive.

constexpr uint32_t getStringId() const noexcept#

Returns the registered string ID.

This ID is only useful for debugging purposes and should not be used for comparisons.

Returns:

The string ID for this registered string.

size_t getHash() const#

Returns the hash value as by carb::hashString(this->c_str()).

Note

This value is computed once for a registered string and cached, so this operation is generally very fast.

Returns:

The hash value as computed by carb::hashString(this->c_str()).

size_t getUncasedHash() const noexcept#

Returns the hash value as by carb::hashLowercaseString(this->c_str()).

Note

This value is pre-computed for registered strings and cached, so this operation is always O(1).

Returns:

The hash value as computed by carb::hashLowercaseString(this->c_str()).

const char *c_str() const noexcept#

Resolves this registered string to a C-style NUL-terminated string.

Note

This operation is O(1).

Returns:

The C-style string previously registered.

const char *data() const noexcept#

An alias for c_str(); resolves this registered string to a C-style NUL-terminated string.

Note

This operation is O(1).

Returns:

The C-style string previously registered.

size_t length() const noexcept#

Returns the length of the registered string.

If the string contains embedded NUL (‘\0’) characters this may differ from std::strlen(c_str()).

Note

This operation is O(1).

Returns:

The length of the registered string not including the NUL terminator.

bool operator==(const RStringTraits &other) const#

Equality comparison between this registered string and another.

Parameters:

other – Another registered string.

Returns:

true if *this and other represent the same registered string; false otherwise.

bool operator!=(const RStringTraits &other) const#

Inequality comparison between this registered string and another.

Parameters:

other – Another registered string.

Returns:

false if *this and other represent the same registered string; true otherwise.

bool owner_before(const RStringTraits &other) const#

Checks whether this registered string is stably (but not lexicographically) ordered before another registered string.

This ordering is to make registered strings usable as keys in ordered associative containers in O(1) time.

Note

This is NOT a lexicographical comparison; for that use one of the compare() functions. To reduce ambiguity between a strict ordering and lexicographical comparison there is no operator< function for this string class. While a lexicographical comparison would be O(n), this comparison is O(1).

Parameters:

other – Another registered string.

Returns:

true if *this should be ordered-before other; false otherwise.

int compare(
const RStringTraits<OtherUncased, OtherBase> &other,
) const#

Lexicographically compares this registered string with another.

Note

If either *this or other is “un-cased” (i.e. case-insensitive), a case-insensitive compare is performed.

Template Parameters:

OtherUncased – true if other is “un-cased” (i.e. case-insensitive); false otherwise.

Parameters:

other – Another registered string to compare against.

Returns:

0 if the strings are equal, >0 if other is lexicographically ordered before *this, or <0 if *this is lexicographically ordered before other. See note above regarding case-sensitivity.

int compare(const char *s) const#

Lexicographically compares this registered string with a C-style string.

Note

If *this is “un-cased” (i.e. case-insensitive), a case-insensitive compare is performed.

Parameters:

s – A C-style string to compare against.

Returns:

0 if the strings are equal, >0 if s is lexicographically ordered before *this, or <0 if *this is lexicographically ordered before s. See note above regarding case-sensitivity.

int compare(size_t pos, size_t count, const char *s) const#

Lexicographically compares a substring of this registered string with a C-style string.

Note

If *this is “un-cased” (i.e. case-insensitive), a case-insensitive compare is performed.

Parameters:

  • pos – The starting offset of the registered string represented by *this. Must less-than-or-equal-to the length of the registered string.

  • count – The length from pos to use in the comparison. This value is automatically clamped to the end of the registered string.

  • s – A C-style string to compare against.

Returns:

0 if the strings are equal, >0 if s is lexicographically ordered before the substring of *this, or <0 if the substring of *this is lexicographically ordered before s. See note above regarding case-sensitivity.

int compare(
size_t pos,
size_t count,
const char *s,
size_t len,
) const#

Lexicographically compares a substring of this registered string with a C-style string.

Note

If *this is “un-cased” (i.e. case-insensitive), a case-insensitive compare is performed.

Parameters:

  • pos – The starting offset of the registered string represented by *this. Must less-than-or-equal-to the length of the registered string.

  • count – The length from pos to use in the comparison. This value is automatically clamped to the end of the registered string.

  • s – A C-style string to compare against.

  • len – The number of characters of s to compare against.

Returns:

0 if the strings are equal, >0 if s is lexicographically ordered before the substring of *this, or <0 if the substring of *this is lexicographically ordered before s. See note above regarding case-sensitivity.

int compare(const std::string &s) const#

Lexicographically compares this registered string with a string.

Note

If *this is “un-cased” (i.e. case-insensitive), a case-insensitive compare is performed.

Parameters:

s – A string to compare against.

Returns:

0 if the strings are equal, >0 if s is lexicographically ordered before *this, or <0 if *this is lexicographically ordered before s. See note above regarding case-sensitivity.

int compare(size_t pos, size_t count, const std::string &s) const#

Lexicographically compares a substring of this registered string with a string.

Note

If *this is “un-cased” (i.e. case-insensitive), a case-insensitive compare is performed.

Parameters:

  • pos – The starting offset of the registered string represented by *this. Must less-than-or-equal-to the length of the registered string.

  • count – The length from pos to use in the comparison. This value is automatically clamped to the end of the registered string.

  • s – A string to compare against.

Returns:

0 if the strings are equal, >0 if s is lexicographically ordered before the substring of *this, or <0 if the substring of *this is lexicographically ordered before s. See note above regarding case-sensitivity.

Public Static Attributes

static constexpr bool IsUncased#

Constant that indicates whether this is “un-cased” (i.e.

case-insensitive).

On this page