From 6abd8bd864646a449fb06aa6ab600e4ee3e4fe8e Mon Sep 17 00:00:00 2001 From: John Guo Date: Tue, 2 Jan 2024 20:16:51 +0800 Subject: [PATCH] comments update for package gstr (#3233) --- container/garray/garray_normal_int.go | 18 ++++++++-- container/gqueue/gqueue_z_unit_test.go | 6 ++-- os/gfile/gfile.go | 28 +++++++++------ text/gstr/gstr_array.go | 3 ++ text/gstr/gstr_case.go | 29 ++++++++++++++- text/gstr/gstr_convert.go | 28 ++++++++++++--- text/gstr/gstr_create.go | 3 ++ text/gstr/gstr_sub.go | 50 ++++++++++++++++++++++---- 8 files changed, 139 insertions(+), 26 deletions(-) diff --git a/container/garray/garray_normal_int.go b/container/garray/garray_normal_int.go index a1473317018..16e59a71c94 100644 --- a/container/garray/garray_normal_int.go +++ b/container/garray/garray_normal_int.go @@ -173,7 +173,11 @@ func (a *IntArray) InsertBefore(index int, values ...int) error { a.mu.Lock() defer a.mu.Unlock() if index < 0 || index >= len(a.array) { - return gerror.NewCodef(gcode.CodeInvalidParameter, "index %d out of array range %d", index, len(a.array)) + return gerror.NewCodef( + gcode.CodeInvalidParameter, + "index %d out of array range %d", + index, len(a.array), + ) } rear := append([]int{}, a.array[index:]...) a.array = append(a.array[0:index], values...) @@ -186,7 +190,11 @@ func (a *IntArray) InsertAfter(index int, values ...int) error { a.mu.Lock() defer a.mu.Unlock() if index < 0 || index >= len(a.array) { - return gerror.NewCodef(gcode.CodeInvalidParameter, "index %d out of array range %d", index, len(a.array)) + return gerror.NewCodef( + gcode.CodeInvalidParameter, + "index %d out of array range %d", + index, len(a.array), + ) } rear := append([]int{}, a.array[index+1:]...) a.array = append(a.array[0:index+1], values...) @@ -583,7 +591,11 @@ func (a *IntArray) Fill(startIndex int, num int, value int) error { a.mu.Lock() defer a.mu.Unlock() if startIndex < 0 || startIndex > len(a.array) { - return gerror.NewCodef(gcode.CodeInvalidParameter, "index %d out of array range %d", startIndex, len(a.array)) + return gerror.NewCodef( + gcode.CodeInvalidParameter, + "index %d out of array range %d", + startIndex, len(a.array), + ) } for i := startIndex; i < startIndex+num; i++ { if i > len(a.array)-1 { diff --git a/container/gqueue/gqueue_z_unit_test.go b/container/gqueue/gqueue_z_unit_test.go index 95ca6761f09..cf87f7a48bb 100644 --- a/container/gqueue/gqueue_z_unit_test.go +++ b/container/gqueue/gqueue_z_unit_test.go @@ -75,7 +75,8 @@ func TestQueue_Close(t *testing.T) { q1 := gqueue.New() q1.Push(1) q1.Push(2) - time.Sleep(time.Millisecond) + // wait sync to channel + time.Sleep(10 * time.Millisecond) t.Assert(q1.Len(), 2) q1.Close() }) @@ -83,7 +84,8 @@ func TestQueue_Close(t *testing.T) { q1 := gqueue.New(2) q1.Push(1) q1.Push(2) - time.Sleep(time.Millisecond) + // wait sync to channel + time.Sleep(10 * time.Millisecond) t.Assert(q1.Len(), 2) q1.Close() }) diff --git a/os/gfile/gfile.go b/os/gfile/gfile.go index 3c9db89e55f..7222ed900fb 100644 --- a/os/gfile/gfile.go +++ b/os/gfile/gfile.go @@ -352,17 +352,19 @@ func SelfDir() string { // Trailing path separators are removed before extracting the last element. // If the path is empty, Base returns ".". // If the path consists entirely of separators, Basename returns a single separator. +// // Example: -// /var/www/file.js -> file.js -// file.js -> file.js +// Basename("/var/www/file.js") -> file.js +// Basename("file.js") -> file.js func Basename(path string) string { return filepath.Base(path) } // Name returns the last element of path without file extension. +// // Example: -// /var/www/file.js -> file -// file.js -> file +// Name("/var/www/file.js") -> file +// Name("file.js") -> file func Name(path string) string { base := filepath.Base(path) if i := strings.LastIndexByte(base, '.'); i != -1 { @@ -378,6 +380,10 @@ func Name(path string) string { // If the `path` is ".", Dir treats the path as current working directory. // If the `path` consists entirely of separators, Dir returns a single separator. // The returned path does not end in a separator unless it is the root directory. +// +// Example: +// Dir("/var/www/file.js") -> "/var/www" +// Dir("file.js") -> "." func Dir(path string) string { if path == "." { return filepath.Dir(RealPath(path)) @@ -416,9 +422,10 @@ func IsEmpty(path string) bool { // in the final element of path; it is empty if there is // no dot. // Note: the result contains symbol '.'. -// Eg: -// main.go => .go -// api.json => .json +// +// Example: +// Ext("main.go") => .go +// Ext("api.json") => .json func Ext(path string) string { ext := filepath.Ext(path) if p := strings.IndexByte(ext, '?'); p != -1 { @@ -429,9 +436,10 @@ func Ext(path string) string { // ExtName is like function Ext, which returns the file name extension used by path, // but the result does not contain symbol '.'. -// Eg: -// main.go => go -// api.json => json +// +// Example: +// ExtName("main.go") => go +// ExtName("api.json") => json func ExtName(path string) string { return strings.TrimLeft(Ext(path), ".") } diff --git a/text/gstr/gstr_array.go b/text/gstr/gstr_array.go index 1e467023731..c4c0f78e09b 100644 --- a/text/gstr/gstr_array.go +++ b/text/gstr/gstr_array.go @@ -24,6 +24,9 @@ func InArray(a []string, s string) bool { } // PrefixArray adds `prefix` string for each item of `array`. +// +// Example: +// PrefixArray(["a","b"], "gf_") -> ["gf_a", "gf_b"] func PrefixArray(array []string, prefix string) { for k, v := range array { array[k] = prefix + v diff --git a/text/gstr/gstr_case.go b/text/gstr/gstr_case.go index 714f44a5a7f..252db6195bb 100644 --- a/text/gstr/gstr_case.go +++ b/text/gstr/gstr_case.go @@ -104,11 +104,17 @@ func CaseConvert(s string, caseType CaseType) string { } // CaseCamel converts a string to CamelCase. +// +// Example: +// CaseCamel("any_kind_of_string") -> AnyKindOfString func CaseCamel(s string) string { return toCamelInitCase(s, true) } // CaseCamelLower converts a string to lowerCamelCase. +// +// Example: +// CaseCamelLower("any_kind_of_string") -> anyKindOfString func CaseCamelLower(s string) string { if s == "" { return s @@ -120,17 +126,26 @@ func CaseCamelLower(s string) string { } // CaseSnake converts a string to snake_case. +// +// Example: +// CaseSnake("AnyKindOfString") -> any_kind_of_string func CaseSnake(s string) string { return CaseDelimited(s, '_') } // CaseSnakeScreaming converts a string to SNAKE_CASE_SCREAMING. +// +// Example: +// CaseSnakeScreaming("AnyKindOfString") -> ANY_KIND_OF_STRING func CaseSnakeScreaming(s string) string { return CaseDelimitedScreaming(s, '_', true) } // CaseSnakeFirstUpper converts a string like "RGBCodeMd5" to "rgb_code_md5". // TODO for efficiency should change regexp to traversing string in future. +// +// Example: +// CaseSnakeFirstUpper("RGBCodeMd5") -> rgb_code_md5 func CaseSnakeFirstUpper(word string, underscore ...string) string { replace := "_" if len(underscore) > 0 { @@ -157,22 +172,34 @@ func CaseSnakeFirstUpper(word string, underscore ...string) string { return TrimLeft(word, replace) } -// CaseKebab converts a string to kebab-case +// CaseKebab converts a string to kebab-case. +// +// Example: +// CaseKebab("AnyKindOfString") -> any-kind-of-string func CaseKebab(s string) string { return CaseDelimited(s, '-') } // CaseKebabScreaming converts a string to KEBAB-CASE-SCREAMING. +// +// Example: +// CaseKebab("AnyKindOfString") -> ANY-KIND-OF-STRING func CaseKebabScreaming(s string) string { return CaseDelimitedScreaming(s, '-', true) } // CaseDelimited converts a string to snake.case.delimited. +// +// Example: +// CaseDelimited("AnyKindOfString", '.') -> any.kind.of.string func CaseDelimited(s string, del byte) string { return CaseDelimitedScreaming(s, del, false) } // CaseDelimitedScreaming converts a string to DELIMITED.SCREAMING.CASE or delimited.screaming.case. +// +// Example: +// CaseDelimitedScreaming("AnyKindOfString", '.') -> ANY.KIND.OF.STRING func CaseDelimitedScreaming(s string, del uint8, screaming bool) string { s = addWordBoundariesToNumbers(s) s = strings.Trim(s, " ") diff --git a/text/gstr/gstr_convert.go b/text/gstr/gstr_convert.go index fc29f11cd84..4bf221b31cf 100644 --- a/text/gstr/gstr_convert.go +++ b/text/gstr/gstr_convert.go @@ -24,18 +24,26 @@ var ( ) // Chr return the ascii string of a number(0-255). +// +// Example: +// Chr(65) -> "A" func Chr(ascii int) string { return string([]byte{byte(ascii % 256)}) } // Ord converts the first byte of a string to a value between 0 and 255. +// +// Example: +// Chr("A") -> 65 func Ord(char string) int { return int(char[0]) } // OctStr converts string container octal string to its original string, // for example, to Chinese string. -// Eg: `\346\200\241` -> 怡 +// +// Example: +// OctStr("\346\200\241") -> 怡 func OctStr(str string) string { return octReg.ReplaceAllStringFunc( str, @@ -47,6 +55,9 @@ func OctStr(str string) string { } // Reverse returns a string which is the reverse of `str`. +// +// Example: +// Reverse("123456") -> "654321" func Reverse(str string) string { runes := []rune(str) for i, j := 0, len(runes)-1; i < j; i, j = i+1, j-1 { @@ -56,10 +67,14 @@ func Reverse(str string) string { } // NumberFormat formats a number with grouped thousands. -// `decimals`: Sets the number of decimal points. -// `decPoint`: Sets the separator for the decimal point. -// `thousandsSep`: Sets the thousands' separator. +// Parameter `decimals`: Sets the number of decimal points. +// Parameter `decPoint`: Sets the separator for the decimal point. +// Parameter `thousandsSep`: Sets the thousands' separator. // See http://php.net/manual/en/function.number-format.php. +// +// Example: +// NumberFormat(1234.56, 2, ".", "") -> 1234,56 +// NumberFormat(1234.56, 2, ",", " ") -> 1 234,56 func NumberFormat(number float64, decimals int, decPoint, thousandsSep string) string { neg := false if number < 0 { @@ -103,6 +118,11 @@ func NumberFormat(number float64, decimals int, decPoint, thousandsSep string) s // Shuffle randomly shuffles a string. // It considers parameter `str` as unicode string. +// +// Example: +// Shuffle("123456") -> "325164" +// Shuffle("123456") -> "231546" +// ... func Shuffle(str string) string { runes := []rune(str) s := make([]rune, len(runes)) diff --git a/text/gstr/gstr_create.go b/text/gstr/gstr_create.go index 8e5ff31294a..047463ae9b5 100644 --- a/text/gstr/gstr_create.go +++ b/text/gstr/gstr_create.go @@ -9,6 +9,9 @@ package gstr import "strings" // Repeat returns a new string consisting of multiplier copies of the string input. +// +// Example: +// Repeat("a", 3) -> "aaa" func Repeat(input string, multiplier int) string { return strings.Repeat(input, multiplier) } diff --git a/text/gstr/gstr_sub.go b/text/gstr/gstr_sub.go index a3f4a702422..847d21979cd 100644 --- a/text/gstr/gstr_sub.go +++ b/text/gstr/gstr_sub.go @@ -10,8 +10,12 @@ import "strings" // Str returns part of `haystack` string starting from and including // the first occurrence of `needle` to the end of `haystack`. -// See http://php.net/manual/en/function.strstr.php. -// Eg: Str("12345", "3") => "345" +// +// This function performs exactly as function SubStr, but to implement the same function +// as PHP: http://php.net/manual/en/function.strstr.php. +// +// Example: +// Str("av.mp4", ".") -> ".mp4" func Str(haystack string, needle string) string { if needle == "" { return "" @@ -25,7 +29,12 @@ func Str(haystack string, needle string) string { // StrEx returns part of `haystack` string starting from and excluding // the first occurrence of `needle` to the end of `haystack`. -// Eg: StrEx("12345", "3") => "45" +// +// This function performs exactly as function SubStrEx, but to implement the same function +// as PHP: http://php.net/manual/en/function.strstr.php. +// +// Example: +// StrEx("av.mp4", ".") -> "mp4" func StrEx(haystack string, needle string) string { if s := Str(haystack, needle); s != "" { return s[1:] @@ -35,7 +44,9 @@ func StrEx(haystack string, needle string) string { // StrTill returns part of `haystack` string ending to and including // the first occurrence of `needle` from the start of `haystack`. -// Eg: StrTill("12345", "3") => "123" +// +// Example: +// StrTill("av.mp4", ".") -> "av." func StrTill(haystack string, needle string) string { pos := strings.Index(haystack, needle) if pos == NotFoundIndex || pos == 0 { @@ -46,7 +57,9 @@ func StrTill(haystack string, needle string) string { // StrTillEx returns part of `haystack` string ending to and excluding // the first occurrence of `needle` from the start of `haystack`. -// Eg: StrTillEx("12345", "3") => "12" +// +// Example: +// StrTillEx("av.mp4", ".") -> "av" func StrTillEx(haystack string, needle string) string { pos := strings.Index(haystack, needle) if pos == NotFoundIndex || pos == 0 { @@ -57,7 +70,9 @@ func StrTillEx(haystack string, needle string) string { // SubStr returns a portion of string `str` specified by the `start` and `length` parameters. // The parameter `length` is optional, it uses the length of `str` in default. -// Eg: SubStr("12345", 1, 2) => "23" +// +// Example: +// SubStr("123456", 1, 2) -> "23" func SubStr(str string, start int, length ...int) (substr string) { strLength := len(str) if start < 0 { @@ -96,6 +111,9 @@ func SubStr(str string, start int, length ...int) (substr string) { // SubStrRune returns a portion of string `str` specified by the `start` and `length` parameters. // SubStrRune considers parameter `str` as unicode string. // The parameter `length` is optional, it uses the length of `str` in default. +// +// Example: +// SubStrRune("一起学习吧！", 2, 2) -> "学习" func SubStrRune(str string, start int, length ...int) (substr string) { // Converting to []rune to support unicode. var ( @@ -137,6 +155,10 @@ func SubStrRune(str string, start int, length ...int) (substr string) { // StrLimit returns a portion of string `str` specified by `length` parameters, if the length // of `str` is greater than `length`, then the `suffix` will be appended to the result string. +// +// Example: +// StrLimit("123456", 3) -> "123..." +// StrLimit("123456", 3, "~") -> "123~" func StrLimit(str string, length int, suffix ...string) string { if len(str) < length { return str @@ -151,6 +173,10 @@ func StrLimit(str string, length int, suffix ...string) string { // StrLimitRune returns a portion of string `str` specified by `length` parameters, if the length // of `str` is greater than `length`, then the `suffix` will be appended to the result string. // StrLimitRune considers parameter `str` as unicode string. +// +// Example: +// StrLimitRune("一起学习吧！", 2) -> "一起..." +// StrLimitRune("一起学习吧！", 2, "~") -> "一起~" func StrLimitRune(str string, length int, suffix ...string) string { runes := []rune(str) if len(runes) < length { @@ -165,6 +191,9 @@ func StrLimitRune(str string, length int, suffix ...string) string { // SubStrFrom returns a portion of string `str` starting from first occurrence of and including `need` // to the end of `str`. +// +// Example: +// SubStrFrom("av.mp4", ".") -> ".mp4" func SubStrFrom(str string, need string) (substr string) { pos := Pos(str, need) if pos < 0 { @@ -175,6 +204,9 @@ func SubStrFrom(str string, need string) (substr string) { // SubStrFromEx returns a portion of string `str` starting from first occurrence of and excluding `need` // to the end of `str`. +// +// Example: +// SubStrFromEx("av.mp4", ".") -> "mp4" func SubStrFromEx(str string, need string) (substr string) { pos := Pos(str, need) if pos < 0 { @@ -185,6 +217,9 @@ func SubStrFromEx(str string, need string) (substr string) { // SubStrFromR returns a portion of string `str` starting from last occurrence of and including `need` // to the end of `str`. +// +// Example: +// SubStrFromR("/dev/vda", "/") -> "/vda" func SubStrFromR(str string, need string) (substr string) { pos := PosR(str, need) if pos < 0 { @@ -195,6 +230,9 @@ func SubStrFromR(str string, need string) (substr string) { // SubStrFromREx returns a portion of string `str` starting from last occurrence of and excluding `need` // to the end of `str`. +// +// Example: +// SubStrFromREx("/dev/vda", "/") -> "vda" func SubStrFromREx(str string, need string) (substr string) { pos := PosR(str, need) if pos < 0 {