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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_i18n_XCollator_idl__
  20 #define __com_sun_star_i18n_XCollator_idl__
  21
  22 #include <com/sun/star/uno/Exception.idl>
  23 #include <com/sun/star/uno/XInterface.idl>
  24 #include <com/sun/star/lang/Locale.idl>
  25
  26 module com { module sun { module star { module i18n {
  27
  28 /** provides locale-sensitive collation algorithms for string comparison.
  29
  30 */
  31 published interface XCollator: com::sun::star::uno::XInterface
  32 {
  33     /** Compare 2 substrings in specific locale and algorithm.
  34
  35         @param aStr1
  36             First string.
  37
  38         @param nOff1
  39             Offset (from 0) of the first string.
  40
  41         @param nLen1
  42             Length (from offset) of the first substring.
  43
  44         @param aStr2
  45             Second string
  46
  47         @param nOff2
  48             Offset (from 0) of the second string.
  49
  50         @param nLen2
  51             Length (from offset) of the second substring.
  52
  53         @returns
  54             1 if the first string is greater than the second string <br/>
  55             0 if the first string is equal to the second string <br/>
  56             -1 if the first string is less than the second string
  57     */
  58     long compareSubstring(  [in] string aStr1, [in] long nOff1, [in] long nLen1,
  59                             [in] string aStr2, [in] long nOff2, [in] long nLen2 );
  60
  61     /** Compare 2 strings in specific locale and algorithm.
  62
  63         @param aStr1
  64             First string.
  65
  66         @param aStr2
  67             Second string.
  68
  69         @returns
  70             1 if the first string is greater than the second string <br/>
  71             0 if the first string is equal to the second string <br/>
  72             -1 if the first string is less than the second string
  73     */
  74     long compareString( [in] string aStr1, [in] string aStr2 );
  75
  76     /** Load the collator with default algorithm defined in
  77         locale data.
  78
  79         @param aLocale
  80             The locale for this collator.
  81
  82         @param nCollatorOptions
  83             A mask of CollatorOptions.
  84
  85         @returns
  86             Returns 0 when loading was successful,
  87             otherwise throws runtime exception. In fact the return value
  88             should be ignored and the exception be caught instead.
  89     */
  90     long loadDefaultCollator(   [in] ::com::sun::star::lang::Locale aLocale,
  91                                 [in] long nCollatorOptions );
  92
  93     /** Load a particular collator algorithm for the locale.
  94
  95         @param aAlgorithmName
  96             The algorithm to load.
  97
  98         @param aLocale
  99             The locale for this collator.
 100
 101         @param nCollatorOptions
 102             A mask of CollatorOptions.
 103
 104         @returns
 105             Returns 0 when loading was successful,
 106             otherwise throws runtime exception.
 107     */
 108     long loadCollatorAlgorithm( [in] string aAlgorithmName,
 109                                 [in] ::com::sun::star::lang::Locale aLocale,
 110                                 [in] long nCollatorOptions );
 111
 112     /** List all collator algorithms for a given locale.
 113
 114         @param aLocale
 115             The locale for which to list algorithms.
 116
 117         @returns
 118             A sequence of algorithm names.
 119     */
 120     sequence <string> listCollatorAlgorithms(
 121                                 [in] ::com::sun::star::lang::Locale aLocale );
 122
 123     /** Load a collator algorithm with options chosen by end user.
 124
 125         @param aAlgorithmName
 126             The algorithm name to load.
 127
 128         @param aLocale
 129             The locale for this collator.
 130
 131         @param aCollatorOptions
 132             A sequence of end user collator options like those returned
 133             by XCollator::listCollatorOptions().
 134     */
 135     void loadCollatorAlgorithmWithEndUserOption(
 136                                 [in] string aAlgorithmName,
 137                                 [in] ::com::sun::star::lang::Locale aLocale,
 138                                 [in] sequence<long> aCollatorOptions );
 139
 140     /** List all end user collator options for a given algorithm.
 141
 142         @param aAlgorithmName
 143             The algorithm name for this collator.
 144
 145         @returns
 146             An array of end user options available for the algorithm.
 147     */
 148     sequence <long> listCollatorOptions( [in] string aAlgorithmName );
 149
 150 };
 151
 152
 153 }; }; }; };
 154
 155
 156 #endif
 157
 158 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */