goutils: github.com/Masterminds/goutils Index | Examples | Files

package goutils

import "github.com/Masterminds/goutils"

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

Package Files

randomstringutils.go stringutils.go wordutils.go

Constants

const INDEX_NOT_FOUND = -1

Typically returned by functions where a searched item cannot be found

const VERSION = "1.0.0"

VERSION indicates the current version of goutils

Variables

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

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

func Abbreviate Uses

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

Code:

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 Uses

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

Code:

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 Uses

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

Code:

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 Uses

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

Code:

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 DeleteWhiteSpace Uses

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

Code:

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 Uses

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)

Code:

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 Uses

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

Code:

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 Uses

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

Code:

in := "John Doe.Ray"
delimiters := []rune{' ', '.'}

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

Output:

JD
JDR

func IsBlank Uses

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 ("")

Code:

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 Uses

func IsEmpty(str string) bool

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

func Random Uses

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 Uses

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 Uses

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 Uses

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 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 RandomAscii Uses

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 Uses

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 Uses

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 Uses

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)

Code:

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 Uses

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

Code:

in := "This Is A.Test"
fmt.Println(SwapCase(in))

Output:

tHIS iS a.tEST

func Uncapitalize Uses

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

Code:

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 Uses

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

Code:

in := "Bob Manuel Bob Manuel"
wrapLength := 10

fmt.Println(Wrap(in, wrapLength))

Output:

Bob Manuel
Bob Manuel

func WrapCustom Uses

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

Code:

in := "BobManuelBob Bob"
wrapLength := 10
newLineStr := "<br\\>"
wrapLongWords := false

fmt.Println(WrapCustom(in, wrapLength, newLineStr, wrapLongWords))

Output:

BobManuelBob<br\>Bob

Code:

in := "BobManuelBob Bob"
wrapLength := 10
newLineStr := "<br\\>"
wrapLongWords := true

fmt.Println(WrapCustom(in, wrapLength, newLineStr, wrapLongWords))

Output:

BobManuelB<br\>ob Bob

Package goutils imports 8 packages (graph). Updated 2017-05-31. Refresh now. Tools for package owners.