COS_Layer.CosArray (Acrobat)

	Define
	CosArrayIsWeakReference
	CosArraySetWeakReference

	Method
	CosObj CosArrayGet(CosObj array, ASTArraySize index) Gets the specified element from an array.
	void CosArrayInsert(CosObj array, ASTArraySize pos, CosObj obj) Inserts an object into an array.
	ASBool CosArrayIsWeakReference(CosObj array, ASInt32 n) Return the state of a weak reference in an array. See CosDictIsWeakReference() for details.
	ASTArraySize CosArrayLength(CosObj array) Gets the number of elements in array.
	void CosArrayPut(CosObj array, ASTArraySize index, CosObj obj) Puts the specified object into the specified location in an array. The array is extended as much as necessary and NULL objects are stored in empty slots. It sets the PDDocNeedsSave flag (see PDDocSetFlags) flag of the array object's CosDoc if array is indirect or is a direct object with an indirect composite object at the root of its container chain.
	void CosArrayRemove(CosObj array, CosObj obj) Finds the first element, if any, equal to the specified object and removes it from the array. CosObjEqual() is used to determine whether an array element is equal to the specified object.
	void CosArrayRemoveNth(CosObj array, ASTArraySize pos) Checks whether the position is within the array bounds, removes it from the array, moves each subsequent element to the slot with the next smaller index, and decrements the array's length by 1. It sets the dirty flag of the array object's CosDoc.
	void CosArraySetWeakReference(CosObj array, ASInt32 n, ASBool isWeak) Establishes or removes a weak reference from an array. For a description of weak references, see CosDictSetWeakReference() .
	CosObj CosNewArray(CosDoc dP, ASBool indirect, ASTArraySize nElements) Creates and returns a new array Cos object.

Defines Detail

CosArrayIsWeakReference

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define CosArrayIsWeakReference CosCallMacro(CosArrayIsWeakReference, 7)

File: CosCalls.h

Line: 446

CosArraySetWeakReference

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define CosArraySetWeakReference CosCallMacro(CosArraySetWeakReference, 7)

File: CosCalls.h

Line: 445

Method Detail

CosArrayGet

()

Product availability: All

Platform availability: All

Syntax





CosObj CosArrayGet(CosObj array, ASTArraySize index)

Gets the specified element from an array.

Parameters

	`array` —	The array from which an element is obtained.

	`index` —	The array element to obtain. The first element in an array has an index of zero.

Returns

The Cos object occupying the index element of array. It returns a NULL Cos object if index is outside the array bounds.

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 765

CosArrayInsert

()

Product availability: All

Platform availability: All

Syntax





void CosArrayInsert(CosObj array, ASTArraySize pos, CosObj obj)

Inserts an object into an array.

An exception is raised if the object to insert is a direct object that is already contained in another object, or if the object to insert belongs to another document.

Parameters

	`array` —	The array into which the object is inserted.

	`pos` —	The location in the array to insert the object. The object is inserted before the specified location. The first element in an array has a pos of zero. If `pos >= CosArrayLength(array)`, `obj` is added at the end of the array. The length of the array always increases by `1`. It is not safe to call `CosArrayInsert()` during a call to `CosObjEnum()` on that same array (for example, from within the callback procedure).

	`obj` —	The object to insert.

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 819

CosArrayIsWeakReference

()

Product availability: All

Platform availability: All

Syntax





ASBool CosArrayIsWeakReference(CosObj array, ASInt32 n)

Return the state of a weak reference in an array. See CosDictIsWeakReference() for details.

Parameters

	`array` —	An array.

	`n` —	The index of an item in the array.

Returns

Returns the value of the isWeak parameter in the most recent call to CosArraySetWeakReference() with these parameters, or false if there has been no such call.

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h

Line: 2073

CosArrayLength

()

Product availability: All

Platform availability: All

Syntax





ASTArraySize CosArrayLength(CosObj array)

Gets the number of elements in array.

Parameters

array —

IN/OUT The array for which the number of elements is determined.

Returns

The number of elements in array.

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 849

CosArrayPut

()

Product availability: All

Platform availability: All

Syntax





void CosArrayPut(CosObj array, ASTArraySize index, CosObj obj)

Puts the specified object into the specified location in an array. The array is extended as much as necessary and NULL objects are stored in empty slots. It sets the PDDocNeedsSave flag (see PDDocSetFlags) flag of the array object's CosDoc if array is indirect or is a direct object with an indirect composite object at the root of its container chain.

It is not safe to call CosArrayPut() during a call to CosObjEnum() on that same array (for example, from within the callback procedure), if doing so would extend the length of the array.

An exception is raised if the object to insert is a direct object that is already contained in another object, or if the object to insert belongs to another document.

Parameters

	`array` —	The array in which `obj` is stored.

	`index` —	The location in `array` to store `obj`. The first element of an array has an index of zero.

	`obj` —	The Cos object to insert into `array`.

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 793

CosArrayRemove

()

Product availability: All

Platform availability: All

Syntax





void CosArrayRemove(CosObj array, CosObj obj)

Finds the first element, if any, equal to the specified object and removes it from the array. CosObjEqual() is used to determine whether an array element is equal to the specified object.

The array is compressed after removing the element. The compression is accomplished by moving each element following the deleted element to the slot with the next smaller index and decrementing the array's length by 1.

It is not safe to call CosArrayRemove() during a call to CosObjEnum() on that same dictionary (for example, from within the callback procedure).

Parameters

	`array` —	The array from which `obj` is removed.

	`obj` —	The object to remove.

See Also

CosArrayInsert

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 840

CosArrayRemoveNth

()

Product availability: All

Platform availability: All

Syntax





void CosArrayRemoveNth(CosObj array, ASTArraySize pos)

Checks whether the position is within the array bounds, removes it from the array, moves each subsequent element to the slot with the next smaller index, and decrements the array's length by 1. It sets the dirty flag of the array object's CosDoc.

Parameters

	`array` —	IN/OUT The `CosArray` from which to remove the member.

	`pos` —	IN/OUT The index for the array member to remove. Array indices start at `0`.

See Also

CosArrayRemove

Since

PI_COS_VERSION >= 0x00040000

File: CosProcs.h

Line: 1314

CosArraySetWeakReference

()

Product availability: All

Platform availability: All

Syntax





void CosArraySetWeakReference(CosObj array, ASInt32 n, ASBool isWeak)

Establishes or removes a weak reference from an array. For a description of weak references, see CosDictSetWeakReference().

Parameters

	`array` —	An array.

	`n` —	The index of the element that is the weak reference. Note that the weak reference travels with the element; that is, if an item is marked as a weak reference, and an item is subsequently inserted before that item, the weak reference applies to the same element as it did previously.

	`isWeak` —	Sets a weak reference for an array.

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h

Line: 2062

CosNewArray

()

Product availability: All

Platform availability: All

Syntax





CosObj CosNewArray(CosDoc dP, ASBool indirect, ASTArraySize nElements)

Creates and returns a new array Cos object.

Parameters

	`dP` —	The document in which the array is used.

	`indirect` —	If `true`, it creates the array as an indirect Cos object, and sets the document's `PDDocNeedsSave` flag (see `PDDocSetFlags`). If `false`, it creates the array as a direct object.

	`nElements` —	The number of elements that will be in the array. `nElements` is only a hint; Cos arrays grow dynamically as needed.

Returns

The newly created array Cos object.

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 259

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
CosArray	Defines \| Methods

Layer	COS_Layer
Object	CosArray