Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.text.edits
Class TextEdit

    java.lang.Object
      org.eclipse.text.edits.TextEdit

Direct Known Subclasses:
  CopyingRangeMarker, CopySourceEdit, CopyTargetEdit, DeleteEdit, InsertEdit, MoveSourceEdit, MoveTargetEdit, MultiTextEdit, RangeMarker, ReplaceEdit, UndoEdit

public abstract class TextEdit
extends Object

A text edit describes an elementary text manipulation operation. Edits are executed by applying them to a document (e.g. an instance of `IDocument` ).

Text edits form a tree. Clients can navigate the tree upwards, from child to parent, as well as downwards. Newly created edits are unparented. New edits are added to the tree by calling one of the `add` methods on a parent edit.

An edit tree is well formed in the following sense:

- a parent edit covers all its children
- children don't overlap
- an edit with length 0 can't have any children

Any manipulation of the tree that violates one of the above requirements results in a `MalformedTreeException`.

Insert edits are represented by an edit of length 0. If more than one insert edit exists at the same offset then the edits are executed in the order in which they have been added to a parent. The following code example:

        IDocument document= new Document("org");
     	  MultiEdit edit= new MultiEdit();
        edit.add(new InsertEdit(0, "www.");
        edit.add(new InsertEdit(0, "eclipse.");
        edit.apply(document);

therefore results in string: "www.eclipse.org".

Text edits can be executed in a mode where the edit's region is updated to reflect the edit's position in the changed document. Region updating is enabled by default or can be requested by passing `UPDATE_REGIONS` to the `apply(IDocument, int)` method. In the above example the region of the `InsertEdit(0, "eclipse.")` edit after executing the root edit is `[3, 8]`. If the region of an edit got deleted during change execution the region is set to `[-1, -1]` and the method `isDeleted` returns `true`.

This class isn't intended to be subclassed outside of the edit framework. Clients are only allowed to subclass `MultiTextEdit`.

Since:
  3.0

Field Summary
`static int` | `CREATE_UNDO` Flags indicating that applying an edit tree to a document is supposed to create a corresponding undo edit.
`static int` | `NONE` Flags indicating that either `CREATE_UNDO` nor `UPDATE_REGIONS` is set.
`static int` | `UPDATE_REGIONS` Flag indicating that the edit's region will be updated to reflect its position in the changed document.

Constructor Summary
`protected` | `TextEdit(int offset, int length)` Create a new text edit.
`protected` | `TextEdit(TextEdit source)` Copy constructor

Method Summary
`void` | `accept(TextEditVisitor visitor)` Accepts the given visitor on a visit of the current edit.
`protected abstract void` | `accept0(TextEditVisitor visitor)` Accepts the given visitor on a type-specific visit of the current edit.
`protected void` | `acceptChildren(TextEditVisitor visitor)` Accepts the given visitor on the edits children.
`void` | `addChild(TextEdit child)` Adds the given edit `child` to this edit.
`void` | `addChildren(TextEdit[] edits)` Adds all edits in `edits` to this edit.
`UndoEdit` | `apply(IDocument document)` Applies the edit tree rooted by this edit to the given document.
`UndoEdit` | `apply(IDocument document, int style)` Applies the edit tree rooted by this edit to the given document.
`protected boolean` | `canZeroLengthCover()` Returns `true` if an edit with length zero can cover another edit.
`TextEdit` | `copy()` Creates a deep copy of the edit tree rooted at this edit.
`boolean` | `covers(TextEdit other)` Returns `true` if the edit covers the given edit `other`.
`protected abstract TextEdit` | `doCopy()` Creates and returns a copy of this edit.
`boolean` | `equals(Object obj)` The `Edit` implementation of this `Object` method uses object identity (==).
`TextEdit[]` | `getChildren()` Returns the edit's children.
`int` | `getChildrenSize()` Returns the size of the managed children.
`static IRegion` | `getCoverage(TextEdit[] edits)` Returns the text range spawned by the given array of text edits.
`int` | `getExclusiveEnd()` Returns the exclusive end position of this edit.
`int` | `getInclusiveEnd()` Returns the inclusive end position of this edit.
`int` | `getLength()` Returns the length of the edit.
`int` | `getOffset()` Returns the offset of the edit.
`TextEdit` | `getParent()` Returns the edit's parent.
`IRegion` | `getRegion()` Returns the range that this edit is manipulating.
`boolean` | `hasChildren()` Returns `true` if this edit has children.
`int` | `hashCode()` The `Edit` implementation of this `Object` method calls uses `Object#hashCode()` to compute its hash code.
`boolean` | `isDeleted()` Returns whether this edit has been deleted or not.
`protected void` | `postProcessCopy(TextEditCopier copier)` This method is called on every edit of the copied tree to do some post-processing like connected an edit to a different edit in the tree.
`TextEdit` | `removeChild(int index)` Removes the edit specified by the given index from the list of children.
`boolean` | `removeChild(TextEdit child)` Removes the first occurrence of the given child from the list of children.
`TextEdit[]` | `removeChildren()` Removes all child edits from and returns them.
`String` | `toString()`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### NONE

    public static final int NONE

  Flags indicating that either `CREATE_UNDO` nor `UPDATE_REGIONS` is set.

  See Also:
    Constant Field Values

### CREATE_UNDO

    public static final int CREATE_UNDO

  Flags indicating that applying an edit tree to a document is supposed to create a corresponding undo edit. If not specified `null` is returned from method `apply`.

  See Also:
    Constant Field Values

### UPDATE_REGIONS

    public static final int UPDATE_REGIONS

  Flag indicating that the edit's region will be updated to reflect its position in the changed document. If not specified when applying an edit tree to a document the edit's region will be arbitrary. It is even not guaranteed that the tree is still well formed.

  See Also:
    Constant Field Values

Constructor Detail

### TextEdit

    protected TextEdit(int offset,
                       int length)

  Create a new text edit. Parent is initialized to `null`and the edit doesn't have any children.

  ``
Parameters:
  `offset` - the edit's offset
  `length` - the edit's length

### TextEdit

    protected TextEdit(TextEdit source)

  Copy constructor

Parameters:
  `source` - the source to copy form

Method Detail

### getRegion

    public final IRegion getRegion()

  Returns the range that this edit is manipulating. The returned `IRegion` contains the edit's offset and length at the point in time when this call is made. Any subsequent changes to the edit's offset and length aren't reflected in the returned region object.

  Creating a region for a deleted edit will result in an assertion failure.

  Returns:
    the manipulated region

### getOffset

    public final int getOffset()

  Returns the offset of the edit. An offset is a 0-based character index. Returns `-1` if the edit is marked as deleted

  Returns:
    the offset of the edit

### getLength

    public final int getLength()

  Returns the length of the edit. Returns `-1` if the edit is marked as deleted.

  Returns:
    the length of the edit

### getInclusiveEnd

    public final int getInclusiveEnd()

  Returns the inclusive end position of this edit. The inclusive end position denotes the last character of the region manipulated by this edit. The returned value is the result of the following calculation:

         getOffset() + getLength() - 1;

  Returns:
    the inclusive end position

### getExclusiveEnd

    public final int getExclusiveEnd()

  Returns the exclusive end position of this edit. The exclusive end position denotes the next character of the region manipulated by this edit. The returned value is the result of the following calculation:

         getOffset() + getLength();

  Returns:
    the exclusive end position

### isDeleted

    public final boolean isDeleted()

  Returns whether this edit has been deleted or not.

  Returns:
    `true` if the edit has been deleted; otherwise `false` is returned.

### covers

    public final boolean covers(TextEdit other)

  Returns `true` if the edit covers the given edit `other`. It is up to the concrete text edit to decide if a edit of length zero can cover another edit.

  Parameters:
    `other` - the other edit
  Returns:
    `true`if the edit covers the other edit; otherwise `false` is returned.``

### canZeroLengthCover

    protected boolean canZeroLengthCover()

  Returns `true` if an edit with length zero can cover another edit. Returns `false` otherwise.

  Returns:
    whether an edit of length zero can cover another edit

### getParent

    public final TextEdit getParent()

  Returns the edit's parent. The method returns `null` if this edit hasn't been add to another edit.

  Returns:
    the edit's parent

### addChild

    public final void addChild(TextEdit child)
                        throws MalformedTreeException

  Adds the given edit `child` to this edit.

  Parameters:
    `child` - the child edit to add
  Throws:
    `MalformedTreeException` - is thrown if the child edit can't be added to this edit. This is the case if the child overlaps with one of its siblings or if the child edit's region isn't fully covered by this edit.

### addChildren

    public final void addChildren(TextEdit[] edits)
                           throws MalformedTreeException

  Adds all edits in `edits` to this edit.

  Parameters:
    `edits` - the text edits to add
  Throws:
    `MalformedTreeException` - is thrown if one of the given edits can't be added to this edit.
  See Also:
    `addChild(TextEdit)`

### removeChild

    public final TextEdit removeChild(int index)

  Removes the edit specified by the given index from the list of children. Returns the child edit that was removed from the list of children. The parent of the returned edit is set to `null`.

  Parameters:
    `index` - the index of the edit to remove
  Returns:
    the removed edit
  Throws:
    `IndexOutOfBoundsException` - if the index is out of range

### removeChild

    public final boolean removeChild(TextEdit child)

  Removes the first occurrence of the given child from the list of children.

  Parameters:
    `child` - the child to be removed
  Returns:
    `true` if the edit contained the given child; otherwise `false` is returned

### removeChildren

    public final TextEdit[] removeChildren()

  Removes all child edits from and returns them. The parent of the removed edits is set to `null`.

  Returns:
    an array of the removed edits

### hasChildren

    public final boolean hasChildren()

  Returns `true` if this edit has children. Otherwise `false` is returned.

  Returns:
    `true` if this edit has children; otherwise `false` is returned

### getChildren

    public final TextEdit[] getChildren()

  Returns the edit's children. If the edit doesn't have any children an empty array is returned.

  Returns:
    the edit's children

### getChildrenSize

    public final int getChildrenSize()

  Returns the size of the managed children.

  Returns:
    the size of the children

### getCoverage

    public static IRegion getCoverage(TextEdit[] edits)

  Returns the text range spawned by the given array of text edits. The method requires that the given array contains at least one edit. If all edits passed are deleted the method returns `null`.

  Parameters:
    `edits` - an array of edits
  Returns:
    the text range spawned by the given array of edits or `null` if all edits are marked as deleted

### equals

    public final boolean equals(Object obj)

  The `Edit` implementation of this `Object` method uses object identity (==).

  Parameters:
    `obj` - the other object
  Returns:
    `true` iff `this == obj`; otherwise `false` is returned
  See Also:
    `Object.equals(java.lang.Object)`

### hashCode

    public final int hashCode()

  The `Edit` implementation of this `Object` method calls uses `Object#hashCode()` to compute its hash code.

  Returns:
    the object's hash code value
  See Also:
    `Object.hashCode()`

### toString

    public String toString()

### copy

    public final TextEdit copy()

  Creates a deep copy of the edit tree rooted at this edit.

  Returns:
    a deep copy of the edit tree
  See Also:
    `doCopy()`

### doCopy

    protected abstract TextEdit doCopy()

  Creates and returns a copy of this edit. The copy method should be implemented in a way so that the copy can executed without causing any harm to the original edit. Implementors of this method are responsible for creating deep or shallow copies of referenced object to fullfil this requirement.

  Implementers of this method should use the copy constructor `Edit#Edit(Edit source) to initialize the edit part of the copy. Implementors aren't responsible to actually copy the children or to set the right parent.`

  This method should not be called from outside the framework. Please use `copy` to create a copy of a edit tree.

  Returns:
    a copy of this edit.
  See Also:
    `copy()`, `postProcessCopy(TextEditCopier)`, `TextEditCopier`

### postProcessCopy

    protected void postProcessCopy(TextEditCopier copier)

  This method is called on every edit of the copied tree to do some post-processing like connected an edit to a different edit in the tree.

  This default implementation does nothing

  Parameters:
    `copier` - the copier that manages a map between original and copied edit.
  See Also:
    `TextEditCopier`

### accept

    public final void accept(TextEditVisitor visitor)

  Accepts the given visitor on a visit of the current edit.

  Parameters:
    `visitor` - the visitor object
  Throws:
    `IllegalArgumentException` - if the visitor is null

### accept0

    protected abstract void accept0(TextEditVisitor visitor)

  Accepts the given visitor on a type-specific visit of the current edit. This method must be implemented in all concrete text edits.

  General template for implementation on each concrete TextEdit class:

       boolean visitChildren = visitor.visit(this);
       if (visitChildren) {
          acceptChildren(visitor);
       }

  Note that the caller (`accept`) takes care of invoking `visitor.preVisit(this)` and `visitor.postVisit(this)`.

  Parameters:
    `visitor` - the visitor object

### acceptChildren

    protected final void acceptChildren(TextEditVisitor visitor)

  Accepts the given visitor on the edits children.

  This method must be used by the concrete implementations of `accept` to traverse list-values properties; it encapsulates the proper handling of on-the-fly changes to the list.

  Parameters:
    `visitor` - the visitor object

### apply

    public final UndoEdit apply(IDocument document,
                                int style)
                         throws MalformedTreeException,
                                BadLocationException

  Applies the edit tree rooted by this edit to the given document. To check if the edit tree can be applied to the document either catch `MalformedTreeException` or use `TextEditProcessor` to execute an edit tree.

  Parameters:
    `document` - the document to be manipulated
    `style` - flags controlling the execution of the edit tree. Valid flags are: `CREATE_UNDO` and UPDATE_REGIONS.
  Returns:
    a undo edit, if `CREATE_UNDO` is specified. Otherwise `null` is returned.
  Throws:
    `MalformedTreeException` - is thrown if the tree isn't in a valid state. This exception is thrown before any edit is executed. So the document is still in its original state.
    `BadLocationException` - is thrown if one of the edits in the tree can't be executed. The state of the document is undefined if this exception is thrown.
  See Also:
    `TextEditProcessor.performEdits()`

### apply

    public final UndoEdit apply(IDocument document)
                         throws MalformedTreeException,
                                BadLocationException

  Applies the edit tree rooted by this edit to the given document. This method is a convenience method for `apply(document, CREATE_UNDO | UPDATE_REGIONS)`

  Parameters:
    `document` - the document to which to apply this edit
  Returns:
    a undo edit, if `CREATE_UNDO` is specified. Otherwise `null` is returned.
  Throws:
    `MalformedTreeException` - is thrown if the tree isn't in a valid state. This exception is thrown before any edit is executed. So the document is still in its original state.
    `BadLocationException` - is thrown if one of the edits in the tree can't be executed. The state of the document is undefined if this exception is thrown.
  See Also:
    `apply(IDocument, int)`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.