goutils

package module
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 4, 2021 License: Apache-2.0 Imports: 9 Imported by: 109

README

GoUtils

GoDoc Build Status Build status

GoUtils provides users with utility functions to manipulate strings in various ways. It is a Go implementation of some string manipulation libraries of Java Apache Commons. GoUtils includes the following Java Apache Commons classes:

  • WordUtils
  • RandomStringUtils
  • StringUtils (partial implementation)

Installation

If you have Go set up on your system, from the GOPATH directory within the command line/terminal, enter this:

go get github.com/Masterminds/goutils

If you do not have Go set up on your system, please follow the Go installation directions from the documenation, and then follow the instructions above to install GoUtils.

Documentation

GoUtils doc is available here: GoDoc

Usage

The code snippets below show examples of how to use GoUtils. Some functions return errors while others do not. The first instance below, which does not return an error, is the Initials function (located within the wordutils.go file).

package main

import (
    "fmt"
	"github.com/Masterminds/goutils"
)

func main() {

	// EXAMPLE 1: A goutils function which returns no errors
    fmt.Println (goutils.Initials("John Doe Foo")) // Prints out "JDF"

}

Some functions return errors mainly due to illegal arguements used as parameters. The code example below illustrates how to deal with function that returns an error. In this instance, the function is the Random function (located within the randomstringutils.go file).

package main

import (
    "fmt"
    "github.com/Masterminds/goutils"
)

func main() {

    // EXAMPLE 2: A goutils function which returns an error
    rand1, err1 := goutils.Random (-1, 0, 0, true, true)  

    if err1 != nil {
		fmt.Println(err1) // Prints out error message because -1 was entered as the first parameter in goutils.Random(...)
	} else {
		fmt.Println(rand1)
	}

}

License

GoUtils is licensed under the Apache License, Version 2.0. Please check the LICENSE.txt file or visit http://www.apache.org/licenses/LICENSE-2.0 for a copy of the license.

Issue Reporting

Make suggestions or report issues using the Git issue tracker: https://github.com/Masterminds/goutils/issues

Website

Documentation

Overview

Package goutils provides utility functions to manipulate strings in various ways. The code snippets below show examples of how to use goutils. Some functions return errors while others do not, so usage would vary as a result.

Example: 

package main

import (
    "fmt"
    "github.com/aokoli/goutils"
)

func main() {

    // EXAMPLE 1: A goutils function which returns no errors
    fmt.Println (goutils.Initials("John Doe Foo")) // Prints out "JDF"

    // EXAMPLE 2: A goutils function which returns an error
    rand1, err1 := goutils.Random (-1, 0, 0, true, true)

    if err1 != nil {
        fmt.Println(err1) // Prints out error message because -1 was entered as the first parameter in goutils.Random(...)
    } else {
        fmt.Println(rand1)
    }
}

Index

Examples

Constants

View Source 
const INDEX_NOT_FOUND = -1

Typically returned by functions where a searched item cannot be found

View Source 
const VERSION = "1.0.0"

VERSION indicates the current version of goutils

Variables

View Source 
var RANDOM = rand.New(rand.NewSource(time.Now().UnixNano()))

RANDOM provides the time-based seed used to generate random numbers

Functions

func Abbreviate 

func Abbreviate(str string, maxWidth int) (string, error)

Abbreviate abbreviates a string using ellipses. This will turn the string "Now is the time for all good men" into "Now is the time for..."

Specifically, the algorithm is as follows:

  • If str is less than maxWidth characters long, return it.
  • Else abbreviate it to (str[0:maxWidth - 3] + "...").
  • If maxWidth is less than 4, return an illegal argument error.
  • In no case will it return a string of length greater than maxWidth.

Parameters: 

str -  the string to check
maxWidth - maximum length of result string, must be at least 4

Returns: 

string - abbreviated string
error - if the width is too small
Example 
str := "abcdefg"
out1, _ := Abbreviate(str, 6)
out2, _ := Abbreviate(str, 7)
out3, _ := Abbreviate(str, 8)
out4, _ := Abbreviate(str, 4)
_, err1 := Abbreviate(str, 3)

fmt.Println(out1)
fmt.Println(out2)
fmt.Println(out3)
fmt.Println(out4)
fmt.Println(err1)

