items

import "github.com/KEINOS/go-items/items"

Package items github.com/KEINOS/go-items/items is an another simple slice manager.

It does nothing special but manage a slice of objects as a list. Such as adding (append/push, prepend/unsift, insert), delete, pop, shift, swap and sort.

Install

go get "github.com/KEINOS/go-items"

Index

• type TItems
  • func New(initial ...interface{}) *TItems
  • func (i *TItems) Append(item interface{})
  • func (i *TItems) Delete(index int)
  • func (i *TItems) InsertAfter(item interface{}, index int)
  • func (i *TItems) InsertBefore(item interface{}, index int)
  • func (i *TItems) Pop() interface{}
  • func (i *TItems) Prepend(item interface{})
  • func (i *TItems) Push(item interface{})
  • func (i *TItems) Shift() interface{}
  • func (i *TItems) Shuffle()
  • func (i *TItems) Sort(isLessThan func(int, int) bool)
  • func (i *TItems) SortRange(indexFrom int, numItems int, isLessThan func(int, int) bool) error
  • func (i *TItems) Swap(a int, b int) error
  • func (i *TItems) Unshift(item interface{})

type TItems

TItems is the structure that holds all the items.

type TItems struct {
    // Items is the list of items.
    Items []interface{} `json:"items"`
    // Sorted is a flag that indicates if the items are sorted.
    Sorted bool `json:"sorted"`
}

func New

func New(initial ...interface{}) *TItems

New returns the pointer to newly created TItems object.

Example

Example of basic method usage.

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
	"os"
)

func main() {
	// Create a new list of items with initial values
	list := items.New("a", "b", "c")

	/* Add to the bottom */

	// Push adds the arg as a new item to the end of the list
	list.Push("d") // {"a", "b", "c", "d"}

	// Append is an alias of Push
	list.Append("e") // {"a", "b", "c", "d", "e"}

	/* Add to the top */

	// Unshift adds new item to the beginning of the list
	list.Unshift("f") // {"f", "a", "b", "c", "d", "e"}

	// Prepend is an alias of Unshift
	list.Prepend("g") // {"g", "f", "a", "b", "c", "d", "e"}

	/* Insert */

	// InsertArter adds new item after the specified index
	list.InsertAfter("h", 1) // {"g", "f", "h", "a", "b", "c", "d", "e"}

	// InsertBefore adds new item before the specified index
	list.InsertBefore("i", 1) // {"g", "i", "f", "h", "a", "b", "c", "d", "e"}

	/* Remove */

	// Delete removes the item at the specified index
	list.Delete(1) // {"g", "f", "h", "a", "b", "c", "d", "e"}

	// Pop removes the last item from the list and returns that item
	popOut := list.Pop()          // {"g", "f", "h", "a", "b", "c", "d"}
	fmt.Println("popOut", popOut) // => popOut e

	// Shift removes the first item from the list and returns that item
	shiftOut := list.Shift()           // {"f", "h", "a", "b", "c", "d"}
	fmt.Println("shiftOut:", shiftOut) // => shiftOut: g

	/* Manage */

	// Swap the item between the specified index and the next one
	if err := list.Swap(1, 5); err != nil { // {"f", "d", "a", "b", "c", "h"}
		fmt.Fprintf(os.Stderr, "error while swapping: %v", err)
		os.Exit(1)
	}

	fmt.Println(list.Items) // => [f d a b c h]
}

Output

popOut e
shiftOut: g
[f d a b c h]

Example

Example of user defined type items.

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
)

func main() {
	// Define your strtuct of the item
	type demoItem struct {
		MyName string
	}

	// Create item
	item1 := demoItem{MyName: "demo1"}
	item2 := demoItem{MyName: "demo2"}

	// Create list with item1 for the first item
	list := items.New(item1)

	// Push item2 to the list
	list.Append(item2)

	// To access item field, re-cast the original item's type
	result1 := list.Items[0].(demoItem).MyName
	fmt.Println(result1) // "demo1"

	// To access item field, re-cast the original item's type
	result2 := list.Items[1].(demoItem).MyName
	fmt.Println(result2) // "demo2"
}

Output

demo1
demo2

Example

Example of Sort() method.

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
	"strconv"
)

