diff --git a/xml/System/String.xml b/xml/System/String.xml index 051f4a52c3d..2dee7b14145 100644 --- a/xml/System/String.xml +++ b/xml/System/String.xml @@ -99,7 +99,7 @@ ## Remarks - A string is a sequential collection of characters that is used to represent text. A object is a sequential collection of objects that represent a string; a object corresponds to a UTF-16 code unit. The value of the object is the content of the sequential collection of objects, and that value is immutable (that is, it is read-only). For more information about the immutability of strings, see the [Immutability and the StringBuilder class](#Immutability) section later in this topic. The maximum size of a object in memory is 2GB, or about 1 billion characters. + A string is a sequential collection of characters that's used to represent text. A object is a sequential collection of objects that represent a string; a object corresponds to a UTF-16 code unit. The value of the object is the content of the sequential collection of objects, and that value is immutable (that is, it is read-only). For more information about the immutability of strings, see the [Immutability and the StringBuilder class](#Immutability) section. The maximum size of a object in memory is 2-GB, or about 1 billion characters. For more information about Unicode, UTF-16, code units, code points, and the and types, see [Introduction to character encoding in .NET](/dotnet/standard/base-types/character-encoding-introduction). @@ -120,31 +120,31 @@ For more information about Unicode, UTF-16, code units, code points, and the object in the following ways: -- By assigning a string literal to a variable. This is the most commonly used method for creating a string. The following example uses assignment to create several strings. Note that in C#, because the backslash (\\) is an escape character, literal backslashes in a string must be escaped or the entire string must be @-quoted. +- By assigning a string literal to a variable. This is the most commonly used method for creating a string. The following example uses assignment to create several strings. Note that in C#, because the backslash (\\) is an escape character, literal backslashes in a string must be escaped or the entire string must be @-quoted. [!code-cpp[System.String.Class.Instantiate#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.class.instantiate/cpp/string.instantiate1.cpp#1)] [!code-csharp-interactive[System.String.Class.Instantiate#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.class.instantiate/cs/program.cs#1)] [!code-vb[System.String.Class.Instantiate#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.class.instantiate/vb/instantiate1.vb#1)] -- By calling a class constructor. The following example instantiates strings by calling several class constructors. Note that some of the constructors include pointers to character arrays or signed byte arrays as parameters. Visual Basic does not support calls to these constructors. For detailed information about constructors, see the constructor summary. +- By calling a class constructor. The following example instantiates strings by calling several class constructors. Note that some of the constructors include pointers to character arrays or signed byte arrays as parameters. Visual Basic does not support calls to these constructors. For detailed information about constructors, see the constructor summary. [!code-cpp[System.String.Class.Instantiate#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.class.instantiate/cpp/string.instantiate2.cpp#2)] [!code-csharp[System.String.Class.Instantiate#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.class.instantiate/cs/program.cs#2)] [!code-vb[System.String.Class.Instantiate#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.class.instantiate/vb/instantiate1.vb#2)] -- By using the string concatenation operator (+ in C# and & or + in Visual Basic) to create a single string from any combination of instances and string literals. The following example illustrates the use of the string concatenation operator. +- By using the string concatenation operator (+ in C# and & or + in Visual Basic) to create a single string from any combination of instances and string literals. The following example illustrates the use of the string concatenation operator. [!code-cpp[System.String.Class.Instantiate#3](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.class.instantiate/cpp/string.instantiate3.cpp#3)] [!code-csharp-interactive[System.String.Class.Instantiate#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.class.instantiate/cs/program.cs#3)] [!code-vb[System.String.Class.Instantiate#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.class.instantiate/vb/instantiate1.vb#3)] -- By retrieving a property or calling a method that returns a string. The following example uses the methods of the class to extract a substring from a larger string. +- By retrieving a property or calling a method that returns a string. The following example uses the methods of the class to extract a substring from a larger string. [!code-cpp[System.String.Class.Instantiate#4](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.class.instantiate/cpp/string.instantiate3.cpp#4)] [!code-csharp-interactive[System.String.Class.Instantiate#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.class.instantiate/cs/program.cs#4)] [!code-vb[System.String.Class.Instantiate#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.class.instantiate/vb/instantiate1.vb#4)] -- By calling a formatting method to convert a value or object to its string representation. The following example uses the [composite formatting](/dotnet/standard/base-types/composite-formatting) feature to embed the string representation of two objects into a string. +- By calling a formatting method to convert a value or object to its string representation. The following example uses the [composite formatting](/dotnet/standard/base-types/composite-formatting) feature to embed the string representation of two objects into a string. [!code-cpp[System.String.Class.Instantiate#5](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.class.instantiate/cpp/string.instantiate3.cpp#5)] [!code-csharp[System.String.Class.Instantiate#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.class.instantiate/cs/program.cs#5)] @@ -155,17 +155,17 @@ For more information about Unicode, UTF-16, code units, code points, and the object. > [!NOTE] -> Note that, because a instance consists of a sequential collection of UTF-16 code units, it is possible to create a object that is not a well-formed Unicode string. For example, it is possible to create a string that has a low surrogate without a corresponding high surrogate. Although some methods, such as the methods of encoding and decoding objects in the namespace, may performs checks to ensure that strings are well-formed, class members don't ensure that a string is well-formed. +> Note that, because a instance consists of a sequential collection of UTF-16 code units, it is possible to create a object that is not a well-formed Unicode string. For example, it is possible to create a string that has a low surrogate without a corresponding high surrogate. Although some methods, such as the methods of encoding and decoding objects in the namespace, may performs checks to ensure that strings are well-formed, class members don't ensure that a string is well-formed. A single object usually represents a single code point; that is, the numeric value of the equals the code point. For example, the code point for the character "a" is U+0061. However, a code point might require more than one encoded element (more than one object). The Unicode standard defines two types of characters that correspond to multiple objects: graphemes, and Unicode supplementary code points that correspond to characters in the Unicode supplementary planes. -- A grapheme is represented by a base character followed by one or more combining characters. For example, the character ä is represented by a object whose code point is U+0061 followed by a object whose code point is U+0308. This character can also be defined by a single object that has a code point of U+00E4. As the following example shows, a culture-sensitive comparison for equality indicates that these two representations are equal, although an ordinary ordinal comparison does not. However, if the two strings are normalized, an ordinal comparison also indicates that they are equal. (For more information on normalizing strings, see the [Normalization](#Normalization) section.) +- A grapheme is represented by a base character followed by one or more combining characters. For example, the character ä is represented by a object whose code point is U+0061 followed by a object whose code point is U+0308. This character can also be defined by a single object that has a code point of U+00E4. As the following example shows, a culture-sensitive comparison for equality indicates that these two representations are equal, although an ordinary ordinal comparison does not. However, if the two strings are normalized, an ordinal comparison also indicates that they are equal. (For more information on normalizing strings, see the [Normalization](#Normalization) section.) [!code-cpp[System.String.Class#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.String.Class/cpp/string.char1.cpp#2)] [!code-csharp[System.String.Class#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Class/cs/grapheme1.cs#2)] [!code-vb[System.String.Class#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Class/vb/grapheme1.vb#2)] -- A Unicode supplementary code point (a surrogate pair) is represented by a object whose code point is a high surrogate followed by a object whose code point is a low surrogate. The code units of high surrogates range from U+D800 to U+DBFF. The code units of low surrogates range from U+DC00 to U+DFFF. Surrogate pairs are used to represent characters in the 16 Unicode supplementary planes. The following example creates a surrogate character and passes it to the method to determine whether it is a surrogate pair. +- A Unicode supplementary code point (a surrogate pair) is represented by a object whose code point is a high surrogate followed by a object whose code point is a low surrogate. The code units of high surrogates range from U+D800 to U+DBFF. The code units of low surrogates range from U+DC00 to U+DFFF. Surrogate pairs are used to represent characters in the 16 Unicode supplementary planes. The following example creates a surrogate character and passes it to the method to determine whether it is a surrogate pair. [!code-cpp[System.String.Class#3](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.String.Class/cpp/string.char2.cpp#3)] [!code-csharp-interactive[System.String.Class#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Class/cs/surrogate1.cs#3)] @@ -195,9 +195,9 @@ For more information about Unicode, UTF-16, code units, code points, and the object can include embedded null characters, which count as a part of the string's length. However, in some languages such as C and C++, a null character indicates the end of a string; it is not considered a part of the string and is not counted as part of the string's length. This means that the following common assumptions that C and C++ programmers or libraries written in C or C++ might make about strings are not necessarily valid when applied to objects: -- The value returned by the `strlen` or `wcslen` functions does not necessarily equal . +- The value returned by the `strlen` or `wcslen` functions does not necessarily equal . -- The string created by the `strcpy_s` or `wcscpy_s` functions is not necessarily identical to the string created by the method. +- The string created by the `strcpy_s` or `wcscpy_s` functions is not necessarily identical to the string created by the method. You should ensure that native C and C++ code that instantiates objects, and code that is passed objects through platform invoke, don't assume that an embedded null character marks the end of the string. @@ -235,13 +235,13 @@ For more information about Unicode, UTF-16, code units, code points, and the class includes the following two convenience methods that enable you to test whether a string is `null` or empty: -- , which indicates whether a string is either `null` or is equal to . This method eliminates the need to use code such as the following: +- , which indicates whether a string is either `null` or is equal to . This method eliminates the need to use code such as the following: [!code-cpp[System.String.Class.Null#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.class.null/cpp/string.null.cpp#1)] [!code-csharp[System.String.Class.Null#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.class.null/cs/nullorempty1.cs#1)] [!code-vb[System.String.Class.Null#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.class.null/vb/nullorempty1.vb#1)] -- , which indicates whether a string is `null`, equals , or consists exclusively of white-space characters. This method eliminates the need to use code such as the following: +- , which indicates whether a string is `null`, equals , or consists exclusively of white-space characters. This method eliminates the need to use code such as the following: [!code-cpp[System.String.Class.Null#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.class.null/cpp/string.null.cpp#2)] [!code-csharp[System.String.Class.Null#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.class.null/cs/nullorempty1.cs#2)] @@ -276,15 +276,15 @@ For more information about Unicode, UTF-16, code units, code points, and the ), which is loosely based on the culture settings of the English language independent of region. Unlike other settings, the settings of the invariant culture are guaranteed to remain consistent on a single computer, from system to system, and across versions of .NET. The invariant culture can be seen as a kind of black box that ensures stability of string comparisons and ordering across all cultures. > [!IMPORTANT] -> If your application makes a security decision about a symbolic identifier such as a file name or named pipe, or about persisted data such as the text-based data in an XML file, the operation should use an ordinal comparison instead of a culture-sensitive comparison. This is because a culture-sensitive comparison can yield different results depending on the culture in effect, whereas an ordinal comparison depends solely on the binary value of the compared characters. +> If your application makes a security decision about a symbolic identifier such as a file name or named pipe, or about persisted data such as the text-based data in an XML file, the operation should use an ordinal comparison instead of a culture-sensitive comparison. This is because a culture-sensitive comparison can yield different results depending on the culture in effect, whereas an ordinal comparison depends solely on the binary value of the compared characters. > [!IMPORTANT] -> Most methods that perform string operations include an overload that has a parameter of type , which enables you to specify whether the method performs an ordinal or culture-sensitive operation. In general, you should call this overload to make the intent of your method call clear. For best practices and guidance for using ordinal and culture-sensitive operations on strings, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). +> Most methods that perform string operations include an overload that has a parameter of type , which enables you to specify whether the method performs an ordinal or culture-sensitive operation. In general, you should call this overload to make the intent of your method call clear. For best practices and guidance for using ordinal and culture-sensitive operations on strings, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). Operations for [casing](#casing), [parsing and formatting](#parsing), [comparison and sorting](#comparison), and [testing for equality](#equality) can be either ordinal or culture-sensitive. The following sections discuss each category of operation. > [!TIP] -> You should always call a method overload that makes the intent of your method call clear. For example, instead of calling the method to perform a culture-sensitive comparison of two strings by using the conventions of the current culture, you should call the method with a value of for the `comparisonType` argument. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). +> You should always call a method overload that makes the intent of your method call clear. For example, instead of calling the method to perform a culture-sensitive comparison of two strings by using the conventions of the current culture, you should call the method with a value of for the `comparisonType` argument. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). You can download the sorting weight tables, a set of text files that contain information on the character weights used in sorting and comparison operations, from the following links: @@ -299,14 +299,14 @@ You can download the sorting weight tables, a set of text files that contain inf Casing operations can be based on the rules of the current culture, a specified culture, or the invariant culture. Because case mappings can vary depending on the culture used, the result of casing operations can vary based on culture. The actual differences in casing are of three kinds: -- Differences in the case mapping of LATIN CAPITAL LETTER I (U+0049), LATIN SMALL LETTER I (U+0069), LATIN CAPITAL LETTER I WITH DOT ABOVE (U+0130), and LATIN SMALL LETTER DOTLESS I (U+0131). In the tr-TR (Turkish (Turkey)) and az-Latn-AZ (Azerbaijan, Latin) cultures, and in the tr, az, and az-Latn neutral cultures, the lowercase equivalent of LATIN CAPITAL LETTER I is LATIN SMALL LETTER DOTLESS I, and the uppercase equivalent of LATIN SMALL LETTER I is LATIN CAPITAL LETTER I WITH DOT ABOVE. In all other cultures, including the invariant culture, LATIN SMALL LETTER I and LATIN CAPITAL LETTER I are lowercase and uppercase equivalents. +- Differences in the case mapping of LATIN CAPITAL LETTER I (U+0049), LATIN SMALL LETTER I (U+0069), LATIN CAPITAL LETTER I WITH DOT ABOVE (U+0130), and LATIN SMALL LETTER DOTLESS I (U+0131). In the tr-TR (Turkish (Turkey)) and az-Latn-AZ (Azerbaijan, Latin) cultures, and in the tr, az, and az-Latn neutral cultures, the lowercase equivalent of LATIN CAPITAL LETTER I is LATIN SMALL LETTER DOTLESS I, and the uppercase equivalent of LATIN SMALL LETTER I is LATIN CAPITAL LETTER I WITH DOT ABOVE. In all other cultures, including the invariant culture, LATIN SMALL LETTER I and LATIN CAPITAL LETTER I are lowercase and uppercase equivalents. The following example demonstrates how a string comparison designed to prevent file system access can fail if it relies on a culture-sensitive casing comparison. (The casing conventions of the invariant culture should have been used.) [!code-csharp[System.String.Class#17](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Class/cs/case2.cs#17)] [!code-vb[System.String.Class#17](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Class/vb/case2.vb#17)] -- Differences in case mappings between the invariant culture and all other cultures. In these cases, using the casing rules of the invariant culture to change a character to uppercase or lowercase returns the same character. For all other cultures, it returns a different character. Some of the affected characters are listed in the following table. +- Differences in case mappings between the invariant culture and all other cultures. In these cases, using the casing rules of the invariant culture to change a character to uppercase or lowercase returns the same character. For all other cultures, it returns a different character. Some of the affected characters are listed in the following table. |Character|If changed to|Returns| |---------------|-------------------|-------------| @@ -317,7 +317,7 @@ You can download the sorting weight tables, a set of text files that contain inf |LATIN CAPITAL LETTER D WITH SMALL LETTER Z WITH CARON (U+01C5)|Lowercase|LATIN SMALL LETTER DZ WITH CARON (U+01C6)| |COMBINING GREEK YPOGEGRAMMENI (U+0345)|Uppercase|GREEK CAPITAL LETTER IOTA (U+0399)| -- Differences in case mappings of two-letter mixed-case pairs in the ASCII character range. In most cultures, a two-letter mixed-case pair is equal to the equivalent two-letter uppercase or lowercase pair. This is not true for the following two-letter pairs in the following cultures, because in each case they are compared to a digraph: +- Differences in case mappings of two-letter mixed-case pairs in the ASCII character range. In most cultures, a two-letter mixed-case pair is equal to the equivalent two-letter uppercase or lowercase pair. This is not true for the following two-letter pairs in the following cultures, because in each case they are compared to a digraph: - "lJ" and "nJ" in the hr-HR (Croatian (Croatia)) culture. @@ -357,7 +357,7 @@ You can download the sorting weight tables, a set of text files that contain inf ### String comparison and sorting Conventions for comparing and sorting strings vary from culture to culture. For example, the sort order may be based on phonetics or on the visual representation of characters. In East Asian languages, characters are sorted by the stroke and radical of ideographs. Sorting also depends on the order languages and cultures use for the alphabet. For example, the Danish language has an "Æ" character that it sorts after "Z" in the alphabet. In addition, comparisons can be case-sensitive or case-insensitive, and casing rules might differ by culture. Ordinal comparison, on the other hand, uses the Unicode code points of individual characters in a string when comparing and sorting strings. - Sort rules determine the alphabetic order of Unicode characters and how two strings compare to each other. For example, the method compares two strings based on the parameter. If the parameter value is , the method performs a linguistic comparison that uses the conventions of the current culture; if the parameter value is , the method performs an ordinal comparison. Consequently, as the following example shows, if the current culture is U.S. English, the first call to the method (using culture-sensitive comparison) considers "a" less than "A", but the second call to the same method (using ordinal comparison) considers "a" greater than "A". + Sort rules determine the alphabetic order of Unicode characters and how two strings compare to each other. For example, the method compares two strings based on the parameter. If the parameter value is , the method performs a linguistic comparison that uses the conventions of the current culture; if the parameter value is , the method performs an ordinal comparison. Consequently, as the following example shows, if the current culture is U.S. English, the first call to the method (using culture-sensitive comparison) considers "a" less than "A", but the second call to the same method (using ordinal comparison) considers "a" greater than "A". [!code-cpp[System.String.Class#10](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.String.Class/cpp/string.compare1.cpp#10)] [!code-csharp[System.String.Class#10](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Class/cs/compare1.cs#10)] @@ -365,13 +365,13 @@ You can download the sorting weight tables, a set of text files that contain inf .NET supports word, string, and ordinal sort rules: -- A word sort performs a culture-sensitive comparison of strings in which certain nonalphanumeric Unicode characters might have special weights assigned to them. For example, the hyphen (-) might have a very small weight assigned to it so that "coop" and "co-op" appear next to each other in a sorted list. For a list of the methods that compare two strings using word sort rules, see the [String operations by category](#ByCategory) section. +- A word sort performs a culture-sensitive comparison of strings in which certain nonalphanumeric Unicode characters might have special weights assigned to them. For example, the hyphen (-) might have a very small weight assigned to it so that "coop" and "co-op" appear next to each other in a sorted list. For a list of the methods that compare two strings using word sort rules, see the [String operations by category](#ByCategory) section. -- A string sort also performs a culture-sensitive comparison. It is similar to a word sort, except that there are no special cases, and all nonalphanumeric symbols come before all alphanumeric Unicode characters. Two strings can be compared using string sort rules by calling the method overloads that have an `options` parameter that is supplied a value of . Note that this is the only method that .NET provides to compare two strings using string sort rules. +- A string sort also performs a culture-sensitive comparison. It is similar to a word sort, except that there are no special cases, and all nonalphanumeric symbols come before all alphanumeric Unicode characters. Two strings can be compared using string sort rules by calling the method overloads that have an `options` parameter that is supplied a value of . Note that this is the only method that .NET provides to compare two strings using string sort rules. -- An ordinal sort compares strings based on the numeric value of each object in the string. An ordinal comparison is automatically case-sensitive because the lowercase and uppercase versions of a character have different code points. However, if case is not important, you can specify an ordinal comparison that ignores case. This is equivalent to converting the string to uppercase by using the invariant culture and then performing an ordinal comparison on the result. For a list of the methods that compare two strings using ordinal sort rules, see the [String operations by category](#ByCategory) section. +- An ordinal sort compares strings based on the numeric value of each object in the string. An ordinal comparison is automatically case-sensitive because the lowercase and uppercase versions of a character have different code points. However, if case is not important, you can specify an ordinal comparison that ignores case. This is equivalent to converting the string to uppercase by using the invariant culture and then performing an ordinal comparison on the result. For a list of the methods that compare two strings using ordinal sort rules, see the [String operations by category](#ByCategory) section. - A culture-sensitive comparison is any comparison that explicitly or implicitly uses a object, including the invariant culture that is specified by the property. The implicit culture is the current culture, which is specified by the and properties. There is considerable variation in the sort order of alphabetic characters (that is, characters for which the property returns `true`) across cultures. You can specify a culture-sensitive comparison that uses the conventions of a specific culture by supplying a object to a string comparison method such as . You can specify a culture-sensitive comparison that uses the conventions of the current culture by supplying , , or any member of the enumeration other than or to an appropriate overload of the method. A culture-sensitive comparison is generally appropriate for sorting whereas an ordinal comparison is not. An ordinal comparison is generally appropriate for determining whether two strings are equal (that is, for determining identity) whereas a culture-sensitive comparison is not. + A culture-sensitive comparison is any comparison that explicitly or implicitly uses a object, including the invariant culture that is specified by the property. The implicit culture is the current culture, which is specified by the and properties. There is considerable variation in the sort order of alphabetic characters (that is, characters for which the property returns `true`) across cultures. You can specify a culture-sensitive comparison that uses the conventions of a specific culture by supplying a object to a string comparison method such as . You can specify a culture-sensitive comparison that uses the conventions of the current culture by supplying , , or any member of the enumeration other than or to an appropriate overload of the method. A culture-sensitive comparison is generally appropriate for sorting whereas an ordinal comparison is not. An ordinal comparison is generally appropriate for determining whether two strings are equal (that is, for determining identity) whereas a culture-sensitive comparison is not. The following example illustrates the difference between culture-sensitive and ordinal comparison. The example evaluates three strings, "Apple", "Æble", and "AEble", using ordinal comparison and the conventions of the da-DK and en-US cultures (each of which is the default culture at the time the method is called). Because the Danish language treats the character "Æ" as an individual letter and sorts it after "Z" in the alphabet, the string "Æble" is greater than "Apple". However, "Æble" is not considered equivalent to "AEble", so "Æble" is also greater than "AEble". The en-US culture doesn't include the letter"Æ" but treats it as equivalent to "AE", which explains why "Æble" is less than "Apple" but equal to "AEble". Ordinal comparison, on the other hand, considers "Apple" to be less than "Æble", and "Æble" to be greater than "AEble". @@ -380,16 +380,16 @@ You can download the sorting weight tables, a set of text files that contain inf Use the following general guidelines to choose an appropriate sorting or string comparison method: -- If you want the strings to be ordered based on the user's culture, you should order them based on the conventions of the current culture. If the user's culture changes, the order of sorted strings will also change accordingly. For example, a thesaurus application should always sort words based on the user's culture. +- If you want the strings to be ordered based on the user's culture, you should order them based on the conventions of the current culture. If the user's culture changes, the order of sorted strings will also change accordingly. For example, a thesaurus application should always sort words based on the user's culture. -- If you want the strings to be ordered based on the conventions of a specific culture, you should order them by supplying a object that represents that culture to a comparison method. For example, in an application designed to teach students a particular language, you want strings to be ordered based on the conventions of one of the cultures that speaks that language. +- If you want the strings to be ordered based on the conventions of a specific culture, you should order them by supplying a object that represents that culture to a comparison method. For example, in an application designed to teach students a particular language, you want strings to be ordered based on the conventions of one of the cultures that speaks that language. -- If you want the order of strings to remain unchanged across cultures, you should order them based on the conventions of the invariant culture or use an ordinal comparison. For example, you would use an ordinal sort to organize the names of files, processes, mutexes, or named pipes. +- If you want the order of strings to remain unchanged across cultures, you should order them based on the conventions of the invariant culture or use an ordinal comparison. For example, you would use an ordinal sort to organize the names of files, processes, mutexes, or named pipes. -- For a comparison that involves a security decision (such as whether a username is valid), you should always perform an ordinal test for equality by calling an overload of the method. +- For a comparison that involves a security decision (such as whether a username is valid), you should always perform an ordinal test for equality by calling an overload of the method. > [!NOTE] -> The culture-sensitive sorting and casing rules used in string comparison depend on the version of the .NET. In .NET Framework 4.5 and later versions running on Windows 8 or later operating systems, sorting, casing, normalization, and Unicode character information conforms to the Unicode 6.0 standard. On earlier Windows operating systems, it conforms to the Unicode 5.0 standard. On .NET Core, it depends on the version of the Unicode Standard supported by the underlying operating system. +> The culture-sensitive sorting and casing rules used in string comparison depend on the version of the .NET. On .NET Core, string comparison depends on the version of the Unicode Standard supported by the underlying operating system. In .NET Framework 4.5 and later versions running on Windows 8 or later, sorting, casing, normalization, and Unicode character information conform to the Unicode 6.0 standard. On other Windows operating systems, they conform to the Unicode 5.0 standard. For more information about word, string, and ordinal sort rules, see the topic. For additional recommendations on when to use each rule, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). @@ -400,15 +400,15 @@ You can download the sorting weight tables, a set of text files that contain inf [!code-vb[System.String.Class#12](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Class/vb/compare2.vb#12)] > [!TIP] -> Internally, .NET uses sort keys to support culturally sensitive string comparison. Each character in a string is given several categories of sort weights, including alphabetic, case, and diacritic. A sort key, represented by the class, provides a repository of these weights for a particular string. If your app performs a large number of searching or sorting operations on the same set of strings, you can improve its performance by generating and storing sort keys for all the strings that it uses. When a sort or comparison operation is required, you use the sort keys instead of the strings. For more information, see the class. +> Internally, .NET uses sort keys to support culturally sensitive string comparison. Each character in a string is given several categories of sort weights, including alphabetic, case, and diacritic. A sort key, represented by the class, provides a repository of these weights for a particular string. If your app performs a large number of searching or sorting operations on the same set of strings, you can improve its performance by generating and storing sort keys for all the strings that it uses. When a sort or comparison operation is required, you use the sort keys instead of the strings. For more information, see the class. - If you don't specify a string comparison convention, sorting methods such as perform a culture-sensitive, case-sensitive sort on strings. The following example illustrates how changing the current culture affects the order of sorted strings in an array. It creates an array of three strings. First, it sets the `System.Threading.Thread.CurrentThread.CurrentCulture` property to en-US and calls the method. The resulting sort order is based on sorting conventions for the English (United States) culture. Next, the example sets the `System.Threading.Thread.CurrentThread.CurrentCulture` property to da-DK and calls the method again. Notice how the resulting sort order differs from the en-US results because it uses the sorting conventions for Danish (Denmark). + If you don't specify a string comparison convention, sorting methods such as perform a culture-sensitive, case-sensitive sort on strings. The following example illustrates how changing the current culture affects the order of sorted strings in an array. It creates an array of three strings. First, it sets the `System.Threading.Thread.CurrentThread.CurrentCulture` property to en-US and calls the method. The resulting sort order is based on sorting conventions for the English (United States) culture. Next, the example sets the `System.Threading.Thread.CurrentThread.CurrentCulture` property to da-DK and calls the method again. Notice how the resulting sort order differs from the en-US results because it uses the sorting conventions for Danish (Denmark). [!code-csharp[Conceptual.Strings.Comparing#3](~/samples/snippets/csharp/VS_Snippets_CLR/conceptual.strings.comparing/cs/sort1.cs#3)] [!code-vb[Conceptual.Strings.Comparing#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.strings.comparing/vb/sort1.vb#3)] > [!WARNING] -> If your primary purpose in comparing strings is to determine whether they are equal, you should call the method. Typically, you should use to perform an ordinal comparison. The method is intended primarily to sort strings. +> If your primary purpose in comparing strings is to determine whether they are equal, you should call the method. Typically, you should use to perform an ordinal comparison. The method is intended primarily to sort strings. String search methods, such as and , also can perform culture-sensitive or ordinal string comparisons. The following example illustrates the differences between ordinal and culture-sensitive comparisons using the method. A culture-sensitive search in which the current culture is English (United States) considers the substring "oe" to match the ligature "œ". Because a soft hyphen (U+00AD) is a zero-width character, the search treats the soft hyphen as equivalent to and finds a match at the beginning of the string. An ordinal search, on the other hand, does not find a match in either case. @@ -416,10 +416,10 @@ You can download the sorting weight tables, a set of text files that contain inf [!code-csharp[System.String.Class#13](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Class/cs/compare3.cs#13)] [!code-vb[System.String.Class#13](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Class/vb/compare3.vb#13)] -### Searching Strings +### Search in strings String search methods, such as and , also can perform culture-sensitive or ordinal string comparisons to determine whether a character or substring is found in a specified string. - The search methods in the class that search for an individual character, such as the method, or one of a set of characters, such as the method, all perform an ordinal search. To perform a culture-sensitive search for a character, you must call a method such as or . Note that the results of searching for a character using ordinal and culture-sensitive comparison can be very different. For example, a search for a precomposed Unicode character such as the ligature "Æ" (U+00C6) might match any occurrence of its components in the correct sequence, such as "AE" (U+041U+0045), depending on the culture. The following example illustrates the difference between the and methods when searching for an individual character. The ligature "æ" (U+00E6) is found in the string "aerial" when using the conventions of the en-US culture, but not when using the conventions of the da-DK culture or when performing an ordinal comparison. + The search methods in the class that search for an individual character, such as the method, or one of a set of characters, such as the method, all perform an ordinal search. To perform a culture-sensitive search for a character, you must call a method such as or . Note that the results of searching for a character using ordinal and culture-sensitive comparison can be very different. For example, a search for a precomposed Unicode character such as the ligature "Æ" (U+00C6) might match any occurrence of its components in the correct sequence, such as "AE" (U+041U+0045), depending on the culture. The following example illustrates the difference between the and methods when searching for an individual character. The ligature "æ" (U+00E6) is found in the string "aerial" when using the conventions of the en-US culture, but not when using the conventions of the da-DK culture or when performing an ordinal comparison. [!code-csharp[System.String.Class#22](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Class/cs/search1.cs#22)] [!code-vb[System.String.Class#22](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Class/vb/search1.vb#22)] @@ -428,10 +428,11 @@ You can download the sorting weight tables, a set of text files that contain inf ### Testing for equality - Use the method to determine the relationship of two strings in the sort order. Typically, this is a culture-sensitive operation. In contrast, call the method to test for equality. Because the test for equality usually compares user input with some known string, such as a valid user name, a password, or a file system path, it is typically an ordinal operation. + +Use the method to determine the relationship of two strings in the sort order. Typically, this is a culture-sensitive operation. In contrast, call the method to test for equality. Because the test for equality usually compares user input with some known string, such as a valid user name, a password, or a file system path, it is typically an ordinal operation. > [!WARNING] -> It is possible to test for equality by calling the method and determining whether the return value is zero. However, this practice is not recommended. To determine whether two strings are equal, you should call one of the overloads of the method. The preferred overload to call is either the instance method or the static method, because both methods include a parameter that explicitly specifies the type of comparison. +> It is possible to test for equality by calling the method and determining whether the return value is zero. However, this practice is not recommended. To determine whether two strings are equal, you should call one of the overloads of the method. The preferred overload to call is either the instance method or the static method, because both methods include a parameter that explicitly specifies the type of comparison. The following example illustrates the danger of performing a culture-sensitive comparison for equality when an ordinal one should be used instead. In this case, the intent of the code is to prohibit file system access from URLs that begin with "FILE://" or "file://" by performing a case-insensitive comparison of the beginning of a URL with the string "FILE://". However, if a culture-sensitive comparison is performed using the Turkish (Turkey) culture on a URL that begins with "file://", the comparison for equality fails, because the Turkish uppercase equivalent of the lowercase "i" is "İ" instead of "I". As a result, file system access is inadvertently permitted. On the other hand, if an ordinal comparison is performed, the comparison for equality succeeds, and file system access is denied. @@ -443,11 +444,11 @@ You can download the sorting weight tables, a set of text files that contain inf ## Normalization Some Unicode characters have multiple representations. For example, any of the following code points can represent the letter "ắ": -- U+1EAF +- U+1EAF -- U+0103 U+0301 +- U+0103 U+0301 -- U+0061 U+0306 U+0301 +- U+0061 U+0306 U+0301 Multiple representations for a single character complicate searching, sorting, matching, and other string operations. @@ -455,15 +456,15 @@ You can download the sorting weight tables, a set of text files that contain inf An ordinal comparison is a binary comparison of the Unicode scalar value of corresponding objects in each string. The class includes a number of methods that can perform an ordinal comparison, including the following: -- Any overload of the , , , , , and methods that includes a parameter. The method performs an ordinal comparison if you supply a value of or for this parameter. +- Any overload of the , , , , , and methods that includes a parameter. The method performs an ordinal comparison if you supply a value of or for this parameter. -- The overloads of the method. +- The overloads of the method. -- Methods that use ordinal comparison by default, such as , , and . +- Methods that use ordinal comparison by default, such as , , and . -- Methods that search for a value or for the elements in a array in a string instance. Such methods include and . +- Methods that search for a value or for the elements in a array in a string instance. Such methods include and . - You can determine whether a string is normalized to normalization form C by calling the method, or you can call the method to determine whether a string is normalized to a specified normalization form. You can also call the method to convert a string to normalization form C, or you can call the method to convert a string to a specified normalization form. For step-by-step information about normalizing and comparing strings, see the and methods. + You can determine whether a string is normalized to normalization form C by calling the method, or you can call the method to determine whether a string is normalized to a specified normalization form. You can also call the method to convert a string to normalization form C, or you can call the method to convert a string to a specified normalization form. For step-by-step information about normalizing and comparing strings, see the and methods. The following simple example illustrates string normalization. It defines the letter "ố" in three different ways in three different strings, and uses an ordinal comparison for equality to determine that each string differs from the other two strings. It then converts each string to the supported normalization forms, and again performs an ordinal comparison of each string in a specified normalization form. In each case, the second test for equality shows that the strings are equal. @@ -477,92 +478,100 @@ You can download the sorting weight tables, a set of text files that contain inf ## String operations by category The class provides members for comparing strings, testing strings for equality, finding characters or substrings in a string, modifying a string, extracting substrings from a string, combining strings, formatting values, copying a string, and normalizing a string. -### Comparing strings +### Compare strings You can compare strings to determine their relative position in the sort order by using the following methods: -- returns an integer that indicates the relationship of one string to a second string in the sort order. +- returns an integer that indicates the relationship of one string to a second string in the sort order. + +- returns an integer that indicates the relationship of one string to a second string based on a comparison of their code points. + +- returns an integer that indicates the relationship of the current string instance to a second string in the sort order. The method provides the and implementations for the class. -- returns an integer that indicates the relationship of one string to a second string based on a comparison of their code points. +### Test strings for equality -- returns an integer that indicates the relationship of the current string instance to a second string in the sort order. The method provides the and implementations for the class. +You call the method to determine whether two strings are equal. The instance and the static overloads let you specify whether the comparison is culture-sensitive or ordinal, and whether case is considered or ignored. Most tests for equality are ordinal, and comparisons for equality that determine access to a system resource (such as a file system object) should always be ordinal. -### Testing strings for equality - You call the method to determine whether two strings are equal. The instance and the static overloads let you specify whether the comparison is culture-sensitive or ordinal, and whether case is considered or ignored. Most tests for equality are ordinal, and comparisons for equality that determine access to a system resource (such as a file system object) should always be ordinal. +### Find characters in a string -### Finding characters in a string - The class includes two kinds of search methods: +The class includes two kinds of search methods: -- Methods that return a value to indicate whether a particular substring is present in a string instance. These include the , , and methods. +- Methods that return a value to indicate whether a particular substring is present in a string instance. These include the , , and methods. -- Methods that indicate the starting position of a substring in a string instance. These include the , , , and methods. +- Methods that indicate the starting position of a substring in a string instance. These include the , , , and methods. > [!WARNING] -> If you want to search a string for a particular pattern rather than a specific substring, you should use regular expressions. For more information, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions). +> If you want to search a string for a particular pattern rather than a specific substring, you should use regular expressions. For more information, see [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions). -### Modifying a string - The class includes the following methods that appear to modify the value of a string: +### Modify a string -- inserts a string into the current instance. +The class includes the following methods that appear to modify the value of a string: -- inserts one or more occurrences of a specified character at the beginning of a string. +- inserts a string into the current instance. -- inserts one or more occurrences of a specified character at the end of a string. +- inserts one or more occurrences of a specified character at the beginning of a string. -- deletes a substring from the current instance. +- inserts one or more occurrences of a specified character at the end of a string. -- replaces a substring with another substring in the current instance. +- deletes a substring from the current instance. -- and convert all the characters in a string to lowercase. +- replaces a substring with another substring in the current instance. -- and convert all the characters in a string to uppercase. +- and convert all the characters in a string to lowercase. -- removes all occurrences of a character from the beginning and end of a string. +- and convert all the characters in a string to uppercase. -- removes all occurrences of a character from the end of a string. +- removes all occurrences of a character from the beginning and end of a string. -- removes all occurrences of a character from the beginning of a string. +- removes all occurrences of a character from the end of a string. + +- removes all occurrences of a character from the beginning of a string. > [!IMPORTANT] -> All string modification methods return a new object. They don't modify the value of the current instance. +> All string modification methods return a new object. They don't modify the value of the current instance. + +### Extract substrings from a string + +The method separates a single string into multiple strings. Overloads of the method allow you to specify multiple delimiters, to limit the number of substrings that the method extracts, to trim white space from substrings, and to specify whether empty strings (which occur when delimiters are adjacent) are included among the returned strings. -### Extracting substrings from a string - The method separates a single string into multiple strings. Overloads of the method allow you to specify multiple delimiters, to limit the number of substrings that the method extracts, to trim white space from substrings, and to specify whether empty strings (which occur when delimiters are adjacent) are included among the returned strings. +### Combine strings -### Combining strings - The following methods can be used for string concatenation: +The following methods can be used for string concatenation: -- combines one or more substrings into a single string. +- combines one or more substrings into a single string. -- concatenates one or more substrings into a single element and adds a separator between each substring. +- concatenates one or more substrings into a single element and adds a separator between each substring. -### Formatting values - The method uses the composite formatting feature to replace one or more placeholders in a string with the string representation of some object or value. The method is often used to do the following: +### Format values -- To embed the string representation of a numeric value in a string. +The method uses the composite formatting feature to replace one or more placeholders in a string with the string representation of some object or value. The method is often used to do the following: -- To embed the string representation of a date and time value in a string. +- To embed the string representation of a numeric value in a string. -- To embed the string representation of an enumeration value in a string. +- To embed the string representation of a date and time value in a string. -- To embed the string representation of some object that supports the interface in a string. +- To embed the string representation of an enumeration value in a string. -- To right-justify or left-justify a substring in a field within a larger string. +- To embed the string representation of some object that supports the interface in a string. + +- To right-justify or left-justify a substring in a field within a larger string. For detailed information about formatting operations and examples, see the overload summary. -### Copying a string - You can call the following methods to make a copy of a string: +### Copy a string + +You can call the following methods to make a copy of a string: + +- returns a reference to an existing object. -- returns a reference to an existing object. +- creates a copy of an existing string. -- creates a copy of an existing string. +- copies a portion of a string to a character array. -- copies a portion of a string to a character array. +### Normalize a string -### Normalizing a string - In Unicode, a single character can have multiple code points. Normalization converts these equivalent characters into the same binary representation. The method performs the normalization, and the method determines whether a string is normalized. +In Unicode, a single character can have multiple code points. Normalization converts these equivalent characters into the same binary representation. The method performs the normalization, and the method determines whether a string is normalized. - For more information and an example, see the [Normalization](#Normalization) section earlier in this topic. +For more information and an example, see the [Normalization](#Normalization) section earlier in this topic. ]]> @@ -613,47 +622,49 @@ Examples of instantiating strings: ## Overloaded constructor syntax - String constructors fall into two categories: those without pointer parameters, and those with pointer parameters. The constructors that use pointers are not CLS-compliant. In addition, Visual Basic does not support the use of pointers, and C# requires code that uses pointers to run in an unsafe context. For more information, see [unsafe](/dotnet/csharp/language-reference/keywords/unsafe). - For additional guidance on choosing an overload, see [Which method do I call?](#Tasks) +String constructors fall into two categories: those without pointer parameters, and those with pointer parameters. The constructors that use pointers are not CLS-compliant. In addition, Visual Basic does not support the use of pointers, and C# requires code that uses pointers to run in an unsafe context. For more information, see [unsafe](/dotnet/csharp/language-reference/keywords/unsafe). - `String(Char[] value)` +For additional guidance on choosing an overload, see [Which method do I call?](#Tasks). + + `String(Char[] value)`\ Initializes the new instance to the value indicated by an array of Unicode characters. This constructor copies Unicode characters([example](#Ctor2_Example)). - `String(Char[] value, Int32 startIndex, Int32 length)` + `String(Char[] value, Int32 startIndex, Int32 length)`\ Initializes the new instance to the value indicated by an array of Unicode characters, a starting character position within that array, and a length ([example](#Ctor3_Example)). - `String(Char c, Int32 count)` + `String(Char c, Int32 count)`\ Initializes the new instance to the value indicated by a specified Unicode character repeated a specified number of times ([example](#Ctor3_Example)). - `String(char* value)` + `String(char* value)`\ **(Not CLS-compliant)** Initializes the new instance to the value indicated by a pointer to an array of Unicode characters that is terminated by a null character (U+0000 or '\0'). ([example](#Ctor4_Example)). Permission: , requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code. - `String(char* value, Int32 startIndex, Int32 length)` + `String(char* value, Int32 startIndex, Int32 length)`\ **(Not CLS-compliant)** Initializes the new instance to the value indicated by a pointer to an array of Unicode characters, a starting character position within that array, and a length. The constructor copies the Unicode characters from `value` starting at index `startIndex` and ending at index `startIndex` + `length` - 1 ([example](#Ctor5_Example)). Permission: , requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code. - `String(SByte* value)` + `String(SByte* value)`\ **(Not CLS-compliant)** Initializes the new instance to the value indicated by a pointer to an array of 8-bit signed integers. The array is assumed to represent a string encoded using the current system code page (that is, the encoding specified by ). The constructor processes characters from `value` starting from the location specified by the pointer until a null character (0x00) is reached ([example](#Ctor6_Example)). Permission: , requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code. - `String(SByte* value, Int32 startIndex, Int32 length)` + `String(SByte* value, Int32 startIndex, Int32 length)`\ **(Not CLS-compliant)** Initializes the new instance to the value indicated by a pointer to an array of 8-bit signed integers, a starting position within that array, and a length. The array is assumed to represent a string encoded using the current system code page (that is, the encoding specified by ). The constructor processes characters from value starting at `startIndex` and ending at `startIndex` + `length` - 1 ([example](#Ctor6_Example)). Permission: , requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code. - `String(SByte* value, Int32 startIndex, Int32 length, Encoding enc)` + `String(SByte* value, Int32 startIndex, Int32 length, Encoding enc)`\ **(Not CLS-compliant)** Initializes the new instance to the value indicated by a pointer to an array of 8-bit signed integers, a starting position within that array, a length, and an object. Permission: , requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code. ## Parameters - Here is a complete list of parameters used by constructors that don't include a pointer parameter. For the parameters used by each overload, see the overload syntax above. + +Here is a complete list of parameters used by constructors that don't include a pointer parameter. For the parameters used by each overload, see the overload syntax above. |Parameter|Type|Description| |---------------|----------|-----------------| @@ -678,17 +689,17 @@ Examples of instantiating strings: |Exception|Condition|Thrown by| |---------------|---------------|---------------| -||`value` is `null`.|| -||`startIndex`,`length`, or `count` is less than zero.

