gostringlist

README

gostringlist

A class which implements convenience functions for working with lists of strings released under the MIT license.

Description

Go is a great language, but sometimes it's more than a little inconvenient. This module makes working with lists of strings a little easier--probably not at all with Go's level of Zen, but whatever. It's heavily influenced by Python's string management methods, so you'll probably find something helpful here.

Usage

Create a StringList object instance with myList := gostringlist.New() and off you go. Helpful methods listed below:

Access

• Items - the []string slice used for internal storage. You'll be accessing this from time to time.
• Copy() - create a duplicate of the object
• ToString() - converts the items into a pretty-printed string which is helpful for debugging

Management

• Append() - convenient access and syntactic sugar, no more, no less
• Insert() - inserts a string at the specified index. Good for one-off insertions, but performance isn't great if used a lot
• Remove() - deletes the item at the specified index.
• RemoveUnordered() - A faster item deletion method if you don't care about items' order
• Join() - convenient access and syntactic sugar, no more, no less
• Filter() - takes a filtering function and creates a new StringList object based on the filter. If you miss Python's list comprehensions, you'll find this useful.
• MatchFilter() - returns a new StringList containing all the items which match the supplied regular expression. Keep in mind that Go's regexes are their own special flavor.
• ReplaceAllFilter() - performs a regular-expression search and replace and returns a new StringList object containing the results.

Comparison

• IsEqual(), IsEmpty() - helpful comparison methods
• IndexOf() - get the index of a string value or -1 if it doesn't exist
• Contains() - returns true if the string passed to it is in the list

Filtering

Filter is a generic interface to creating new StringList objects from the original, similar to Python's list comprehensions, and takes a pointer to a filter function. The filter function is passed the index of the current item and the slice of strings to be used as the source. It is expected to return a boolean and a string. The boolean value specifies whether the returned string is to be added to the filtered list.

// Uppercase Filter just returns converts items to all capitals
func UppercaseFilter(index int, list []string) (bool, string) {
	return true, strings.ToUpper(list[index])
}

Contributing

This module is meant to help Go developers remove some annoyance and boilerplate code caused by Go's minimalism. Contributions are always welcome.

Documentation

Overview

Package gostringlist - an object to make managing lists of strings more convenient. In some cases, convenient frontends for functionality defined in other packages are provided

©2020 Jon Yoder <jsyoder@mailfence.com> Released under the MIT License

Index

• type StringList
  • func New() *StringList
  • func (list *StringList) Append(str string)
  • func (list StringList) Contains(str string) bool
  • func (list StringList) Copy() StringList
  • func (list StringList) Filter(op func(int, []string) (bool, string)) StringList
  • func (list StringList) IndexOf(str string) int
  • func (list *StringList) Insert(str string, index int) error
  • func (list StringList) IsEmpty() bool
  • func (list StringList) IsEqual(list2 StringList) bool
  • func (list StringList) Join(sep string) string
  • func (list StringList) MatchFilter(pattern string) (StringList, error)
  • func (list *StringList) Remove(str string)
  • func (list *StringList) RemoveUnordered(str string)
  • func (list StringList) ReplaceAllFilter(pattern string, repl string) (StringList, error)
  • func (list *StringList) Sort()
  • func (list StringList) ToString() string

Types

type StringList

type StringList struct {
	Items []string
}

StringList - a class for managing and manipulating lists of strings. It stores the items internally as a slice, so memory management caveats apply.

func New

func New() *StringList

New creates a new empty list

func (*StringList) Append

func (list *StringList) Append(str string)

Append appends a string to the list

func (StringList) Contains

func (list StringList) Contains(str string) bool

Contains returns true if the list contains an exact match of the specified string

func (StringList) Copy

func (list StringList) Copy() StringList

Copy creates a duplicate of the existing object

func (StringList) Filter

func (list StringList) Filter(op func(int, []string) (bool, string)) StringList

Filter is a generic interface to creating new StringLists from the original, similar to Python's list comprehensions. It takes a pointer to a filter function. The filter function is passed an index to the current item and the slice of strings to be used as the source. It is expected to return a boolean and a string. The boolean value specifies whether the returned string is to be added to the filtered list.

func (StringList) IndexOf

func (list StringList) IndexOf(str string) int

IndexOf returns the index of item if the list contains an exact match of the specified string or -1 if not found

func (*StringList) Insert

func (list *StringList) Insert(str string, index int) error

Insert inserts the specified string into the list at the specified index. Like Remove(), this method performs some memory reallocations and copying as needed in order to provide convenience. As such, it is expensive, and if you need to do a lot of insertions, a task-specific implementation will perform better.

func (StringList) IsEmpty

func (list StringList) IsEmpty() bool

IsEmpty returns true if the object contains no items.

func (StringList) IsEqual

func (list StringList) IsEqual(list2 StringList) bool

IsEqual returns true if the current object's items match exactly those of the passed StringList.

func (StringList) Join

func (list StringList) Join(sep string) string

Join - convenience function to return all items joined by the specified character

func (StringList) MatchFilter

func (list StringList) MatchFilter(pattern string) (StringList, error)

MatchFilter returns a new StringList containing all the items in the list which match the supplied regular expression

func (*StringList) Remove

func (list *StringList) Remove(str string)

Remove deletes the string from the list. This method removes the item by copying each element after the one deleted to the slot before it, which is the method recommended from The Go Programming Language. Speed is sacrificed for the sake of convenience. If you intend to do a lot of removal, you are better off implementing a task-specific version.

func (*StringList) RemoveUnordered

func (list *StringList) RemoveUnordered(str string)

RemoveUnordered deletes the string from the list like Remove(), but it rearranges the items for the sake of speed. If the order of the list items doesn't matter, this method should be preferred over Remove()

func (StringList) ReplaceAllFilter

func (list StringList) ReplaceAllFilter(pattern string, repl string) (StringList, error)

ReplaceAllFilter returns a new StringList containing all the items in the list which match the supplied regular expression

func (*StringList) Sort

func (list *StringList) Sort()

Sort - sorts the list in ascending alphabetical order

func (StringList) ToString

func (list StringList) ToString() string

ToString converts the list to a string conveying its contents