add function Walk for package garray; improve comment for package garray

.example/other/test.go

@@ -1,20 +1,5 @@
 package main
 
-import (
-	"github.com/gogf/gf/os/glog"
-	"runtime/debug"
-)
-
-func doPrintLog(content string) {
-	debug.PrintStack()
-	glog.Skip(1).Line().Println("line number with skip:", content)
-	glog.Line().Println("line number without skip:", content)
-}
-
-func PrintLog(content string) {
-	doPrintLog(content)
-}
-
 func main() {
-	PrintLog("just test")
+
 }

container/garray/garray_normal_any.go

@@ -681,7 +681,7 @@ func (a *Array) Iterator(f func(k int, v interface{}) bool) {
 	a.IteratorAsc(f)
 }
 
-// IteratorAsc iterates the array in ascending order with given callback function <f>.
+// IteratorAsc iterates the array readonly in ascending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (a *Array) IteratorAsc(f func(k int, v interface{}) bool) {
 	a.mu.RLock()
@@ -693,7 +693,7 @@ func (a *Array) IteratorAsc(f func(k int, v interface{}) bool) {
 	}
 }
 
-// IteratorDesc iterates the array in descending order with given callback function <f>.
+// IteratorDesc iterates the array readonly in descending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (a *Array) IteratorDesc(f func(k int, v interface{}) bool) {
 	a.mu.RLock()
@@ -789,6 +789,16 @@ func (a *Array) FilterEmpty() *Array {
 	return a
 }
 
+// Walk applies a user supplied function <f> to every item of array.
+func (a *Array) Walk(f func(value interface{}) interface{}) *Array {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	for i, v := range a.array {
+		a.array[i] = f(v)
+	}
+	return a
+}
+
 // IsEmpty checks whether the array is empty.
 func (a *Array) IsEmpty() bool {
 	return a.Len() == 0

container/garray/garray_normal_int.go

@@ -683,7 +683,7 @@ func (a *IntArray) Iterator(f func(k int, v int) bool) {
 	a.IteratorAsc(f)
 }
 
-// IteratorAsc iterates the array in ascending order with given callback function <f>.
+// IteratorAsc iterates the array readonly in ascending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (a *IntArray) IteratorAsc(f func(k int, v int) bool) {
 	a.mu.RLock()
@@ -695,7 +695,7 @@ func (a *IntArray) IteratorAsc(f func(k int, v int) bool) {
 	}
 }
 
-// IteratorDesc iterates the array in descending order with given callback function <f>.
+// IteratorDesc iterates the array readonly in descending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (a *IntArray) IteratorDesc(f func(k int, v int) bool) {
 	a.mu.RLock()
@@ -759,6 +759,16 @@ func (a *IntArray) FilterEmpty() *IntArray {
 	return a
 }
 
+// Walk applies a user supplied function <f> to every item of array.
+func (a *IntArray) Walk(f func(value int) int) *IntArray {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	for i, v := range a.array {
+		a.array[i] = f(v)
+	}
+	return a
+}
+
 // IsEmpty checks whether the array is empty.
 func (a *IntArray) IsEmpty() bool {
 	return a.Len() == 0

container/garray/garray_normal_str.go

@@ -674,7 +674,7 @@ func (a *StrArray) Iterator(f func(k int, v string) bool) {
 	a.IteratorAsc(f)
 }
 
-// IteratorAsc iterates the array in ascending order with given callback function <f>.
+// IteratorAsc iterates the array readonly in ascending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (a *StrArray) IteratorAsc(f func(k int, v string) bool) {
 	a.mu.RLock()
@@ -686,7 +686,7 @@ func (a *StrArray) IteratorAsc(f func(k int, v string) bool) {
 	}
 }
 
-// IteratorDesc iterates the array in descending order with given callback function <f>.
+// IteratorDesc iterates the array readonly in descending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (a *StrArray) IteratorDesc(f func(k int, v string) bool) {
 	a.mu.RLock()
@@ -761,6 +761,16 @@ func (a *StrArray) FilterEmpty() *StrArray {
 	return a
 }
 
