![]() |
BlitzMax Extended
0.8.19
Pushing Blitz to the Max.
|
Functionality to work with array data structures. More...
Go to the source code of this file.
Data Structures | |
struct | BBArray |
Fixed-length array object. More... | |
struct | BBByteArray |
Helper array object storing BBBytes. More... | |
struct | BBShortArray |
Helper array object storing BBShorts. More... | |
struct | BBIntArray |
Helper array object storing BBInts. More... | |
struct | BBLongArray |
Helper array object storing BBLongs. More... | |
struct | BBFloatArray |
Helper array object storing BBFloats. More... | |
struct | BBDoubleArray |
Helper array object storing BBDoubles. More... | |
struct | BBObjectArray |
Helper array object storing BBObjects. More... | |
struct | BBStringArray |
Helper array object storing BBStrings. More... | |
struct | BBArrayArray |
Helper array object storing other BBArrays. More... |
Macros | |
#define | BBARRAY_SIZE(arr) |
Gives the size of an array in bytes. | |
#define | BBARRAY_DATAPTR(arr) |
Gives a pointer to the beginning of an array's data section. | |
#define | BBARRAY_ALLOC(size, dims, flags) |
Allocates a new BBArray object with the GC. | |
#define | BBARRAY_ISCOMPLEX(arr) |
Checks if an array stores complex elements. | |
#define | BBARRAY_ISNUMERIC(arr) |
Checks if an array stores numeric elements. | |
#define | BBARRAY_ISPRIMITIVE(arr) |
Checks if an array stores primitive elements. | |
#define | BBNULLARRAY |
for bbEmptyArray | |
#define | BBARRAY_NOTFOUND |
Shows that an element could not be found within a given array. |
Functions | |
BBArray * | bbArrayNew (const char *type, BBInt dims,...) |
Creates a new array. | |
BBArray * | bbArrayNew1D (const char *type, BBInt length) |
Creates a new 1-dimensional array. | |
BBArray * | bbArraySlice (const char *type, BBArray *arr, BBInt begin, BBInt end) |
Creates a new array from a subset of the given array. | |
BBArray * | bbArrayFromData (const char *type, BBInt length, const void *data) |
Creates a new array from a block of data. | |
BBArray * | bbArrayCastFromObject (const BBObject *obj, const char *typetag) |
Casts an object to an array depending on the type tag. | |
void | bbArraySort (BBArray *arr, BBInt ascending) |
Sorts an array depending on its data type. | |
BBArray * | bbArrayDimensions (const BBArray *arr) |
Gives an array's dimensions. | |
BBArray * | bbArrayConcat (const char *type, BBArray *arr, BBArray *rhs) |
Concatenates two arrays to a new one. | |
BBIntArray * | bbArrayFromInts (const BBInt *buf, BBInt size) |
Creates a new array from a BBInt buffer. | |
BBInt | bbArrayCompare (const BBArray *arr, const BBArray *rhs) __attribute__((pure)) |
Compares two arrays. | |
BBString * | bbArrayToString (const BBArray *arr) |
Gives a string description the array. | |
BBArray * | bbArrayClone (const BBArray *arr) |
Creates an exact clone of an array. | |
BBBool | bbArrayEquals (const BBArray *arr, const BBArray *rhs) __attribute__((pure)) |
Checks two arrays for equality. | |
BBInt | bbArrayFind (const BBArray *arr, const BBArray *sub, BBInt start_pos) __attribute__((pure)) |
Finds the first occurance of a subarray's data in an array. | |
BBInt | bbArrayFindInt (const BBArray *arr, BBInt num, BBInt start_pos) __attribute__((pure)) |
Finds the first occurance of a BBInt value in an array. | |
BBInt | bbArrayFindLong (const BBLongArray *arr, BBLong num, BBInt start_pos) __attribute__((pure)) |
Finds the first occurance of a BBLong value in an array. | |
BBInt | bbArrayFindFloat (const BBFloatArray *arr, BBFloat num, BBInt start_pos) __attribute__((pure)) |
Finds the first occurance of a BBFloat value in an array. | |
BBInt | bbArrayFindDouble (const BBDoubleArray *arr, BBDouble num, BBInt start_pos) __attribute__((pure)) |
Finds the first occurance of a BBDouble value in an array. | |
BBInt | bbArrayFindObject (const BBObjectArray *arr, const BBObject *obj, BBInt start_pos) __attribute__((pure)) |
Finds the first occurance of an object in an array. | |
BBInt | bbArrayFindString (const BBStringArray *arr, const BBString *str, BBInt start_pos) __attribute__((pure)) |
Finds the first occurance of a string in an array. | |
BBBool | bbArrayStartsWith (const BBArray *arr, const BBArray *rhs) __attribute__((pure)) |
Checks if an array starts with another one. | |
BBBool | bbArrayEndsWith (const BBArray *arr, const BBArray *rhs) __attribute__((pure)) |
Checks if an array ends with another one. | |
BBBool | bbArrayContains (const BBArray *arr, const BBArray *sub) __attribute__((pure)) |
Checks if an array contains another one. | |
BBBool | bbArrayContainsInt (const BBArray *arr, BBInt num) __attribute__((pure)) |
Checks if an array contains a BBInt number. | |
BBBool | bbArrayContainsLong (const BBLongArray *arr, BBLong num) __attribute__((pure)) |
Checks if an array contains a BBLong number. | |
BBBool | bbArrayContainsFloat (const BBFloatArray *arr, BBFloat num) __attribute__((pure)) |
Checks if an array contains a BBFloat number. | |
BBBool | bbArrayContainsDouble (const BBDoubleArray *arr, BBDouble num) __attribute__((pure)) |
Checks if an array contains a BBDouble number. | |
BBBool | bbArrayContainsObject (const BBObjectArray *arr, const BBObject *obj) __attribute__((pure)) |
Checks if an array contains an object. | |
BBBool | bbArrayContainsString (const BBStringArray *arr, const BBString *str) __attribute__((pure)) |
Checks if an array contains a string. | |
BBArray * | bbArrayReverse (const BBArray *arr) |
Reverses an array. | |
BBArray * | bbArrayRotate (const BBArray *arr, BBInt count) |
Rotates all array indexes. | |
BBArray * | bbArrayFilter (const BBArray *arr, BBBool(*filter)(void *)) |
Filters all array elements using a callback function. | |
BBArray * | bbArrayMap (BBArray *arr, void *(*callback)(void *)) |
Applies a given callback to every element. |
Variables | |
BBClass | bbArrayClass |
The array class. | |
BBArray | bbEmptyArray |
A typesafe NULL pointer for arrays. |
Functionality to work with array data structures.
#define BBARRAY_ALLOC | ( | size, | |
dims, | |||
flags | |||
) |
Allocates a new BBArray object with the GC.
This is a utility macro which does not perform any additional checking. It only fills in the right parameters for allocating a string object with the GC.
Only use this if you can ensure that all parameters are valid and you set the array's information like size or type by hand.
Generally it is advised to use bb_array_alloc instead.
size | The size of each dimension |
dims | The number of dimensions |
flags | Information for the GC on how to handle destruction |
Referenced by bbArrayNew1D().
#define BBARRAY_DATAPTR | ( | arr | ) |
Gives a pointer to the beginning of an array's data section.
This is a useful shorthand if the array is already initialized with the correct information about its properties.
arr | A pointer to the array |
Referenced by bbArrayClone(), bbArrayCompare(), bbArrayEndsWith(), bbArrayNew1D(), bbArrayRotate(), bbArraySlice(), bbArraySort(), bbArrayStartsWith(), and bbStringFromArray().
#define BBARRAY_ISCOMPLEX | ( | arr | ) |
Checks if an array stores complex elements.
Tests the array's type
property. If the array stores BBObject
, BBString
or BBArray
elements it will return true
.
true
true | The array stores complex elements |
false | The array stores non-complex elements |
Referenced by bbArrayReverse().
#define BBARRAY_ISNUMERIC | ( | arr | ) |
Checks if an array stores numeric elements.
Tests the array's type
property. If the array stores BBByte
, BBShort
, BBInt
, BBLong
, BBFloat
or BBDouble
elements it will return true
.
true | The array stores numeric elements |
false | The array stores non-numeric elements |
Referenced by bbArrayReverse().
#define BBARRAY_ISPRIMITIVE | ( | arr | ) |
Checks if an array stores primitive elements.
Tests the array's type
property. If the array stores BBByte
, BBShort
, BBInt
, BBLong
, BBFloat
, BBDouble
or (function) pointer elements it will return true
.
true | The array stores primitive elements |
false | The array stores non-primitive elements |
#define BBARRAY_NOTFOUND |
Shows that an element could not be found within a given array.
Referenced by bbArrayContains(), bbArrayContainsDouble(), bbArrayContainsFloat(), bbArrayContainsInt(), bbArrayContainsLong(), bbArrayContainsObject(), bbArrayContainsString(), bbArrayFind(), bbArrayFindDouble(), bbArrayFindFloat(), bbArrayFindInt(), bbArrayFindLong(), bbArrayFindObject(), and bbArrayFindString().
#define BBARRAY_SIZE | ( | arr | ) |
Gives the size of an array in bytes.
arr | A pointer to the array |
#define BBNULLARRAY |
for bbEmptyArray
Referenced by bbArrayFilter(), bbArrayMap(), bbArrayReverse(), and bbArrayToString().
Casts an object to an array depending on the type tag.
obj | The object pointer which points to an array |
typetag | The type of the array that is pointed to by obj |
BBNULL
as a BBArray*
. Creates an exact clone of an array.
Primitive data type arrays, namely Byte, Short, Int, Long, Float, Double and their respective pointer counterparts are copied by value.
Complex data type arrays on the other hand are copied by reference, meaning every element will have an increase reference count, but won't be cloned itself.
If arr
is an empty array, BBNULLARRAY is returned.
arr | The array to be cloned |
Compares two arrays.
Comparison is done with respect to a number of properties and of course both array's data. The importance of each tested value is listed below.
If one of the following properties in the given arr is greater than or equal to the corresponing one in the rhs array, 1 is returned. Otherwise -1.
scales
[0] dims
size
type_tag
If all properties are equal, the arrays' data is compared using memcmp.
arr | The array to be compared against |
rhs | The righthand side array to compare the first one with |
0 | If both arrays are equal |
1 | If arr is greater than or equal to rhs |
-1 | If arr is lesser than rhs |
Concatenates two arrays to a new one.
If the resulting array's length would be 0
, BBNULLARRAY
is returned.
type | The type of both array's as a type tag |
arr | The array that is the beginning of the resulting one |
rhs | The right-hand side array that will be concatenated to the first one |
BBNULLARRAY
. Checks if an array contains another one.
arr | The array to be searched |
sub | The subarray to be searched for |
BBTRUE | If the array contains the subarray |
BBFALSE | If the subarray could not be found in the array |
BBBool bbArrayContainsDouble | ( | const BBDoubleArray * | arr, |
BBDouble | num | ||
) |
Checks if an array contains a BBDouble number.
arr | The array to be searched |
num | The number which is searched for |
BBTRUE | If the array contains the number |
BBFALSE | If the number could not be found in the array |
BBBool bbArrayContainsFloat | ( | const BBFloatArray * | arr, |
BBFloat | num | ||
) |
Checks if an array contains a BBFloat number.
arr | The array to be searched |
num | The number which is searched for |
BBTRUE | If the array contains the number |
BBFALSE | If the number could not be found in the array |
Checks if an array contains a BBInt number.
arr | The array to be searched |
num | The number which is searched for |
BBTRUE | If the array contains the number |
BBFALSE | If the number could not be found in the array |
BBBool bbArrayContainsLong | ( | const BBLongArray * | arr, |
BBLong | num | ||
) |
Checks if an array contains a BBLong number.
arr | The array to be searched |
num | The number which is searched for |
BBTRUE | If the array contains the number |
BBFALSE | If the number could not be found in the array |
BBBool bbArrayContainsObject | ( | const BBObjectArray * | arr, |
const BBObject * | obj | ||
) |
Checks if an array contains an object.
arr | The array to be searched |
obj | The object which is searched for |
BBTRUE | If the array contains the object |
BBFALSE | If the object could not be found in the array |
BBBool bbArrayContainsString | ( | const BBStringArray * | arr, |
const BBString * | str | ||
) |
Checks if an array contains a string.
arr | The array to be searched |
str | The string which is searched for |
BBTRUE | If the array contains the string |
BBFALSE | If the string could not be found in the array |
Gives an array's dimensions.
If the array's length is 0
, BBNULLARRAY
is returned.
arr | The array to get the dimensions for |
BBNULLARRAY
. Checks if an array ends with another one.
arr | The array to be checked against |
rhs | The subarray to be checked for |
BBTRUE | If the array ends with the given subarray |
BBFALSE | If the subarray does not match the end of the array |
Checks two arrays for equality.
arr | The array to be checked for equality |
rhs | The other array, that the first one is compared against |
BBTRUE | if both arrays contain the exact same values. |
BBFALSE | if there are differences between both arrays. |
Filters all array elements using a callback function.
The given filter callback is called with each element of the array. When it returns BBTRUE
for a given value, the element will be included in the resulting array. If BBFALSE
is returned it will not.
arr | The array to be filtered |
filter | The callback function filtering the elements |
BBNULLARRAY
. Finds the first occurance of a subarray's data in an array.
arr | The array to be searched |
sub | The subarray which provides the values to be looked for |
BBARRAY_NOTFOUND
. BBInt bbArrayFindDouble | ( | const BBDoubleArray * | arr, |
BBDouble | num, | ||
BBInt | start_pos | ||
) |
Finds the first occurance of a BBDouble value in an array.
arr | The array to be searched |
search | The BBDouble value to be searched for |
BBInt bbArrayFindFloat | ( | const BBFloatArray * | arr, |
BBFloat | num, | ||
BBInt | start_pos | ||
) |
Finds the first occurance of a BBFloat value in an array.
arr | The array to be searched |
search | The BBFloat value to be searched for |
Finds the first occurance of a BBInt value in an array.
arr | The array to be searched |
num | The BBInt value to be searched for |
start_pos | The start index of the search |
BBARRAY_NOTFOUND
. BBInt bbArrayFindLong | ( | const BBLongArray * | arr, |
BBLong | num, | ||
BBInt | start_pos | ||
) |
Finds the first occurance of a BBLong value in an array.
arr | The array to be searched |
search | The BBLong value to be searched for |
BBInt bbArrayFindObject | ( | const BBObjectArray * | arr, |
const BBObject * | obj, | ||
BBInt | start_pos | ||
) |
Finds the first occurance of an object in an array.
arr | The array to be searched |
obj | The BBObject to be searched for |
BBInt bbArrayFindString | ( | const BBStringArray * | arr, |
const BBString * | str, | ||
BBInt | start_pos | ||
) |
Finds the first occurance of a string in an array.
arr | The array to be searched |
str | The BBString to be searched for |
Creates a new array from a block of data.
type | The type tag indicating the new array's data type |
BBIntArray* bbArrayFromInts | ( | const BBInt * | buf, |
BBInt | size | ||
) |
Creates a new array from a BBInt
buffer.
buf | A buffer of BBInt values |
size | The length of the buffer |
BBIntArray
or BBNULLARRAY
Applies a given callback to every element.
arr | The array to be run through the callback |
callback | The callback function applying a certain action to each element |
Creates a new array.
Allocates a new multi-dimensional array with the GC and initializes its data.
type | Type tag describing the data to store |
dims | The number of dimensions |
Creates a new 1-dimensional array.
Allocates a new 1-dimensional array with the GC and initializes its data. Since this is the most common method of creating an array, it is heavily optimized, so it is a good idea to always use this.
type | Type tag describing the data to store |
len | The number of array elements |
Reverses an array.
arr | The input array which should be reversed |
Rotates all array indexes.
The sign of count controls the direction of the rotation. If count is negative, the array's indexes will be rotated to the left. If count is positive, the array's indexes will be rotated to the right. In the case that count is 0
, the given array is returned without any rotation.
The number of rotations given in count can be greater than the length of the array. In that case the array's indexes will be rotateted from the beginning/end again.
arr | The array to be rotated |
count | The number of rotations |
Creates a new array from a subset of the given array.
type | The type tag indicating the array's data type |
arr | The array to be sliced |
begin | The start position of the resulting array section |
end | The last position of the reuslting array section |
Sorts an array depending on its data type.
arr | The array to be sorted |
ascending | If the order of sorting should be ascending or descending |
Checks if an array starts with another one.
arr | The array to be checked against |
rhs | The subarray to be checked for |
BBTRUE | If the array starts with the given subarray |
BBFALSE | If the subarray does not match the beginning of the array |
Gives a string description the array.
The string describing the given array has the format: (Array) $TYPE[$DIMS]
For a 1-dimensional BBFloat array with three elements, it would be: (Array) Float[3]
If the given array arr is BBNULLARRAY
, "(Array) Null" is returned.
arr | The array to get a description of |
BBClass bbArrayClass |
The array class.
In BlitzMax arrays are a built-in Final
class. Therefore this structure rarely needs to be accessed directly except for testing if an BBObject*
parameter is an array. All other functionality can safely be done via the API functions.
BBArray bbEmptyArray |
A typesafe NULL
pointer for arrays.
Used as a typesafe NULL
pointer for arrays in the runtime.