position

Purpose

Matches documents containing arguments at a specific position in text.

Syntax

position()

position([number], term_1, term_2…​)

Arguments

The function position() has no required arguments. When called without arguments, optional named parameters should be specified, for example:

position(max_snt:=1) matches the first sentence of each text.

The function accepts several arguments:

  • The first optional parameter number is used to specify the maximum position (in tokens) at which the argument can occur in text. By default, the function finds arguments at the first position in text. Punctuation marks are not taken into consideration when calculating position number.

  • the terms to search for.

The function also accepts the following optional named parameters:

  1. scope:=line/sentence/paragraph/text/table_cell/table_row/table_name/table_row_name/table_column_name/heading/page specifies a position within a line/sentence/paragraph/text/table_cell/table_row/table_name/table_row_name/table_column_name/heading/page. The default value is text.

    • position(1, meeting) = position(1, meeting, scope:=text) finds the word "meeting", if it is the first word in the document, i.e. in the text "Meeting focus will be on organizational matters. Meeting dates and times are subject to change without notice".

    • position(1, meeting, scope:=sentence) finds the word "meeting", if it is the first word in the sentence, i.e. in both "Meeting focus will be on organizational matters" and Meeting dates and times are subject to change without notice".

  2. mode:=forward/backward specifies a position from the beginning/end of the scope; the default value is forward.

    • position(1, meeting, scope:=sentence) finds the word "meeting", if it is the first word in the sentence, for example, "Meeting dates and times are subject to change without notice".

    • position(1, meeting, scope:=sentence, mode:=backward) = position(meeting, scope:=sentence, mode:=backward, max_pos:=1) finds the word "meeting", if it is the last word in the sentence, for example, "Tomorrow we will have the date set for such a meeting".

    • position(1, meeting, mode:=backward) = position(meeting, mode:=backward, max_pos:=1) finds the word meeting, if it is the last word in the document.

    • position(2, meeting, scope:=sentence, mode:=backward) = position(meeting, scope:=sentence, mode:=backward, max_pos:=2) finds the word meeting, if its position is <= 2 from the sentence end, and finds "Tomorrow we will have the date set for such a meeting. We have a lot of meetings too.", but does not match "I think it will make the meeting more productive".

  3. min_pos/max_pos specifies the required minimal and maximal positions of the argument. The maximal position can be specified, using the first argument of the function, i.e. position(1, meeting) = position(meeting, max_pos:=1). If you need to count positions from the end of sentences, then you should specify negative values for min_pos and max_pos parameters.

    • position(meeting, min_pos:=2, max_pos:=4, scope:=sentence) finds the word "meeting", if its position is in the range [2;4] from the beginning of the sentence. It finds "New meeting request", "Below are meeting notes", but it does not match "The next Strategic Planning Meeting is scheduled for Wednesday".

    • position(meeting, min_pos:=3, max_pos:=3, scope:=sentence, mode:=backward) finds the word meeting, if its position is in the range [3;3] from the end of the sentence. It finds "I think it will make the meeting more productive", but does not find "We have a lot of meetings too".

    • position(min_snt:=1, min_pos:="-1") matches tokens starting from the last word of the first sentence.

  4. min_snt/max_snt specifies the minimal/maximal sentence number. If both min_snt and min_pos parameters are specified, positions will be counted from the beginning of the indicated sentence. The same will occur if both max_snt and max_pos parameters are indicated. If the sentence number is not specified, then the position is calculated from the beginning of the scope parameter.

    • position(meeting, min_snt:=2, max_snt:=2) finds the word "meeting" in the second sentence of the text.

Returned Value

Documents matching the query.

Examples

position(3, dog) matches the word "dog" within the first 3 tokens of the document. This would match "I chased dog" but not "I chased the dog" because in the latter case "dog" is at the 4th position.

position(min_snt:=1, min_pos:=1, max_snt:=1, max_pos:=2, mode:=backward) matches the first two words of the last sentence.

position(max_pos:=1, scope:=line) matches the first word of each line.

position(scope:=page, max_pos:=1) matches the first word of each page.

position(scope:=page, sentence(), max_snt:=1, mode:=backward) matches the last sentence of the last page.