1219820Sjeff/* 2219820Sjeff * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved. 3219820Sjeff * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4219820Sjeff * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5219820Sjeff * 6219820Sjeff * This software is available to you under a choice of one of two 7219820Sjeff * licenses. You may choose to be licensed under the terms of the GNU 8219820Sjeff * General Public License (GPL) Version 2, available from the file 9219820Sjeff * COPYING in the main directory of this source tree, or the 10219820Sjeff * OpenIB.org BSD license below: 11219820Sjeff * 12219820Sjeff * Redistribution and use in source and binary forms, with or 13219820Sjeff * without modification, are permitted provided that the following 14219820Sjeff * conditions are met: 15219820Sjeff * 16219820Sjeff * - Redistributions of source code must retain the above 17219820Sjeff * copyright notice, this list of conditions and the following 18219820Sjeff * disclaimer. 19219820Sjeff * 20219820Sjeff * - Redistributions in binary form must reproduce the above 21219820Sjeff * copyright notice, this list of conditions and the following 22219820Sjeff * disclaimer in the documentation and/or other materials 23219820Sjeff * provided with the distribution. 24219820Sjeff * 25219820Sjeff * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26219820Sjeff * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27219820Sjeff * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28219820Sjeff * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29219820Sjeff * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30219820Sjeff * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31219820Sjeff * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32219820Sjeff * SOFTWARE. 33219820Sjeff * 34219820Sjeff */ 35219820Sjeff 36219820Sjeff/* 37219820Sjeff * Abstract: 38219820Sjeff * This file contains vector definitions. Vector provides dynmically 39219820Sjeff * resizable array functionality. Objects in a Vector are not relocated 40219820Sjeff * when the array is resized. 41219820Sjeff */ 42219820Sjeff 43219820Sjeff#ifndef _CL_VECTOR_H_ 44219820Sjeff#define _CL_VECTOR_H_ 45219820Sjeff 46219820Sjeff#include <complib/cl_qlist.h> 47219820Sjeff 48219820Sjeff#ifdef __cplusplus 49219820Sjeff# define BEGIN_C_DECLS extern "C" { 50219820Sjeff# define END_C_DECLS } 51219820Sjeff#else /* !__cplusplus */ 52219820Sjeff# define BEGIN_C_DECLS 53219820Sjeff# define END_C_DECLS 54219820Sjeff#endif /* __cplusplus */ 55219820Sjeff 56219820SjeffBEGIN_C_DECLS 57219820Sjeff/****h* Component Library/Vector 58219820Sjeff* NAME 59219820Sjeff* Vector 60219820Sjeff* 61219820Sjeff* DESCRIPTION 62219820Sjeff* The Vector is a self-sizing array. Like a traditonal array, a vector 63219820Sjeff* allows efficient constant time access to elements with a specified index. 64219820Sjeff* A vector grows transparently as the user adds elements to the array. 65219820Sjeff* 66219820Sjeff* As the vector grows in size, it does not relocate existing elements in 67219820Sjeff* memory. This allows using pointers to elements stored in a Vector. 68219820Sjeff* 69219820Sjeff* Users can supply an initializer functions that allow a vector to ensure 70219820Sjeff* that new items added to the vector are properly initialized. A vector 71219820Sjeff* calls the initializer function on a per object basis when growing the 72219820Sjeff* array. The initializer is optional. 73219820Sjeff* 74219820Sjeff* The initializer function can fail, and returns a cl_status_t. The vector 75219820Sjeff* will call the destructor function, if provided, for an element that 76219820Sjeff* failed initialization. If an initializer fails, a vector does not call 77219820Sjeff* the initializer for objects in the remainder of the new memory allocation. 78219820Sjeff* 79219820Sjeff* The cl_vector_t structure should be treated as opaque and should be 80219820Sjeff* manipulated only through the provided functions. 81219820Sjeff* 82219820Sjeff* SEE ALSO 83219820Sjeff* Structures: 84219820Sjeff* cl_vector_t 85219820Sjeff* 86219820Sjeff* Callbacks: 87219820Sjeff* cl_pfn_vec_init_t, cl_pfn_vec_dtor_t, cl_pfn_vec_apply_t, 88219820Sjeff* cl_pfn_vec_find_t 89219820Sjeff* 90219820Sjeff* Item Manipulation: 91219820Sjeff* cl_vector_set_obj, cl_vector_obj 92219820Sjeff* 93219820Sjeff* Initialization: 94219820Sjeff* cl_vector_construct, cl_vector_init, cl_vector_destroy 95219820Sjeff* 96219820Sjeff* Manipulation: 97219820Sjeff* cl_vector_get_capacity, cl_vector_set_capacity, 98219820Sjeff* cl_vector_get_size, cl_vector_set_size, cl_vector_set_min_size 99219820Sjeff* cl_vector_get_ptr, cl_vector_get, cl_vector_at, cl_vector_set 100219820Sjeff* 101219820Sjeff* Search: 102219820Sjeff* cl_vector_find_from_start, cl_vector_find_from_end 103219820Sjeff* cl_vector_apply_func 104219820Sjeff*********/ 105219820Sjeff/****d* Component Library: Vector/cl_pfn_vec_init_t 106219820Sjeff* NAME 107219820Sjeff* cl_pfn_vec_init_t 108219820Sjeff* 109219820Sjeff* DESCRIPTION 110219820Sjeff* The cl_pfn_vec_init_t function type defines the prototype for functions 111219820Sjeff* used as initializer for elements being allocated by a vector. 112219820Sjeff* 113219820Sjeff* SYNOPSIS 114219820Sjeff*/ 115219820Sjefftypedef cl_status_t 116219820Sjeff (*cl_pfn_vec_init_t) (IN void *const p_element, IN void *context); 117219820Sjeff/* 118219820Sjeff* PARAMETERS 119219820Sjeff* p_element 120219820Sjeff* [in] Pointer to an element being added to a vector. 121219820Sjeff* 122219820Sjeff* context 123219820Sjeff* [in] Context provided in a call to cl_vector_init. 124219820Sjeff* 125219820Sjeff* RETURN VALUES 126219820Sjeff* Return CL_SUCCESS to indicate that the element was initialized successfully. 127219820Sjeff* 128219820Sjeff* Other cl_status_t values will be returned by the cl_vector_init, 129219820Sjeff* cl_vector_set_size, and cl_vector_set_min_size functions. 130219820Sjeff* 131219820Sjeff* In situations where the vector's size needs to grows in order to satisfy 132219820Sjeff* a call to cl_vector_set, a non-successful status returned by the 133219820Sjeff* initializer callback causes the growth to stop. 134219820Sjeff* 135219820Sjeff* NOTES 136219820Sjeff* This function type is provided as function prototype reference for 137219820Sjeff* the initializer function provided by users as an optional parameter to 138219820Sjeff* the cl_vector_init function. 139219820Sjeff* 140219820Sjeff* SEE ALSO 141219820Sjeff* Vector, cl_vector_init 142219820Sjeff*********/ 143219820Sjeff 144219820Sjeff/****d* Component Library: Vector/cl_pfn_vec_dtor_t 145219820Sjeff* NAME 146219820Sjeff* cl_pfn_vec_dtor_t 147219820Sjeff* 148219820Sjeff* DESCRIPTION 149219820Sjeff* The cl_pfn_vec_dtor_t function type defines the prototype for functions 150219820Sjeff* used as destructor for elements being deallocated from a vector. 151219820Sjeff* 152219820Sjeff* SYNOPSIS 153219820Sjeff*/ 154219820Sjefftypedef void 155219820Sjeff (*cl_pfn_vec_dtor_t) (IN void *const p_element, IN void *context); 156219820Sjeff/* 157219820Sjeff* PARAMETERS 158219820Sjeff* p_element 159219820Sjeff* [in] Pointer to an element being deallocated from a vector. 160219820Sjeff* 161219820Sjeff* context 162219820Sjeff* [in] Context provided in a call to cl_vector_init. 163219820Sjeff* 164219820Sjeff* RETURN VALUE 165219820Sjeff* This function does not return a value. 166219820Sjeff* 167219820Sjeff* NOTES 168219820Sjeff* This function type is provided as function prototype reference for 169219820Sjeff* the destructor function provided by users as an optional parameter to 170219820Sjeff* the cl_vector_init function. 171219820Sjeff* 172219820Sjeff* SEE ALSO 173219820Sjeff* Vector, cl_vector_init 174219820Sjeff*********/ 175219820Sjeff 176219820Sjeff/****d* Component Library: Vector/cl_pfn_vec_apply_t 177219820Sjeff* NAME 178219820Sjeff* cl_pfn_vec_apply_t 179219820Sjeff* 180219820Sjeff* DESCRIPTION 181219820Sjeff* The cl_pfn_vec_apply_t function type defines the prototype for functions 182219820Sjeff* used to iterate elements in a vector. 183219820Sjeff* 184219820Sjeff* SYNOPSIS 185219820Sjeff*/ 186219820Sjefftypedef void 187219820Sjeff (*cl_pfn_vec_apply_t) (IN const size_t index, 188219820Sjeff IN void *const p_element, IN void *context); 189219820Sjeff/* 190219820Sjeff* PARAMETERS 191219820Sjeff* index 192219820Sjeff* [in] Index of the element. 193219820Sjeff* 194219820Sjeff* p_element 195219820Sjeff* [in] Pointer to an element at the specified index in the vector. 196219820Sjeff* 197219820Sjeff* context 198219820Sjeff* [in] Context provided in a call to cl_vector_apply_func. 199219820Sjeff* 200219820Sjeff* RETURN VALUE 201219820Sjeff* This function does not return a value. 202219820Sjeff* 203219820Sjeff* NOTES 204219820Sjeff* This function type is provided as function prototype reference for 205219820Sjeff* the function passed by users as a parameter to the cl_vector_apply_func 206219820Sjeff* function. 207219820Sjeff* 208219820Sjeff* SEE ALSO 209219820Sjeff* Vector, cl_vector_apply_func 210219820Sjeff*********/ 211219820Sjeff 212219820Sjeff/****d* Component Library: Vector/cl_pfn_vec_find_t 213219820Sjeff* NAME 214219820Sjeff* cl_pfn_vec_find_t 215219820Sjeff* 216219820Sjeff* DESCRIPTION 217219820Sjeff* The cl_pfn_vec_find_t function type defines the prototype for functions 218219820Sjeff* used to find elements in a vector. 219219820Sjeff* 220219820Sjeff* SYNOPSIS 221219820Sjeff*/ 222219820Sjefftypedef cl_status_t 223219820Sjeff (*cl_pfn_vec_find_t) (IN const size_t index, 224219820Sjeff IN const void *const p_element, IN void *context); 225219820Sjeff/* 226219820Sjeff* PARAMETERS 227219820Sjeff* index 228219820Sjeff* [in] Index of the element. 229219820Sjeff* 230219820Sjeff* p_element 231219820Sjeff* [in] Pointer to an element at the specified index in the vector. 232219820Sjeff* 233219820Sjeff* context 234219820Sjeff* [in] Context provided in a call to cl_vector_find_from_start or 235219820Sjeff* cl_vector_find_from_end. 236219820Sjeff* 237219820Sjeff* RETURN VALUES 238219820Sjeff* Return CL_SUCCESS if the element was found. This stops vector iteration. 239219820Sjeff* 240219820Sjeff* CL_NOT_FOUND to continue the vector iteration. 241219820Sjeff* 242219820Sjeff* NOTES 243219820Sjeff* This function type is provided as function prototype reference for the 244219820Sjeff* function provided by users as a parameter to the cl_vector_find_from_start 245219820Sjeff* and cl_vector_find_from_end functions. 246219820Sjeff* 247219820Sjeff* SEE ALSO 248219820Sjeff* Vector, cl_vector_find_from_start, cl_vector_find_from_end 249219820Sjeff*********/ 250219820Sjeff 251219820Sjeff/****i* Component Library: Vector/cl_pfn_vec_copy_t 252219820Sjeff* NAME 253219820Sjeff* cl_pfn_vec_copy_t 254219820Sjeff* 255219820Sjeff* DESCRIPTION 256219820Sjeff* The cl_pfn_vec_copy_t function type defines the prototype for functions 257219820Sjeff* used to copy elements in a vector. 258219820Sjeff* 259219820Sjeff* SYNOPSIS 260219820Sjeff*/ 261219820Sjefftypedef void 262219820Sjeff (*cl_pfn_vec_copy_t) (IN void *const p_dest, 263219820Sjeff IN const void *const p_src, IN const size_t size); 264219820Sjeff/* 265219820Sjeff* PARAMETERS 266219820Sjeff* p_dest 267219820Sjeff* [in] Pointer to the destination buffer into which to copy p_src. 268219820Sjeff* 269219820Sjeff* p_src 270219820Sjeff* [in] Pointer to the destination buffer from which to copy. 271219820Sjeff* 272219820Sjeff* size 273219820Sjeff* [in] Number of bytes to copy. 274219820Sjeff* 275219820Sjeff* RETURN VALUE 276219820Sjeff* This function does not return a value. 277219820Sjeff* 278219820Sjeff* SEE ALSO 279219820Sjeff* Vector 280219820Sjeff*********/ 281219820Sjeff 282219820Sjeff/****s* Component Library: Vector/cl_vector_t 283219820Sjeff* NAME 284219820Sjeff* cl_vector_t 285219820Sjeff* 286219820Sjeff* DESCRIPTION 287219820Sjeff* Vector structure. 288219820Sjeff* 289219820Sjeff* The cl_vector_t structure should be treated as opaque and should be 290219820Sjeff* manipulated only through the provided functions. 291219820Sjeff* 292219820Sjeff* SYNOPSIS 293219820Sjeff*/ 294219820Sjefftypedef struct _cl_vector { 295219820Sjeff size_t size; 296219820Sjeff size_t grow_size; 297219820Sjeff size_t capacity; 298219820Sjeff size_t element_size; 299219820Sjeff cl_pfn_vec_init_t pfn_init; 300219820Sjeff cl_pfn_vec_dtor_t pfn_dtor; 301219820Sjeff cl_pfn_vec_copy_t pfn_copy; 302219820Sjeff const void *context; 303219820Sjeff cl_qlist_t alloc_list; 304219820Sjeff void **p_ptr_array; 305219820Sjeff cl_state_t state; 306219820Sjeff} cl_vector_t; 307219820Sjeff/* 308219820Sjeff* FIELDS 309219820Sjeff* size 310219820Sjeff* Number of elements successfully initialized in the vector. 311219820Sjeff* 312219820Sjeff* grow_size 313219820Sjeff* Number of elements to allocate when growing. 314219820Sjeff* 315219820Sjeff* capacity 316219820Sjeff* total # of elements allocated. 317219820Sjeff* 318219820Sjeff* element_size 319219820Sjeff* Size of each element. 320219820Sjeff* 321219820Sjeff* pfn_init 322219820Sjeff* User supplied element initializer. 323219820Sjeff* 324219820Sjeff* pfn_dtor 325219820Sjeff* User supplied element destructor. 326219820Sjeff* 327219820Sjeff* pfn_copy 328219820Sjeff* Copy operator. 329219820Sjeff* 330219820Sjeff* context 331219820Sjeff* User context for callbacks. 332219820Sjeff* 333219820Sjeff* alloc_list 334219820Sjeff* List of allocations. 335219820Sjeff* 336219820Sjeff* p_ptr_array 337219820Sjeff* Internal array of pointers to elements. 338219820Sjeff* 339219820Sjeff* state 340219820Sjeff* State of the vector. 341219820Sjeff* 342219820Sjeff* SEE ALSO 343219820Sjeff* Vector 344219820Sjeff*********/ 345219820Sjeff 346219820Sjeff/****f* Component Library: Vector/cl_vector_construct 347219820Sjeff* NAME 348219820Sjeff* cl_vector_construct 349219820Sjeff* 350219820Sjeff* DESCRIPTION 351219820Sjeff* The cl_vector_construct function constructs a vector. 352219820Sjeff* 353219820Sjeff* SYNOPSIS 354219820Sjeff*/ 355219820Sjeffvoid cl_vector_construct(IN cl_vector_t * const p_vector); 356219820Sjeff/* 357219820Sjeff* PARAMETERS 358219820Sjeff* p_vector 359219820Sjeff* [in] Pointer to a cl_vector_t structure to construct. 360219820Sjeff* 361219820Sjeff* RETURN VALUE 362219820Sjeff* This function does not return a value. 363219820Sjeff* 364219820Sjeff* NOTES 365219820Sjeff* Allows calling cl_vector_destroy without first calling cl_vector_init. 366219820Sjeff* 367219820Sjeff* Calling cl_vector_construct is a prerequisite to calling any other 368219820Sjeff* vector function except cl_vector_init. 369219820Sjeff* 370219820Sjeff* SEE ALSO 371219820Sjeff* Vector, cl_vector_init, cl_vector_destroy 372219820Sjeff*********/ 373219820Sjeff 374219820Sjeff/****f* Component Library: Vector/cl_vector_init 375219820Sjeff* NAME 376219820Sjeff* cl_vector_init 377219820Sjeff* 378219820Sjeff* DESCRIPTION 379219820Sjeff* The cl_vector_init function initializes a vector for use. 380219820Sjeff* 381219820Sjeff* SYNOPSIS 382219820Sjeff*/ 383219820Sjeffcl_status_t 384219820Sjeffcl_vector_init(IN cl_vector_t * const p_vector, 385219820Sjeff IN const size_t min_size, 386219820Sjeff IN const size_t grow_size, 387219820Sjeff IN const size_t element_size, 388219820Sjeff IN cl_pfn_vec_init_t pfn_init OPTIONAL, 389219820Sjeff IN cl_pfn_vec_dtor_t pfn_dtor OPTIONAL, 390219820Sjeff IN const void *const context); 391219820Sjeff/* 392219820Sjeff* PARAMETERS 393219820Sjeff* p_vector 394219820Sjeff* [in] Pointer to a cl_vector_t structure to inititalize. 395219820Sjeff* 396219820Sjeff* initial_size 397219820Sjeff* [in] Initial number of elements. 398219820Sjeff* 399219820Sjeff* grow_size 400219820Sjeff* [in] Number of elements to allocate when incrementally growing 401219820Sjeff* the vector. A value of zero disables automatic growth. 402219820Sjeff* 403219820Sjeff* element_size 404219820Sjeff* [in] Size of each element. 405219820Sjeff* 406219820Sjeff* pfn_init 407219820Sjeff* [in] Initializer callback to invoke for every new element. 408219820Sjeff* See the cl_pfn_vec_init_t function type declaration for details about 409219820Sjeff* the callback function. 410219820Sjeff* 411219820Sjeff* pfn_dtor 412219820Sjeff* [in] Destructor callback to invoke for elements being deallocated. 413219820Sjeff* See the cl_pfn_vec_dtor_t function type declaration for details about 414219820Sjeff* the callback function. 415219820Sjeff* 416219820Sjeff* context 417219820Sjeff* [in] Value to pass to the callback functions to provide context. 418219820Sjeff* 419219820Sjeff* RETURN VALUES 420219820Sjeff* CL_SUCCESS if the vector was initialized successfully. 421219820Sjeff* 422219820Sjeff* CL_INSUFFICIENT_MEMORY if the initialization failed. 423219820Sjeff* 424219820Sjeff* cl_status_t value returned by optional initializer function specified by 425219820Sjeff* the pfn_init parameter. 426219820Sjeff* 427219820Sjeff* NOTES 428219820Sjeff* The constructor and initializer functions, if any, are invoked for every 429219820Sjeff* new element in the array. 430219820Sjeff* 431219820Sjeff* SEE ALSO 432219820Sjeff* Vector, cl_vector_construct, cl_vector_destroy, cl_vector_set, 433219820Sjeff* cl_vector_get, cl_vector_get_ptr, cl_vector_at 434219820Sjeff*********/ 435219820Sjeff 436219820Sjeff/****f* Component Library: Vector/cl_vector_destroy 437219820Sjeff* NAME 438219820Sjeff* cl_vector_destroy 439219820Sjeff* 440219820Sjeff* DESCRIPTION 441219820Sjeff* The cl_vector_destroy function destroys a vector. 442219820Sjeff* 443219820Sjeff* SYNOPSIS 444219820Sjeff*/ 445219820Sjeffvoid cl_vector_destroy(IN cl_vector_t * const p_vector); 446219820Sjeff/* 447219820Sjeff* PARAMETERS 448219820Sjeff* p_vector 449219820Sjeff* [in] Pointer to a cl_vector_t structure to destroy. 450219820Sjeff* 451219820Sjeff* RETURN VALUE 452219820Sjeff* This function does not return a value. 453219820Sjeff* 454219820Sjeff* NOTES 455219820Sjeff* cl_vector_destroy frees all memory allocated for the vector. The vector 456219820Sjeff* is left initialized to a zero capacity and size. 457219820Sjeff* 458219820Sjeff* This function should only be called after a call to cl_vector_construct 459219820Sjeff* or cl_vector_init. 460219820Sjeff* 461219820Sjeff* SEE ALSO 462219820Sjeff* Vector, cl_vector_construct, cl_vector_init 463219820Sjeff*********/ 464219820Sjeff 465219820Sjeff/****f* Component Library: Vector/cl_vector_get_capacity 466219820Sjeff* NAME 467219820Sjeff* cl_vector_get_capacity 468219820Sjeff* 469219820Sjeff* DESCRIPTION 470219820Sjeff* The cl_vector_get_capacity function returns the capacity of a vector. 471219820Sjeff* 472219820Sjeff* SYNOPSIS 473219820Sjeff*/ 474219820Sjeffstatic inline size_t 475219820Sjeffcl_vector_get_capacity(IN const cl_vector_t * const p_vector) 476219820Sjeff{ 477219820Sjeff CL_ASSERT(p_vector); 478219820Sjeff CL_ASSERT(p_vector->state == CL_INITIALIZED); 479219820Sjeff 480219820Sjeff return (p_vector->capacity); 481219820Sjeff} 482219820Sjeff 483219820Sjeff/* 484219820Sjeff* PARAMETERS 485219820Sjeff* p_vector 486219820Sjeff* [in] Pointer to a cl_vector_t structure whose capacity to return. 487219820Sjeff* 488219820Sjeff* RETURN VALUE 489219820Sjeff* Capacity, in elements, of the vector. 490219820Sjeff* 491219820Sjeff* NOTES 492219820Sjeff* The capacity is the number of elements that the vector can store, and 493219820Sjeff* can be greater than the number of elements stored. To get the number of 494219820Sjeff* elements stored in the vector, use cl_vector_get_size. 495219820Sjeff* 496219820Sjeff* SEE ALSO 497219820Sjeff* Vector, cl_vector_set_capacity, cl_vector_get_size 498219820Sjeff*********/ 499219820Sjeff 500219820Sjeff/****f* Component Library: Vector/cl_vector_get_size 501219820Sjeff* NAME 502219820Sjeff* cl_vector_get_size 503219820Sjeff* 504219820Sjeff* DESCRIPTION 505219820Sjeff* The cl_vector_get_size function returns the size of a vector. 506219820Sjeff* 507219820Sjeff* SYNOPSIS 508219820Sjeff*/ 509219820Sjeffstatic inline size_t cl_vector_get_size(IN const cl_vector_t * const p_vector) 510219820Sjeff{ 511219820Sjeff CL_ASSERT(p_vector); 512219820Sjeff CL_ASSERT(p_vector->state == CL_INITIALIZED); 513219820Sjeff 514219820Sjeff return (p_vector->size); 515219820Sjeff} 516219820Sjeff 517219820Sjeff/* 518219820Sjeff* PARAMETERS 519219820Sjeff* p_vector 520219820Sjeff* [in] Pointer to a cl_vector_t structure whose size to return. 521219820Sjeff* 522219820Sjeff* RETURN VALUE 523219820Sjeff* Size, in elements, of the vector. 524219820Sjeff* 525219820Sjeff* SEE ALSO 526219820Sjeff* Vector, cl_vector_set_size, cl_vector_get_capacity 527219820Sjeff*********/ 528219820Sjeff 529219820Sjeff/****f* Component Library: Vector/cl_vector_get_ptr 530219820Sjeff* NAME 531219820Sjeff* cl_vector_get_ptr 532219820Sjeff* 533219820Sjeff* DESCRIPTION 534219820Sjeff* The cl_vector_get_ptr function returns a pointer to an element 535219820Sjeff* stored in a vector at a specified index. 536219820Sjeff* 537219820Sjeff* SYNOPSIS 538219820Sjeff*/ 539219820Sjeffstatic inline void *cl_vector_get_ptr(IN const cl_vector_t * const p_vector, 540219820Sjeff IN const size_t index) 541219820Sjeff{ 542219820Sjeff CL_ASSERT(p_vector); 543219820Sjeff CL_ASSERT(p_vector->state == CL_INITIALIZED); 544219820Sjeff 545219820Sjeff return (p_vector->p_ptr_array[index]); 546219820Sjeff} 547219820Sjeff 548219820Sjeff/* 549219820Sjeff* PARAMETERS 550219820Sjeff* p_vector 551219820Sjeff* [in] Pointer to a cl_vector_t structure from which to get a 552219820Sjeff* pointer to an element. 553219820Sjeff* 554219820Sjeff* index 555219820Sjeff* [in] Index of the element. 556219820Sjeff* 557219820Sjeff* RETURN VALUE 558219820Sjeff* Pointer to the element stored at specified index. 559219820Sjeff* 560219820Sjeff* NOTES 561219820Sjeff* cl_vector_get_ptr provides constant access times regardless of the index. 562219820Sjeff* 563219820Sjeff* cl_vector_get_ptr does not perform boundary checking. Callers are 564219820Sjeff* responsible for providing an index that is within the range of the vector. 565219820Sjeff* 566219820Sjeff* SEE ALSO 567219820Sjeff* Vector, cl_vector_get, cl_vector_at, cl_vector_set, cl_vector_get_size 568219820Sjeff*********/ 569219820Sjeff 570219820Sjeff/****f* Component Library: Vector/cl_vector_get 571219820Sjeff* NAME 572219820Sjeff* cl_vector_get 573219820Sjeff* 574219820Sjeff* DESCRIPTION 575219820Sjeff* The cl_vector_get function copies an element stored in a vector at a 576219820Sjeff* specified index. 577219820Sjeff* 578219820Sjeff* SYNOPSIS 579219820Sjeff*/ 580219820Sjeffstatic inline void 581219820Sjeffcl_vector_get(IN const cl_vector_t * const p_vector, 582219820Sjeff IN const size_t index, OUT void *const p_element) 583219820Sjeff{ 584219820Sjeff void *p_src; 585219820Sjeff 586219820Sjeff CL_ASSERT(p_vector); 587219820Sjeff CL_ASSERT(p_vector->state == CL_INITIALIZED); 588219820Sjeff CL_ASSERT(p_element); 589219820Sjeff 590219820Sjeff /* Get a pointer to the element. */ 591219820Sjeff p_src = cl_vector_get_ptr(p_vector, index); 592219820Sjeff p_vector->pfn_copy(p_src, p_element, p_vector->element_size); 593219820Sjeff} 594219820Sjeff 595219820Sjeff/* 596219820Sjeff* PARAMETERS 597219820Sjeff* p_vector 598219820Sjeff* [in] Pointer to a cl_vector_t structure from which to get a copy of 599219820Sjeff* an element. 600219820Sjeff* 601219820Sjeff* index 602219820Sjeff* [in] Index of the element. 603219820Sjeff* 604219820Sjeff* p_element 605219820Sjeff* [out] Pointer to storage for the element. Contains a copy of the 606219820Sjeff* desired element upon successful completion of the call. 607219820Sjeff* 608219820Sjeff* RETURN VALUE 609219820Sjeff* This function does not return a value. 610219820Sjeff* 611219820Sjeff* NOTES 612219820Sjeff* cl_vector_get provides constant time access regardless of the index. 613219820Sjeff* 614219820Sjeff* cl_vector_get does not perform boundary checking on the vector, and 615219820Sjeff* callers are responsible for providing an index that is within the range 616219820Sjeff* of the vector. To access elements after performing boundary checks, 617219820Sjeff* use cl_vector_at. 618219820Sjeff* 619219820Sjeff* The p_element parameter contains a copy of the desired element upon 620219820Sjeff* return from this function. 621219820Sjeff* 622219820Sjeff* SEE ALSO 623219820Sjeff* Vector, cl_vector_get_ptr, cl_vector_at 624219820Sjeff*********/ 625219820Sjeff 626219820Sjeff/****f* Component Library: Vector/cl_vector_at 627219820Sjeff* NAME 628219820Sjeff* cl_vector_at 629219820Sjeff* 630219820Sjeff* DESCRIPTION 631219820Sjeff* The cl_vector_at function copies an element stored in a vector at a 632219820Sjeff* specified index, performing boundary checks. 633219820Sjeff* 634219820Sjeff* SYNOPSIS 635219820Sjeff*/ 636219820Sjeffcl_status_t 637219820Sjeffcl_vector_at(IN const cl_vector_t * const p_vector, 638219820Sjeff IN const size_t index, OUT void *const p_element); 639219820Sjeff/* 640219820Sjeff* PARAMETERS 641219820Sjeff* p_vector 642219820Sjeff* [in] Pointer to a cl_vector_t structure from which to get a copy of 643219820Sjeff* an element. 644219820Sjeff* 645219820Sjeff* index 646219820Sjeff* [in] Index of the element. 647219820Sjeff* 648219820Sjeff* p_element 649219820Sjeff* [out] Pointer to storage for the element. Contains a copy of the 650219820Sjeff* desired element upon successful completion of the call. 651219820Sjeff* 652219820Sjeff* RETURN VALUES 653219820Sjeff* CL_SUCCESS if an element was found at the specified index. 654219820Sjeff* 655219820Sjeff* CL_INVALID_SETTING if the index was out of range. 656219820Sjeff* 657219820Sjeff* NOTES 658219820Sjeff* cl_vector_at provides constant time access regardless of the index, and 659219820Sjeff* performs boundary checking on the vector. 660219820Sjeff* 661219820Sjeff* Upon success, the p_element parameter contains a copy of the desired element. 662219820Sjeff* 663219820Sjeff* SEE ALSO 664219820Sjeff* Vector, cl_vector_get, cl_vector_get_ptr 665219820Sjeff*********/ 666219820Sjeff 667219820Sjeff/****f* Component Library: Vector/cl_vector_set 668219820Sjeff* NAME 669219820Sjeff* cl_vector_set 670219820Sjeff* 671219820Sjeff* DESCRIPTION 672219820Sjeff* The cl_vector_set function sets the element at the specified index. 673219820Sjeff* 674219820Sjeff* SYNOPSIS 675219820Sjeff*/ 676219820Sjeffcl_status_t 677219820Sjeffcl_vector_set(IN cl_vector_t * const p_vector, 678219820Sjeff IN const size_t index, IN void *const p_element); 679219820Sjeff/* 680219820Sjeff* PARAMETERS 681219820Sjeff* p_vector 682219820Sjeff* [in] Pointer to a cl_vector_t structure into which to store 683219820Sjeff* an element. 684219820Sjeff* 685219820Sjeff* index 686219820Sjeff* [in] Index of the element. 687219820Sjeff* 688219820Sjeff* p_element 689219820Sjeff* [in] Pointer to an element to store in the vector. 690219820Sjeff* 691219820Sjeff* RETURN VALUES 692219820Sjeff* CL_SUCCESS if the element was successfully set. 693219820Sjeff* 694219820Sjeff* CL_INSUFFICIENT_MEMORY if the vector could not be resized to accommodate 695219820Sjeff* the new element. 696219820Sjeff* 697219820Sjeff* NOTES 698219820Sjeff* cl_vector_set grows the vector as needed to accommodate the new element, 699219820Sjeff* unless the grow_size parameter passed into the cl_vector_init function 700219820Sjeff* was zero. 701219820Sjeff* 702219820Sjeff* SEE ALSO 703219820Sjeff* Vector, cl_vector_get 704219820Sjeff*********/ 705219820Sjeff 706219820Sjeff/****f* Component Library: Vector/cl_vector_set_capacity 707219820Sjeff* NAME 708219820Sjeff* cl_vector_set_capacity 709219820Sjeff* 710219820Sjeff* DESCRIPTION 711219820Sjeff* The cl_vector_set_capacity function reserves memory in a vector for a 712219820Sjeff* specified number of elements. 713219820Sjeff* 714219820Sjeff* SYNOPSIS 715219820Sjeff*/ 716219820Sjeffcl_status_t 717219820Sjeffcl_vector_set_capacity(IN cl_vector_t * const p_vector, 718219820Sjeff IN const size_t new_capacity); 719219820Sjeff/* 720219820Sjeff* PARAMETERS 721219820Sjeff* p_vector 722219820Sjeff* [in] Pointer to a cl_vector_t structure whose capacity to set. 723219820Sjeff* 724219820Sjeff* new_capacity 725219820Sjeff* [in] Total number of elements for which the vector should 726219820Sjeff* allocate memory. 727219820Sjeff* 728219820Sjeff* RETURN VALUES 729219820Sjeff* CL_SUCCESS if the capacity was successfully set. 730219820Sjeff* 731219820Sjeff* CL_INSUFFICIENT_MEMORY if there was not enough memory to satisfy the 732219820Sjeff* operation. The vector is left unchanged. 733219820Sjeff* 734219820Sjeff* NOTES 735219820Sjeff* cl_vector_set_capacity increases the capacity of the vector. It does 736219820Sjeff* not change the size of the vector. If the requested capacity is less 737219820Sjeff* than the current capacity, the vector is left unchanged. 738219820Sjeff* 739219820Sjeff* SEE ALSO 740219820Sjeff* Vector, cl_vector_get_capacity, cl_vector_set_size, 741219820Sjeff* cl_vector_set_min_size 742219820Sjeff*********/ 743219820Sjeff 744219820Sjeff/****f* Component Library: Vector/cl_vector_set_size 745219820Sjeff* NAME 746219820Sjeff* cl_vector_set_size 747219820Sjeff* 748219820Sjeff* DESCRIPTION 749219820Sjeff* The cl_vector_set_size function resizes a vector, either increasing or 750219820Sjeff* decreasing its size. 751219820Sjeff* 752219820Sjeff* SYNOPSIS 753219820Sjeff*/ 754219820Sjeffcl_status_t 755219820Sjeffcl_vector_set_size(IN cl_vector_t * const p_vector, IN const size_t size); 756219820Sjeff/* 757219820Sjeff* PARAMETERS 758219820Sjeff* p_vector 759219820Sjeff* [in] Pointer to a cl_vector_t structure whose size to set. 760219820Sjeff* 761219820Sjeff* size 762219820Sjeff* [in] Number of elements desired in the vector. 763219820Sjeff* 764219820Sjeff* RETURN VALUES 765219820Sjeff* CL_SUCCESS if the size of the vector was set successfully. 766219820Sjeff* 767219820Sjeff* CL_INSUFFICIENT_MEMORY if there was not enough memory to complete the 768219820Sjeff* operation. The vector is left unchanged. 769219820Sjeff* 770219820Sjeff* NOTES 771219820Sjeff* cl_vector_set_size sets the vector to the specified size. If size is 772219820Sjeff* smaller than the current size of the vector, the size is reduced. 773219820Sjeff* The destructor function, if any, will be invoked for all elements that 774219820Sjeff* are above size. Likewise, the constructor and initializer, if any, will 775219820Sjeff* be invoked for all new elements. 776219820Sjeff* 777219820Sjeff* This function can only fail if size is larger than the current capacity. 778219820Sjeff* 779219820Sjeff* SEE ALSO 780219820Sjeff* Vector, cl_vector_get_size, cl_vector_set_min_size, 781219820Sjeff* cl_vector_set_capacity 782219820Sjeff*********/ 783219820Sjeff 784219820Sjeff/****f* Component Library: Vector/cl_vector_set_min_size 785219820Sjeff* NAME 786219820Sjeff* cl_vector_set_min_size 787219820Sjeff* 788219820Sjeff* DESCRIPTION 789219820Sjeff* The cl_vector_set_min_size function resizes a vector to a specified size 790219820Sjeff* if the vector is smaller than the specified size. 791219820Sjeff* 792219820Sjeff* SYNOPSIS 793219820Sjeff*/ 794219820Sjeffcl_status_t 795219820Sjeffcl_vector_set_min_size(IN cl_vector_t * const p_vector, 796219820Sjeff IN const size_t min_size); 797219820Sjeff/* 798219820Sjeff* PARAMETERS 799219820Sjeff* p_vector 800219820Sjeff* [in] Pointer to a cl_vector_t structure whose minimum size to set. 801219820Sjeff* 802219820Sjeff* min_size 803219820Sjeff* [in] Minimum number of elements that the vector should contain. 804219820Sjeff* 805219820Sjeff* RETURN VALUES 806219820Sjeff* CL_SUCCESS if the vector size is greater than or equal to min_size. This 807219820Sjeff* could indicate that the vector's capacity was increased to min_size or 808219820Sjeff* that the vector was already of sufficient size. 809219820Sjeff* 810219820Sjeff* CL_INSUFFICIENT_MEMORY if there was not enough memory to resize the vector. 811219820Sjeff* The vector is left unchanged. 812219820Sjeff* 813219820Sjeff* NOTES 814219820Sjeff* If min_size is smaller than the current size of the vector, the vector is 815219820Sjeff* unchanged. The vector is unchanged if the size could not be changed due 816219820Sjeff* to insufficient memory being available to perform the operation. 817219820Sjeff* 818219820Sjeff* SEE ALSO 819219820Sjeff* Vector, cl_vector_get_size, cl_vector_set_size, cl_vector_set_capacity 820219820Sjeff*********/ 821219820Sjeff 822219820Sjeff/****f* Component Library: Vector/cl_vector_apply_func 823219820Sjeff* NAME 824219820Sjeff* cl_vector_apply_func 825219820Sjeff* 826219820Sjeff* DESCRIPTION 827219820Sjeff* The cl_vector_apply_func function invokes a specified function for every 828219820Sjeff* element in a vector. 829219820Sjeff* 830219820Sjeff* SYNOPSIS 831219820Sjeff*/ 832219820Sjeffvoid 833219820Sjeffcl_vector_apply_func(IN const cl_vector_t * const p_vector, 834219820Sjeff IN cl_pfn_vec_apply_t pfn_callback, 835219820Sjeff IN const void *const context); 836219820Sjeff/* 837219820Sjeff* PARAMETERS 838219820Sjeff* p_vector 839219820Sjeff* [in] Pointer to a cl_vector_t structure whose elements to iterate. 840219820Sjeff* 841219820Sjeff* pfn_callback 842219820Sjeff* [in] Function invoked for every element in the array. 843219820Sjeff* See the cl_pfn_vec_apply_t function type declaration for details 844219820Sjeff* about the callback function. 845219820Sjeff* 846219820Sjeff* context 847219820Sjeff* [in] Value to pass to the callback function. 848219820Sjeff* 849219820Sjeff* RETURN VALUE 850219820Sjeff* This function does not return a value. 851219820Sjeff* 852219820Sjeff* NOTES 853219820Sjeff* cl_vector_apply_func invokes the specified function for every element 854219820Sjeff* in the vector, starting from the beginning of the vector. 855219820Sjeff* 856219820Sjeff* SEE ALSO 857219820Sjeff* Vector, cl_vector_find_from_start, cl_vector_find_from_end, 858219820Sjeff* cl_pfn_vec_apply_t 859219820Sjeff*********/ 860219820Sjeff 861219820Sjeff/****f* Component Library: Vector/cl_vector_find_from_start 862219820Sjeff* NAME 863219820Sjeff* cl_vector_find_from_start 864219820Sjeff* 865219820Sjeff* DESCRIPTION 866219820Sjeff* The cl_vector_find_from_start function uses a specified function to 867219820Sjeff* search for elements in a vector starting from the lowest index. 868219820Sjeff* 869219820Sjeff* SYNOPSIS 870219820Sjeff*/ 871219820Sjeffsize_t 872219820Sjeffcl_vector_find_from_start(IN const cl_vector_t * const p_vector, 873219820Sjeff IN cl_pfn_vec_find_t pfn_callback, 874219820Sjeff IN const void *const context); 875219820Sjeff/* 876219820Sjeff* PARAMETERS 877219820Sjeff* p_vector 878219820Sjeff* [in] Pointer to a cl_vector_t structure to inititalize. 879219820Sjeff* 880219820Sjeff* pfn_callback 881219820Sjeff* [in] Function invoked to determine if a match was found. 882219820Sjeff* See the cl_pfn_vec_find_t function type declaration for details 883219820Sjeff* about the callback function. 884219820Sjeff* 885219820Sjeff* context 886219820Sjeff* [in] Value to pass to the callback function. 887219820Sjeff* 888219820Sjeff* RETURN VALUES 889219820Sjeff* Index of the element, if found. 890219820Sjeff* 891219820Sjeff* Size of the vector if the element was not found. 892219820Sjeff* 893219820Sjeff* NOTES 894219820Sjeff* cl_vector_find_from_start does not remove the found element from 895219820Sjeff* the vector. The index of the element is returned when the function 896219820Sjeff* provided by the pfn_callback parameter returns CL_SUCCESS. 897219820Sjeff* 898219820Sjeff* SEE ALSO 899219820Sjeff* Vector, cl_vector_find_from_end, cl_vector_apply_func, cl_pfn_vec_find_t 900219820Sjeff*********/ 901219820Sjeff 902219820Sjeff/****f* Component Library: Vector/cl_vector_find_from_end 903219820Sjeff* NAME 904219820Sjeff* cl_vector_find_from_end 905219820Sjeff* 906219820Sjeff* DESCRIPTION 907219820Sjeff* The cl_vector_find_from_end function uses a specified function to search 908219820Sjeff* for elements in a vector starting from the highest index. 909219820Sjeff* 910219820Sjeff* SYNOPSIS 911219820Sjeff*/ 912219820Sjeffsize_t 913219820Sjeffcl_vector_find_from_end(IN const cl_vector_t * const p_vector, 914219820Sjeff IN cl_pfn_vec_find_t pfn_callback, 915219820Sjeff IN const void *const context); 916219820Sjeff/* 917219820Sjeff* PARAMETERS 918219820Sjeff* p_vector 919219820Sjeff* [in] Pointer to a cl_vector_t structure to inititalize. 920219820Sjeff* 921219820Sjeff* pfn_callback 922219820Sjeff* [in] Function invoked to determine if a match was found. 923219820Sjeff* See the cl_pfn_vec_find_t function type declaration for details 924219820Sjeff* about the callback function. 925219820Sjeff* 926219820Sjeff* context 927219820Sjeff* [in] Value to pass to the callback function. 928219820Sjeff* 929219820Sjeff* RETURN VALUES 930219820Sjeff* Index of the element, if found. 931219820Sjeff* 932219820Sjeff* Size of the vector if the element was not found. 933219820Sjeff* 934219820Sjeff* NOTES 935219820Sjeff* cl_vector_find_from_end does not remove the found element from 936219820Sjeff* the vector. The index of the element is returned when the function 937219820Sjeff* provided by the pfn_callback parameter returns CL_SUCCESS. 938219820Sjeff* 939219820Sjeff* SEE ALSO 940219820Sjeff* Vector, cl_vector_find_from_start, cl_vector_apply_func, 941219820Sjeff* cl_pfn_vec_find_t 942219820Sjeff*********/ 943219820Sjeff 944219820SjeffEND_C_DECLS 945219820Sjeff#endif /* _CL_VECTOR_H_ */ 946