Add examples for FilterX, QueryX and other Xes

CHANGELOG.md

@@ -44,7 +44,7 @@
 
 - Implements archetype graph for faster lookup on transitions (#104)
 - Optimizes query creation with 50% speedup (#144)
-- Optimize component operations with average 20% speedup (#146)
+- Optimizes component operations with average 20% speedup (#146)
 
 ### Bugfixes
 

ecs/examples_test.go

@@ -2,19 +2,6 @@ package ecs_test
 
 import "github.com/mlange-42/ark/ecs"
 
-type Position struct {
-	X, Y float64
-}
-
-type Velocity struct {
-	X, Y float64
-}
-
-type Grid struct {
-	Width  int
-	Height int
-}
-
 func NewGrid(width, height int) Grid {
 	return Grid{
 		Width:  width,
@@ -25,3 +12,108 @@ func NewGrid(width, height int) Grid {
 func (g *Grid) Get(x, y int) ecs.Entity {
 	return ecs.Entity{}
 }
+
+func ExampleFilter2() {
+	world := ecs.NewWorld()
+
+	// A simple filter for components (non-exclusive).
+	simpleFilter := ecs.NewFilter2[Position, Velocity](&world)
+
+	// A simple filter with an additional (unused) and an excluded component.
+	complexFilter := ecs.NewFilter2[Position, Velocity](&world).
+		With(ecs.C[Altitude]()).
+		Without(ecs.C[ChildOf]())
+
+	// A cached/registered filter, with an additional (unused) component.
+	cachedFilter := ecs.NewFilter2[Position, Velocity](&world).
+		With(ecs.C[Altitude]()).
+		Register()
+
+	// Create a query from a filter, and iterate it.
+	query := simpleFilter.Query()
+	for query.Next() {
+		// ...
+	}
+
+	_, _ = complexFilter, cachedFilter
+	// Output:
+}
+
+func ExampleQuery2() {
+	world := ecs.NewWorld()
+
+	// A simple filter.
+	filter := ecs.NewFilter2[Position, Velocity](&world)
+
+	// Create a fresh query before iterating.
+	query := filter.Query()
+	for query.Next() {
+		// Access components of the current entity.
+		pos, vel := query.Get()
+		// Access the current entity itself.
+		entity := query.Entity()
+		// ...
+		_, _, _ = pos, vel, entity
+	}
+	// Output:
+}
+
+func ExampleMap() {
+	world := ecs.NewWorld()
+
+	// Create a component mapper.
+	mapper := ecs.NewMap[Position](&world)
+
+	// Create an entity.
+	entity := mapper.NewEntity(&Position{X: 100, Y: 100})
+
+	// Remove component from the entity.
+	mapper.Remove(entity)
+	// Add component to the entity.
+	mapper.Add(entity, &Position{X: 100, Y: 100})
+	// Output:
+}
+
+func ExampleMap2() {
+	world := ecs.NewWorld()
+
+	// Create a component mapper.
+	mapper := ecs.NewMap2[Position, Velocity](&world)
+
+	// Create an entity.
+	entity := mapper.NewEntity(&Position{X: 100, Y: 100}, &Velocity{X: 1, Y: -1})
+
+	// Remove components from the entity.
+	mapper.Remove(entity)
+	// Add components to the entity.
+	mapper.Add(entity, &Position{X: 100, Y: 100}, &Velocity{X: 1, Y: -1})
+	// Output:
+}
+
+func ExampleExchange2() {
+	world := ecs.NewWorld()
+
+	// Create a component mapper.
+	mapper := ecs.NewMap[Altitude](&world)
+
+	// Create an exchange helper.
+	// Adds Position and Velocity, removes Altitude.
+	exchange := ecs.NewExchange2[Position, Velocity](&world).
+		Removes(ecs.C[Altitude]())
+
+	// Create an entity with an Altitude component.
+	entity := mapper.NewEntity(&Altitude{Z: 10_000})
+
+	// Remove Altitude and add Position and Velocity.
+	exchange.Exchange(entity, &Position{X: 100, Y: 100}, &Velocity{X: 1, Y: -1})
+
+	// Create another entity.
+	entity = mapper.NewEntity(&Altitude{Z: 10_000})
+
+	// Remove Altitude.
+	exchange.Remove(entity)
+
+	// Add Position and Velocity.
+	exchange.Add(entity, &Position{X: 100, Y: 100}, &Velocity{X: 1, Y: -1})
+	// Output:
+}

ecs/generate/exchange.go.template

@@ -20,6 +20,10 @@ import "unsafe"
 // to set components to be removed.
 //
 // Instances should be created during initialization and stored, e.g. in systems.
+{{- if ne . 2 }}
+//
+// See [Exchange2] for a usage example.
+{{- end}}
 type Exchange{{.}}{{$generics}} struct {
 	world     *World
 	ids       []ID

ecs/generate/filter.go.template

@@ -13,8 +13,13 @@ package ecs
 {{- end}}
 
 // Filter{{.}} is a filter for {{.}} components.
+// Used to create [Query{{.}}] iterators.
 //
 // Instances should be created during initialization and stored, e.g. in systems.
+{{- if ne . 2 }}
+//
+// See [Filter2] for a usage example.
+{{- end}}
 type Filter{{.}}{{$generics}} struct {
 	world         *World
 	ids           []ID

ecs/generate/maps.go.template

@@ -18,6 +18,10 @@ import "unsafe"
 // Map{{.}} is a mapper to access {{.}} components of an entity.
 //
 // Instances should be created during initialization and stored, e.g. in systems.
+{{- if ne . 2 }}
+//
+// See [Map2] for a usage example.
+{{- end}}
 type Map{{.}}{{$generics}} struct {
 	world    *World
 	ids      []ID

ecs/generate/query.go.template

@@ -25,9 +25,13 @@ type cursor struct {
 {{- end}}
 
 // Query{{.}} is a query for {{.}} components.
-// Use a [NewFilter{{.}}] to create one.
+// Use a [Filter{{.}}] to create one.
 //
 // Queries are one-time use iterators and must be re-created each time before iterating.
+{{- if ne . 2 }}
+//
+// See [Query2] for a usage example.
+{{- end}}
 type Query{{.}}{{$generics}} struct {
 	world      *World
 	filter     *filter