[errutil] New methods and more usage examples

CHANGELOG.md

@@ -2,7 +2,10 @@
 
 ### 12.84.0
 
+* `[errutil]` Added method `Errors.First()`
+* `[errutil]` Added method `Errors.Get()`
 * `[fmtutil/table]` Added short form of align flags
+* `[errutil]` Added more usage examples
 
 ### 12.83.2
 

errutil/errutil.go

@@ -89,15 +89,34 @@ func (e *Errors) Add(errs ...any) *Errors {
 	return e
 }
 
+// First returns the first error
+func (e *Errors) First() error {
+	if e == nil || len(e.errors) == 0 {
+		return nil
+	}
+
+	return e.errors[0]
+}
+
 // Last returns the last error
 func (e *Errors) Last() error {
-	if e == nil || e.errors == nil {
+	if e == nil || len(e.errors) == 0 {
 		return nil
 	}
 
 	return e.errors[len(e.errors)-1]
 }
 
+// Get returns error by it index
+func (e *Errors) Get(index int) error {
+	if e == nil || len(e.errors) == 0 ||
+		index < 0 || index >= len(e.errors) {
+		return nil
+	}
+
+	return e.errors[index]
+}
+
 // All returns all errors in slice
 func (e *Errors) All() []error {
 	if e == nil || e.errors == nil {

errutil/errutil_test.go

@@ -43,7 +43,12 @@ func (s *ErrSuite) TestPositive(c *C) {
 	c.Assert(errs.Num(), Equals, 5)
 	c.Assert(errs.All(), HasLen, 5)
 	c.Assert(errs.HasErrors(), Equals, true)
+	c.Assert(errs.First(), DeepEquals, errors.New("1"))
 	c.Assert(errs.Last(), DeepEquals, errors.New("5"))
+	c.Assert(errs.Get(0), DeepEquals, errors.New("1"))
+	c.Assert(errs.Get(4), DeepEquals, errors.New("5"))
+	c.Assert(errs.Get(100), IsNil)
+	c.Assert(errs.Get(-100), IsNil)
 	c.Assert(errs.All(), DeepEquals,
 		[]error{
 			errors.New("1"),
@@ -134,6 +139,7 @@ func (s *ErrSuite) TestNil(c *C) {
 	c.Assert(errs.Cap(), Equals, 0)
 	c.Assert(errs.All(), HasLen, 0)
 	c.Assert(errs.HasErrors(), Equals, false)
+	c.Assert(errs.First(), IsNil)
 	c.Assert(errs.Last(), IsNil)
 	c.Assert(errs.Error(), Equals, "")
 }

errutil/example_test.go

@@ -57,3 +57,144 @@ func ExampleErrors() {
 	// Capacity: 10
 	// Has errors: true
 }
+
+func ExampleErrors_Add() {
+	var myErrs Errors
+
+	myErrs.Add(fmt.Errorf("Error 1"))
+	myErrs.Add(fmt.Errorf("Error 2"))
+	myErrs.Add(fmt.Errorf("Error 3"))
+
+	fmt.Printf("First: %v\n", myErrs.First())
+	fmt.Printf("Last: %v\n", myErrs.Last())
+
+	// Output:
+	// First: Error 1
+	// Last: Error 3
+}
+
+func ExampleErrors_First() {
+	var myErrs Errors
+
+	myErrs.Add(fmt.Errorf("Error 1"))
+	myErrs.Add(fmt.Errorf("Error 2"))
+	myErrs.Add(fmt.Errorf("Error 3"))
+
+	fmt.Printf("First: %v\n", myErrs.First())
+
+	// Output:
+	// First: Error 1
+}
+
+func ExampleErrors_Last() {
+	var myErrs Errors
+
+	myErrs.Add(fmt.Errorf("Error 1"))
+	myErrs.Add(fmt.Errorf("Error 2"))
+	myErrs.Add(fmt.Errorf("Error 3"))
+
+	fmt.Printf("Last: %v\n", myErrs.Last())
+
+	// Output:
+	// Last: Error 3
+}
+
+func ExampleErrors_Get() {
+	var myErrs Errors
+
+	myErrs.Add(fmt.Errorf("Error 1"))
+	myErrs.Add(fmt.Errorf("Error 2"))
+	myErrs.Add(fmt.Errorf("Error 3"))
+
+	fmt.Printf("Index 1: %v\n", myErrs.Get(1))
+	fmt.Printf("Index 99: %v\n", myErrs.Get(99))
+
+	// Output:
+	// Index 1: Error 2
+	// Index 99: <nil>
+}
+
+func ExampleErrors_All() {
+	var myErrs Errors
+
+	myErrs.Add(fmt.Errorf("Error 1"))
+	myErrs.Add(fmt.Errorf("Error 2"))
+	myErrs.Add(fmt.Errorf("Error 3"))
+
+	fmt.Printf("Errors: %v\n", myErrs.All())
+
+	// Output:
+	// Errors: [Error 1 Error 2 Error 3]
+}
+
+func ExampleErrors_HasErrors() {
+	var myErrs Errors
+
+	fmt.Printf("Has errors: %t\n", myErrs.HasErrors())
+
+	myErrs.Add(fmt.Errorf("Error"))
+
+	fmt.Printf("Has errors: %t\n", myErrs.HasErrors())
+
+	// Output:
+	// Has errors: false
+	// Has errors: true
+}
+
+func ExampleErrors_Num() {
+	var myErrs Errors
+
+	myErrs.Add(fmt.Errorf("Error 1"))
+	myErrs.Add(fmt.Errorf("Error 2"))
+	myErrs.Add(fmt.Errorf("Error 3"))
+
+	fmt.Printf("Errors num: %d\n", myErrs.Num())
+
+	// Output:
+	// Errors num: 3
+}
+
+func ExampleErrors_Cap() {
+	myErrs := NewErrors(2)
+
+	myErrs.Add(fmt.Errorf("Error 1"))
+	myErrs.Add(fmt.Errorf("Error 2"))
+	myErrs.Add(fmt.Errorf("Error 3"))
+
+	fmt.Printf("Errors cap: %d\n", myErrs.Cap())
+	fmt.Printf("First: %v\n", myErrs.First())
+	fmt.Printf("Last: %v\n", myErrs.Last())
+
+	// Output:
+	// Errors cap: 2
+	// First: Error 2
+	// Last: Error 3
+}
+
+func ExampleErrors_Error() {
+	var myErrs Errors
+
+	myErrs.Add(fmt.Errorf("Error 1"))
+	myErrs.Add(fmt.Errorf("Error 2"))
+	myErrs.Add(fmt.Errorf("Error 3"))
+
+	fmt.Printf("Errors:\n%s\n", myErrs.Error())
+
+	// Output:
+	// Errors:
+	//   Error 1
+	//   Error 2
+	//   Error 3
+}
+
+func ExampleErrors_Reset() {
+	var myErrs Errors
+
+	myErrs.Add(fmt.Errorf("Error"))
+	myErrs.Reset()
+
+	fmt.Printf("Has errors: %t\n", myErrs.HasErrors())
+
+	// Output:
+	// Has errors: false
+}