Struct: `TQuery`

template <class... T>
struct TQuery;

Systems world query iterator.

Allows to iterate over actors and their components that comply to requested types signature.

More about iterators in this architecture book page.

Note

User should rather construct queries with USystemsWorld::Query instead o constructing queries by hand.

Returned query iterator has always put actor as first item of item tuple and then follow requested components. So Systems->Query<A, B, C>() iterator will yield given tuple TTuple<AActor*, A*, B*, C*>

Example

	const auto Count = static_cast<int>(Systems.Query<UBoidComponent>().Count());
	const auto Difference = Count - EXPECTED_POPULATION_NUMBER;

	if (Difference > 0)
	{
		for (auto& QueryItem : Systems.Query<UBoidComponent>().Take(Difference))
		{
			auto* Actor = QueryItem.Get<0>();
			Actor->Destroy();
		}
	}

Methods

`Adapt`

public:
template <typename ADAPTER>
TIterAdapt<Self, ADAPTER> Adapt(
    ADAPTER Adapter
);

Injects custom iterator adapter into the chain of iteration.

Useful only for really custom/advanced solutions that cannot be solved with regular iterators.

Note

ADAPTER should implement iterator adapter methods. Yielded values share same type wit iterator that wraps this adapter.

Example

// [1, 3, 5, 7, 9]
const TArray<int> Result = IterRange(0, 10).Adapt(TIterOddAdapter<int>()).CollectArray();

template <typename T>
struct TIterOddAdapter
{
public:
	template <typename I>
	TOptional<T> Next(I& Iter)
	{
		Iter.Next();
		return Iter.Next();
	}

	template <typename I>
	IterSizeHint SizeHint(const I& Iter) const
	{
		return Iter.SizeHint();
	}
};

Arguments

Adapter
```
ADAPTER Adapter
```

All
```
public:
template <typename FUNCTOR>
bool All(
    FUNCTOR Func
);
```
Checks if all values yielded by this iterator passes predicate.

Note

FUNCTOR should comply to given function signature: bool(I::Item Value) where Value holds current value yielded by iterator.

Example
```
// false
const bool Result = IterRange(0, 10).All([](const auto& Value) { return Value > 5; });
```
Arguments
- Func
```
FUNCTOR Func
```
Any
```
public:
template <typename FUNCTOR>
bool Any(
    FUNCTOR Func
);
```
Checks if any value yielded by this iterator passes predicate.

Note

FUNCTOR should comply to given function signature: bool(I::Item Value) where Value holds current value yielded by iterator.

Example
```
// true
const bool Result = IterRange(0, 10).Any([](const auto& Value) { return Value > 5; });
```
Arguments
- Func
```
FUNCTOR Func
```
Cast
```
public:
template <typename RESULT>
TIterCast<typename RESULT, Self> Cast();
```
Casts yielded values to another type.

Commonly used as a shourtcut for mapping between types using target type constructor.

Note

RESULT is type that this iterator will yield after casting.

Example
```
// [0.0, 1.0, 2.0, 3.0, 4.0]
const TArray<float> Result = IterRange(0, 5).Cast<float>().CollectArray();
```
Chain
```
public:
template <typename ITER>
TIterChain<Self, ITER> Chain(
    ITER&& Iter
);
```
Appends another iterator at the end of this iterator.

Useful for combining results of different iterators that yield same value type.

Note

ITER should implement iterator methods. Yielded values share same type with this iterato value type.

Example
```
// [0, 1, 2, 3, 4, -5, -4, -3, -2, -1]
const TArray<int> Result = IterRange(0, 5).Chain(IterRange(-5, 0)).CollectArray();
```
Arguments
- Iter
```
ITER&& Iter
```

`CollectArray`

public:
TArray<Item> CollectArray();

Consumes iterator and returns an array with its values.

Example

const TArray<int> Result = IterRange(0, 10).CollectArray();

`CollectIntoArray`

public:
void CollectIntoArray(
    TArray<Item>& Result
);

Consumes iterator and stores its values into provided array.

Example

TArray<int> Result();
IterRange(0, 10).CollectIntoArray(Result);

Arguments

Result
```
TArray<Item>& Result
```

`CollectIntoSet`

public:
void CollectIntoSet(
    TSet<Item>& Result
);

Consumes iterator and stores its values into provided set.

Example

TSet<int> Result();
IterRange(0, 10).CollectIntoSet(Result);

Arguments

Result
```
TSet<Item>& Result
```

`CollectSet`

public:
TSet<Item> CollectSet();

Consumes iterator and returns a set with its values.

Example

const TArray<int> Result = IterRange(0, 10).CollectArray();

