<<    Index    >>	FutureBasic
mda		statement / function

Note: the tag parameter identifies which array to use. If it is omitted, array 0 is used.

 
Description
Although mda is an acronym for "multi-dimensional array", mda arrays can also be single-dimensional.

The mda statement assigns a value to an element in one of FB's special mda arrays. mda arrays are mutable, single or multi-dimensional, always global in scope and are zero-based. An mda array contains CF/NS objects. However, for convenience, integer and double values can be used directly in its statements/functions and are converted to/from objects behind the scenes.

You can read the contents of an mda array element by using the mda function.

Your program can use as many mda arrays as memory allows, numbered 0 to 2,147,483,647. The tag parameter specifies which mda array to use. If you omit this parameter, mda 0 is used. The dim1, dim2, ... parameters specify which element to target in the array.

More options

Option	Description
mda_add [ [tag] ( dim1 [, dim2 [, ... ] ] ) ] = { object | intValue | dblValue }	Adds a value to the end of the array Note: If the number of dims entered is equal to the array's dim count, the last dim value is ignored
mda_append [ [tag] ( dim1 [, dim2 [, ... ] ] ) ] = CFArrayRef	Adds the contents of a CFArray to the end of the mda array Note: If the number of dims entered is equal to the array's dim count, the last dim value is ignored
array = mda_array [tag]	Returns the root array, as a CFMutableArrayRef, of the mda array
class = mda_class [tag] ( dim1 [, dim2 [, ... ] ] )	Returns the class of the object as a ClassRef
mda_clear [tag]	Removes all elements from the array
mda_compact [tag]	Removes all NULL values from the array
count = mda_count [ [tag] ( dim1 [, dim2 [, ... ] ] ) ]	Returns the length of the array at the specified location. Beware of precedence when using a single-dimensional array in an expression In this example, we want to subtract 1 from the count of the array. However, due to precedence, 1 is subtracted from the tag value instead. count = mda_count tag - 1 Enclosing the function and its tag value in parentheses ensures the expected value is returned. count = (mda_count tag) - 1
string = mda_description [ [tag] [, emptyArrays [, nulls [, classes ] ] ] ]	Useful for debugging. Returns a string description of the contents of the array Flags: emptyArrays - include empty arrays in description. Default = YES nulls - include NULL values. Default = YES classes - show object class names. Default = NO
dblValue = mda_double [tag] ( dim1 [, dim2 [, ... ] ] )	Force mda to return a double value (see Limitations below)
mda_insert [tag] ( dim1 [, dim2 [, ... ] ] ) = { object | intValue | dblValue }	Inserts a value at the specified location
intValue = mda_integer [tag] ( dim1 [, dim2 [, ... ] ] )	Force mda to return an integer value (see Limitations below)
mda_kill [tag]	Deletes the entire array
object = mda_object [tag] ( dim1 [, dim2 [, ... ] ] )	Force mda to return an object value (see Limitations below)
[result = ] mda_read [tag,] url	Reads an mda array from a previously saved file at the specified url. Returns YES if successful
mda_remove [tag] ( dim1 [, dim2 [, ... ] ] ) [, length ]	Removes the value at the dim location The optional length param indicates the number of values to remove from the array (default = 1)
mda_sort [tag] [, selector]	Sorts the entire array in ascending order. Note: This has the effect of removing all NULL values The optional selector parameter must be a CFString literal and can have one of the following values: @"compare:" (default) @"caseInsensitiveCompare:" @"localizedCaseInsensitiveCompare:" @"localizedCompare:" @"localizedStandardCompare:"
mda_swap [tag1] ( dim1 [, dim2 [, ... ] ] ), [tag2] ( dim1 [, dim2 [, ... ] ] )	Swaps the values at the specified arrays and locations
string = mda_text [tag]	Returns the textual contents of the array
[result = ] mda_write [tag,] url	Writes the mda array to a file at the specified url. Returns YES if successful

 

Ancillary functions
UserDefaultsGetMDA( tag ) gets a previously stored mda array with its tag value from user defaults.
UserDefaultsSetMDA( tag ) stores an mda array with its tag value in user defaults.
 

Aggregate initialization
Say what?... "aggregate initialization" is just a fancy name for "shortcut population". For example, the following line assigns the values 1-9 to the first nine elements of a single-dimensional array.

mda (0) = {1,2,3,4,5,6,7,8,9}

 
This example populates a two-dimensional array. Note the nested curly braces.

Output:
a	b	c
d	e	f
g	h	i

 
Three-dimensional array

Output:
10	11	
12	13	
14	15	
16	17	
18	19	
20	21	

Limitations
Some things we cannot (yet) do with mda arrays
 
(1) mda 1(2) = mda 1(0) + mda 1(1) // fail

 
(2) if ( mda 1(0) == 12 ) then beep// fail

 
(3)
printf @"%ld", mda 1(0)// fail
printf @"%f", mda 1(0)// fail

 
(4) long count = mda_count 3 - 1 // returns the count of array 2 (= 3 - 1)