mcs/class/corlib/Documentation/en/System.Globalization/SortKey.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <Type Name="SortKey" FullName="System.Globalization.SortKey">
   3   <TypeSignature Maintainer="auto" Language="C#" Value="public class SortKey" />
   4   <TypeSignature Language="ILAsm" Value=".class public sequential ansi serializable beforefieldinit SortKey extends System.Object" />
   5   <AssemblyInfo>
   6     <AssemblyName>mscorlib</AssemblyName>
   7     <AssemblyPublicKey>[00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00]</AssemblyPublicKey>
   8     <AssemblyVersion>1.0.5000.0</AssemblyVersion>
   9     <AssemblyVersion>2.0.0.0</AssemblyVersion>
  10     <AssemblyVersion>4.0.0.0</AssemblyVersion>
  11   </AssemblyInfo>
  12   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the &lt;link location="node:gtk-sharp/programming/threads"&gt;Gtk# Thread Programming&lt;/link&gt; for details.</ThreadSafetyStatement>
  13   <Base>
  14     <BaseTypeName>System.Object</BaseTypeName>
  15   </Base>
  16   <Interfaces />
  17   <Attributes>
  18     <Attribute>
  19       <AttributeName>System.Runtime.InteropServices.ComVisible(true)</AttributeName>
  20     </Attribute>
  21   </Attributes>
  22   <Docs>
  23     <remarks>
  24       <attribution license="cc4" from="Microsoft" modified="false" />
  25       <para>A culture-sensitive comparison of two strings depends on each character in the strings having several categories of sort weights, including script, alphabetic, case, and diacritic weights. A sort key serves as the repository of these weights for a particular string. In particular, the value of a <see cref="T:System.Globalization.SortKey" /> object is its key data, which is a series of bytes that encode the string, culture-specific sorting rules, and user-specified compare options. A comparison using sort keys consists of a bitwise comparison of the corresponding key data in each sort key. </para>
  26       <para>An instance of the <see cref="T:System.Globalization.SortKey" /> class is returned by the <see cref="M:System.Globalization.CompareInfo.GetSortKey(System.String)" /> method. </para>
  27       <format type="text/html">
  28         <h2>Performance Considerations</h2>
  29       </format>
  30       <para>When performing a string comparison, the <see cref="M:System.Globalization.SortKey.Compare(System.Globalization.SortKey,System.Globalization.SortKey)" /> and <see cref="Overload:System.Globalization.CompareInfo.Compare" /> methods yield the same results. </para>
  31       <para>In effect, the <see cref="Overload:System.Globalization.CompareInfo.Compare" /> method generates the sort key for each string, performs the comparison, then discards the sort key and returns the result of the comparison. In fact, the <see cref="Overload:System.Globalization.CompareInfo.Compare" /> method does not generate an entire sort key and then perform the comparison. Instead, the method generates the key data for each text element, that is, base character, surrogate pair, or combining character sequence, in each string. The method then compares the key data for the corresponding text elements. The operation terminates as soon as the ultimate result of the comparison is determined. Sort key information is computed, but no <see cref="T:System.Globalization.SortKey" /> object is created. This strategy is economical in terms of performance if both strings are compared once, but becomes expensive if the same strings are compared many times. </para>
  32       <para>The <see cref="M:System.Globalization.SortKey.Compare(System.Globalization.SortKey,System.Globalization.SortKey)" /> method requires generation of a <see cref="T:System.Globalization.SortKey" /> object for each string before performing the comparison. This strategy is expensive in terms of performance for the first comparison because of the time and memory invested to generate the <see cref="T:System.Globalization.SortKey" /> objects. However, it becomes economical if the same sort keys are compared many times. </para>
  33       <para>For example, suppose you write an application that searches a database table for the row in which the string-based index column matches a specified search string. The table contains thousands of rows, and comparing the search string to the index in each row will take a long time. Therefore, when the application stores a row and its index column, it also generates and stores the sort key for the index in a column dedicated to improving search performance. When the application searches for a target row, it compares the sort key for the search string to the sort key for the index string, instead of comparing the search string to the index string. </para>
  34       <format type="text/html">
  35         <h2>Security Considerations</h2>
  36       </format>
  37       <para>The <see cref="M:System.Globalization.CompareInfo.GetSortKey(System.String,System.Globalization.CompareOptions)" /> method returns a <see cref="T:System.Globalization.SortKey" /> object with the value based on a specified string and <see cref="T:System.Globalization.CompareOptions" /> value, and the culture associated with the underlying <see cref="T:System.Globalization.CompareInfo" /> object. If a security decision depends on a string comparison or case change, the application should use the <see cref="M:System.Globalization.CompareInfo.GetSortKey(System.String,System.Globalization.CompareOptions)" /> method of the invariant culture to ensure that the behavior of the operation is consistent, regardless of the culture settings of the operating system. </para>
  38       <para>The application should use the following steps to obtain the <see cref="M:System.Globalization.CompareInfo.GetSortKey(System.String,System.Globalization.CompareOptions)" /> method:</para>
  39       <list type="ordered">
  40         <item>
  41           <para>Use the <see cref="P:System.Globalization.CultureInfo.InvariantCulture" /> property to obtain the invariant culture. </para>
  42         </item>
  43         <item>
  44           <para>Use the <see cref="P:System.Globalization.CultureInfo.CompareInfo" /> property of the invariant culture to obtain a <see cref="T:System.Globalization.CompareInfo" /> object.</para>
  45         </item>
  46         <item>
  47           <para>Use the <see cref="M:System.Globalization.CompareInfo.GetSortKey(System.String,System.Globalization.CompareOptions)" /> method of the <see cref="T:System.Globalization.CompareInfo" /> object. </para>
  48         </item>
  49       </list>
  50       <para>Working with the value of a <see cref="T:System.Globalization.SortKey" /> object is equivalent to calling the Windows API LCMapString method with the LCMAP_SORTKEY value specified. However, for the SortKey object, the sort keys for English characters precede the sort keys for Korean characters.</para>
  51       <para>
  52         <see cref="T:System.Globalization.SortKey" /> objects can be serialized, but only so that they can cross <see cref="T:System.AppDomain" /> objects. If an application serializes a <see cref="T:System.Globalization.SortKey" /> object, the application must regenerate all of the sort keys when there is a new version of the .NET Framework.</para>
  53       <para>For more information about sort keys, see Unicode Technical Standard #10, "Unicode Collation Algorithm" at the <see cref="http://go.microsoft.com/fwlink/?linkid=37123">Unicode home page</see>.</para>
  54     </remarks>
  55     <summary>
  56       <attribution license="cc4" from="Microsoft" modified="false" />
  57       <para>Represents the result of mapping a string to its sort key.</para>
  58     </summary>
  59   </Docs>
  60   <Members>
  61     <Member MemberName="Compare">
  62       <MemberSignature Language="C#" Value="public static int Compare (System.Globalization.SortKey sortkey1, System.Globalization.SortKey sortkey2);" />
  63       <MemberSignature Language="ILAsm" Value=".method public static hidebysig int32 Compare(class System.Globalization.SortKey sortkey1, class System.Globalization.SortKey sortkey2) cil managed" />
  64       <MemberType>Method</MemberType>
  65       <AssemblyInfo>
  66         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
  67         <AssemblyVersion>2.0.0.0</AssemblyVersion>
  68         <AssemblyVersion>4.0.0.0</AssemblyVersion>
  69       </AssemblyInfo>
  70       <ReturnValue>
  71         <ReturnType>System.Int32</ReturnType>
  72       </ReturnValue>
  73       <Parameters>
  74         <Parameter Name="sortkey1" Type="System.Globalization.SortKey" />
  75         <Parameter Name="sortkey2" Type="System.Globalization.SortKey" />
  76       </Parameters>
  77       <Docs>
  78         <remarks>
  79           <attribution license="cc4" from="Microsoft" modified="false" />
  80           <para>The <see cref="M:System.Globalization.SortKey.Compare(System.Globalization.SortKey,System.Globalization.SortKey)" /> method compares the <see cref="P:System.Globalization.SortKey.KeyData" /> properties of the <paramref name="sortkey1" /> and <paramref name="sortkey2" /> parameters. The method yields the same results as the <see cref="M:System.Globalization.CompareInfo.Compare(System.String,System.String)" /> method. </para>
  81         </remarks>
  82         <summary>
  83           <attribution license="cc4" from="Microsoft" modified="false" />
  84           <para>Compares two sort keys.</para>
  85         </summary>
  86         <returns>
  87           <attribution license="cc4" from="Microsoft" modified="false" />
  88           <para>A signed integer that indicates the relationship between <paramref name="sortkey1" /> and <paramref name="sortkey2" />.</para>
  89           <list type="table">
  90             <listheader>
  91               <item>
  92                 <term>
  93                   <para>Value </para>
  94                 </term>
  95                 <description>
  96                   <para>Condition </para>
  97                 </description>
  98               </item>
  99             </listheader>
 100             <item>
 101               <term>
 102                 <para>Less than zero </para>
 103               </term>
 104               <description>
 105                 <para>
 106                   <paramref name="sortkey1" /> is less than <paramref name="sortkey2" />. </para>
 107               </description>
 108             </item>
 109             <item>
 110               <term>
 111                 <para>Zero </para>
 112               </term>
 113               <description>
 114                 <para>
 115                   <paramref name="sortkey1" /> is equal to <paramref name="sortkey2" />. </para>
 116               </description>
 117             </item>
 118             <item>
 119               <term>
 120                 <para>Greater than zero </para>
 121               </term>
 122               <description>
 123                 <para>
 124                   <paramref name="sortkey1" /> is greater than <paramref name="sortkey2" />. </para>
 125               </description>
 126             </item>
 127           </list>
 128         </returns>
 129         <param name="sortkey1">
 130           <attribution license="cc4" from="Microsoft" modified="false" />The first sort key to compare. </param>
 131         <param name="sortkey2">
 132           <attribution license="cc4" from="Microsoft" modified="false" />The second sort key to compare. </param>
 133       </Docs>
 134     </Member>
 135     <Member MemberName="Equals">
 136       <MemberSignature Language="C#" Value="public override bool Equals (object value);" />
 137       <MemberSignature Language="ILAsm" Value=".method public hidebysig virtual instance bool Equals(object value) cil managed" />
 138       <MemberType>Method</MemberType>
 139       <AssemblyInfo>
 140         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 141         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 142         <AssemblyVersion>4.0.0.0</AssemblyVersion>
 143       </AssemblyInfo>
 144       <ReturnValue>
 145         <ReturnType>System.Boolean</ReturnType>
 146       </ReturnValue>
 147       <Parameters>
 148         <Parameter Name="value" Type="System.Object" />
 149       </Parameters>
 150       <Docs>
 151         <remarks>
 152           <attribution license="cc4" from="Microsoft" modified="false" />
 153           <para>Two <see cref="T:System.Globalization.SortKey" /> objects are considered equal if their <see cref="P:System.Globalization.SortKey.KeyData" /> properties are equal.</para>
 154           <para>This method overrides <see cref="M:System.Object.Equals(System.Object)" />.</para>
 155         </remarks>
 156         <summary>
 157           <attribution license="cc4" from="Microsoft" modified="false" />
 158           <para>Determines whether the specified object is equal to the current <see cref="T:System.Globalization.SortKey" /> object.</para>
 159         </summary>
 160         <returns>
 161           <attribution license="cc4" from="Microsoft" modified="false" />
 162           <para>true if the <paramref name="value" /> parameter is equal to the current <see cref="T:System.Globalization.SortKey" /> object; otherwise, false. </para>
 163         </returns>
 164         <param name="value">
 165           <attribution license="cc4" from="Microsoft" modified="false" />The object to compare with the current <see cref="T:System.Globalization.SortKey" /> object. </param>
 166       </Docs>
 167     </Member>
 168     <Member MemberName="GetHashCode">
 169       <MemberSignature Language="C#" Value="public override int GetHashCode ();" />
 170       <MemberSignature Language="ILAsm" Value=".method public hidebysig virtual instance int32 GetHashCode() cil managed" />
 171       <MemberType>Method</MemberType>
 172       <AssemblyInfo>
 173         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 174         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 175         <AssemblyVersion>4.0.0.0</AssemblyVersion>
 176       </AssemblyInfo>
 177       <ReturnValue>
 178         <ReturnType>System.Int32</ReturnType>
 179       </ReturnValue>
 180       <Parameters />
 181       <Docs>
 182         <remarks>
 183           <attribution license="cc4" from="Microsoft" modified="false" />
 184           <para>This method generates the same hash code for two objects that are equal according to the <see cref="M:System.Globalization.SortKey.Equals(System.Object)" /> method.</para>
 185           <para>This method overrides <see cref="M:System.Object.GetHashCode" />.</para>
 186         </remarks>
 187         <summary>
 188           <attribution license="cc4" from="Microsoft" modified="false" />
 189           <para>Serves as a hash function for the current <see cref="T:System.Globalization.SortKey" /> object that is suitable for hashing algorithms and data structures such as a hash table.</para>
 190         </summary>
 191         <returns>
 192           <attribution license="cc4" from="Microsoft" modified="false" />
 193           <para>A hash code for the current <see cref="T:System.Globalization.SortKey" /> object.</para>
 194         </returns>
 195       </Docs>
 196     </Member>
 197     <Member MemberName="KeyData">
 198       <MemberSignature Language="C#" Value="public virtual byte[] KeyData { get; }" />
 199       <MemberSignature Language="ILAsm" Value=".property instance unsigned int8[] KeyData" />
 200       <MemberType>Property</MemberType>
 201       <AssemblyInfo>
 202         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 203         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 204         <AssemblyVersion>4.0.0.0</AssemblyVersion>
 205       </AssemblyInfo>
 206       <ReturnValue>
 207         <ReturnType>System.Byte[]</ReturnType>
 208       </ReturnValue>
 209       <Docs>
 210         <value>To be added: an object of type 'byte []'</value>
 211         <remarks>To be added</remarks>
 212         <summary>
 213           <attribution license="cc4" from="Microsoft" modified="false" />
 214           <para>Gets the byte array representing the current <see cref="T:System.Globalization.SortKey" /> object.</para>
 215         </summary>
 216       </Docs>
 217     </Member>
 218     <Member MemberName="OriginalString">
 219       <MemberSignature Language="C#" Value="public virtual string OriginalString { get; }" />
 220       <MemberSignature Language="ILAsm" Value=".property instance string OriginalString" />
 221       <MemberType>Property</MemberType>
 222       <AssemblyInfo>
 223         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 224         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 225         <AssemblyVersion>4.0.0.0</AssemblyVersion>
 226       </AssemblyInfo>
 227       <ReturnValue>
 228         <ReturnType>System.String</ReturnType>
 229       </ReturnValue>
 230       <Docs>
 231         <value>To be added: an object of type 'string'</value>
 232         <remarks>To be added</remarks>
 233         <summary>
 234           <attribution license="cc4" from="Microsoft" modified="false" />
 235           <para>Gets the original string used to create the current <see cref="T:System.Globalization.SortKey" /> object.</para>
 236         </summary>
 237       </Docs>
 238     </Member>
 239     <Member MemberName="ToString">
 240       <MemberSignature Language="C#" Value="public override string ToString ();" />
 241       <MemberSignature Language="ILAsm" Value=".method public hidebysig virtual instance string ToString() cil managed" />
 242       <MemberType>Method</MemberType>
 243       <AssemblyInfo>
 244         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
 245         <AssemblyVersion>2.0.0.0</AssemblyVersion>
 246         <AssemblyVersion>4.0.0.0</AssemblyVersion>
 247       </AssemblyInfo>
 248       <ReturnValue>
 249         <ReturnType>System.String</ReturnType>
 250       </ReturnValue>
 251       <Parameters />
 252       <Docs>
 253         <remarks>
 254           <attribution license="cc4" from="Microsoft" modified="false" />
 255           <para>The return value is the concatenation of the string "SortKey - ", the culture identifier and compare options of the current <see cref="T:System.Globalization.SortKey" /> object, and the value of the <see cref="P:System.Globalization.SortKey.OriginalString" /> property.</para>
 256           <para>This method overrides <see cref="M:System.Object.ToString" />.</para>
 257         </remarks>
 258         <summary>
 259           <attribution license="cc4" from="Microsoft" modified="false" />
 260           <para>Returns a string that represents the current <see cref="T:System.Globalization.SortKey" /> object.</para>
 261         </summary>
 262         <returns>
 263           <attribution license="cc4" from="Microsoft" modified="false" />
 264           <para>A string that represents the current <see cref="T:System.Globalization.SortKey" /> object.</para>
 265         </returns>
 266       </Docs>
 267     </Member>
 268   </Members>
 269 </Type>