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_XTransliteration_idl__
24#define __com_sun_star_i18n_XTransliteration_idl__
25
26#include <com/sun/star/lang/Locale.idl>
27#include <com/sun/star/uno/XInterface.idl>
28#include <com/sun/star/i18n/TransliterationModules.idl>
29#include <com/sun/star/i18n/TransliterationModulesNew.idl>
30
31//=============================================================================
32
33module com { module sun { module star { module i18n {
34
35//=============================================================================
36
37/**
38    Character conversions like case folding or Hiragana to Katakana.
39
40    <p> Transliteration is a character to character conversion but it is
41    not always a one to one mapping between characters. Transliteration
42    modules are primarily used by collation, and search and replace
43    modules to perform approximate search. It can also be used to format
44    the numbers in different numbering systems. <p/>
45
46    <p> In order to select transliteration modules for different
47    purposes, they are classified with attributes of
48    <type>TransliterationType</type>. <p/>
49
50    <p> For Western languages there would be three transliteration
51    modules available to compare two mixed case strings: upper to lower,
52    lower to upper, and ignore case. </p>
53
54    <p> A typical calling sequence of transliteration is
55        <ol>
56            <li> getAvailableModules() </li>
57            <li> loadModulesByImplNames() </li>
58            <li> equals() </li>
59        </ol>
60    or another one is
61        <ol>
62            <li> loadModule() </li>
63            <li> transliterate() </li>
64        </ol>
65    </p>
66
67*/
68
69/* comment:
70 * 0.
71 * All the IGNORE-type functionalities (Range, equals) are based on mapping.
72 * except equals() method in IGNORE_CASE, which is based on Locale-independent
73 * casefolding
74 * ( This second assumption is very complicated and may cause confusion of use)
75 *
76 * 1.
77 * We are assuming Upper to Lower mapping as one of transliteration.
78 * The mapping depends on Locale.
79 * Upper <-> Lower methods are just wrappers to provide equals() and Range()
80 *
81 * 2.
82 * equals() in IGNORE_CASE module is locale-independent and
83 * we don't provide locale-sensitive ones.
84 * The reason we provided locale-independent ones is that IGNORE_CASE is mainly
85 * dedicated to StarOffice internal code.
86 *
87 * 3.
88 * TransliterationModules is used just for convenience without calling
89 * getAvailableModule.
90 *
91 * 4.
92 * Implementation name in the methods below is not the same as
93 * the true implemenation name registered.
94 * In particular, for generic modules:"UPPERCASE_LOWERCASE",
95 * "LOWERCASE_UPPERCASE", "IGNORE_CASE", there is no registered name.
96 */
97
98
99published interface XTransliteration: com::sun::star::uno::XInterface
100{
101
102    //------------------------------------------------------------------------
103    /** Unique ASCII name to identify a module. This name is used
104        to get its localized name for menus, dialogs etc. The behavior
105        is undefined for <const>TransliterationType::CASCADE</const>
106        modules.
107     */
108    string  getName();
109
110    //------------------------------------------------------------------------
111    /** Return the attribute(s) associated with this transliterator
112        object, as defined in <type>TransliterationType</type>. The
113        value is determined by the transliteration modules. For example,
114        for UPPERCASE_LOWERCASE, a ONE_TO_ONE is returned, for
115        IGNORE_CASE, IGNORE is returned.
116     */
117    short   getType();
118
119    //------------------------------------------------------------------------
120    /** Load instance of predefined module - old style method.
121     */
122    void    loadModule( [in] TransliterationModules eModType,
123                        [in] ::com::sun::star::lang::Locale aLocale );
124
125    //------------------------------------------------------------------------
126    /** Load a sequence of instances of predefined modules - supersedes
127        method <member>XTransliteration::loadModule()</member>.
128     */
129    void    loadModuleNew(  [in] sequence <TransliterationModulesNew> aModType,
130                            [in] ::com::sun::star::lang::Locale aLocale );
131
132    //------------------------------------------------------------------------
133    /** Load instance of UNO registered module.
134
135        <p> Each transliteration module is registered under a different
136        service name. The convention for the service name is
137        com.sun.star.i18n.Transliteration.l10n.{implName}. The
138        {implName} is a unique name used to identify a module. The
139        implName is used to get a localized name for the transliteration
140        module. The implName is used in locale data to list the
141        available transliteration modules for the locale. There are some
142        transliteration modules that are always available. The names of
143        those modules are listed as enum
144        <type>TransliterationModules</type> names. For modules not
145        listed there it is possible to load them directly by their
146        implName.
147
148        @param aImplName
149            The module's {implName} under which it is registered with
150            com.sun.star.i18n.Transliteration.l10n.{implName}.
151     */
152    void    loadModuleByImplName(   [in] string aImplName,
153                                    [in] ::com::sun::star::lang::Locale aLocale );
154
155    //------------------------------------------------------------------------
156    /** Load a sequence of instances of transliteration modules.
157        Output of one module is feeded as input to the next module in
158        the sequence. The object created by this call has
159        <type>TransliterationType</type> CASCADE and IGNORE types.
160
161        @param aImplNameList
162            Only IGNORE type modules can be specified.
163    */
164    void    loadModulesByImplNames( [in] sequence <string> aImplNameList,
165                                    [in] ::com::sun::star::lang::Locale aLocale );
166
167    //------------------------------------------------------------------------
168    /** List the available transliteration modules for a given locale.
169        It can be filtered based on its type.
170
171        @param nType
172            A bitmask field of values defined in
173            <type>TransliterationType</type>
174    */
175    sequence<string>    getAvailableModules(
176                            [in] ::com::sun::star::lang::Locale aLocale,
177                            [in] short nType );
178
179
180    //------------------------------------------------------------------------
181    /** Transliterate a substring. This method can be called if the
182        object doesn't have <type>TransliterationType</type> IGNORE
183        attribute.
184
185        @param aStr
186            The input string.
187
188        @param nStartPos
189            Start position within aStr from where transliteration starts.
190
191        @param nCount
192            Number of codepoints to be transliterated.
193
194        @param rOffset
195            To find the grapheme of input string corresponding to the
196            grapheme of output string, rOffset provides the offset array
197            whose index is the offset of output string, the element
198            containing the position within the input string before
199            transliteration.
200     */
201    string  transliterate(  [in] string aInStr, [in] long nStartPos,
202                            [in] long nCount, [out] sequence <long> rOffset );
203
204    //------------------------------------------------------------------------
205    /** @deprecated
206        For internal use, this method is supported to get the
207        "transliteration", which equals() is based on.
208     */
209    string  folding(    [in] string aInStr, [in] long nStartPos,
210                        [in] long nCount, [out] sequence <long> rOffset );
211
212    //------------------------------------------------------------------------
213    /** Match two substrings and find if they are equivalent as per this
214        transliteration.
215
216        <p> This method can be called if the object has
217        <type>TransliterationType</type> IGNORE attribute. </p>
218
219        <p> Returns the number of matched code points in any case, even if
220        strings are not equal, for example: <br/>
221        equals( "a", 0, 1, nMatch1, "aaa", 0, 3, nMatch2 ) <br/>
222        returns <FALSE/> and nMatch:=1 and nMatch2:=1 <br/>
223        equals( "aab", 0, 3, nMatch1, "aaa", 0, 3, nMatch2 ) <br/>
224        returns <FALSE/> and nMatch:=2 and nMatch2:=2 <br/> </p>
225
226        @param aStr1
227            First string to match.
228
229        @param nPos1
230            Start position within aStr1.
231
232        @param nCount1
233            Number of code points to use of aStr1.
234
235        @param rMatch1
236            Returns number of matched code points in aStr1.
237
238        @param aStr2
239            Second string to match.
240
241        @param nPos2
242            Start position within aStr2.
243
244        @param nCount2
245            Number of code points to use of aStr2.
246
247        @param rMatch2
248            Returns number of matched code points in aStr2.
249
250        @returns
251            <TRUE/> if the substrings are equal per this
252            transliteration <br/>
253            <FALSE/> else.
254     */
255
256    boolean equals( [in] string aStr1, [in] long nPos1, [in] long nCount1,
257                    [out] long rMatch1,
258                    [in] string aStr2, [in] long nPos2, [in] long nCount2,
259                    [out] long rMatch2 );
260
261    //------------------------------------------------------------------------
262    /** Transliterate one set of characters to another.
263
264        <p> This method is intended for getting corresponding ranges and
265        can be called if the object has <type>TransliterationType</type>
266        IGNORE attribute. </p>
267
268        <p> For example: generic CASE_IGNORE transliterateRange( "a", "i" )
269        returns {"A","I","a","i"}, transliterateRange( "a", "a" )
270        returns {"A","A","a","a"}. </p>
271
272        <p> Use this transliteration to create regular expresssions like
273        [a-i] --> [A-Ia-i]. </p>
274
275        @returns
276            String sequence containing corresponding transliterated
277            pairs of characters to represent a range.
278     */
279    sequence <string>   transliterateRange( [in] string aStr1, [in] string aStr2 );
280
281    //------------------------------------------------------------------------
282    /** Compare 2 substrings as per this transliteration. It translates both
283        substrings before comparing them.
284
285        @param aStr1
286            First string.
287
288        @param nOff1
289            Offset (from 0) of the first substring.
290
291        @param nLen1
292            Length (from offset) of the first substring.
293
294        @param aStr2
295            Second string.
296
297        @param nOff2
298            Offset (from 0) of the second substring.
299
300        @param nLen2
301            Length (from offset) of the second substring.
302
303        @returns
304            1 if the first substring is greater than the second substring <br/>
305            0 if the first substring is equal to the second substring <br/>
306            -1 if the first substring is less than the second substring
307    */
308    long    compareSubstring(   [in] string aStr1, [in] long nOff1, [in] long nLen1,
309                                [in] string aStr2, [in] long nOff2, [in] long nLen2 );
310
311    //------------------------------------------------------------------------
312    /** Compare 2 strings as per this transliteration. It translates both
313        strings before comparing them.
314
315        @returns
316            1 if the first string is greater than the second string <br/>
317            0 if the first string is equal to the second string <br/>
318            -1 if the first string is less than the second string
319    */
320    long    compareString( [in] string aStr1, [in] string aStr2 );
321
322};
323
324//=============================================================================
325}; }; }; };
326
327#endif
328