Equality here means that both represent the same piece of text (i.e. at the same position) in the file. It compares using the custom Chunk.equals method if either chunk defines one, and falls back to checking the objects’ identity (i.e. chunk1 === chunk2).

Equality here means equality of each of their four properties (i.e. startChunk, startIndex, endChunk, and endIndex). For the startChunks and endChunks, this function uses the custom Chunk.equals method if defined.

Note that if the start/end of one range points at the end of a chunk, and the other to the start of a subsequent chunk, they are not considered equal, even though semantically they may be representing the same range of characters. To test for such semantic equivalence, ensure that both inputs are normalised: typically this means the range is shrunk to its narrowest equivalent, and (if it is empty) positioned at its first equivalent.

This is an abstract implementation of the function’s logic, which expects a generic Chunker to represent the text, and returns an (async) generator producing a single ChunkRange to represent the match. (unlike e.g. TextQuoteSelector, it cannot result in multiple matches).

See dom.createTextPositionSelectorMatcher for a wrapper around this implementation which applies it to the text of an HTML DOM.

The function is curried, taking first the selector and then the text.

example

const selector = { type: 'TextPositionSelector', start: 702, end: 736 };
const matches = textPositionSelectorMatcher(selector)(textChunks);
const match = (await matches.next()).value;
console.log(match);
// ⇒ { startChunk: { … }, startIndex: 64, endChunk: { … }, endIndex: 98 }

This performs an exact search the selector’s quote (including prefix and suffix) within the given text.

Note the match is based on strict character-by-character equivalence, i.e. it is sensitive to whitespace, capitalisation, etc.

This is an abstract implementation of the function’s logic, which expects a generic Chunker to represent the text, and returns an (async) generator of ChunkRanges to represent the matches.

See dom.createTextQuoteSelectorMatcher for a wrapper around this implementation which applies it to the text of an HTML DOM.

The function is curried, taking first the selector and then the text.

As there may be multiple matches for a given selector (when its prefix and suffix attributes are not sufficient to disambiguate it), the matcher will return an (async) generator that produces each match in the order they are found in the text.

XXX Modifying the Chunks while the search is still running can mess up and result in an error or an infinite loop. See issue #112.

example

const selector = { type: 'TextQuoteSelector', exact: 'banana' };
const matches = textQuoteSelectorMatcher(selector)(textChunks);
for await (match of matches) console.log(match);
// ⇒ { startChunk: { … }, startIndex: 187, endChunk: { … }, endIndex: 193 }
// ⇒ { startChunk: { … }, startIndex: 631, endChunk: { … }, endIndex: 637 }