Report an issue
Class

Range (engine/model)

@ckeditor/ckeditor5-engine/src/model/range

class

Range class. Range is iterable.

Filtering

Properties

  • end : Position

    readonly

    End position.

  • isCollapsed : Boolean

    Returns whether the range is collapsed, that is if start and end positions are equal.

  • isFlat : Boolean

    Returns whether this range is flat, that is if start position and end position are in the same parent.

  • root : Element | DocumentFragment

    Range root element.

  • start : Position

    readonly

    Start position.

Methods

  • constructor( start, [ end ] )

    Creates a range spanning from start position to end position.

    Note: Constructor creates it's own Position instances basing on passed values.

    Parameters

    start : Position

    Start position.

    [ end ] : Position

    End position. If not set, range will be collapsed at start position.

  • Symbol.iterator() → Iterable.<TreeWalkerValue>

    Iterable interface.

    Iterates over all items that are in this range and returns them together with additional information like length or positions, grouped as TreeWalkerValue. It iterates over all text contents that are inside the range and all the Elements that are entered into when iterating over this range.

    This iterator uses TreeWalker with boundaries set to this range and ignoreElementEnd option set to true.

    Returns

    Iterable.<TreeWalkerValue>
  • containsItem( item )

    Checks whether given Item is inside this range.

    Parameters

    item : Item

    Model item to check.

  • containsPosition( position ) → Boolean

    Checks whether this range contains given position.

    Parameters

    position : Position

    Position to check.

    Returns

    Boolean

    true if given position is contained in this range,false otherwise.

  • containsRange( otherRange, [ loose ] ) → Boolean

    Checks whether this range contains given range.

    Parameters

    otherRange : Range

    Range to check.

    [ loose ] : Boolean

    Whether the check is loose or strict. If the check is strict (false), compared range cannot start or end at the same position as this range boundaries. If the check is loose (true), compared range can start, end or even be equal to this range. Note that collapsed ranges are always compared in strict mode.

    Defaults to false

    Returns

    Boolean

    true if given range boundaries are contained by this range, false otherwise.

  • getCommonAncestor() → Element | DocumentFragment | null

    Returns an Element or DocumentFragment which is a common ancestor of the range's both ends (in which the entire range is contained).

    Returns

    Element | DocumentFragment | null
  • getDifference( otherRange ) → Array.<Range>

    Computes which part(s) of this range is not a part of given range. Returned array contains zero, one or two ranges.

    Examples:

    let range = new Range( new Position( root, [ 2, 7 ] ), new Position( root, [ 4, 0, 1 ] ) );
    let otherRange = new Range( new Position( root, [ 1 ] ), new Position( root, [ 5 ] ) );
    let transformed = range.getDifference( otherRange );
    // transformed array has no ranges because `otherRange` contains `range`
    
    otherRange = new Range( new Position( root, [ 1 ] ), new Position( root, [ 3 ] ) );
    transformed = range.getDifference( otherRange );
    // transformed array has one range: from [ 3 ] to [ 4, 0, 1 ]
    
    otherRange = new Range( new Position( root, [ 3 ] ), new Position( root, [ 4 ] ) );
    transformed = range.getDifference( otherRange );
    // transformed array has two ranges: from [ 2, 7 ] to [ 3 ] and from [ 4 ] to [ 4, 0, 1 ]

    Parameters

    otherRange : Range

    Range to differentiate against.

    Returns

    Array.<Range>

    The difference between ranges.

  • getIntersection( otherRange ) → Range | null

    Returns an intersection of this range and given range. Intersection is a common part of both of those ranges. If ranges has no common part, returns null.

    Examples:

    let range = new Range( new Position( root, [ 2, 7 ] ), new Position( root, [ 4, 0, 1 ] ) );
    let otherRange = new Range( new Position( root, [ 1 ] ), new Position( root, [ 2 ] ) );
    let transformed = range.getIntersection( otherRange ); // null - ranges have no common part
    
    otherRange = new Range( new Position( root, [ 3 ] ), new Position( root, [ 5 ] ) );
    transformed = range.getIntersection( otherRange ); // range from [ 3 ] to [ 4, 0, 1 ]

    Parameters

    otherRange : Range

    Range to check for intersection.

    Returns

    Range | null

    A common part of given ranges or null if ranges have no common part.

  • getMinimalFlatRanges() → Array.<Range>

    Computes and returns the smallest set of flat ranges, that covers this range in whole.

    See an example of a model structure ([ and ] are range boundaries):

    root                                                            root
     |- element DIV                         DIV             P2              P3             DIV
     |   |- element H                   H        P1        f o o           b a r       H         P4
     |   |   |- "fir[st"             fir[st     lorem                               se]cond     ipsum
     |   |- element P1
     |   |   |- "lorem"                                              ||
     |- element P2                                                   ||
     |   |- "foo"                                                    VV
     |- element P3
     |   |- "bar"                                                   root
     |- element DIV                         DIV             [P2             P3]             DIV
     |   |- element H                   H       [P1]       f o o           b a r        H         P4
     |   |   |- "se]cond"            fir[st]    lorem                               [se]cond     ipsum
     |   |- element P4
     |   |   |- "ipsum"

    As it can be seen, letters contained in the range are: stloremfoobarse, spread across different parents. We are looking for minimal set of flat ranges that contains the same nodes.

    Minimal flat ranges for above range ( [ 0, 0, 3 ], [ 3, 0, 2 ] ) will be:

    ( [ 0, 0, 3 ], [ 0, 0, 5 ] ) = "st"
    ( [ 0, 1 ], [ 0, 2 ] ) = element P1 ("lorem")
    ( [ 1 ], [ 3 ] ) = element P2, element P3 ("foobar")
    ( [ 3, 0, 0 ], [ 3, 0, 2 ] ) = "se"

    Note: if an element is not wholly contained in this range, it won't be returned in any of the returned flat ranges. See in the example how H elements at the beginning and at the end of the range were omitted. Only their parts that were wholly in the range were returned.

    Note: this method is not returning flat ranges that contain no nodes.

    Returns

    Array.<Range>

    Array of flat ranges covering this range.

  • getPositions( options ) → Iterable.<Position>

    Returns an iterator that iterates over all positions that are boundaries or contained in this range.

    This method uses TreeWalker with boundaries set to this range. However it returns only positions, not TreeWalkerValue.

    You may specify additional options for the tree walker. See TreeWalker for a full list of available options.

    Parameters

    options : Object

    Object with configuration options. See TreeWalker.

    Returns

    Iterable.<Position>
  • getTransformedByDelta( delta ) → Array.<Range>

    Returns a range that is a result of transforming this range by given delta.

    Note: transformation may break one range into multiple ranges (e.g. when a part of the range is moved to a different part of document tree). For this reason, an array is returned by this method and it may contain one or more Range instances.

    Parameters

    delta : Delta

    Delta to transform range by.

    Returns

    Array.<Range>

    Range which is the result of transformation.

  • getTransformedByDeltas( deltas ) → Array.<Range>

    Returns a range that is a result of transforming this range by multiple deltas.

    Note: transformation may break one range into multiple ranges (e.g. when a part of the range is moved to a different part of document tree). For this reason, an array is returned by this method and it may contain one or more Range instances.

    Parameters

    deltas : Iterable.<Delta>

    Deltas to transform the range by.

    Returns

    Array.<Range>

    Range which is the result of transformation.

  • getWalker( options = { [options.startPosition], [options.singleCharacters], [options.shallow], [options.ignoreElementEnd] } )

    Creates a TreeWalker instance with this range as a boundary.

    Parameters

    options : Object

    Object with configuration options. See TreeWalker.

    Properties
    [ options.startPosition ] : Position
    [ options.singleCharacters ] : Boolean

    Defaults to false

    [ options.shallow ] : Boolean

    Defaults to false

    [ options.ignoreElementEnd ] : Boolean

    Defaults to false

  • isEqual( otherRange ) → Boolean

    Two ranges are equal if their start and end positions are equal.

    Parameters

    otherRange : Range

    Range to compare with.

    Returns

    Boolean

    true if ranges are equal, false otherwise.

  • isIntersecting( otherRange ) → Boolean

    Checks and returns whether this range intersects with given range.

    Parameters

    otherRange : Range

    Range to compare with.

    Returns

    Boolean

    true if ranges intersect, false otherwise.

  • _getTransformedByDocumentChange( type, deltaType, targetPosition, howMany, sourcePosition ) → Array.<Range>

    protected

    Returns a range that is a result of transforming this range by a change in the model document.

    Parameters

    type : 'insert' | 'move' | 'remove' | 'reinsert'

    Change type.

    deltaType : String

    Type of delta that introduced the change.

    targetPosition : Position

    Position before the first changed node.

    howMany : Number

    How many nodes has been changed.

    sourcePosition : Position

    Source position of changes.

    Returns

    Array.<Range>
  • _getTransformedByInsertion( insertPosition, howMany, [ spread ], [ isSticky ] ) → Array.<Range>

    protected

    Returns an array containing one or two ranges that are a result of transforming this range by inserting howMany nodes at insertPosition. Two ranges are returned if the insertion was inside this range and spread is set to true.

    Examples:

    let range = new Range( new Position( root, [ 2, 7 ] ), new Position( root, [ 4, 0, 1 ] ) );
    let transformed = range._getTransformedByInsertion( new Position( root, [ 1 ] ), 2 );
    // transformed array has one range from [ 4, 7 ] to [ 6, 0, 1 ]
    
    transformed = range._getTransformedByInsertion( new Position( root, [ 4, 0, 0 ] ), 4 );
    // transformed array has one range from [ 2, 7 ] to [ 4, 0, 5 ]
    
    transformed = range._getTransformedByInsertion( new Position( root, [ 3, 2 ] ), 4 );
    // transformed array has one range, which is equal to original range
    
    transformed = range._getTransformedByInsertion( new Position( root, [ 3, 2 ] ), 4, true );
    // transformed array has two ranges: from [ 2, 7 ] to [ 3, 2 ] and from [ 3, 6 ] to [ 4, 0, 1 ]
    
    transformed = range._getTransformedByInsertion( new Position( root, [ 4, 0, 1 ] ), 4, false, false );
    // transformed array has one range which is equal to original range because insertion is after the range boundary
    
    transformed = range._getTransformedByInsertion( new Position( root, [ 4, 0, 1 ] ), 4, false, true );
    // transformed array has one range: from [ 2, 7 ] to [ 4, 0, 5 ] because range was expanded

    Parameters

    insertPosition : Position

    Position where nodes are inserted.

    howMany : Number

    How many nodes are inserted.

    [ spread ] : Boolean

    Flag indicating whether this {~Range range} should be spread if insertion was inside the range. Defaults to false.

    Defaults to false

    [ isSticky ] : Boolean

    Flag indicating whether insertion should expand a range if it is in a place of range boundary. Defaults to false.

    Defaults to false

    Returns

    Array.<Range>

    Result of the transformation.

  • _getTransformedByMove( sourcePosition, targetPosition, howMany ) → Array.<Range>

    protected

    Returns an array containing ranges that are a result of transforming this range by moving howMany nodes from sourcePosition to targetPosition.

    Parameters

    sourcePosition : Position

    Position from which nodes are moved.

    targetPosition : Position

    Position to where nodes are moved.

    howMany : Number

    How many nodes are moved.

    Returns

    Array.<Range>

    Result of the transformation.

