Skip to content

Commit 9a1ecdf

Browse files
authored
update readme (#4)
1 parent 6788e7e commit 9a1ecdf

File tree

1 file changed

+19
-0
lines changed

1 file changed

+19
-0
lines changed

README.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,25 @@ And then you'd be able to import it as `"array"`:
9696
const array = @import("array");
9797
```
9898

99+
## Why This Library
100+
101+
The standard library already includes `std.ArrayList`. In many cases, this is
102+
the ideal choice. This is especially so if you know you are going to be storing
103+
many items in the array. Alternatively, if you know you will only be storing
104+
a limited number of items, using zig's array types (i.e. `[8]i32`) is sensible.
105+
106+
However, there are cases where you are most likely going to be storing few
107+
items, but need the flexibility to grow past the fixed limit that arrays
108+
provide. That is, you will generally need the compactness of a zig array,
109+
but you need the option to grow like a `std.ArrayList`.
110+
111+
This is where `SmallArrayList` comes in. In the low item count case, you can
112+
stay allocation-free, like a zig array. If item capacity needs to increase,
113+
however, you can still expand to support whatever size is needed. This can
114+
keep overall memory usage down for low-item array lists. Additionally, when
115+
the items are non-allocated, you gain a memory locality benefit as there is
116+
no pointer indirection.
117+
99118
## Small Capacity Limit
100119

101120
The available small capacity limit is determined by the type stored and the

0 commit comments

Comments
 (0)