BlitzMax Extended  0.8.11
Pushing Blitz to the Max.
Data Structures | Defines | Functions | Variables
blitz_array.h File Reference

Functionality to work with array data structures. More...

#include "_common.h"
#include "blitz_class.h"
#include "blitz_object.h"

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

BBArraybb_array_alloc (const char *type, BBSize dims, const BBSize *lens)
 Allocates a new multi-dimensional array.
BBArraybb_array_alloc1d (const char *type, BBSize len)
 Allocates a new 1-dimensional array.
void bb_array_init (BBArray *arr)
 Initializes an array.
BBArraybbArrayNew (const char *type, BBInt dims,...)
 Creates a new array.
BBArraybbArrayNew1D (const char *type, BBInt length)
 Creates a new 1-dimensional array.
BBArraybbArraySlice (const char *type, const BBArray *arr, BBInt begin, BBInt end)
 Creates a new array from a subset of the given array.
BBArraybbArrayFromData (const char *type, BBInt length, const void *data)
 Creates a new array from a block of data.
BBArraybbArrayCastFromObject (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.
BBArraybbArrayDimensions (const BBArray *arr)
 Gives an array including the size of all of the array's dimensions.
BBArraybbArrayConcat (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.
BBStringbbArrayToString (const BBArray *arr)
 Gives a string description the array.
BBArraybbArrayClone (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.
BBArraybbArrayReverse (const BBArray *arr)
 Gives a reversed array.
BBArraybbArrayRotate (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.

Detailed Description

Functionality to work with array data structures.

Author:
Mark Sibly
Fabian Niemann

Define Documentation

#define BBARRAY_ALLOC (   size,
  dims,
  flags 
)
Value:
({                                                                          \
        (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.

Note:
Depending on the data type an array stores, different GC flags are required. Use with care.
See also:
bb_array_alloc, bb_array_alloc1d, bbGCAllocObject
Parameters:
sizeThe size of each dimension
dimsThe number of dimensions
flagsInformation for the GC on how to handle destruction
Returns:
A pointer to the newly allocated object

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.

See also:
BBARRAY_DATAPTR_CALC
Parameters:
arrA pointer to the array
Returns:
A pointer to the first element in the array

Referenced by bb_array_init(), bbArrayClone(), bbArrayCompare(), bbArrayNew1D(), bbArrayRotate(), bbArraySlice(), bbArraySort(), and bbStringFromArray().

#define BBARRAY_DATAPTR_CALC (   arr,
  num_dims 
)
Value:
((void *)                                                                       \
    ((char *)(arr) + BBARRAY_HEADER_SIZE + (num_dims) * sizeof (int))           \
)

Calculates a pointer to an array's data section.

See also:
BBARRAY_DATAPTR
Parameters:
arrA pointer to the array
num_dimsThe number of dimensions the array contains
Returns:
A pointer of type void* to the data

Referenced by bbArrayConcat(), bbArrayDimensions(), bbArrayFromData(), bbArrayReverse(), bbArraySlice(), and bbStringJoin().

#define BBARRAY_NOTFOUND   (-1)
#define BBARRAY_SIZE (   arr)    BBARRAY_SIZE_CALC ((arr)->size, (arr)->dims)

Gives the size of an array in bytes.

See also:
BBARRAY_SIZE_CALC
Parameters:
arrA pointer to the array
Returns:
The size of the array in bytes
#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.

See also:
BBARRAY_SIZE
Parameters:
sizeThe value of the array's size property
num_dimsThe number of dimensions the array contains
Returns:
The size of the array in bytes
#define BBNULLARRAY   (&bbEmptyArray)

Alias for bbEmptyArray.

See also:
BBNULLOBJECT, BBNULLSTRING

Function Documentation

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.

See also:
bb_array_alloc1d, bb_array_init
Parameters:
typeThe type tag describing the data to store
dimsThe number of dimensions
lensThe number of elements for each dimension
Returns:
A new multi-dimensional array

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.

Note:
The returned array's data is not initialized, you have to either completely fill it with fitting values or use bb_array_init.
See also:
bb_array_alloc, bb_array_init
Parameters:
typeThe type tag describing the data to store
lenThe number of array elements
Returns:
A new 1-dimensional array.

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.

Note:
It does not matter how the array was allocated. However, arrays allocated by bbArrayNew, bbArrayNew1D or bbArrayNewEx are already fully initialized.
Parameters:
arrThe 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.

Parameters:
arrThe array to be cloned
Returns:
A new array containing the values of the given one. BBNULLARRAY in case of an error.
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.

See also:
bbArrayEquals
Parameters:
arrThe array to be compared against
rhsThe righthand side array to compare the first one with
Return values:
0If both arrays are equal
1If arr is greater than or equal to rhs
-1If 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.

See also:
bbArrayCompare
Parameters:
arrThe array to be checked for equality
rhsThe other array, that the first one is compared against
Return values:
BBTRUEif both arrays contain the exact same values.
BBFALSEif 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.

Parameters:
arrThe array to be searched
subThe subarray which provides the values to be looked for
Returns:
The position of the first occurance of all of the values of subarray, or BBARRAY_NOTFOUND.
BBInt bbArrayFindDouble ( const BBDoubleArray arr,
BBDouble  num,
BBInt  start_pos 
)

Finds the first occurance of a BBDouble value in an array.

Parameters:
arrThe array to be searched
searchThe 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.

Parameters:
arrThe array to be searched
searchThe 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.

Parameters:
arrThe array to be searched
numThe BBInt value to be searched for
start_posThe start index of the search
Returns:
The position of the first occurance of num, or BBARRAY_NOTFOUND.
BBInt bbArrayFindLong ( const BBLongArray arr,
BBLong  num,
BBInt  start_pos 
)

Finds the first occurance of a BBLong value in an array.

Parameters:
arrThe array to be searched
searchThe 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.

Parameters:
arrThe array to be searched
objThe 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.

Parameters:
arrThe array to be searched
strThe BBString to be searched for
BBArray* bbArrayFromData ( const char *  type,
BBInt  length,
const void *  data 
)

Creates a new array from a block of data.

Parameters:
typeThe 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.

Parameters:
typeType tag describing the data to store.
dimsThe number of dimensions
Returns:
A new multi-dimensional array
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.

Note:
The only reason to use the bb_array_alloc1d instead is when you have all the data to fill the new array with, so initializing it would be unnecessary.
Parameters:
typeType tag describing the data to store.
lenThe number of array elements
Returns:
A new 1-dimensional array
BBArray* bbArrayReverse ( const BBArray arr)

Gives a reversed array.

Parameters:
arrThe input array which should be reversed
Returns:
A reversed version of the given array, or a pointer the given arr.
BBArray* bbArrayRotate ( const BBArray arr,
BBInt  count 
)

Rotates all array indexes.

Parameters:
arrThe array to be rotated
countThe number of rotations
Returns:
A rotated version of the array, or a pointer to the given arr.
BBArray* bbArraySlice ( const char *  type,
const BBArray arr,
BBInt  begin,
BBInt  end 
)

Creates a new array from a subset of the given array.

Parameters:
typeThe type tag indicating the array's data type
arrThe array to be sliced
beginThe start position of the resulting array section
endThe last position of the reuslting array section
Returns:
A new array containing the specified section of the array
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.

Parameters:
arrThe array to get a description of
Returns:
A new string containing the array's type and dimensions

Variable Documentation

The array class.