Array functions

Functions

array_key 

mixed array_key(int arrayID, int index)

Don’t use it directly; it is generated by the compiler in foreach loops.

  • for lists, returns index back (no change).
  • for maps, returns a key at the specified numeric index (don’t rely on the order in which keys are stored though).
  • can be checked if given array is associative or not, by using index (-1): 0 - array is list, 1 - array is map.

arrayexpr 

int arrayexpr(mixed key, mixed value)

Don’t use it directly; it is used by compiler to create array expressions.

  • assigns value to a given key in an array, created by last create_array or temp_array call.
  • always returns 0.

create_array 

int create_array(int size, int nothing)

Creates permanent array (but not “saved”).

  • if size >= 0, creates list with given size.
  • if size == -1, creates map (associative array).
  • if size == -1 and flags == 2, creates a “lookup” map (associative array) in which the values of existing keys are read-only and can’t be updated. This type of array allows you to store a zero (0) key value.
  • returns array ID (valid until array is deleted).

fix_array 

void fix_array(int arrayID)

Changes “temporary” array into “permanent” (“permanent” arrays are not automatically saved into savegames).

free_array 

void free_array(int arrayID)

Deletes any array.

  • if array was “saved”, it will be removed from a savegame.

get_array 

mixed get_array(int arrayID, mixed key)

Returns array value by key or index (shorthand: arrayID[key]).

  • if key doesn’t exist or index is not in valid range, returns 0.

len_array 

int len_array(int arrayID)

Returns number of elements or key=>value pairs in a given array.

  • if array is not found, returns -1 (can be used to check if given array exist).

load_array 

int load_array(mixed key)

Loads array from savegame data by the same key provided in save_array.

  • returns array ID or zero (0) if none found.

resize_array 

void resize_array(int arrayID, int size)

Changes array size. - applicable to maps too, but only to reduce elements. - there are number of special negative values of “size” which perform various operations on the array, use macros sort_array, sort_array_reverse, reverse_array, shuffle_array from sfall.h header.

save_array 

void save_array(mixed key, int arrayID)

Makes the array saveable; it will be saved in sfallgv.sav file when saving the game.

  • array ID is associated with given “key”.
  • array becomes permanent (if it was temporary) and “saved”.
  • key can be of any type (int, float or string).
  • if you specify 0 as the key for the array ID, it will make the array “unsaved”.

scan_array 

mixed scan_array(int arrayID, mixed value)

Searches for a first occurence of given value inside given array.

  • if value is found, returns its index (for lists) or key (for maps).
  • if value is not found, returns -1 (be careful, as -1 can be a valid key for a map).

set_array 

void set_array(int arrayID, mixed key, mixed value)

Sets array value (shorthand: arrayID[key] := value).

  • if used on list, “key” must be numeric and within valid index range (0..size-1)
  • if used on map, key can be of any type
  • to “unset” a value from map, just set it to zero (0)
    • NOTE: to add a value of 0 for the key, use the float value of 0.0

temp_array 

int temp_array(int size, int nothing)

Works exactly like create_array, only created array becomes “temporary”.