<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../../make-menu.xsl" type="text/xsl"?><html>
   <head>
      <this-is section="extensions" page="instructions" subpage="collation"/>
      <!--
           Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: saxon:collation</title>
      <meta name="coverage" content="Worldwide"/>
      <meta name="copyright" content="Copyright Saxonica Ltd"/>
      <meta name="title" content="Saxonica: XSLT and XQuery Processing: saxon:collation"/>
      <meta name="robots" content="noindex,nofollow"/>
      <link rel="stylesheet" href="../../saxondocs.css" type="text/css"/>
   </head>
   <body class="main">
      <h1>saxon:collation</h1>
      <div class="boxed"
           style="border: solid thin; background-color: #B1CCC7; padding: 2px">
            <b>saxon:collation is deprecated.</b> Instead, you can define collations in 
a configuration file: see <a class="bodylink"
            href="../../configuration/configuration-file/config-collations.xml">The collations element</a>.
It is also possible to specify a collation directly by using a URI of
the form <code>http://saxon.sf.net/collation?keyword=value;keyword=value;...</code>.
For details see <a class="bodylink" href="../../extensibility/collation.xml">Collations</a>.</div>
      <p>The <code>saxon:collation</code> element is a top-level element used to define 
collating sequences that may be used in sort keys and in functions such as 
<code>compare()</code>.</p>
      <p>The collation name is a URI, and
is defined in the mandatory <code>name</code> attribute. This must be a valid URI.
If it is a relative URI, it is interpreted as being relative to the base URI of the
<code>saxon:collation</code> element itself.</p>
      <p>The <b>default</b> attribute was used in earlier Saxon releases to identify the default
collation. From Saxon 8.8 this attribute is ignored, with a warning. To specify the default
collation, use the standard <code>[xsl:]default-collation</code> attribute.</p>
      <p>The other attributes 
control how the collation is defined. These attributes have the same effect as the corresponding
query parameters in a URI starting with <code>http://saxon.sf.net/collation?</code>, and are
described <a class="bodylink" href="../../extensibility/collation.xml">here</a>.</p>
      <p>Specifically, these attributes are:</p>
      <table>
         <thead>
            <tr>
               <td content="para">
                  <p>
                     <b>attribute</b>
                  </p>
               </td>
               <td content="para">
                  <p>
                     <b>values</b>
                  </p>
               </td>
               <td content="para">
                  <p>
                     <b>effect</b>
                  </p>
               </td>
            </tr>
         </thead>
         <tbody>
            <tr>
               <td content="para">
                  <p>class</p>
               </td>
               <td content="para">
                  <p>fully-qualified Java class name of a class that
implements <code>java.util.Comparator</code>.</p>
               </td>
               <td content="para">
                  <p>This parameter should not be combined with any other parameter.
An instance of the requested class is created, and is used to perform
the comparisons. Note that if the collation is to be used
in functions such as contains() and starts-with(), this class must also be a
<code>java.text.RuleBasedCollator</code>. This approach allows a user-defined collation
to be implemented in Java.This option is also available on the .NET platform, but the class must implement
the Java interface java.util.Comparator.</p>
               </td>
            </tr>
            <tr>
               <td content="para">
                  <p>rules</p>
               </td>
               <td content="para">
                  <p>details of the ordering required, using the syntax of the Java 
<code>RuleBasedCollator</code>
                  </p>
               </td>
               <td content="para">
                  <p>This defines exactly how individual characters are collated.This option is also available on the .NET platform, and if used will select a collation
provided using the GNU Classpath implementation of <code>RuleBasedCollator</code>. At the time of writing,
this is not 100% compatible with the Sun JDK implementation.</p>
               </td>
            </tr>
            <tr>
               <td content="para">
                  <p>lang</p>
               </td>
               <td content="para">
                  <p>any value allowed for xml:lang, for example <code>en-US</code> for US English</p>
               </td>
               <td content="para">
                  <p>This is used to find the collation appropriate to a Java locale or .NET culture. 
The collation may be further tailored using the parameters described below.</p>
               </td>
            </tr>
            <tr>
               <td content="para">
                  <p>ignore-case</p>
               </td>
               <td content="para">
                  <p>yes, no</p>
               </td>
               <td content="para">
                  <p>Indicates whether the upper and lower case letters are considered
