From 72abfd17de79d082f29bb690311962c5bb1217c3 Mon Sep 17 00:00:00 2001 From: Runxi Yu Date: Fri, 26 Sep 2025 22:21:55 +0800 Subject: [PATCH] Update README to note upstream opinion better --- README.md | 44 +++++++++++++++++++++++++++----------------- diff --git a/README.md b/README.md index 628ee3f46fd810e598d8ceff7e6bd853d25a544b..4597e056fa3d0fb69c72b1163648b4a6acfaa29d 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ - Binary heap ## Note -The maintainers of Hare would not recommend using this library. +The maintainers of Hare would not recommend using this as a library. From [Why doesn’t Hare have generics?](https://harelang.org/documentation/faq.html#why-doesn-t-hare-have-generics), @@ -52,30 +52,40 @@ > them to your specific use-case. Optimizing every other data structure that > your program makes use of, but which is not bottlenecking your performance, > is a premature optimization. +
+(My own dissenting opinion) +

While the above is an explanation of why Hare does not have generics, it serves as a general argument against general-purpose data structures, such as those implemented in this library. For examples, when a key-value map is needed but is not a bottleneck, they may recommend using a simple slice of pairs and -iterate through them linearly. - -We respectfully dissent, because we believe that general-purpose data -structures can be implemented in a way that is efficient enough for many use -cases, even if not as efficient as a hand-crafted data structure for each -specific use case. It is, instead, a premature optimization to hand-craft maps -for specific use case that would want something better than a linear search. -Even though hashmaps and tree-based maps could be considered an optimization -over a linear search, optimization should not be all-or-nothing; an appropriate -amount of optimization such as using hashmaps in many places, is better than -having linear searches everywhere where they are slow, and is also better than -hand-crafting maps for every conceivable use case where linear searches are too -slow. In practice, -[many codebases](https://paste.sr.ht/~runxiyu/a0b49d84a3c9f3b35a05dd60993a3cd9d185bfff) +iterate through them linearly. We respectfully dissent, because we believe that +general-purpose data structures can be implemented in a way that is efficient +enough for many use cases, even if not as efficient as a hand-crafted data +structure for each specific use case. It is, instead, a premature optimization +to hand-craft maps for specific use case that would want something better than +a linear search. Even though hashmaps and tree-based maps could be considered +an optimization over a linear search, optimization should not be +all-or-nothing; an appropriate amount of optimization such as using hashmaps in +many places, is better than having linear searches everywhere where they are +slow, and is also better than hand-crafting maps for every conceivable use case +where linear searches are too slow. In practice, +many codebases use numerous auxillary maps which share similar access patterns but may use differen types. Re-implementing a bespoke and non-general-purpose map for each key/value type is likely a waste of effort if access patterns are similar. +

+
-Also, as a consequence of not having generics, the data structures here are not -type safe. Structures here typically use `[]u8` keys and `*opaque` values. +As a consequence of not having generics, the data structures here are not type +safe. Structures here typically use `[]u8` keys and `*opaque` values. + +You should consider copying implementations here to paste into your own code +and adapting them to your particular needs as upstream suggests. + +Currently, this codebase lacks comments and explanations. Drew DeVault's +[hare-datastructures](https://git.sr.ht/~sircmpwn/hare-datastructures) may be +better-documented implementations worth checking out. ## Contributing -- 2.48.1