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

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