vec.3 (4114B)
1 .TH VEC 3 2 .SH NAME 3 Vec, Vecadd, Vecaddv, Vecclose, Vecdel, Vecinit, Vecinitf, Vecinsure, Veczero, Vecsiz \- generic resizable vectors 4 .SH SYNOPSIS 5 .B #include <u.h> 6 .br 7 .B #include <libc.h> 8 .br 9 .B #include <vec.h> 10 .PP 11 .ft L 12 .nf 13 .ta \w'\fL 'u +\w'\fLulong 'u 14 typedef struct { 15 void (*init)(); 16 void (*close)(); 17 ulong n; 18 ulong size; 19 } Vector; 20 .fi 21 .PP 22 .ta \w'\fLVector* 'u 23 .B 24 Vector* Vec(Type p) 25 .PP 26 .ta \w'\fLType 'u 27 .B 28 Type Vecadd(Type *p) 29 .PP 30 .B 31 void Vecaddv(Type *p, val, Type) 32 .PP 33 .B 34 void Vecclose(Type *p) 35 .PP 36 .B 37 void Vecdel(Type *p, ulong n) 38 .PP 39 .B 40 void Vecinit(Type *p) 41 .PP 42 .B 43 void Vecinitf(Type *p, void (*init)(), void (*close)()) 44 .PP 45 .B 46 void Vecinsure(Type *p, ulong n) 47 .PP 48 .B 49 void Veczero(Type *p) 50 .PP 51 .B 52 ulong Vecsiz(Type p) 53 .SH DESCRIPTION 54 These functions provide a generic interface for manipulating resizable vectors (dynamic arrays). 55 A vector is a pointer to an array of elements that can grow automatically as elements are added. 56 The vector maintains metadata about its size and capacity in a 57 .B Vector 58 structure stored immediately before the data. 59 .PP 60 .I Vec 61 returns a pointer to the 62 .B Vector 63 structure for vector 64 .IR p . 65 .PP 66 .I Vecinit 67 initializes a vector pointed to by 68 .IR p . 69 The vector is initially empty. 70 .PP 71 .I Vecinitf 72 initializes a vector with custom initialization and cleanup functions. 73 The 74 .I init 75 function is called when new elements are added to initialize them. 76 The 77 .I close 78 function is called when elements are removed to clean them up. 79 If 80 .I init 81 is 82 .BR nil , 83 new elements are zeroed. 84 If 85 .I close 86 is 87 .BR nil , 88 no cleanup is performed. 89 .PP 90 .I Vecadd 91 adds a new element to the vector and returns a pointer to the new element. 92 The vector grows automatically if necessary. 93 .PP 94 .I Vecaddv 95 is a convenience macro that adds a value 96 .I val 97 of type 98 .I Type 99 to the vector. 100 .PP 101 .I Vecdel 102 removes the element at index 103 .I n 104 from the vector. 105 If the vector is empty, it does nothing. 106 Elements after the removed element are shifted down. 107 If a cleanup function was provided to 108 .IR Vecinitf , 109 it is called on the removed element. 110 .PP 111 .I Vecinsure 112 ensures that the vector has space for at least 113 .I n 114 elements. 115 This can be used to preallocate space for better performance. 116 .PP 117 .I Veczero 118 removes all elements from the vector and frees any excess space. 119 If a cleanup function was provided, it is called on each element. 120 The vector remains valid and can be used to add new elements. 121 .PP 122 .I Vecclose 123 frees the vector and all its elements. 124 If a cleanup function was provided, it is called on each element. 125 The vector pointer is set to 126 .BR nil . 127 .PP 128 .I Vecsiz 129 returns the number of elements in the vector. 130 .PP 131 Since vectors are implemented as regular arrays with metadata stored separately, 132 the vector pointer returned by these functions can be used directly with 133 standard C library functions like 134 .IR qsort (3) 135 and 136 .IR bsearch (3) . 137 .SH EXAMPLES 138 .PP 139 Simple vector of integers: 140 .IP 141 .EX 142 int *v; 143 Vecinit(&v); 144 Vecaddv(&v, 42, int); 145 Vecaddv(&v, 100, int); 146 print("size: %lud, first: %d, second: %d\en", 147 Vecsiz(v), v[0], v[1]); 148 Vecclose(&v); 149 .EE 150 .PP 151 Vector of strings with cleanup: 152 .IP 153 .EX 154 void str_free(void *p) { free(*(char**)p); } 155 156 char **v; 157 Vecinitf(&v, nil, str_free); 158 *(char**)Vecadd(&v) = strdup("hello"); 159 *(char**)Vecadd(&v) = strdup("world"); 160 Vecclose(&v); 161 .EE 162 .PP 163 Using with standard library functions: 164 .IP 165 .EX 166 int *v; 167 int i; 168 Vecinit(&v); 169 for(i = 0; i < 100; i++) 170 Vecaddv(&v, rand(), int); 171 qsort(v, Vecsiz(v), sizeof(int), intcmp); 172 print("sorted vector has %lud elements\en", Vecsiz(v)); 173 Vecclose(&v); 174 .EE 175 .PP 176 Preallocation: 177 .IP 178 .EX 179 int *v; 180 Vecinit(&v); 181 Vecinsure(&v, 1000); 182 for(i = 0; i < 1000; i++) 183 Vecaddv(&v, i, int); 184 Vecclose(&v); 185 .EE 186 .SH SOURCE 187 .B \*9/src/libvec 188 .SH SEE ALSO 189 .MR malloc (3) , 190 .MR qsort (3) 191 .SH DIAGNOSTICS 192 All functions call 193 .I sysfatal 194 if memory allocation fails or if passed nil or uninitialized vectors. 195 .SH NOTES 196 The vector implementation uses 197 .I Type 198 as a generic pointer type. 199 This allows the same vector functions to work with any pointer type. 200 The macros provide minimal type checking to ensure a pointer to pointer 201 is passed rather than a plain pointer.