Output:

abc...
abcdefg
abcdefg
a...
stringutils illegal argument: Minimum abbreviation width is 4

func AbbreviateFull 

func AbbreviateFull(str string, offset int, maxWidth int) (string, error)

AbbreviateFull abbreviates a string using ellipses. This will turn the string "Now is the time for all good men" into "...is the time for..." This function works like Abbreviate(string, int), but allows you to specify a "left edge" offset. Note that this left edge is not necessarily going to be the leftmost character in the result, or the first character following the ellipses, but it will appear somewhere in the result. In no case will it return a string of length greater than maxWidth.

Parameters: 

str - the string to check
offset - left edge of source string
maxWidth - maximum length of result string, must be at least 4

Returns: 

string - abbreviated string
error - if the width is too small
Example 
str := "abcdefghijklmno"
str2 := "abcdefghij"
out1, _ := AbbreviateFull(str, -1, 10)
out2, _ := AbbreviateFull(str, 0, 10)
out3, _ := AbbreviateFull(str, 1, 10)
out4, _ := AbbreviateFull(str, 4, 10)
out5, _ := AbbreviateFull(str, 5, 10)
out6, _ := AbbreviateFull(str, 6, 10)
out7, _ := AbbreviateFull(str, 8, 10)
out8, _ := AbbreviateFull(str, 10, 10)
out9, _ := AbbreviateFull(str, 12, 10)
_, err1 := AbbreviateFull(str2, 0, 3)
_, err2 := AbbreviateFull(str2, 5, 6)

fmt.Println(out1)
fmt.Println(out2)
fmt.Println(out3)
fmt.Println(out4)
fmt.Println(out5)
fmt.Println(out6)
fmt.Println(out7)
fmt.Println(out8)
fmt.Println(out9)
fmt.Println(err1)
fmt.Println(err2)

Output:

abcdefg...
abcdefg...
abcdefg...
abcdefg...
...fghi...
...ghij...
...ijklmno
...ijklmno
...ijklmno
stringutils illegal argument: Minimum abbreviation width is 4
stringutils illegal argument: Minimum abbreviation width with offset is 7

func Capitalize 

func Capitalize(str string, delimiters ...rune) string

Capitalize capitalizes all the delimiter separated words in a string. Only the first letter of each word is changed. To convert the rest of each word to lowercase at the same time, use CapitalizeFully(str string, delimiters ...rune). The delimiters represent a set of characters understood to separate words. The first string character and the first non-delimiter character after a delimiter will be capitalized. A "" input string returns "". Capitalization uses the Unicode title case, normally equivalent to upper case.

Parameters: 

str - the string to capitalize
delimiters - set of characters to determine capitalization, exclusion of this parameter means whitespace would be delimeter

Returns: 

capitalized string
Example 
in := "test is going.well.thank.you.for inquiring" // Compare input to CapitalizeFully example
delimiters := []rune{' ', '.'}

fmt.Println(Capitalize(in))
fmt.Println(Capitalize(in, delimiters...))

Output:

Test Is Going.well.thank.you.for Inquiring
Test Is Going.Well.Thank.You.For Inquiring

func CapitalizeFully 

func CapitalizeFully(str string, delimiters ...rune) string

CapitalizeFully converts all the delimiter separated words in a string into capitalized words, that is each word is made up of a titlecase character and then a series of lowercase characters. The delimiters represent a set of characters understood to separate words. The first string character and the first non-delimiter character after a delimiter will be capitalized. Capitalization uses the Unicode title case, normally equivalent to upper case.

Parameters: 

str - the string to capitalize fully
delimiters - set of characters to determine capitalization, exclusion of this parameter means whitespace would be delimeter

Returns: 

capitalized string
Example 
in := "tEsT iS goiNG.wELL.tHaNk.yOU.for inqUIrING" // Notice scattered capitalization
delimiters := []rune{' ', '.'}

fmt.Println(CapitalizeFully(in))
fmt.Println(CapitalizeFully(in, delimiters...))

Output:

Test Is Going.well.thank.you.for Inquiring
Test Is Going.Well.Thank.You.For Inquiring

func CryptoRandom added in v1.1.0 

