1/*!
2 * @header OC_PythonArray.h
3 * @abstract Objective-C proxy class for Python sequences
4 * @discussion
5 *     This file defines the class that is used to represent Python sequences
6 *     in Objective-C.
7 */
8
9#import "pyobjc.h"
10#import <Foundation/Foundation.h>
11
12/*!
13 * @class       OC_PythonArray
14 * @abstract    Objective-C proxy class for Python sequences
15 * @discussion  Instances of this class are used as proxies for Python
16 * 	        sequences when these are passed to Objective-C code. Because
17 * 	        this class is a subclass of NSMutableArray Python sequences
18 * 	        can be used everywhere where NSArray or NSMutableArray objects
19 * 	        are expected.
20 */
21@interface OC_PythonArray : NSMutableArray
22{
23	PyObject* value;
24}
25
26/*!
27 * @method depythonifyObject:
28 * @abstract Create a new instance when appropriate
29 * @param value A python object
30 * @result Returns an autoreleased value or nil. Might set error in latter case.
31 *
32 * Caller must own the GIL
33 */
34+ depythonifyObject:(PyObject*)object;
35
36
37/*!
38 * @method newWithPythonObject:
39 * @abstract Create a new OC_PythonArray for a specific Python sequence
40 * @param value A python sequence
41 * @result Returns an autoreleased instance representing value
42 *
43 * Caller must own the GIL.
44 */
45+ newWithPythonObject:(PyObject*)value;
46
47/*!
48 * @method initWithPythonObject:
49 * @abstract Initialise a OC_PythonArray for a specific Python sequence
50 * @param value A python sequence
51 * @result Returns self
52 *
53 * Caller must own the GIL.
54 */
55- initWithPythonObject:(PyObject*)value;
56
57/*!
58 * @method dealloc
59 * @abstract Deallocate the object
60 */
61-(void)dealloc;
62
63/*!
64 * @method dealloc
65 * @abstract Access the wrapped Python sequence
66 * @result  Returns a new reference to the wrapped Python sequence.
67 */
68-(PyObject*)__pyobjc_PythonObject__;
69
70/*!
71 * @method count
72 * @result  Returns the length of the wrapped Python sequence
73 */
74-(NSUInteger)count;
75
76/*!
77 * @method objectAtIndex:
78 * @param idx An index
79 * @result  Returns the object at the specified index in the wrapped Python
80 *          sequence
81 */
82- (id)objectAtIndex:(NSUInteger)idx;
83
84/*!
85 * @method replaceObjectAtIndex:withObject:
86 * @abstract Replace the current value at idx by the new value
87 * @discussion This method will raise an exception when the wrapped Python
88 *             sequence is immutable.
89 * @param idx An index
90 * @param newValue A replacement value
91 */
92-(void)replaceObjectAtIndex:(NSUInteger)idx withObject:newValue;
93
94/*!
95 * @method getObjects:inRange:
96 * @abstract Fetch objects in the specified range
97 * @discussion The output buffer must have enough space to contain all
98 *             requested objects, the range must be valid.
99 *
100 *             This method is not documented in the NSArray interface, but
101 *             is used by Cocoa on MacOS X 10.3 when an instance of this
102 *             class is used as the value for -setObject:forKey: in
103 *             NSUserDefaults.
104 * @param buffer  The output buffer
105 * @param range   The range of objects to fetch.
106 */
107-(void)getObjects:(id*)buffer inRange:(NSRange)range;
108
109/*!
110 * @method addObject:
111 * @abstract Append an object
112 * @param anObject The object that will be append
113 */
114-(void)addObject:(id)anObject;
115
116/*!
117 * @method insertObject:atIndex:
118 * @abstract Insert an object at the specified index
119 * @param anObject The object to insert
120 * @param idx  The index
121 */
122-(void)insertObject:(id)anObject atIndex:(NSUInteger)idx;
123
124/*!
125 * @method removeLastObject
126 * @abstract Remove the last object of the sequence
127 */
128-(void)removeLastObject;
129
130/*!
131 * @method removeObjectAtIndex:
132 * @abstract Remove a specific item
133 * @param idx Which object should be removed
134 */
135-(void)removeObjectAtIndex:(NSUInteger)idx;
136
137/* These two are only present to *disable* coding, not implement it */
138- (void)encodeWithCoder:(NSCoder*)coder;
139- initWithCoder:(NSCoder*)coder;
140
141@end
142