nodelist.js 5.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204
  1. /**
  2. * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. /**
  6. * @module engine/model/nodelist
  7. */
  8. import Node from './node';
  9. import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  10. /**
  11. * Provides an interface to operate on a list of {@link module:engine/model/node~Node nodes}. `NodeList` is used internally
  12. * in classes like {@link module:engine/model/element~Element Element}
  13. * or {@link module:engine/model/documentfragment~DocumentFragment DocumentFragment}.
  14. */
  15. export default class NodeList {
  16. /**
  17. * Creates an empty node list.
  18. *
  19. * @param {Iterable.<module:engine/model/node~Node>} nodes Nodes contained in this node list.
  20. */
  21. constructor( nodes ) {
  22. /**
  23. * Nodes contained in this node list.
  24. *
  25. * @private
  26. * @member {Array.<module:engine/model/node~Node>}
  27. */
  28. this._nodes = [];
  29. if ( nodes ) {
  30. this.insertNodes( 0, nodes );
  31. }
  32. }
  33. /**
  34. * Returns an iterator that iterates over all nodes contained inside this node list.
  35. *
  36. * @returns {Iterator.<module:engine/model/node~Node>}
  37. */
  38. [ Symbol.iterator ]() {
  39. return this._nodes[ Symbol.iterator ]();
  40. }
  41. /**
  42. * Number of nodes contained inside this node list.
  43. *
  44. * @readonly
  45. * @type {Number}
  46. */
  47. get length() {
  48. return this._nodes.length;
  49. }
  50. /**
  51. * Sum of {@link module:engine/model/node~Node#offsetSize offset sizes} of all nodes contained inside this node list.
  52. *
  53. * @readonly
  54. * @type {Number}
  55. */
  56. get maxOffset() {
  57. return this._nodes.reduce( ( sum, node ) => sum + node.offsetSize, 0 );
  58. }
  59. /**
  60. * Gets the node at the given index. Returns `null` if incorrect index was passed.
  61. *
  62. * @param {Number} index Index of node.
  63. * @returns {module:engine/model/node~Node|null} Node at given index.
  64. */
  65. getNode( index ) {
  66. return this._nodes[ index ] || null;
  67. }
  68. /**
  69. * Returns an index of the given node. Returns `null` if given node is not inside this node list.
  70. *
  71. * @param {module:engine/model/node~Node} node Child node to look for.
  72. * @returns {Number|null} Child node's index.
  73. */
  74. getNodeIndex( node ) {
  75. const index = this._nodes.indexOf( node );
  76. return index == -1 ? null : index;
  77. }
  78. /**
  79. * Returns the starting offset of given node. Starting offset is equal to the sum of
  80. * {module:engine/model/node~Node#offsetSize offset sizes} of all nodes that are before this node in this node list.
  81. *
  82. * @param {module:engine/model/node~Node} node Node to look for.
  83. * @returns {Number|null} Node's starting offset.
  84. */
  85. getNodeStartOffset( node ) {
  86. const index = this.getNodeIndex( node );
  87. return index === null ? null : this._nodes.slice( 0, index ).reduce( ( sum, node ) => sum + node.offsetSize, 0 );
  88. }
  89. /**
  90. * Converts index to offset in node list.
  91. *
  92. * Returns starting offset of a node that is at given index. Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
  93. * `model-nodelist-index-out-of-bounds` if given index is less than `0` or more than {@link #length}.
  94. *
  95. * @param {Number} index Node's index.
  96. * @returns {Number} Node's starting offset.
  97. */
  98. indexToOffset( index ) {
  99. if ( index == this._nodes.length ) {
  100. return this.maxOffset;
  101. }
  102. const node = this._nodes[ index ];
  103. if ( !node ) {
  104. /**
  105. * Given index cannot be found in the node list.
  106. *
  107. * @error nodelist-index-out-of-bounds
  108. */
  109. throw new CKEditorError( 'model-nodelist-index-out-of-bounds: Given index cannot be found in the node list.' );
  110. }
  111. return this.getNodeStartOffset( node );
  112. }
  113. /**
  114. * Converts offset in node list to index.
  115. *
  116. * Returns index of a node that occupies given offset. Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
  117. * `model-nodelist-offset-out-of-bounds` if given offset is less than `0` or more than {@link #maxOffset}.
  118. *
  119. * @param {Number} offset Offset to look for.
  120. * @returns {Number} Index of a node that occupies given offset.
  121. */
  122. offsetToIndex( offset ) {
  123. let totalOffset = 0;
  124. for ( const node of this._nodes ) {
  125. if ( offset >= totalOffset && offset < totalOffset + node.offsetSize ) {
  126. return this.getNodeIndex( node );
  127. }
  128. totalOffset += node.offsetSize;
  129. }
  130. if ( totalOffset != offset ) {
  131. /**
  132. * Given offset cannot be found in the node list.
  133. *
  134. * @error nodelist-offset-out-of-bounds
  135. */
  136. throw new CKEditorError( 'model-nodelist-offset-out-of-bounds: Given offset cannot be found in the node list.' );
  137. }
  138. return this.length;
  139. }
  140. /**
  141. * Inserts given nodes at given index.
  142. *
  143. * @param {Number} index Index at which nodes should be inserted.
  144. * @param {Iterable.<module:engine/model/node~Node>} nodes Nodes to be inserted.
  145. */
  146. insertNodes( index, nodes ) {
  147. // Validation.
  148. for ( const node of nodes ) {
  149. if ( !( node instanceof Node ) ) {
  150. /**
  151. * Trying to insert an object which is not a Node instance.
  152. *
  153. * @error nodelist-insertNodes-not-node
  154. */
  155. throw new CKEditorError( 'model-nodelist-insertNodes-not-node: Trying to insert an object which is not a Node instance.' );
  156. }
  157. }
  158. this._nodes.splice( index, 0, ...nodes );
  159. }
  160. /**
  161. * Removes one or more nodes starting at the given index.
  162. *
  163. * @param {Number} indexStart Index of the first node to remove.
  164. * @param {Number} [howMany=1] Number of nodes to remove.
  165. * @returns {Array.<module:engine/model/node~Node>} Array containing removed nodes.
  166. */
  167. removeNodes( indexStart, howMany = 1 ) {
  168. return this._nodes.splice( indexStart, howMany );
  169. }
  170. /**
  171. * Converts `NodeList` instance to an array containing nodes that were inserted in the node list. Nodes
  172. * are also converted to their plain object representation.
  173. *
  174. * @returns {Array.<module:engine/model/node~Node>} `NodeList` instance converted to `Array`.
  175. */
  176. toJSON() {
  177. return this._nodes.map( node => node.toJSON() );
  178. }
  179. }