+// Walk applies a user supplied function <f> to every item of array.
+func (a *StrArray) Walk(f func(value string) string) *StrArray {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	for i, v := range a.array {
+		a.array[i] = f(v)
+	}
+	return a
+}
+
 // IsEmpty checks whether the array is empty.
 func (a *StrArray) IsEmpty() bool {
 	return a.Len() == 0

container/garray/garray_sorted_any.go

@@ -388,7 +388,7 @@ func (a *SortedArray) Len() int {
 // Note that, if it's in concurrent-safe usage, it returns a copy of underlying data,
 // or else a pointer to the underlying data.
 func (a *SortedArray) Slice() []interface{} {
-	array := ([]interface{})(nil)
+	var array []interface{}
 	if a.mu.IsSafe() {
 		a.mu.RLock()
 		defer a.mu.RUnlock()
@@ -507,6 +507,12 @@ func (a *SortedArray) Clear() *SortedArray {
 func (a *SortedArray) LockFunc(f func(array []interface{})) *SortedArray {
 	a.mu.Lock()
 	defer a.mu.Unlock()
+
+	// Keep the array always sorted.
+	defer sort.Slice(a.array, func(i, j int) bool {
+		return a.getComparator()(a.array[i], a.array[j]) < 0
+	})
+
 	f(a.array)
 	return a
 }
@@ -607,7 +613,7 @@ func (a *SortedArray) Iterator(f func(k int, v interface{}) bool) {
 	a.IteratorAsc(f)
 }
 
-// IteratorAsc iterates the array in ascending order with given callback function <f>.
+// IteratorAsc iterates the array readonly in ascending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (a *SortedArray) IteratorAsc(f func(k int, v interface{}) bool) {
 	a.mu.RLock()
@@ -619,7 +625,7 @@ func (a *SortedArray) IteratorAsc(f func(k int, v interface{}) bool) {
 	}
 }
 
-// IteratorDesc iterates the array in descending order with given callback function <f>.
+// IteratorDesc iterates the array readonly in descending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (a *SortedArray) IteratorDesc(f func(k int, v interface{}) bool) {
 	a.mu.RLock()
@@ -745,6 +751,20 @@ func (a *SortedArray) FilterEmpty() *SortedArray {
 	return a
 }
 
+// Walk applies a user supplied function <f> to every item of array.
+func (a *SortedArray) Walk(f func(value interface{}) interface{}) *SortedArray {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	// Keep the array always sorted.
+	defer sort.Slice(a.array, func(i, j int) bool {
+		return a.getComparator()(a.array[i], a.array[j]) < 0
+	})
+	for i, v := range a.array {
+		a.array[i] = f(v)
+	}
+	return a
+}
+
 // IsEmpty checks whether the array is empty.
 func (a *SortedArray) IsEmpty() bool {
 	return a.Len() == 0

container/garray/garray_sorted_int.go

@@ -604,7 +604,7 @@ func (a *SortedIntArray) Iterator(f func(k int, v int) bool) {
 	a.IteratorAsc(f)
 }
 
-// IteratorAsc iterates the array in ascending order with given callback function <f>.
+// IteratorAsc iterates the array readonly in ascending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (a *SortedIntArray) IteratorAsc(f func(k int, v int) bool) {
 	a.mu.RLock()
@@ -616,7 +616,7 @@ func (a *SortedIntArray) IteratorAsc(f func(k int, v int) bool) {
 	}
 }
 
-// IteratorDesc iterates the array in descending order with given callback function <f>.
+// IteratorDesc iterates the array readonly in descending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (a *SortedIntArray) IteratorDesc(f func(k int, v int) bool) {
 	a.mu.RLock()
@@ -697,6 +697,20 @@ func (a *SortedIntArray) FilterEmpty() *SortedIntArray {
 	return a
 }
 
+// Walk applies a user supplied function <f> to every item of array.
+func (a *SortedIntArray) Walk(f func(value int) int) *SortedIntArray {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	// Keep the array always sorted.
+	defer quickSortInt(a.array, a.getComparator())
+
+	for i, v := range a.array {
+		a.array[i] = f(v)
+	}
+	return a
+}
+
 // IsEmpty checks whether the array is empty.
 func (a *SortedIntArray) IsEmpty() bool {
 	return a.Len() == 0

container/garray/garray_sorted_str.go

@@ -589,7 +589,7 @@ func (a *SortedStrArray) Iterator(f func(k int, v string) bool) {
 	a.IteratorAsc(f)
 }
 
-// IteratorAsc iterates the array in ascending order with given callback function <f>.
+// IteratorAsc iterates the array readonly in ascending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (a *SortedStrArray) IteratorAsc(f func(k int, v string) bool) {
 	a.mu.RLock()
@@ -601,7 +601,7 @@ func (a *SortedStrArray) IteratorAsc(f func(k int, v string) bool) {
 	}
 }
 
-// IteratorDesc iterates the array in descending order with given callback function <f>.
+// IteratorDesc iterates the array readonly in descending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (a *SortedStrArray) IteratorDesc(f func(k int, v string) bool) {
 	a.mu.RLock()
@@ -693,6 +693,20 @@ func (a *SortedStrArray) FilterEmpty() *SortedStrArray {
 	return a
 }
 
+// Walk applies a user supplied function <f> to every item of array.
+func (a *SortedStrArray) Walk(f func(value string) string) *SortedStrArray {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	// Keep the array always sorted.
+	defer quickSortStr(a.array, a.getComparator())
+
+	for i, v := range a.array {
+		a.array[i] = f(v)
+	}
+	return a
+}
+
 // IsEmpty checks whether the array is empty.
 func (a *SortedStrArray) IsEmpty() bool {
 	return a.Len() == 0

container/garray/garray_z_unit_normal_any_array_test.go

@@ -650,3 +650,12 @@ func TestArray_FilterEmpty(t *testing.T) {
 		t.Assert(array.FilterEmpty(), g.Slice{1, 2, 3, 4})
 	})
 }
+
+func TestArray_Walk(t *testing.T) {
+	gtest.C(t, func(t *gtest.T) {
+		array := garray.NewArrayFrom(g.Slice{"1", "2"})
+		t.Assert(array.Walk(func(value interface{}) interface{} {
+			return "key-" + gconv.String(value)
+		}), g.Slice{"key-1", "key-2"})
+	})
+}

container/garray/garray_z_unit_normal_int_array_test.go

@@ -683,3 +683,12 @@ func TestIntArray_FilterEmpty(t *testing.T) {
 		t.Assert(array.FilterEmpty(), g.SliceInt{1, 2, 3, 4})
 	})
 }
+
+func TestIntArray_Walk(t *testing.T) {
+	gtest.C(t, func(t *gtest.T) {
+		array := garray.NewIntArrayFrom(g.SliceInt{1, 2})
+		t.Assert(array.Walk(func(value int) int {
+			return 10 + value
+		}), g.Slice{11, 12})
+	})
+}

container/garray/garray_z_unit_normal_str_array_test.go

@@ -671,3 +671,12 @@ func TestStrArray_FilterEmpty(t *testing.T) {
 		t.Assert(array.FilterEmpty(), g.SliceStr{"1", "2"})
 	})
 }
