vec.3 (3180B)
1 .TH VEC 3 2 .SH NAME 3 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 .nf 12 .ta \w'\fL 'u +\w'\fLulong 'u 13 typedef struct { 14 void (*init)(); 15 void (*close)(); 16 ulong n; 17 ulong size; 18 } Vector; 19 .PP 20 .B 21 Type Vecadd(Type *p) 22 .PP 23 .B 24 void Vecaddv(Type *p, val, Type) 25 .PP 26 .B 27 void Vecclose(Type *p) 28 .PP 29 .B 30 void Vecdel(Type *p, ulong n) 31 .PP 32 .B 33 void Vecinit(Type *p) 34 .PP 35 .B 36 void Vecinitf(Type *p, void (*init)(), void (*close)()) 37 .PP 38 .B 39 void Vecinsure(Type *p, ulong n) 40 .PP 41 .B 42 void Veczero(Type *p) 43 .PP 44 .B 45 ulong Vecsiz(Type p) 46 .SH DESCRIPTION 47 These functions provide a generic interface for manipulating resizable vectors (dynamic arrays). 48 A vector is a pointer to an array of elements that can grow automatically as elements are added. 49 The vector maintains metadata about its size and capacity in a 50 .B Vector 51 structure stored immediately before the data. 52 .PP 53 .I Vecinit 54 initializes a vector pointed to by 55 .IR p . 56 The vector is initially empty. 57 .PP 58 .I Vecinitf 59 initializes a vector with custom initialization and cleanup functions. 60 The 61 .I init 62 function is called when new elements are added to initialize them. 63 The 64 .I close 65 function is called when elements are removed to clean them up. 66 .PP 67 .I Vecadd 68 adds a new element to the vector and returns a pointer to the new element. 69 .PP 70 .I Vecaddv 71 is a convenience macro that adds a value 72 .I val 73 of type 74 .I Type 75 to the vector. 76 .PP 77 .I Vecdel 78 removes the element at index 79 .I n 80 from the vector. 81 .PP 82 .I Vecinsure 83 ensures that the vector has space for at least 84 .I n 85 elements. 86 .PP 87 .I Veczero 88 removes all elements from the vector and frees any excess space. 89 The vector remains valid and can be used to add new elements. 90 .PP 91 .I Vecclose 92 frees the vector and all its elements. 93 The vector pointer is set to nil. 94 .PP 95 .I Vecsiz 96 returns the number of elements in the vector. 97 .PP 98 Since vectors are implemented as regular arrays with metadata stored separately, 99 the vector pointer returned by these functions can be used directly with 100 standard C library functions like 101 .IR qsort (3) 102 and 103 .IR bsearch (3) . 104 .SH EXAMPLES 105 .PP 106 Simple vector of integers: 107 .IP 108 .EX 109 int *v; 110 Vecinit(&v); 111 Vecaddv(&v, 42, int); 112 Vecaddv(&v, 100, int); 113 print("size: %lud, first: %d, second: %d\en", 114 Vecsiz(v), v[0], v[1]); 115 Vecclose(&v); 116 .EE 117 .PP 118 Vector of strings with cleanup: 119 .IP 120 .EX 121 void str_free(void *p) { free(*(char**)p); } 122 123 char **v; 124 Vecinitf(&v, nil, str_free); 125 *(char**)Vecadd(&v) = strdup("hello"); 126 *(char**)Vecadd(&v) = strdup("world"); 127 Vecclose(&v); 128 .EE 129 .PP 130 Using with standard library functions: 131 .IP 132 .EX 133 int *v; 134 int i; 135 Vecinit(&v); 136 for(i = 0; i < 100; i++) 137 Vecaddv(&v, rand(), int); 138 qsort(v, Vecsiz(v), sizeof(int), intcmp); 139 print("sorted vector has %lud elements\en", Vecsiz(v)); 140 Vecclose(&v); 141 .EE 142 .PP 143 Preallocation: 144 .IP 145 .EX 146 int *v; 147 Vecinit(&v); 148 Vecinsure(&v, 1000); 149 for(i = 0; i < 1000; i++) 150 Vecaddv(&v, i, int); 151 Vecclose(&v); 152 .EE 153 .SH SOURCE 154 .B \*9/src/libvec 155 .SH SEE ALSO 156 .MR malloc (3) , 157 .MR qsort (3) 158 .SH DIAGNOSTICS 159 .PP 160 All functions call 161 .I sysfatal 162 if memory allocation fails, or if passed nil or uninitialized vectors.