AIArraySuite Struct Reference
[API Suite List]

This suite defines the array, a heterogeneous container whose elements are accessed by sequential integer indices. More...

#include <AIArray.h>

List of all members.

Public Attributes
AIAPI AIErr(*	CreateArray )(AIArrayRef *array)
	Creates a new array.
AIAPI ai::int32(*	AddRef )(AIArrayRef array)
	Increments the reference count for an array.
AIAPI ai::int32(*	Release )(AIArrayRef array)
	Decrements the reference count for an array, and frees the memory when the reference count is 0.
AIAPI AIErr(*	Clone )(AIArrayRef src, AIArrayRef *dst)
	Makes an exact duplicate of a source array.
AIAPI AIErr(*	Copy )(AIArrayRef array, AIArrayRef src)
	Makes a copy of a source array by replacing the current contents of the destination array.
AIAPI ai::int32(*	Size )(AIArrayRef array)
	Returns the number of entries in an array.
AIAPI AIErr(*	DeleteEntry )(AIArrayRef array, ai::int32 i)
	Removes an entry from an array.
AIAPI AIErr(*	InsertEntry )(AIArrayRef array, ai::int32 i)
	Inserts an entry into an array at the given index.
AIAPI AIErr(*	GetEntryType )(AIArrayRef array, ai::int32 i, AIEntryType *type)
	Gets the data type of an array entry.
AIAPI AIErr(*	CopyEntry )(AIArrayRef array1, AIArrayRef array2, ai::int32 position1, ai::int32 position2)
	Copies an entry from one array to another, or to another position in the same array.
AIAPI AIErr(*	MoveEntry )(AIArrayRef array1, AIArrayRef array2, ai::int32 position1, ai::int32 position2, ai::int32 *newposition)
	Moves an entry from one array to another, or to another position in the same array.
AIAPI AIErr(*	SwapEntries )(AIArrayRef array1, AIArrayRef array2, ai::int32 position1, ai::int32 position2)
	Swaps two entries in two arrays, or in the same array.
AIAPI AIErr(*	GetArtEntry )(AIArrayRef array, ai::int32 i, AIArtHandle *art)
	Gets an art-object array entry.
AIAPI AIErr(*	NewArtEntry )(AIArrayRef array, ai::int32 i, ai::int16 type)
	Sets the value of an array entry to be a new art object of the specified type.
AIAPI AIErr(*	MoveArtToEntry )(AIArrayRef array, ai::int32 i, AIArtHandle art)
	Moves an art object from the artwork tree into an array.
AIAPI AIErr(*	MoveEntryToArt )(AIArrayRef array, ai::int32 i, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *art)
	Moves an art object to the artwork tree from an array.
AIAPI AIErr(*	CopyArtToEntry )(AIArrayRef array, ai::int32 i, AIArtHandle art)
	Copies an art object from the art tree into an array.
AIAPI AIErr(*	CopyEntryToArt )(AIArrayRef array, ai::int32 i, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *art)
	Copies an art object from an array into the art tree.
AIAPI AIErr(*	SetEntryToLayer )(AIArrayRef array, ai::int32 i, AILayerHandle layer)
	Sets an array entry to refer to the topmost group of a layer.
AIAPI AIErr(*	SetLayerToEntry )(AIArrayRef array, ai::int32 i, ai::int16 paintOrder, AILayerHandle prep, AILayerHandle *layer)
	Inserts a new layer in the current document, from a group array entry.
AIAPI AIEntryRef(*	Get )(AIArrayRef array, ai::int32 i)
	Retrieves an array entry by position index.
AIAPI AIErr(*	Set )(AIArrayRef array, ai::int32 i, AIEntryRef entry)
	Adds an array entry at a given position index.
AIAPI AIErr(*	GetBooleanEntry )(AIArrayRef array, ai::int32 i, ASBoolean *value)
	Retrieves a boolean value from an array entry.
AIAPI AIErr(*	SetBooleanEntry )(AIArrayRef array, ai::int32 i, AIBoolean value)
	Sets a boolean value for an array entry.
AIAPI AIErr(*	GetIntegerEntry )(AIArrayRef array, ai::int32 i, ai::int32 *value)
	Retrieves an integer value from an array entry.
AIAPI AIErr(*	SetIntegerEntry )(AIArrayRef array, ai::int32 i, ai::int32 value)
	Sets an integer value for an array entry.
AIAPI AIErr(*	GetRealEntry )(AIArrayRef array, ai::int32 i, AIReal *value)
	Retrieves a `real` value from an array entry.
