Public Member Functions | Protected Attributes

nsBidi Class Reference

This class holds information about a paragraph of text with Bidi-algorithm-related details, or about one line of such a paragraph. More...

#include <nsBidi.h>

Collaboration diagram for nsBidi:

List of all members.

Public Member Functions

 nsBidi ()
 Default constructor.
 nsBidi (PRUint32 aMaxLength, PRUint32 aMaxRunCount)
 Preallocating constructor Allocate an nsBidi object with preallocated memory for internal structures.
virtual ~nsBidi ()
 Destructor.
nsresult SetPara (const PRUnichar *aText, PRInt32 aLength, nsBidiLevel aParaLevel, nsBidiLevel *aEmbeddingLevels)
 Perform the Unicode Bidi algorithm.
nsresult GetCharTypeAt (PRInt32 aCharIndex, nsCharType *aType)
 Get the bidirectional type for one character.
nsresult GetLogicalRun (PRInt32 aLogicalStart, PRInt32 *aLogicalLimit, nsBidiLevel *aLevel)
 Get a logical run.
nsresult CountRuns (PRInt32 *aRunCount)
 Get the number of runs.
nsresult GetVisualRun (PRInt32 aRunIndex, PRInt32 *aLogicalStart, PRInt32 *aLength, nsBidiDirection *aDirection)
 Get one run's logical start, length, and directionality, which can be 0 for LTR or 1 for RTL.
nsresult ReorderVisual (const nsBidiLevel *aLevels, PRInt32 aLength, PRInt32 *aIndexMap)
 This is a convenience function that does not use a nsBidi object.
nsresult WriteReverse (const PRUnichar *aSrc, PRInt32 aSrcLength, PRUnichar *aDest, PRUint16 aOptions, PRInt32 *aDestSize)
 Reverse a Right-To-Left run of Unicode text.

Protected Attributes

PRInt32 mLength
 length of the current text
PRSize mDirPropsSize
 memory sizes in bytes
PRSize mLevelsSize
PRSize mRunsSize
DirPropmDirPropsMemory
 allocated memory
nsBidiLevelmLevelsMemory
RunmRunsMemory
PRBool mMayAllocateText
 indicators for whether memory may be allocated after construction
PRBool mMayAllocateRuns
const DirPropmDirProps
nsBidiLevelmLevels
nsBidiLevel mParaLevel
 the paragraph level
Flags mFlags
 flags is a bit set for which directional properties are in the text
nsBidiDirection mDirection
 the overall paragraph or line directionality - see nsBidiDirection
PRInt32 mTrailingWSStart
 characters after trailingWSStart are WS and are
PRInt32 mRunCount
 fields for line reordering
RunmRuns
Run mSimpleRuns [1]
 for non-mixed text, we only need a tiny array of runs (no malloc())

Detailed Description

This class holds information about a paragraph of text with Bidi-algorithm-related details, or about one line of such a paragraph.

Reordering can be done on a line, or on a paragraph which is then interpreted as one single line.

On construction, the class is initially empty. It is assigned the Bidi properties of a paragraph by SetPara or the Bidi properties of a line of a paragraph by SetLine.

A Bidi class can be reused for as long as it is not deallocated by calling its destructor.

SetPara will allocate additional memory for internal structures as necessary.


Constructor & Destructor Documentation

nsBidi::nsBidi (  ) 

Default constructor.

The nsBidi object is initially empty. It is assigned the Bidi properties of a paragraph by SetPara() or the Bidi properties of a line of a paragraph by GetLine().

This object can be reused for as long as it is not destroyed.

SetPara() will allocate additional memory for internal structures as necessary.

nsBidi::nsBidi ( PRUint32  aMaxLength,
PRUint32  aMaxRunCount 
)

Preallocating constructor Allocate an nsBidi object with preallocated memory for internal structures.

This constructor provides an nsBidi object like the default constructor, but it also preallocates memory for internal structures according to the sizings supplied by the caller.

Subsequent functions 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., aMaxRunCount cannot be reasonably predetermined and should not be set to aMaxLength (the only failproof value) to avoid wasting memory, then aMaxRunCount could be set to 0 here and the internal structures that are associated with it will be allocated on demand, just like with the default constructor.

If sufficient memory could not be allocated, no exception is thrown. Test whether mDirPropsSize == aMaxLength and/or mRunsSize == aMaxRunCount.

