Add example showing the use of asfoldable to docs

examples/reducibles.jl

@@ -8,6 +8,8 @@ struct VecOfVec{T}
     vectors::Vector{Vector{T}}
 end
 
+# ## Method 1: The `__foldl__` interface:
+
 # We need [`@next`](@ref Transducers.@next) and [`complete`](@ref
 # Transducers.complete) to invoke the reducing function `rf`.
 
@@ -47,6 +49,32 @@ vov |> Take(3) |> collect
 
 vov |> PartitionBy(isequal(1)) |> Zip(Map(copy), Map(sum)) |> collect
 
+# ## Method 2: In terms of existing transducers and reducibles with `asfoldable`
+
+# Transducers.jl has a function `Transducers.asfoldable` which can be overloaded to convert your existing type into a foldable before being fed
+# into `__foldl__`. This allows us to express a new type in terms of existing structures:
+
+struct VecOfVec2{T}
+    vectors::Vector{T}
+end
+Transducers.asfoldable(vov::VecOfVec2) = vov.vectors |> Cat()
+
+# This simply tells Transducers.jl that a `VecOfVec2` may be folded over by simply applying the [`Cat`](@ref Transducers.Cat) transducer 
+# to the `.vectors` field of the struct. This is enough to reproduce all the examples from the previous section:
+
+vov2 = VecOfVec2(collect.([1:n for n in 1:3]))
+collect(Map(identity), vov2)
+
+# 
+
+vov2 |> Take(3) |> collect
+
+# 
+
+vov2 |> PartitionBy(isequal(1)) |> Zip(Map(copy), Map(sum)) |> collect
+
+# ## Comparison to defining an Iterator:
+
 # Notice that writing [`Transducers.__foldl__`](@ref) is very
 # straightforward comparing to how to define an iterator:
 

src/core.jl

@@ -884,6 +884,26 @@ identityof(::typeof(right), ::Any) = nothing
 
 abstract type Reducible end
 abstract type Foldable <: Reducible end
+
+"""
+   Transducers.asfoldable(x) -> foldable
+
+By default, this function does nothing, but it can be overloaded to convert an input into another type before reducing over it.
+This allows one to implement a foldable in terms of transducers over an existing type. For instance,
+
+```julia
+struct VectorOfVectors{T}
+   v::Vector{Vector{T}}
+end
+
+Transducers.asfoldable(vov::VectorOfVectors{T}) = vov.v |> Cat()
+```
+Now we can do things like
+```julia
+julia> foldxl(+, VectorOfVectors([[1,2], [3, 4]]))
+10
+```
+"""
 asfoldable(x) = x
 
 """