AIAPI AIErr(*	SetRealEntry )(AIArrayRef array, ai::int32 i, AIReal value)
	Sets a `real` value for an array entry.
AIAPI AIErr(*	GetStringEntry )(AIArrayRef array, ai::int32 i, const char **value)
	Retrieves a string value from an array entry.
AIAPI AIErr(*	SetStringEntry )(AIArrayRef array, ai::int32 i, const char *value)
	Sets a string value for an array entry.
AIAPI AIErr(*	GetBinaryEntry )(AIArrayRef array, ai::int32 i, void value, ASInt32 size)
	Retrieves a binary value from an array entry.
AIAPI AIErr(*	SetBinaryEntry )(AIArrayRef array, ai::int32 i, void *value, ai::int32 size)
	Sets a binary value for an array entry.
AIAPI AIErr(*	GetDictEntry )(AIArrayRef array, ai::int32 i, AIDictionaryRef *value)
	Retrieves a dictionary value from an array entry.
AIAPI AIErr(*	SetDictEntry )(AIArrayRef array, ai::int32 i, AIDictionaryRef value)
	Sets a dictionary value for an array entry.
AIAPI AIErr(*	GetArrayEntry )(AIArrayRef array, ai::int32 i, AIArrayRef *value)
	Retrieves an array value from an array entry.
AIAPI AIErr(*	SetArrayEntry )(AIArrayRef array, ai::int32 i, AIArrayRef value)
	Sets an array value for an array entry.
AIAPI AIErr(*	GetUnicodeStringEntry )(AIArrayRef array, ai::int32 i, ai::UnicodeString &value)
	Retrieves a Unicode string value from an array entry.
AIAPI AIErr(*	SetUnicodeStringEntry )(AIArrayRef array, ai::int32 i, const ai::UnicodeString &value)
	Sets a Unicode string value for an array entry.
AIAPI AIErr(*	AppendEntry )(AIArrayRef array, AIEntryRef entry)
	Adds an entry at the end of an array.
AIAPI AIErr(*	Reserve )(AIArrayRef array, ai::int32 count)
	Reserves a minimum length of storage for an array.

Detailed Description

This suite defines the array, a heterogeneous container whose elements are accessed by sequential integer indices.

Entries (of type AIEntryRef), can be inserted into and removed from the array. The AIEntry suite provides methods to construct and query entries of different types. See apiAIEntry.h. Entries can be of simple types such as booleans, integers, floats, and strings and complex types such as other arrays, dictionaries and references to document objects including art objects, brushes and styles. This makes arrays a very flexible and powerful container.

Arrays can themselves be stored in other containers such as other arrays or dictionaries. In particular they can be stored in the dictionaries attached to art objects and to the document. When an array is stored in one of these places (directly or indirectly) it is read and written as a part of the document.

See also:: AIEntrySuite, AIDictionarySuite, AIArtSuite

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIArraySuite and kAIArrayVersion.

Member Data Documentation

AIAPI ai::int32(* AIArraySuite::AddRef)(AIArrayRef array)

Increments the reference count for an array.

When you create an array, the initial count is 1. Use Release() to decrement the count. (Note that this function returns a numeric value, not an error code.)

Parameters:

array

The array reference.

Returns:: The current reference count.

AIAPI AIErr(* AIArraySuite::AppendEntry)(AIArrayRef array, AIEntryRef entry)

Adds an entry at the end of an array.

Parameters:

	array	The array reference.
	entry	The array entry reference. See `apiAIEntry.h`.

See also:: Set()

AIAPI AIErr(* AIArraySuite::Clone)(AIArrayRef src, AIArrayRef *dst)

Makes an exact duplicate of a source array.

Performs a deep copy.

Parameters:

	src	The array reference for the source.
	dest	[out] buffer in which to return the new array.

AIAPI AIErr(* AIArraySuite::Copy)(AIArrayRef array, AIArrayRef src)

Makes a copy of a source array by replacing the current contents of the destination array.

Parameters:

	array	The reference for the array to be replaced.
	src	The array reference for the source.

AIAPI AIErr(* AIArraySuite::CopyArtToEntry)(AIArrayRef array, ai::int32 i, AIArtHandle art)

Copies an art object from the art tree into an array.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	art	The art object. See `apiAIArt.h`.

AIAPI AIErr(* AIArraySuite::CopyEntry)(AIArrayRef array1, AIArrayRef array2, ai::int32 position1, ai::int32 position2)

Copies an entry from one array to another, or to another position in the same array.

