![]() |
BlitzMax Extended
0.8.11
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... | |
Defines | |
#define | BBARRAY_SIZE_CALC(size, num_dims) (BBARRAY_HEADER_SIZE + (num_dims) * sizeof (int) + (size)) |
Calculates the size of an array. | |
#define | BBARRAY_SIZE(arr) BBARRAY_SIZE_CALC ((arr)->size, (arr)->dims) |
Gives the size of an array in bytes. | |
#define | BBARRAY_DATAPTR_CALC(arr, num_dims) |
Calculates a pointer to an array's data section. | |
#define | BBARRAY_DATAPTR(arr) BBARRAY_DATAPTR_CALC((arr), (arr)->dims) |
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 | BBNULLARRAY (&bbEmptyArray) |
Alias for bbEmptyArray. | |
#define | BBARRAY_NOTFOUND (-1) |
Shows that an element could not be found within a given array. | |
Functions | |
BBArray * | bb_array_alloc (const char *type, BBSize dims, const BBSize *lens) |
Allocates a new multi-dimensional array. | |
BBArray * | bb_array_alloc1d (const char *type, BBSize len) |
Allocates a new 1-dimensional array. | |
void | bb_array_init (BBArray *arr) |
Initializes an array. | |
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, const 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 *type_encoding) |
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 including the size of all of the array's dimensions. | |
BBArray * | bbArrayConcat (const char *type, const BBArray *arr, const BBArray *rhs) |
Concatenates two arrays to a new one. | |
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. | |
BBArray * | bbArrayReverse (const BBArray *arr) |
Gives a reversed array. | |
BBArray * | bbArrayRotate (const BBArray *arr, BBInt count) |
Rotates all array indexes. | |
Variables | |
BBClass | bbArrayClass |
The array class. | |
BBArray | bbEmptyArray |
A compile time array instance for use as a NULL pointer. |
Functionality to work with array data structures.
#define BBARRAY_ALLOC | ( | size, | |
dims, | |||
flags | |||
) |
({ \ (BBArray *) \ bbGCAllocObject( \ BBARRAY_SIZE_CALC((size), (dims)), \ &bbArrayClass, \ (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 | ) | BBARRAY_DATAPTR_CALC((arr), (arr)->dims) |
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 bb_array_init(), bbArrayClone(), bbArrayCompare(), bbArrayNew1D(), bbArrayRotate(), bbArraySlice(), bbArraySort(), and bbStringFromArray().
#define BBARRAY_DATAPTR_CALC | ( | arr, | |
num_dims | |||
) |
((void *) \ ((char *)(arr) + BBARRAY_HEADER_SIZE + (num_dims) * sizeof (int)) \ )
Calculates a pointer to an array's data section.
arr | A pointer to the array |
num_dims | The number of dimensions the array contains |
Referenced by bbArrayConcat(), bbArrayDimensions(), bbArrayFromData(), bbArrayReverse(), bbArraySlice(), and bbStringJoin().
#define BBARRAY_NOTFOUND (-1) |
Shows that an element could not be found within a given array.
Referenced by bbArrayFind(), bbArrayFindDouble(), bbArrayFindFloat(), bbArrayFindInt(), bbArrayFindLong(), bbArrayFindObject(), and bbArrayFindString().
#define BBARRAY_SIZE | ( | arr | ) | BBARRAY_SIZE_CALC ((arr)->size, (arr)->dims) |
Gives the size of an array in bytes.
arr | A pointer to the array |
#define BBARRAY_SIZE_CALC | ( | size, | |
num_dims | |||
) | (BBARRAY_HEADER_SIZE + (num_dims) * sizeof (int) + (size)) |
Calculates the size of an array.
This can be used to calculate the size of an array object from its properties. Comes in handy for all sorts of allocations.
The amount of memory the array uses is calculated from the size of "struct BBArray" (the so-called header), the size of the scales property (which is a variable C array) and the number of dimensions.
size | The value of the array's size property |
num_dims | The number of dimensions the array contains |
#define BBNULLARRAY (&bbEmptyArray) |
Alias for bbEmptyArray.
BBArray* bb_array_alloc | ( | const char * | type, |
BBSize | dims, | ||
const BBSize * | lens | ||
) |
Allocates a new multi-dimensional array.
This allocates a new multi-dimensional array with the GC and sets all of its required information.
type | The type tag describing the data to store |
dims | The number of dimensions |
lens | The number of elements for each dimension |
Referenced by bbArrayClone(), bbArrayNew(), bbArrayReverse(), and bbArrayRotate().
BBArray* bb_array_alloc1d | ( | const char * | type, |
BBSize | len | ||
) |
Allocates a new 1-dimensional array.
This allocates a new 1-dimensional array with the GC and sets all of its required information.
If you know that you only need one dimension and have all the necessary data to fill the array with, this is the best way to go in terms of speed.
type | The type tag describing the data to store |
len | The number of array elements |
Referenced by bbArrayConcat(), bbArrayDimensions(), bbArrayFromData(), bbArraySlice(), bbStringFindAll(), and bbStringSplit().
void bb_array_init | ( | BBArray * | arr | ) |
Initializes an array.
After allocation via bb_array_alloc or bb_array_alloc1d, the array's parameters are set, but the data is not initialized.
Initialized means that each data type has a default value, like any BBInt variable is set to 0 by default.
Of course this can also be used to reset an array that has already been used to its initial state.
arr | The array of which the data should be initialized |
BBArray* bbArrayCastFromObject | ( | const BBObject * | obj, |
const char * | type_encoding | ||
) |
Casts an object to an array depending on the type tag.
BBArray* bbArrayClone | ( | const BBArray * | arr | ) |
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 |
BBInt bbArrayCompare | ( | const BBArray * | arr, |
const BBArray * | rhs | ||
) |
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 |
BBArray* bbArrayConcat | ( | const char * | type, |
const BBArray * | arr, | ||
const BBArray * | rhs | ||
) |
Concatenates two arrays to a new one.
BBArray* bbArrayDimensions | ( | const BBArray * | arr | ) |
Gives an array including the size of all of the array's dimensions.
BBBool bbArrayEquals | ( | const BBArray * | arr, |
const BBArray * | rhs | ||
) |
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. |
BBInt bbArrayFind | ( | const BBArray * | arr, |
const BBArray * | sub, | ||
BBInt | start_pos | ||
) |
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 |
BBInt bbArrayFindInt | ( | const BBArray * | arr, |
BBInt | num, | ||
BBInt | start_pos | ||
) |
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 |
BBArray* bbArrayFromData | ( | const char * | type, |
BBInt | length, | ||
const void * | data | ||
) |
Creates a new array from a block of data.
type | The type tag indicating the new array's data type |
BBArray* bbArrayNew | ( | const char * | type, |
BBInt | dims, | ||
... | |||
) |
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 |
BBArray* bbArrayNew1D | ( | const char * | type, |
BBInt | length | ||
) |
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 |
BBArray* bbArrayReverse | ( | const BBArray * | arr | ) |
Gives a reversed array.
arr | The input array which should be reversed |
BBArray* bbArrayRotate | ( | const BBArray * | arr, |
BBInt | count | ||
) |
Rotates all array indexes.
arr | The array to be rotated |
count | The number of rotations |
BBArray* bbArraySlice | ( | const char * | type, |
const BBArray * | arr, | ||
BBInt | begin, | ||
BBInt | end | ||
) |
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 |
void bbArraySort | ( | BBArray * | arr, |
BBInt | ascending | ||
) |
Sorts an array depending on its data type.
BBString* bbArrayToString | ( | const BBArray * | arr | ) |
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 |
The array class.