ComparedBy
```
public:
template <typename FUNCTOR>
TOptional<Item> ComparedBy(
    FUNCTOR Func
);
```
Finds iterator value that compared to other items gets greater "score".

Headline is rather vague, but what it actually does is user can do finding min/max value with this iterator consumer.

Note

FUNCTOR should comply to given function signature: bool(I::Item A, I::Item B) where A holds current value yielded by iterator and B is the one that has best "score" so far.

Example
```
// 42
const int Result = IterRange(0, 42).ComparedBy([](const auto A, const auto B) { return A > B; });
```
Arguments
- Func
```
FUNCTOR Func
```

`Count`

public:
uint32 Count();

Returns exact number of items that iterator can yield.

Example

// 10
const uint32 Result = IterRange(0, 10).Count();

Enumerate
```
public:
TIterEnumerate<Self> Enumerate();
```
Enumerates values in this iterator.

Useful for reading index of element/iteration.

Note

Yielded values have type: TTuple<uint32, Item>, which means this iterator yields tuple o index-value pair.

Example
```
// [0, 1, 2, 3, 4]
const TArray<int> Result =
	IterRepeat(42).Enumerate().Map<int>([](const auto& Pair) { return Pair.Get<0>(); }).Take(5).CollectArray();
```

`Filter`

public:
template <typename FUNCTOR>
TIterFilter<Self, typename FUNCTOR> Filter(
    FUNCTOR Func
);

Filters values in the iterator by predicate.

Note

FUNCTOR should comply to this function signature: bool(const I::Item& Value).

Example

// [0, 2, 4, 6, 8]
const TArray<int> Result = IterRange(0, 10).Filter([](const auto& Value) { return Value % 2 == 0; }).CollectArray();

Arguments

Func
```
FUNCTOR Func
```

`FilterMap`

public:
template <typename RESULT, typename FUNCTOR>
TIterFilterMap<typename RESULT, Self, typename FUNCTOR> FilterMap(
    FUNCTOR Func
);

Filters values in the iterator by predicate and maps them to another type.

Note

RESULT is a type of values yielded by this iterator that maps into. FUNCTOR should comply to this function signature: TOptional<RESULT>(const I::Item& Value) Returning some value means pasing it to next iterator, returning none means we omit thi value.

Example

// [0.0, 2.0, 4.0, 6.0, 8.0]
const TArray<float> I = IterRange(0, 10)
							.FilterMap<float>(
								[](const auto& Value)
								{
									if (Value % 2 == 0)
									{
										return TOptional<float>(static_cast<float>(Value));
									}
									else
									{
										return TOptional<float>();
									}
								})
							.CollectArray();

Arguments

Func
```
FUNCTOR Func
```

Find
```
public:
template <typename FUNCTOR>
TOptional<Item> Find(
    FUNCTOR Func
);
```
Finds and returns value in this iterator that passes FUNCTOR predicate.

Note

FUNCTOR should comply to given function signature: bool(I::Item Value) where Value holds current value yielded by iterator.

Example
```
// 5
const TOptional<int> Result = IterRange(0, 10).Find([](const auto& Value) { return Value >= 5; });
```
Arguments
- Func
```
FUNCTOR Func
```
FindMap
```
public:
template <typename RESULT, typename FUNCTOR>
TOptional<RESULT> FindMap(
    FUNCTOR Func
);
```
Finds and returns value in this iterator that passes FUNCTOR predicate, mapped to another type.

Note

FUNCTOR should comply to given function signature: TOptional<Item>(I::Item Value) where Value holds current value yielded by iterator. RESULT is the returned type and use should always return TOptional<RESULT> in the predicate where some value means "found" an none means "not found".

Example
```
// 5.0
const TOptional<float> Result = IterRange(0, 10).FindMap<float>(
	[](const auto& Value)
	{
		if (Value >= 5)
		{
			return TOptional<float>(static_cast<float>(Value));
		}
		else
		{
			return TOptional<float>();
		}
	});
```
Arguments
- Func
```
FUNCTOR Func
```
First
```
public:
TOptional<Item> First();
```
Returns first item in the iterator.

This is an equivalent of calling TQuery::Next.

Example
```
// 5
const int Result = IterRange(5, 10).First();
```
Flatten
```
public:
template <typename RESULT>
TIterFlatten<typename RESULT, Self> Flatten();
```
Flattens nested iterators.

Imagine you have an iterator that yields another iterators, such as arrays of arrays.

Note

RESULT is a type of values yielded by this iterator - it should be the same as nested iterator value type (c++ won't accept that syntax, hence we have to provide a RESULT type and ensure it's the same), FUNCTOR should comply to this function signature: RESULT(const I::Item& Value).

