# Interface IDocumentInformationMapping

All Known Implementing Classes:
  `ProjectionMapping`

public interface IDocumentInformationMapping
A `IDocumentInformationMapping` represents a mapping between the coordinates of two `IDocument` objects: the original and the image. The document information mapping can translate document information such as line numbers or character ranges given for the original into the corresponding information of the image and vice versa. In order to provided backward compatibility for clients of `IDocumentInformationMapping`, extension interfaces are used to provide a means of evolution. The following extension interfaces exist:

- `IDocumentInformationMappingExtension` since version 3.0 extending the degree of detail of the mapping information.
- `IDocumentInformationMappingExtension2` since version 3.1, adding lenient image region computation.

Since:
  2.1

## Method Summary

Modifier and Type
Method
Description
`IRegion`
`getCoverage()`
Returns the minimal region of the original document that completely comprises all of the image document or `null` if there is no such region.
`int`
`toClosestImageLine(int originLine)`
Returns the line of the image document whose corresponding line in the original document is closest to the given line in the original document.
`int`
`toImageLine(int originLine)`
Returns the line of the image document that corresponds to the given line of the original document or `-1` if there is no such line.
`int`
`toImageOffset(int originOffset)`
Returns the offset in the image document that corresponds to the given offset in the original document or `-1` if there is no such offset
`IRegion`
`toImageRegion(IRegion originRegion)`
Returns the minimal region of the image document that completely comprises the given region of the original document or `null` if there is no such region.
`int`
`toOriginLine(int imageLine)`
Returns the line of the original document that corresponds to the given line of the image document or `-1` if there is no such line.
`IRegion`
`toOriginLines(int imageLine)`
Returns the range of lines of the original document that corresponds to the given line of the image document or `null` if there are no such lines.
`int`
`toOriginOffset(int imageOffset)`
Returns the offset in the original document that corresponds to the given offset in the image document or `-1` if there is no such offset
`IRegion`
`toOriginRegion(IRegion imageRegion)`
Returns the minimal region of the original document that completely comprises the given region of the image document or `null` if there is no such region.

## Method Details

### getCoverage

IRegion getCoverage()
Returns the minimal region of the original document that completely comprises all of the image document or `null` if there is no such region.

Returns:
  the minimal region of the original document comprising the image document or `null`

### toOriginOffset

int toOriginOffset(int imageOffset) throws BadLocationException
Returns the offset in the original document that corresponds to the given offset in the image document or `-1` if there is no such offset

Parameters:
  `imageOffset` - the offset in the image document
Returns:
  the corresponding offset in the original document or `-1`
Throws:
  `BadLocationException` - if `imageOffset` is not a valid offset in the image document

### toOriginRegion

IRegion toOriginRegion(IRegion imageRegion) throws BadLocationException
Returns the minimal region of the original document that completely comprises the given region of the image document or `null` if there is no such region.

Parameters:
  `imageRegion` - the region of the image document
Returns:
  the minimal region of the original document comprising the given region of the image document or `null`
Throws:
  `BadLocationException` - if `imageRegion` is not a valid region of the image document

### toOriginLines

IRegion toOriginLines(int imageLine) throws BadLocationException
Returns the range of lines of the original document that corresponds to the given line of the image document or `null` if there are no such lines.

Parameters:
  `imageLine` - the line of the image document
Returns:
  the corresponding lines of the original document or `null`
Throws:
  `BadLocationException` - if `imageLine` is not a valid line number in the image document

### toOriginLine

int toOriginLine(int imageLine) throws BadLocationException
Returns the line of the original document that corresponds to the given line of the image document or `-1` if there is no such line.

Parameters:
  `imageLine` - the line of the image document
Returns:
  the corresponding line of the original document or `-1`
Throws:
  `BadLocationException` - if `imageLine` is not a valid line number in the image document

### toImageOffset

int toImageOffset(int originOffset) throws BadLocationException
Returns the offset in the image document that corresponds to the given offset in the original document or `-1` if there is no such offset

Parameters:
  `originOffset` - the offset in the original document
Returns:
  the corresponding offset in the image document or `-1`
Throws:
  `BadLocationException` - if `originOffset` is not a valid offset in the original document

### toImageRegion

IRegion toImageRegion(IRegion originRegion) throws BadLocationException
Returns the minimal region of the image document that completely comprises the given region of the original document or `null` if there is no such region.

Parameters:
  `originRegion` - the region of the original document
Returns:
  the minimal region of the image document comprising the given region of the original document or `null`
Throws:
  `BadLocationException` - if `originRegion` is not a valid region of the original document

### toImageLine

int toImageLine(int originLine) throws BadLocationException
Returns the line of the image document that corresponds to the given line of the original document or `-1` if there is no such line.

Parameters:
  `originLine` - the line of the original document
Returns:
  the corresponding line of the image document or `-1`
Throws:
  `BadLocationException` - if `originLine` is not a valid line number in the original document

### toClosestImageLine

int toClosestImageLine(int originLine) throws BadLocationException
Returns the line of the image document whose corresponding line in the original document is closest to the given line in the original document.

Parameters:
  `originLine` - the line in the original document
Returns:
  the line in the image document that corresponds best to the given line in the original document
Throws:
  `BadLocationException` - if `originLine`is not a valid line in the original document