+
+func TestStrArray_Walk(t *testing.T) {
+	gtest.C(t, func(t *gtest.T) {
+		array := garray.NewStrArrayFrom(g.SliceStr{"1", "2"})
+		t.Assert(array.Walk(func(value string) string {
+			return "key-" + value
+		}), g.Slice{"key-1", "key-2"})
+	})
+}

container/garray/garray_z_unit_sorted_any_array_test.go

@@ -779,3 +779,12 @@ func TestSortedArray_FilterEmpty(t *testing.T) {
 		t.Assert(array.FilterEmpty(), g.Slice{1, 2, 3, 4})
 	})
 }
+
+func TestSortedArray_Walk(t *testing.T) {
+	gtest.C(t, func(t *gtest.T) {
+		array := garray.NewSortedArrayFrom(g.Slice{"1", "2"}, gutil.ComparatorString)
+		t.Assert(array.Walk(func(value interface{}) interface{} {
+			return "key-" + gconv.String(value)
+		}), g.Slice{"key-1", "key-2"})
+	})
+}

container/garray/garray_z_unit_sorted_int_array_test.go

@@ -642,3 +642,12 @@ func TestSortedIntArray_FilterEmpty(t *testing.T) {
 		t.Assert(array.FilterEmpty(), g.SliceInt{1, 2, 3, 4})
 	})
 }
