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 [io/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 [*io/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 74 // ErrUnsupported indicates that a requested operation cannot be performed, 75 // because it is unsupported. For example, a call to [os.Link] when using a 76 // file system that does not support hard links. 77 // 78 // Functions and methods should not return this error but should instead 79 // return an error including appropriate context that satisfies 80 // 81 // errors.Is(err, errors.ErrUnsupported) 82 // 83 // either by directly wrapping ErrUnsupported or by implementing an [Is] method. 84 // 85 // Functions and methods should document the cases in which an error 86 // wrapping this will be returned. 87 var ErrUnsupported = New("unsupported operation") 88