github.com/haraldrudell/parl@v0.4.176/parli/if-ordered.go (about)

     1  /*
     2  © 2022–present Harald Rudell <harald.rudell@gmail.com> (https://haraldrudell.github.io/haraldrudell/)
     3  ISC License
     4  */
     5  
     6  package parli
     7  
     8  // OrderedPointers[E any] is an ordered list of pointers sorted by the referenced values.
     9  // OrderedPointers should be used when E is a large struct.
    10  // pslices.NewOrderedPointers[E constraints.Ordered]() instantiates for pointers to
    11  // comparable types, ie. not func slice map.
    12  // pslices.NewOrderedAny instantiates for pointers to any type or for custom sort orders.
    13  type OrderedPointers[E any] interface {
    14  	Ordered[*E]
    15  }
    16  
    17  // Ordered[E any] is an ordered list of values.
    18  //   - Ordered should be used when E is interface type or a small-sized value.
    19  //   - pslices.NewOrdered[E constraints.Ordered]() instantiates for
    20  //     comparable types, ie. not func map slice
    21  //   - pslices.NewOrderedAny[E any](cmp func(a, b E) (result int)) instantiates for any type
    22  //     or for custom sort order
    23  //   - pslices.NewOrderedPointers[E constraints.Ordered]() orders pointer to value, to
    24  //     be used for large structs or order of in-place data
    25  //   - those list implementations have Index O(log n)
    26  type Ordered[E any] interface {
    27  	Slice[E] // Element() Length() Clear() List()
    28  	// Insert adds an element to the ordered slice.
    29  	// The implementation may allow duplicates.
    30  	Insert(element E)
    31  	// Delete removes an element from the ordered slice.
    32  	// If the ordered slice does not contain element, the slice is not changed.
    33  	Delete(element E)
    34  	// Index returns index of the first occurrence of element in the ordered slice
    35  	// or -1 if element is not in the slice.
    36  	Index(element E) (index int)
    37  	// Clone returns a clone of the ordered slice
    38  	Clone() (ordered Ordered[E])
    39  }
    40  
    41  // Slice is a reusable unordered slice
    42  //   - functions by index that apply to unordered slice
    43  //   - embedded interface for slice interface types
    44  type Slice[E any] interface {
    45  	// Element returns element by index.
    46  	// if index is negative or the length of the slice or larger, the E zero-value is returned.
    47  	Element(index int) (element E)
    48  	// SubSlice returns a multiple-element sub-slice, not a clone
    49  	//	index0 and index1 aree adjusted to legal values
    50  	SubSlice(index0, index1 int) (elements []E)
    51  	// SetElement updates single element by index
    52  	//	- slice is extended if too short
    53  	SetElement(index int, element E)
    54  	// Append adds element at end
    55  	Append(slice []E)
    56  	// DeleteIndex removes elements by index
    57  	//	- index1 default is slice length
    58  	DeleteIndex(index0 int, index1 ...int)
    59  	// Length returns number of elements in the slice
    60  	Length() (length int)
    61  	// Cap returns slice capacity
    62  	Cap() (capacity int)
    63  	// Clear empties the ordered slice
    64  	Clear()
    65  	// List returns a clone of the internal slice
    66  	List(n ...int) (list []E)
    67  }