Ready for release?

[rickb777]

Deque is a good utility, clear and simple to use, and fast.

Is it ready for a release version? It's overdue for one, IMO :-)

Meanwhile, here are some ideas for methods that you could add:

• push and insert slices - i.e. internalise the loop needed and reduce loop overhead
• add adaptors for the PopBack, PopFront and At methods to provide iterators (Go 1.23)
• add Full() bool method - a shortcut for q.Len() == q.Cap() which would be useful for anyone wanting to impose a maximum size or avoid resizing

[gammazero]

@rickb777 I have made a few changes that I think make it ready for release.

1. Added a Grow function that grows the deque's capacity, if necessary, to guarantee space for another n items.
   This makes it unnecessary to add a PushSlice and InsertSlice since the purpose of those, aside from some convenience, is to avoid possible multiple resizes when adding a number of items. With Grow the caller can do this:

    q.Grow(len(elems))                                                                                                                                                                                                                                        
    for i := range elems {                                                                                                                                                                                                                                    
        q.PushBack(elems[i])                                                                                                                                                                                                                                  
    }                                                                                                                                                                                                                                                         

2. Removed the New function. Previously New took two optional arguments, the initial capacity and the base capacity. Use SetBaseCap and Grow instead of arguments to New. This improves orthogonality. New is no longer needed.
3. A Swap method has been added.
4. Insert now allows out-of-range indexes, resulting in adding an item to the front or back of the deque.
5. Replace SetMinCapacity with SetBaseCapacity that takes a minimum number of items to reserve space for.

I am considering an Iter function that returns a go1.23 iterator to iterate the items in the Deque, but doing that will force callers to use go1.23. Callers can already do:

for i := 0; i < q.Len(); i++ {
    doSomething(q.At(i))
}

This could also include IterPopFront and IterPopBack, but than may be somewhat unnecessary when the caller can already do:

for q.Len() != 0 {
    process(q.PopFront())
}

The iterator looks like:

for item := range IterPopFront() {
    process(item)
}

Probably worth adding iterators to eliminate intermediate resizes during iteration. Somewhat like the inverse of Grow. See PR #32.

As for a Full function, it seems like it is syntactic sugar for something that is likely not very common. I think if q.Len() == q.Cap() is a bit more explicit. If a size limit is desired them it might be better wrap Deque in a type that checks if Len is at the limit when adding items. The wrapper's PushBask can then return a bool or error to indicate that the limit has been reached. If it is necessary to block on a write to a full Deque, or a read from an empty Deque, then channelqueue does exactly this. WDYT?

[gammazero]

@rickb777 I think I will release v1.0.0 without PR #32 which requires go1.23. Later, when go1.24 is released I can merge the iterator PR and create release v1.1.0.

[gammazero]

Completed. Closing this PR as v1.0.0 is now released. Discussion continued in #35.