Example
```
// [0, 1, 2, 3, 4, 0, 1, 2, 3, 4]
const TArray<int> P =
	IterGenerate<TIterRange<int>>([]() { return IterRange(0, 5); }).Take(2).Flatten<int>().CollectArray();
```
Fold
```
public:
template <typename FUNCTOR>
Item Fold(
    Item Start,
    FUNCTOR Func
);
```
Folds iterator into single value.

Folding basically means going through all iterator items and collapsing them into single value. Example of folding can be sum/accumulation, or min/max, or anything like that - although for ones mentioned there are existing optimized iterator consumers: TQuery::Sum and TQuery::ComparedBy.

Note

RESULT is the returned type, same as Start argument used as initial accumulator. FUNCTOR should comply to given function signature: Item(Item Accumulator, I::Item Value) where Accumulator argument holds result of previous iteration, and Value holds curren value yielded by iterator. Start argument holds value passed to first iteratio Accumulator.

Example
```
// 45
const int Result = IterRange(0, 10).Fold(0, [](const auto& Accum, const auto& Value) { return Accum + Value; });
```
Arguments
- Start
```
Item Start
```
- Func
```
FUNCTOR Func
```

`ForEach`

public:
template <typename FUNCTOR>
void ForEach(
    FUNCTOR Func
);

Consumes iterator and yields its values for user to process.

This is equivalent of:

auto Iter = IterRange(0, 9);
while (const auto Value = Iter.Next())
{
	const auto Squared = Value * Value;
	UE_LOG(LogTemp, Warning, TEXT("Squared value: %i"), Squared);
}

Note

FUNCTOR should comply to given function signature: void(I::Item Value) where Value holds current value yielded by iterator.

Example

for (const auto Value : IterRange(0, 9))
{
	const auto Squared = Value * Value;
	UE_LOG(LogTemp, Warning, TEXT("Squared value: %i"), Squared);
}

Arguments

Func
```
FUNCTOR Func
```

`Inspect`

public:
template <typename FUNCTOR>
TIterInspect<Self, typename FUNCTOR> Inspect(
    FUNCTOR Func
);

Inspects yielded values.

Useful when debugging iterators to for example log what values are yielded at which iterator chain stage.

Note

FUNCTOR should comply to this function signature: void(const I::Item& Value).

Example

// [0, 2, 4, 6, 8]
const TArray<int> Result = IterRange(0, 10)
							   .Inspect(
								   [](const auto& Value)
								   {
									   // Prints values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9.
									   UE_LOG(LogTemp, Warning, TEXT("Inspected item before: %i"), Value);
								   })
							   .Filter([](const auto& Value) { return Value % 2 == 0; })
							   .Inspect(
								   [](const auto& Value)
								   {
									   // Prints values: 0, 2, 4, 6, 8.
									   UE_LOG(LogTemp, Warning, TEXT("Inspected item after: %i"), Value);
								   })
							   .CollectArray();

Arguments

Func
```
FUNCTOR Func
```

`Last`

public:
TOptional<Item> Last();

Returns last item in the iterator.

Example

// 4
const int Result = IterRange(0, 4).Last();

`Map`

public:
template <typename RESULT, typename FUNCTOR>
TIterMap<typename RESULT, Self, typename FUNCTOR> Map(
    FUNCTOR Func
);

Maps yielded values to another type.

Commonly used for data transformations for use in later stages of iteration.

Note

RESULT is type that this iterator will yield after data transformations. FUNCTOR should comply to this function signature: RESULT(const I::Item& Value).

Example

// [0.0, 4.0, 16.0, 36.0, 64.0]
const TArray<float> Result = IterRange(0, 10)
								 .Filter([](const auto& Value) { return Value % 2 == 0; })
								 .Map<float>([](const auto& Value) { return static_cast<float>(Value * Value); })
								 .CollectArray();

Arguments

Func
```
FUNCTOR Func
```

`Next`

public:
TOptional<Item> Next();

Yields tuple to next actors component set.

Usually user would rather want to use iterator methods for ergonomic iteration over the query, but in case user has valid reasons to handle iteration different way, this is the single point that performs iteration and yields an item.

Example

	auto Query = Systems.Query<UShiaComponent>();
	while (auto& QueryItem = Query.Next())
	{
		// Note that we do not check if QueryItem optional value is set.
		// `while` loop perform these checks for us, hence we use it
		// instead of standard `for` loop.
		auto* Actor = QueryItem.GetValue().Get<0>();
		auto* Shia = QueryItem.GetValue().Get<1>();

		Shia->JustDoIt(Actor);
	}

`Nth`

public:
TOptional<Item> Nth(
    uint32 Index
);