func CryptoRandom(count int, start int, end int, letters bool, numbers bool, chars ...rune) (string, error)

CryptoRandom creates a random string based on a variety of options, using using golang's crypto/rand source of randomness. If the parameters start and end are both 0, start and end are set to ' ' and 'z', the ASCII printable characters, will be used, unless letters and numbers are both false, in which case, start and end are set to 0 and math.MaxInt32, respectively. If chars is not nil, characters stored in chars that are between start and end are chosen.

Parameters: 

count - the length of random string to create
start - the position in set of chars (ASCII/Unicode int) to start at
end - the position in set of chars (ASCII/Unicode int) to end before
letters - if true, generated string may include alphabetic characters
numbers - if true, generated string may include numeric characters
chars - the set of chars to choose randoms from. If nil, then it will use the set of all chars.

Returns: 

string - the random string
error - an error stemming from invalid parameters: if count < 0; or the provided chars array is empty; or end <= start; or end > len(chars)

func CryptoRandomAlphaNumeric added in v1.1.0 

func CryptoRandomAlphaNumeric(count int) (string, error)

CryptoRandomAlphaNumeric creates a random string whose length is the number of characters specified. Characters will be chosen from the set of alpha-numeric characters.

Parameter: 

count - the length of random string to create

Returns: 

string - the random string
error - an error stemming from an invalid parameter within underlying function, CryptoRandom(...)

func CryptoRandomAlphaNumericCustom added in v1.1.0 

func CryptoRandomAlphaNumericCustom(count int, letters bool, numbers bool) (string, error)

CryptoRandomAlphaNumericCustom creates a random string whose length is the number of characters specified. Characters will be chosen from the set of alpha-numeric characters as indicated by the arguments.

Parameters: 

count - the length of random string to create
letters - if true, generated string may include alphabetic characters
numbers - if true, generated string may include numeric characters

Returns: 

string - the random string
error - an error stemming from an invalid parameter within underlying function, CryptoRandom(...)

func CryptoRandomAlphabetic added in v1.1.0 

func CryptoRandomAlphabetic(count int) (string, error)

CryptoRandomAlphabetic creates a random string whose length is the number of characters specified. Characters will be chosen from the set of alpha-numeric characters as indicated by the arguments.

Parameters: 

count - the length of random string to create
letters - if true, generated string may include alphabetic characters
numbers - if true, generated string may include numeric characters

Returns: 

string - the random string
error - an error stemming from an invalid parameter within underlying function, CryptoRandom(...)

func CryptoRandomAscii added in v1.1.0 

func CryptoRandomAscii(count int) (string, error)

CryptoRandomAscii creates a random string whose length is the number of characters specified. Characters will be chosen from the set of characters whose ASCII value is between 32 and 126 (inclusive).

Parameter: 

count - the length of random string to create

Returns: 

string - the random string
error - an error stemming from an invalid parameter within underlying function, CryptoRandom(...)

func CryptoRandomNonAlphaNumeric added in v1.1.0 

func CryptoRandomNonAlphaNumeric(count int) (string, error)

CryptoRandomNonAlphaNumeric creates a random string whose length is the number of characters specified. Characters will be chosen from the set of all characters (ASCII/Unicode values between 0 to 2,147,483,647 (math.MaxInt32)).

Parameter: 

count - the length of random string to create

Returns: 

string - the random string
error - an error stemming from an invalid parameter within underlying function, CryptoRandom(...)

func CryptoRandomNumeric added in v1.1.0 

func CryptoRandomNumeric(count int) (string, error)

CryptoRandomNumeric creates a random string whose length is the number of characters specified. Characters will be chosen from the set of numeric characters.

Parameter: 

count - the length of random string to create

Returns: 

string - the random string
error - an error stemming from an invalid parameter within underlying function, CryptoRandom(...)

func DefaultIfBlank added in v1.1.1 

func DefaultIfBlank(str string, defaultStr string) string

Returns either the passed in string, or if the string is whitespace, empty (""), the value of defaultStr.

Example 
out1 := DefaultIfBlank("", "abc")
out2 := DefaultIfBlank(" ", "abc")
out3 := DefaultIfBlank("ab", "cd")

