[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_vector.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
4  *\r
5  * This software is available to you under the OpenIB.org BSD license\r
6  * below:\r
7  *\r
8  *     Redistribution and use in source and binary forms, with or\r
9  *     without modification, are permitted provided that the following\r
10  *     conditions are met:\r
11  *\r
12  *      - Redistributions of source code must retain the above\r
13  *        copyright notice, this list of conditions and the following\r
14  *        disclaimer.\r
15  *\r
16  *      - Redistributions in binary form must reproduce the above\r
17  *        copyright notice, this list of conditions and the following\r
18  *        disclaimer in the documentation and/or other materials\r
19  *        provided with the distribution.\r
20  *\r
21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
22  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
23  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
24  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
25  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
26  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
27  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
28  * SOFTWARE.\r
29  *\r
30  * $Id$\r
31  */\r
32 \r
33 \r
34 /*\r
35  * Abstract:\r
36  *      This file contains vector definitions.  Vector provides dynmically\r
37  *      resizable array functionality.  Objects in a Vector are not relocated\r
38  *      when the array is resized.\r
39  *\r
40  * Environment:\r
41  *      All\r
42  */\r
43 \r
44 \r
45 #ifndef _CL_VECTOR_H_\r
46 #define _CL_VECTOR_H_\r
47 \r
48 \r
49 #include <complib/cl_qlist.h>\r
50 \r
51 \r
52 /****h* Component Library/Vector\r
53 * NAME\r
54 *       Vector\r
55 *\r
56 * DESCRIPTION\r
57 *       The Vector is a self-sizing array. Like a traditonal array, a vector\r
58 *       allows efficient constant time access to elements with a specified index.\r
59 *       A vector grows transparently as the user adds elements to the array.\r
60 *\r
61 *       As the vector grows in size, it does not relocate existing elements in\r
62 *       memory. This allows using pointers to elements stored in a Vector.\r
63 *\r
64 *       Users can supply an initializer functions that allow a vector to ensure\r
65 *       that new items added to the vector are properly initialized. A vector\r
66 *       calls the initializer function on a per object basis when growing the\r
67 *       array. The initializer is optional.\r
68 *\r
69 *       The initializer function can fail, and returns a cl_status_t. The vector\r
70 *       will call the destructor function, if provided, for an element that\r
71 *       failed initialization. If an initializer fails, a vector does not call\r
72 *       the initializer for objects in the remainder of the new memory allocation.\r
73 *\r
74 *       The cl_vector_t structure should be treated as opaque and should be\r
75 *       manipulated only through the provided functions.\r
76 *\r
77 * SEE ALSO\r
78 *       Structures:\r
79 *               cl_vector_t\r
80 *\r
81 *       Callbacks:\r
82 *               cl_pfn_vec_init_t, cl_pfn_vec_dtor_t, cl_pfn_vec_apply_t,\r
83 *               cl_pfn_vec_find_t\r
84 *\r
85 *       Item Manipulation:\r
86 *               cl_vector_set_obj, cl_vector_obj\r
87 *\r
88 *       Initialization:\r
89 *               cl_vector_construct, cl_vector_init, cl_vector_destroy\r
90 *\r
91 *       Manipulation:\r
92 *               cl_vector_get_capacity, cl_vector_set_capacity,\r
93 *               cl_vector_get_size, cl_vector_set_size, cl_vector_set_min_size\r
94 *               cl_vector_get_ptr, cl_vector_get, cl_vector_at, cl_vector_set\r
95 *\r
96 *       Search:\r
97 *               cl_vector_find_from_start, cl_vector_find_from_end\r
98 *               cl_vector_apply_func\r
99 *********/\r
100 \r
101 \r
102 /****d* Component Library: Vector/cl_pfn_vec_init_t\r
103 * NAME\r
104 *       cl_pfn_vec_init_t\r
105 *\r
106 * DESCRIPTION\r
107 *       The cl_pfn_vec_init_t function type defines the prototype for functions\r
108 *       used as initializer for elements being allocated by a vector.\r
109 *\r
110 * SYNOPSIS\r
111 */\r
112 typedef cl_status_t\r
113 (CL_API *cl_pfn_vec_init_t)(\r
114         IN      void* const                     p_element,\r
115         IN      void*                           context );\r
116 /*\r
117 * PARAMETERS\r
118 *       p_element\r
119 *               [in] Pointer to an element being added to a vector.\r
120 *\r
121 *       context\r
122 *               [in] Context provided in a call to cl_vector_init.\r
123 *\r
124 * RETURN VALUES\r
125 *       Return CL_SUCCESS to indicate that the element was initialized successfully.\r
126 *\r
127 *       Other cl_status_t values will be returned by the cl_vector_init,\r
128 *       cl_vector_set_size, and cl_vector_set_min_size functions.\r
129 *\r
130 *       In situations where the vector's size needs to grows in order to satisfy\r
131 *       a call to cl_vector_set, a non-successful status returned by the\r
132 *       initializer callback causes the growth to stop.\r
133 *\r
134 * NOTES\r
135 *       This function type is provided as function prototype reference for\r
136 *       the initializer function provided by users as an optional parameter to\r
137 *       the cl_vector_init function.\r
138 *\r
139 * SEE ALSO\r
140 *       Vector, cl_vector_init\r
141 *********/\r
142 \r
143 \r
144 /****d* Component Library: Vector/cl_pfn_vec_dtor_t\r
145 * NAME\r
146 *       cl_pfn_vec_dtor_t\r
147 *\r
148 * DESCRIPTION\r
149 *       The cl_pfn_vec_dtor_t function type defines the prototype for functions\r
150 *       used as destructor for elements being deallocated from a vector.\r
151 *\r
152 * SYNOPSIS\r
153 */\r
154 typedef void\r
155 (CL_API *cl_pfn_vec_dtor_t)(\r
156         IN      void* const                     p_element,\r
157         IN      void*                           context );\r
158 /*\r
159 * PARAMETERS\r
160 *       p_element\r
161 *               [in] Pointer to an element being deallocated from a vector.\r
162 *\r
163 *       context\r
164 *               [in] Context provided in a call to cl_vector_init.\r
165 *\r
166 * RETURN VALUE\r
167 *       This function does not return a value.\r
168 *\r
169 * NOTES\r
170 *       This function type is provided as function prototype reference for\r
171 *       the destructor function provided by users as an optional parameter to\r
172 *       the cl_vector_init function.\r
173 *\r
174 * SEE ALSO\r
175 *       Vector, cl_vector_init\r
176 *********/\r
177 \r
178 \r
179 /****d* Component Library: Vector/cl_pfn_vec_apply_t\r
180 * NAME\r
181 *       cl_pfn_vec_apply_t\r
182 *\r
183 * DESCRIPTION\r
184 *       The cl_pfn_vec_apply_t function type defines the prototype for functions\r
185 *       used to iterate elements in a vector.\r
186 *\r
187 * SYNOPSIS\r
188 */\r
189 typedef void\r
190 (CL_API *cl_pfn_vec_apply_t)(\r
191         IN      const size_t            index,\r
192         IN      void* const                     p_element,\r
193         IN      void*                           context );\r
194 /*\r
195 * PARAMETERS\r
196 *       index\r
197 *               [in] Index of the element.\r
198 *\r
199 *       p_element\r
200 *               [in] Pointer to an element at the specified index in the vector.\r
201 *\r
202 *       context\r
203 *               [in] Context provided in a call to cl_vector_apply_func.\r
204 *\r
205 * RETURN VALUE\r
206 *       This function does not return a value.\r
207 *\r
208 * NOTES\r
209 *       This function type is provided as function prototype reference for\r
210 *       the function passed by users as a parameter to the cl_vector_apply_func\r
211 *       function.\r
212 *\r
213 * SEE ALSO\r
214 *       Vector, cl_vector_apply_func\r
215 *********/\r
216 \r
217 \r
218 /****d* Component Library: Vector/cl_pfn_vec_find_t\r
219 * NAME\r
220 *       cl_pfn_vec_find_t\r
221 *\r
222 * DESCRIPTION\r
223 *       The cl_pfn_vec_find_t function type defines the prototype for functions\r
224 *       used to find elements in a vector.\r
225 *\r
226 * SYNOPSIS\r
227 */\r
228 typedef cl_status_t\r
229 (CL_API *cl_pfn_vec_find_t)(\r
230         IN      const size_t            index,\r
231         IN      const void* const       p_element,\r
232         IN      void*                           context );\r
233 /*\r
234 * PARAMETERS\r
235 *       index\r
236 *               [in] Index of the element.\r
237 *\r
238 *       p_element\r
239 *               [in] Pointer to an element at the specified index in the vector.\r
240 *\r
241 *       context\r
242 *               [in] Context provided in a call to cl_vector_find_from_start or\r
243 *               cl_vector_find_from_end.\r
244 *\r
245 * RETURN VALUES\r
246 *       Return CL_SUCCESS if the element was found. This stops vector iteration.\r
247 *\r
248 *       CL_NOT_FOUND to continue the vector iteration.\r
249 *\r
250 * NOTES\r
251 *       This function type is provided as function prototype reference for the\r
252 *       function provided by users as a parameter to the cl_vector_find_from_start\r
253 *       and cl_vector_find_from_end functions.\r
254 *\r
255 * SEE ALSO\r
256 *       Vector, cl_vector_find_from_start, cl_vector_find_from_end\r
257 *********/\r
258 \r
259 \r
260 /****i* Component Library: Vector/cl_pfn_vec_copy_t\r
261 * NAME\r
262 *       cl_pfn_vec_copy_t\r
263 *\r
264 * DESCRIPTION\r
265 *       The cl_pfn_vec_copy_t function type defines the prototype for functions\r
266 *       used to copy elements in a vector.\r
267 *\r
268 * SYNOPSIS\r
269 */\r
270 typedef void\r
271 (CL_API *cl_pfn_vec_copy_t)(\r
272         IN      void* const                     p_dest,\r
273         IN      const void* const       p_src,\r
274         IN      const size_t            size );\r
275 /*\r
276 * PARAMETERS\r
277 *       p_dest\r
278 *               [in] Pointer to the destination buffer into which to copy p_src.\r
279 *\r
280 *       p_src\r
281 *               [in] Pointer to the destination buffer from which to copy.\r
282 *\r
283 *       size\r
284 *               [in] Number of bytes to copy.\r
285 *\r
286 * RETURN VALUE\r
287 *       This function does not return a value.\r
288 *\r
289 * SEE ALSO\r
290 *       Vector\r
291 *********/\r
292 \r
293 \r
294 /****s* Component Library: Vector/cl_vector_t\r
295 * NAME\r
296 *       cl_vector_t\r
297 *\r
298 * DESCRIPTION\r
299 *       Vector structure.\r
300 *\r
301 *       The cl_vector_t structure should be treated as opaque and should be\r
302 *       manipulated only through the provided functions.\r
303 *\r
304 * SYNOPSIS\r
305 */\r
306 typedef struct _cl_vector\r
307 {\r
308         size_t                          size;\r
309         size_t                          grow_size;\r
310         size_t                          capacity;\r
311         size_t                          element_size;\r
312         cl_pfn_vec_init_t       pfn_init;\r
313         cl_pfn_vec_dtor_t       pfn_dtor;\r
314         cl_pfn_vec_copy_t       pfn_copy;\r
315         const void                      *context;\r
316         cl_qlist_t                      alloc_list;\r
317         void                            **p_ptr_array;\r
318         cl_state_t                      state;\r
319 \r
320 } cl_vector_t;\r
321 /*\r
322 * FIELDS\r
323 *       size\r
324 *                Number of elements successfully initialized in the vector.\r
325 *\r
326 *       grow_size\r
327 *                Number of elements to allocate when growing.\r
328 *\r
329 *       capacity\r
330 *                total # of elements allocated.\r
331 *\r
332 *       element_size\r
333 *                Size of each element.\r
334 *\r
335 *       pfn_init\r
336 *                User supplied element initializer.\r
337 *\r
338 *       pfn_dtor\r
339 *                User supplied element destructor.\r
340 *\r
341 *       pfn_copy\r
342 *                Copy operator.\r
343 *\r
344 *       context\r
345 *                User context for callbacks.\r
346 *\r
347 *       alloc_list\r
348 *                List of allocations.\r
349 *\r
350 *       p_ptr_array\r
351 *                Internal array of pointers to elements.\r
352 *\r
353 *       state\r
354 *               State of the vector.\r
355 *\r
356 * SEE ALSO\r
357 *       Vector\r
358 *********/\r
359 \r
360 \r
361 #ifdef __cplusplus\r
362 extern "C"\r
363 {\r
364 #endif\r
365 \r
366 \r
367 /****f* Component Library: Vector/cl_vector_construct\r
368 * NAME\r
369 *       cl_vector_construct\r
370 *\r
371 * DESCRIPTION\r
372 *       The cl_vector_construct function constructs a vector.\r
373 *\r
374 * SYNOPSIS\r
375 */\r
376 CL_EXPORT void CL_API\r
377 cl_vector_construct(\r
378         IN      cl_vector_t* const      p_vector );\r
379 /*\r
380 * PARAMETERS\r
381 *       p_vector\r
382 *               [in] Pointer to a cl_vector_t structure to construct.\r
383 *\r
384 * RETURN VALUE\r
385 *       This function does not return a value.\r
386 *\r
387 * NOTES\r
388 *       Allows calling cl_vector_destroy without first calling cl_vector_init.\r
389 *\r
390 *       Calling cl_vector_construct is a prerequisite to calling any other\r
391 *       vector function except cl_vector_init.\r
392 *\r
393 * SEE ALSO\r
394 *       Vector, cl_vector_init, cl_vector_destroy\r
395 *********/\r
396 \r
397 \r
398 /****f* Component Library: Vector/cl_vector_init\r
399 * NAME\r
400 *       cl_vector_init\r
401 *\r
402 * DESCRIPTION\r
403 *       The cl_vector_init function initializes a vector for use.\r
404 *\r
405 * SYNOPSIS\r
406 */\r
407 CL_EXPORT cl_status_t CL_API\r
408 cl_vector_init(\r
409         IN      cl_vector_t* const      p_vector,\r
410         IN      const size_t            min_size,\r
411         IN      const size_t            grow_size,\r
412         IN      const size_t            element_size,\r
413         IN      cl_pfn_vec_init_t       pfn_init OPTIONAL,\r
414         IN      cl_pfn_vec_dtor_t       pfn_dtor OPTIONAL,\r
415         IN      const void* const       context );\r
416 /*\r
417 * PARAMETERS\r
418 *       p_vector\r
419 *               [in] Pointer to a cl_vector_t structure to inititalize.\r
420 *\r
421 *       initial_size\r
422 *               [in] Initial number of elements.\r
423 *\r
424 *       grow_size\r
425 *               [in] Number of elements to allocate when incrementally growing\r
426 *               the vector.  A value of zero disables automatic growth.\r
427 *\r
428 *       element_size\r
429 *               [in] Size of each element.\r
430 *\r
431 *       pfn_init\r
432 *               [in] Initializer callback to invoke for every new element.\r
433 *               See the cl_pfn_vec_init_t function type declaration for details about\r
434 *               the callback function.\r
435 *\r
436 *       pfn_dtor\r
437 *               [in] Destructor callback to invoke for elements being deallocated.\r
438 *               See the cl_pfn_vec_dtor_t function type declaration for details about\r
439 *               the callback function.\r
440 *\r
441 *       context\r
442 *               [in] Value to pass to the callback functions to provide context.\r
443 *\r
444 * RETURN VALUES\r
445 *       CL_SUCCESS if the vector was initialized successfully.\r
446 *\r
447 *       CL_INSUFFICIENT_MEMORY if the initialization failed.\r
448 *\r
449 *       cl_status_t value returned by optional initializer function specified by\r
450 *       the pfn_init parameter.\r
451 *\r
452 * NOTES\r
453 *       The constructor and initializer functions, if any, are invoked for every\r
454 *       new element in the array.\r
455 *\r
456 * SEE ALSO\r
457 *       Vector, cl_vector_construct, cl_vector_destroy, cl_vector_set,\r
458 *       cl_vector_get, cl_vector_get_ptr, cl_vector_at\r
459 *********/\r
460 \r
461 \r
462 /****f* Component Library: Vector/cl_vector_destroy\r
463 * NAME\r
464 *       cl_vector_destroy\r
465 *\r
466 * DESCRIPTION\r
467 *       The cl_vector_destroy function destroys a vector.\r
468 *\r
469 * SYNOPSIS\r
470 */\r
471 CL_EXPORT void CL_API\r
472 cl_vector_destroy(\r
473         IN      cl_vector_t* const      p_vector );\r
474 /*\r
475 * PARAMETERS\r
476 *       p_vector\r
477 *               [in] Pointer to a cl_vector_t structure to destroy.\r
478 *\r
479 * RETURN VALUE\r
480 *       This function does not return a value.\r
481 *\r
482 * NOTES\r
483 *       cl_vector_destroy frees all memory allocated for the vector. The vector\r
484 *       is left initialized to a zero capacity and size.\r
485 *\r
486 *       This function should only be called after a call to cl_vector_construct\r
487 *       or cl_vector_init.\r
488 *\r
489 * SEE ALSO\r
490 *       Vector, cl_vector_construct, cl_vector_init\r
491 *********/\r
492 \r
493 \r
494 /****f* Component Library: Vector/cl_vector_get_capacity\r
495 * NAME\r
496 *       cl_vector_get_capacity\r
497 *\r
498 * DESCRIPTION\r
499 *       The cl_vector_get_capacity function returns the capacity of a vector.\r
500 *\r
501 * SYNOPSIS\r
502 */\r
503 CL_INLINE size_t CL_API\r
504 cl_vector_get_capacity(\r
505         IN      const cl_vector_t* const        p_vector )\r
506 {\r
507         CL_ASSERT( p_vector );\r
508         CL_ASSERT( p_vector->state == CL_INITIALIZED );\r
509 \r
510         return( p_vector->capacity );\r
511 }\r
512 /*\r
513 * PARAMETERS\r
514 *       p_vector\r
515 *               [in] Pointer to a cl_vector_t structure whose capacity to return.\r
516 *\r
517 * RETURN VALUE\r
518 *       Capacity, in elements, of the vector.\r
519 *\r
520 * NOTES\r
521 *       The capacity is the number of elements that the vector can store, and\r
522 *       can be greater than the number of elements stored. To get the number of\r
523 *       elements stored in the vector, use cl_vector_get_size.\r
524 *\r
525 * SEE ALSO\r
526 *       Vector, cl_vector_set_capacity, cl_vector_get_size\r
527 *********/\r
528 \r
529 \r
530 /****f* Component Library: Vector/cl_vector_get_size\r
531 * NAME\r
532 *       cl_vector_get_size\r
533 *\r
534 * DESCRIPTION\r
535 *       The cl_vector_get_size function returns the size of a vector.\r
536 *\r
537 * SYNOPSIS\r
538 */\r
539 CL_INLINE size_t CL_API\r
540 cl_vector_get_size(\r
541         IN      const cl_vector_t* const        p_vector )\r
542 {\r
543         CL_ASSERT( p_vector );\r
544         CL_ASSERT( p_vector->state == CL_INITIALIZED );\r
545 \r
546         return( p_vector->size );\r
547 }\r
548 /*\r
549 * PARAMETERS\r
550 *       p_vector\r
551 *               [in] Pointer to a cl_vector_t structure whose size to return.\r
552 *\r
553 * RETURN VALUE\r
554 *       Size, in elements, of the vector.\r
555 *\r
556 * SEE ALSO\r
557 *       Vector, cl_vector_set_size, cl_vector_get_capacity\r
558 *********/\r
559 \r
560 \r
561 /****f* Component Library: Vector/cl_vector_get_ptr\r
562 * NAME\r
563 *       cl_vector_get_ptr\r
564 *\r
565 * DESCRIPTION\r
566 *       The cl_vector_get_ptr function returns a pointer to an element\r
567 *       stored in a vector at a specified index.\r
568 *\r
569 * SYNOPSIS\r
570 */\r
571 CL_INLINE void* CL_API\r
572 cl_vector_get_ptr(\r
573         IN      const cl_vector_t* const        p_vector,\r
574         IN      const size_t                            index )\r
575 {\r
576         CL_ASSERT( p_vector );\r
577         CL_ASSERT( p_vector->state == CL_INITIALIZED );\r
578 \r
579         return( p_vector->p_ptr_array[index] );\r
580 }\r
581 /*\r
582 * PARAMETERS\r
583 *       p_vector\r
584 *               [in] Pointer to a cl_vector_t structure from which to get a\r
585 *               pointer to an element.\r
586 *\r
587 *       index\r
588 *               [in] Index of the element.\r
589 *\r
590 * RETURN VALUE\r
591 *       Pointer to the element stored at specified index.\r
592 *\r
593 * NOTES\r
594 *       cl_vector_get_ptr provides constant access times regardless of the index.\r
595 *\r
596 *       cl_vector_get_ptr does not perform boundary checking. Callers are\r
597 *       responsible for providing an index that is within the range of the vector.\r
598 *\r
599 * SEE ALSO\r
600 *       Vector, cl_vector_get, cl_vector_at, cl_vector_set, cl_vector_get_size\r
601 *********/\r
602 \r
603 \r
604 /****f* Component Library: Vector/cl_vector_get\r
605 * NAME\r
606 *       cl_vector_get\r
607 *\r
608 * DESCRIPTION\r
609 *       The cl_vector_get function copies an element stored in a vector at a\r
610 *       specified index.\r
611 *\r
612 * SYNOPSIS\r
613 */\r
614 CL_INLINE void CL_API\r
615 cl_vector_get(\r
616         IN      const cl_vector_t* const        p_vector,\r
617         IN      const size_t                            index,\r
618         OUT     void* const                                     p_element )\r
619 {\r
620         void *p_src;\r
621 \r
622         CL_ASSERT( p_vector );\r
623         CL_ASSERT( p_vector->state == CL_INITIALIZED );\r
624         CL_ASSERT( p_element );\r
625 \r
626         /* Get a pointer to the element. */\r
627         p_src = cl_vector_get_ptr( p_vector, index );\r
628         p_vector->pfn_copy( p_element, p_src, p_vector->element_size );\r
629 }\r
630 /*\r
631 * PARAMETERS\r
632 *       p_vector\r
633 *               [in] Pointer to a cl_vector_t structure from which to get a copy of\r
634 *               an element.\r
635 *\r
636 *       index\r
637 *               [in] Index of the element.\r
638 *\r
639 *       p_element\r
640 *               [out] Pointer to storage for the element. Contains a copy of the\r
641 *               desired element upon successful completion of the call.\r
642 *\r
643 * RETURN VALUE\r
644 *       This function does not return a value.\r
645 *\r
646 * NOTES\r
647 *       cl_vector_get provides constant time access regardless of the index.\r
648 *\r
649 *       cl_vector_get does not perform boundary checking on the vector, and\r
650 *       callers are responsible for providing an index that is within the range\r
651 *       of the vector. To access elements after performing boundary checks,\r
652 *       use cl_vector_at.\r
653 *\r
654 *       The p_element parameter contains a copy of the desired element upon\r
655 *       return from this function.\r
656 *\r
657 * SEE ALSO\r
658 *       Vector, cl_vector_get_ptr, cl_vector_at\r
659 *********/\r
660 \r
661 \r
662 /****f* Component Library: Vector/cl_vector_at\r
663 * NAME\r
664 *       cl_vector_at\r
665 *\r
666 * DESCRIPTION\r
667 *       The cl_vector_at function copies an element stored in a vector at a\r
668 *       specified index, performing boundary checks.\r
669 *\r
670 * SYNOPSIS\r
671 */\r
672 CL_EXPORT cl_status_t CL_API\r
673 cl_vector_at(\r
674         IN      const cl_vector_t* const        p_vector,\r
675         IN      const size_t                            index,\r
676         OUT     void* const                                     p_element );\r
677 /*\r
678 * PARAMETERS\r
679 *       p_vector\r
680 *               [in] Pointer to a cl_vector_t structure from which to get a copy of\r
681 *               an element.\r
682 *\r
683 *       index\r
684 *               [in] Index of the element.\r
685 *\r
686 *       p_element\r
687 *               [out] Pointer to storage for the element. Contains a copy of the\r
688 *               desired element upon successful completion of the call.\r
689 *\r
690 * RETURN VALUES\r
691 *       CL_SUCCESS if an element was found at the specified index.\r
692 *\r
693 *       CL_INVALID_SETTING if the index was out of range.\r
694 *\r
695 * NOTES\r
696 *       cl_vector_at provides constant time access regardless of the index, and\r
697 *       performs boundary checking on the vector.\r
698 *\r
699 *       Upon success, the p_element parameter contains a copy of the desired element.\r
700 *\r
701 * SEE ALSO\r
702 *       Vector, cl_vector_get, cl_vector_get_ptr\r
703 *********/\r
704 \r
705 \r
706 /****f* Component Library: Vector/cl_vector_set\r
707 * NAME\r
708 *       cl_vector_set\r
709 *\r
710 * DESCRIPTION\r
711 *       The cl_vector_set function sets the element at the specified index.\r
712 *\r
713 * SYNOPSIS\r
714 */\r
715 CL_EXPORT cl_status_t CL_API\r
716 cl_vector_set(\r
717         IN      cl_vector_t* const      p_vector,\r
718         IN      const size_t            index,\r
719         IN      void* const                     p_element );\r
720 /*\r
721 * PARAMETERS\r
722 *       p_vector\r
723 *               [in] Pointer to a cl_vector_t structure into which to store\r
724 *               an element.\r
725 *\r
726 *       index\r
727 *               [in] Index of the element.\r
728 *\r
729 *       p_element\r
730 *               [in] Pointer to an element to store in the vector.\r
731 *\r
732 * RETURN VALUES\r
733 *       CL_SUCCESS if the element was successfully set.\r
734 *\r
735 *       CL_INSUFFICIENT_MEMORY if the vector could not be resized to accommodate\r
736 *       the new element.\r
737 *\r
738 * NOTES\r
739 *       cl_vector_set grows the vector as needed to accommodate the new element,\r
740 *       unless the grow_size parameter passed into the cl_vector_init function\r
741 *       was zero.\r
742 *\r
743 * SEE ALSO\r
744 *       Vector, cl_vector_get\r
745 *********/\r
746 \r
747 \r
748 /****f* Component Library: Vector/cl_vector_set_capacity\r
749 * NAME\r
750 *       cl_vector_set_capacity\r
751 *\r
752 * DESCRIPTION\r
753 *       The cl_vector_set_capacity function reserves memory in a vector for a\r
754 *       specified number of elements.\r
755 *\r
756 * SYNOPSIS\r
757 */\r
758 CL_EXPORT cl_status_t CL_API\r
759 cl_vector_set_capacity(\r
760         IN      cl_vector_t* const      p_vector,\r
761         IN      const size_t            new_capacity );\r
762 /*\r
763 * PARAMETERS\r
764 *       p_vector\r
765 *               [in] Pointer to a cl_vector_t structure whose capacity to set.\r
766 *\r
767 *       new_capacity\r
768 *               [in] Total number of elements for which the vector should\r
769 *               allocate memory.\r
770 *\r
771 * RETURN VALUES\r
772 *       CL_SUCCESS if the capacity was successfully set.\r
773 *\r
774 *       CL_INSUFFICIENT_MEMORY if there was not enough memory to satisfy the\r
775 *       operation. The vector is left unchanged.\r
776 *\r
777 * NOTES\r
778 *       cl_vector_set_capacity increases the capacity of the vector. It does\r
779 *       not change the size of the vector. If the requested capacity is less\r
780 *       than the current capacity, the vector is left unchanged.\r
781 *\r
782 * SEE ALSO\r
783 *       Vector, cl_vector_get_capacity, cl_vector_set_size,\r
784 *       cl_vector_set_min_size\r
785 *********/\r
786 \r
787 \r
788 /****f* Component Library: Vector/cl_vector_set_size\r
789 * NAME\r
790 *       cl_vector_set_size\r
791 *\r
792 * DESCRIPTION\r
793 *       The cl_vector_set_size function resizes a vector, either increasing or\r
794 *       decreasing its size.\r
795 *\r
796 * SYNOPSIS\r
797 */\r
798 CL_EXPORT cl_status_t CL_API\r
799 cl_vector_set_size(\r
800         IN      cl_vector_t* const      p_vector,\r
801         IN      const size_t            size );\r
802 /*\r
803 * PARAMETERS\r
804 *       p_vector\r
805 *               [in] Pointer to a cl_vector_t structure whose size to set.\r
806 *\r
807 *       size\r
808 *               [in] Number of elements desired in the vector.\r
809 *\r
810 * RETURN VALUES\r
811 *       CL_SUCCESS if the size of the vector was set successfully.\r
812 *\r
813 *       CL_INSUFFICIENT_MEMORY if there was not enough memory to complete the\r
814 *       operation. The vector is left unchanged.\r
815 *\r
816 * NOTES\r
817 *       cl_vector_set_size sets the vector to the specified size. If size is\r
818 *       smaller than the current size of the vector, the size is reduced.\r
819 *       The destructor function, if any, will be invoked for all elements that\r
820 *       are above size. Likewise, the constructor and initializer, if any, will\r
821 *       be invoked for all new elements.\r
822 *\r
823 *       This function can only fail if size is larger than the current capacity.\r
824 *\r
825 * SEE ALSO\r
826 *       Vector, cl_vector_get_size, cl_vector_set_min_size,\r
827 *       cl_vector_set_capacity\r
828 *********/\r
829 \r
830 \r
831 /****f* Component Library: Vector/cl_vector_set_min_size\r
832 * NAME\r
833 *       cl_vector_set_min_size\r
834 *\r
835 * DESCRIPTION\r
836 *       The cl_vector_set_min_size function resizes a vector to a specified size\r
837 *       if the vector is smaller than the specified size.\r
838 *\r
839 * SYNOPSIS\r
840 */\r
841 CL_EXPORT cl_status_t CL_API\r
842 cl_vector_set_min_size(\r
843         IN      cl_vector_t* const      p_vector,\r
844         IN      const size_t            min_size );\r
845 /*\r
846 * PARAMETERS\r
847 *       p_vector\r
848 *               [in] Pointer to a cl_vector_t structure whose minimum size to set.\r
849 *\r
850 *       min_size\r
851 *               [in] Minimum number of elements that the vector should contain.\r
852 *\r
853 * RETURN VALUES\r
854 *       CL_SUCCESS if the vector size is greater than or equal to min_size.  This\r
855 *       could indicate that the vector's capacity was increased to min_size or\r
856 *       that the vector was already of sufficient size.\r
857 *\r
858 *       CL_INSUFFICIENT_MEMORY if there was not enough memory to resize the vector.\r
859 *       The vector is left unchanged.\r
860 *\r
861 * NOTES\r
862 *       If min_size is smaller than the current size of the vector, the vector is\r
863 *       unchanged. The vector is unchanged if the size could not be changed due\r
864 *       to insufficient memory being available to perform the operation.\r
865 *\r
866 * SEE ALSO\r
867 *       Vector, cl_vector_get_size, cl_vector_set_size, cl_vector_set_capacity\r
868 *********/\r
869 \r
870 \r
871 /****f* Component Library: Vector/cl_vector_apply_func\r
872 * NAME\r
873 *       cl_vector_apply_func\r
874 *\r
875 * DESCRIPTION\r
876 *       The cl_vector_apply_func function invokes a specified function for every\r
877 *       element in a vector.\r
878 *\r
879 * SYNOPSIS\r
880 */\r
881 CL_EXPORT void CL_API\r
882 cl_vector_apply_func(\r
883         IN      const cl_vector_t* const        p_vector,\r
884         IN      cl_pfn_vec_apply_t                      pfn_callback,\r
885         IN      const void* const                       context );\r
886 /*\r
887 * PARAMETERS\r
888 *       p_vector\r
889 *               [in] Pointer to a cl_vector_t structure whose elements to iterate.\r
890 *\r
891 *       pfn_callback\r
892 *               [in] Function invoked for every element in the array.\r
893 *               See the cl_pfn_vec_apply_t function type declaration for details\r
894 *               about the callback function.\r
895 *\r
896 *       context\r
897 *               [in] Value to pass to the callback function.\r
898 *\r
899 * RETURN VALUE\r
900 *       This function does not return a value.\r
901 *\r
902 * NOTES\r
903 *       cl_vector_apply_func invokes the specified function for every element\r
904 *       in the vector, starting from the beginning of the vector.\r
905 *\r
906 * SEE ALSO\r
907 *       Vector, cl_vector_find_from_start, cl_vector_find_from_end,\r
908 *       cl_pfn_vec_apply_t\r
909 *********/\r
910 \r
911 \r
912 /****f* Component Library: Vector/cl_vector_find_from_start\r
913 * NAME\r
914 *       cl_vector_find_from_start\r
915 *\r
916 * DESCRIPTION\r
917 *       The cl_vector_find_from_start function uses a specified function to\r
918 *       search for elements in a vector starting from the lowest index.\r
919 *\r
920 * SYNOPSIS\r
921 */\r
922 CL_EXPORT size_t CL_API\r
923 cl_vector_find_from_start(\r
924         IN      const cl_vector_t* const        p_vector,\r
925         IN      cl_pfn_vec_find_t                       pfn_callback,\r
926         IN      const void* const                       context );\r
927 /*\r
928 * PARAMETERS\r
929 *       p_vector\r
930 *               [in] Pointer to a cl_vector_t structure to inititalize.\r
931 *\r
932 *       pfn_callback\r
933 *               [in] Function invoked to determine if a match was found.\r
934 *               See the cl_pfn_vec_find_t function type declaration for details\r
935 *               about the callback function.\r
936 *\r
937 *       context\r
938 *               [in] Value to pass to the callback function.\r
939 *\r
940 * RETURN VALUES\r
941 *       Index of the element, if found.\r
942 *\r
943 *       Size of the vector if the element was not found.\r
944 *\r
945 * NOTES\r
946 *       cl_vector_find_from_start does not remove the found element from\r
947 *       the vector. The index of the element is returned when the function\r
948 *       provided by the pfn_callback parameter returns CL_SUCCESS.\r
949 *\r
950 * SEE ALSO\r
951 *       Vector, cl_vector_find_from_end, cl_vector_apply_func, cl_pfn_vec_find_t\r
952 *********/\r
953 \r
954 \r
955 /****f* Component Library: Vector/cl_vector_find_from_end\r
956 * NAME\r
957 *       cl_vector_find_from_end\r
958 *\r
959 * DESCRIPTION\r
960 *       The cl_vector_find_from_end function uses a specified function to search\r
961 *       for elements in a vector starting from the highest index.\r
962 *\r
963 * SYNOPSIS\r
964 */\r
965 CL_EXPORT size_t CL_API\r
966 cl_vector_find_from_end(\r
967         IN      const cl_vector_t* const        p_vector,\r
968         IN      cl_pfn_vec_find_t                       pfn_callback,\r
969         IN      const void* const                       context );\r
970 /*\r
971 * PARAMETERS\r
972 *       p_vector\r
973 *               [in] Pointer to a cl_vector_t structure to inititalize.\r
974 *\r
975 *       pfn_callback\r
976 *               [in] Function invoked to determine if a match was found.\r
977 *               See the cl_pfn_vec_find_t function type declaration for details\r
978 *               about the callback function.\r
979 *\r
980 *       context\r
981 *               [in] Value to pass to the callback function.\r
982 *\r
983 * RETURN VALUES\r
984 *       Index of the element, if found.\r
985 *\r
986 *       Size of the vector if the element was not found.\r
987 *\r
988 * NOTES\r
989 *       cl_vector_find_from_end does not remove the found element from\r
990 *       the vector. The index of the element is returned when the function\r
991 *       provided by the pfn_callback parameter returns CL_SUCCESS.\r
992 *\r
993 * SEE ALSO\r
994 *       Vector, cl_vector_find_from_start, cl_vector_apply_func,\r
995 *       cl_pfn_vec_find_t\r
996 *********/\r
997 \r
998 \r
999 #ifdef __cplusplus\r
1000 }       /* extern "C" */\r
1001 #endif\r
1002 \r
1003 \r
1004 #endif  /* _CL_VECTOR_H_ */\r