From b40c868f8449132041ff40cd0c33515001af8cf0 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Sat, 9 Mar 2024 17:56:00 +0000 Subject: [PATCH] build based on 95a4cfd --- previews/PR74/.documenter-siteinfo.json | 2 +- previews/PR74/api/index.html | 18 +++++++++--------- previews/PR74/index.html | 2 +- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/previews/PR74/.documenter-siteinfo.json b/previews/PR74/.documenter-siteinfo.json index fce7209..a397392 100644 --- a/previews/PR74/.documenter-siteinfo.json +++ b/previews/PR74/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.6.7","generation_timestamp":"2024-03-09T12:23:17","documenter_version":"1.3.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.6.7","generation_timestamp":"2024-03-09T17:55:55","documenter_version":"1.3.0"}} \ No newline at end of file diff --git a/previews/PR74/api/index.html b/previews/PR74/api/index.html index a5542ad..9af9c1d 100644 --- a/previews/PR74/api/index.html +++ b/previews/PR74/api/index.html @@ -64,12 +64,12 @@ Foo("hello", (40, 50, "hello"))

The behaviour when the same node appears twice can be altered by giving a value to the prune keyword, which is then used in place of all but the first:

julia> twice = [1, 2];
 
 julia> fmap(float, (x = twice, y = [1,2], z = twice); prune = missing)
-(x = [1.0, 2.0], y = [1.0, 2.0], z = missing)
source
Functors.fmap_with_path — Function

" fmapwithpath(f, x, ys...; exclude = isleaf, walk = DefaultWalkWithPath(), [prune])

Like fmap, but also passes a KeyPath to f for each node in the recursion. The KeyPath is a tuple of the indices used to reach the current node from the root of the recursion. The KeyPath is constructed by the walk function, and can be used to reconstruct the path to the current node from the root of the recursion.

f has to accept two arguments: the value of the current node and the associated KeyPath.

exclude also receives the KeyPath as its first argument and a node as its second. It should return true if the recursion should not continue on its children and f applied to it.

prune is used to control the behaviour when the same node appears twice, see fmap for more information.

Examples

julia> x = ([1, 2, 3], 4, (a=5, b=Dict("A"=>6, "B"=>7), c=Dict("C"=>8, "D"=>9)));
+(x = [1.0, 2.0], y = [1.0, 2.0], z = missing)
source
Functors.fmap_with_path — Function

" fmapwithpath(f, x, ys...; exclude = isleaf, walk = DefaultWalkWithPath(), [prune])

Like fmap, but also passes a KeyPath to f for each node in the recursion. The KeyPath is a tuple of the indices used to reach the current node from the root of the recursion. The KeyPath is constructed by the walk function, and can be used to reconstruct the path to the current node from the root of the recursion.

f has to accept two arguments: the value of the current node and the associated KeyPath.

exclude also receives the KeyPath as its first argument and a node as its second. It should return true if the recursion should not continue on its children and f applied to it.

prune is used to control the behaviour when the same node appears twice, see fmap for more information.

Examples

julia> x = ([1, 2, 3], 4, (a=5, b=Dict("A"=>6, "B"=>7), c=Dict("C"=>8, "D"=>9)));
 
 julia> fexclude(kp, x) = kp == KeyPath(3, :c) || Functors.isleaf(x);
 
 julia> fmap_with_path((kp, x) -> x isa Dict ? nothing : x.^2, x; exclude = fexclude)
-([1, 4, 9], 16, (a = 25, b = Dict("B" => 49, "A" => 36), c = nothing))
source
Functors.@functor — Macro
@functor T
+([1, 4, 9], 16, (a = 25, b = Dict("B" => 49, "A" => 36), c = nothing))
source
Functors.@functor — Macro
@functor T
 @functor T (x,)

Adds methods to functor allowing recursion into objects of type T, and reconstruction. Assumes that T has a constructor accepting all of its fields, which is true unless you have provided an inner constructor which does not.

By default all fields of T are considered children; this can be restricted be restructed by providing a tuple of field names.

Examples

julia> struct Foo; x; y; end
 
 julia> @functor Foo
@@ -95,7 +95,7 @@
 TwoThirds("ten", 20, "thirty")
 
 julia> fmap(x -> 10x, TwoThirds(Foo(1,2), Foo(3,4), 56))