fmt.Println(out1)
fmt.Println(out2)
fmt.Println(out3)

Output:

abc
abc
ab

func DefaultString added in v1.1.1 

func DefaultString(str string, defaultStr string) string

Returns either the passed in string, or if the string is empty, the value of defaultStr.

Example 
out1 := DefaultString("abc", "")
out2 := DefaultString("ab", "c")
out3 := DefaultString("", "abc")

fmt.Println(out1)
fmt.Println(out2)
fmt.Println(out3)

Output:

abc
ab
abc

func DeleteWhiteSpace 

func DeleteWhiteSpace(str string) string

DeleteWhiteSpace deletes all whitespaces from a string as defined by unicode.IsSpace(rune). It returns the string without whitespaces.

Parameter: 

str - the string to delete whitespace from, may be nil

Returns: 

the string without whitespaces
Example 
out1 := DeleteWhiteSpace(" ")
out2 := DeleteWhiteSpace("bob")
out3 := DeleteWhiteSpace("bob   ")
out4 := DeleteWhiteSpace("  b  o    b  ")

fmt.Println(out1)
fmt.Println(out2)
fmt.Println(out3)
fmt.Println(out4)

Output:


bob
bob
bob

func IndexOf 

func IndexOf(str string, sub string, start int) int

IndexOf returns the index of the first instance of sub in str, with the search beginning from the index start point specified. -1 is returned if sub is not present in str.

An empty string ("") will return -1 (INDEX_NOT_FOUND). A negative start position is treated as zero. A start position greater than the string length returns -1.

Parameters: 

str - the string to check
sub - the substring to find
start - the start position; negative treated as zero

Returns: 

the first index where the sub string was found  (always >= start)
Example 
str := "abcdefgehije"
out1 := IndexOf(str, "e", 0)
out2 := IndexOf(str, "e", 5)
out3 := IndexOf(str, "e", 8)
out4 := IndexOf(str, "eh", 0)
out5 := IndexOf(str, "eh", 22)
out6 := IndexOf(str, "z", 0)
out7 := IndexOf(str, "", 0)

fmt.Println(out1)
fmt.Println(out2)
fmt.Println(out3)
fmt.Println(out4)
fmt.Println(out5)
fmt.Println(out6)
fmt.Println(out7)

Output:

4
7
11
7
-1
-1
-1

func IndexOfDifference 

func IndexOfDifference(str1 string, str2 string) int

IndexOfDifference compares two strings, and returns the index at which the strings begin to differ.

Parameters: 

str1 - the first string
str2 - the second string

Returns: 

the index where str1 and str2 begin to differ; -1 if they are equal
Example 
out1 := IndexOfDifference("abc", "abc")
out2 := IndexOfDifference("ab", "abxyz")
out3 := IndexOfDifference("", "abc")
out4 := IndexOfDifference("abcde", "abxyz")

fmt.Println(out1)
fmt.Println(out2)
fmt.Println(out3)
fmt.Println(out4)

Output:

-1
2
0
2

func Initials 

func Initials(str string, delimiters ...rune) string

Initials extracts the initial letters from each word in the string. The first letter of the string and all first letters after the defined delimiters are returned as a new string. Their case is not changed. If the delimiters parameter is excluded, then Whitespace is used. Whitespace is defined by unicode.IsSpacea(char). An empty delimiter array returns an empty string.

Parameters: 

str - the string to get initials from
delimiters - set of characters to determine words, exclusion of this parameter means whitespace would be delimeter

Returns: 

string of initial letters
Example 
in := "John Doe.Ray"
delimiters := []rune{' ', '.'}

fmt.Println(Initials(in))
fmt.Println(Initials(in, delimiters...))

Output:

JD
JDR

func IsBlank 

func IsBlank(str string) bool

IsBlank checks if a string is whitespace or empty (""). Observe the following behavior: 

goutils.IsBlank("")        = true
goutils.IsBlank(" ")       = true
goutils.IsBlank("bob")     = false
goutils.IsBlank("  bob  ") = false

Parameter: 

str - the string to check

Returns: 

true - if the string is whitespace or empty ("")
Example 
out1 := IsBlank("")
out2 := IsBlank(" ")
out3 := IsBlank("bob")
out4 := IsBlank("  bob  ")