Parameters:
aMaxLength is the maximum paragraph or line length that internal memory will be preallocated for. An attempt to associate this object with a longer text will fail, unless this value is 0, which leaves the allocation up to the implementation.
aMaxRunCount is the maximum anticipated number of same-level runs that internal memory will be preallocated for. An attempt to access visual runs on an object that was not preallocated for as many runs as the text was actually resolved to will fail, unless this value is 0, which leaves the allocation up to the implementation.

The number of runs depends on the actual text and maybe anywhere between 1 and aMaxLength. It is typically small.

virtual nsBidi::~nsBidi (  )  [virtual]

Destructor.


Member Function Documentation

nsresult nsBidi::CountRuns ( PRInt32 *  aRunCount  ) 

Get the number of runs.

This function may invoke the actual reordering on the nsBidi object, after SetPara may have resolved only the levels of the text. Therefore, CountRuns may have to allocate memory, and may fail doing so.

Parameters:
aRunCount will receive the number of runs.
nsresult nsBidi::GetCharTypeAt ( PRInt32  aCharIndex,
nsCharType aType 
)

Get the bidirectional type for one character.

Parameters:
aCharIndex the index of a character.
aType receives the bidirectional type of the character at aCharIndex.
nsresult nsBidi::GetLogicalRun ( PRInt32  aLogicalStart,
PRInt32 *  aLogicalLimit,
nsBidiLevel aLevel 
)

Get a logical run.

This function returns information about a run and is used to retrieve runs in logical order.

This is especially useful for line-breaking on a paragraph.

Parameters:
aLogicalStart is the first character of the run.
aLogicalLimit will receive the limit of the run. The l-value that you point to here may be the same expression (variable) as the one for aLogicalStart. This pointer can be NULL if this value is not necessary.
aLevel will receive the level of the run. This pointer can be NULL if this value is not necessary.
nsresult nsBidi::GetVisualRun ( PRInt32  aRunIndex,
PRInt32 *  aLogicalStart,
PRInt32 *  aLength,
nsBidiDirection aDirection 
)

Get one run's logical start, length, and directionality, which can be 0 for LTR or 1 for RTL.

In an RTL run, the character at the logical start is visually on the right of the displayed run. The length is the number of characters in the run.

CountRuns should be called before the runs are retrieved.

Parameters:
aRunIndex is the number of the run in visual order, in the range [0..CountRuns-1].
aLogicalStart is the first logical character index in the text. The pointer may be NULL if this index is not needed.
aLength is the number of characters (at least one) in the run. The pointer may be NULL if this is not needed.
aDirection will receive the directionality of the run, NSBIDI_LTR==0 or NSBIDI_RTL==1, never NSBIDI_MIXED.
See also:
CountRuns

Example:

  PRInt32 i, count, logicalStart, visualIndex=0, length;
  nsBidiDirection dir;
  pBidi->CountRuns(&count);
  for(i=0; i<count; ++i) {
    pBidi->GetVisualRun(i, &logicalStart, &length, &dir);
    if(NSBIDI_LTR==dir) {
      do { // LTR
        show_char(text[logicalStart++], visualIndex++);
      } while(--length>0);
    } else {
      logicalStart+=length;  // logicalLimit
      do { // RTL
        show_char(text[--logicalStart], visualIndex++);
      } while(--length>0);
    }
  }

Note that in right-to-left runs, code like this places modifier letters before base characters and second surrogates before first ones.

nsresult nsBidi::ReorderVisual ( const nsBidiLevel aLevels,
PRInt32  aLength,
PRInt32 *  aIndexMap 
)

This is a convenience function that does not use a nsBidi object.

It is intended to be used for when an application has determined the levels of objects (character sequences) and just needs to have them reordered (L2). This is equivalent to using GetVisualMap on a nsBidi object.

Parameters:
aLevels is an array with aLength levels that have been determined by the application.
aLength is the number of levels in the array, or, semantically, the number of objects to be reordered. It must be aLength>0.
aIndexMap is a pointer to an array of aLength indexes which will reflect the reordering of the characters. The array does not need to be initialized.

The index map will result in aIndexMap[aVisualIndex]==aLogicalIndex.

nsresult nsBidi::SetPara ( const PRUnichar aText,
PRInt32  aLength,
nsBidiLevel  aParaLevel,
nsBidiLevel aEmbeddingLevels 
)

Perform the Unicode Bidi algorithm.