Parameters:

	array1	The array reference for the source.
	array2	The array reference for the destination. Can be the same array, or different one.
	position1	The 0-based index position of the source entry.
	position2	The 0-based index position of the destination entry.

AIAPI AIErr(* AIArraySuite::CopyEntryToArt)(AIArrayRef array, ai::int32 i, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *art)

Copies an art object from an array into the art tree.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	paintOrder	The paint order of the art object in the art tree. See `apiAIArt.h`.
	prep	The prepositional object for the paint order. See `apiAIArt.h`.
	art	The art object. See `apiAIArt.h`.

AIAPI AIErr(* AIArraySuite::CreateArray)(AIArrayRef *array)

Creates a new array.

Arrays are reference counted. Initial reference count is 1. Use AddRef() to increment the count, and Release() to decrement the count.

Parameters:

array

[out] A buffer in which to return the new array reference.

AIAPI AIErr(* AIArraySuite::DeleteEntry)(AIArrayRef array, ai::int32 i)

Removes an entry from an array.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.

AIAPI AIEntryRef(* AIArraySuite::Get)(AIArrayRef array, ai::int32 i)

Retrieves an array entry by position index.

(Note this returns an array entry reference, not an error code.)

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.

Returns:: The array entry, or a null entry if one does not exist.

AIAPI AIErr(* AIArraySuite::GetArrayEntry)(AIArrayRef array, ai::int32 i, AIArrayRef *value)

Retrieves an array value from an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIArraySuite::GetArtEntry)(AIArrayRef array, ai::int32 i, AIArtHandle *art)

Gets an art-object array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	type	[out] A buffer in which to return the entry.

AIAPI AIErr(* AIArraySuite::GetBinaryEntry)(AIArrayRef array, ai::int32 i, void *value, ASInt32 *size)

Retrieves a binary value from an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	[out] A buffer in which to return the value.
	size	[out] The number of bytes in `value`.

AIAPI AIErr(* AIArraySuite::GetBooleanEntry)(AIArrayRef array, ai::int32 i, ASBoolean *value)

Retrieves a boolean value from an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIArraySuite::GetDictEntry)(AIArrayRef array, ai::int32 i, AIDictionaryRef *value)

Retrieves a dictionary value from an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIArraySuite::GetEntryType)(AIArrayRef array, ai::int32 i, AIEntryType *type)

Gets the data type of an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	type	[out] A buffer in which to return the type. See `apiAIEntry.h`.

AIAPI AIErr(* AIArraySuite::GetIntegerEntry)(AIArrayRef array, ai::int32 i, ai::int32 *value)

Retrieves an integer value from an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIArraySuite::GetRealEntry)(AIArrayRef array, ai::int32 i, AIReal *value)

Retrieves a real value from an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIArraySuite::GetStringEntry)(AIArrayRef array, ai::int32 i, const char **value)

Retrieves a string value from an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIArraySuite::GetUnicodeStringEntry)(AIArrayRef array, ai::int32 i, ai::UnicodeString &value)

Retrieves a Unicode string value from an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	[out] A buffer in which to return the value.

AIAPI AIErr(* AIArraySuite::InsertEntry)(AIArrayRef array, ai::int32 i)

Inserts an entry into an array at the given index.

The new entry is assigned an arbitrary initial value.

Parameters:

	array	The array reference.
	i	The 0-based index position of the new entry.

AIAPI AIErr(* AIArraySuite::MoveArtToEntry)(AIArrayRef array, ai::int32 i, AIArtHandle art)

Moves an art object from the artwork tree into an array.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	art	The art object. See `apiAIArt.h`.

AIAPI AIErr(* AIArraySuite::MoveEntry)(AIArrayRef array1, AIArrayRef array2, ai::int32 position1, ai::int32 position2, ai::int32 *newposition)

Moves an entry from one array to another, or to another position in the same array.

Parameters:

	array1	The array reference for the source.
	array2	The array reference for the destination. Can be the same array, or different one.
	position1	The 0-based index position of the source entry.
	position2	The 0-based index position of the destination entry.
	newposition	[out] (Optional) A buffer in which to return the position of the entry in `array2` after the move.

AIAPI AIErr(* AIArraySuite::MoveEntryToArt)(AIArrayRef array, ai::int32 i, ai::int16 paintOrder, AIArtHandle prep, AIArtHandle *art)

Moves an art object to the artwork tree from an array.

