feat(list): first version of deque as fork from container/list (#45).

LICENSE-GO.txt

@@ -0,0 +1,27 @@
+Copyright 2009 The Go Authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -7,24 +7,29 @@
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/fgm/container/badge)](https://securityscorecards.dev/viewer/?uri=github.com/fgm/container)
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/10245/badge)](https://www.bestpractices.dev/projects/10245)
 
-This module contains minimal type-safe Ordered Map, Queue, Set and Stack implementations
-using Go generics.
+This module contains minimal type-safe Double-ended queue, Ordered Map, Queue, Set and Stack implementations
+using Go generics, as well as a concurrent-safe WaitableQueue.
 
 The Ordered Map supports both stable (in-place) updates and recency-based ordering,
 making it suitable both for highest performance (in-place), and for LRU caches (recency).
 
+The double-ended queue is currently a fork of the Go stdlib [container/list](https://pkg.go.dev/container/list) package,
+replacing the `any` value with a type parameter for type safety.
+This API is not stable, as it differs from the other packages,
+and will be deprecated when a simpler one is found, more in line with the other packages.
+
 ## Contents
 
 See the available types by underlying storage
 
-| Type          | Slice | Map | List | List+sync.Pool | List+int. pool | Recommended          |
-|---------------|:-----:|:---:|:----:|:--------------:|:--------------:|----------------------|
-| OrderedMap    |   Y   |     |      |                |                | Slice with size hint |
-| Queue         |   Y   |     |  Y   |       Y        |       Y        | Slice with size hint |
-| WaitableQueue |   Y   |     |      |                |                | Slice with size hint |
-| Set           |       |  Y  |      |                |                | Map with size hint   |
-| Stack         |   Y   |     |  Y   |       Y        |       Y        | Slice with size hint |
-
+| Type               | Slice | Map | List | List+sync.Pool | List+int. pool | Recommended           |
+|--------------------|:-----:|:---:|:----:|:--------------:|:--------------:|-----------------------|
+| Double-ended queue |       |     |  Y   |                |                | Type-safe stdlib fork |
+| OrderedMap         |   Y   |     |      |                |                | Slice with size hint  |
+| Queue              |   Y   |     |  Y   |       Y        |       Y        | Slice with size hint  |
+| WaitableQueue      |   Y   |     |      |                |                | Slice with size hint  |
+| Set                |       |  Y  |      |                |                | Map with size hint    |
+| Stack              |   Y   |     |  Y   |       Y        |       Y        | Slice with size hint  |
 
 **CAVEAT**: In order to optimize performance, except for WaitableQueue,
 all of these implementations are unsafe for concurrent execution,
@@ -43,9 +48,11 @@ See [BENCHARKS.md](BENCHMARKS.md) for details.
 
 See complete listings in:
 
+- [`cmd/list`](cmd/list/real_main.go)
 - [`cmd/orderedmap`](cmd/orderedmap/real_main.go)
 - [`cmd/queuestack`](cmd/queuestack/real_main.go)
 - [`cmd/set`](cmd/set/real_main.go)
+- [`cmd/waitablequeue`](cmd/waitablequeue/real_main.go)
 
 ### Ordered Map
 
@@ -161,3 +168,11 @@ Fuzz tests are not run by CI, but you can run them on-demand during development
 
 - Adjust `-fuzztime` duration as relevant: 20 seconds is just a smoke test.
 - Be sure to escape the `\Q\E` characters in the `-fuzz` argument in your shell.
+
+## Licensing
+
+- In the directory [container](container) and below,
+  this project includes code derived from the Go standard library's container/list package,
+  which is licensed under the BSD 3-Clause License.  
+  The original copyright and license text are included in the source files.
+- The rest of this project is licensed under the Apache License 2.0.

cmd/list/main.go

@@ -0,0 +1,9 @@
+package main
+
+import (
+	"os"
+)
+
+func main() {
+	os.Exit(realMain(os.Stdout))
+}

cmd/list/real_main.go

@@ -0,0 +1,41 @@
+package main
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/fgm/container/list"
+)
+
+type Element int
+
+func realMain(w io.Writer) int {
+	var e Element = 13
+
+	l := list.New[Element]()
+	// Add squares.
+	for i := range e {
+		l.PushBack(i * i)
+	}
+	fmt.Fprintf(w, "elements in list: %d\n", l.Len())
+
+	found := 0
+	for {
+		if cur := l.Front(); cur != nil {
+			found++
+			l.Remove(cur)
+			fmt.Fprintf(w, "Element: %3v len: %d\n", cur.Value, l.Len())
+		} else {
+			break
+		}
+		if cur := l.Back(); cur != nil {
+			found++
+			l.Remove(cur)
+			fmt.Fprintf(w, "Element: %3v len: %d\n", cur.Value, l.Len())
+		} else {
+			break
+		}
+	}
+	fmt.Fprintf(w, "Found %d elements, expected %d\n", found, e)
+	return 0
+}

cmd/list/real_main_test.go

@@ -0,0 +1,37 @@
+package main
+
+import (
+	"bytes"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+)
+
+func TestRealMain(t *testing.T) {
+	var buf bytes.Buffer
+	exitCode := realMain(&buf)
+
+	if exitCode != 0 {
+		t.Fatalf("expected exit code 0, got %d", exitCode)
+	}
+
+	expectedOutput := `elements in list: 13
+Element:   0 len: 12
+Element: 144 len: 11
+Element:   1 len: 10
+Element: 121 len: 9
+Element:   4 len: 8
+Element: 100 len: 7
+Element:   9 len: 6
+Element:  81 len: 5
+Element:  16 len: 4
+Element:  64 len: 3
+Element:  25 len: 2
+Element:  49 len: 1
+Element:  36 len: 0
+Found 13 elements, expected 13
+`
+	if buf.String() != expectedOutput {
+		t.Fatal(cmp.Diff(expectedOutput, buf.String()))
+	}
+}

list/example_test.go

@@ -0,0 +1,33 @@
+// Copyright 2013 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+//
+// This file contains code from the go stdlib container/list package,
+// and is therefore dual licensed under the BSD 3 clause license, and the Apache 2.0 license.
+package list_test
+
+import (
+	"fmt"
+
+	"github.com/fgm/container/list"
+)
+
+func Example() {
+	// Create a new list and put some numbers in it.
+	l := list.New[int]()
+	e4 := l.PushBack(4)
+	e1 := l.PushFront(1)
+	l.InsertBefore(3, e4)
+	l.InsertAfter(2, e1)
+
+	// Iterate through list and print its contents.
+	for e := l.Front(); e != nil; e = e.Next() {
+		fmt.Println(e.Value)
+	}
+
+	// Output:
+	// 1
+	// 2
+	// 3
+	// 4
+}