oracle.javatools.buffer
Interface LineMap

public interface LineMap

A LineMap is an interface for accessing the line structure information of a TextBuffer. This allows clients to determine the line that an offset is on, the starting and ending offset of a specific line, and the total number of lines in the TextBuffer.

Client Usage Notes:

• All line numbers accessed through this interface are 0-based (as are all offsets.) This includes line numbers returned by the LineMap as well as specified by the client. For example, if there are 5 lines in the buffer, the lines will be numbered 0 through 4, while getLineCount() will return 5 lines.

  Clients must take this into account as line numbers reported through UI components to end users typically start from 1.

• Following the conventions in the String class, start offsets returned from getLineStartOffset(int) are inclusive, while end offsets returned from getLineEndOffset(int) are exclusive.

  For example, if the first line of the buffer contains "abcd" followed by a newline (\n), then the start offset of the line will be 0, while the end offset will be 5. The length of the line (including line terminators) will always be the end offset minus the start offset.

• When mapping from an offset to a line using getLineFromOffset(int), the offset given has a forward bias. In the above example, offset 5 occurs between the newline (\n) of line 0 and the first character of line 1. Since the bias is to the right, getLineFromOffset( 5 ) will return line 1, not 0.

• Since the LineMap tracks the underlying text buffer, it will be modified when the text buffer is modified. To ensure data consistency (and program stability), clients must be sure to acquire at least a read lock on the buffer while accessing the LineMap. This is just a documented policy, and is not enforced programmatically in order to not affect performance.

Note that we do not follow the convention of the Swing text package, where documents have the implicit trailing '\n' character. The very last line of the TextBuffer does NOT have a trailing '\n' character.

See Also:

TextBuffer

Method Summary

int	getLineCount() Fetches the number of lines in this TextBuffer.
int	getLineEndOffset(int line) Given a specified line, returns the offset from the beginning of a TextBuffer that the line ends at.
int	getLineFromOffset(int offset) Given an offset from the beginning of the underlying TextBuffer, fetches the line number containing that offset using a Forward bias.
int	getLineStartOffset(int line) Given a specified line, returns the offset from the beginning of the TextBuffer for the start of the line.
TextBuffer	getTextBuffer() Fetches the underlying TextBuffer of this line map.

Method Detail

getTextBuffer

public TextBuffer getTextBuffer()

Fetches the underlying TextBuffer of this line map.

Returns:

the text buffer

getLineCount

public int getLineCount()

Fetches the number of lines in this TextBuffer. For example, a 5-line TextBuffer has lines 0 through 4.

Returns:

number of lines in TextBuffer

getLineFromOffset

public int getLineFromOffset(int offset)

Given an offset from the beginning of the underlying TextBuffer, fetches the line number containing that offset using a Forward bias. This means if line A starts with offset B, and previous line A-1 ends with offset B, getLineFromOffset(B) will return line A.

Returns:

the line containing an offset

getLineStartOffset

public int getLineStartOffset(int line)

Given a specified line, returns the offset from the beginning of the TextBuffer for the start of the line.

Parameters:

line - a line in the TextBuffer

Returns:

the starting offset of the specified line

getLineEndOffset

public int getLineEndOffset(int line)

Given a specified line, returns the offset from the beginning of a TextBuffer that the line ends at.

Parameters:

line - a line in the TextBuffer