-TwoThirds(Foo(10, 20), Foo(3, 4), 560)
source
Functors.@leaf — Macro
@leaf T

Define functor for the type T so that isleaf(x::T) == true.

source
Functors.functor — Function
Functors.functor(x) = functor(typeof(x), x)

Returns a tuple containing, first, a NamedTuple of the children of x (typically its fields), and second, a reconstruction funciton. This controls the behaviour of fmap.

Methods should be added to functor(::Type{T}, x) for custom types, usually using the macro @functor.

source
Functors.children — Function
Functors.children(x)

Return the children of x as defined by functor. Equivalent to functor(x)[1].

source
Functors.isleaf — Function
Functors.isleaf(x)

Return true if x has no children according to functor.

Examples

julia> Functors.isleaf(1)
+TwoThirds(Foo(10, 20), Foo(3, 4), 560)
source
Functors.@leaf — Macro
@leaf T

Define functor for the type T so that isleaf(x::T) == true.

source
Functors.functor — Function
Functors.functor(x) = functor(typeof(x), x)

Returns a tuple containing, first, a NamedTuple of the children of x (typically its fields), and second, a reconstruction funciton. This controls the behaviour of fmap.

Methods should be added to functor(::Type{T}, x) for custom types, usually using the macro @functor.

source
Functors.children — Function
Functors.children(x)

Return the children of x as defined by functor. Equivalent to functor(x)[1].

source
Functors.isleaf — Function
Functors.isleaf(x)

Return true if x has no children according to functor.

Examples

julia> Functors.isleaf(1)
 true
 
 julia> Functors.isleaf([2, 3, 4])
@@ -111,11 +111,11 @@
 false
 
 julia> Functors.isleaf(())
-true
source
Functors.AbstractWalk — Type
AbstractWalk

Any walk for use with fmap should inherit from this type. A walk subtyping AbstractWalk must satisfy the walk function interface:

struct MyWalk <: AbstractWalk end
+true
source
Functors.AbstractWalk — Type
AbstractWalk

Any walk for use with fmap should inherit from this type. A walk subtyping AbstractWalk must satisfy the walk function interface:

struct MyWalk <: AbstractWalk end
 
 function (::MyWalk)(recurse, x, ys...)
   # implement this
-end

The walk function is called on a node x in a Functors tree. It may also be passed associated nodes ys... in other Functors trees. The walk function recurses further into (x, ys...) by calling recurse on the child nodes. The choice of which nodes to recurse and in what order is custom to the walk.

source
Functors.execute — Function
execute(walk, x, ys...)

Execute a walk that recursively calls itself, starting at a node x in a Functors tree, as well as optional associated nodes ys... in other Functors trees. Any custom walk function that subtypes Functors.AbstractWalk is permitted.

source
Functors.DefaultWalk — Type
DefaultWalk()

The default walk behavior for Functors.jl. Walks all the Functors.children of trees (x, ys...) based on the structure of x. The resulting mapped child nodes are restructured into the type of x.

See fmap for more information.

source
Functors.StructuralWalk — Type
StructuralWalk()

A structural variant of Functors.DefaultWalk. The recursion behavior is identical, but the mapped children are not restructured.

See fmapstructure for more information.

source
Functors.ExcludeWalk — Type
ExcludeWalk(walk, fn, exclude)

A walk that recurses nodes (x, ys...) according to walk, except when exclude(x) is true. Then, fn(x, ys...) is applied instead of recursing further.

Typically wraps an existing walk for use with fmap.

source
Functors.CachedWalk — Type
CachedWalk(walk[; prune])

A walk that recurses nodes (x, ys...) according to walk and storing the output of the recursion in a cache indexed by x (based on object ID). Whenever the cache already contains x, either:

  • prune is specified, then it is returned, or
  • prune is unspecified, and the previously cached recursion of (x, ys...) returned.

Typically wraps an existing walk for use with fmap.

source
Functors.CollectWalk — Type
CollectWalk()

A walk that recurses into a node x via Functors.children, storing the recursion history in a cache. The resulting ordered recursion history is returned.

See fcollect for more information.

source
Functors.AnonymousWalk — Type
AnonymousWalk(walk_fn)

Wrap a walk_fn so that AnonymousWalk(walk_fn) isa AbstractWalk. This type only exists for backwards compatability and should not be directly used. Attempting to wrap an existing AbstractWalk is a no-op (i.e. it is not wrapped).