-or-

The sum of `startIndex` and `length` is greater than the number of elements in `value`.

-or-

`count` is less than zero.|

| +||`value` is `null`.|| +||`startIndex`,`length`, or `count` is less than zero.

-or-

The sum of `startIndex` and `length` is greater than the number of elements in `value`.

-or-

`count` is less than zero.|

| Here's a list of exceptions thrown by constructors that include pointer parameters. |Exception|Condition|Thrown by| |---------------|---------------|---------------| ||`value` specifies an array that contains an invalid Unicode character.

-or-

`value` or `value` + `startIndex` specifies an address that is less than 64K.

-or-

A new instance could not be initialized from the `value` byte array because `value` does not use the default code page encoding.|All constructors with pointers.| -||`value` is null.|



| +||`value` is null.|



| ||The current process does not have read access to all the addressed characters.

-or-

`startIndex` or `length` is less than zero, `value` + `startIndex` cause a pointer overflow, or the current process does not have read access to all the addressed characters.

-or-

The length of the new string is too large to allocate.|All constructors with pointers.| -||`value`, or `value` + `startIndex` + `length` - 1, specifies an invalid address.|



| +||`value`, or `value` + `startIndex` + `length` - 1, specifies an invalid address.|



| ## Which method do I call? @@ -696,100 +707,108 @@ Examples of instantiating strings: |To|Call or use| |--------|-----------------| |Create a string.|Assignment from a string literal or an existing string ([example](#Ctor1_Example))| -|Create a string from an entire character array.| ([example](#Ctor2_Example))| -|Create a string from a portion of a character array.| ([example](#Ctor3_Example))| -|Create a string that repeats the same character multiple times.| ([example](#Ctor3_Example))| -|Create a string from a pointer to a Unicode or wide character array.|| -|Create a string from a portion of a Unicode or wide character array by using its pointer.|| -|Create a string from a C++ `char` array.|,

