Source file src/errors/errors.go
1 // Copyright 2011 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package errors implements functions to manipulate errors. 6 // 7 // The New function creates errors whose only content is a text message. 8 // 9 // An error e wraps another error if e's type has one of the methods 10 // 11 // Unwrap() error 12 // Unwrap() []error 13 // 14 // If e.Unwrap() returns a non-nil error w or a slice containing w, 15 // then we say that e wraps w. A nil error returned from e.Unwrap() 16 // indicates that e does not wrap any error. It is invalid for an 17 // Unwrap method to return an []error containing a nil error value. 18 // 19 // An easy way to create wrapped errors is to call fmt.Errorf and apply 20 // the %w verb to the error argument: 21 // 22 // wrapsErr := fmt.Errorf("... %w ...", ..., err, ...) 23 // 24 // Successive unwrapping of an error creates a tree. The Is and As 25 // functions inspect an error's tree by examining first the error 26 // itself followed by the tree of each of its children in turn 27 // (pre-order, depth-first traversal). 28 // 29 // Is examines the tree of its first argument looking for an error that 30 // matches the second. It reports whether it finds a match. It should be 31 // used in preference to simple equality checks: 32 // 33 // if errors.Is(err, fs.ErrExist) 34 // 35 // is preferable to 36 // 37 // if err == fs.ErrExist 38 // 39 // because the former will succeed if err wraps fs.ErrExist. 40 // 41 // As examines the tree of its first argument looking for an error that can be 42 // assigned to its second argument, which must be a pointer. If it succeeds, it 43 // performs the assignment and returns true. Otherwise, it returns false. The form 44 // 45 // var perr *fs.PathError 46 // if errors.As(err, &perr) { 47 // fmt.Println(perr.Path) 48 // } 49 // 50 // is preferable to 51 // 52 // if perr, ok := err.(*fs.PathError); ok { 53 // fmt.Println(perr.Path) 54 // } 55 // 56 // because the former will succeed if err wraps an *fs.PathError. 57 package errors 58 59 // New returns an error that formats as the given text. 60 // Each call to New returns a distinct error value even if the text is identical. 61 func New(text string) error { 62 return &errorString{text} 63 } 64 65 // errorString is a trivial implementation of error. 66 type errorString struct { 67 s string 68 } 69 70 func (e *errorString) Error() string { 71 return e.s 72 } 73