ReQL command: slice, []

Command syntax

selection.slice(start_offset[, end_offset, :left_bound => 'closed', :right_bound =>'open']) → selection
stream.slice(start_offset[, end_offset, :left_bound => 'closed', :right_bound =>'open']) → stream
array.slice(start_offset[, end_offset, :left_bound => 'closed', :right_bound =>'open']) → array
binary.slice(start_offset[, end_offset, :left_bound => 'closed', :right_bound =>'open']) → binary
string.slice(start_offset[, end_offset, :left_bound => 'closed', :right_bound =>'open']) → string

Description

Return the elements of a sequence within the specified range.

slice returns the range between start_offset and end_offset. If only start_offset is specified, slice returns the range from that index to the end of the sequence. Specify left_bound or right_bound as open or closed to indicate whether to include that endpoint of the range by default: closed returns that endpoint, while open does not. By default, left_bound is closed and right_bound is open, so the range (10,13) will return the tenth, eleventh and twelfth elements in the sequence.

If end_offset is past the end of the sequence, all elements from start_offset to the end of the sequence will be returned. If start_offset is past the end of the sequence or end_offset is less than start_offset, a zero-element sequence will be returned.

Negative start_offset and end_offset values are allowed with arrays; in that case, the returned range counts back from the array’s end. That is, the range (-2) returns the last two elements, and the range of (2,-1) returns the second element through the next-to-last element of the range. An error will be raised on a negative start_offset or end_offset with non-arrays. (An end_offset of −1 is allowed with a stream if right_bound is closed; this behaves as if no end_offset was specified.)

If slice is used with a binary object, the indexes refer to byte positions within the object. That is, the range (10,20) will refer to the 10th byte through the 19th byte.

With a string, slice behaves similarly, with the indexes referring to Unicode codepoints. String indexes start at 0. (Note that combining codepoints are counted separately.)

If you are only specifying the indexes and not the bounding options, you may use Ruby’s range operator as a shorthand: [start_offset..end_offset]. Note that when you use this shorthand right_bound will be closed and thus include end_offset.

Example: Return the fourth, fifth and sixth youngest players. (The youngest player is at index 0, so those are elements 3–5.)

r.table('players').order_by(:index => 'age').slice(3,6).run(conn)

Or, using Ruby’s range operator:

r.table('players').filter({'class': 'amateur'})[10..19].run(conn)

Example: Return all but the top three players who have a red flag.

r.table('players').filter(:flag => 'red'}).order_by(:index => r.desc('score')).slice(3).run(conn)

Example: Return holders of tickets X through Y, assuming tickets are numbered sequentially. We want to include ticket Y.

r.table('users').order_by(:index => 'ticket').slice(x, y, :right_bound => 'closed').run(conn)

Example: Return the elements of an array from the second through two from the end (that is, not including the last two).

> r.expr([0,1,2,3,4,5]).slice(2,-2).run(conn)
[2,3]

Example: Return the third through fifth characters of a string.

> r.expr("rutabaga").slice(2,5).run(conn)
"tab"