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

   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
  37 module 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
 103 published 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