func main() {
	// Define item type.
	type demoItem struct {
		ID  string // Note that ID is a string
		Num int    // Of course, you can use any type
	}

	// Create empty list
	list := items.New()

	// Push items to the list randomly
	list.Push(demoItem{ID: "1", Num: 1})
	list.Push(demoItem{ID: "5", Num: 2})
	list.Push(demoItem{ID: "4", Num: 3})
	list.Push(demoItem{ID: "2", Num: 4})
	list.Push(demoItem{ID: "3", Num: 5})

	fmt.Println("Before Sort: ", list.Items) // [{1 1} {5 2} {4 3} {2 4} {3 5}]

	// Define IsLessThan function.
	// This function is used to sort the list by ID fields. It returns true if
	// the first item is less than the second item. The given args a and b are
	// the the indexs of the item.
	myIsLessThen := func(a, b int) bool {
		// Since the items are in interface{}, you need to re-cast the item's type
		// to get the value from the field name.
		valA := list.Items[a].(demoItem).ID
		valB := list.Items[b].(demoItem).ID

		// String -> Int
		numA, _ := strconv.Atoi(valA)
		numB, _ := strconv.Atoi(valB)

		return numA < numB
	}

	// Sort the list.
	// You need to define the range of the list and the function to sort the list.
	list.Sort(myIsLessThen)

	fmt.Println("After Sort by ID: ", list.Items) // [{1 1} {2 4} {3 5} {4 3} {5 2}]

	// Sort the list by Num field.
	list.Sort(func(a, b int) bool {
		// Re-cast type and get Num field
		valA := list.Items[a].(demoItem).Num
		valB := list.Items[b].(demoItem).Num

		return valA < valB
	})

	// Note that the order of the items were sorted by Num field.
	fmt.Println("After Sort by Num: ", list.Items) // [{1 1} {5 2} {4 3} {2 4} {3 5}]

}

Output

Before Sort:  [{1 1} {5 2} {4 3} {2 4} {3 5}]
After Sort by ID:  [{1 1} {2 4} {3 5} {4 3} {5 2}]
After Sort by Num:  [{1 1} {5 2} {4 3} {2 4} {3 5}]

func (*TItems) Append

func (i *TItems) Append(item interface{})

Append adds the item to the bottom of the list which is an alias of Push().

Example

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
)

func main() {
	list := items.New("a", "b")

	list.Append("c")

	for _, item := range list.Items {
		fmt.Println(item)
	}
}

Output

a
b
c

func (*TItems) Delete

func (i *TItems) Delete(index int)

Delete a single item of the given index from the list.

Example

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
)

func main() {
	list := items.New("a", "b", "c", "d")

	list.Delete(1)  // Remove index 1 = "b"
	list.Delete(10) // Remove undefined index(should do nothing)

	fmt.Println("Left overs:", list.Items)
}

Output

Left overs: [a c d]

func (*TItems) InsertAfter

func (i *TItems) InsertAfter(item interface{}, index int)

InsertAfter inserts the given item after the given index.

Example

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
)

func main() {
	list := items.New("1", "2", "3") // [1 2 3], Len = 3

	list.InsertAfter("4", 0)                  // Insert "4" after index 0 = "1"
	fmt.Println("Insert 4 to 0:", list.Items) // [1 4 2 3]

	list.InsertAfter("5", 1)                  // Insert "5" after index 1 = "4"
	fmt.Println("Insert 5 to 1:", list.Items) // [1 4 5 2 3]

	list.InsertAfter("6", -1)                  // Negative index will add to the top
	fmt.Println("Insert 6 to -1:", list.Items) // [6 1 4 5 2 3]

	list.InsertAfter("7", 10)                  // Oversize index will add to the bottom
	fmt.Println("Insert 7 to 10:", list.Items) // [6 1 4 5 2 3 7]

}

Output

Insert 4 to 0: [1 4 2 3]
Insert 5 to 1: [1 4 5 2 3]
Insert 6 to -1: [6 1 4 5 2 3]
Insert 7 to 10: [6 1 4 5 2 3 7]

func (*TItems) InsertBefore

func (i *TItems) InsertBefore(item interface{}, index int)

InsertBefore inserts the given item before the given index.

Example

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
)

func main() {
	list := items.New("1", "2", "3") // [1 2 3], Len = 3

	list.InsertBefore("4", 0)                 // Insert "4" before index 0 = "1"
	fmt.Println("Insert 4 to 0:", list.Items) // [4 1 2 3]

	list.InsertBefore("5", 1)                 // Insert "5" before index 1 = "1"
	fmt.Println("Insert 5 to 1:", list.Items) // [4 5 1 2 3]

	list.InsertBefore("6", -1)                 // Negative index will add to the top
	fmt.Println("Insert 6 to -1:", list.Items) // [6 4 5 1 2 3]

	list.InsertBefore("7", 10)                 // Oversize index will add to the bottom
	fmt.Println("Insert 7 to 10:", list.Items) // [6 4 5 1 2 3 7]

}

Output

Insert 4 to 0: [4 1 2 3]
Insert 5 to 1: [4 5 1 2 3]
Insert 6 to -1: [6 4 5 1 2 3]
Insert 7 to 10: [6 4 5 1 2 3 7]

func (*TItems) Pop

func (i *TItems) Pop() interface{}

Pop outs the last item from the list. It will return the last item which was removed from the list.

Example

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
)

func main() {
	list := items.New("a", "b", "c")

	poppedOut := list.Pop()

	fmt.Println("Popped out:", poppedOut)
	fmt.Println("Left overs:", list.Items)
}

Output

Popped out: c
Left overs: [a b]

func (*TItems) Prepend

func (i *TItems) Prepend(item interface{})

