offapi/com/sun/star/i18n/XCollator.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*************************************************************************
   3  *
   4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5  *
   6  * Copyright 2000, 2010 Oracle and/or its affiliates.
   7  *
   8  * OpenOffice.org - a multi-platform office productivity suite
   9  *
  10  * This file is part of OpenOffice.org.
  11  *
  12  * OpenOffice.org is free software: you can redistribute it and/or modify
  13  * it under the terms of the GNU Lesser General Public License version 3
  14  * only, as published by the Free Software Foundation.
  15  *
  16  * OpenOffice.org is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU Lesser General Public License version 3 for more details
  20  * (a copy is included in the LICENSE file that accompanied this code).
  21  *
  22  * You should have received a copy of the GNU Lesser General Public License
  23  * version 3 along with OpenOffice.org.  If not, see
  24  * <http://www.openoffice.org/license.html>
  25  * for a copy of the LGPLv3 License.
  26  *
  27  ************************************************************************/
  28 #ifndef __com_sun_star_i18n_XCollator_idl__
  29 #define __com_sun_star_i18n_XCollator_idl__
  30
  31 #include <com/sun/star/uno/Exception.idl>
  32 #include <com/sun/star/uno/XInterface.idl>
  33 #include <com/sun/star/lang/Locale.idl>
  34 //=============================================================================
  35
  36 module com { module sun { module star { module i18n {
  37
  38 /** provides locale-sensitive collation algorithms for string comparison.
  39
  40 */
  41 published interface XCollator: com::sun::star::uno::XInterface
  42 {
  43     //-------------------------------------------------------------------------
  44     /** Compare 2 substrings in specific locale and algorithm.
  45
  46         @param aStr1
  47             First string.
  48
  49         @param nOff1
  50             Offset (from 0) of the first string.
  51
  52         @param nLen1
  53             Length (from offset) of the first substring.
  54
  55         @param aStr2
  56             Second string
  57
  58         @param nOff2
  59             Offset (from 0) of the second string.
  60
  61         @param nLen2
  62             Length (from offset) of the second substring.
  63
  64         @returns
  65             1 if the first string is greater than the second string <br/>
  66             0 if the first string is equal to the second string <br/>
  67             -1 if the first string is less than the second string
  68     */
  69     long compareSubstring(  [in] string aStr1, [in] long nOff1, [in] long nLen1,
  70                             [in] string aStr2, [in] long nOff2, [in] long nLen2 );
  71
  72     //-------------------------------------------------------------------------
  73     /** Compare 2 strings in specific locale and algorithm.
  74
  75         @param aStr1
  76             First string.
  77
  78         @param aStr2
  79             Second string.
  80
  81         @returns
  82             1 if the first string is greater than the second string <br/>
  83             0 if the first string is equal to the second string <br/>
  84             -1 if the first string is less than the second string
  85     */
  86     long compareString( [in] string aStr1, [in] string aStr2 );
  87
  88     //-------------------------------------------------------------------------
  89     /** Load the collator with default algorithm defined in
  90         locale data.
  91
  92         @param aLocale
  93             The locale for this collator.
  94
  95         @param nCollatorOptions
  96             A mask of <type>CollatorOptions</type>.
  97
  98         @returns
  99             Returns 0 when loading was successful,
 100             otherwise throws runtime exception. In fact the return value
 101             should be ignored and the exception be caught instead.
 102     */
 103     long loadDefaultCollator(   [in] ::com::sun::star::lang::Locale aLocale,
 104                                 [in] long nCollatorOptions );
 105
 106     //-------------------------------------------------------------------------
 107     /** Load a particular collator algorithm for the locale.
 108
 109         @param aAlgorithmName
 110             The algorithm to load.
 111
 112         @param aLocale
 113             The locale for this collator.
 114
 115         @param nCollatorOptions
 116             A mask of <type>CollatorOptions</type>.
 117
 118         @returns
 119             Returns 0 when loading was successful,
 120             otherwise throws runtime exception.
 121     */
 122     long loadCollatorAlgorithm( [in] string aAlgorithmName,
 123                                 [in] ::com::sun::star::lang::Locale aLocale,
 124                                 [in] long nCollatorOptions );
 125
 126     //-------------------------------------------------------------------------
 127     /** List all collator algorithms for a given locale.
 128
 129         @param aLocale
 130             The locale for which to list algorithms.
 131
 132         @returns
 133             A sequence of algorithm names.
 134     */
 135     sequence <string> listCollatorAlgorithms(
 136                                 [in] ::com::sun::star::lang::Locale aLocale );
 137
 138     //-------------------------------------------------------------------------
 139     /** Load a collator algorithm with options chosen by end user.
 140
 141         @param aAlgorithmName
 142             The algorithm name to load.
 143
 144         @param aLocale
 145             The locale for this collator.
 146
 147         @param aCollatorOptions
 148             A sequence of end user collator options like those returned
 149             by <member>XCollator::listCollatorOptions()</member>.
 150     */
 151     void loadCollatorAlgorithmWithEndUserOption(
 152                                 [in] string aAlgorithmName,
 153                                 [in] ::com::sun::star::lang::Locale aLocale,
 154                                 [in] sequence<long> aCollatorOptions );
 155
 156     //-------------------------------------------------------------------------
 157     /** List all end user collator options for a given algorithm.
 158
 159         @param aAlgorithmName
 160             The algorithm name for this collator.
 161
 162         @returns
 163             An array of end user options available for the algorithm.
 164     */
 165     sequence <long> listCollatorOptions( [in] string aAlgorithmName );
 166
 167 };
 168
 169 //=============================================================================
 170
 171 }; }; }; };
 172
 173 //=============================================================================
 174
 175 #endif
 176
 177 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */