OpenTTD Game API
Public Types | Public Member Functions | Static Public Attributes
GSList Class Reference

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

Inheritance diagram for GSList:
GSBridgeList GSBridgeList_Length GSCargoList GSCargoList_IndustryAccepting GSCargoList_IndustryProducing GSCargoList_StationAccepting GSClientList GSClientList_Company GSDepotList GSEngineList GSIndustryList GSIndustryList_CargoAccepting GSIndustryList_CargoProducing GSIndustryTypeList GSRailTypeList GSSignList GSStationList GSStationList_Cargo GSStationList_Vehicle GSStoryPageElementList GSStoryPageList GSSubsidyList GSTileList GSTownEffectList GSTownList GSVehicleList GSVehicleList_Depot GSVehicleList_SharedOrders GSVehicleList_Station GSWaypointList GSWaypointList_Vehicle

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 (GSList *list)
 Add one list to another one. More...
 
void SwapList (GSList *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 (GSList *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 (GSList *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

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 GSList::AddItem ( int64  item,
int64  value 
)

Add a single item to the list.

Parameters
itemthe item to add. Should be unique, otherwise it is ignored.
valuethe value to assign.

◆ AddList()

void GSList::AddList ( GSList list)

Add one list to another one.

Parameters
listThe 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 GSList::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 GSList::Count ( )

Returns the amount of items in the list.

Returns
amount of items in the list.

◆ GetValue()

int64 GSList::GetValue ( int64  item)

Get the value that belongs to this item.

Parameters
itemthe item to get the value from
Returns
the value that belongs to this item.

◆ HasItem()

bool GSList::HasItem ( int64  item)

Check if an item is in the list.

Parameters
itemthe item to check for.
Returns
true if the item is in the list.

◆ IsEmpty()

bool GSList::IsEmpty ( )

Check if a list is empty.

Returns
true if the list is empty.

◆ IsEnd()

bool GSList::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 GSList::KeepAboveValue ( int64  value)

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

Parameters
valuethe value above which all items are kept.

◆ KeepBelowValue()

void GSList::KeepBelowValue ( int64  value)

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

Parameters
valuethe value below which all items are kept.

◆ KeepBetweenValue()

void GSList::KeepBetweenValue ( int64  start,
int64  end 
)

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

Parameters
startthe lower bound of the to be kept values (exclusive).
endthe upper bound of the to be kept values (exclusive).

◆ KeepBottom()

void GSList::KeepBottom ( int32  count)

Keep the last count items, i.e.

remove everything except the last count items.

Parameters
countthe amount of items to keep.

◆ KeepList()

void GSList::KeepList ( GSList list)

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

Parameters
listthe list of items to keep.
Precondition
list != NULL

◆ KeepTop()

void GSList::KeepTop ( int32  count)

Keep the first count items, i.e.

remove everything except the first count items.

Parameters
countthe amount of items to keep.

◆ KeepValue()

void GSList::KeepValue ( int64  value)

Keep all items with this value.

Parameters
valuethe value to keep.

◆ Next()

int64 GSList::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 GSList::RemoveAboveValue ( int64  value)

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

Parameters
valuethe value above which all items are removed.

◆ RemoveBelowValue()

void GSList::RemoveBelowValue ( int64  value)

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

Parameters
valuethe value below which all items are removed.

◆ RemoveBetweenValue()

void GSList::RemoveBetweenValue ( int64  start,
int64  end 
)

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

Parameters
startthe lower bound of the to be removed values (exclusive).
endthe upper bound of the to be removed values (exclusive).

◆ RemoveBottom()

void GSList::RemoveBottom ( int32  count)

Remove the last count items.

Parameters
countthe amount of items to remove.

◆ RemoveItem()

void GSList::RemoveItem ( int64  item)

Remove a single item from the list.

Parameters
itemthe item to remove. If not existing, it is ignored.

◆ RemoveList()

void GSList::RemoveList ( GSList list)

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

Parameters
listthe list of items to remove.
Precondition
list != NULL

◆ RemoveTop()

void GSList::RemoveTop ( int32  count)

Remove the first count items.

Parameters
countthe amount of items to remove.

◆ RemoveValue()

void GSList::RemoveValue ( int64  value)

Remove all items with this value.

Parameters
valuethe value to remove.

◆ SetValue()

bool GSList::SetValue ( int64  item,
int64  value 
)

Set a value of an item directly.

Parameters
itemthe item to set the value for.
valuethe 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 GSList::Sort ( SorterType  sorter,
bool  ascending 
)

Sort this list by the given sorter and direction.

Parameters
sorterthe type of sorter to use
ascendingif 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 GSList::SwapList ( GSList list)

Swap the contents of two lists.

Parameters
listThe list that will be swapped with.

◆ Valuate()

void GSList::Valuate ( void *  valuator_function,
int  params,
  ... 
)

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

Parameters
valuator_functionThe function which will be doing the valuation.
paramsThe 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(GSBridge.GetPrice, 5); list.Valuate(GSBridge.GetMaxLength); function MyVal(bridge_id, myparam) { return myparam * bridge_id; // This is silly } list.Valuate(MyVal, 12);