Prepend adds the item to the top of the list which is an alias of Unshift().

Example

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
)

func main() {
	list := items.New("a", "b")

	list.Prepend("c") // adds to the top

	for _, item := range list.Items {
		fmt.Println(item)
	}
}

Output

c
a
b

func (*TItems) Push

func (i *TItems) Push(item interface{})

Push the given item into the bottom of the list.

Example

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
)

func main() {
	list := items.New("a", "b")

	list.Push("c")

	for _, item := range list.Items {
		fmt.Println(item)
	}
}

Output

a
b
c

func (*TItems) Shift

func (i *TItems) Shift() interface{}

Shift the item from the list. It will return the deleted first item from the list.

Example

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
)

func main() {
	list := items.New("a", "b", "c")

	shiftedItem := list.Shift()

	fmt.Println("Shifted item:", shiftedItem)
	fmt.Println("Left overs  :", list.Items)
}

Output

Shifted item: a
Left overs  : [b c]

func (*TItems) Shuffle

func (i *TItems) Shuffle()

Shuffle the items.

func (*TItems) Sort

func (i *TItems) Sort(isLessThan func(int, int) bool)

Sort thelist using the given isLessThan compare function.

The isLessThan function should return true if the first argument is less than the second argument.

isLessThan := func(a, b int) bool {
	return yourItems[a] < yourItems[b]
}

Example

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
	"strconv"
)

func main() {
	// Create a new list with random order items
	list := items.New("4", "5", "3", "2", "1")

	// Sort function for comparing items
	myIsLessThen := func(a, b int) bool {
		// Note that the items are interface. Re-cast them to string then convert to int
		numA, _ := strconv.Atoi(list.Items[a].(string))
		numB, _ := strconv.Atoi(list.Items[b].(string))

		return numA < numB
	}

	// Sort the items with the custom function
	list.Sort(myIsLessThen)

	// Print the sorted items
	fmt.Println(list.Items)
}

Output

[1 2 3 4 5]

func (*TItems) SortRange

func (i *TItems) SortRange(indexFrom int, numItems int, isLessThan func(int, int) bool) error

SortRange sorts the number of items "numItems" from index "indexFrom" using the given "isLessThan" compare function.

The isLessThan function should return true if the first argument is less than the second argument.

isLessThan := func(a, b int) bool {
	return yourItems[a] < yourItems[b]
}

Example

Example to sort own defined struct items but limited to a range.

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
	"os"
	"strconv"
)

func main() {
	type MyItem struct {
		ID string
	}

	list := items.New()

	// Add items to the list but in random order
	list.Append(MyItem{ID: "4"})
	list.Append(MyItem{ID: "1"})
	list.Append(MyItem{ID: "3"})
	list.Append(MyItem{ID: "7"})
	list.Append(MyItem{ID: "8"})
	list.Append(MyItem{ID: "5"})
	list.Append(MyItem{ID: "6"})
	list.Append(MyItem{ID: "9"})
	list.Append(MyItem{ID: "10"})
	list.Append(MyItem{ID: "2"})

	fmt.Println("Before sort:", list.Items) // => [{4} {1} {3} {7} {8} {5} {6} {9} {10} {2}]

	// Sort function for comparing items
	myIsLessThen := func(a, b int) bool {
		// Note that the items are interface.
		// So you need to re-cast to the item type then convert to int
		numA, _ := strconv.Atoi(list.Items[a].(MyItem).ID)
		numB, _ := strconv.Atoi(list.Items[b].(MyItem).ID)

		return numA < numB
	}

	// Sort only the first 5 items from index 0
	if err := list.SortRange(0, 5, myIsLessThen); err != nil {
		fmt.Fprintf(os.Stderr, "error sorting: %v", err)
		os.Exit(1)
	}

	fmt.Println("After sort :", list.Items) // => [{1} {3} {4} {7} {8} {5} {6} {9} {10} {2}]
}

Output

Before sort: [{4} {1} {3} {7} {8} {5} {6} {9} {10} {2}]
After sort : [{1} {3} {4} {7} {8} {5} {6} {9} {10} {2}]

func (*TItems) Swap

func (i *TItems) Swap(a int, b int) error

Swap items between index of a and b.

Example

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
)

func main() {
	list := items.New("s", "t", "u", "d", "y")

	list.Swap(1, 3) // Swap t and d = [s d u t y]
	list.Swap(0, 1) // Swap s and d = [d s u t y]
	list.Swap(1, 2) // Swap s and u = [d u s t y]

	fmt.Println(list.Items)
}

Output

[d u s t y]

func (*TItems) Unshift

func (i *TItems) Unshift(item interface{})

Unshift adds the item to the top of the list.

Example

package main

import (
	"fmt"
	"github.com/KEINOS/go-items/items"
)

func main() {
	list := items.New("a", "b")

	list.Unshift("c") // adds to the top

	for _, item := range list.Items {
		fmt.Println(item)
	}
}

Output

c
a
b

Generated by gomarkdoc