source
Functors.IterateWalk — Type
IterateWalk()

A walk that walks all the Functors.children of trees (x, ys...) and concatenates the iterators of the children via Iterators.flatten. The resulting iterator is returned.

When used with fmap, the provided function f should return an iterator. For example, to iterate through the square of every scalar value:

julia> x = ([1, 2, 3], 4, (5, 6, [7, 8]));
+end

The walk function is called on a node x in a Functors tree. It may also be passed associated nodes ys... in other Functors trees. The walk function recurses further into (x, ys...) by calling recurse on the child nodes. The choice of which nodes to recurse and in what order is custom to the walk.

source
Functors.execute — Function
execute(walk, x, ys...)

Execute a walk that recursively calls itself, starting at a node x in a Functors tree, as well as optional associated nodes ys... in other Functors trees. Any custom walk function that subtypes Functors.AbstractWalk is permitted.

source
Functors.DefaultWalk — Type
DefaultWalk()

The default walk behavior for Functors.jl. Walks all the Functors.children of trees (x, ys...) based on the structure of x. The resulting mapped child nodes are restructured into the type of x.

See fmap for more information.

source
Functors.StructuralWalk — Type
StructuralWalk()

A structural variant of Functors.DefaultWalk. The recursion behavior is identical, but the mapped children are not restructured.

See fmapstructure for more information.

source
Functors.ExcludeWalk — Type
ExcludeWalk(walk, fn, exclude)

A walk that recurses nodes (x, ys...) according to walk, except when exclude(x) is true. Then, fn(x, ys...) is applied instead of recursing further.

Typically wraps an existing walk for use with fmap.

source
Functors.CachedWalk — Type
CachedWalk(walk[; prune])

A walk that recurses nodes (x, ys...) according to walk and storing the output of the recursion in a cache indexed by x (based on object ID). Whenever the cache already contains x, either:

  • prune is specified, then it is returned, or
  • prune is unspecified, and the previously cached recursion of (x, ys...) returned.

Typically wraps an existing walk for use with fmap.

source
Functors.CollectWalk — Type
CollectWalk()

A walk that recurses into a node x via Functors.children, storing the recursion history in a cache. The resulting ordered recursion history is returned.

See fcollect for more information.

source
Functors.AnonymousWalk — Type
AnonymousWalk(walk_fn)

Wrap a walk_fn so that AnonymousWalk(walk_fn) isa AbstractWalk. This type only exists for backwards compatability and should not be directly used. Attempting to wrap an existing AbstractWalk is a no-op (i.e. it is not wrapped).

source
Functors.IterateWalk — Type
IterateWalk()

A walk that walks all the Functors.children of trees (x, ys...) and concatenates the iterators of the children via Iterators.flatten. The resulting iterator is returned.

When used with fmap, the provided function f should return an iterator. For example, to iterate through the square of every scalar value:

julia> x = ([1, 2, 3], 4, (5, 6, [7, 8]));
 
 julia> make_iterator(x) = x isa AbstractVector ? x.^2 : (x^2,);
 
@@ -145,7 +145,7 @@
  (25, 16)
  (36, 9)
  (49, 4)
- (64, 1)
source
Functors.fmapstructure — Function
fmapstructure(f, x, ys...; [exclude, prune])

Like fmap, but doesn't preserve the type of custom structs. Instead, it returns a NamedTuple (or a Tuple, or an array), or a nested set of these.

Useful for when the output must not contain custom structs.

See also fmap and fmapstructure_with_path.

Examples

julia> struct Foo; x; y; end
+ (64, 1)
source
Functors.fmapstructure — Function
fmapstructure(f, x, ys...; [exclude, prune])

Like fmap, but doesn't preserve the type of custom structs. Instead, it returns a NamedTuple (or a Tuple, or an array), or a nested set of these.

Useful for when the output must not contain custom structs.

See also fmap and fmapstructure_with_path.

Examples

julia> struct Foo; x; y; end
 
 julia> @functor Foo
 
@@ -161,7 +161,7 @@
 6
 7
 8
-(x = nothing, y = Any[nothing, (nothing, nothing), (x = nothing, y = nothing)])
source
Functors.fmapstructure_with_path — Function
fmapstructure_with_path(f, x, ys...; [exclude, prune])

