BlitzMax Extended  0.8.17
Pushing Blitz to the Max.
Data Structures | Macros | 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...

Macros

#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)
 for bbEmptyArray
#define BBARRAY_NOTFOUND   (-1)
 Shows that an element could not be found within a given array.

Functions

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, 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 *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.
BBArraybbArrayDimensions (const BBArray *arr)
 Gives an array's dimensions.
BBArraybbArrayConcat (const char *type, BBArray *arr, BBArray *rhs)
 Concatenates two arrays to a new one.
BBIntArraybbArrayFromInts (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.
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.
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.
BBArraybbArrayReverse (const BBArray *arr)
 Reverses an array.
BBArraybbArrayRotate (const BBArray *arr, BBInt count)
 Rotates all array indexes.

Variables

BBClass bbArrayClass
 The array class.
BBArray bbEmptyArray
 A typesafe NULL pointer for arrays.

Detailed Description

Functionality to work with array data structures.

Author:
Mark Sibly
Fabian Niemann

Macro Definition 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 bbArrayClone(), bbArrayCompare(), bbArrayEndsWith(), bbArrayNew1D(), bbArrayRotate(), bbArraySlice(), bbArraySort(), bbArrayStartsWith(), 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(), 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)

for bbEmptyArray

See also:
BBNULLOBJECT, BBNULLSTRING

Function Documentation

BBArray* bbArrayCastFromObject ( const BBObject obj,
const char *  typetag 
)

Casts an object to an array depending on the type tag.

Parameters:
objThe object pointer which points to an array
typetagThe type of the array that is pointed to by obj
Returns:
A pointer to the casted array, or BBNULL as a BBArray*.
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,
BBArray arr,
BBArray rhs 
)

Concatenates two arrays to a new one.

If the resulting array's length would be 0, BBNULLARRAY is returned.

Parameters:
typeThe type of both array's as a type tag
arrThe array that is the beginning of the resulting one
rhsThe right-hand side array that will be concatenated to the first one
Returns:
A new array consisting of both given arrays or BBNULLARRAY.
BBBool bbArrayContains ( const BBArray arr,
const BBArray sub 
)

Checks if an array contains another one.

Parameters:
arrThe array to be searched
subThe subarray to be searched for
Return values:
BBTRUEIf the array contains the subarray
BBFALSEIf the subarray could not be found in the array
BBBool bbArrayContainsDouble ( const BBDoubleArray arr,
BBDouble  num 
)

Checks if an array contains a BBDouble number.

Parameters:
arrThe array to be searched
numThe number which is searched for
Return values:
BBTRUEIf the array contains the number
BBFALSEIf the number could not be found in the array
BBBool bbArrayContainsFloat ( const BBFloatArray arr,
BBFloat  num 
)

Checks if an array contains a BBFloat number.

Parameters:
arrThe array to be searched
numThe number which is searched for
Return values:
BBTRUEIf the array contains the number
BBFALSEIf the number could not be found in the array
BBBool bbArrayContainsInt ( const BBArray arr,
BBInt  num 
)

Checks if an array contains a BBInt number.

Parameters:
arrThe array to be searched
numThe number which is searched for
Return values:
BBTRUEIf the array contains the number
BBFALSEIf the number could not be found in the array
BBBool bbArrayContainsLong ( const BBLongArray arr,
BBLong  num 
)

Checks if an array contains a BBLong number.

Parameters:
arrThe array to be searched
numThe number which is searched for
Return values:
BBTRUEIf the array contains the number
BBFALSEIf the number could not be found in the array
BBBool bbArrayContainsObject ( const BBObjectArray arr,
const BBObject obj 
)

Checks if an array contains an object.

Parameters:
arrThe array to be searched
objThe object which is searched for
Return values:
BBTRUEIf the array contains the object
BBFALSEIf the object could not be found in the array
BBBool bbArrayContainsString ( const BBStringArray arr,
const BBString str 
)

Checks if an array contains a string.

Parameters:
arrThe array to be searched
strThe string which is searched for
Return values:
BBTRUEIf the array contains the string
BBFALSEIf the string could not be found in the array
BBArray* bbArrayDimensions ( const BBArray arr)

Gives an array's dimensions.

If the array's length is 0, BBNULLARRAY is returned.

Parameters:
arrThe array to get the dimensions for
Returns:
A new array containing the size of every dimension of arr or BBNULLARRAY.
BBBool bbArrayEndsWith ( const BBArray arr,
const BBArray rhs 
)

Checks if an array ends with another one.

Parameters:
arrThe array to be checked against
rhsThe subarray to be checked for
Return values:
BBTRUEIf the array ends with the given subarray
BBFALSEIf the subarray does not match the end of the array
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
BBIntArray* bbArrayFromInts ( const BBInt buf,
BBInt  size 
)

Creates a new array from a BBInt buffer.

Parameters:
bufA buffer of BBInt values
sizeThe length of the buffer
Returns:
A new BBIntArray or BBNULLARRAY
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)

Reverses an array.

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

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.

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,
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.

Note:
This changes the indexing of the given array.
Parameters:
arrThe array to be sorted
ascendingIf the order of sorting should be ascending or descending
BBBool bbArrayStartsWith ( const BBArray arr,
const BBArray rhs 
)

Checks if an array starts with another one.

Parameters:
arrThe array to be checked against
rhsThe subarray to be checked for
Return values:
BBTRUEIf the array starts with the given subarray
BBFALSEIf the subarray does not match the beginning of the array
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

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.

Note:
Contains only the standard BlitzMax functions to ensure maximum compatibility with legacy code.
BBArray bbEmptyArray

A typesafe NULL pointer for arrays.

Used as a typesafe NULL pointer for arrays in the runtime.

See also:
BBNULLARRAY, bbNullObject, bbEmptyString
Warning:
Do not free this compile-time object.