+
+func TestSortedIntArray_Walk(t *testing.T) {
+	gtest.C(t, func(t *gtest.T) {
+		array := garray.NewSortedIntArrayFrom(g.SliceInt{1, 2})
+		t.Assert(array.Walk(func(value int) int {
+			return 10 + value
+		}), g.Slice{11, 12})
+	})
+}

container/garray/garray_z_unit_sorted_str_array_test.go

@@ -652,3 +652,12 @@ func TestSortedStrArray_FilterEmpty(t *testing.T) {
 		t.Assert(array.FilterEmpty(), g.SliceStr{"1", "2"})
 	})
 }
+
+func TestSortedStrArray_Walk(t *testing.T) {
+	gtest.C(t, func(t *gtest.T) {
+		array := garray.NewSortedStrArrayFrom(g.SliceStr{"1", "2"})
+		t.Assert(array.Walk(func(value string) string {
+			return "key-" + value
+		}), g.Slice{"key-1", "key-2"})
+	})
+}

container/glist/glist.go

@@ -360,7 +360,7 @@ func (l *List) Iterator(f func(e *Element) bool) {
 	l.IteratorAsc(f)
 }
 
-// IteratorAsc iterates the list in ascending order with given callback function <f>.
+// IteratorAsc iterates the list readonly in ascending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (l *List) IteratorAsc(f func(e *Element) bool) {
 	l.mu.RLock()
@@ -375,7 +375,7 @@ func (l *List) IteratorAsc(f func(e *Element) bool) {
 	}
 }
 
-// IteratorDesc iterates the list in descending order with given callback function <f>.
+// IteratorDesc iterates the list readonly in descending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (l *List) IteratorDesc(f func(e *Element) bool) {
 	l.mu.RLock()

container/gmap/gmap_hash_any_any_map.go

@@ -42,7 +42,7 @@ func NewAnyAnyMapFrom(data map[interface{}]interface{}, safe ...bool) *AnyAnyMap
 	}
 }
 
-// Iterator iterates the hash map with custom callback function <f>.
+// Iterator iterates the hash map readonly with custom callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (m *AnyAnyMap) Iterator(f func(k interface{}, v interface{}) bool) {
 	m.mu.RLock()

container/gmap/gmap_hash_int_any_map.go

@@ -42,7 +42,7 @@ func NewIntAnyMapFrom(data map[int]interface{}, safe ...bool) *IntAnyMap {
 	}
 }
 
-// Iterator iterates the hash map with custom callback function <f>.
+// Iterator iterates the hash map readonly with custom callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (m *IntAnyMap) Iterator(f func(k int, v interface{}) bool) {
 	m.mu.RLock()

container/gmap/gmap_hash_int_int_map.go

@@ -40,7 +40,7 @@ func NewIntIntMapFrom(data map[int]int, safe ...bool) *IntIntMap {
 	}
 }
 
-// Iterator iterates the hash map with custom callback function <f>.
+// Iterator iterates the hash map readonly with custom callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (m *IntIntMap) Iterator(f func(k int, v int) bool) {
 	m.mu.RLock()

container/gmap/gmap_hash_int_str_map.go

@@ -40,7 +40,7 @@ func NewIntStrMapFrom(data map[int]string, safe ...bool) *IntStrMap {
 	}
 }
 
-// Iterator iterates the hash map with custom callback function <f>.
+// Iterator iterates the hash map readonly with custom callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (m *IntStrMap) Iterator(f func(k int, v string) bool) {
 	m.mu.RLock()

container/gmap/gmap_hash_str_any_map.go

