Back to index

lightning-sunbird  0.9+nobinonly
Public Member Functions | Protected Attributes | Private Member Functions
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:
Collaboration graph
[legend]

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.
PRBool IsBidiControl (PRUint32 aChar)
 Give a UTF-32 codepoint return PR_TRUE if the codepoint is a Bidi control character (LRE, RLE, PDF, LRO, RLO, LRM, RLM) return PR_FALSE, otherwise.

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())

Private Member Functions

void Init ()
PRBool GetMemory (void **aMemory, PRSize *aSize, PRBool aMayAllocate, PRSize aSizeNeeded)
void Free ()
void GetDirProps (const PRUnichar *aText)
nsBidiDirection ResolveExplicitLevels ()
nsresult CheckExplicitLevels (nsBidiDirection *aDirection)
nsBidiDirection DirectionFromFlags (Flags aFlags)
void ResolveImplicitLevels (PRInt32 aStart, PRInt32 aLimit, DirProp aSOR, DirProp aEOR)
void AdjustWSLevels ()
void SetTrailingWSStart ()
PRBool GetRuns ()
void GetSingleRun (nsBidiLevel aLevel)
void ReorderLine (nsBidiLevel aMinLevel, nsBidiLevel aMaxLevel)
PRBool PrepareReorder (const nsBidiLevel *aLevels, PRInt32 aLength, PRInt32 *aIndexMap, nsBidiLevel *aMinLevel, nsBidiLevel *aMaxLevel)
eBidiCategory GetBidiCategory (PRUint32 aChar)
 Give a UTF-32 codepoint, return an eBidiCategory.
PRBool IsBidiCategory (PRUint32 aChar, eBidiCategory aBidiCategory)
 Give a UTF-32 codepoint and an eBidiCategory, return PR_TRUE if the codepoint is in that category, return PR_FALSE, otherwise.
nsCharType GetCharType (PRUint32 aChar)
 Give a UTF-32 codepoint, return a nsCharType (compatible with ICU)
PRUint32 SymmSwap (PRUint32 aChar)
 Give a Unicode character, return the symmetric equivalent.
PRInt32 doWriteReverse (const PRUnichar *src, PRInt32 srcLength, PRUnichar *dest, PRUint16 options)

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.

Definition at line 502 of file nsBidi.h.


Constructor & Destructor Documentation

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:
aMaxLengthis 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.
aMaxRunCountis 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

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:
aRunCountwill receive the number of runs.
PRInt32 nsBidi::doWriteReverse ( const PRUnichar src,
PRInt32  srcLength,
PRUnichar dest,
PRUint16  options 
) [private]
void nsBidi::Free ( ) [private]

Give a UTF-32 codepoint, return an eBidiCategory.

nsCharType nsBidi::GetCharType ( PRUint32  aChar) [private]

Give a UTF-32 codepoint, return a nsCharType (compatible with ICU)

nsresult nsBidi::GetCharTypeAt ( PRInt32  aCharIndex,
nsCharType aType 
)

Get the bidirectional type for one character.

Parameters:
aCharIndexthe index of a character.
aTypereceives the bidirectional type of the character at aCharIndex.
void nsBidi::GetDirProps ( const PRUnichar aText) [private]
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:
aLogicalStartis the first character of the run.
aLogicalLimitwill 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.
aLevelwill receive the level of the run. This pointer can be NULL if this value is not necessary.
PRBool nsBidi::GetMemory ( void **  aMemory,
PRSize aSize,
PRBool  aMayAllocate,
PRSize  aSizeNeeded 
) [private]
PRBool nsBidi::GetRuns ( ) [private]
void nsBidi::GetSingleRun ( nsBidiLevel  aLevel) [private]
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:
aRunIndexis the number of the run in visual order, in the range [0..CountRuns-1].
aLogicalStartis the first logical character index in the text. The pointer may be NULL if this index is not needed.
aLengthis the number of characters (at least one) in the run. The pointer may be NULL if this is not needed.
aDirectionwill 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.

void nsBidi::Init ( ) [private]
PRBool nsBidi::IsBidiCategory ( PRUint32  aChar,
eBidiCategory  aBidiCategory 
) [private]

Give a UTF-32 codepoint and an eBidiCategory, return PR_TRUE if the codepoint is in that category, return PR_FALSE, otherwise.

Give a UTF-32 codepoint return PR_TRUE if the codepoint is a Bidi control character (LRE, RLE, PDF, LRO, RLO, LRM, RLM) return PR_FALSE, otherwise.

PRBool nsBidi::PrepareReorder ( const nsBidiLevel aLevels,
PRInt32  aLength,
PRInt32 aIndexMap,
nsBidiLevel aMinLevel,
nsBidiLevel aMaxLevel 
) [private]
void nsBidi::ReorderLine ( nsBidiLevel  aMinLevel,
nsBidiLevel  aMaxLevel 
) [private]
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:
aLevelsis an array with aLength levels that have been determined by the application.
aLengthis the number of levels in the array, or, semantically, the number of objects to be reordered. It must be aLength>0.
aIndexMapis 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.

void nsBidi::ResolveImplicitLevels ( PRInt32  aStart,
PRInt32  aLimit,
DirProp  aSOR,
DirProp  aEOR 
) [private]
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:
aTextis 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.
aLengthis the length of the text; if aLength==-1 then the text must be zero-terminated.
aParaLevelspecifies 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.

PRUint32 nsBidi::SymmSwap ( PRUint32  aChar) [private]

Give a Unicode character, return the symmetric equivalent.

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:
aSrcA pointer to the RTL run text.
aSrcLengthThe 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.
aDestA pointer to where the reordered text is to be copied. aSrc[aSrcLength] and aDest[aSrcLength] must not overlap.
aOptionsA bit set of options for the reordering that control how the reordered text is written.
aDestSizewill receive the number of characters that were written to aDest.

Member Data Documentation

the overall paragraph or line directionality - see nsBidiDirection

Definition at line 991 of file nsBidi.h.

Definition at line 981 of file nsBidi.h.

allocated memory

Definition at line 974 of file nsBidi.h.

memory sizes in bytes

Definition at line 971 of file nsBidi.h.

Flags nsBidi::mFlags [protected]

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

Definition at line 988 of file nsBidi.h.

PRInt32 nsBidi::mLength [protected]

length of the current text

Definition at line 968 of file nsBidi.h.

Definition at line 982 of file nsBidi.h.

Definition at line 975 of file nsBidi.h.

Definition at line 971 of file nsBidi.h.

Definition at line 979 of file nsBidi.h.

indicators for whether memory may be allocated after construction

Definition at line 979 of file nsBidi.h.

the paragraph level

Definition at line 985 of file nsBidi.h.

fields for line reordering

Definition at line 998 of file nsBidi.h.

Run* nsBidi::mRuns [protected]

Definition at line 999 of file nsBidi.h.

Run* nsBidi::mRunsMemory [protected]

Definition at line 976 of file nsBidi.h.

Definition at line 971 of file nsBidi.h.

Run nsBidi::mSimpleRuns[1] [protected]

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

Definition at line 1002 of file nsBidi.h.

characters after trailingWSStart are WS and are

Definition at line 995 of file nsBidi.h.


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