Page History

...

• uniformity (ease of learning)
• conciseness (in expression)
• alignment with / exploitation of Java 8 styles, including streams
• hiding implementation internals

PDF of chapter on select documentation for review

This is the version 2 after incorporating most of Richard's suggestions on version 1, uploaded Monday 17 Oct at 3:45 EDT.

Here: 

Conceptual overview MS

...

Get all annotations of the given type at the specified offsets. , i.e. all annotations with exactly the given start and end offset.

MS: Does this mean covered-by (limit the FSs returned) or startAt - no limit?

REC: It does not mean covered-by because only annotations at the exact specified offset are returned. If there are multiple annotations at the given offset, then all of the specified type are returned.

selectAt(JCas, Class<T>, int, int)

jcas.select(Token.class).at(begin1, end3)

selectBetween

Get a list of annotations of the given annotation type located between two annotations. Does not use subiterators and does not respect type priorities. Zero-width annotations what lie on the borders are included in the result, e.g. if the boundary annotations are [1..2] and [2..3] then an annotation [2..2] is returned. If there is a non-zero overlap between the boundary annotations, the result is empty. The method properly handles cases where the second boundary annotations occurs before the first boundary annotation by switching their roles.

...

The covering annotation is never returned itself, even if it is of the queried-for type or a subtype of that type.
 

MS: Not sure why this is special-cased? 

REC: Because the covering annotation itself would always be included in the result and it is almost never needed. So handling it specifically (since we already know it) is easier than tediously filtering it out from the result in 99.9% of the cases.

MS: Good point.  Just for completeness, I'll point out a somewhat surprising fact that the covering annotation is not always included; it is only returned if

• it is in the index 
• it's type is the index's type or subtype.
• You can make annotations that don't fit these criteria, and use them as "covering" spec.

selectCovered(Class<T>, AnnotationFS)

...

selectFollowing(JCas, Class<T>, AnnotationFS, int)

// Initial brainstorming
jcas.select(Token.class).startAt(contextAnnotation).limit(10) // it is IMHO not entirely clear here that contextAnnotation is not included in the result...
jcas.select(Token.class).seek(contextAnnotation).skip(1).limit(10) // somehow too complex...
jcas.select(Token.class).following(contextAnnotation).limit(10)
 
// Suggestion MS - deleted - I like REC's better with the fs first.

 
// Suggestion REC 1
jcas.select().following(fs, 10)  // the 10 FSs >= fs
jcas.select().following(fs, 10, -3) // the 10 FSs >= { fs , after a -3 offset }
jcas.select().following(2, 20, 10, -3) // the 10 FSs >= { a bounding FS with begin=10, end=100, offset by -3}
jcas.select().preceding(10, 100, 3)  // the 3 FSs < a bounding FS with begin=10, end=100, in reverse order(?)
// Suggestion REC 2
jcas.at(fs).select(Token.class).following(10)  // the 10 FSs >= fs
jcas.at(fs).select(Token.class).precedingskip(-3).following(10) // the 10 FSs >= { fs , after a -3 offset }
jcas.at(10, 100).select(Token.class).preceding(3)  // the 3 FSs < a bounding FS with begin=10, end=100, in reverse order(?)
// MS: following(10) is the same as the standard stream method limit(10), I think. 
// Suggestion REC 3
jcas.select(Token.class, fs).following(10, fs, -3)10)  // the 10 FSs >= fs
jcas.select(Token.class, fs).skip(-3).following(10) // the 10 FSs >= { fs , after a -3 offset }
jcas.select(Token.class, 10, 100).preceding(3)  // the 3 FSs < a bounding FS with begin=10, end=100, in reverse order(?)
// MS: basic idea: extend select syntax, with 2nd positional argument, representing a position or a bound

REC: I would put the context to the front and the conditions to the back...

selectPreceding

Returns the n annotations preceding the given annotation.

...