OpenTTD AI API: AIList Class Reference

OpenTTD AI API 13.0-beta2

Public Types | Public Member Functions | Static Public Attributes
AIList Class Reference

Class that creates a list which can keep item/value pairs, which you can walk. More...

Inheritance diagram for AIList:

## Public Types
enum | SorterType { SORT_BY_VALUE, SORT_BY_ITEM }
| Type of sorter. More...

## Public Member Functions
void | AddItem (int64 item, int64 value)
| Add a single item to the list. More...
void | RemoveItem (int64 item)
| Remove a single item from the list. More...
void | Clear ()
| Clear the list, making Count() returning 0 and IsEmpty() returning true.
bool | HasItem (int64 item)
| Check if an item is in the list. More...
int64 | Begin ()
| Go to the beginning of the list and return the item. More...
int64 | Next ()
| Go to the next item in the list and return the item. More...
bool | IsEmpty ()
| Check if a list is empty. More...
bool | IsEnd ()
| Check if there is a element left. More...
int32 | Count ()
| Returns the amount of items in the list. More...
int64 | GetValue (int64 item)
| Get the value that belongs to this item. More...
bool | SetValue (int64 item, int64 value)
| Set a value of an item directly. More...
void | Sort (SorterType sorter, bool ascending)
| Sort this list by the given sorter and direction. More...
void | AddList (AIList *list)
| Add one list to another one. More...
void | SwapList (AIList *list)
| Swap the contents of two lists. More...
void | RemoveAboveValue (int64 value)
| Removes all items with a higher value than 'value'. More...
void | RemoveBelowValue (int64 value)
| Removes all items with a lower value than 'value'. More...
void | RemoveBetweenValue (int64 start, int64 end)
| Removes all items with a value above start and below end. More...
void | RemoveValue (int64 value)
| Remove all items with this value. More...
void | RemoveTop (int32 count)
| Remove the first count items. More...
void | RemoveBottom (int32 count)
| Remove the last count items. More...
void | RemoveList (AIList *list)
| Remove everything that is in the given list from this list (same item index that is). More...
void | KeepAboveValue (int64 value)
| Keep all items with a higher value than 'value'. More...
void | KeepBelowValue (int64 value)
| Keep all items with a lower value than 'value'. More...
void | KeepBetweenValue (int64 start, int64 end)
| Keep all items with a value above start and below end. More...
void | KeepValue (int64 value)
| Keep all items with this value. More...
void | KeepTop (int32 count)
| Keep the first count items, i.e. More...
void | KeepBottom (int32 count)
| Keep the last count items, i.e. More...
void | KeepList (AIList *list)
| Keeps everything that is in the given list from this list (same item index that is). More...
void | Valuate (void *valuator_function, int params,...)
| Give all items a value defined by the valuator you give. More...

## Static Public Attributes
static const bool | SORT_ASCENDING = true
| Sort ascending.
static const bool | SORT_DESCENDING = false
| Sort descending.

## Detailed Description

Class that creates a list which can keep item/value pairs, which you can walk.

## Member Enumeration Documentation

## ◆ SorterType

enum AIList::SorterType

Type of sorter.

Enumerator
SORT_BY_VALUE | Sort the list based on the value of the item.
SORT_BY_ITEM | Sort the list based on the item itself.

## Member Function Documentation

## ◆ AddItem()

void AIList::AddItem | ( | int64 | item,
|  | int64 | value
| ) |  |

Add a single item to the list.

Parameters

  item | the item to add. Should be unique, otherwise it is ignored.
  value | the value to assign.

## ◆ AddList()

void AIList::AddList | ( | AIList * | list | ) |

Add one list to another one.

Parameters

  list | The list that will be added to the caller.

Postcondition
  The list to be added ('list') stays unmodified.

Note
  All added items keep their value as it was in 'list'.
  If the item already exists inside the caller, the value of the list that is added is set on the item.

## ◆ Begin()

int64 AIList::Begin | ( |  | ) |

Go to the beginning of the list and return the item.

To get the value use list.GetValue(list.Begin()).

Returns
  the first item.

Note
  returns 0 if beyond end-of-list. Use IsEnd() to check for end-of-list.

## ◆ Count()

int32 AIList::Count | ( |  | ) |

Returns the amount of items in the list.

Returns
  amount of items in the list.

## ◆ GetValue()

int64 AIList::GetValue | ( | int64 | item | ) |

Get the value that belongs to this item.

Parameters

  item | the item to get the value from

Returns
  the value that belongs to this item.

## ◆ HasItem()

bool AIList::HasItem | ( | int64 | item | ) |

Check if an item is in the list.

Parameters

  item | the item to check for.

Returns
  true if the item is in the list.

## ◆ IsEmpty()

bool AIList::IsEmpty | ( |  | ) |

Check if a list is empty.

Returns
  true if the list is empty.

## ◆ IsEnd()

bool AIList::IsEnd | ( |  | ) |

Check if there is a element left.

In other words, if this is false, the last call to Begin() or Next() returned a valid item.

Returns
  true if the current item is beyond end-of-list.

