Platform::String Class
Represents a sequential collection of Unicode characters that is used to represent text. For more information and examples, see Strings.
Syntax
public ref class String sealed : Object,
IDisposable,
IEquatable,
IPrintable
Iterators
Two 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. |
Members
The String class inherits from Object, and the IDisposable, IEquatable, and IPrintable interfaces.
The String class also has the following types of members.
Constructors
| Member | Description |
|---|---|
| String::String | Initializes a new instance of the String class. |
Methods
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. |
Operators
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. |
Requirements
Minimum supported client: Windows 8
Minimum supported server: Windows Server 2012
Namespace: Platform
Header vccorlib.h (included by default)
String::Begin Method
Returns a pointer to the beginning of the current string.
Syntax
char16* Begin();
Return Value
A pointer to the beginning of the current string.
String::CompareOrdinal Method
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.
Syntax
static int CompareOrdinal( String^ str1, String^ str2 );
Parameters
str1
The first String object.
str2
The second String object.
Return Value
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. |
String::Concat Method
Concatenates the values of two String objects.
Syntax
String^ Concat( String^ str1, String^ str2);
Parameters
str1
The first String object, or null.
str2
The second String object, or null.
Return Value
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.
String::Data Method
Returns a pointer to the beginning of the object's data buffer as a C-style array of char16 (wchar_t) elements.
Syntax
const char16* Data();
Return Value
A pointer to the beginning of a const char16 array of Unicode characters (char16 is a typedef for wchar_t).
Remarks
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.
String::Dispose Method
Frees or releases resources.
Syntax
virtual override void Dispose();
String::End Method
Returns a pointer past the end of the current string.
Syntax
char16* End();
Return Value
A pointer to past the end of the current string.
Remarks
End() returns Begin() + Length.
String::Equals Method
Indicates whether the specified String has the same value as the current object.
Syntax
bool String::Equals(Object^ str);
bool String::Equals(String^ str);
Parameters
str
The object to compare.
Return Value
true if str is equal to the current object; otherwise, false.
Remarks
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.
String::GetHashCode Method
Returns the hash code for this instance.
Syntax
virtual override int GetHashCode();
Return Value
The hash code for this instance.
String::IsEmpty Method
Indicates whether the current String object is empty.
Syntax
bool IsEmpty();
Return Value
true if the current String object is null or the empty string (L""); otherwise, false.
String::IsFastPass Method
Indicates whether the current String object is participating in a fast pass operation. In a fast pass operation, reference counting is suspended.
Syntax
bool IsFastPass();
Return Value
true if the current String object is fast-past; otherwise, false.
Remarks
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.
String::Length Method
Retrieves the number of characters in the current String object.
Syntax
unsigned int Length();
Return Value
The number of characters in the current String object.
Remarks
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 = 5
The 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.
String::operator+ Operator
Concatenates two String objects into a new String object.
Syntax
bool String::operator+( String^ str1, String^ str2);
Parameters
str1
The first String object.
str2
The second String object, whose contents will be appended to str1.
Return Value
true if str1 is equal to str2; otherwise, false.
Remarks
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.
String::operator== Operator
Indicates whether two specified String objects have the same text value.
Syntax
bool String::operator==( String^ str1, String^ str2);
Parameters
str1
The first String object to compare.
str2
The second String object to compare.
Return Value
true if the contents of str1 are equal to str2; otherwise, false.
Remarks
This operator is equivalent to String::CompareOrdinal.
String::operator>
Indicates whether the value of one String object is greater than the value of a second String object.
Syntax
bool String::operator>( String^ str1, String^ str2);
Parameters
str1
The first String object.
str2
The second String object.
Return Value
true if the value of str1 is greater than the value of str2; otherwise, false.
Remarks
This operator is equivalent to explicitly calling String::CompareOrdinal and getting a result greater than zero.
String::operator>=
Indicates whether the value of one String object is greater than or equal to the value of a second String object.
Syntax
bool String::operator>=( String^ str1, String^ str2);
Parameters
str1
The first String object.
str2
The second String object.
Return Value
true if the value of str1 is greater than or equal to the value of str2; otherwise, false.
String::operator!=
Indicates whether two specified String objects have different values.
Syntax
bool String::operator!=( String^ str1, String^ str2);
Parameters
str1
The first String object to compare.
str2
The second String object to compare.
Return Value
true if str1 is not equal to str2; otherwise, false.
String::operator<
Indicates whether the value of one String object is less than the value of a second String object.
Syntax
bool String::operator<( String^ str1, String^ str2);
Parameters
str1
The first String object.
str2
The second String object.
Return Value
true if the value of str1 is less than the value of str2; otherwise, false.
String::String Constructor
Initializes a new instance of the String class with a copy of the input string data.
Syntax
String();
String(char16* s);
String(char16* s, unsigned int n);
Parameters
s
A series of wide characters that initialize the string. char16
n
A number that specifies the length of the string.
Remarks
If performance is critical and you control the lifetime of the source string, you can use Platform::StringReference in place of String.
Example
String^ s = L"Hello!";
String::ToString
Returns a String object whose value is the same as the current string.
Syntax
String^ String::ToString();
Return Value
A String object whose value is the same as the current string.