Switch to a recommendation of Ordinal

dotnet · Oct 13, 2023 · b3a3dbd · b3a3dbd
1 parent d256314
commit b3a3dbd
Showing 1 changed file with 10 additions and 10 deletions.
diff --git a/xml/System/String.xml b/xml/System/String.xml
@@ -5287,7 +5287,7 @@ This method performs an ordinal (case-sensitive and culture-insensitive) compari
         <exception cref="T:System.ArgumentNullException">
           <paramref name="value" /> is <see langword="null" />.</exception>
         <block subset="none" type="usage">
-          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To determine whether a string ends with a particular substring by using the string comparison rules of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.EndsWith(System.String,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its <paramref name="comparisonType" /> parameter. Note that <see cref="F:System.StringComparison.InvariantCulture" /> is rarely appropriate.</para>
+          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To determine whether a string ends with a particular substring by using the string comparison rules of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.EndsWith(System.String,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its <paramref name="comparisonType" /> parameter. If you don't need linguistic-aware comparison, consider using <see cref="F:System.StringComparison.Ordinal" />.</para>
         </block>
         <altmember cref="M:System.String.StartsWith(System.String)" />
         <altmember cref="M:System.String.Compare(System.String,System.String)" />
@@ -8014,7 +8014,7 @@ The `GetPinnableReference` method returns a character that can be used for pinni
         <exception cref="T:System.ArgumentNullException">
           <paramref name="value" /> is <see langword="null" />.</exception>
         <block subset="none" type="usage">
-          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To find the first index of a substring within a string instance by using the comparison rules of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.IndexOf(System.String,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its `comparisonType` parameter. Note that <see cref="F:System.StringComparison.InvariantCulture" /> is rarely appropriate.</para>
+          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To find the first index of a substring within a string instance by using the comparison rules of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.IndexOf(System.String,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its `comparisonType` parameter. If you don't need linguistic-aware comparison, consider using <see cref="F:System.StringComparison.Ordinal" />.</para>
         </block>
         <altmember cref="T:System.Int32" />
         <altmember cref="T:System.Globalization.CultureInfo" />
@@ -8230,7 +8230,7 @@ The `comparisonType` parameter is a <xref:System.StringComparison> enumeration m
         <exception cref="T:System.ArgumentOutOfRangeException">
           <paramref name="startIndex" /> is less than 0 (zero) or greater than the length of this string.</exception>
         <block subset="none" type="usage">
-          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To find the first index of a substring that occurs after a particular character position by using the comparison rules of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.IndexOf(System.String,System.Int32,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its `comparisonType` parameter. Note that <see cref="F:System.StringComparison.InvariantCulture" /> is rarely appropriate.</para>
+          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To find the first index of a substring that occurs after a particular character position by using the comparison rules of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.IndexOf(System.String,System.Int32,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its `comparisonType` parameter. If you don't need linguistic-aware comparison, consider using <see cref="F:System.StringComparison.Ordinal" />.</para>
         </block>
         <altmember cref="T:System.Int32" />
         <altmember cref="T:System.Globalization.CultureInfo" />
@@ -8502,7 +8502,7 @@ The `comparisonType` parameter is a <xref:System.StringComparison> enumeration m
 
  <paramref name="count" /> is greater than the length of this string minus <paramref name="startIndex" />.</exception>
         <block subset="none" type="usage">
-          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To use the comparison rules of the current culture to perform this operation, signal your intention explicitly by calling the <see cref="M:System.String.IndexOf(System.String,System.Int32,System.Int32,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its `comparisonType` parameter. Note that <see cref="F:System.StringComparison.InvariantCulture" /> is rarely appropriate.</para>
+          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To use the comparison rules of the current culture to perform this operation, signal your intention explicitly by calling the <see cref="M:System.String.IndexOf(System.String,System.Int32,System.Int32,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its `comparisonType` parameter. If you don't need linguistic-aware comparison, consider using <see cref="F:System.StringComparison.Ordinal" />.</para>
         </block>
         <altmember cref="T:System.Int32" />
         <altmember cref="T:System.Globalization.CultureInfo" />
@@ -10501,7 +10501,7 @@ In the following example, the <xref:System.String.LastIndexOf%28System.String%29
         <exception cref="T:System.ArgumentNullException">
           <paramref name="value" /> is <see langword="null" />.</exception>
         <block subset="none" type="usage">
-          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To find the last index of a substring within a string instance by using the comparison rules of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.LastIndexOf(System.String,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its <paramref name="comparisonType" /> parameter. Note that <see cref="F:System.StringComparison.InvariantCulture" /> is rarely appropriate.</para>
+          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To find the last index of a substring within a string instance by using the comparison rules of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.LastIndexOf(System.String,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its <paramref name="comparisonType" /> parameter. If you don't need linguistic-aware comparison, consider using <see cref="F:System.StringComparison.Ordinal" />.</para>
         </block>
         <altmember cref="T:System.Int32" />
         <altmember cref="M:System.String.IndexOf(System.Char)" />
@@ -10661,7 +10661,7 @@ In the following example, the <xref:System.String.LastIndexOf%28System.String%29
 
  The current instance equals <see cref="F:System.String.Empty" />, and <paramref name="startIndex" /> is less than -1 or greater than zero.</exception>
         <block subset="none" type="usage">
-          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To find the index of a substring that precedes a particular character position by using the comparison rules of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.LastIndexOf(System.String,System.Int32,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its <paramref name="comparisonType" /> parameter. Note that <see cref="F:System.StringComparison.InvariantCulture" /> is rarely appropriate.</para>
+          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To find the index of a substring that precedes a particular character position by using the comparison rules of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.LastIndexOf(System.String,System.Int32,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its <paramref name="comparisonType" /> parameter. If you don't need linguistic-aware comparison, consider using <see cref="F:System.StringComparison.Ordinal" />.</para>
         </block>
         <altmember cref="T:System.Int32" />
         <altmember cref="M:System.String.IndexOf(System.Char)" />
@@ -10950,7 +10950,7 @@ In the following example, the <xref:System.String.LastIndexOf%2A> method is used
 
  The current instance equals <see cref="F:System.String.Empty" /> and <paramref name="count" /> is greater than 1.</exception>
         <block subset="none" type="usage">
-          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To perform this operation by using the comparison rules of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.LastIndexOf(System.String,System.Int32,System.Int32,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its <paramref name="comparisonType" /> parameter. Note that <see cref="F:System.StringComparison.InvariantCulture" /> is rarely appropriate.</para>
+          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To perform this operation by using the comparison rules of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.LastIndexOf(System.String,System.Int32,System.Int32,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its <paramref name="comparisonType" /> parameter. If you don't need linguistic-aware comparison, consider using <see cref="F:System.StringComparison.Ordinal" />.</para>
         </block>
         <altmember cref="T:System.Int32" />
         <altmember cref="M:System.String.IndexOf(System.Char)" />
@@ -13929,7 +13929,7 @@ The following example defines a `StripStartTags` method that uses the <xref:Syst
         <exception cref="T:System.ArgumentNullException">
           <paramref name="value" /> is <see langword="null" />.</exception>
         <block subset="none" type="usage">
-          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To determine whether a string begins with a particular substring by using the string comparison rules of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.StartsWith(System.String,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its <paramref name="comparisonType" /> parameter. Note that <see cref="F:System.StringComparison.InvariantCulture" /> is rarely appropriate.</para>
+          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string comparison methods that substitute default values and instead call methods that require parameters to be explicitly specified. To determine whether a string begins with a particular substring by using the string comparison rules of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.StartsWith(System.String,System.StringComparison)" /> method overload with a value of <see cref="F:System.StringComparison.CurrentCulture" /> for its <paramref name="comparisonType" /> parameter. If you don't need linguistic-aware comparison, consider using <see cref="F:System.StringComparison.Ordinal" />.</para>
         </block>
         <altmember cref="M:System.String.EndsWith(System.String)" />
       </Docs>
@@ -15953,7 +15953,7 @@ This member is an explicit interface member implementation. It can be used only
  ]]></format>
         </remarks>
         <block subset="none" type="usage">
-          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string casing methods that substitute default values and instead call methods that require parameters to be explicitly specified. To convert a character to lowercase by using the casing conventions of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.ToLower(System.Globalization.CultureInfo)" /> method overload with a value of <see cref="P:System.Globalization.CultureInfo.CurrentCulture" /> for its <paramref name="culture" /> parameter. Note that <see cref="F:System.StringComparison.InvariantCulture" /> is rarely appropriate.</para>
+          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string casing methods that substitute default values and instead call methods that require parameters to be explicitly specified. To convert a character to lowercase by using the casing conventions of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.ToLower(System.Globalization.CultureInfo)" /> method overload with a value of <see cref="P:System.Globalization.CultureInfo.CurrentCulture" /> for its <paramref name="culture" /> parameter. If you don't need linguistic-aware comparison, consider using <see cref="F:System.StringComparison.Ordinal" />.</para>
         </block>
         <altmember cref="M:System.String.ToLowerInvariant" />
         <altmember cref="M:System.String.ToUpper" />
@@ -16342,7 +16342,7 @@ This member is an explicit interface member implementation. It can be used only
  ]]></format>
         </remarks>
         <block subset="none" type="usage">
-          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string casing methods that substitute default values and instead call methods that require parameters to be explicitly specified. To convert a string to uppercase by using the casing conventions of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.ToUpper(System.Globalization.CultureInfo)" /> method overload with a value of <see cref="P:System.Globalization.CultureInfo.CurrentCulture" /> for its <paramref name="culture" /> parameter. Note that <see cref="F:System.StringComparison.InvariantCulture" /> is rarely appropriate.</para>
+          <para>As explained in [Best Practices for Using Strings](/dotnet/standard/base-types/best-practices-strings), we recommend that you avoid calling string casing methods that substitute default values and instead call methods that require parameters to be explicitly specified. To convert a string to uppercase by using the casing conventions of the current culture, signal your intention explicitly by calling the <see cref="M:System.String.ToUpper(System.Globalization.CultureInfo)" /> method overload with a value of <see cref="P:System.Globalization.CultureInfo.CurrentCulture" /> for its <paramref name="culture" /> parameter. If you don't need linguistic-aware comparison, consider using <see cref="F:System.StringComparison.Ordinal" />.</para>
         </block>
         <altmember cref="M:System.String.ToLower" />
         <altmember cref="M:System.String.ToLowerInvariant" />