commit a117fa3478e9eadf15d019dd1a382f8466fffcca
parent 69cf5e2d79b53afa6774e05c3b12629bbb38fbab
Author: ssnf <ssnf@ssnf.xyz>
Date: Fri, 11 Jul 2025 00:26:10 +0000
add libvec manpage
Diffstat:
2 files changed, 199 insertions(+), 0 deletions(-)
diff --git a/man/man3/INDEX b/man/man3/INDEX
@@ -1245,6 +1245,16 @@ nsec time.3
time time.3
udpread udpread.3
udpwrite udpread.3
+Vecadd vec.3
+Vecaddv vec.3
+Vecclose vec.3
+Vecdel vec.3
+Vecinit vec.3
+Vecinitf vec.3
+Vecinsure vec.3
+Vecsiz vec.3
+Veczero vec.3
+vec vec.3
VtBlock venti-cache.3
VtCache venti-cache.3
venti-cache venti-cache.3
diff --git a/man/man3/vec.3 b/man/man3/vec.3
@@ -0,0 +1,189 @@
+.TH VEC 3
+.SH NAME
+Vecadd, Vecaddv, Vecclose, Vecdel, Vecinit, Vecinitf, Vecinsure, Veczero, Vecsiz \- generic resizable vectors
+.SH SYNOPSIS
+.B #include <u.h>
+.br
+.B #include <libc.h>
+.br
+.B #include <vec.h>
+.PP
+.ft L
+.nf
+.ta \w'\fL 'u +\w'\fLulong 'u
+typedef struct {
+ void (*init)();
+ void (*close)();
+ ulong n;
+ ulong size;
+} Vector;
+.fi
+.PP
+.ta \w'\fLType 'u
+.B
+Type Vecadd(Type *p)
+.PP
+.B
+void Vecaddv(Type *p, val, Type)
+.PP
+.B
+void Vecclose(Type *p)
+.PP
+.B
+void Vecdel(Type *p, ulong n)
+.PP
+.B
+void Vecinit(Type *p)
+.PP
+.B
+void Vecinitf(Type *p, void (*init)(), void (*close)())
+.PP
+.B
+void Vecinsure(Type *p, ulong n)
+.PP
+.B
+void Veczero(Type *p)
+.PP
+.B
+ulong Vecsiz(Type p)
+.SH DESCRIPTION
+These functions provide a generic interface for manipulating resizable vectors (dynamic arrays).
+A vector is a pointer to an array of elements that can grow automatically as elements are added.
+The vector maintains metadata about its size and capacity in a
+.B Vector
+structure stored immediately before the data.
+.PP
+.I Vecinit
+initializes a vector pointed to by
+.IR p .
+The vector is initially empty.
+.PP
+.I Vecinitf
+initializes a vector with custom initialization and cleanup functions.
+The
+.I init
+function is called when new elements are added to initialize them.
+The
+.I close
+function is called when elements are removed to clean them up.
+If
+.I init
+is
+.BR nil ,
+new elements are zeroed.
+If
+.I close
+is
+.BR nil ,
+no cleanup is performed.
+.PP
+.I Vecadd
+adds a new element to the vector and returns a pointer to the new element.
+The vector grows automatically if necessary.
+.PP
+.I Vecaddv
+is a convenience macro that adds a value
+.I val
+of type
+.I Type
+to the vector.
+.PP
+.I Vecdel
+removes the element at index
+.I n
+from the vector.
+If the vector is empty, it does nothing.
+Elements after the removed element are shifted down.
+If a cleanup function was provided to
+.IR Vecinitf ,
+it is called on the removed element.
+.PP
+.I Vecinsure
+ensures that the vector has space for at least
+.I n
+elements.
+This can be used to preallocate space for better performance.
+.PP
+.I Veczero
+removes all elements from the vector and frees any excess space.
+If a cleanup function was provided, it is called on each element.
+The vector remains valid and can be used to add new elements.
+.PP
+.I Vecclose
+frees the vector and all its elements.
+If a cleanup function was provided, it is called on each element.
+The vector pointer is set to
+.BR nil .
+.PP
+.I Vecsiz
+returns the number of elements in the vector.
+.PP
+Since vectors are implemented as regular arrays with metadata stored separately,
+the vector pointer returned by these functions can be used directly with
+standard C library functions like
+.IR qsort (3)
+and
+.IR bsearch (3) .
+.SH EXAMPLES
+.PP
+Simple vector of integers:
+.IP
+.EX
+int *v;
+Vecinit(&v);
+Vecaddv(&v, 42, int);
+Vecaddv(&v, 100, int);
+print("size: %lud, first: %d, second: %d\en",
+ Vecsiz(v), v[0], v[1]);
+Vecclose(&v);
+.EE
+.PP
+Vector of strings with cleanup:
+.IP
+.EX
+char **v;
+Vecinitf(&v, nil, free);
+*(char**)Vecadd(&v) = strdup("hello");
+*(char**)Vecadd(&v) = strdup("world");
+Vecclose(&v);
+.EE
+.PP
+Using with standard library functions:
+.IP
+.EX
+int *v;
+int i;
+Vecinit(&v);
+for(i = 0; i < 100; i++)
+ Vecaddv(&v, rand(), int);
+qsort(v, Vecsiz(v), sizeof(int), intcmp);
+print("sorted vector has %lud elements\en", Vecsiz(v));
+Vecclose(&v);
+.EE
+.PP
+Preallocation:
+.IP
+.EX
+int *v;
+Vecinit(&v);
+Vecinsure(&v, 1000);
+for(i = 0; i < 1000; i++)
+ Vecaddv(&v, i, int);
+Vecclose(&v);
+.EE
+.SH SOURCE
+.B \*9/src/libvec
+.SH SEE ALSO
+.MR malloc (3) ,
+.MR qsort (3)
+.SH DIAGNOSTICS
+All functions call
+.I sysfatal
+if memory allocation fails.
+.SH NOTES
+The vector implementation uses
+.I Type
+as a generic pointer type.
+This allows the same vector functions to work with any pointer type.
+The macros provide minimal type checking to ensure a pointer to pointer
+is passed rather than a plain pointer.
