[#BloombergLP-bslstl-StringRefImp-0c]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bslstl.adoc[bslstl]::StringRefImp
:relfileprefix: ../../
:mrdocs:

This class provides a reference‐semantic‐like (see below) mechanism that allows `const` `std::string` values, which are represented externally as either an `std::string` or null‐terminated c‐style string (or parts thereof), to be treated both uniformly and efficiently when passed as an argument to a function in which the string's length will be needed. The interface of this class provides a subset of accessor methods found on `std::string` (but none of the manipulators) ‐‐ all of which apply to the referenced string. But, because only non‐modifiable access is afforded to the referenced string value, each of the manipulators on this type ‐‐ assignment in particular ‐‐ apply to this string‐reference object itself (as if it had pointer semantics). Hence, this class has a hybrid of reference‐ and pointer‐semantics.

== Synopsis

Declared in `<bslstl_stringref.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<class CHAR_TYPE>
class StringRefImp
    : public xref:BloombergLP/bslstl/StringRefData-04.adoc[StringRefData<CHAR_TYPE>]
----

== Description

This class: * supports a complete set of _value‐semantic_ operations

* except for `bdex` serialization * is _exception‐neutral_ (agnostic) * is _alias‐safe_ * is `const` _thread‐safe_ For terminology see `bsldoc_glossary`.

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bslstl/StringRefData-04.adoc[StringRefData<CHAR_TYPE>]`
| This class is an intermediate link between `bslstl::StringRef` used in BDE and `bsl::string_view` and is kept only for compatibility with legacy code.
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslstl/StringRefImp-0c/const_iterator.adoc[`const_iterator`] 
| Alias for a constant iterator over the characters of this ref.
| xref:BloombergLP/bslstl/StringRefImp-0c/const_reference.adoc[`const_reference`] 
| This `typedef` is an alias to `reference`.
| xref:BloombergLP/bslstl/StringRefImp-0c/const_reverse_iterator.adoc[`const_reverse_iterator`] 
| This `typedef` is an alias to `bsl::reverse_iterator<const_iterator>`.
| xref:BloombergLP/bslstl/StringRefImp-0c/difference_type.adoc[`difference_type`] 
| This `typedef` is an alias to `std::ptrdiff_t`.
| xref:BloombergLP/bslstl/StringRefImp-0c/iterator.adoc[`iterator`] 
| This `typedef` is an alias to `value_type const *`.
| xref:BloombergLP/bslstl/StringRefImp-0c/reference.adoc[`reference`] 
| This `typedef` is an alias to `value_type const&`.
| xref:BloombergLP/bslstl/StringRefImp-0c/size_type.adoc[`size_type`] 
| Standard Library general container requirements.
| xref:BloombergLP/bslstl/StringRefImp-0c/value_type.adoc[`value_type`] 
| Alias for a constant character type stored in this string ref.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslstl/StringRefImp-0c/2constructor-07.adoc[`StringRefImp`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bslstl/StringRefImp-0c/assign-0d.adoc[`assign`] 
| `assign` overloads
| xref:BloombergLP/bslstl/StringRefImp-0c/begin.adoc[`begin`] 
| Return an STL‐compatible iterator to the first character of the string bound to this string reference or `end()` if the string reference is empty. The iterator remains valid as long as this object is valid and is bound to the same string.
| xref:BloombergLP/bslstl/StringRefImp-0c/compare.adoc[`compare`] 
| Compare this and the specified `other` string objects using a lexicographical comparison and return a negative value if this string is less than `other` string, a positive value if this string is greater than `other` string, and 0 if this string is equal to `other` string.
| xref:BloombergLP/bslstl/StringRefImp-0c/data.adoc[`data`] 
| Return the address of the first character of the string bound to this string reference such that `[data() .. data()+length())]` is a valid half‐open range of characters. Note that the range of characters might not be null‐terminated and may contain embedded null characters.
| xref:BloombergLP/bslstl/StringRefImp-0c/empty.adoc[`empty`] 
| Return `true` if this object represents an empty string value, and `false` otherwise. This object represents an empty string value if `begin() == end()`. Note that this method is functionally identical with the `isEmpty` method and allows developers to avoid distracting syntax differences when `StringRef` appears in juxtaposition with `string`, which defines `empty` but not `isEmpty`.
| xref:BloombergLP/bslstl/StringRefImp-0c/end.adoc[`end`] 
| Return an STL‐compatible iterator one‐past‐the‐last character of the string bound to this string reference or `begin()` if the string reference is empty. The iterator remains valid as long as this object is valid and is bound to the same string.
| xref:BloombergLP/bslstl/StringRefImp-0c/isEmpty.adoc[`isEmpty`] 
| Return `true` if this object represents an empty string value, and `false` otherwise. This object represents an empty string value if `begin() == end()`.
| xref:BloombergLP/bslstl/StringRefImp-0c/length.adoc[`length`] 
| Return the length of the string referred to by this object. Note that this call is equivalent to `end() ‐ begin()`.
| xref:BloombergLP/bslstl/StringRefImp-0c/operator_subs.adoc[`operator[]`] 
| Return a reference providing a non‐modifiable access to the character at the specified `index` in the string bound to this reference. This reference remains valid as long as the string currently bound to this object remains valid. The behavior is undefined unless `0 <= index < length()`.
| xref:BloombergLP/bslstl/StringRefImp-0c/rbegin.adoc[`rbegin`] 
| Return an STL‐compatible reverse iterator to the last character of the string bound to this string reference or `rend()` if the string reference is empty. The iterator remains valid as long as this object is valid and is bound to the same string.
| xref:BloombergLP/bslstl/StringRefImp-0c/rend.adoc[`rend`] 
| Return an STL‐compatible reverse iterator to the prior‐to‐the‐beginning character of the string bound to this string reference or `rbegin()` if the string reference is empty. The iterator remains valid as long as this object is valid and is bound to the same string.
| xref:BloombergLP/bslstl/StringRefImp-0c/reset.adoc[`reset`] 
| Reset this string reference to the default‐constructed state having an empty `std::string` value and the following attribute values: ` begin() == end() isEmpty() == true `
| xref:BloombergLP/bslstl/StringRefImp-0c/size.adoc[`size`] 
| Return the number of characters in the string referred to by this object. Note that this call is equivalent to `end() ‐ begin()`.
| xref:BloombergLP/bslstl/StringRefData-04/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<StringRefData, is_trivially_copyable>`] 
| Declare `StringRefData` as trivially copyable.
| xref:BloombergLP/bslstl/StringRefImp-0c/2conversion-09.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<StringRefImp, is_trivially_copyable>`] 
| Nested trait declaration for `bsl::is_trivially_copyable`.
| xref:BloombergLP/bslstl/StringRefImp-0c/2conversion-0d.adoc[`operator std::basic_string<CHAR_TYPE>`] 
| Return an `std::basic_string` (synonymous with `std::basic_string`) having the value of the string bound to this string reference.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslstl/StringRefData-04/cStringLength.adoc[`cStringLength`] 
| Return the number of `CHAR_TYPE` characters in the specified null‐terminated `data` string, up to but not including the terminal null value.
|===


== Specializations

[cols="1"]
|===
| Name
| xref:BloombergLP/bslstl/StringRefImp-02.adoc[`StringRefImp<char>`] 
| xref:BloombergLP/bslstl/StringRefImp-0a.adoc[`StringRefImp<wchar_t>`] 
|===


== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslstl/operator_plus-00.adoc[`operator+`]
| Return the concatenation of the specified `lhs` string ref and the specified `rhs` `std::basic_string` value.
| xref:BloombergLP/bslstl/operator_plus-02.adoc[`operator+`]
| Return a `bsl::string` having the value of the concatenation of the strings referred to by the specified `lhs` and `rhs` values.
| xref:BloombergLP/bslstl/operator_plus-05.adoc[`operator+`]
| Return the concatenation of the specified `lhs` string ref and the specified `rhs` `bsl::basic_string` value.
| xref:BloombergLP/bslstl/operator_plus-076.adoc[`operator+`]
| Return the concatenation of the specified string ref and C string.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#