## ◆ KeepAboveValue()

void AIList::KeepAboveValue | ( | int64 | value | ) |

Keep all items with a higher value than 'value'.

Parameters

  value | the value above which all items are kept.

## ◆ KeepBelowValue()

void AIList::KeepBelowValue | ( | int64 | value | ) |

Keep all items with a lower value than 'value'.

Parameters

  value | the value below which all items are kept.

## ◆ KeepBetweenValue()

void AIList::KeepBetweenValue | ( | int64 | start,
|  | int64 | end
| ) |  |

Keep all items with a value above start and below end.

Parameters

  start | the lower bound of the to be kept values (exclusive).
  end | the upper bound of the to be kept values (exclusive).

## ◆ KeepBottom()

void AIList::KeepBottom | ( | int32 | count | ) |

Keep the last count items, i.e.

remove everything except the last count items.

Parameters

  count | the amount of items to keep.

## ◆ KeepList()

void AIList::KeepList | ( | AIList * | list | ) |

Keeps everything that is in the given list from this list (same item index that is).

Parameters

  list | the list of items to keep.

Precondition
  list != nullptr

## ◆ KeepTop()

void AIList::KeepTop | ( | int32 | count | ) |

Keep the first count items, i.e.

remove everything except the first count items.

Parameters

  count | the amount of items to keep.

## ◆ KeepValue()

void AIList::KeepValue | ( | int64 | value | ) |

Keep all items with this value.

Parameters

  value | the value to keep.

## ◆ Next()

int64 AIList::Next | ( |  | ) |

Go to the next item in the list and return the item.

To get the value use list.GetValue(list.Next()).

Returns
  the next item.

Note
  returns 0 if beyond end-of-list. Use IsEnd() to check for end-of-list.

## ◆ RemoveAboveValue()

void AIList::RemoveAboveValue | ( | int64 | value | ) |

Removes all items with a higher value than 'value'.

Parameters

  value | the value above which all items are removed.

## ◆ RemoveBelowValue()

void AIList::RemoveBelowValue | ( | int64 | value | ) |

Removes all items with a lower value than 'value'.

Parameters

  value | the value below which all items are removed.

## ◆ RemoveBetweenValue()

void AIList::RemoveBetweenValue | ( | int64 | start,
|  | int64 | end
| ) |  |

Removes all items with a value above start and below end.

Parameters

  start | the lower bound of the to be removed values (exclusive).
  end | the upper bound of the to be removed values (exclusive).

## ◆ RemoveBottom()

void AIList::RemoveBottom | ( | int32 | count | ) |

Remove the last count items.

Parameters

  count | the amount of items to remove.

## ◆ RemoveItem()

void AIList::RemoveItem | ( | int64 | item | ) |

Remove a single item from the list.

Parameters

  item | the item to remove. If not existing, it is ignored.

## ◆ RemoveList()

void AIList::RemoveList | ( | AIList * | list | ) |

Remove everything that is in the given list from this list (same item index that is).

Parameters

  list | the list of items to remove.

Precondition
  list != nullptr

## ◆ RemoveTop()

void AIList::RemoveTop | ( | int32 | count | ) |

Remove the first count items.

Parameters

  count | the amount of items to remove.

## ◆ RemoveValue()

void AIList::RemoveValue | ( | int64 | value | ) |

Remove all items with this value.

Parameters

  value | the value to remove.

## ◆ SetValue()

bool AIList::SetValue | ( | int64 | item,
|  | int64 | value
| ) |  |

Set a value of an item directly.

Parameters

  item | the item to set the value for.
  value | the value to give to the item

Returns
  true if we could set the item to value, false otherwise.

Note
  Changing values of items while looping through a list might cause entries to be skipped. Be very careful with such operations.

## ◆ Sort()

void AIList::Sort | ( | SorterType | sorter,
|  | bool | ascending
| ) |  |

Sort this list by the given sorter and direction.

Parameters

  sorter | the type of sorter to use
  ascending | if true, lowest value is on top, else at bottom.

Note
  the current item stays at the same place.

See also
  SORT_ASCENDING SORT_DESCENDING

## ◆ SwapList()

void AIList::SwapList | ( | AIList * | list | ) |

Swap the contents of two lists.

Parameters

  list | The list that will be swapped with.

## ◆ Valuate()

void AIList::Valuate | ( | void * | valuator_function,
|  | int | params,
|  |  | ...
| ) |  |

Give all items a value defined by the valuator you give.

Parameters

  valuator_function | The function which will be doing the valuation.
  params | The params to give to the valuators (minus the first param, which is always the index-value we are valuating).

Note
  You may not add, remove or change (setting the value of) items while valuating. You may also not (re)sort while valuating.
  You can write your own valuators and use them. Just remember that the first parameter should be the index-value, and it should return an integer.
  Example: list.Valuate(AIBridge.GetPrice, 5); list.Valuate(AIBridge.GetMaxLength); function MyVal(bridge_id, myparam) { return myparam * bridge_id; // This is silly } list.Valuate(MyVal, 12);