From b5e73159e4ba675fe5208708f0c6431d82ae79c3 Mon Sep 17 00:00:00 2001 From: Matitiahu Allouche Date: Thu, 16 Aug 2007 13:40:19 +0000 Subject: [PATCH] ICU-5489 a few improvements to Javadoc X-SVN-Rev: 22399 --- icu4j/src/com/ibm/icu/text/Bidi.java | 96 +++++++++++------------- icu4j/src/com/ibm/icu/text/BidiLine.java | 3 +- 2 files changed, 47 insertions(+), 52 deletions(-) diff --git a/icu4j/src/com/ibm/icu/text/Bidi.java b/icu4j/src/com/ibm/icu/text/Bidi.java index 3ce9a360cdb..283f3ffde90 100644 --- a/icu4j/src/com/ibm/icu/text/Bidi.java +++ b/icu4j/src/com/ibm/icu/text/Bidi.java @@ -7,7 +7,7 @@ */ /* FOOD FOR THOUGHT: currently the reordering modes are a mixture of - * algorithm for direct BiDi, algorithm for inverse BiDi and the bizarre + * algorithm for direct BiDi, algorithm for inverse Bidi and the bizarre * concept of RUNS_ONLY which is a double operation. * It could be advantageous to divide this into 3 concepts: * a) Operation: direct / inverse / RUNS_ONLY @@ -42,7 +42,7 @@ import com.ibm.icu.lang.UCharacterDirection; /** * - *

BIDI algorithm for ICU

+ *

Bidi algorithm for ICU

* * This is an implementation of the Unicode Bidirectional algorithm. The * algorithm is defined in the * If this mode is set together with option - * OPTION_INSERT_MARKS, some BiDi controls in the source + * OPTION_INSERT_MARKS, some Bidi controls in the source * text may be removed and other controls may be added to produce the * minimum combination which has the required display. * @see #OPTION_INSERT_MARKS @@ -658,7 +658,7 @@ public class Bidi { public static final short REORDER_RUNS_ONLY = 3; /** Reordering mode: Visual to Logical algorithm which handles numbers - * like L (same algorithm as selected by * setInverse(true). + * like L (same algorithm as selected by setInverse(true). * @see #setInverse * @see #setReorderingMode * @draft ICU 3.8 @@ -675,7 +675,7 @@ public class Bidi { public static final short REORDER_INVERSE_LIKE_DIRECT = 5; /** Reordering mode: Inverse Bidi (Visual to Logical) algorithm for the - * REORDER_NUMBERS_SPECIAL BiDi algorithm. + * REORDER_NUMBERS_SPECIAL Bidi algorithm. * @see #setReorderingMode * @draft ICU 3.8 * @provisional This API might change or be removed in a future release. @@ -726,7 +726,7 @@ public class Bidi { *

For other reordering modes, a minimum number of LRM or RLM characters * will be added to the source text after reordering it so as to ensure * round trip, i.e. when applying the inverse reordering mode on the - * resulting logical text with removal of BiDi marks + * resulting logical text with removal of Bidi marks * (option OPTION_REMOVE_CONTROLS set before calling * setPara() or option * REMOVE_BIDI_CONTROLS in @@ -762,9 +762,6 @@ public class Bidi { *

This option must be set or reset before calling * setPara.

* - *

This option implies the option REMOVE_BIDI_CONTROLS - * in writeReordered.

- * *

This option nullifies option * OPTION_INSERT_MARKS. It inhibits option * INSERT_LRM_FOR_NUMERIC in calls to method @@ -898,7 +895,7 @@ public class Bidi { */ int length; - /* if option OPTION_REMOVE_CONTROLS is set, and/or BiDi + /* if option OPTION_REMOVE_CONTROLS is set, and/or Bidi * marks are allowed to be inserted in one of the reordering modes, the * length of the result string may be different from the processed length. */ @@ -1141,8 +1138,6 @@ public class Bidi { * This method provides a Bidi object like the default constructor * but it also preallocates memory for internal structures * according to the sizings supplied by the caller.

- * Subsequent methods will not allocate any more memory, and are thus - * guaranteed not to fail because of lack of memory.

* The preallocation can be limited to some of the internal memory * by setting some values to 0 here. That means that if, e.g., * maxRunCount cannot be reasonably predetermined and should not @@ -1461,7 +1456,7 @@ public class Bidi { * This mode may be needed when logical text which is basically Arabic or * Hebrew, with possible included numbers or phrases in English, has to be * displayed as if it had an even embedding level (this can happen if the - * displaying application treats all text as if it was basically LTR. + * displaying application treats all text as if it was basically LTR). *
* This mode may also be needed in the reverse case, when logical text which * is basically English, with possible included phrases in Arabic or Hebrew, @@ -1498,14 +1493,14 @@ public class Bidi { * with mode REORDER_INVERSE_NUMBERS_AS_L.
* When used in conjunction with option * OPTION_INSERT_MARKS, this mode generally - * adds BiDi marks to the output significantly more sparingly than mode + * adds Bidi marks to the output significantly more sparingly than mode * REORDER_INVERSE_NUMBERS_AS_L.
with option * INSERT_LRM_FOR_NUMERIC in calls to * writeReordered. * *

  • When the reordering mode is set to * REORDER_INVERSE_FOR_NUMBERS_SPECIAL, the Logical to Visual - * BiDi algorithm used in Windows XP is used as an approximation of an "inverse + * Bidi algorithm used in Windows XP is used as an approximation of an "inverse * Bidi" algorithm. *
    * For example, an LTR paragraph with the content "abc FED123" (where @@ -1617,7 +1612,7 @@ public class Bidi { byte dirProp; byte paraDirDefault = 0; /* initialize to avoid compiler warnings */ boolean isDefaultLevel = IsDefaultLevel(paraLevel); - /* for inverse BiDi, the default para level is set to RTL if there is a + /* for inverse Bidi, the default para level is set to RTL if there is a strong R or AL character at either end of the text */ boolean isDefaultLevelInverse=isDefaultLevel && (reorderingMode==REORDER_INVERSE_LIKE_DIRECT || @@ -1634,7 +1629,7 @@ public class Bidi { int paraStart = 0; /* index of first char in paragraph */ byte paraDir; /* == CONTEXT_RTL within paragraphs starting with strong R char */ - byte lastStrongDir=0; /* for default level & inverse BiDi */ + byte lastStrongDir=0; /* for default level & inverse Bidi */ int lastStrongLTR=0; /* for STREAMING option */ if ((reorderingOptions & OPTION_STREAMING) > 0) { @@ -2605,8 +2600,8 @@ public class Bidi { int nextStrongPos = -1; - /* check for RTL inverse BiDi mode */ - /* FOOD FOR THOUGHT: in case of RTL inverse BiDi, it would make sense to + /* check for RTL inverse Bidi mode */ + /* FOOD FOR THOUGHT: in case of RTL inverse Bidi, it would make sense to * loop on the text characters from end to start. * This would need a different properties state table (at least different * actions) and different levels state tables (maybe very similar to the @@ -2788,7 +2783,7 @@ public class Bidi { /* FOOD FOR THOUGHT: instead of writing the visual text, we could use * the visual map and the dirProps array to drive the second call * to setPara (but must make provision for possible removal of - * BiDi controls. Alternatively, only use the dirProps array via + * Bidi controls. Alternatively, only use the dirProps array via * customized classifier callback. */ visualText = writeReordered(DO_MIRRORING); @@ -2964,8 +2959,8 @@ public class Bidi { * with one exception: a level of zero may be specified for a * paragraph separator even if paraLevel>0 when multiple * paragraphs are submitted in the same call to setPara().

    - * Caution: A copy of this pointer, not of the levels, - * will be stored in the Bidi object; + * Caution: A reference to this array, not a copy + * of the levels, will be stored in the Bidi object; * the embeddingLevels * should not be modified to avoid unexpected results on subsequent * Bidi operations. However, the setPara() and @@ -3049,8 +3044,8 @@ public class Bidi { * with one exception: a level of zero may be specified for a * paragraph separator even if paraLevel>0 when multiple * paragraphs are submitted in the same call to setPara().

    - * Caution: A copy of this pointer, not of the levels, - * will be stored in the Bidi object; + * Caution: A reference to this array, not a copy + * of the levels, will be stored in the Bidi object; * the embeddingLevels * should not be modified to avoid unexpected results on subsequent * Bidi operations. However, the setPara() and @@ -3173,7 +3168,7 @@ public class Bidi { } /* - * The steps after (X9) in the UBiDi algorithm are performed only if + * The steps after (X9) in the Bidi algorithm are performed only if * the paragraph text has mixed directionality! */ switch (direction) { @@ -3609,7 +3604,7 @@ public class Bidi { *
  • number of elements returned by getVisualMap
    • * * Note that this length stays identical to the source text length if - * BiDi marks are inserted or removed using option bits of + * Bidi marks are inserted or removed using option bits of * writeReordered, or if option * REORDER_INVERSE_NUMBERS_AS_L has been set. * @@ -3678,7 +3673,8 @@ public class Bidi { * * This method returns information about a paragraph.

    * - * @param paraIndex is the number of the paragraph, starting from 0. + * @param paraIndex is the number of the paragraph, in the + * range [0..countParagraphs()-1]. * * @return a BidiRun object with the details of the paragraph:
    * start will receive the index of the first character @@ -3810,8 +3806,8 @@ public class Bidi { /** * Retrieves the Bidi class for a given code point. *

    If a BidiClassifier is defined and returns a value - * other than the default, that value is used; otherwise the default class - * determination mechanism is invoked.

    + * other than CLASS_DEFAULT, that value is used; otherwise + * the default class determination mechanism is invoked.

    * * @param c The code point to get a Bidi class for. * @@ -3850,11 +3846,10 @@ public class Bidi { * trailing WS and for reordering are performed on * a Bidi object that represents a line.

    * - * Important: pLineBiDi references data - * within pParaBiDi. - * You must destroy or reuse pLineBiDi before pParaBiDi. - * In other words, you must destroy or reuse the Bidi - * object for a line before the object for its parent paragraph. + * Important: the line Bidi object may + * reference data within the global text Bidi object. + * You should not alter the content of the global text object until + * you are finished using the line object. * * @param start is the line's first index into the text. * @@ -3878,7 +3873,7 @@ public class Bidi { { verifyValidPara(); verifyRange(start, 0, limit); - verifyRange(limit, 0, length); + verifyRange(limit, 0, length+1); if (getParagraphIndex(start) != getParagraphIndex(limit - 1)) { /* the line crosses a paragraph boundary */ throw new IllegalArgumentException(); @@ -3891,9 +3886,7 @@ public class Bidi { * * @param charIndex the index of a character. * - * @return The level for the character at charIndex. If - * charIndex is <0 or >= the length of the line, - * return the base direction level. + * @return The level for the character at charIndex. * * @throws IllegalStateException if this call is not preceded by a successful * call to setPara or setLine @@ -3991,7 +3984,8 @@ public class Bidi { /** * - * Get one run's logical start, length, and level, + * Get a BidiRun object according to its index. BidiRun methods + * may be used to retrieve the run's logical start, length and level, * which can be even for an LTR run or odd for an RTL run. * In an RTL run, the character at the logical start is * visually on the right of the displayed run. @@ -4240,7 +4234,7 @@ public class Bidi { { /* countRuns() checks successful call to setPara/setLine */ countRuns(); - if (length <= 0) { + if (resultLength <= 0) { return new int[0]; } return BidiLine.getVisualMap(this); @@ -4299,30 +4293,30 @@ public class Bidi { * The index mapping of the argument map is inverted and returned as * an array of indexes that we will call the inverse map. * - * @param srcMap is an array whose indexes define the original mapping + * @param srcMap is an array whose elements define the original mapping * from a source array to a destination array. * Some elements of the source array may have no mapping in the - * destination array. In that case, the index for those elements will be + * destination array. In that case, their value will be * the special value MAP_NOWHERE. - * All indexes must be >=0 or equal to MAP_NOWHERE. - * Some indexes in the source map may have a value greater than the + * All elements must be >=0 or equal to MAP_NOWHERE. + * Some elements in the source map may have a value greater than the * srcMap.length if the destination array has more elements than the * source array. - * There must be no duplicate indexes (two or more indexes with the + * There must be no duplicate indexes (two or more elements with the * same value except MAP_NOWHERE). * * @return an array representing the inverse map. - * This array has a number of indexes equal to 1 + the highest + * This array has a number of elements equal to 1 + the highest * value in srcMap. * For elements of the result array which have no matching elements - * in the source array, the corresponding indexes in the inverse + * in the source array, the corresponding elements in the inverse * map will receive a value equal to MAP_NOWHERE. - * If index i in srcMap has a value k different + * If element with index i in srcMap has a value k different * from MAP_NOWHERE, this means that element i of * the source array maps to element k in the destination array. - * The inverse map will have value i in its k-th index. + * The inverse map will have value i in its k-th element. * For all elements of the destination array which do not map to - * an element in the source array, the corresponding index in the + * an element in the source array, the corresponding element in the * inverse map will have a value equal to MAP_NOWHERE. * * @see #MAP_NOWHERE @@ -4853,7 +4847,7 @@ public class Bidi { * length of the returned string may be less than * getLength().
    * If none of these options is set, then the length of the returned - * string will be exactly getLength(). + * string will be exactly getProcessedLength(). * * @throws IllegalStateException if this call is not preceded by a successful * call to setPara or setLine diff --git a/icu4j/src/com/ibm/icu/text/BidiLine.java b/icu4j/src/com/ibm/icu/text/BidiLine.java index a521df3a438..fcfd9696bd7 100644 --- a/icu4j/src/com/ibm/icu/text/BidiLine.java +++ b/icu4j/src/com/ibm/icu/text/BidiLine.java @@ -279,7 +279,8 @@ final class BidiLine { a special interpretation when REORDER_RUNS_ONLY */ BidiRun newRun = new BidiRun(), iRun; - int runCount = bidi.countRuns(); + getRuns(bidi); + int runCount = bidi.runCount; int visualStart = 0, logicalLimit = 0; iRun = bidi.runs[0];