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