fmt.Println(out1)
fmt.Println(out2)
fmt.Println(out3)
fmt.Println(out4)

Output:

true
true
false
false

func IsEmpty 

func IsEmpty(str string) bool

IsEmpty checks if a string is empty (""). Returns true if empty, and false otherwise.

func Random 

func Random(count int, start int, end int, letters bool, numbers bool, chars ...rune) (string, error)

Random creates a random string based on a variety of options, using default source of randomness. This method has exactly the same semantics as RandomSeed(int, int, int, bool, bool, []char, *rand.Rand), but instead of using an externally supplied source of randomness, it uses the internal *rand.Rand instance.

Parameters: 

count - the length of random string to create
start - the position in set of chars (ASCII/Unicode int) to start at
end - the position in set of chars (ASCII/Unicode int) to end before
letters - if true, generated string may include alphabetic characters
numbers - if true, generated string may include numeric characters
chars - the set of chars to choose randoms from. If nil, then it will use the set of all chars.

Returns: 

string - the random string
error - an error stemming from an invalid parameter within underlying function, RandomSeed(...)

func RandomAlphaNumeric 

func RandomAlphaNumeric(count int) (string, error)

RandomAlphaNumeric creates a random string whose length is the number of characters specified. Characters will be chosen from the set of alpha-numeric characters.

Parameter: 

count - the length of random string to create

Returns: 

string - the random string
error - an error stemming from an invalid parameter within underlying function, RandomSeed(...)

func RandomAlphaNumericCustom 

func RandomAlphaNumericCustom(count int, letters bool, numbers bool) (string, error)

RandomAlphaNumericCustom creates a random string whose length is the number of characters specified. Characters will be chosen from the set of alpha-numeric characters as indicated by the arguments.

Parameters: 

count - the length of random string to create
letters - if true, generated string may include alphabetic characters
numbers - if true, generated string may include numeric characters

Returns: 

string - the random string
error - an error stemming from an invalid parameter within underlying function, RandomSeed(...)

func RandomAlphabetic 

func RandomAlphabetic(count int) (string, error)

RandomAlphabetic creates a random string whose length is the number of characters specified. Characters will be chosen from the set of alphabetic characters.

Parameters: 

count - the length of random string to create

Returns: 

string - the random string
error - an error stemming from an invalid parameter within underlying function, RandomSeed(...)

func RandomAscii 

func RandomAscii(count int) (string, error)

RandomAscii creates a random string whose length is the number of characters specified. Characters will be chosen from the set of characters whose ASCII value is between 32 and 126 (inclusive).

Parameter: 

count - the length of random string to create

Returns: 

string - the random string
error - an error stemming from an invalid parameter within underlying function, RandomSeed(...)

func RandomNonAlphaNumeric 

func RandomNonAlphaNumeric(count int) (string, error)

RandomNonAlphaNumeric creates a random string whose length is the number of characters specified. Characters will be chosen from the set of all characters (ASCII/Unicode values between 0 to 2,147,483,647 (math.MaxInt32)).

Parameter: 

count - the length of random string to create

Returns: 

string - the random string
error - an error stemming from an invalid parameter within underlying function, RandomSeed(...)

func RandomNumeric 

func RandomNumeric(count int) (string, error)

RandomNumeric creates a random string whose length is the number of characters specified. Characters will be chosen from the set of numeric characters.

Parameter: 

count - the length of random string to create

Returns: 

string - the random string
error - an error stemming from an invalid parameter within underlying function, RandomSeed(...)

func RandomSeed 

func RandomSeed(count int, start int, end int, letters bool, numbers bool, chars []rune, random *rand.Rand) (string, error)

RandomSeed creates a random string based on a variety of options, using supplied source of randomness. If the parameters start and end are both 0, start and end are set to ' ' and 'z', the ASCII printable characters, will be used, unless letters and numbers are both false, in which case, start and end are set to 0 and math.MaxInt32, respectively. If chars is not nil, characters stored in chars that are between start and end are chosen. This method accepts a user-supplied *rand.Rand instance to use as a source of randomness. By seeding a single *rand.Rand instance with a fixed seed and using it for each call, the same random sequence of strings can be generated repeatedly and predictably.