Returns Nth item in the iterator.

Example

// 5
const TOptional<int> Result = IterRange(0, 10).Nth(5);

Arguments

Index
```
uint32 Index
```

`SizeHint`

public:
IterSizeHint SizeHint() const;

Gets hint about minimum and optional maximum items count this iterator can yield.

Used internally by lazy-iterators, but in case user would like to implement their own iterators, or iterator consumers, or just wants to preallocate some memory for later consumed iterator items, this method is really useful for these usecases.

See IterSizeHint.

Example

template <typename I>
void IterCollectIntoArray(I&& Iterator, TArray<typename I::Item>& Result)
{
	const auto SizeHint = Iterator.SizeHint();
	const auto Capacity = SizeHint.Maximum.IsSet() ? SizeHint.Maximum.GetValue() : SizeHint.Minimum;
	Result.Reserve(Result.Num() + Capacity);
	while (auto QueryItem = Iterator.Next())
	{
		Result.Add(QueryItem.GetValue());
	}
}

Skip
```
public:
TIterSkip<Self> Skip(
    uint32 Count
);
```
Skips iteration by number of elements.

It's worth noting that this is one-shot skip, not repeated one, which means if we yield iterator of 10 elements and we skip 2 iterations, then it will skip just 2 values and yield rest 8.

Example
```
// [3, 4, 5, 6, 7]
const TArray<int> Result = IterRange(0, 10).Skip(3).Take(5).CollectArray();
```
Arguments
- Count
```
uint32 Count
```
Sum
```
public:
Item Sum(
    Item InitialValue
);
```
Returns sum of values that iterator can yield.

Note

Make sure that type of iterator values actually implement operator+! Also since iterator can work on non-numerical types, user has to provide initial value, tha makes it work like TQuery::Fold.

Example
```
// 45
const int Return = IterRange(0, 10).Sum(0);
```
This is equivalent of:
```
// 45
const int Result = IterRange(0, 10).Fold(0, [](const auto& Accum, const auto& Value) { return Accum + Value; });
```
Arguments
- InitialValue
```
Item InitialValue
```
TQuery
```
public:
TQuery(
    USystemsWorld* Systems
);
```
Constructs query from systems.

An equivalent of calling USystemsWorld::Query

Arguments
- Systems
```
USystemsWorld* Systems
```
  Pointer to systems world of which actor components user wants to iterate on.
Take
```
public:
TIterTake<Self> Take(
    uint32 Count
);
```
Limits iterator to at most number of iterations.

If we create an iterator that yields 10 values and we tell it to take 5, then it will stop iterating after next 5 values (or less, depends if there is enough values left in iterator).

Example
```
// [3, 4, 5, 6, 7]
const TArray<int> Result = IterRange(0, 10).Skip(3).Take(5).CollectArray();
```
Arguments
- Count
```
uint32 Count
```

`Views`

public:
template <uint32 COUNT>
TIterViews<Self, COUNT> Views();

Yields sequences of consecutive views over set of values.

If we create an iterator that yields 5 integer values and we tell it to view 2 at the same time, then it will yield TArrayView with values: [0, 1], [1, 2], [2, 3], [3, 4].

Example

// [(0, 1), (1, 2), (2, 3), (3, 4)]
const TArray<TTuple<int, int>> Result =
	IterRange(0, 5)
		.Views<2>()
		.Map<TTuple<int, int>>([](const auto& View) { return MakeTuple(View[0], View[1]); })
		.CollectArray();

`Zip`

public:
template <typename ITER>
TIterZip<Self, ITER> Zip(
    ITER&& Iter
);

Combines two iterators to make one that yields pair of both iterator values at the same time.

Example

// [(0, -5), (1, -4), (2, -3), (3, -2), (4, -1)]
const TArray<TTuple<int, int>> Result = IterRange(0, 5).Zip(IterRange(-5, 0)).CollectArray();

Arguments

Iter
```
ITER&& Iter
```

`begin`

public:
TStlIterator<Self> begin();

Allows this iterator to be used in for-in loop.

Example

// 0
// 1
// 2
// 3
// 4
for (auto Value : IterRange(0, 5))
{
	UE_LOG(LogTemp, Info, TEXT("%i"), Value);
}

`end`

public:
TStlIterator<Self> end();

Allows this iterator to be used in for-in loop.

Example

// 0
// 1
// 2
// 3
// 4
for (auto Value : IterRange(0, 5))
{
	UE_LOG(LogTemp, Info, TEXT("%i"), Value);
}

Documentation built with Unreal-Doc v1.0.8 tool by PsichiX

Systems - Modular and scalable game architecture for orthogonal game logic