It is defined in the Unicode Technical Report 9, version 5, also described in The Unicode Standard, Version 3.0 .

This function takes a single plain text paragraph with or without externally specified embedding levels from <quote>styled</quote> text and computes the left-right-directionality of each character.

If the entire paragraph consists of text of only one direction, then the function may not perform all the steps described by the algorithm, i.e., some levels may not be the same as if all steps were performed. This is not relevant for unidirectional text.
For example, in pure LTR text with numbers the numbers would get a resolved level of 2 higher than the surrounding text according to the algorithm. This implementation may set all resolved levels to the same value in such a case.

The text must be externally split into separate paragraphs (rule P1). Paragraph separators (B) should appear at most at the very end.

Parameters:
aText is a pointer to the single-paragraph text that the Bidi algorithm will be performed on (step (P1) of the algorithm is performed externally). The text must be (at least) aLength long.
aLength is the length of the text; if aLength==-1 then the text must be zero-terminated.
aParaLevel specifies the default level for the paragraph; it is typically 0 (LTR) or 1 (RTL). If the function shall determine the paragraph level from the text, then aParaLevel can be set to either NSBIDI_DEFAULT_LTR or NSBIDI_DEFAULT_RTL; if there is no strongly typed character, then the desired default is used (0 for LTR or 1 for RTL). Any other value between 0 and NSBIDI_MAX_EXPLICIT_LEVEL is also valid, with odd levels indicating RTL.
aEmbeddingLevels (in) may be used to preset the embedding and override levels, ignoring characters like LRE and PDF in the text. A level overrides the directional property of its corresponding (same index) character if the level has the NSBIDI_LEVEL_OVERRIDE bit set.

Except for that bit, it must be aParaLevel<=aEmbeddingLevels[]<=NSBIDI_MAX_EXPLICIT_LEVEL.

Caution: A copy of this pointer, not of the levels, will be stored in the nsBidi object; the aEmbeddingLevels array must not be deallocated before the nsBidi object is destroyed or reused, and the aEmbeddingLevels should not be modified to avoid unexpected results on subsequent Bidi operations. However, the SetPara and SetLine functions may modify some or all of the levels.

After the nsBidi object is reused or destroyed, the caller must take care of the deallocation of the aEmbeddingLevels array.

The aEmbeddingLevels array must be at least aLength long.

nsresult nsBidi::WriteReverse ( const PRUnichar aSrc,
PRInt32  aSrcLength,
PRUnichar aDest,
PRUint16  aOptions,
PRInt32 *  aDestSize 
)

Reverse a Right-To-Left run of Unicode text.

This function preserves the integrity of characters with multiple code units and (optionally) modifier letters. Characters can be replaced by mirror-image characters in the destination buffer. Note that "real" mirroring has to be done in a rendering engine by glyph selection and that for many "mirrored" characters there are no Unicode characters as mirror-image equivalents. There are also options to insert or remove Bidi control characters; see the description of the aDestSize and aOptions parameters and of the option bit flags.

Since no Bidi controls are inserted here, this function will never write more than aSrcLength characters to aDest.

Parameters:
aSrc A pointer to the RTL run text.
aSrcLength The length of the RTL run. If the NSBIDI_REMOVE_BIDI_CONTROLS option is set, then the destination length may be less than aSrcLength. If this option is not set, then the destination length will be exactly aSrcLength.
aDest A pointer to where the reordered text is to be copied. aSrc[aSrcLength] and aDest[aSrcLength] must not overlap.
aOptions A bit set of options for the reordering that control how the reordered text is written.
aDestSize will receive the number of characters that were written to aDest.

Member Data Documentation

the overall paragraph or line directionality - see nsBidiDirection

const DirProp* nsBidi::mDirProps [protected]

allocated memory

memory sizes in bytes

Flags nsBidi::mFlags [protected]

flags is a bit set for which directional properties are in the text

PRInt32 nsBidi::mLength [protected]

length of the current text

indicators for whether memory may be allocated after construction

the paragraph level

PRInt32 nsBidi::mRunCount [protected]

fields for line reordering

Run* nsBidi::mRuns [protected]
Run* nsBidi::mRunsMemory [protected]
Run nsBidi::mSimpleRuns[1] [protected]

for non-mixed text, we only need a tiny array of runs (no malloc())

PRInt32 nsBidi::mTrailingWSStart [protected]

characters after trailingWSStart are WS and are


The documentation for this class was generated from the following file: