It is my pleasure to announce the first release of hector, an OCaml library that offers vectors (also known as dynamic arrays, or resizeable arrays).
To install it, type opam update && opam install hector.
hector offers polymorphic vectors, where the type of the elements is a parameter, monomorphic vectors, where the type of the elements is fixed, and integer vectors, a special case of monomorphic vectors.
hector’s vectors are not thread-safe and do not include a protection against memory leaks. Compared with the Dynarray module in OCaml’s standard library, hector’s polymorphic and monomorphic vectors are slightly faster, and hector’s integer vectors are significantly faster. hector offers fast (but dangerous) unsafe access operations, namely unsafe_get, unsafe_set, and unsafe_borrow. For a more detailed overview, see the documentation.
It took me a while to find a link to the actual api on the doc page. I was expecting it in sidebar or on the top but there was nothing, and the links in the doc body don’t look like links (as opposed to Dynarray which is a visible link)
Almost always, the capacity of a vector is the length of the data array where the vector’s elements are stored. As an exception to the previous sentence, if a vector has logical length 0 then its data array can be empty, even if its capacity is nonzero.
I am confused about this exception Dynarray documentation has “Memory layout” chapter which is nice to understand the tradeoffs. I think it would be beneficial for hector too given that it has a nice elaborate readme.
Thanks @ygrek for noting that the hyperlinks are not colored (I am not sure how to fix this, though) and the explanation of the capacity could be clarified.
With hector, the thing that is a bit confusing about capacity is that each vector has a capacity field (which can be updated by set_capacity), and each vector has a data array (which can be accessed via unsafe_borrow), but the length of the data array is not always the vector’s capacity. There is one special case where the data array can have length zero even if the capacity is nonzero.
hyperlinks style fix probably requires custom css, but idk. I would just put api doc link explicitly at the top so that it would be impossible to miss.
Re capacity - so this word has an assumed baggage, that’s why I got confused, namely I implicitly read “size of backing array” when I see the word “capacity”. And in case of hector this mental model breaks because essentially there are now two different “capacities”. Maybe it makes sense to rename capacity field to maximum_capacity.
Dynarray documentation has “Memory layout” chapter which is nice to understand the tradeoffs. I think it would be beneficial for hector too given that it has a nice elaborate readme.