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