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