@@ -42,7 +42,7 @@ func NewStrAnyMapFrom(data map[string]interface{}, safe ...bool) *StrAnyMap {
 	}
 }
 
-// Iterator iterates the hash map with custom callback function <f>.
+// Iterator iterates the hash map readonly with custom callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (m *StrAnyMap) Iterator(f func(k string, v interface{}) bool) {
 	m.mu.RLock()

container/gmap/gmap_hash_str_int_map.go

@@ -40,7 +40,7 @@ func NewStrIntMapFrom(data map[string]int, safe ...bool) *StrIntMap {
 	}
 }
 
-// Iterator iterates the hash map with custom callback function <f>.
+// Iterator iterates the hash map readonly with custom callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (m *StrIntMap) Iterator(f func(k string, v int) bool) {
 	m.mu.RLock()

container/gmap/gmap_hash_str_str_map.go

@@ -41,7 +41,7 @@ func NewStrStrMapFrom(data map[string]string, safe ...bool) *StrStrMap {
 	}
 }
 
-// Iterator iterates the hash map with custom callback function <f>.
+// Iterator iterates the hash map readonly with custom callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (m *StrStrMap) Iterator(f func(k string, v string) bool) {
 	m.mu.RLock()

container/gmap/gmap_list_map.go

@@ -55,7 +55,7 @@ func (m *ListMap) Iterator(f func(key, value interface{}) bool) {
 	m.IteratorAsc(f)
 }
 
-// IteratorAsc iterates the map in ascending order with given callback function <f>.
+// IteratorAsc iterates the map readonly in ascending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (m *ListMap) IteratorAsc(f func(key interface{}, value interface{}) bool) {
 	m.mu.RLock()
@@ -69,7 +69,7 @@ func (m *ListMap) IteratorAsc(f func(key interface{}, value interface{}) bool) {
 	}
 }
 
-// IteratorDesc iterates the map in descending order with given callback function <f>.
+// IteratorDesc iterates the map readonly in descending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (m *ListMap) IteratorDesc(f func(key interface{}, value interface{}) bool) {
 	m.mu.RLock()

container/gset/gset_any_set.go

@@ -48,7 +48,7 @@ func NewFrom(items interface{}, safe ...bool) *Set {
 	}
 }
 
-// Iterator iterates the set with given callback function <f>,
+// Iterator iterates the set readonly with given callback function <f>,
 // if <f> returns true then continue iterating; or false to stop.
 func (set *Set) Iterator(f func(v interface{}) bool) {
 	set.mu.RLock()

container/gset/gset_int_set.go

@@ -41,7 +41,7 @@ func NewIntSetFrom(items []int, safe ...bool) *IntSet {
 	}
 }
 
-// Iterator iterates the set with given callback function <f>,
+// Iterator iterates the set readonly with given callback function <f>,
 // if <f> returns true then continue iterating; or false to stop.
 func (set *IntSet) Iterator(f func(v int) bool) {
 	set.mu.RLock()

container/gset/gset_str_set.go

@@ -42,7 +42,7 @@ func NewStrSetFrom(items []string, safe ...bool) *StrSet {
 	}
 }
 
