carb::RStringKey¶
Defined in carb/RString.h
Inheritance Relationships¶
Base Type¶
public carb::details::RStringTraits< false, details::RStringKeyBase >
(carb::details::RStringTraits)
-
class
carb
::
RStringKey
: public carb::details::RStringTraits<false, details::RStringKeyBase>¶ A registered string key.
See RString key for high-level information about the registered string system.
RStringKey is formed by appending a numeric component to a registered string. This numeric component can be used as a unique instance identifier alongside the registered string. Additionally, the RStringKey::toString() function will append a non-zero numeric component following an underscore.
Public Functions
-
constexpr
RStringKey
() noexcept¶ Default constructor.
isEmpty() will report
true
and getNumber() will return0
.
-
constexpr
RStringKey
(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().
-
explicit
RStringKey
(const char *str, RStringOp op = RStringOp::eRegister)¶ Finds or registers a new string.
- 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.
-
RStringKey
(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
RStringKey
(const char *str, size_t len, RStringOp op = RStringOp::eRegister)¶ Finds or registers a new counted string.
Note
While generally not recommended, passing
len
allows the given string to contain embedded NUL (‘\0’) characters.- 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
RStringKey
(int32_t number, const char *str, size_t len, RStringOp op = RStringOp::eRegister)¶ Finds or registers a new counted string with a given number component.
Note
While generally not recommended, passing
len
allows the given string to contain embedded NUL (‘\0’) characters.- 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
RStringKey
(const std::string &str, RStringOp op = RStringOp::eRegister)¶ Finds or registers a new
std::string
.Note
If
str
contains embedded NUL (‘\0’) characters, the RString will contain the embedded NUL characters as well.- 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
RStringKey
(int32_t number, const std::string &str, RStringOp op = RStringOp::eRegister)¶ Finds or registers a new
std::string
with a number component.Note
If
str
contains embedded NUL (‘\0’) characters, the RString will contain the embedded NUL characters as well.- 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.
-
RStringKey
(const RString &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().
-
RStringUKey
toUncased
() const noexcept¶ Converts this registered string key into an “un-cased” (i.e.
case-insensitive) registered string key.
Note
The returned string may differ in case to
*this
when retrieved with c_str() or toString().- Returns
An “un-cased” (i.e. case-insensitive) string that matches
*this
when compared in a case-insensitive manner. The returned registered string key will have the same number component as*this
.
-
RString
truncate
() const noexcept¶ Returns a registered string without the number component.
- Returns
A regsitered string that matches
*this
without a number component.
-
bool
operator==
(const RStringKey &other) const noexcept¶ Equality comparison between this registered string key and another.
- Parameters
other – Another registered string.
- Returns
true
if*this
andother
represent the same registered string and have matching number components;false
otherwise.
-
bool
operator!=
(const RStringKey &other) const noexcept¶ Inequality comparison between this registered string key and another.
- Parameters
other – Another registered string.
- Returns
false
if*this
andother
represent the same registered string and have matching number components;true
otherwise.
-
bool
owner_before
(const RStringKey &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-beforeother
;false
otherwise.
-
std::string
toString
() const¶ Returns a string containing the registered string, and if getNumber() is not zero, the number appended.
Example: RStringKey(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 comparisions.
- 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
andother
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
andother
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-beforeother
;false
otherwise.
-
int
compare
(const RStringTraits<OtherUncased, OtherBase> &other) const¶ Lexicographically compares this registered string with another.
Note
If either
*this
orother
is “un-cased” (i.e. case-insensitive), a case-insensitive compare is performed.- Template Parameters
OtherUncased –
true
ifother
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
ifother
is lexicographically ordered before*this
, or<0
if*this
is lexicographically ordered beforeother
. 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
ifs
is lexicographically ordered before*this
, or<0
if*this
is lexicographically ordered befores
. 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
ifs
is lexicographically ordered before the substring of*this
, or<0
if the substring of*this
is lexicographically ordered befores
. 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
ifs
is lexicographically ordered before the substring of*this
, or<0
if the substring of*this
is lexicographically ordered befores
. 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
ifs
is lexicographically ordered before*this
, or<0
if*this
is lexicographically ordered befores
. 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
ifs
is lexicographically ordered before the substring of*this
, or<0
if the substring of*this
is lexicographically ordered befores
. 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).
-
constexpr