Static methods

  • createCollapsedAt( itemOrPosition, [ offset ] )

    static

    Creates a collapsed range at given position or on the given item.

    Parameters

    itemOrPosition : Item | Position
    [ offset ] : Number | 'end' | 'before' | 'after'

    Offset or one of the flags. Used only when first parameter is a model item.

    Defaults to 0

  • createFromParentsAndOffsets( startElement, startOffset, endElement, endOffset ) → Range

    static

    Creates a range from given parents and offsets.

    Parameters

    startElement : Element

    Start position parent element.

    startOffset : Number

    Start position offset.

    endElement : Element

    End position parent element.

    endOffset : Number

    End position offset.

    Returns

    Range
  • createFromPositionAndShift( position, shift ) → Range

    static

    Creates a new range, spreading from specified position to a position moved by given shift. If shift is a negative value, shifted position is treated as the beginning of the range.

    Parameters

    position : Position

    Beginning of the range.

    shift : Number

    How long the range should be.

    Returns

    Range
  • createFromRange( range ) → Range

    static

    Creates a new instance of Range which is equal to passed range.

    Parameters

    range : Range

    Range to clone.

    Returns

    Range
  • createFromRanges( ranges ) → Range

    static

    Combines all ranges from the passed array into a one range. At least one range has to be passed. Passed ranges must not have common parts.

    The first range from the array is a reference range. If other ranges start or end on the exactly same position where the reference range, they get combined into one range.

    [  ][]  [    ][ ][             ][ ][]  [  ]  // Passed ranges, shown sorted
    [    ]                                       // The result of the function if the first range was a reference range.
            [                           ]        // The result of the function if the third-to-seventh range was a reference range.
                                           [  ]  // The result of the function if the last range was a reference range.

    Parameters

    ranges : Array.<Range>

    Ranges to combine.

    Returns

    Range

    Combined range.

  • createIn( element ) → Range

    static

    Creates a range inside an element which starts before the first child of that element and ends after the last child of that element.

    Parameters

    element : Element

    Element which is a parent for the range.

    Returns

    Range
  • createOn( item ) → Range

    static

    Creates a range that starts before given model item and ends after it.

    Parameters

    item : Item

    Returns

    Range
  • fromJSON( json, doc ) → Element

    static

    Creates a Range instance from given plain object (i.e. parsed JSON string).

    Parameters

    json : Object

    Plain object to be converted to Range.

    doc : Document

    Document object that will be range owner.

    Returns

    Element

    Range instance created using given plain object.