-// Iterator iterates the set with given callback function <f>,
+// Iterator iterates the set readonly with given callback function <f>,
 // if <f> returns true then continue iterating; or false to stop.
 func (set *StrSet) Iterator(f func(v string) bool) {
 	set.mu.RLock()

container/gtree/gtree_avltree.go

@@ -465,7 +465,7 @@ func (tree *AVLTree) IteratorFrom(key interface{}, match bool, f func(key, value
 	tree.IteratorAscFrom(key, match, f)
 }
 
-// IteratorAsc iterates the tree in ascending order with given callback function <f>.
+// IteratorAsc iterates the tree readonly in ascending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (tree *AVLTree) IteratorAsc(f func(key, value interface{}) bool) {
 	tree.mu.RLock()
@@ -473,7 +473,7 @@ func (tree *AVLTree) IteratorAsc(f func(key, value interface{}) bool) {
 	tree.doIteratorAsc(tree.bottom(0), f)
 }
 
-// IteratorAscFrom iterates the tree in ascending order with given callback function <f>.
+// IteratorAscFrom iterates the tree readonly in ascending order with given callback function <f>.
 // The parameter <key> specifies the start entry for iterating. The <match> specifies whether
 // starting iterating if the <key> is fully matched, or else using index searching iterating.
 // If <f> returns true, then it continues iterating; or false to stop.
@@ -499,7 +499,7 @@ func (tree *AVLTree) doIteratorAsc(node *AVLTreeNode, f func(key, value interfac
 	}
 }
 
-// IteratorDesc iterates the tree in descending order with given callback function <f>.
+// IteratorDesc iterates the tree readonly in descending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (tree *AVLTree) IteratorDesc(f func(key, value interface{}) bool) {
 	tree.mu.RLock()
@@ -507,7 +507,7 @@ func (tree *AVLTree) IteratorDesc(f func(key, value interface{}) bool) {
 	tree.doIteratorDesc(tree.bottom(1), f)
 }
 
-// IteratorDescFrom iterates the tree in descending order with given callback function <f>.
+// IteratorDescFrom iterates the tree readonly in descending order with given callback function <f>.
 // The parameter <key> specifies the start entry for iterating. The <match> specifies whether
 // starting iterating if the <key> is fully matched, or else using index searching iterating.
 // If <f> returns true, then it continues iterating; or false to stop.

container/gtree/gtree_btree.go

@@ -406,7 +406,7 @@ func (tree *BTree) IteratorFrom(key interface{}, match bool, f func(key, value i
 	tree.IteratorAscFrom(key, match, f)
 }
 
-// IteratorAsc iterates the tree in ascending order with given callback function <f>.
+// IteratorAsc iterates the tree readonly in ascending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (tree *BTree) IteratorAsc(f func(key, value interface{}) bool) {
 	tree.mu.RLock()
@@ -418,7 +418,7 @@ func (tree *BTree) IteratorAsc(f func(key, value interface{}) bool) {
 	tree.doIteratorAsc(node, node.Entries[0], 0, f)
 }
 
-// IteratorAscFrom iterates the tree in ascending order with given callback function <f>.
+// IteratorAscFrom iterates the tree readonly in ascending order with given callback function <f>.
 // The parameter <key> specifies the start entry for iterating. The <match> specifies whether
 // starting iterating if the <key> is fully matched, or else using index searching iterating.
 // If <f> returns true, then it continues iterating; or false to stop.
@@ -479,7 +479,7 @@ loop:
 	}
 }
 
-// IteratorDesc iterates the tree in descending order with given callback function <f>.
+// IteratorDesc iterates the tree readonly in descending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (tree *BTree) IteratorDesc(f func(key, value interface{}) bool) {
 	tree.mu.RLock()
@@ -493,7 +493,7 @@ func (tree *BTree) IteratorDesc(f func(key, value interface{}) bool) {
 	tree.doIteratorDesc(node, entry, index, f)
 }
 
-// IteratorDescFrom iterates the tree in descending order with given callback function <f>.
+// IteratorDescFrom iterates the tree readonly in descending order with given callback function <f>.
 // The parameter <key> specifies the start entry for iterating. The <match> specifies whether
 // starting iterating if the <key> is fully matched, or else using index searching iterating.
 // If <f> returns true, then it continues iterating; or false to stop.
@@ -510,7 +510,7 @@ func (tree *BTree) IteratorDescFrom(key interface{}, match bool, f func(key, val
 	}
 }
 
-// IteratorDesc iterates the tree in descending order with given callback function <f>.
+// IteratorDesc iterates the tree readonly in descending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (tree *BTree) doIteratorDesc(node *BTreeNode, entry *BTreeEntry, index int, f func(key, value interface{}) bool) {
 	first := true

container/gtree/gtree_redblacktree.go

@@ -499,7 +499,7 @@ func (tree *RedBlackTree) IteratorFrom(key interface{}, match bool, f func(key,
 	tree.IteratorAscFrom(key, match, f)
 }
 
-// IteratorAsc iterates the tree in ascending order with given callback function <f>.
+// IteratorAsc iterates the tree readonly in ascending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (tree *RedBlackTree) IteratorAsc(f func(key, value interface{}) bool) {
 	tree.mu.RLock()
@@ -507,7 +507,7 @@ func (tree *RedBlackTree) IteratorAsc(f func(key, value interface{}) bool) {
 	tree.doIteratorAsc(tree.leftNode(), f)
 }
 
-// IteratorAscFrom iterates the tree in ascending order with given callback function <f>.
+// IteratorAscFrom iterates the tree readonly in ascending order with given callback function <f>.
 // The parameter <key> specifies the start entry for iterating. The <match> specifies whether
 // starting iterating if the <key> is fully matched, or else using index searching iterating.
 // If <f> returns true, then it continues iterating; or false to stop.
@@ -550,7 +550,7 @@ loop:
 	}
 }
 
