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 // See https://go.dev/blog/go1.13-errors for a deeper discussion of the 30 // philosophy of wrapping and when to wrap. 31 // 32 // [Is] examines the tree of its first argument looking for an error that 33 // matches the second. It reports whether it finds a match. It should be 34 // used in preference to simple equality checks: 35 // 36 // if errors.Is(err, fs.ErrExist) 37 // 38 // is preferable to 39 // 40 // if err == fs.ErrExist 41 // 42 // because the former will succeed if err wraps [io/fs.ErrExist]. 43 // 44 // [As] examines the tree of its first argument looking for an error that can be 45 // assigned to its second argument, which must be a pointer. If it succeeds, it 46 // performs the assignment and returns true. Otherwise, it returns false. The form 47 // 48 // var perr *fs.PathError 49 // if errors.As(err, &perr) { 50 // fmt.Println(perr.Path) 51 // } 52 // 53 // is preferable to 54 // 55 // if perr, ok := err.(*fs.PathError); ok { 56 // fmt.Println(perr.Path) 57 // } 58 // 59 // because the former will succeed if err wraps an [*io/fs.PathError]. 60 package errors 61 62 // New returns an error that formats as the given text. 63 // Each call to New returns a distinct error value even if the text is identical. 64 func New(text string) error { 65 return &errorString{text} 66 } 67 68 // errorString is a trivial implementation of error. 69 type errorString struct { 70 s string 71 } 72 73 func (e *errorString) Error() string { 74 return e.s 75 } 76 77 // ErrUnsupported indicates that a requested operation cannot be performed, 78 // because it is unsupported. For example, a call to [os.Link] when using a 79 // file system that does not support hard links. 80 // 81 // Functions and methods should not return this error but should instead 82 // return an error including appropriate context that satisfies 83 // 84 // errors.Is(err, errors.ErrUnsupported) 85 // 86 // either by directly wrapping ErrUnsupported or by implementing an [Is] method. 87 // 88 // Functions and methods should document the cases in which an error 89 // wrapping this will be returned. 90 var ErrUnsupported = New("unsupported operation") 91