| description | title | ms.date | ms.topic | f1_keywords | helpviewer_keywords | ms.assetid | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: Platform::String Class | Platform::String Class | 10/16/2019 | reference |
|
| 72dd04a4-a694-40d3-b899-eaa0b503eab8 |
Represents a sequential collection of Unicode characters that is used to represent text. For more information and examples, see Strings.
public ref classString sealed : Object, IDisposable, IEquatable, IPrintableTwo iterator functions, which are not members of the String class, can be used with the std::for_each function template to enumerate the characters in a String object.
| Member | Description |
|---|---|
const char16* begin(String^ s) | Returns a pointer to the beginning of the specified String object. |
const char16* end(String^ s) | Returns a pointer past the end of the specified String object. |
The String class inherits from Object, and the IDisposable, IEquatable, and IPrintable interfaces.
The String class also has the following types of members.
| Member | Description |
|---|---|
| String::String | Initializes a new instance of the String class. |
The String class inherits the Equals(), Finalize(), GetHashCode(), GetType(), MemberwiseClose(), and ToString() methods from the Platform::Object Class. String also has the following methods.
| Method | Description |
|---|---|
| String::Begin | Returns a pointer to the beginning of the current string. |
| String::CompareOrdinal | Compares two String objects by evaluating the numeric values of the corresponding characters in the two string values represented by the objects. |
| String::Concat | Concatenates the values of two String objects. |
| String::Data | Returns a pointer to the beginning of the current string. |
| String::Dispose | Frees or releases resources. |
| String::End | Returns a pointer past the end of the current string. |
| String::Equals | Indicates whether the specified object is equal to the current object. |
| String::GetHashCode | Returns the hash code for this instance. |
| String::IsEmpty | Indicates whether the current String object is empty. |
| String::IsFastPass | Indicates whether the current String object is participating in a fast pass operation. In a fast pass operation, reference counting is suspended. |
| String::Length | Retrieves the length of the current String object. |
| String::ToString | Returns a String object whose value is the same as the current string. |
The String class has the following operators.
| Member | Description |
|---|---|
| String::operator== Operator | Indicates whether two specified String objects have the same value. |
| operator+ Operator | Concatenates two String objects into a new String object. |
| String::operator> Operator | Indicates whether the value of one String object is greater than the value of a second String object. |
| String::operator>= Operator | Indicates whether the value of one String object is greater than or equal to the value of a second String object. |
| String::operator!= Operator | Indicates whether two specified String objects have different values. |
| String::operator< Operator | Indicates whether the value of one String object is less than the value of a second String object. |
Minimum supported client: Windows 8
Minimum supported server: Windows Server 2012
Namespace: Platform
Header vccorlib.h (included by default)
Returns a pointer to the beginning of the current string.
char16* Begin();A pointer to the beginning of the current string.
Static method that compares two String objects by evaluating the numeric values of the corresponding characters in the two string values represented by the objects.
staticintCompareOrdinal( String^ str1, String^ str2 );str1
The first String object.
str2
The second String object.
An integer that indicates the lexical relationship between the two comparands. The following table lists the possible return values.
| Value | Condition |
|---|---|
| -1 | str1 is less than str2. |
| 0 | str1 is equals str2. |
| 1 | str1 is greater than str2. |
Concatenates the values of two String objects.
String^ Concat( String^ str1, String^ str2);str1
The first String object, or null.
str2
The second String object, or null.
A new String^ object whose value is the concatenation of the values of str1 and str2.
If str1 is null and str2 is not, str1 is returned. If str2 is null and str1 is not, str2 is returned. If str1 and str2 are both null, the empty string (L"") is returned.
Returns a pointer to the beginning of the object's data buffer as a C-style array of char16 (wchar_t) elements.
const char16* Data();A pointer to the beginning of a const char16 array of Unicode characters (char16 is a typedef for wchar_t).
Use this method to convert from Platform::String^ to wchar_t*. When the String object goes out of scope, the Data pointer is no longer guaranteed to be valid. To store the data beyond the lifetime of the original String object, use wcscpy_s to copy the array into memory that you have allocated yourself.
Frees or releases resources.
virtualoverridevoidDispose();Returns a pointer past the end of the current string.
char16* End();A pointer to past the end of the current string.
End() returns Begin() + Length.
Indicates whether the specified String has the same value as the current object.
boolString::Equals(Object^ str); boolString::Equals(String^ str);str
The object to compare.
true if str is equal to the current object; otherwise, false.
This method is equivalent to the static String::CompareOrdinal. In the first overload, it is expected the str parameter can be cast to a String^ object.
Returns the hash code for this instance.
virtualoverrideintGetHashCode();The hash code for this instance.
Indicates whether the current String object is empty.
boolIsEmpty();true if the current String object is null or the empty string (L""); otherwise, false.
Indicates whether the current String object is participating in a fast pass operation. In a fast pass operation, reference counting is suspended.
boolIsFastPass();true if the current String object is fast-past; otherwise, false.
In a call to a function where a reference-counted object is a parameter, and the called function only reads that object, the compiler can safely suspend reference counting and improve calling performance. There is nothing useful that your code can do with this property. The system handles all the details.
Retrieves the number of characters in the current String object.
unsignedintLength();The number of characters in the current String object.
The length of a String with no characters is zero. The length of the following string is 5:
String^ str = "Hello"; int len = str->Length(); //len = 5The character array returned by the String::Data has one additional character, which is the terminating NULL or '\0'. This character is also two bytes long.
Concatenates two String objects into a new String object.
bool String::operator+( String^ str1, String^ str2);str1
The first String object.
str2
The second String object, whose contents will be appended to str1.
true if str1 is equal to str2; otherwise, false.
This operator creates a String^ object that contains the data from the two operands. Use it for convenience when extreme performance is not critical. A few calls to "+" in a function will probably not be noticeable, but if you are manipulating large objects or text data in a tight loop, then use the standard C++ mechanisms and types.
Indicates whether two specified String objects have the same text value.
bool String::operator==( String^ str1, String^ str2);str1
The first String object to compare.
str2
The second String object to compare.
true if the contents of str1 are equal to str2; otherwise, false.
This operator is equivalent to String::CompareOrdinal.
Indicates whether the value of one String object is greater than the value of a second String object.
bool String::operator>( String^ str1, String^ str2);str1
The first String object.
str2
The second String object.
true if the value of str1 is greater than the value of str2; otherwise, false.
This operator is equivalent to explicitly calling String::CompareOrdinal and getting a result greater than zero.
Indicates whether the value of one String object is greater than or equal to the value of a second String object.
bool String::operator>=( String^ str1, String^ str2);str1
The first String object.
str2
The second String object.
true if the value of str1 is greater than or equal to the value of str2; otherwise, false.
Indicates whether two specified String objects have different values.
bool String::operator!=( String^ str1, String^ str2);str1
The first String object to compare.
str2
The second String object to compare.
true if str1 is not equal to str2; otherwise, false.
Indicates whether the value of one String object is less than the value of a second String object.
bool String::operator<( String^ str1, String^ str2);str1
The first String object.
str2
The second String object.
true if the value of str1 is less than the value of str2; otherwise, false.
Initializes a new instance of the String class with a copy of the input string data.
String(); String(char16* s); String(char16* s, unsignedint n);s
A series of wide characters that initialize the string. char16
n
A number that specifies the length of the string.
If performance is critical and you control the lifetime of the source string, you can use Platform::StringReference in place of String.
String^ s = L"Hello!";Returns a String object whose value is the same as the current string.
String^ String::ToString();A String object whose value is the same as the current string.