equivalent. Note that even when ignore-case is set to "no", case is less significant than
the actual letter value, so that "XPath" and "Xpath" will appear next to each other in the
sorted sequence.On the Java platform, setting ignore-case sets the collation strength to secondary.</p>
               </td>
            </tr>
            <tr>
               <td content="para">
                  <p>ignore-modifiers</p>
               </td>
               <td content="para">
                  <p>yes, no</p>
               </td>
               <td content="para">
                  <p>Indicates whether non-spacing combining characters 
(such as accents and diacritical marks) are considered
significant. Note that even when ignore-modifiers is set to "no", modifiers are less significant than
the actual letter value, so that "Hofen" and "Höfen" will appear next to each other in the
sorted sequence.On the Java platform, setting ignore-case sets the collation strength to primary.</p>
               </td>
            </tr>
            <tr>
               <td content="para">
                  <p>ignore-symbols</p>
               </td>
               <td content="para">
                  <p>yes, no</p>
               </td>
               <td content="para">
                  <p>Indicates whether symbols such as whitespace characters and punctuation
marks are to be ignored. This option currently has no effect on the Java platform, where
such symbols are in most cases ignored by default.</p>
               </td>
            </tr>
            <tr>
               <td content="para">
                  <p>ignore-width</p>
               </td>
               <td content="para">
                  <p>yes, no</p>
               </td>
               <td content="para">
                  <p>Indicates whether characters that differ only in width should be considered
equivalent.On the Java platform, setting ignore-width sets the collation strength to tertiary.</p>
               </td>
            </tr>
            <tr>
               <td content="para">
                  <p>strength</p>
               </td>
               <td content="para">
                  <p>primary, secondary, tertiary, or identical</p>
               </td>
               <td content="para">
                  <p>Indicates the differences that are considered significant when comparing
two strings. A/B is a primary difference; A/a is a secondary difference;
a/ä is a tertiary difference (though this varies by language). So
if strength=primary then A=a is true; with strength=secondary 
then A=a is false but a=ä is true; with strength=tertiary
then a=ä is false.This option should not be combined with the ignore-XXX options. The setting "primary" is
equivalent to ignoring case, modifiers, and width; "secondary" is equivalent to ignoring
case and width; "tertiary" ignores width only; and "identical" ignores nothing.</p>
               </td>
            </tr>
            <tr>
               <td content="para">
                  <p>decomposition</p>
               </td>
               <td content="para">
                  <p>none, standard, full</p>
               </td>
               <td content="para">
                  <p>Indicates how the collator handles Unicode composed characters. See
the JDK documentation for details. This option is ignored on the .NET platform.</p>
               </td>
            </tr>
            <tr>
               <td content="para">
                  <p>alphanumeric</p>
               </td>
               <td content="para">
                  <p>yes, no</p>
               </td>
               <td content="para">
                  <p>If set to yes, the string is split into a sequence of alphabetic and numeric parts (a numeric
part is any consecutive sequence of ASCII digits; anything else is considered alphabetic). Eacn numeric part is considered
to be preceded by an alphabetic part even if it is zero-length. The parts are then compared pairwise: alphabetic parts
using the collation implied by the other query parameters, numeric parts using their numeric value. The result is that,
for example, AD985 collates before AD1066.Note that an alphanumeric collation cannot be used in conjunction with functions such as contains() and substring-before().</p>
               </td>
            </tr>
            <tr>
               <td content="para">
                  <p>case-order</p>
               </td>
               <td content="para">
                  <p>upper-first, lower-first</p>
               </td>
               <td content="para">
                  <p>Indicates whether upper case letters collate before or after lower case
letters.</p>
               </td>
            </tr>
         </tbody>
      </table>
      <p>Sorting and comparison according to Unicode codepoints can be achieved by setting up a collator as 
<code>&lt;saxon:collation name="unicode" class="net.sf.saxon.sort.CodepointCollator"/&gt;</code></p>
      <p><i>Note that a stylesheet containing a <code>saxon:collation</code> declaration cannot be
compiled at this release, because the underlying Java classes are not serializable.</i></p>
      <table width="100%">
         <tr>
            <td>
               <p align="right"><a class="nav" href="continue.xml">Next</a></p>
            </td>
         </tr>
      </table>
   </body>
</html>