The entry is not deleted from the array, but instead is set to an arbitrary value.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	paintOrder	The paint order of the art object in the art tree. See `apiAIArt.h`.
	prep	The prepositional object for the paint order. See `apiAIArt.h`.
	art	The art object. See `apiAIArt.h`.

AIAPI AIErr(* AIArraySuite::NewArtEntry)(AIArrayRef array, ai::int32 i, ai::int16 type)

Sets the value of an array entry to be a new art object of the specified type.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	type	The type of art object. See `apiAIArt.h`.

AIAPI ai::int32(* AIArraySuite::Release)(AIArrayRef array)

Decrements the reference count for an array, and frees the memory when the reference count is 0.

When you create an array, the initial count is 1. Use AddRef() to increment the count. (Note that this function returns a numeric value, not an error code.)

Parameters:

array

The array reference.

Returns:: The current reference count.

AIAPI AIErr(* AIArraySuite::Reserve)(AIArrayRef array, ai::int32 count)

Reserves a minimum length of storage for an array.

Parameters:

	array	The array reference.
	count	The number of entries to reserve.

AIAPI AIErr(* AIArraySuite::Set)(AIArrayRef array, ai::int32 i, AIEntryRef entry)

Adds an array entry at a given position index.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	entry	The array entry reference. See `apiAIEntry.h`.

See also:: AppendEntry()

AIAPI AIErr(* AIArraySuite::SetArrayEntry)(AIArrayRef array, ai::int32 i, AIArrayRef value)

Sets an array value for an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	The new value.

AIAPI AIErr(* AIArraySuite::SetBinaryEntry)(AIArrayRef array, ai::int32 i, void *value, ai::int32 size)

Sets a binary value for an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	A pointer to the new value.
	size	The number of bytes in `value`.

AIAPI AIErr(* AIArraySuite::SetBooleanEntry)(AIArrayRef array, ai::int32 i, AIBoolean value)

Sets a boolean value for an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	The new value.

AIAPI AIErr(* AIArraySuite::SetDictEntry)(AIArrayRef array, ai::int32 i, AIDictionaryRef value)

Sets a dictionary value for an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	The new value.

AIAPI AIErr(* AIArraySuite::SetEntryToLayer)(AIArrayRef array, ai::int32 i, AILayerHandle layer)

Sets an array entry to refer to the topmost group of a layer.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	layer	The layer reference.

AIAPI AIErr(* AIArraySuite::SetIntegerEntry)(AIArrayRef array, ai::int32 i, ai::int32 value)

Sets an integer value for an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	The new value.

AIAPI AIErr(* AIArraySuite::SetLayerToEntry)(AIArrayRef array, ai::int32 i, ai::int16 paintOrder, AILayerHandle prep, AILayerHandle *layer)

Inserts a new layer in the current document, from a group array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry. Must be an art object, of type `kGroupArt`.
	paintOrder	The paint order of the art object in the art tree. Valid values are `kPlaceDefault`, `kPlaceAbove`, `kPlaceBelow`, `kPlaceAboveAll` and `kPlaceBelowAll`.
	prep	The prepositional object for the paint order.
	layer	[out] A buffer in which to return the new layer reference.

AIAPI AIErr(* AIArraySuite::SetRealEntry)(AIArrayRef array, ai::int32 i, AIReal value)

Sets a real value for an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	The new value.

AIAPI AIErr(* AIArraySuite::SetStringEntry)(AIArrayRef array, ai::int32 i, const char *value)

Sets a string value for an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	The new value.

AIAPI AIErr(* AIArraySuite::SetUnicodeStringEntry)(AIArrayRef array, ai::int32 i, const ai::UnicodeString &value)

Sets a Unicode string value for an array entry.

Parameters:

	array	The array reference.
	i	The 0-based index position of the entry.
	value	The new value.

AIAPI ai::int32(* AIArraySuite::Size)(AIArrayRef array)

Returns the number of entries in an array.

The index position of an entry is in the range [0..Size(array) - 1]. Note this returns a number, not an error code.

Parameters:

array

The array reference.

Returns:: The number of entries in the array.

AIAPI AIErr(* AIArraySuite::SwapEntries)(AIArrayRef array1, AIArrayRef array2, ai::int32 position1, ai::int32 position2)

Swaps two entries in two arrays, or in the same array.

Parameters:

	array1	The first array reference.
	array2	The second array reference. Can be the same array, or different one.
	position1	The 0-based index position of the first entry.
	position2	The 0-based index position of the second entry.

The documentation for this struct was generated from the following file:

AIArray.h

AIArraySuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

AIArraySuite Struct Reference
[API Suite List]