1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
.TH DYN 3M "15 March 1990"
.SH NAME
dyn \- the C Dynamic Object library
.SH DESCRIPTION
A C Dynamic Object is an array that takes care of resizing
itself as you add and delete elements from it. It can be of any type
for which sizeof is defined and for which an address of a variable of
that type can be passed to a function. The library containing the
functions described below is called
.IR libdyn.a ,
and the necessary declarations to use them are in
.RI < dyn.h >.
.PP
A DynObject is actually a structure that contains an array and a
couple of integers to maintain necessary state information. When a
Dyn function is said to operate on "the object" or "the array", it is
operating on the array stored in the structure while at the same time
updating internal state information.
.SH LIST OF FUNCTIONS
.nf
DynObject DynCreate(size, increment)
int size, increment;
.fi
.PP
.IR Requires :
.I size
and
.I increment
are greater than zero.
.PP
.IR Effects :
Creates a new DynObject that will store elements of size
.I size
and will allocate memory in blocks large enough to hold exactly
.I increment
elements. For example, if you are storing 8-byte double
precision numbers and
.I increment
is 5, each 5th element you add to the object will cause it to request
40 more bytes (8 * 5) from the operating system. If
.I increment
is zero, a default value is used (currently 100). This is the only
time the programmer deals with a dynamic object's memory allocation.
.PP
.IR Returns :
.B DynCreate
returns the new DynObject, or NULL if there is insufficient memory.
.PP
.nf
int DynDestroy(obj)
DynObject obj;
.fi
.PP
.IR Modifies :
obj
.PP
.IR Effects :
Frees all memory associated with
.IR obj .
The results of calling any Dyn function on a destroyed object are
undefined (except for DynCreate, which resets the object).
.PP
.IR Returns :
.B DynDestroy
returns DYN_OK.
.PP
.nf
int DynAdd(obj, el)
DynObject obj;
DynPtr el;
.fi
.PP
.IR Modifies :
obj
.PP
.IR Effects :
Adds the element pointed to by
.I el
to the object
.IR obj ,
resizing the object if necessary.
The new element becomes the last element in obj's array.
.PP
.IR Returns :
.B DynAdd
returns DYN_OK on success or DYN_NOMEM if there is insufficient
memory.
.PP
.nf
int DynInsert(obj, index, els, num)
DynObject obj;
DynPtr els;
int index, num;
.fi
.PP
.IR Modifies :
obj
.PP
.IR Effects :
Inserts the array of
.I num
elements, pointed to by
.IR els,
into the object
.I obj
starting at the array location
.IR index ,
resizing the object if necessary. Order is preserved; if you have the
array "1 2 3 4 5" and insert "10 11 12" at the third position, you
will have the array "1 2 10 11 12 3 4 5".
.PP
.IR Returns :
.B DynInsert
returns DYN_BADINDEX if
.I index
is not between 0 and
.BR DynSize ( obj ) ;
DYN_BADVALUE if
.I num
is less than 1; DYN_NOMEM if there is insufficient memory.
.PP
.nf
int DynGet(obj, index)
DynObject obj;
int index;
.fi
.PP
.IR Effects :
Returns the address of the element
.I index
in the array of
.IR obj .
This pointer can be treated as a normal array of the type specified to
.BR DynCreate .
The order of elements in this array is the order in which they were
added to the object. The returned pointer is guaranteed to be valid
only until obj is modified.
.PP
.IR Returns :
.B DynGet
returns NULL if
.I index
is larger than the number of elements in the array of less than zero.
.PP
.nf
int DynDelete(obj, index)
DynObject obj;
int index;
.fi
.PP
.IR Modifies :
obj
.PP
.IR Effects :
The element
.I index
is deleted from the object
.IR obj .
Note that the element is actually removed permanently from the array.
If you have the array "1 2 3 4 5" and delete the third element, you
will have the array "1 2 4 5". The order of elements in not affected.
.PP
.IR Returns :
.B DynDelete
will return DYN_OK on success or DYN_BADINDEX if the element
.I index
does not exist in the array or is less than zero.
.PP
.nf
int DynSize(obj)
DynObject obj;
.fi
.PP
.IR Effects :
Returns the number of elements in the object
.IR obj .
.PP
.nf
int DynHigh(obj)
DynObject obj;
.fi
.PP
.IR Effects :
Returns the index of the highest element in the object
.IR obj .
In this version,
.B DynHigh
is macro that expands to
.B DynSize
- 1.
.PP
.nf
int DynLow(obj)
DynObject obj;
.fi
.PP
.IR Effects :
Returns the index of the lowest element in the object
.IR obj .
In this version,
.B DynLow
is macro that expands to 0.
.PP
.nf
int DynDebug(obj, state)
DynObject obj;
int state;
.fi
.PP
.IR Modifies :
obj
.PP
.IR Effects :
Sets the debugging state of
.I obj
to
.I state
and prints a message on stderr saying what state debugging was set to.
Any non-zero value for
.I state
turns debugging ``on''. When debugging is on, all Dyn functions will
produce (hopefully useful) output describing what is going on on
stderr.
.PP
.IR Returns :
.B DynDebug
returns DYN_OK.
.SH AUTHOR
Barr3y Jaspan, Student Information Processing Board (SIPB) and
MIT-Project Athena, bjaspan@athena.mit.edu
|