Like fmap_with_path, but doesn't preserve the type of custom structs. Instead, it returns a named tuple, a tuple, an array, a dict, or a nested set of these.

See also fmapstructure.

source
Functors.fcollect — Function
fcollect(x; exclude = v -> false)

Traverse x by recursing each child of x as defined by functor and collecting the results into a flat array, ordered by a breadth-first traversal of x, respecting the iteration order of children calls.

Doesn't recurse inside branches rooted at nodes v for which exclude(v) == true. In such cases, the root v is also excluded from the result. By default, exclude always yields false.

See also children.

Examples

julia> struct Foo; x; y; end
+(x = nothing, y = Any[nothing, (nothing, nothing), (x = nothing, y = nothing)])
source
Functors.fmapstructure_with_path — Function
fmapstructure_with_path(f, x, ys...; [exclude, prune])

Like fmap_with_path, but doesn't preserve the type of custom structs. Instead, it returns a named tuple, a tuple, an array, a dict, or a nested set of these.

See also fmapstructure.

source
Functors.fcollect — Function
fcollect(x; exclude = v -> false)

Traverse x by recursing each child of x as defined by functor and collecting the results into a flat array, ordered by a breadth-first traversal of x, respecting the iteration order of children calls.

Doesn't recurse inside branches rooted at nodes v for which exclude(v) == true. In such cases, the root v is also excluded from the result. By default, exclude always yields false.

See also children.

Examples

julia> struct Foo; x; y; end
 
 julia> @functor Foo
 
@@ -189,8 +189,8 @@
 julia> fcollect(m, exclude = v -> Functors.isleaf(v))
 2-element Vector{Any}:
  Foo(Bar([1, 2, 3]), TypeWithNoChildren(:a, :b))
- Bar([1, 2, 3])
source
Functors.KeyPath — Type
KeyPath(keys...)

A type for representing a path of keys to a value in a nested structure. Can be constructed with a sequence of keys, or by concatenating other KeyPaths. Keys can be of type Symbol, String, or Int.

Examples

julia> kp = KeyPath(:b, 3)
+ Bar([1, 2, 3])
source
Functors.KeyPath — Type
KeyPath(keys...)

A type for representing a path of keys to a value in a nested structure. Can be constructed with a sequence of keys, or by concatenating other KeyPaths. Keys can be of type Symbol, String, or Int.

Examples

julia> kp = KeyPath(:b, 3)
 KeyPath(:b, 3)
 
 julia> KeyPath(:a, kp, :c, 4)
-KeyPath(:a, :b, 3, :c, 4)
source
+KeyPath(:a, :b, 3, :c, 4)source diff --git a/previews/PR74/index.html b/previews/PR74/index.html index 46f1b55..6148425 100644 --- a/previews/PR74/index.html +++ b/previews/PR74/index.html @@ -29,4 +29,4 @@ Baz(1, 2) julia> fmap(float, model) -Baz(1.0, 2)

Any field not in the list will be passed through as-is during reconstruction. This is done by invoking the default constructor, so structs that define custom inner constructors are expected to provide one that acts like the default.

Appropriate Use

Not everything should be a functor!

Due to its generic nature it is very attractive to mark several structures as @functor when it may not be quite safe to do so.

Typically, since any function f is applied to the leaves of the tree, but it is possible for some functions to require dispatching on the specific type of the fields causing some methods to be missed entirely.

Examples of this include element types of arrays which typically have their own mathematical operations defined. Adding a @functor to such a type would end up missing methods such as +(::MyElementType, ::MyElementType). Think RGB from Colors.jl.

+Baz(1.0, 2)

Any field not in the list will be passed through as-is during reconstruction. This is done by invoking the default constructor, so structs that define custom inner constructors are expected to provide one that acts like the default.

Appropriate Use

Not everything should be a functor!

Due to its generic nature it is very attractive to mark several structures as @functor when it may not be quite safe to do so.

Typically, since any function f is applied to the leaves of the tree, but it is possible for some functions to require dispatching on the specific type of the fields causing some methods to be missed entirely.

Examples of this include element types of arrays which typically have their own mathematical operations defined. Adding a @functor to such a type would end up missing methods such as +(::MyElementType, ::MyElementType). Think RGB from Colors.jl.