-// IteratorDesc iterates the tree in descending order with given callback function <f>.
+// IteratorDesc iterates the tree readonly in descending order with given callback function <f>.
 // If <f> returns true, then it continues iterating; or false to stop.
 func (tree *RedBlackTree) IteratorDesc(f func(key, value interface{}) bool) {
 	tree.mu.RLock()
@@ -558,7 +558,7 @@ func (tree *RedBlackTree) IteratorDesc(f func(key, value interface{}) bool) {
 	tree.doIteratorDesc(tree.rightNode(), f)
 }
 
-// IteratorDescFrom iterates the tree in descending order with given callback function <f>.
+// IteratorDescFrom iterates the tree readonly in descending order with given callback function <f>.
 // The parameter <key> specifies the start entry for iterating. The <match> specifies whether
 // starting iterating if the <key> is fully matched, or else using index searching iterating.
 // If <f> returns true, then it continues iterating; or false to stop.

encoding/gurl/url.go

@@ -12,12 +12,17 @@ import (
 	"strings"
 )
 
-// url encode string, is + not %20
+// Encode escapes the string so it can be safely placed
+// inside a URL query.
 func Encode(str string) string {
 	return url.QueryEscape(str)
 }
 
-// url decode string
+// Decode does the inverse transformation of Encode,
+// converting each 3-byte encoded substring of the form "%AB" into the
+// hex-decoded byte 0xAB.
+// It returns an error if any % is not followed by two hexadecimal
+// digits.
 func Decode(str string) (string, error) {
 	return url.QueryUnescape(str)
 }

net/ghttp/ghttp_request_param_file.go

@@ -30,10 +30,7 @@ type UploadFiles []*UploadFile
 //
 // The parameter <dirPath> should be a directory path or it returns error.
 //
-// The parameter <randomlyRename> specifies whether randomly renames the file name, which
-// make sense if the <path> is a directory.
-//
-// Note that it will overwrite the target file if there's already a same name file exist.
+// Note that it will OVERWRITE the target file if there's already a same name file exist.
 func (f *UploadFile) Save(dirPath string, randomlyRename ...bool) (filename string, err error) {
 	if f == nil {
 		return "", errors.New("file is empty, maybe you retrieve it from invalid field name or form enctype")
@@ -93,6 +90,8 @@ func (fs UploadFiles) Save(dirPath string, randomlyRename ...bool) (filenames []
 // This function is used for retrieving single uploading file object, which is
 // uploaded using multipart form content type.
 //
+// It returns nil if retrieving failed or no form file with given name posted.
+//
 // Note that the <name> is the file field name of the multipart form from client.
 func (r *Request) GetUploadFile(name string) *UploadFile {
 	uploadFiles := r.GetUploadFiles(name)
@@ -106,6 +105,8 @@ func (r *Request) GetUploadFile(name string) *UploadFile {
 // This function is used for retrieving multiple uploading file objects, which are
 // uploaded using multipart form content type.
 //
+// It returns nil if retrieving failed or no form file with given name posted.
+//
 // Note that the <name> is the file field name of the multipart form from client.
 func (r *Request) GetUploadFiles(name string) UploadFiles {
 	multipartFiles := r.GetMultipartFiles(name)