Parameters: 

count - the length of random string to create
start - the position in set of chars (ASCII/Unicode decimals) to start at
end - the position in set of chars (ASCII/Unicode decimals) to end before
letters - if true, generated string may include alphabetic characters
numbers - if true, generated string may include numeric characters
chars - the set of chars to choose randoms from. If nil, then it will use the set of all chars.
random - a source of randomness.

Returns: 

string - the random string
error - an error stemming from invalid parameters: if count < 0; or the provided chars array is empty; or end <= start; or end > len(chars)
Example 
var seed int64 = 10 // If you change this seed #, the random sequence below will change
random := rand.New(rand.NewSource(seed))
chars := []rune{'1', '2', '3', 'a', 'b', 'c'}

rand1, _ := RandomSeed(5, 0, 0, true, true, nil, random)      // RandomAlphaNumeric (Alphabets and numbers possible)
rand2, _ := RandomSeed(5, 0, 0, true, false, nil, random)     // RandomAlphabetic (Only alphabets)
rand3, _ := RandomSeed(5, 0, 0, false, true, nil, random)     // RandomNumeric (Only numbers)
rand4, _ := RandomSeed(5, 32, 127, false, false, nil, random) // RandomAscii (Alphabets, numbers, and other ASCII chars)
rand5, _ := RandomSeed(5, 0, 0, true, true, chars, random)    // RandomSeed with custom characters

fmt.Println(rand1)
fmt.Println(rand2)
fmt.Println(rand3)
fmt.Println(rand4)
fmt.Println(rand5)

Output:

3ip9v
MBrbj
88935
H_I;E
2b2ca

func SwapCase 

func SwapCase(str string) string

SwapCase swaps the case of a string using a word based algorithm.

Conversion algorithm: 

Upper case character converts to Lower case
Title case character converts to Lower case
Lower case character after Whitespace or at start converts to Title case
Other Lower case character converts to Upper case
Whitespace is defined by unicode.IsSpace(char).

Parameters: 

str - the string to swap case

Returns: 

the changed string
Example 
in := "This Is A.Test"
fmt.Println(SwapCase(in))

Output:

tHIS iS a.tEST

func Uncapitalize 

func Uncapitalize(str string, delimiters ...rune) string

Uncapitalize uncapitalizes all the whitespace separated words in a string. Only the first letter of each word is changed. The delimiters represent a set of characters understood to separate words. The first string character and the first non-delimiter character after a delimiter will be uncapitalized. Whitespace is defined by unicode.IsSpace(char).

Parameters: 

str - the string to uncapitalize fully
delimiters - set of characters to determine capitalization, exclusion of this parameter means whitespace would be delimeter

Returns: 

uncapitalized string
Example 
in := "This Is A.Test"
delimiters := []rune{' ', '.'}

fmt.Println(Uncapitalize(in))
fmt.Println(Uncapitalize(in, delimiters...))

Output:

this is a.Test
this is a.test

func Wrap 

func Wrap(str string, wrapLength int) string

Wrap wraps a single line of text, identifying words by ' '. New lines will be separated by '\n'. Very long words, such as URLs will not be wrapped. Leading spaces on a new line are stripped. Trailing spaces are not stripped.

Parameters: 

str - the string to be word wrapped
wrapLength - the column (a column can fit only one character) to wrap the words at, less than 1 is treated as 1

Returns: 

a line with newlines inserted
Example 
in := "Bob Manuel Bob Manuel"
wrapLength := 10

fmt.Println(Wrap(in, wrapLength))

Output:

Bob Manuel
Bob Manuel

func WrapCustom 

func WrapCustom(str string, wrapLength int, newLineStr string, wrapLongWords bool) string

WrapCustom wraps a single line of text, identifying words by ' '. Leading spaces on a new line are stripped. Trailing spaces are not stripped.

Parameters: 

str - the string to be word wrapped
wrapLength - the column number (a column can fit only one character) to wrap the words at, less than 1 is treated as 1
newLineStr - the string to insert for a new line, "" uses '\n'
wrapLongWords - true if long words (such as URLs) should be wrapped

Returns: 

a line with newlines inserted

Types

This section is empty.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.