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