1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved. 4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 * 6 * This code is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License version 2 only, as 8 * published by the Free Software Foundation. Oracle designates this 9 * particular file as subject to the "Classpath" exception as provided 10 * by Oracle in the LICENSE file that accompanied this code. 11 * 12 * This code is distributed in the hope that it will be useful, but WITHOUT 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 * version 2 for more details (a copy is included in the LICENSE file that 16 * accompanied this code). 17 * 18 * You should have received a copy of the GNU General Public License version 19 * 2 along with this work; if not, write to the Free Software Foundation, 20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 * 22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 * or visit www.oracle.com if you need additional information or have any 24 * questions. 25 */ 26 27 /* 28 * (C) Copyright IBM Corp. 1999-2003 - All Rights Reserved 29 * 30 * The original version of this source code and documentation is 31 * copyrighted and owned by IBM. These materials are provided 32 * under terms of a License Agreement between IBM and Sun. 33 * This technology is protected by multiple US and International 34 * patents. This notice and attribution to IBM may not be removed. 35 */ 36 37 package java.text; 38 39 /** 40 * This class implements the Unicode Bidirectional Algorithm. 41 * <p> 42 * A Bidi object provides information on the bidirectional reordering of the text 43 * used to create it. This is required, for example, to properly display Arabic 44 * or Hebrew text. These languages are inherently mixed directional, as they order 45 * numbers from left-to-right while ordering most other text from right-to-left. 46 * <p> 47 * Once created, a Bidi object can be queried to see if the text it represents is 48 * all left-to-right or all right-to-left. Such objects are very lightweight and 49 * this text is relatively easy to process. 50 * <p> 51 * If there are multiple runs of text, information about the runs can be accessed 52 * by indexing to get the start, limit, and level of a run. The level represents 53 * both the direction and the 'nesting level' of a directional run. Odd levels 54 * are right-to-left, while even levels are left-to-right. So for example level 55 * 0 represents left-to-right text, while level 1 represents right-to-left text, and 56 * level 2 represents left-to-right text embedded in a right-to-left run. 57 * 58 * @since 1.4 59 */ 60 public final class Bidi { 61 62 /** Constant indicating base direction is left-to-right. */ 63 public static final int DIRECTION_LEFT_TO_RIGHT = 0; 64 65 /** Constant indicating base direction is right-to-left. */ 66 public static final int DIRECTION_RIGHT_TO_LEFT = 1; 67 68 /** 69 * Constant indicating that the base direction depends on the first strong 70 * directional character in the text according to the Unicode 71 * Bidirectional Algorithm. If no strong directional character is present, 72 * the base direction is left-to-right. 73 */ 74 public static final int DIRECTION_DEFAULT_LEFT_TO_RIGHT = -2; 75 76 /** 77 * Constant indicating that the base direction depends on the first strong 78 * directional character in the text according to the Unicode 79 * Bidirectional Algorithm. If no strong directional character is present, 80 * the base direction is right-to-left. 81 */ 82 public static final int DIRECTION_DEFAULT_RIGHT_TO_LEFT = -1; 83 84 // Android-note: Upstream this class delegates to an internal implementation class BidiBase. 85 // For Android that is replaced with android.icu.text.Bidi. BidiBase and ICU Bidi work very 86 // similarly, but differ in some details like level of argument validation and how how exactly 87 // runs are counted. The majority of the changes in this file exist to allow for backwards 88 // compatibility with an earlier ICU4C based Bidi implementation. 89 90 // BEGIN Android-added: translateConstToIcu(int). translateConstToIcu(int javaInt)91 private static int translateConstToIcu(int javaInt) { 92 switch (javaInt) { 93 case DIRECTION_DEFAULT_LEFT_TO_RIGHT: 94 return android.icu.text.Bidi.DIRECTION_DEFAULT_LEFT_TO_RIGHT; 95 case DIRECTION_DEFAULT_RIGHT_TO_LEFT: 96 return android.icu.text.Bidi.DIRECTION_DEFAULT_RIGHT_TO_LEFT; 97 case DIRECTION_LEFT_TO_RIGHT: 98 return android.icu.text.Bidi.DIRECTION_LEFT_TO_RIGHT; 99 case DIRECTION_RIGHT_TO_LEFT: 100 return android.icu.text.Bidi.DIRECTION_RIGHT_TO_LEFT; 101 // If the parameter was unrecognized use LEFT_TO_RIGHT. 102 default: 103 return android.icu.text.Bidi.DIRECTION_LEFT_TO_RIGHT; 104 } 105 } 106 // END Android-added: translateConstToIcu(int). 107 108 // Android-changed: use ICU Bidi class instead of BidiBase. 109 private final android.icu.text.Bidi bidiBase; 110 111 /** 112 * Create Bidi from the given paragraph of text and base direction. 113 * @param paragraph a paragraph of text 114 * @param flags a collection of flags that control the algorithm. The 115 * algorithm understands the flags DIRECTION_LEFT_TO_RIGHT, DIRECTION_RIGHT_TO_LEFT, 116 * DIRECTION_DEFAULT_LEFT_TO_RIGHT, and DIRECTION_DEFAULT_RIGHT_TO_LEFT. 117 * Other values are reserved. 118 */ Bidi(String paragraph, int flags)119 public Bidi(String paragraph, int flags) { 120 if (paragraph == null) { 121 throw new IllegalArgumentException("paragraph is null"); 122 } 123 124 // Android-changed: use ICU Bidi class instead of BidiBase. 125 bidiBase = new android.icu.text.Bidi(paragraph.toCharArray(), 0, null, 0, 126 paragraph.length(), translateConstToIcu(flags)); 127 } 128 129 /** 130 * Create Bidi from the given paragraph of text. 131 * <p> 132 * The RUN_DIRECTION attribute in the text, if present, determines the base 133 * direction (left-to-right or right-to-left). If not present, the base 134 * direction is computes using the Unicode Bidirectional Algorithm, defaulting to left-to-right 135 * if there are no strong directional characters in the text. This attribute, if 136 * present, must be applied to all the text in the paragraph. 137 * <p> 138 * The BIDI_EMBEDDING attribute in the text, if present, represents embedding level 139 * information. Negative values from -1 to -62 indicate overrides at the absolute value 140 * of the level. Positive values from 1 to 62 indicate embeddings. Where values are 141 * zero or not defined, the base embedding level as determined by the base direction 142 * is assumed. 143 * <p> 144 * The NUMERIC_SHAPING attribute in the text, if present, converts European digits to 145 * other decimal digits before running the bidi algorithm. This attribute, if present, 146 * must be applied to all the text in the paragraph. 147 * 148 * @param paragraph a paragraph of text with optional character and paragraph attribute information 149 * 150 * @see java.awt.font.TextAttribute#BIDI_EMBEDDING 151 * @see java.awt.font.TextAttribute#NUMERIC_SHAPING 152 * @see java.awt.font.TextAttribute#RUN_DIRECTION 153 */ Bidi(AttributedCharacterIterator paragraph)154 public Bidi(AttributedCharacterIterator paragraph) { 155 if (paragraph == null) { 156 throw new IllegalArgumentException("paragraph is null"); 157 } 158 159 // Android-changed: change from BidiBase to ICU Bidi class. 160 this.bidiBase = new android.icu.text.Bidi(paragraph); 161 } 162 163 /** 164 * Create Bidi from the given text, embedding, and direction information. 165 * The embeddings array may be null. If present, the values represent embedding level 166 * information. Negative values from -1 to -61 indicate overrides at the absolute value 167 * of the level. Positive values from 1 to 61 indicate embeddings. Where values are 168 * zero, the base embedding level as determined by the base direction is assumed. 169 * @param text an array containing the paragraph of text to process. 170 * @param textStart the index into the text array of the start of the paragraph. 171 * @param embeddings an array containing embedding values for each character in the paragraph. 172 * This can be null, in which case it is assumed that there is no external embedding information. 173 * @param embStart the index into the embedding array of the start of the paragraph. 174 * @param paragraphLength the length of the paragraph in the text and embeddings arrays. 175 * @param flags a collection of flags that control the algorithm. The 176 * algorithm understands the flags DIRECTION_LEFT_TO_RIGHT, DIRECTION_RIGHT_TO_LEFT, 177 * DIRECTION_DEFAULT_LEFT_TO_RIGHT, and DIRECTION_DEFAULT_RIGHT_TO_LEFT. 178 * Other values are reserved. 179 */ Bidi(char[] text, int textStart, byte[] embeddings, int embStart, int paragraphLength, int flags)180 public Bidi(char[] text, int textStart, byte[] embeddings, int embStart, int paragraphLength, int flags) { 181 if (text == null) { 182 throw new IllegalArgumentException("text is null"); 183 } 184 if (paragraphLength < 0) { 185 throw new IllegalArgumentException("bad length: " + paragraphLength); 186 } 187 if (textStart < 0 || paragraphLength > text.length - textStart) { 188 throw new IllegalArgumentException("bad range: " + textStart + 189 " length: " + paragraphLength + 190 " for text of length: " + text.length); 191 } 192 if (embeddings != null && (embStart < 0 || paragraphLength > embeddings.length - embStart)) { 193 throw new IllegalArgumentException("bad range: " + embStart + 194 " length: " + paragraphLength + 195 " for embeddings of length: " + text.length); 196 } 197 198 // Android-changed: use ICU Bidi class instead of BidiBase. 199 bidiBase = new android.icu.text.Bidi(text, textStart, embeddings, embStart, 200 paragraphLength, translateConstToIcu(flags)); 201 } 202 203 // Android-added: private constructor based on ICU Bidi object. Bidi(android.icu.text.Bidi bidiBase)204 private Bidi(android.icu.text.Bidi bidiBase) { 205 this.bidiBase = bidiBase; 206 } 207 208 /** 209 * Create a Bidi object representing the bidi information on a line of text within 210 * the paragraph represented by the current Bidi. This call is not required if the 211 * entire paragraph fits on one line. 212 * 213 * @param lineStart the offset from the start of the paragraph to the start of the line. 214 * @param lineLimit the offset from the start of the paragraph to the limit of the line. 215 * @return a {@code Bidi} object 216 */ createLineBidi(int lineStart, int lineLimit)217 public Bidi createLineBidi(int lineStart, int lineLimit) { 218 // BEGIN Android-changed: add explict argument checks and use ICU Bidi class. 219 /* 220 AttributedString astr = new AttributedString(""); 221 Bidi newBidi = new Bidi(astr.getIterator()); 222 223 return bidiBase.setLine(this, bidiBase, newBidi, newBidi.bidiBase, lineStart, lineLimit); 224 */ 225 if (lineStart < 0 || lineLimit < 0 || lineStart > lineLimit || lineLimit > getLength()) { 226 throw new IllegalArgumentException("Invalid ranges (start=" + lineStart + ", " + 227 "limit=" + lineLimit + ", length=" + getLength() + ")"); 228 } 229 230 // In the special case where the start and end positions are the same, we return a new bidi 231 // instance which is empty. Note that the default constructor for an empty ICU4J bidi 232 // instance is not the same as passing in empty values. This way allows one to call 233 // .getLength() for example and return a correct value instead of an IllegalStateException 234 // being thrown, which happens in the case of using the empty constructor. 235 if (lineStart == lineLimit) { 236 return new Bidi(new android.icu.text.Bidi(new char[] {}, 0, new byte[] {}, 0, 0, 237 translateConstToIcu(DIRECTION_LEFT_TO_RIGHT))); 238 } 239 240 return new Bidi(bidiBase.createLineBidi(lineStart, lineLimit)); 241 // END Android-changed: add explict argument checks and use ICU Bidi class. 242 } 243 244 /** 245 * Return true if the line is not left-to-right or right-to-left. This means it either has mixed runs of left-to-right 246 * and right-to-left text, or the base direction differs from the direction of the only run of text. 247 * 248 * @return true if the line is not left-to-right or right-to-left. 249 */ isMixed()250 public boolean isMixed() { 251 return bidiBase.isMixed(); 252 } 253 254 /** 255 * Return true if the line is all left-to-right text and the base direction is left-to-right. 256 * 257 * @return true if the line is all left-to-right text and the base direction is left-to-right 258 */ isLeftToRight()259 public boolean isLeftToRight() { 260 return bidiBase.isLeftToRight(); 261 } 262 263 /** 264 * Return true if the line is all right-to-left text, and the base direction is right-to-left. 265 * @return true if the line is all right-to-left text, and the base direction is right-to-left 266 */ isRightToLeft()267 public boolean isRightToLeft() { 268 return bidiBase.isRightToLeft(); 269 } 270 271 /** 272 * Return the length of text in the line. 273 * @return the length of text in the line 274 */ getLength()275 public int getLength() { 276 return bidiBase.getLength(); 277 } 278 279 /** 280 * Return true if the base direction is left-to-right. 281 * @return true if the base direction is left-to-right 282 */ baseIsLeftToRight()283 public boolean baseIsLeftToRight() { 284 return bidiBase.baseIsLeftToRight(); 285 } 286 287 /** 288 * Return the base level (0 if left-to-right, 1 if right-to-left). 289 * @return the base level 290 */ getBaseLevel()291 public int getBaseLevel() { 292 return bidiBase.getParaLevel(); 293 } 294 295 /** 296 * Return the resolved level of the character at offset. If offset is 297 * {@literal <} 0 or ≥ the length of the line, return the base direction 298 * level. 299 * 300 * @param offset the index of the character for which to return the level 301 * @return the resolved level of the character at offset 302 */ getLevelAt(int offset)303 public int getLevelAt(int offset) { 304 // BEGIN Android-changed: return base level on out of range offset argument. 305 try { 306 return bidiBase.getLevelAt(offset); 307 } catch (IllegalArgumentException e) { 308 return getBaseLevel(); 309 } 310 // END Android-changed: return base level on out of range offset argument. 311 } 312 313 /** 314 * Return the number of level runs. 315 * @return the number of level runs 316 */ getRunCount()317 public int getRunCount() { 318 // Android-changed: ICU treats the empty string as having 0 runs, we see it as 1 empty run. 319 int runCount = bidiBase.countRuns(); 320 return (runCount == 0 ? 1 : runCount); 321 } 322 323 /** 324 * Return the level of the nth logical run in this line. 325 * @param run the index of the run, between 0 and {@code getRunCount()} 326 * @return the level of the run 327 */ getRunLevel(int run)328 public int getRunLevel(int run) { 329 // Android-added: Tolerate calls with run == getRunCount() for backwards compatibility. 330 if (run == getRunCount()) { 331 return getBaseLevel(); 332 } 333 // Android-changed: ICU treats the empty string as having 0 runs, we see it as 1 empty run. 334 return (bidiBase.countRuns() == 0 ? bidiBase.getBaseLevel() : bidiBase.getRunLevel(run)); 335 } 336 337 /** 338 * Return the index of the character at the start of the nth logical run in this line, as 339 * an offset from the start of the line. 340 * @param run the index of the run, between 0 and {@code getRunCount()} 341 * @return the start of the run 342 */ getRunStart(int run)343 public int getRunStart(int run) { 344 // Android-added: Tolerate calls with run == getRunCount() for backwards compatibility. 345 if (run == getRunCount()) { 346 return getBaseLevel(); 347 } 348 // Android-changed: ICU treats the empty string as having 0 runs, we see it as 1 empty run. 349 return (bidiBase.countRuns() == 0 ? 0 : bidiBase.getRunStart(run)); 350 } 351 352 /** 353 * Return the index of the character past the end of the nth logical run in this line, as 354 * an offset from the start of the line. For example, this will return the length 355 * of the line for the last run on the line. 356 * @param run the index of the run, between 0 and {@code getRunCount()} 357 * @return limit the limit of the run 358 */ getRunLimit(int run)359 public int getRunLimit(int run) { 360 // Android-added: Tolerate calls with run == getRunCount() for backwards compatibility. 361 if (run == getRunCount()) { 362 return getBaseLevel(); 363 } 364 // Android-changed: ICU treats the empty string as having 0 runs, we see it as 1 empty run. 365 return (bidiBase.countRuns() == 0 ? bidiBase.getLength() : bidiBase.getRunLimit(run)); 366 } 367 368 /** 369 * Return true if the specified text requires bidi analysis. If this returns false, 370 * the text will display left-to-right. Clients can then avoid constructing a Bidi object. 371 * Text in the Arabic Presentation Forms area of Unicode is presumed to already be shaped 372 * and ordered for display, and so will not cause this function to return true. 373 * 374 * @param text the text containing the characters to test 375 * @param start the start of the range of characters to test 376 * @param limit the limit of the range of characters to test 377 * @return true if the range of characters requires bidi analysis 378 */ requiresBidi(char[] text, int start, int limit)379 public static boolean requiresBidi(char[] text, int start, int limit) { 380 // Android-added: Check arguments to throw correct exception. 381 if (0 > start || start > limit || limit > text.length) { 382 throw new IllegalArgumentException("Value start " + start + 383 " is out of range 0 to " + limit); 384 } 385 return android.icu.text.Bidi.requiresBidi(text, start, limit); 386 } 387 388 /** 389 * Reorder the objects in the array into visual order based on their levels. 390 * This is a utility function to use when you have a collection of objects 391 * representing runs of text in logical order, each run containing text 392 * at a single level. The elements at {@code index} from 393 * {@code objectStart} up to {@code objectStart + count} 394 * in the objects array will be reordered into visual order assuming 395 * each run of text has the level indicated by the corresponding element 396 * in the levels array (at {@code index - objectStart + levelStart}). 397 * 398 * @param levels an array representing the bidi level of each object 399 * @param levelStart the start position in the levels array 400 * @param objects the array of objects to be reordered into visual order 401 * @param objectStart the start position in the objects array 402 * @param count the number of objects to reorder 403 */ reorderVisually(byte[] levels, int levelStart, Object[] objects, int objectStart, int count)404 public static void reorderVisually(byte[] levels, int levelStart, Object[] objects, int objectStart, int count) { 405 // BEGIN Android-added: Check arguments to throw correct exception. 406 if (0 > levelStart || levels.length <= levelStart) { 407 throw new IllegalArgumentException("Value levelStart " + 408 levelStart + " is out of range 0 to " + 409 (levels.length-1)); 410 } 411 if (0 > objectStart || objects.length <= objectStart) { 412 throw new IllegalArgumentException("Value objectStart " + 413 levelStart + " is out of range 0 to " + 414 (objects.length-1)); 415 } 416 if (0 > count || objects.length < (objectStart+count)) { 417 throw new IllegalArgumentException("Value count " + 418 levelStart + " is out of range 0 to " + 419 (objects.length - objectStart)); 420 } 421 // END Android-added: Check arguments to throw correct exception. 422 423 // Android-changed: use ICU Bidi class instead of BidiBase. 424 android.icu.text.Bidi.reorderVisually(levels, levelStart, objects, objectStart, count); 425 } 426 427 /** 428 * Display the bidi internal state, used in debugging. 429 */ toString()430 public String toString() { 431 // Android-changed: construct String representation from ICU Bidi object values. 432 return getClass().getName() 433 + "[direction: " + bidiBase.getDirection() + " baseLevel: " + bidiBase.getBaseLevel() 434 + " length: " + bidiBase.getLength() + " runs: " + bidiBase.getRunCount() + "]"; 435 } 436 437 } 438