add getrows

Author: CarloLucibello

docs/src/index.md

@@ -197,9 +197,11 @@ the table-specific use-case, knowing that it will Just Work™️.
 
 Before moving on to _implementing_ the Tables.jl interfaces, we take a quick
 break to highlight some useful utility functions provided by Tables.jl:
+
 ```@docs
 Tables.Schema
 Tables.schema
+Tables.getrows
 Tables.partitions
 Tables.partitioner
 Tables.rowtable
@@ -239,6 +241,7 @@ For a type `MyTable`, the interface to becoming a proper table is straightforwar
 | **Optional methods**                   |                              |                                                                                                                                 |
 | `Tables.schema(x::MyTable)`                     | `Tables.schema(x) = nothing` | Return a [`Tables.Schema`](@ref) object from your `Tables.AbstractRow` iterator or `Tables.AbstractColumns` object; or `nothing` for unknown schema |
 | `Tables.materializer(::Type{MyTable})` | `Tables.columntable`         | Declare a "materializer" sink function for your table type that can construct an instance of your type from any Tables.jl input |
+| `Tables.getrows(x::MyTable, inds; view)`  |            | Return a row or a sub-table of the original table
 
 Based on whether your table type has defined `Tables.rows` or `Tables.columns`, you then ensure that the `Tables.AbstractRow` iterator
 or `Tables.AbstractColumns` object satisfies the respective interface.

src/Tables.jl

@@ -565,6 +565,28 @@ struct Partitioner{T}
     x::T
 end
 
+"""
+    getrows(x, inds; view=nothing)
+
+Return one or more rows from table `x` according to the position(s) specified by `inds`.
+
+- If `inds` is a single integer return a row object.
+- If `inds` is a collection of integers, return a table object. 
+  In this case,t he returned type is not necessarily the same as the original table type.
+
+The `view` argument influences whether the returned object is a view of the original table
+or an independent copy:
+- If `view=nothing` (the default) then the implementation for a specific table type 
+  is free to decide  whether to return a copy or a view.
+- If `view=true` then a view is returned and if `view=false` a copy is returned.
+  This applies both to returning a row or a table.
+ 
+Any specialized implementation of `getrows` must support the `view=nothing` argument. 
+Support for `view=true` or `view=false` instead can be an opt-in 
+(i.e. implementations might error on them if they are not supported).
+"""
+function getrows end
+
 """
     Tables.partitioner(f, itr)
     Tables.partitioner(x)

test/runtests.jl

@@ -798,4 +798,8 @@ Tables.columnnames(::WideTable2) = [Symbol("x", i) for i = 1:1000]
         @test nm isa Symbol
         @test col isa Vector{Float64}
     end
+
+    @testset "getrows" begin
+        Tables.getrows isa Function
+    end
 end