API Reference

@swizzle v.xyz
@swizzle v.rgb
@swizzle T v.xyz
@swizzle v[].some.expression().xyz
@swizzle v.xyz = [1, 2, 3]
@swizzle v.rgb = @swizzle v.bgr
@swizzle begin
  a.yz = b.xz
  b.w = a.x
end

Perform a swizzling operation, extracting components or, if an assignment is provided, mutating them.

This macro translates x.<field1><field2>...<fieldn> field access syntax (e.g. x.xwyz) in the provided expression into an appropriate call to swizzle (non-mutating) or swizzle! (mutating).

An additional type argument T may be provided to put the result of a non-mutating swizzle extraction into a specific type (see the documentation for swizzle for more details). It has no effect on mutating swizzles.

Each letter on the right-hand side of any . is considered as a separate component name, and is by default mapped to:

• x or r -> first component
• y or g -> second component
• z or b -> third component
• w or a -> fourth component

using nomenclature from geometry processing ([x, y, z, w] representing spatial coordinates) and computer graphics ([r, g, b, a] representing color vectors).

This mapping may be customized from Julia 1.11 onwards (see extended help).

Extended help

From Julia 1.11 onwards, scoped values allow the customization of this component mapping, via @with Swizzles.component_names => Dict(...). For example, if you wanted to consider width, height and depth as first, second and third components, you may do

new_names = Dict('w' => 1, 'h' => 2, 'd' => 3)

# You might also have done `@with Swizzles.component_names[] => new_names`
# to discard existing names.
@with Swizzles.component_names => merge(Swizzles.component_names[], new_names) begin
  # Note: the `@eval` is important here.
  # It prevents `@swizzle` from being executed before the scoped value is set.
  @eval begin
    @swizzle [10, 20, 30].w
    @swizzle [10, 20, 30].whd
  end
  # `@swizzle` macrocalls in `include`d files will also be affected.
  include("file.jl")
end

For convenience, you could even define your own @swizzle macro shadowing the one exported by this package as

using Swizzles

macro _swizzle(ex)
  new_names = Dict('w' => 1, 'h' => 2, 'd' => 3)
  swizzle_ex = @with Swizzles.component_names => merge(Swizzles.component_names[], new_names) begin
    # One might also pass around a `T` parameter as second argument.
    Swizzles.generate_swizzle_expr(ex)
  end
  esc(swizzle_ex)
end

@_swizzle [10, 20, 30].hd

Whether or not this is a good idea is for you to decide.

swizzle(v, indices...)
swizzle(T, v, indices...)

Create a new object made up of v[i₁], v[i₂], ... where indices = (i₁, i₂, ...). If a type is provided as first argument, the result will be wrapped into it via construct_swizzle.

A default type is derived from swizzle(v, indices...), where a single index infers T = eltype(v), and multiple indices infer T = typeof(v). For statically sized vectors (StaticVector and SizedVector), an extension extends StaticArraysCore vectors such that one of correct size is used to hold the result.

See also: swizzle!

swizzle!(v, value, indices...)

Mutate v at indices such that v[i₁] = value[1], v[i₂] = value[2], ... where indices = (i₁, i₂, ...). and return value.

If any indices are duplicated in indices, v will be consecutively overwritten at the corresponding index, retaining the last value per the semantics of setindex!.

construct_swizzle(T, args)

Wrap the result of a swizzling operation into T(args...).

This method may be extended for your own types, e.g. if a different constructor must be used.

See also: swizzle