-or-

| +|Create a string from an entire character array.| ([example](#Ctor2_Example))| +|Create a string from a portion of a character array.| ([example](#Ctor3_Example))| +|Create a string that repeats the same character multiple times.| ([example](#Ctor3_Example))| +|Create a string from a pointer to a Unicode or wide character array.|| +|Create a string from a portion of a Unicode or wide character array by using its pointer.|| +|Create a string from a C++ `char` array.|,

-or-

| |Create a string from ASCII characters.|| ## Create strings - The most commonly used technique for creating strings programmatically is simple assignment, as illustrated in [this example](#Ctor1_Example). The class also includes four types of constructor overloads that let you create strings from the following values: -- From a character array (an array of UTF-16-encoded characters). You can create a new object from the characters in the entire array or a portion of it. The constructor copies all the characters in the array to the new string. The constructor copies the characters from index `startIndex` to index `startIndex` + `length` - 1 to the new string. If `length` is zero, the value of the new string is . +The most commonly used technique for creating strings programmatically is simple assignment, as illustrated in [this example](#Ctor1_Example). The class also includes four types of constructor overloads that let you create strings from the following values: + +- From a character array (an array of UTF-16-encoded characters). You can create a new object from the characters in the entire array or a portion of it. The constructor copies all the characters in the array to the new string. The constructor copies the characters from index `startIndex` to index `startIndex` + `length` - 1 to the new string. If `length` is zero, the value of the new string is . - If your code repeatedly instantiates strings that have the same value, you can improve application performance by using an alternate means of creating strings. For more information, see [Handling repetitive strings](#Repetitive). + If your code repeatedly instantiates strings that have the same value, you can improve application performance by using an alternate means of creating strings. For more information, see [Handling repetitive strings](#Repetitive). -- From a single character that is duplicated zero, one, or more times, by using the constructor. If `count` is zero, the value of the new string is . +- From a single character that is duplicated zero, one, or more times, by using the constructor. If `count` is zero, the value of the new string is . -- From a pointer to a null-terminated character array, by using the or constructor. Either the entire array or a specified range can be used to initialize the string. The constructor copies a sequence of Unicode characters starting from the specified pointer or from the specified pointer plus `startIndex` and continuing to the end of the array or for `length` characters. If `value` is a null pointer or `length` is zero, the constructor creates a string whose value is . If the copy operation proceeds to the end of the array and the array is not null-terminated, the constructor behavior is system-dependent. Such a condition might cause an access violation. +- From a pointer to a null-terminated character array, by using the or constructor. Either the entire array or a specified range can be used to initialize the string. The constructor copies a sequence of Unicode characters starting from the specified pointer or from the specified pointer plus `startIndex` and continuing to the end of the array or for `length` characters. If `value` is a null pointer or `length` is zero, the constructor creates a string whose value is . If the copy operation proceeds to the end of the array and the array is not null-terminated, the constructor behavior is system-dependent. Such a condition might cause an access violation. - If the array contains any embedded null characters (U+0000 or '\0') and the overload is called, the string instance contains `length` characters including any embedded nulls. The following example shows what happens when a pointer to an array of 10 elements that includes two null characters is passed to the method. Because the address is the beginning of the array and all elements in the array are to be added to the string, the constructor instantiates a string with ten characters, including two embedded nulls. On the other hand, if the same array is passed to the constructor, the result is a four-character string that does not include the first null character. + If the array contains any embedded null characters (U+0000 or '\0') and the overload is called, the string instance contains `length` characters including any embedded nulls. The following example shows what happens when a pointer to an array of 10 elements that includes two null characters is passed to the method. Because the address is the beginning of the array and all elements in the array are to be added to the string, the constructor instantiates a string with ten characters, including two embedded nulls. On the other hand, if the same array is passed to the constructor, the result is a four-character string that does not include the first null character. - [!code-cpp[System.String.ctor#5](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/chptrctor_null.cpp#5)] - [!code-csharp[System.String.ctor#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.ctor/cs/chptrctor_null.cs#5)] + [!code-cpp[System.String.ctor#5](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/chptrctor_null.cpp#5)] + [!code-csharp[System.String.ctor#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.ctor/cs/chptrctor_null.cs#5)] - The array must contain Unicode characters. In C++, this means that the character array must be defined either as the managed [] type or the unmanaged`wchar_t`[] type. + The array must contain Unicode characters. In C++, this means that the character array must be defined either as the managed [] type or the unmanaged`wchar_t`[] type. - If the overload is called and the array is not null-terminated, or if the overload is called and `startIndex` + `length`-1 includes a range that is outside the memory allocated for the sequence of characters, the behavior of the constructor is system-dependent, and an access violation may occur. + If the overload is called and the array is not null-terminated, or if the overload is called and `startIndex` + `length`-1 includes a range that is outside the memory allocated for the sequence of characters, the behavior of the constructor is system-dependent, and an access violation may occur. -- From a pointer to a signed byte array. Either the entire array or a specified range can be used to initialize the string. The sequence of bytes can be interpreted by using the default code page encoding, or an encoding can be specified in the constructor call. If the constructor tries to instantiate a string from an entire array that is not null-terminated, or if the range of the array from `value` + `startIndex` to `value` + `startIndex` + `length` -1 is outside of the memory allocated for the array, the behavior of this constructor is system-dependent, and an access violation may occur. +- From a pointer to a signed byte array. Either the entire array or a specified range can be used to initialize the string. The sequence of bytes can be interpreted by using the default code page encoding, or an encoding can be specified in the constructor call. If the constructor tries to instantiate a string from an entire array that is not null-terminated, or if the range of the array from `value` + `startIndex` to `value` + `startIndex` + `length` -1 is outside of the memory allocated for the array, the behavior of this constructor is system-dependent, and an access violation may occur. - The three constructors that include a signed byte array as a parameter are designed primarily to convert a C++ `char` array to a string, as shown in this example: + The three constructors that include a signed byte array as a parameter are designed primarily to convert a C++ `char` array to a string, as shown in this example: - [!code-cpp[System.String.Ctor#4](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/sbyte_ctor1.cpp#4)] + [!code-cpp[System.String.Ctor#4](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/sbyte_ctor1.cpp#4)] - If the array contains any null characters ('\0') or bytes whose value is 0 and the overload is called, the string instance contains `length` characters including any embedded nulls. The following example shows what happens when a pointer to an array of 10 elements that includes two null characters is passed to the method. Because the address is the beginning of the array and all elements in the array are to be added to the string, the constructor instantiates a string with ten characters, including two embedded nulls. On the other hand, if the same array is passed to the constructor, the result is a four-character string that does not include the first null character. + If the array contains any null characters ('\0') or bytes whose value is 0 and the overload is called, the string instance contains `length` characters including any embedded nulls. The following example shows what happens when a pointer to an array of 10 elements that includes two null characters is passed to the method. Because the address is the beginning of the array and all elements in the array are to be added to the string, the constructor instantiates a string with ten characters, including two embedded nulls. On the other hand, if the same array is passed to the constructor, the result is a four-character string that does not include the first null character. - [!code-cpp[System.String.ctor#6](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/ptrctor_null.cpp#6)] - [!code-csharp[System.String.ctor#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.ctor/cs/ptrctor_null.cs#6)] + [!code-cpp[System.String.ctor#6](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/ptrctor_null.cpp#6)] + [!code-csharp[System.String.ctor#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.ctor/cs/ptrctor_null.cs#6)] - Because the and constructors interpret `value` by using the default ANSI code page, calling these constructors with identical byte arrays may create strings that have different values on different systems. + Because the and constructors interpret `value` by using the default ANSI code page, calling these constructors with identical byte arrays may create strings that have different values on different systems. ## Handle repetitive strings - Apps that parse or decode streams of text often use the constructor or the method to convert sequences of characters into a string. Repeatedly creating new strings with the same value instead of creating and reusing one string wastes memory. If you are likely to create the same string value repeatedly by calling the constructor, even if you don't know in advance what those identical string values may be, you can use a lookup table instead. - For example, suppose you read and parse a stream of characters from a file that contains XML tags and attributes. When you parse the stream, you repeatedly encounter certain tokens (that is, sequences of characters that have a symbolic meaning). Tokens equivalent to the strings "0", "1", "true", and "false" are likely to occur frequently in an XML stream. +Apps that parse or decode streams of text often use the constructor or the method to convert sequences of characters into a string. Repeatedly creating new strings with the same value instead of creating and reusing one string wastes memory. If you are likely to create the same string value repeatedly by calling the constructor, even if you don't know in advance what those identical string values may be, you can use a lookup table instead. - Instead of converting each token into a new string, you can create a object to hold commonly occurring strings. The object improves performance, because it retrieves stored strings without allocating temporary memory. When you encounter a token, use the method to retrieve the token from the table. If the token exists, the method returns the corresponding string. If the token does not exist, use the method to insert the token into the table and to get the corresponding string. +For example, suppose you read and parse a stream of characters from a file that contains XML tags and attributes. When you parse the stream, you repeatedly encounter certain tokens (that is, sequences of characters that have a symbolic meaning). Tokens equivalent to the strings "0", "1", "true", and "false" are likely to occur frequently in an XML stream. + +Instead of converting each token into a new string, you can create a object to hold commonly occurring strings. The object improves performance, because it retrieves stored strings without allocating temporary memory. When you encounter a token, use the method to retrieve the token from the table. If the token exists, the method returns the corresponding string. If the token does not exist, use the method to insert the token into the table and to get the corresponding string. ## Example 1: Use string assignment - The following example creates a new string by assigning it a string literal. It creates a second string by assigning the value of the first string to it. These are the two most common ways to instantiate a new object. - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/assignment.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.ctor/cs/ctor1.cs" interactive="try-dotnet" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.ctor/vb/ctor1.vb" id="Snippet1"::: +The following example creates a new string by assigning it a string literal. It creates a second string by assigning the value of the first string to it. These are the two most common ways to instantiate a new object. + +:::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/assignment.cpp" id="Snippet1"::: +:::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.ctor/cs/ctor1.cs" interactive="try-dotnet" id="Snippet1"::: +:::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.ctor/vb/ctor1.vb" id="Snippet1"::: ## Example 2: Use a character array - The following example demonstrates how to create a new object from a character array. - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/stringexample1/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/stringexample1/CS/source.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/stringexample1/VB/source.vb" id="Snippet1"::: +The following example demonstrates how to create a new object from a character array. + +:::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/stringexample1/CPP/source.cpp" id="Snippet1"::: +:::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/stringexample1/CS/source.cs" interactive="try-dotnet-method" id="Snippet1"::: +:::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/stringexample1/VB/source.vb" id="Snippet1"::: ## Example 3: Use a portion of a character array and repeating a single character - The following example demonstrates how to create a new object from a portion of a character array, and how to create a new object that contains multiple occurrences of a single character. - :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/stringexample1/CPP/source.cpp" id="Snippet3"::: - :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/stringexample1/CS/source.cs" interactive="try-dotnet-method" id="Snippet3"::: - :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/stringexample1/VB/source.vb" id="Snippet3"::: +The following example demonstrates how to create a new object from a portion of a character array, and how to create a new object that contains multiple occurrences of a single character. + +:::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/stringexample1/CPP/source.cpp" id="Snippet3"::: +:::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/stringexample1/CS/source.cs" interactive="try-dotnet-method" id="Snippet3"::: +:::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR/stringexample1/VB/source.vb" id="Snippet3"::: ## Example 4: Use a pointer to a character array - The following example demonstrates how to create a new object from a pointer to an array of characters. The C# example must be compiled by using the `/unsafe` compiler switch. - [!code-cpp[System.String.Ctor#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/char1_ctor.cpp#2)] - [!code-csharp[System.String.Ctor#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.ctor/cs/ctor2.cs#2)] +The following example demonstrates how to create a new object from a pointer to an array of characters. The C# example must be compiled by using the `/unsafe` compiler switch. + +[!code-cpp[System.String.Ctor#2](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/char1_ctor.cpp#2)] +[!code-csharp[System.String.Ctor#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.ctor/cs/ctor2.cs#2)] ## Example 5: Instantiate a string from a pointer and a range of an array - The following example examines the elements of a character array for either a period or an exclamation point. If one is found, it instantiates a string from the characters in the array that precede the punctuation symbol. If not, it instantiates a string with the entire contents of the array. The C# example must be compiled using the `/unsafe` compiler switch. - [!code-cpp[System.String.Ctor#3](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/char2_ctor.cpp#3)] - [!code-csharp[System.String.Ctor#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.ctor/cs/char2_ctor.cs#3)] +The following example examines the elements of a character array for either a period or an exclamation point. If one is found, it instantiates a string from the characters in the array that precede the punctuation symbol. If not, it instantiates a string with the entire contents of the array. The C# example must be compiled using the `/unsafe` compiler switch. + +[!code-cpp[System.String.Ctor#3](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.ctor/cpp/char2_ctor.cpp#3)] +[!code-csharp[System.String.Ctor#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.ctor/cs/char2_ctor.cs#3)] ## Example 6: Instantiate a string from a pointer to a signed byte array - The following example demonstrates how you can create an instance of the class with the constructor. - [!code-cpp[stringexample1#2](~/samples/snippets/cpp/VS_Snippets_CLR/stringexample1/CPP/source.cpp#2)] - [!code-csharp[stringexample1#2](~/samples/snippets/csharp/VS_Snippets_CLR/stringexample1/CS/source.cs#2)] +The following example demonstrates how you can create an instance of the class with the constructor. + +[!code-cpp[stringexample1#2](~/samples/snippets/cpp/VS_Snippets_CLR/stringexample1/CPP/source.cpp#2)] +[!code-csharp[stringexample1#2](~/samples/snippets/csharp/VS_Snippets_CLR/stringexample1/CS/source.cs#2)] ]]> @@ -847,7 +866,7 @@ Examples of instantiating strings: ## Remarks > [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. ]]> @@ -905,7 +924,7 @@ Examples of instantiating strings: ## Remarks > [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. ]]> @@ -989,7 +1008,7 @@ Examples of instantiating strings: ## Remarks > [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. ]]> @@ -1052,7 +1071,7 @@ Examples of instantiating strings: ## Remarks > [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. ]]> @@ -1116,7 +1135,7 @@ Examples of instantiating strings: ## Remarks > [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. ]]> @@ -1179,7 +1198,7 @@ Examples of instantiating strings: ## Remarks > [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. ]]> @@ -1245,7 +1264,7 @@ Examples of instantiating strings: ## Remarks > [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. ]]> @@ -1325,7 +1344,7 @@ Examples of instantiating strings: ## Remarks > [!NOTE] -> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. +> For examples and comprehensive usage information about this and other `String` constructor overloads, see the constructor summary. ]]> @@ -1410,8 +1429,6 @@ Examples of instantiating strings: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.chars/cs/chars1.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.chars/vb/chars1.vb" id="Snippet1"::: - - ## Examples The following example demonstrates how you can use this indexer in a routine to validate a string. @@ -1502,7 +1519,7 @@ Examples of instantiating strings: |Greater than zero|The first substring follows the second substring in the sort order.| > [!WARNING] -> Whenever possible, you should call an overload of the method that includes a parameter. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). +> Whenever possible, you should call an overload of the method that includes a parameter. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). ]]> @@ -1585,7 +1602,7 @@ Examples of instantiating strings: The comparison is performed using word sort rules. For more information about word, string, and ordinal sorts, see . > [!WARNING] -> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). +> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. @@ -1603,10 +1620,8 @@ Examples of instantiating strings: [!code-csharp[System.String.Compare#11](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Compare/cs/remarks.cs#11)] [!code-vb[System.String.Compare#11](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb#11)] - - ## Examples - The following example calls the method to compare three sets of strings. + The following example calls the method to compare three sets of strings. [!code-cpp[System.String.Compare#18](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/compare02.cpp#18)] [!code-csharp-interactive[System.String.Compare#18](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Compare/cs/compare02.cs#18)] @@ -1710,7 +1725,7 @@ Examples of instantiating strings: The comparison is performed using word sort rules. For more information about word, string, and ordinal sorts, see . > [!WARNING] -> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). +> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. @@ -1728,10 +1743,8 @@ Examples of instantiating strings: [!code-csharp[System.String.Compare#13](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Compare/cs/remarks.cs#13)] [!code-vb[System.String.Compare#13](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb#13)] - - ## Examples - The following example demonstrates that the method is equivalent to using or when comparing strings. + The following example demonstrates that the method is equivalent to using or when comparing strings. [!code-cpp[System.String.Compare#18](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.String.Compare/cpp/compare02.cpp#18)] [!code-csharp-interactive[System.String.Compare#18](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Compare/cs/compare02.cs#18)] @@ -1843,8 +1856,6 @@ Examples of instantiating strings: [!code-csharp[System.String.Compare#17](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Compare/cs/remarks.cs#17)] [!code-vb[System.String.Compare#17](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb#17)] - - ## Examples The following example compares three versions of the letter "I". The results are affected by the choice of culture, whether case is ignored, and whether an ordinal comparison is performed. @@ -1959,8 +1970,6 @@ Examples of instantiating strings: [!code-csharp[System.String.Compare#15](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Compare/cs/remarks.cs#15)] [!code-vb[System.String.Compare#15](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb#15)] - - ## Examples The following example demonstrates how culture can affect a comparison. In Czech - Czech Republic culture, "ch" is a single character that is greater than "d". However, in English - United States culture, "ch" consists of two characters, and "c" is less than "d". @@ -2060,7 +2069,7 @@ Examples of instantiating strings: The comparison uses the `culture` parameter to obtain culture-specific information, such as casing rules and the alphabetical order of individual characters. For example, a particular culture could specify that certain combinations of characters be treated as a single character, that uppercase and lowercase characters be compared in a particular way, or that the sort order of a character depends on the characters that precede or follow it. > [!CAUTION] -> The method is designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent (that is, when the purpose of the method call is to test for a return value of zero). To determine whether two strings are equivalent, call the method. +> The method is designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent (that is, when the purpose of the method call is to test for a return value of zero). To determine whether two strings are equivalent, call the method. The comparison can be further specified by the `options` parameter, which consists of one or more members of the enumeration. However, because the purpose of this method is to conduct a culture-sensitive string comparison, the and values have no effect. @@ -2068,8 +2077,6 @@ Examples of instantiating strings: The comparison terminates when an inequality is discovered or both strings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, the string with the remaining characters is considered greater. - - ## Examples The following example compares two strings in three different ways: Use linguistic comparison for the en-US culture; using linguistic case-sensitive comparison for the en-US culture; and using an ordinal comparison. It illustrates how the three methods of comparison produce three different results. @@ -2171,7 +2178,7 @@ Examples of instantiating strings: The comparison is performed using word sort rules. For more information about word, string, and ordinal sorts, see . > [!WARNING] -> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). +> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. @@ -2189,8 +2196,6 @@ Examples of instantiating strings: [!code-csharp[System.String.Compare#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Compare/cs/remarks.cs#3)] [!code-vb[System.String.Compare#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb#3)] - - ## Examples The following example compares two substrings. @@ -2301,7 +2306,7 @@ Examples of instantiating strings: The comparison is performed using word sort rules. For more information about word, string, and ordinal sorts, see . > [!WARNING] -> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). +> When comparing strings, you should call the method, which requires that you explicitly specify the type of string comparison that the method uses. For more information, see [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings). One or both comparands can be `null`. By definition, any string, including the empty string (""), compares greater than a null reference; and two null references compare equal to each other. @@ -2319,8 +2324,6 @@ Examples of instantiating strings: [!code-csharp[System.String.Compare#5](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Compare/cs/remarks.cs#5)] [!code-vb[System.String.Compare#5](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb#5)] - - ## Examples The following example performs two comparisons of two substrings that only differ in case. The first comparison ignores case and the second comparison considers case. @@ -2452,8 +2455,6 @@ Examples of instantiating strings: [!code-csharp[System.String.Compare#9](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Compare/cs/remarks.cs#9)] [!code-vb[System.String.Compare#9](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb#9)] - - ## Examples The following example compares two substrings. @@ -2583,8 +2584,6 @@ Examples of instantiating strings: [!code-csharp[System.String.Compare#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Compare/cs/remarks.cs#7)] [!code-vb[System.String.Compare#7](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare/vb/remarks.vb#7)] - - ## Examples The following example compares two substrings using different cultures and ignoring the case of the substrings. The choice of culture affects how the letter "I" is compared. @@ -2695,7 +2694,7 @@ Examples of instantiating strings: The comparison uses the `culture` parameter to obtain culture-specific information, such as casing rules and the alphabetical order of individual characters. For example, a particular culture could specify that certain combinations of characters be treated as a single character, that uppercase and lowercase characters be compared in a particular way, or that the sort order of a character depends on the characters that precede or follow it. > [!CAUTION] -> The method is designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two substrings are equivalent (that is, when the purpose of the method call is to test for a return value of zero). To determine whether two strings are equivalent, call the method. +> The method is designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two substrings are equivalent (that is, when the purpose of the method call is to test for a return value of zero). To determine whether two strings are equivalent, call the method. One or both of `strA` and `strB` can be `null`. By definition, any string, including , compares greater than a null reference, and two null references compare equal to each other. @@ -2703,10 +2702,8 @@ Examples of instantiating strings: The comparison terminates when an inequality is discovered or both substrings have been compared. However, if the two strings compare equal to the end of one string, and the other string has characters remaining, the string with the remaining characters is considered greater. The return value is the result of the last comparison performed. - - ## Examples - The following example uses the method to compare the last names of two people. It then lists them in alphabetical order. + The following example uses the method to compare the last names of two people. It then lists them in alphabetical order. :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Compare5/cs/Example.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Compare5/vb/Example.vb" id="Snippet1"::: @@ -2821,11 +2818,9 @@ Examples of instantiating strings: . To perform a case-insensitive comparison using ordinal sort rules, call the method with the `comparisonType` argument set to . - - Because is a static method, `strA` and `strB` can be `null`. If both values are `null`, the method returns 0 (zero), which indicates that `strA` and `strB` are equal. If only one of the values is `null`, the method considers the non-null value to be greater. - + This method performs a case-sensitive comparison using ordinal sort rules. For more information about word, string, and ordinal sorts, see . To perform a case-insensitive comparison using ordinal sort rules, call the method with the `comparisonType` argument set to . + Because is a static method, `strA` and `strB` can be `null`. If both values are `null`, the method returns 0 (zero), which indicates that `strA` and `strB` are equal. If only one of the values is `null`, the method considers the non-null value to be greater. ## Examples The following example performs and ordinal comparison of two strings that only differ in case. @@ -2926,11 +2921,9 @@ Examples of instantiating strings: The number of characters compared is the lesser of the length of `strA` less `indexA`, the length of `strB` less `indexB`, and `length`. - This method performs a case-sensitive comparison using ordinal sort rules. For more information about word, string, and ordinal sorts, see . To perform a case-insensitive comparison using ordinal sort rules, call the method with the `comparisonType` argument set to . - - Because is a static method, `strA` and `strB` can be `null`. If both values are `null`, the method returns 0 (zero), which indicates that `strA` and `strB` are equal. If only one of the values is `null`, the method considers the non-null value to be greater. - + This method performs a case-sensitive comparison using ordinal sort rules. For more information about word, string, and ordinal sorts, see . To perform a case-insensitive comparison using ordinal sort rules, call the method with the `comparisonType` argument set to . + Because is a static method, `strA` and `strB` can be `null`. If both values are `null`, the method returns 0 (zero), which indicates that `strA` and `strB` are equal. If only one of the values is `null`, the method considers the non-null value to be greater. ## Examples This following example demonstrates that and use different sort orders. @@ -3049,13 +3042,11 @@ Examples of instantiating strings: `value` must be a object. > [!CAUTION] -> The method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the method. +> The method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the method. This method performs a word (case-sensitive and culture-sensitive) comparison using the current culture. For more information about word, string, and ordinal sorts, see . - For more information about the behavior of this method, see the Remarks section of the method. - - + For more information about the behavior of this method, see the Remarks section of the method. ## Examples The following example uses the method with an . Because it attempts to compare a instance to a `TestClass` object, the method throws an . @@ -3162,13 +3153,11 @@ Examples of instantiating strings: This method performs a word (case-sensitive and culture-sensitive) comparison using the current culture. For more information about word, string, and ordinal sorts, see . > [!CAUTION] -> The method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the method. - - For more information about the behavior of this method, see the Remarks section of the method. - - This method implements the interface and performs slightly better than the method, because it does not have to determine whether the `strB` argument is a mutable value type that must be boxed, and it does not have to cast its parameter from an to a . +> The method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the method. + For more information about the behavior of this method, see the Remarks section of the method. + This method implements the interface and performs slightly better than the method, because it does not have to determine whether the `strB` argument is a mutable value type that must be boxed, and it does not have to cast its parameter from an to a . ## Examples The following example uses the method to compare the current string instance with another string. @@ -3212,7 +3201,7 @@ Examples of instantiating strings: [!NOTE] -> You can also use your language's string concatenation operator, such as `+` in C#, or `&` and `+` in Visual Basic, to concatenate strings. Both compilers translate the concatenation operator into a call to one of the overloads of `String.Concat`. +> You can also use your language's string concatenation operator, such as `+` in C#, or `&` and `+` in Visual Basic, to concatenate strings. Both compilers translate the concatenation operator into a call to one of the overloads of `String.Concat`. ]]> @@ -3268,19 +3257,19 @@ Examples of instantiating strings: method. + The method concatenates each object in `values`; it does not add any delimiters. To specify a delimiter between each member of `values`, call the method. An string is used in place of any null element in `values`. If `values` is an empty `IEnumerable(Of String)`, the method returns . If `values` is `null`, the method throws an exception. - is a convenience method that lets you concatenate each element in an `IEnumerable(Of String)` collection without first converting the elements to a string array. It is particularly useful with Language-Integrated Query (LINQ) query expressions. The following example passes a `List(Of String)` object that contains either the uppercase or lowercase letters of the alphabet to a lambda expression that selects letters that are equal to or greater than a particular letter (which, in the example, is "M"). The `IEnumerable(Of String)` collection that is returned by the method is passed to the method to display the result as a single string. + is a convenience method that lets you concatenate each element in an `IEnumerable(Of String)` collection without first converting the elements to a string array. It is particularly useful with Language-Integrated Query (LINQ) query expressions. The following example passes a `List(Of String)` object that contains either the uppercase or lowercase letters of the alphabet to a lambda expression that selects letters that are equal to or greater than a particular letter (which, in the example, is "M"). The `IEnumerable(Of String)` collection that is returned by the method is passed to the method to display the result as a single string. :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.concat/cs/concat2.cs" interactive="try-dotnet" id="Snippet3"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat2.vb" id="Snippet3"::: ## Examples - The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type , which it then passes to the method. + The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type , which it then passes to the method. :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.concat/cs/concat1.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat1.vb" id="Snippet2"::: @@ -3337,9 +3326,7 @@ Examples of instantiating strings: method represents `arg0` as a string by calling its parameterless `ToString` method. - - + The method represents `arg0` as a string by calling its parameterless `ToString` method. ## Examples The following example demonstrates the method. @@ -3411,8 +3398,6 @@ Examples of instantiating strings: is used in place of any null object in the array. - - ## Examples The following example demonstrates the use of the method with an array. @@ -3494,8 +3479,6 @@ Examples of instantiating strings: An string is used in place of any null object in the array. - - ## Examples The following example demonstrates the use of the method with a array. @@ -3565,8 +3548,6 @@ Examples of instantiating strings: If either of the arguments is an array reference, the method concatenates a string representing that array, instead of its members (for example, "System.String[]"). - - ## Examples The following example demonstrates the method. @@ -3739,8 +3720,6 @@ Examples of instantiating strings: is used in place of any null argument. - - ## Examples The following example demonstrates the method. @@ -3915,19 +3894,17 @@ Examples of instantiating strings: ## Remarks > [!NOTE] -> This API is not CLS-compliant. The CLS-compliant alternative is . The C# and Visual Basic compilers automatically resolve a call to this method as a call to . +> This API is not CLS-compliant. The CLS-compliant alternative is . The C# and Visual Basic compilers automatically resolve a call to this method as a call to . The method concatenates each object in the parameter list by calling its parameterless `ToString` method; it does not add any delimiters. is used in place of any null argument. > [!NOTE] -> The last parameter of the method is an optional comma-delimited list of one or more additional objects to concatenate. - - +> The last parameter of the method is an optional comma-delimited list of one or more additional objects to concatenate. ## Examples - The following example illustrates the use of the method to concatenate a list of variable parameters. In this case, the method is called with nine parameters. + The following example illustrates the use of the method to concatenate a list of variable parameters. In this case, the method is called with nine parameters. :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.concat/cs/concat4.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat4.vb" id="Snippet1"::: @@ -4039,7 +4016,7 @@ Examples of instantiating strings: The method concatenates `str0`, `str1`, `str2`, and `str3`; it does not add any delimiters. ## Examples - The following example defines an array of four-letter words and stores their individual letters to a string array in order to scramble them. It then calls the method to reassemble the scrambled words. + The following example defines an array of four-letter words and stores their individual letters to a string array in order to scramble them. It then calls the method to reassemble the scrambled words. :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.concat/cs/concat4.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat4.vb" id="Snippet1"::: @@ -4106,12 +4083,10 @@ Examples of instantiating strings: An string is used in place of any null argument. - is a convenience method that lets you concatenate each element in an collection without first converting the elements to strings. It is particularly useful with Language-Integrated Query (LINQ) query expressions, as the example illustrates. The string representation of each object in the collection is derived by calling that object's `ToString` method. - - + is a convenience method that lets you concatenate each element in an collection without first converting the elements to strings. It is particularly useful with Language-Integrated Query (LINQ) query expressions, as the example illustrates. The string representation of each object in the collection is derived by calling that object's `ToString` method. ## Examples - The following example defines a very simple `Animal` class that contains the name of an animal and the order to which it belongs. It then defines a object to contain a number of `Animal` objects. The extension method is called to extract the `Animal` objects whose `Order` property equals "Rodent". The result is passed to the method and displayed to the console. + The following example defines a very simple `Animal` class that contains the name of an animal and the order to which it belongs. It then defines a object to contain a number of `Animal` objects. The extension method is called to extract the `Animal` objects whose `Order` property equals "Rodent". The result is passed to the method and displayed to the console. :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.concat/cs/concat3.cs" interactive="try-dotnet" id="Snippet4"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.concat/vb/concat3.vb" id="Snippet4"::: @@ -4222,13 +4197,10 @@ To perform a culture-sensitive or ordinal case-insensitive comparison: - On .NET Framework: Create a custom method. The following example illustrates one such approach. It defines a extension method that includes a parameter and indicates whether a string contains a substring when using the specified form of string comparison. - [!code-csharp[System.String.Contains#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/System.String.Contains/cs/ContainsExt1.cs#1)] - [!code-vb[System.String.Contains#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Contains/vb/ContainsExt1.vb#1)] - - The following example then calls the `Contains` extension method to determine whether a substring is found in a string when using ordinal comparison and case-insensitive ordinal comparison. + [!code-csharp[System.String.Contains#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/System.String.Contains/cs/ContainsExt1.cs#2)] + [!code-vb[System.String.Contains#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Contains/vb/ContainsExt1.vb#2)] - [!code-csharp[System.String.Contains#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/System.String.Contains/cs/ContainsExt1.cs#2)] - [!code-vb[System.String.Contains#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Contains/vb/ContainsExt1.vb#2)] + If you are interested in the position of the substring `value` in the current instance, you can call the method to get the starting position of its first occurrence, or you can call the method to get the starting position of its last occurrence. The example includes a call to the method if a substring is found in a string instance. ## Examples The following example determines whether the string "fox" is a substring of a familiar quotation. If "fox" is found in the string, it also displays its starting position. @@ -4378,7 +4350,7 @@ To perform a culture-sensitive or ordinal case-insensitive comparison: The `Copy` method returns a object that has the same value as the original string but represents a different object reference. It differs from an assignment operation, which assigns an existing string reference to an additional object variable. > [!IMPORTANT] -> Starting with .NET Core 3.0, this method is obsolete. However, we do not recommend its use in any .NET implementation. In particular, because of changes in string interning in .NET Core 3.0, in some cases the `Copy` method will not create a new string but will simply return a reference to an existing interned string. +> Starting with .NET Core 3.0, this method is obsolete. However, we do not recommend its use in any .NET implementation. In particular, because of changes in string interning in .NET Core 3.0, in some cases the `Copy` method will not create a new string but will simply return a reference to an existing interned string. Depending on Why you want to call the `Copy` method, there are a number of alternatives: @@ -4464,8 +4436,6 @@ Depending on Why you want to call the `Copy` method, there are a number of alter `sourceIndex` and `destinationIndex` are zero-based. - - ## Examples The following example demonstrates the method. @@ -4701,15 +4671,13 @@ This method performs a case-sensitive and culture-sensitive comparison using the This method performs a word (case-sensitive and culture-sensitive) comparison using the current culture. - - ## Examples The following example indicates whether each string in an array ends with a period ("."). :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/System.String.EndsWith/cs/EndsWith1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/System.String.EndsWith/vb/EndsWith1.vb" id="Snippet1"::: - The following example defines a `StripEndTags` method that uses the method to remove HTML end tags from the end of a line. Note that the `StripEndTags` method is called recursively to ensure that multiple HTML end tags at the end of the line are removed. + The following example defines a `StripEndTags` method that uses the method to remove HTML end tags from the end of a line. Note that the `StripEndTags` method is called recursively to ensure that multiple HTML end tags at the end of the line are removed. :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/stringendswith/CPP/stringendswith.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/stringendswith/CS/stringendswith.cs" interactive="try-dotnet" id="Snippet1"::: @@ -4785,8 +4753,6 @@ This method performs a case-sensitive and culture-sensitive comparison using the ## Remarks The method compares the `value` parameter to the substring at the end of this string and returns a value that indicates whether they are equal. To be equal, `value` must be a reference to this same string, must be the empty string (""), or must match the end of this string. The type of comparison performed by the method depends on the value of the `comparisonType` parameter. - - ## Examples The following example determines whether a string ends with a particular substring. The results are affected by the choice of culture, whether case is ignored, and whether an ordinal comparison is performed. @@ -4854,8 +4820,6 @@ This method performs a case-sensitive and culture-sensitive comparison using the This method performs a word (culture-sensitive) comparison using the specified casing and culture. - - ## Examples The following example determines whether a string occurs at the end of another string. The method is called several times using case sensitivity, case insensitivity, and different cultures that influence the results of the search. @@ -4974,8 +4938,6 @@ Invalid sequences are represented in the enumeration by method. @@ -5052,10 +5014,8 @@ Invalid sequences are represented in the enumeration by method. It compares the title-cased word "File" with an equivalent word, its lowercase equivalent, its uppercase equivalent, and a word that contains LATIN SMALL LETTER DOTLESS I (U+0131) instead of LATIN SMALL LETTER I (U+0069). Because the method performs an ordinal comparison, only the comparison with an identical word returns `true`. + The following example demonstrates the method. It compares the title-cased word "File" with an equivalent word, its lowercase equivalent, its uppercase equivalent, and a word that contains LATIN SMALL LETTER DOTLESS I (U+0131) instead of LATIN SMALL LETTER I (U+0069). Because the method performs an ordinal comparison, only the comparison with an identical word returns `true`. [!code-csharp[System.String.Equals#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.equals/cs/equalsex1.cs#2)] [!code-vb[System.String.Equals#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.equals/vb/equalsex1.vb#2)] @@ -5121,8 +5081,6 @@ Invalid sequences are represented in the enumeration by method. @@ -5190,10 +5148,8 @@ Invalid sequences are represented in the enumeration by method to compare them by using each possible enumeration value. + The following example creates a string array that consists of an uppercase "I", a lowercase "i", and a dotless "ı". It then calls the method to compare them by using each possible enumeration value. [!code-csharp[System.String.Equals#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.equals/cs/eqcmp.cs#1)] [!code-vb[System.String.Equals#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.equals/vb/eqcmp.vb#1)] @@ -5267,8 +5223,6 @@ Invalid sequences are represented in the enumeration by enumeration. The comparisons use the conventions of the English (United States) and Sami (Upper Sweden) cultures. Note that the strings "encyclopædia" and "encyclopaedia" are considered equivalent in the en-US culture but not in the Sami (Northern Sweden) culture. @@ -5382,14 +5336,14 @@ Invalid sequences are represented in the enumeration by overloads include a parameter followed by one or more object parameters. Because of this, you don't have to determine which overload you intend to call. Your language compiler selects the appropriate overload from among the overloads that don't have a `provider` parameter, based on your argument list. For example, if your argument list has five arguments, the compiler calls the method.| -|Format one or more objects by using the conventions of a specific culture.|Each overload that begins with a `provider` parameter is followed by a parameter and one or more object parameters. Because of this, you don't have to determine which specific overload you intend to call. Your language compiler selects the appropriate overload from among the overloads that have a `provider` parameter, based on your argument list. For example, if your argument list has five arguments, the compiler calls the method.| +|Format one or more objects by using the conventions of the current culture.|Except for the overloads that include a `provider` parameter, the remaining overloads include a parameter followed by one or more object parameters. Because of this, you don't have to determine which overload you intend to call. Your language compiler selects the appropriate overload from among the overloads that don't have a `provider` parameter, based on your argument list. For example, if your argument list has five arguments, the compiler calls the method.| +|Format one or more objects by using the conventions of a specific culture.|Each overload that begins with a `provider` parameter is followed by a parameter and one or more object parameters. Because of this, you don't have to determine which specific overload you intend to call. Your language compiler selects the appropriate overload from among the overloads that have a `provider` parameter, based on your argument list. For example, if your argument list has five arguments, the compiler calls the method.| |Perform a custom formatting operation either with an implementation or an implementation.|Any of the four overloads with a `provider` parameter. The compiler selects the appropriate overload from among the overloads that have a `provider` parameter, based on your argument list.| ## The Format method in brief - Each overload of the method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to include zero-based indexed placeholders, called *format items*, in a composite format string. At run time, each format item is replaced with the string representation of the corresponding argument in a parameter list. If the value of the argument is `null`, the format item is replaced with . For example, the following call to the method includes a format string with three format items, {0}, {1}, and {2}, and an argument list with three items. + Each overload of the method uses the [composite formatting feature](/dotnet/standard/base-types/composite-formatting) to include zero-based indexed placeholders, called *format items*, in a composite format string. At run time, each format item is replaced with the string representation of the corresponding argument in a parameter list. If the value of the argument is `null`, the format item is replaced with . For example, the following call to the method includes a format string with three format items, {0}, {1}, and {2}, and an argument list with three items. [!code-cpp[System.String.Format#8](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/formatoverload1.cpp#8)] [!code-csharp[System.String.Format#8](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Format/cs/formatoverload1.cs#8)] @@ -5424,15 +5378,15 @@ Invalid sequences are represented in the enumeration by interface. Types that support format strings include: -- All integral and floating-point types. (See [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings).) +- All integral and floating-point types. (See [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings).) -- and . (See [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings).) +- and . (See [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings).) -- All enumeration types. (See [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings).) +- All enumeration types. (See [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings).) -- values. (See [Standard TimeSpan Format Strings](/dotnet/standard/base-types/standard-timespan-format-strings) and [Custom TimeSpan Format Strings](/dotnet/standard/base-types/custom-timespan-format-strings).) +- values. (See [Standard TimeSpan Format Strings](/dotnet/standard/base-types/standard-timespan-format-strings) and [Custom TimeSpan Format Strings](/dotnet/standard/base-types/custom-timespan-format-strings).) -- GUIDs. (See the method.) +- GUIDs. (See the method.) However, note that any custom type can implement or extend an existing type's implementation. @@ -5446,13 +5400,13 @@ Invalid sequences are represented in the enumeration by method retrieves the argument and derives its string representation as follows: -- If the argument is `null`, the method inserts into the result string. You don't have to be concerned with handling a for null arguments. +- If the argument is `null`, the method inserts into the result string. You don't have to be concerned with handling a for null arguments. -- If you call the overload and the `provider` object's implementation returns a non-null implementation, the argument is passed to its method. If the format item includes a *formatString* argument, it is passed as the first argument to the method. If the implementation is available and produces a non-null string, that string is returned as the string representation of the argument; otherwise, the next step executes. +- If you call the overload and the `provider` object's implementation returns a non-null implementation, the argument is passed to its method. If the format item includes a *formatString* argument, it is passed as the first argument to the method. If the implementation is available and produces a non-null string, that string is returned as the string representation of the argument; otherwise, the next step executes. -- If the argument implements the interface, its implementation is called. +- If the argument implements the interface, its implementation is called. -- The argument's parameterless `ToString` method, which either overrides or inherits from a base class implementation, is called. +- The argument's parameterless `ToString` method, which either overrides or inherits from a base class implementation, is called. For an example that intercepts calls to the method and allows you to see what information the method passes to a formatting method for each format item in a composite format string, see [Example: An intercept provider and Roman numeral formatter](#Format7_Example). @@ -5460,7 +5414,7 @@ Invalid sequences are represented in the enumeration by ## Format items that have the same index - The method throws a exception if the index of an index item is greater than or equal to the number of arguments in the argument list. However, `format` can include more format items than there are arguments, as long as multiple format items have the same index. In the call to the method in following example, the argument list has a single argument, but the format string includes two format items: one displays the decimal value of a number, and the other displays its hexadecimal value. + The method throws a exception if the index of an index item is greater than or equal to the number of arguments in the argument list. However, `format` can include more format items than there are arguments, as long as multiple format items have the same index. In the call to the method in following example, the argument list has a single argument, but the format string includes two format items: one displays the decimal value of a number, and the other displays its hexadecimal value. [!code-csharp-interactive[System.String.Format2#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Format2/cs/Example1.cs#1)] [!code-vb[System.String.Format2#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format2/vb/Example1.vb#1)] @@ -5471,11 +5425,11 @@ Invalid sequences are represented in the enumeration by interface has a single member, , which is responsible for returning the object that provides formatting information. .NET has three implementations that provide culture-specific formatting: -- . Its method returns a culture-specific object for formatting numeric values and a culture-specific object for formatting date and time values. +- . Its method returns a culture-specific object for formatting numeric values and a culture-specific object for formatting date and time values. -- , which is used for culture-specific formatting of date and time values. Its method returns itself. +- , which is used for culture-specific formatting of date and time values. Its method returns itself. -- , which is used for culture-specific formatting of numeric values. Its property returns itself. +- , which is used for culture-specific formatting of numeric values. Its property returns itself. ## Custom formatting operations @@ -5495,9 +5449,9 @@ Invalid sequences are represented in the enumeration by and interfaces to do two things: -- It displays the parameters passed to its implementation. This enables us to see what parameters the method is passing to the custom formatting implementation for each object that it tries to format. This can be useful when you're debugging your application. +- It displays the parameters passed to its implementation. This enables us to see what parameters the method is passing to the custom formatting implementation for each object that it tries to format. This can be useful when you're debugging your application. -- If the object to be formatted is an unsigned byte value that is to be formatted by using the "R" standard format string, the custom formatter formats the numeric value as a Roman numeral. +- If the object to be formatted is an unsigned byte value that is to be formatted by using the "R" standard format string, the custom formatter formats the numeric value as a Roman numeral. [!code-cpp[System.String.Format#11](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/interceptor2.cpp#11)] [!code-csharp[System.String.Format#11](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Format/cs/interceptor2.cs#11)] @@ -5526,15 +5480,15 @@ In contrast, the use of interpolated strings in the following example produce mu ### Where can I find a list of the predefined format strings that can be used with format items? -- For all integral and floating-point types, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). +- For all integral and floating-point types, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings) and [Custom Numeric Format Strings](/dotnet/standard/base-types/custom-numeric-format-strings). -- For date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). +- For date and time values, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings) and [Custom Date and Time Format Strings](/dotnet/standard/base-types/custom-date-and-time-format-strings). -- For enumeration values, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). +- For enumeration values, see [Enumeration Format Strings](/dotnet/standard/base-types/enumeration-format-strings). -- For values, see [Standard TimeSpan Format Strings](/dotnet/standard/base-types/standard-timespan-format-strings) and [Custom TimeSpan Format Strings](/dotnet/standard/base-types/custom-timespan-format-strings). +- For values, see [Standard TimeSpan Format Strings](/dotnet/standard/base-types/standard-timespan-format-strings) and [Custom TimeSpan Format Strings](/dotnet/standard/base-types/custom-timespan-format-strings). -- For values, see the Remarks section of the reference page. +- For values, see the Remarks section of the reference page. ### How do I control the alignment of the result strings that replace format items? The general syntax of a format item is: @@ -5568,7 +5522,7 @@ In contrast, the use of interpolated strings in the following example produce mu [!code-vb[System.String.Format#28](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa28.vb#28)] ### How many items can I include in the format list? - There is no practical limit. The second parameter of the method is tagged with the attribute, which allows you to include either a delimited list or an object array as your format list. + There is no practical limit. The second parameter of the method is tagged with the attribute, which allows you to include either a delimited list or an object array as your format list. ### How do I include literal braces ("{" and "}") in the result string? @@ -5596,9 +5550,9 @@ In contrast, the use of interpolated strings in the following example produce mu [!code-csharp[System.String.Format#21](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Format/cs/qa1.cs#21)] [!code-vb[System.String.Format#21](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa1.vb#21)] - This is a problem of compiler overload resolution. Because the compiler cannot convert an array of integers to an object array, it treats the integer array as a single argument, so it calls the method. The exception is thrown because there are four format items but only a single item in the format list. + This is a problem of compiler overload resolution. Because the compiler cannot convert an array of integers to an object array, it treats the integer array as a single argument, so it calls the method. The exception is thrown because there are four format items but only a single item in the format list. - Because neither Visual Basic nor C# can convert an integer array to an object array, you have to perform the conversion yourself before calling the method. The following example provides one implementation. + Because neither Visual Basic nor C# can convert an integer array to an object array, you have to perform the conversion yourself before calling the method. The following example provides one implementation. [!code-csharp-interactive[System.String.Format#22](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Format/cs/qa2.cs#22)] [!code-vb[System.String.Format#22](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format/vb/qa2.vb#22)] @@ -5703,7 +5657,7 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ ## Example: Formatting a single argument - The following example uses the method to embed an individual's age in the middle of a string. + The following example uses the method to embed an individual's age in the middle of a string. [!code-cpp[System.String.Format#7](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format7.cpp#7)] [!code-csharp-interactive[System.String.Format#7](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Format/cs/format7.cs#7)] @@ -5965,7 +5919,7 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ ### Example: Culture-sensitive formatting - This example uses the method to display the string representation of some date and time values and numeric values by using several different cultures. + This example uses the method to display the string representation of some date and time values and numeric values by using several different cultures. [!code-csharp-interactive[System.String.Format2#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Format2/cs/Example2.cs#2)] [!code-vb[System.String.Format2#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Format2/vb/Example2.vb#2)] @@ -6052,7 +6006,7 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ ## Example: Format two arguments - This example uses the method to display time and temperature data stored in a generic object. Note that the format string has three format items, although there are only two objects to format. This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date. + This example uses the method to display time and temperature data stored in a generic object. Note that the format string has three format items, although there are only two objects to format. This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date. [!code-cpp[System.String.Format#6](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/formatexample4.cpp#6)] [!code-csharp[System.String.Format#6](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Format/cs/formatexample4.cs#6)] @@ -6205,7 +6159,7 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ ## Example: Format three arguments - This example uses the method to create a string that illustrates the result of a Boolean `And` operation with two integer values. Note that the format string includes six format items, but the method has only three items in its parameter list, because each item is formatted in two different ways. + This example uses the method to create a string that illustrates the result of a Boolean `And` operation with two integer values. Note that the format string includes six format items, but the method has only three items in its parameter list, because each item is formatted in two different ways. [!code-cpp[System.String.Format#4](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.String.Format/cpp/format4.cpp#4)] [!code-csharp-interactive[System.String.Format#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Format/cs/format4.cs#4)] @@ -6338,8 +6292,6 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ This method enables you to iterate the individual characters in a string. For example, the Visual Basic `For Each` and C# `foreach` statements invoke this method to return a object that can provide read-only access to the characters in this string instance. - - ## Examples The following example iterates the characters in several strings and displays information about their individual characters. It uses the language iteration construct rather than a call to the method. @@ -6409,15 +6361,15 @@ This method uses the [composite formatting feature](/dotnet/standard/base-types/ The behavior of is dependent on its implementation, which might change from one version of the common language runtime to another. A reason why this might happen is to improve the performance of . > [!IMPORTANT] -> If two string objects are equal, the method returns identical values. However, there is not a unique hash code value for each unique string value. Different strings can return the same hash code. +> If two string objects are equal, the method returns identical values. However, there is not a unique hash code value for each unique string value. Different strings can return the same hash code. > -> The hash code itself is not guaranteed to be stable. Hash codes for identical strings can differ across .NET implementations, across .NET versions, and across .NET platforms (such as 32-bit and 64-bit) for a single version of .NET. In some cases, they can even differ by application domain. This implies that two subsequent runs of the same program may return different hash codes. +> The hash code itself is not guaranteed to be stable. Hash codes for identical strings can differ across .NET implementations, across .NET versions, and across .NET platforms (such as 32-bit and 64-bit) for a single version of .NET. In some cases, they can even differ by application domain. This implies that two subsequent runs of the same program may return different hash codes. > -> As a result, hash codes should never be used outside of the application domain in which they were created, they should never be used as key fields in a collection, and they should never be persisted. +> As a result, hash codes should never be used outside of the application domain in which they were created, they should never be used as key fields in a collection, and they should never be persisted. > -> Finally, don't use the hash code instead of a value returned by a cryptographic hashing function if you need a cryptographically strong hash. For cryptographic hashes, use a class derived from the or class. +> Finally, don't use the hash code instead of a value returned by a cryptographic hashing function if you need a cryptographically strong hash. For cryptographic hashes, use a class derived from the or class. > -> For more information about hash codes, see . +> For more information about hash codes, see . In desktop apps, you can use the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element) to generate unique hash codes on a per application domain basis. This can reduce the number of collisions and improve the overall performance of insertions and lookups that use hash tables. The following example shows how to use the [\ element](/dotnet/framework/configure-apps/file-schema/runtime/userandomizedstringhashalgorithm-element). It defines a `DisplayString` class that includes a private string constant, `s`, whose value is "This is a string." It also includes a `ShowStringHashCode` method that displays the string value and its hash code along with the name of the application domain in which the method is executing. @@ -6450,12 +6402,10 @@ String 'This is a string.' in domain 'NewDomain': 75CC8236 ``` > [!IMPORTANT] -> Hash codes are used to insert and retrieve keyed objects from hash tables efficiently. However, hash codes don't uniquely identify strings. Identical strings have equal hash codes, but the common language runtime can also assign the same hash code to different strings. In addition, hash codes can vary by version of .NET, by platform within a single version, and by application domain. Because of this, you should not serialize or persist hash code values, nor should you use them as keys in a hash table or dictionary. +> Hash codes are used to insert and retrieve keyed objects from hash tables efficiently. However, hash codes don't uniquely identify strings. Identical strings have equal hash codes, but the common language runtime can also assign the same hash code to different strings. In addition, hash codes can vary by version of .NET, by platform within a single version, and by application domain. Because of this, you should not serialize or persist hash code values, nor should you use them as keys in a hash table or dictionary. For additional information about the use of hash codes and the `GetHashCode` method, see . - - ## Examples The following example demonstrates the method using various input strings. @@ -6466,7 +6416,7 @@ String 'This is a string.' in domain 'NewDomain': 75CC8236 ]]> - The value returned by is platform-dependent. It differs on the 32-bit and 64-bit versions of the .NET Framework. It also can differ between versions of the .NET Framework and .NET Core. + The value returned by is platform-dependent. It differs on the 32-bit and 64-bit versions of .NET Framework. It also can differ between versions of .NET Framework and .NET Core. <UseRandomizedStringHashAlgorithm> Element @@ -6751,8 +6701,6 @@ The `GetPinnableReference` method returns a character that can be used for pinni This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - - ## Examples The following example demonstrates how you can search a for a character using the method. @@ -6817,15 +6765,13 @@ The `GetPinnableReference` method returns a character that can be used for pinni This method performs a word (case-sensitive and culture-sensitive) search using the current culture. The search begins at the first character position of this instance and continues until the last character position. - Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. If `value` consists only of one or more ignorable characters, the method always returns 0 (zero) to indicate that the match is found at the beginning of the current instance. In the following example, the method is used to find three substrings (a soft hyphen (U+00AD), a soft hyphen followed by "n", and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on the [!INCLUDE[netfx40_short](~/includes/netfx40-short-md.md)] or later, in each case, because the soft hyphen is an ignorable character, the result is the same as if the soft hyphen had not been included in `value`. When searching for a soft hyphen only, the method returns 0 (zero) to indicate that it has found a match at the beginning of the string. + Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. If `value` consists only of one or more ignorable characters, the method always returns 0 (zero) to indicate that the match is found at the beginning of the current instance. In the following example, the method is used to find three substrings (a soft hyphen (U+00AD), a soft hyphen followed by "n", and a soft hyphen followed by "m") in two strings. Only one of the strings contains a soft hyphen. If the example is run on the [!INCLUDE[netfx40_short](~/includes/netfx40-short-md.md)] or later, in each case, because the soft hyphen is an ignorable character, the result is the same as if the soft hyphen had not been included in `value`. When searching for a soft hyphen only, the method returns 0 (zero) to indicate that it has found a match at the beginning of the string. [!code-csharp[System.String.IndexOf#21](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.IndexOf/CS/ignorable21.cs#21)] [!code-vb[System.String.IndexOf#21](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable21.vb#21)] - - ## Examples - The following example searches for the "n" in "animal". Because string indexes begin at zero rather than one, the method indicates that the "n" is at position 1. + The following example searches for the "n" in "animal". Because string indexes begin at zero rather than one, the method indicates that the "n" is at position 1. [!code-cpp[System.String.IndexOf#12](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.String.IndexOf/CPP/simple1.cpp#12)] [!code-csharp-interactive[System.String.IndexOf#12](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.IndexOf/CS/simple1.cs#12)] @@ -6910,8 +6856,6 @@ The `GetPinnableReference` method returns a character that can be used for pinni This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - - ## Examples The following example demonstrates the method. @@ -7029,13 +6973,11 @@ The `comparisonType` parameter is a enumeration m This method performs a word (case-sensitive and culture-sensitive) search using the current culture. The search begins at the `startIndex` character position of this instance and continues until the last character position. - Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. If `value` consists only of one or more ignorable characters, the method always returns `startIndex`, which is the character position at which the search begins. In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" in two strings. Only one of the strings contains the required substring. If the example is run on the [!INCLUDE[netfx40_short](~/includes/netfx40-short-md.md)] or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". + Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. If `value` consists only of one or more ignorable characters, the method always returns `startIndex`, which is the character position at which the search begins. In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" in two strings. Only one of the strings contains the required substring. If the example is run on the [!INCLUDE[netfx40_short](~/includes/netfx40-short-md.md)] or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". [!code-csharp[System.String.IndexOf#22](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.IndexOf/CS/ignorable22.cs#22)] [!code-vb[System.String.IndexOf#22](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable22.vb#22)] - - ## Examples The following example searches for all occurrences of a specified string within a target string. @@ -7119,8 +7061,6 @@ The `comparisonType` parameter is a enumeration m The `comparisonType` parameter specifies to search for the `value` parameter using the current or invariant culture, using a case-sensitive or case-insensitive search, and using word or ordinal comparison rules. - - ## Examples The following example demonstrates three overloads of the method that find the first occurrence of a string within another string using different values of the enumeration. @@ -7204,8 +7144,6 @@ The `comparisonType` parameter is a enumeration m This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - - ## Examples The following example demonstrates the method. @@ -7285,13 +7223,11 @@ The `comparisonType` parameter is a enumeration m This method performs a word (case-sensitive and culture-sensitive) search using the current culture. The search begins at `startIndex` and continues to `startIndex` + `count` -1. The character at `startIndex` + `count` is not included in the search. - Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. If `value` consists only of one or more ignorable characters, the method always returns `startIndex`, which is the character position at which the search begins. In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" starting in the third through sixth character positions in two strings. Only one of the strings contains the required substring. If the example is run on the [!INCLUDE[netfx40_short](~/includes/netfx40-short-md.md)] or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". + Character sets include ignorable characters, which are characters that are not considered when performing a linguistic or culture-sensitive comparison. In a culture-sensitive search, if `value` contains an ignorable character, the result is equivalent to searching with that character removed. If `value` consists only of one or more ignorable characters, the method always returns `startIndex`, which is the character position at which the search begins. In the following example, the method is used to find the position of a soft hyphen (U+00AD) followed by an "m" starting in the third through sixth character positions in two strings. Only one of the strings contains the required substring. If the example is run on the [!INCLUDE[netfx40_short](~/includes/netfx40-short-md.md)] or later, in both cases, because the soft hyphen is an ignorable character, the method returns the index of "m" in the string when it performs a culture-sensitive comparison. Note that in the case of the first string, which includes the soft hyphen followed by an "m", the method fails to return the index of the soft hyphen but instead returns the index of the "m". [!code-csharp[System.String.IndexOf#23](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.IndexOf/CS/ignorable23.cs#23)] [!code-vb[System.String.IndexOf#23](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.IndexOf/VB/ignorable23.vb#23)] - - ## Examples The following example finds the index of all occurrences of the string "he" within a substring of another string. Note that the number of characters to be searched must be recalculated for each search iteration. @@ -7381,8 +7317,6 @@ The `comparisonType` parameter is a enumeration m The `comparisonType` parameter specifies to search for the `value` parameter using the current or invariant culture, using a case-sensitive or case-insensitive search, and using word or ordinal comparison rules. - - ## Examples The following example demonstrates three overloads of the method that find the first occurrence of a string within another string using different values of the enumeration. @@ -7469,8 +7403,6 @@ The `comparisonType` parameter is a enumeration m The `comparisonType` parameter specifies to search for the `value` parameter using the current or invariant culture, using a case-sensitive or case-insensitive search, and using word or ordinal comparison rules. - - ## Examples The following example demonstrates three overloads of the method that find the first occurrence of a string within another string using different values of the enumeration. @@ -7573,8 +7505,6 @@ The `comparisonType` parameter is a enumeration m This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - - ## Examples The following example finds the first vowel in a string. @@ -7651,8 +7581,6 @@ The `comparisonType` parameter is a enumeration m This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar value are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - - ## Examples The following example finds the index of the occurrence of any character of the string "is" within a substring of another string. @@ -7741,8 +7669,6 @@ The `comparisonType` parameter is a enumeration m This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar value are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - - ## Examples The following example finds the index of the occurrence of any character of the string "aid" within a substring of another string. @@ -7824,12 +7750,10 @@ The `comparisonType` parameter is a enumeration m If `startIndex` is equal to the length of this instance, `value` is appended to the end of this instance. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which `value` is inserted into the current instance. +> This method does not modify the value of the current instance. Instead, it returns a new string in which `value` is inserted into the current instance. For example, the return value of `"abc".Insert(2, "XYZ")` is "abXYZc". - - ## Examples The following example inserts a space character in the fourth character position (the character at index 3) of a string. @@ -7926,7 +7850,7 @@ The `comparisonType` parameter is a enumeration m ## Version considerations - In the [!INCLUDE[net_v35SP1_long](~/includes/net-v35sp1-long-md.md)], the method reverts to its behavior in the .NET Framework 1.0 and 1.1 with regard to interning the empty string. In the following example, the variable `str1` is assigned a reference to , and the variable `str2` is assigned the reference to that is returned by calling the method after converting a object whose value is to a string. Then the references contained in `str1` and `str2` are compared for equality. + In the [!INCLUDE[net_v35SP1_long](~/includes/net-v35sp1-long-md.md)], the method reverts to its behavior in .NET Framework 1.0 and 1.1 with regard to interning the empty string. In the following example, the variable `str1` is assigned a reference to , and the variable `str2` is assigned the reference to that is returned by calling the method after converting a object whose value is to a string. Then the references contained in `str1` and `str2` are compared for equality. :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Intern/cs/Intern2.cs" interactive="try-dotnet-method" id="Snippet2"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Intern/vb/Intern2.vb" id="Snippet2"::: @@ -7936,9 +7860,7 @@ The `comparisonType` parameter is a enumeration m ## Performance Considerations If you are trying to reduce the total amount of memory your application allocates, keep in mind that interning a string has two unwanted side effects. First, the memory allocated for interned objects is not likely to be released until the common language runtime (CLR) terminates. The reason is that the CLR's reference to the interned object can persist after your application, or even your application domain, terminates. Second, to intern a string, you must first create the string. The memory used by the object must still be allocated, even though the memory will eventually be garbage collected. - The .NET Framework version 2.0 introduces the enumeration member. The member marks an assembly as not requiring string-literal interning. You can apply to an assembly using the attribute. Also, when you use the [Ngen.exe (Native Image Generator)](/dotnet/framework/tools/ngen-exe-native-image-generator) to compile an assembly in advance of run time, strings are not interned across modules. - - +The enumeration member marks an assembly as not requiring string-literal interning. You can apply to an assembly using the attribute. Also, when you use [Ngen.exe (Native Image Generator)](/dotnet/framework/tools/ngen-exe-native-image-generator) to compile an assembly in advance of run time, strings are not interned across modules. ## Examples The following example uses three strings that are equal in value to determine whether a newly created string and an interned string are equal. @@ -8016,9 +7938,7 @@ The `comparisonType` parameter is a enumeration m :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.isinterned/vb/isinternedex1.vb" id="Snippet1"::: > [!NOTE] -> Starting with the .NET Framework version 2.0, you can override the use of the intern pool when you use the [Ngen.exe (Native Image Generator)](/dotnet/framework/tools/ngen-exe-native-image-generator) to install an assembly to the native image cache on a local computer. For more information, see Performance Considerations in the Remarks section for the property. - - +> You can override the use of the intern pool when you use [Ngen.exe (Native Image Generator)](/dotnet/framework/tools/ngen-exe-native-image-generator) to install an assembly to the native image cache on a local computer. For more information, see Performance Considerations in the Remarks section for the property. ## Examples The following example demonstrates that literal strings are interned automatically by the compiler. @@ -8309,8 +8229,6 @@ A string is empty if it is explicitly assigned an empty string ("") or method interprets any character that returns a value of `true` when it is passed to the method as a white-space character. - - ## Examples The following example creates a string array, and then passes each element of the array to the method. @@ -8492,13 +8410,13 @@ A string is empty if it is explicitly assigned an empty string ("") or ) is used instead. If any member of `values` is `null`, an empty string is used instead. - is a convenience method that lets you concatenate each element in an `IEnumerable(Of String)` collection without first converting the elements to a string array. It is particularly useful with Language-Integrated Query (LINQ) query expressions. The following example passes a `List(Of String)` object that contains either the uppercase or lowercase letters of the alphabet to a lambda expression that selects letters that are equal to or greater than a particular letter (which, in the example, is "M"). The `IEnumerable(Of String)` collection returned by the method is passed to the method to display the result as a single string. + is a convenience method that lets you concatenate each element in an `IEnumerable(Of String)` collection without first converting the elements to a string array. It is particularly useful with Language-Integrated Query (LINQ) query expressions. The following example passes a `List(Of String)` object that contains either the uppercase or lowercase letters of the alphabet to a lambda expression that selects letters that are equal to or greater than a particular letter (which, in the example, is "M"). The `IEnumerable(Of String)` collection returned by the method is passed to the method to display the result as a single string. :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.join/cs/join4.cs" interactive="try-dotnet" id="Snippet4"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join4.vb" id="Snippet4"::: ## Examples - The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type , which it then passes to the method. + The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type , which it then passes to the method. :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.join/cs/join3.cs" interactive="try-dotnet" id="Snippet3"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join3.vb" id="Snippet3"::: @@ -8572,12 +8490,10 @@ A string is empty if it is explicitly assigned an empty string ("") or ) is used instead. See the Notes for Callers section if the first element of `values` is `null`. - is a convenience method that lets you concatenate each element in an object array without explicitly converting its elements to strings. The string representation of each object in the array is derived by calling that object's `ToString` method. - - + is a convenience method that lets you concatenate each element in an object array without explicitly converting its elements to strings. The string representation of each object in the array is derived by calling that object's `ToString` method. ## Examples - The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a integer array, which it then passes to the method. + The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a integer array, which it then passes to the method. :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.join/cs/join1.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join1.vb" id="Snippet1"::: @@ -8658,8 +8574,6 @@ A string is empty if it is explicitly assigned an empty string ("") or ) is used instead. If any element in `value` is `null`, an empty string is used instead. - - ## Examples The following example demonstrates the method. @@ -8796,8 +8710,6 @@ A string is empty if it is explicitly assigned an empty string ("") or ) is used instead. If any element in `value` is `null`, an empty string is used instead. - - ## Examples The following example concatenates two elements from an array of names of fruit. @@ -8921,15 +8833,15 @@ A string is empty if it is explicitly assigned an empty string ("") or ) is used instead. If any member of `values` is `null`, an empty string is used instead. - is a convenience method that lets you concatenate each member of an collection without first converting them to strings. The string representation of each object in the collection is derived by calling that object's `ToString` method. + is a convenience method that lets you concatenate each member of an collection without first converting them to strings. The string representation of each object in the collection is derived by calling that object's `ToString` method. - This method is particular useful with Language-Integrated Query (LINQ) query expressions. For example, the following code defines a very simple `Animal` class that contains the name of an animal and the order to which it belongs. It then defines a object that contains a number of `Animal` objects. The extension method is called to extract the `Animal` objects whose `Order` property equals "Rodent". The result is passed to the method. + This method is particular useful with Language-Integrated Query (LINQ) query expressions. For example, the following code defines a very simple `Animal` class that contains the name of an animal and the order to which it belongs. It then defines a object that contains a number of `Animal` objects. The extension method is called to extract the `Animal` objects whose `Order` property equals "Rodent". The result is passed to the method. :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.join/cs/join5.cs" interactive="try-dotnet" id="Snippet5"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join5.vb" id="Snippet5"::: ## Examples - The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type integer, which it then passes to the method. + The following example uses the Sieve of Eratosthenes algorithm to calculate the prime numbers that are less than or equal to 100. It assigns the result to a object of type integer, which it then passes to the method. :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.join/cs/join2.cs" interactive="try-dotnet" id="Snippet2"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.join/vb/join2.vb" id="Snippet2"::: @@ -9012,10 +8924,8 @@ A string is empty if it is explicitly assigned an empty string ("") or method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - - ## Examples - The following example defines an `ExtractFilename` method that uses the method to find the last directory separator character in a string and to extract the string's file name. If the file exists, the method returns the file name without its path. + The following example defines an `ExtractFilename` method that uses the method to find the last directory separator character in a string and to extract the string's file name. If the file exists, the method returns the file name without its path. [!code-csharp[System.String.LastIndexOf#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.LastIndexOf/cs/LastIndexOf_Example.cs#1)] [!code-vb[System.String.LastIndexOf#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.LastIndexOf/vb/LastIndexOf_Example.vb#1)] @@ -9163,8 +9073,6 @@ In the following example, the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - - ## Examples The following example finds the index of all occurrences of a character in a string, working from the end of the string to the start of the string. @@ -9415,8 +9323,6 @@ The search begins at the last character position of this instance and proceeds b This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar value are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - - ## Examples The following example finds the index of all occurrences of a character in a substring, working from the end of the substring to the start of the substring. @@ -9797,8 +9703,6 @@ In the following example, the method is used This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - - ## Examples The following example finds the index of the last occurrence of any character in the string "is" within another string. @@ -9871,8 +9775,6 @@ In the following example, the method is used This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - - ## Examples The following example finds the index of the last occurrence of any character in the string "is" within a substring of another string. @@ -9954,8 +9856,6 @@ In the following example, the method is used This method performs an ordinal (culture-insensitive) search, where a character is considered equivalent to another character only if their Unicode scalar values are the same. To perform a culture-sensitive search, use the method, where a Unicode scalar value representing a precomposed character, such as the ligature "Æ" (U+00C6), might be considered equivalent to any occurrence of the character's components in the correct sequence, such as "AE" (U+0041, U+0045), depending on the culture. - - ## Examples The following example finds the index of the last occurrence of any character in the string "aid" within a substring of another string. @@ -10035,8 +9935,6 @@ In the following example, the method is used [!code-csharp-interactive[System.String.Class#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.String.Class/cs/System.String.Class.cs#1)] [!code-vb[System.String.Class#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.String.Class/vb/System.String.Class.vb#1)] - - ## Examples The following example demonstrates the property. @@ -10110,11 +10008,11 @@ In the following example, the method is used ## Remarks Some Unicode characters have multiple equivalent binary representations consisting of sets of combining and/or composite Unicode characters. For example, any of the following code points can represent the letter "ắ": -- U+1EAF +- U+1EAF -- U+0103 U+0301 +- U+0103 U+0301 -- U+0061 U+0306 U+0301 +- U+0061 U+0306 U+0301 The existence of multiple representations for a single character complicates searching, sorting, matching, and other operations. @@ -10126,7 +10024,7 @@ In the following example, the method is used 2. Call the method to normalize the strings to normalization form C. -3. To compare two strings, call a method that supports ordinal string comparison, such as the method, and supply a value of or as the argument. To sort an array of normalized strings, pass a `comparer` value of or to an appropriate overload of . +3. To compare two strings, call a method that supports ordinal string comparison, such as the method, and supply a value of or as the argument. To sort an array of normalized strings, pass a `comparer` value of or to an appropriate overload of . 4. Emit the strings in the sorted output based on the order indicated by the previous step. @@ -10195,9 +10093,9 @@ In the following example, the method is used 1. Obtain the strings to be compared from an input source, such as a file or a user input device. -2. Call the method to normalize the strings to a specified normalization form. +2. Call the method to normalize the strings to a specified normalization form. -3. To compare two strings, call a method that supports ordinal string comparison, such as the method, and supply a value of or as the argument. To sort an array of normalized strings, pass a `comparer` value of or to an appropriate overload of . +3. To compare two strings, call a method that supports ordinal string comparison, such as the method, and supply a value of or as the argument. To sort an array of normalized strings, pass a `comparer` value of or to an appropriate overload of . 4. Emit the strings in the sorted output based on the order indicated by the previous step. @@ -10266,12 +10164,10 @@ In the following example, the method is used method defines the operation of the equality operator for the class. It enables code such as that shown in the Example section. The operator, in turn, calls the static method, which performs an ordinal (case-sensitive and culture-insensitive) comparison. + The method defines the operation of the equality operator for the class. It enables code such as that shown in the Example section. The operator, in turn, calls the static method, which performs an ordinal (case-sensitive and culture-insensitive) comparison. > [!NOTE] -> The Visual Basic compiler does not resolve the equality operator as a call to the method. Instead, the equality operator wraps a call to the method. - - +> The Visual Basic compiler does not resolve the equality operator as a call to the method. Instead, the equality operator wraps a call to the method. ## Examples The following example demonstrates the equality operator. @@ -10374,12 +10270,10 @@ In the following example, the method is used ## Remarks The method defines the operation of the inequality operator for the class. It enables code such as that shown in the Examples section. - The operator in turn calls the static method, which performs an ordinal (case-sensitive and culture-insensitive) comparison. + The operator in turn calls the static method, which performs an ordinal (case-sensitive and culture-insensitive) comparison. > [!NOTE] -> The Visual Basic compiler does not resolve the inequality operator as a call to the method. Instead, the inequality operator wraps a call to the method. - - +> The Visual Basic compiler does not resolve the inequality operator as a call to the method. Instead, the inequality operator wraps a call to the method. ## Examples The following example demonstrates the inequality operator. @@ -10451,12 +10345,10 @@ In the following example, the method is used ## Remarks A Unicode space is defined as hexadecimal 0x0020. - The method pads the beginning of the returned string. This means that, when used with right-to-left languages, it pads the right portion of the string. + The method pads the beginning of the returned string. This means that, when used with right-to-left languages, it pads the right portion of the string. > [!NOTE] -> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with leading white space so that its total length is `totalWidth` characters. - - +> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with leading white space so that its total length is `totalWidth` characters. ## Examples The following example demonstrates the method. @@ -10521,12 +10413,10 @@ In the following example, the method is used method pads the beginning of the returned string. This means that, when used with right-to-left languages, it pads the right portion of the string. + The method pads the beginning of the returned string. This means that, when used with right-to-left languages, it pads the right portion of the string. > [!NOTE] -> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with leading `paddingChar` characters so that its total length is `totalWidth` characters. - - +> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with leading `paddingChar` characters so that its total length is `totalWidth` characters. ## Examples The following example demonstrates the method. @@ -10605,12 +10495,10 @@ In the following example, the method is used ## Remarks A Unicode space is defined as hexadecimal 0x0020. - The method pads the end of the returned string. This means that, when used with right-to-left languages, it pads the left portion of the string. + The method pads the end of the returned string. This means that, when used with right-to-left languages, it pads the left portion of the string. > [!NOTE] -> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with trailing white space so that its total length is `totalWidth` characters. - - +> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with trailing white space so that its total length is `totalWidth` characters. ## Examples The following example demonstrates the method. @@ -10675,12 +10563,10 @@ In the following example, the method is used method pads the end of the returned string. This means that, when used with right-to-left languages, it pads the left portion of the string. + The method pads the end of the returned string. This means that, when used with right-to-left languages, it pads the left portion of the string. > [!NOTE] -> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with trailing `paddingChar` characters so that its total length is `totalWidth` characters. - - +> If the method pads the current instance with white-space characters, this method does not modify the value of the current instance. Instead, it returns a new string that is padded with trailing `paddingChar` characters so that its total length is `totalWidth` characters. ## Examples The following example demonstrates the method. @@ -10759,9 +10645,7 @@ In the following example, the method is used In the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)], strings are zero-based. The value of the `startIndex` parameter can range from zero to one less than the length of the string instance. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters from position `startIndex` to the end of the original string have been removed. - - +> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters from position `startIndex` to the end of the original string have been removed. ## Examples The following example demonstrates the method. The next-to-last case removes all text starting from the specified index through the end of the string. The last case removes three characters starting from the specified index. @@ -10844,9 +10728,7 @@ In the following example, the method is used In the [!INCLUDE[dnprdnshort](~/includes/dnprdnshort-md.md)], strings are zero-based. The value of the `startIndex` parameter can range from zero to one less than the length of the string instance. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which the number of characters specified by the `count` parameter have been removed. The characters are removed at the position specified by `startIndex`. - - +> This method does not modify the value of the current instance. Instead, it returns a new string in which the number of characters specified by the `count` parameter have been removed. The characters are removed at the position specified by `startIndex`. ## Examples The following example demonstrates how you can remove the middle name from a complete name. @@ -10941,15 +10823,13 @@ In the following example, the method is used This method performs an ordinal (case-sensitive and culture-insensitive) search to find `oldChar`. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldChar` are replaced by `newChar`. +> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldChar` are replaced by `newChar`. Because this method returns the modified string, you can chain together successive calls to the method to perform multiple replacements on the original string. Method calls are executed from left to right. The following example provides an illustration. [!code-csharp-interactive[System.String.Replace#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.replace/cs/replace2.cs#2)] [!code-vb[System.String.Replace#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.replace/vb/replace2.vb#2)] - - ## Examples The following example creates a comma separated value list by substituting commas for the blanks between a series of numbers. @@ -11030,7 +10910,7 @@ In the following example, the method is used If `newValue` is `null`, all occurrences of `oldValue` are removed. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldValue` are replaced by `newValue`. +> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldValue` are replaced by `newValue`. This method performs an ordinal (case-sensitive and culture-insensitive) search to find `oldValue`. @@ -11039,8 +10919,6 @@ In the following example, the method is used [!code-csharp-interactive[System.String.Replace#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.replace/cs/replace1.cs#1)] [!code-vb[System.String.Replace#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.replace/vb/replace1.vb#1)] - - ## Examples The following example demonstrates how you can use the method to correct a spelling error. @@ -11107,7 +10985,7 @@ In the following example, the method is used If `newValue` is `null`, all occurrences of `oldValue` are removed. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldValue` are replaced by `newValue`. +> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldValue` are replaced by `newValue`. This method performs a search to find `oldValue` using the culture and case sensitivity described by `comparisonType`. @@ -11171,7 +11049,7 @@ Because this method returns the modified string, you can chain together successi If `newValue` is `null`, all occurrences of `oldValue` are removed. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldValue` are replaced by `newValue`. +> This method does not modify the value of the current instance. Instead, it returns a new string in which all occurrences of `oldValue` are replaced by `newValue`. This method performs a search to find `oldValue` using the provided `culture` and `ignoreCase` case sensitivity. @@ -11187,8 +11065,7 @@ Because this method returns the modified string, you can chain together successi is the empty string (""). - - + System.Runtime 4.0.0.0 @@ -12186,7 +12063,7 @@ This method performs a word (case-sensitive and culture-sensitive) comparison us ## Examples -The following example defines a `StripStartTags` method that uses the method to remove HTML start tags from the beginning of a string. Note that the `StripStartTags` method is called recursively to ensure that multiple HTML start tags at the beginning of the line are removed. The example does not remove HTML tags embedded in a string. +The following example defines a `StripStartTags` method that uses the method to remove HTML start tags from the beginning of a string. Note that the `StripStartTags` method is called recursively to ensure that multiple HTML start tags at the beginning of the line are removed. The example does not remove HTML tags embedded in a string. :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR/stringstartswith/CPP/stringstartswith.cpp" id="Snippet1"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR/stringstartswith/CS/stringstartswith.cs" interactive="try-dotnet" id="Snippet1"::: @@ -12261,10 +12138,8 @@ The following example defines a `StripStartTags` method that uses the method compares the `value` parameter to the substring at the beginning of this string and returns a value that indicates whether they are equal. To be equal, `value` must be a reference to this same string, must be the empty string (""), or must match the beginning of this string. The type of comparison performed by the method depends on the value of the `comparisonType` parameter. The comparison can use the conventions of the current culture ( and ) or the invariant culture ( and ), or it can consist of a character-by-character comparison of code points ( or ). The comparison can also be case-sensitive (, , or ), or it can ignore case (, , ). - - ## Examples - The following example searches for the string "the" at the beginning of a longer string that begins with the word "The". As the output from the example shows, a call to the method that performs a culture-insensitive but case-sensitive comparison fails to match the string, while a call that performs a culture- and case-insensitive comparison matches the string. + The following example searches for the string "the" at the beginning of a longer string that begins with the word "The". As the output from the example shows, a call to the method that performs a culture-insensitive but case-sensitive comparison fails to match the string, while a call that performs a culture- and case-insensitive comparison matches the string. :::code language="cpp" source="~/samples/snippets/cpp/VS_Snippets_CLR_System/system.string.startswith/cpp/StartsWith2.cpp" id="Snippet2"::: :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.startswith/cs/StartsWith2.cs" interactive="try-dotnet" id="Snippet2"::: @@ -12336,8 +12211,6 @@ The following example defines a `StripStartTags` method that uses the method is called several times using case sensitivity, case insensitivity, and different cultures that influence the results of the search. @@ -12416,16 +12289,14 @@ The following example defines a `StripStartTags` method that uses the method to extract a substring from a string that begins at a specified character position and ends at the end of the string. The starting character position is a zero-based; in other words, the first character in the string is at index 0, not index 1. To extract a substring that begins at a specified character position and ends before the end of the string, call the method. + You call the method to extract a substring from a string that begins at a specified character position and ends at the end of the string. The starting character position is a zero-based; in other words, the first character in the string is at index 0, not index 1. To extract a substring that begins at a specified character position and ends before the end of the string, call the method. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string that begins at the `startIndex` position in the current string. +> This method does not modify the value of the current instance. Instead, it returns a new string that begins at the `startIndex` position in the current string. To extract a substring that begins with a particular character or character sequence, call a method such as or to get the value of `startIndex`. The second example illustrates this; it extracts a key value that begins one character position after the "=" character. If `startIndex` is equal to zero, the method returns the original string unchanged. - - ## Examples The following example demonstrates obtaining a substring from a string. @@ -12438,7 +12309,7 @@ The following example defines a `StripStartTags` method that uses the method is used to get the position of the equals character in the string. The call to the method extracts the key name, which starts from the first character in the string and extends for the number of characters returned by the call to the method. The call to the method then extracts the value assigned to the key. It starts at one character position beyond the equals character and extends to the end of the string. + The method is used to get the position of the equals character in the string. The call to the method extracts the key name, which starts from the first character in the string and extends for the number of characters returned by the call to the method. The call to the method then extracts the value assigned to the key. It starts at one character position beyond the equals character and extends to the end of the string. ]]> @@ -12511,10 +12382,10 @@ The following example defines a `StripStartTags` method that uses the method to extract a substring from a string that begins at a specified character position and ends before the end of the string. The starting character position is a zero-based; in other words, the first character in the string is at index 0, not index 1. To extract a substring that begins at a specified character position and continues to the end of the string, call the method. + You call the method to extract a substring from a string that begins at a specified character position and ends before the end of the string. The starting character position is a zero-based; in other words, the first character in the string is at index 0, not index 1. To extract a substring that begins at a specified character position and continues to the end of the string, call the method. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string with `length` characters starting from the `startIndex` position in the current string. +> This method does not modify the value of the current instance. Instead, it returns a new string with `length` characters starting from the `startIndex` position in the current string. The `length` parameter represents the total number of characters to extract from the current string instance. This includes the starting character found at index `startIndex`. In other words, the method attempts to extract characters from index `startIndex` to index `startIndex` + `length` - 1. @@ -12522,35 +12393,33 @@ The following example defines a `StripStartTags` method that uses the or to get the index of the ending character or character sequence. You can then convert that value to an index position in the string as follows: -- If you've searched for a single character that is to mark the end of the substring, the `length` parameter equals `endIndex` - `startIndex` + 1, where `endIndex` is the return value of the or method. The following example extracts a continuous block of "b" characters from a string. +- If you've searched for a single character that is to mark the end of the substring, the `length` parameter equals `endIndex` - `startIndex` + 1, where `endIndex` is the return value of the or method. The following example extracts a continuous block of "b" characters from a string. [!code-csharp-interactive[System.String.Substring#2](~/samples/snippets/csharp/VS_Snippets_CLR_System/System.String.Substring/cs/Substring2.cs#2)] [!code-vb[System.String.Substring#2](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring2.vb#2)] -- If you've searched for multiple characters that are to mark the end of the substring, the `length` parameter equals `endIndex` + `endMatchLength` - `startIndex`, where `endIndex` is the return value of the or method, and `endMatchLength` is the length of the character sequence that marks the end of the substring. The following example extracts a block of text that contains an XML `` element. +- If you've searched for multiple characters that are to mark the end of the substring, the `length` parameter equals `endIndex` + `endMatchLength` - `startIndex`, where `endIndex` is the return value of the or method, and `endMatchLength` is the length of the character sequence that marks the end of the substring. The following example extracts a block of text that contains an XML `` element. [!code-csharp-interactive[System.String.Substring#3](~/samples/snippets/csharp/VS_Snippets_CLR_System/System.String.Substring/cs/Substring3.cs#3)] [!code-vb[System.String.Substring#3](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring3.vb#3)] -- If the character or character sequence is not included in the end of the substring, the `length` parameter equals `endIndex` - `startIndex`, where `endIndex` is the return value of the or method. +- If the character or character sequence is not included in the end of the substring, the `length` parameter equals `endIndex` - `startIndex`, where `endIndex` is the return value of the or method. If `startIndex` is equal to zero and equals the length of the current string, the method returns the original string unchanged. - - ## Examples - The following example illustrates a simple call to the method that extracts two characters from a string starting at the sixth character position (that is, at index five). + The following example illustrates a simple call to the method that extracts two characters from a string starting at the sixth character position (that is, at index five). [!code-csharp-interactive[System.String.Substring#4](~/samples/snippets/csharp/VS_Snippets_CLR_System/System.String.Substring/cs/Substring4.cs#4)] [!code-vb[System.String.Substring#4](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/System.String.Substring/vb/Substring4.vb#4)] - The following example uses the method in the following three cases to isolate substrings within a string. In two cases the substrings are used in comparisons, and in the third case an exception is thrown because invalid parameters are specified. + The following example uses the method in the following three cases to isolate substrings within a string. In two cases the substrings are used in comparisons, and in the third case an exception is thrown because invalid parameters are specified. -- It extracts the single character and the third position in the string (at index 2) and compares it with a "c". This comparison returns `true`. +- It extracts the single character and the third position in the string (at index 2) and compares it with a "c". This comparison returns `true`. -- It extracts zero characters starting at the fourth position in the string (at index 3) and passes it to the method. This returns true because the call to the method returns . +- It extracts zero characters starting at the fourth position in the string (at index 3) and passes it to the method. This returns true because the call to the method returns . -- It attempts to extract one character starting at the fourth position in the string. Because there is no character at that position, the method call throws an exception. +- It attempts to extract one character starting at the fourth position in the string. Because there is no character at that position, the method call throws an exception. [!code-csharp-interactive[Classic String.Substring1 Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_Classic/classic String.Substring1 Example/CS/source.cs#1)] [!code-vb[Classic String.Substring1 Example#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_Classic/classic String.Substring1 Example/VB/source.vb#1)] @@ -12560,7 +12429,7 @@ The following example defines a `StripStartTags` method that uses the method is used to get the position of the equals character in the string. The call to the method extracts the key name, which starts from the first character in the string and extends for the number of characters returned by the call to the method. The call to the method then extracts the value assigned to the key. It starts at one character position beyond the equals character and extends to the end of the string. + The method is used to get the position of the equals character in the string. The call to the method extracts the key name, which starts from the first character in the string and extends for the number of characters returned by the call to the method. The call to the method then extracts the value assigned to the key. It starts at one character position beyond the equals character and extends to the end of the string. ]]> @@ -12719,11 +12588,11 @@ The following example defines a `StripStartTags` method that uses the object. > [!CAUTION] -> The method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the method. +> The method was designed primarily for use in sorting or alphabetizing operations. It should not be used when the primary purpose of the method call is to determine whether two strings are equivalent. To determine whether two strings are equivalent, call the method. This method performs a word (case-sensitive and culture-sensitive) comparison using the current culture. For more information about word, string, and ordinal sorts, see . -For more information about the behavior of this method, see the Remarks section of the method. +For more information about the behavior of this method, see the Remarks section of the method. ## Examples @@ -12830,7 +12699,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -12889,7 +12758,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -12943,7 +12812,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -13001,7 +12870,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -13059,7 +12928,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -13119,7 +12988,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -13179,7 +13048,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -13239,7 +13108,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -13297,7 +13166,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -13359,7 +13228,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -13419,7 +13288,7 @@ The following example displays the enumerated constant fo instance is cast to an interface. The recommended alternative is to call the method. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -13585,7 +13454,7 @@ This member is an explicit interface member implementation. It can be used only instance is cast to an interface. The recommended alternative is to call the method. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -13649,7 +13518,7 @@ This member is an explicit interface member implementation. It can be used only instance is cast to an interface. The recommended alternative is to call the method. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -13713,7 +13582,7 @@ This member is an explicit interface member implementation. It can be used only instance is cast to an interface. The recommended alternative is to call the method. + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. The recommended alternative is to call the method. ]]> @@ -13782,9 +13651,9 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This method copies each character (that is, each object) in a string to a character array. The first character copied is at index zero of the returned character array; the last character copied is at index - 1. - To create a string from the characters in a character array, call the constructor. + To create a string from the characters in a character array, call the constructor. - To create a byte array that contains the encoded characters in a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include the following: + To create a byte array that contains the encoded characters in a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include the following: |Encoding|Object| |--------------|------------| @@ -13796,8 +13665,6 @@ This member is an explicit interface member implementation. It can be used only For more information, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). - - ## Examples The following example calls the method to extract the characters in a string to a character array. It then displays the original string and the elements in the array. @@ -13863,13 +13730,13 @@ This member is an explicit interface member implementation. It can be used only constructor. + This method copies the characters in a portion of a string to a character array. To create a string from a range of characters in a character array, call the constructor. The `startIndex` parameter is zero-based. That is, the index of the first character in the string instance is zero. If `length` is zero, the returned array is empty and has a zero length. If this instance is `null` or an empty string (""), the returned array is empty and has a zero length. - To create a byte array that contains the encoded characters in a portion of a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include: + To create a byte array that contains the encoded characters in a portion of a string, instantiate the appropriate object and call its method. Some of the standard encodings available in .NET include: |Encoding|Object| |--------------|------------| @@ -13881,8 +13748,6 @@ This member is an explicit interface member implementation. It can be used only For more information, see [Character Encoding in .NET](/dotnet/standard/base-types/character-encoding). - - ## Examples The following example converts a substring within a string to an array of characters, then enumerates and displays the elements of the array. @@ -13961,13 +13826,11 @@ This member is an explicit interface member implementation. It can be used only This method takes into account the casing rules of the current culture. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. +> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. ## Security Considerations The casing operation that results from calling the method takes the casing conventions of the current culture into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. This produces the same result in every culture (unlike the method) and performs more efficiently. - - ## Examples The following example converts several mixed case strings to lowercase. @@ -14036,12 +13899,10 @@ This member is an explicit interface member implementation. It can be used only The casing rules of the culture specified by the `culture` parameter determine the way the case of the string is changed. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. +> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. ## Security Considerations - If you pass the method a object other than , the casing operation will take culture-specific rules into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture and performs more efficiently. - - + If you pass the method a object other than , the casing operation will take culture-specific rules into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture and performs more efficiently. ## Examples The following example converts two strings of uppercase characters to lowercase characters using the English-United States and Turkish-Turkey cultures, then compares the lowercase strings. The uppercase strings are identical except that for each occurrence of the Unicode LATIN CAPITAL LETTER I in one string, the other string contains LATIN CAPITAL LETTER I WITH DOT ABOVE. @@ -14110,15 +13971,13 @@ This member is an explicit interface member implementation. It can be used only If your application depends on the case of a string changing in a predictable way that is unaffected by the current culture, use the method. The method is equivalent to `ToLower(CultureInfo.InvariantCulture)`. The method is recommended when a collection of strings must appear in a predictable order in a user interface control. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. +> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to lowercase. ## Security Considerations If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. - - ## Examples - The following example defines a string array that contains a single word in a number of languages. The method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the lowercase array to ensure that elements appear in the same order regardless of language. + The following example defines a string array that contains a single word in a number of languages. The method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the lowercase array to ensure that elements appear in the same order regardless of language. :::code language="csharp" source="~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.tolowerinvariant/cs/tolowerinvariant.cs" interactive="try-dotnet" id="Snippet1"::: :::code language="vb" source="~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.tolowerinvariant/vb/tolowerinvariant.vb" id="Snippet1"::: @@ -14194,8 +14053,6 @@ This member is an explicit interface member implementation. It can be used only ## Remarks Because this method simply returns the current string unchanged, there is no need to call it directly. It is usually called implicitly in a composite formatting operation, as the example shows. - - ## Examples The following example demonstrates the method.Note that the example does not explicitly call the method. Instead, the method is called implicitly by the [composite formatting](/dotnet/standard/base-types/composite-formatting) feature. @@ -14325,15 +14182,13 @@ This member is an explicit interface member implementation. It can be used only This method uses the casing rules of the current culture to convert each character in the current instance to its uppercase equivalent. If a character does not have an uppercase equivalent, it is included unchanged in the returned string. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. +> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. The method is often used to convert a string to uppercase so that it can be used in a case-insensitive comparison. A better method to perform case-insensitive comparison is to call a string comparison method that has a parameter whose value you set to for a culture-sensitive, case-insensitive comparison. ## Security Considerations The casing operation that results from calling the method takes the casing conventions of the current culture into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture (unlike the method) and performs more efficiently. - - ## Examples The following example calls the method to convert a series of one-character strings that contain each character in the Basic Latin, Latin-1 Supplement, and Latin Extended-A character sets. It then displays each string whose uppercase character is different from its lowercase character. @@ -14402,12 +14257,10 @@ This member is an explicit interface member implementation. It can be used only The casing rules of the culture specified by the `culture` parameter determine the way the case of a string is changed. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. +> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. ## Security Considerations - If you pass the method a object other than , the casing operation will take culture-specific rules into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture and performs more efficiently. - - + If you pass the method a object other than , the casing operation will take culture-specific rules into account. If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or method. This produces the same result in every culture and performs more efficiently. ## Examples The following example converts a string of lowercase characters to two strings of uppercase characters using the English-United States and Turkish-Turkey cultures, then compares the uppercase strings. The uppercase strings are identical except that for each occurrence of the Unicode LATIN CAPITAL LETTER I in one string, the other string contains LATIN CAPITAL LETTER I WITH DOT ABOVE. @@ -14476,15 +14329,13 @@ This member is an explicit interface member implementation. It can be used only If your application depends on the case of a string changing in a predictable way that is unaffected by the current culture, use the method. The method is equivalent to `ToUpper(CultureInfo.InvariantCulture)`. The method is recommended when a collection of strings must appear in a predictable order in a user interface control. > [!NOTE] -> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. +> This method does not modify the value of the current instance. Instead, it returns a new string in which all characters in the current instance are converted to uppercase. ## Security Considerations If you need the lowercase or uppercase version of an operating system identifier, such as a file name, named pipe, or registry key, use the or methods. - - ## Examples - The following example defines a string array that contains a single word in a number of languages. The method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the uppercase array to ensure that elements appear in the same order regardless of language. + The following example defines a string array that contains a single word in a number of languages. The method is used to populate the elements of a parallel array with the case-insensitive version of each word. The method is used to sort the case-sensitive array based on the order of elements in the uppercase array to ensure that elements appear in the same order regardless of language. [!code-csharp[System.String.ToUpperInvariant#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.string.toupperinvariant/cs/toupperinvariant.cs#1)] [!code-vb[System.String.ToUpperInvariant#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.string.toupperinvariant/vb/toupperinvariant.vb#1)] @@ -14555,7 +14406,7 @@ This member is an explicit interface member implementation. It can be used only The `Trim` method removes from the current string all leading and trailing white-space characters. Each leading and trailing trim operation stops when a non-white-space character is encountered. For example, if the current string is " abc xyz ", the `Trim` method returns "abc xyz". To remove white-space characters between words in a string, use [.NET Regular Expressions](/dotnet/standard/base-types/regular-expressions). > [!NOTE] -> If the `Trim` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading and trailing white space characters found in the current instance are removed. +> If the `Trim` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading and trailing white space characters found in the current instance are removed. If the current string equals or all the characters in the current instance consist of white-space characters, the method returns . @@ -14619,7 +14470,7 @@ The following example uses the [!NOTE] -> If the `Trim(System.Char)` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading and trailing `trimChar` characters found in the current instance are removed. +> If the `Trim(System.Char)` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading and trailing `trimChar` characters found in the current instance are removed. If the current string equals or all the characters in the current instance consist of `trimChar` characters, the method returns . @@ -14690,7 +14541,7 @@ If the current string equals [!NOTE] -> If the `Trim(System.Char[])` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading and trailing `trimChars` characters found in the current instance are removed. +> If the `Trim(System.Char[])` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading and trailing `trimChars` characters found in the current instance are removed. If the current string equals or all the characters in the current instance consist of characters in the `trimChars` array, the method returns . @@ -14752,7 +14603,7 @@ The following example uses the `Trim(System.Char[])` method to remove space, ast The `TrimEnd` method removes from the current string all trailing white-space characters. The trim operation stops when the first non white-space character is encountered at the end of the string. For example, if the current string is " abc xyz ", the `TrimEnd` method returns " abc xyz". > [!NOTE] -> If the `TrimEnd` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all trailing white-space characters are removed from the current string. +> If the `TrimEnd` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all trailing white-space characters are removed from the current string. ]]> @@ -14798,7 +14649,7 @@ The `TrimEnd` method removes from the current string all trailing white-space ch The `TrimEnd(System.Char)` method removes from the current string all trailing `trimChar` characters. The trim operation stops when the first character that is not `trimChar` is encountered at the end of the string. For example, if `trimChar` is `-` and the current string is "---abc---xyz----", the `TrimEnd(System.Char)` method returns "---abc---xyz". > [!NOTE] -> If the `TrimEnd(System.Char)` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all trailing `trimChar` characters are removed from the current string. +> If the `TrimEnd(System.Char)` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all trailing `trimChar` characters are removed from the current string. ]]> @@ -14867,7 +14718,7 @@ The `TrimEnd(System.Char)` method removes from the current string all trailing ` The `TrimEnd(System.Char[])` method removes from the current string all trailing characters that are in the `trimChars` parameter. The trim operation stops when the first character that is not in `trimChars` is encountered at the end of the string. For example, if the current string is "123abc456xyz789" and `trimChars` contains the digits from "1" through "9", the `TrimEnd(System.Char[])` method returns "123abc456xyz". > [!NOTE] -> If the `TrimEnd(System.Char[])` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all trailing characters found in `trimChars` are removed from the current string. +> If the `TrimEnd(System.Char[])` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all trailing characters found in `trimChars` are removed from the current string. ## Examples @@ -14924,7 +14775,7 @@ The following example demonstrates how you can use the `TrimEnd(System.Char[])` The `TrimStart` method removes from the current string all leading white-space characters. The trim operation stops when a non white-space character is encountered. For example, if the current string is " abc xyz ", the `TrimStart` method returns "abc xyz ". > [!NOTE] -> If the `TrimStart` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading white space characters found in the current instance are removed. +> If the `TrimStart` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading white space characters found in the current instance are removed. ]]> @@ -14970,7 +14821,7 @@ The `TrimStart` method removes from the current string all leading white-space c The `TrimStart(System.Char)` method removes from the current string all leading `trimChar` characters. The trim operation stops when a character that is not `trimChar` is encountered. For example, if `trimChar` is `-` and the current string is "---abc---xyz----", the `TrimStart(System.Char)` method returns "abc---xyz----". > [!NOTE] -> If the `TrimStart(System.Char)` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading `trimChar` characters found in the current instance are removed. +> If the `TrimStart(System.Char)` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading `trimChar` characters found in the current instance are removed. ]]> @@ -15039,7 +14890,7 @@ The `TrimStart(System.Char)` method removes from the current string all leading The `TrimStart(System.Char[])` method removes from the current string all leading characters that are in the `trimChars` parameter. The trim operation stops when a character that is not in `trimChars` is encountered. For example, if the current string is "123abc456xyz789" and `trimChars` contains the digits from "1" through "9", the `TrimStart(System.Char[])` method returns "abc456xyz789". > [!NOTE] -> If the `TrimStart(System.Char[])` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading characters that are in the `trimChars` parameter found in the current instance are removed. +> If the `TrimStart(System.Char[])` method removes any characters from the current instance, this method does not modify the value of the current instance. Instead, it returns a new string in which all leading characters that are in the `trimChars` parameter found in the current instance are removed. ## Examples