Documentation
¶
Overview ¶
errorsパッケージは、エラーを操作するための関数を実装しています。
[New]関数は、テキストメッセージのみが含まれるエラーを作成します。
エラーeの型にメソッドが1つある場合、eは別のエラーをラップします。
Unwrap() error Unwrap() []error
もしe.Unwrap()がnilでないエラーwまたはwを含むスライスを返した場合、 eはwをラップしていると言います。e.Unwrap()がnilを返した場合、 eは他のエラーをラップしていないことを示します。Unwrapメソッドが、 nilエラー値を含む[]errorを返すことは無効です。
ラップされたエラーを作成する簡単な方法は、 fmt.Errorf を呼び出し、 エラー引数に%w動詞を適用することです。
wrapsErr := fmt.Errorf("... %w ...", ..., err, ...)
エラーの連続的なアンラップにより、ツリーが作成されます。 Is および As 関数は、エラーのツリーを調べるために、 最初にエラー自体を調べ、次にその子のツリーを順番に調べます (前順、深さ優先のトラバース)。
Isは、第1引数のエラーツリーを調べ、第2引数に一致するエラーを探します。 一致するエラーが見つかった場合、trueを返します。 単純な等価性チェックよりも使用することをお勧めします。
if errors.Is(err, fs.ErrExist)
これは、次のようなエラーの比較よりも好ましいです。
if err == fs.ErrExist
なぜなら、前者はエラーが io/fs.ErrExist をラップしている場合に成功するからです。
Asは、第1引数のエラーツリーを調べ、第2引数に割り当て可能なエラーを探します。 第2引数はポインタである必要があります。成功した場合、Asは割り当てを実行し、trueを返します。 それ以外の場合、falseを返します。フォームは次のようになります。
var perr *fs.PathError if errors.As(err, &perr) { fmt.Println(perr.Path) }
これは、次のようなエラーの比較よりも好ましいです。
if perr, ok := err.(*fs.PathError); ok { fmt.Println(perr.Path) }
なぜなら、前者はエラーが[*io/fs.PathError]をラップしている場合に成功するからです。
Example ¶
if err := oops(); err != nil { fmt.Println(err) }
Output: 1989-03-15 22:30:00 +0000 UTC: the file system has gone away
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrUnsupported = New("unsupported operation")
ErrUnsupportedは、サポートされていないため、要求された操作を実行できないことを示します。 たとえば、ハードリンクをサポートしていないファイルシステムを使用して os.Link を呼び出す場合。
関数やメソッドは、このエラーを返すべきではありません。 代わりに、適切な文脈を含むエラーを返すべきです。
errors.Is(err, errors.ErrUnsupported)
ErrUnsupportedを直接ラップするか、Isメソッドを実装することによって、 サポートされていないことを示すエラーを返すことができます。
関数やメソッドは、このエラーをラップして返す場合があることを文書化する必要があります。
Functions ¶
func As ¶ added in v1.13.0
Asは、errのツリー内で最初にtargetに一致するエラーを検索し、 一致するエラーが見つかった場合、targetをそのエラー値に設定してtrueを返します。 それ以外の場合、falseを返します。
ツリーは、err自体に続いて、Unwrapを繰り返し呼び出して得られたエラーで構成されています。 errが複数のエラーをラップしている場合、Asは、errに続いてその子の深さ優先のトラバースを行います。
エラーがターゲットに一致する場合、エラーの具体的な値がtargetが指す値に代入可能であるか、 またはエラーがAs(interface{}) boolというメソッドを持ち、As(target)がtrueを返す場合です。 後者の場合、Asメソッドはtargetを設定する責任があります。
エラータイプは、異なるエラータイプであるかのように扱うことができるように、Asメソッドを提供する場合があります。
Asは、targetがエラーを実装する型または任意のインターフェース型の、 非nilポインタでない場合にパニックを引き起こします。
Example ¶
package main import ( "github.com/shogo82148/std/errors" "github.com/shogo82148/std/fmt" "github.com/shogo82148/std/io/fs" "github.com/shogo82148/std/os" ) func main() { if _, err := os.Open("non-existing"); err != nil { var pathError *fs.PathError if errors.As(err, &pathError) { fmt.Println("Failed at path:", pathError.Path) } else { fmt.Println(err) } } }
Output: Failed at path: non-existing
func Is ¶ added in v1.13.0
Isは、errのツリー内の任意のエラーがtargetに一致するかどうかを報告します。
ツリーは、err自体に続いて、Unwrapを繰り返し呼び出して得られたエラーで構成されています。 errが複数のエラーをラップしている場合、Isは、errに続いてその子の深さ優先のトラバースを行います。
ターゲットに一致するエラーは、そのターゲットに等しい場合、または Is(error) boolというメソッドを実装している場合、Is(target)がtrueを返す場合です。
エラータイプは、既存のエラーと同等に扱うためにIsメソッドを提供する場合があります。 たとえば、MyErrorが次のように定義されている場合、
func (m MyError) Is(target error) bool { return target == fs.ErrExist }
例えば、MyError{}とfs.ErrExistを引数に渡すと、Is(MyError{}, fs.ErrExist)はtrueを返します。 標準ライブラリの例については、 syscall.Errno.Is を参照してください。 Isメソッドは、errとターゲットを浅く比較し、Unwrapを呼び出さないようにする必要があります。
Example ¶
package main import ( "github.com/shogo82148/std/errors" "github.com/shogo82148/std/fmt" "github.com/shogo82148/std/io/fs" "github.com/shogo82148/std/os" ) func main() { if _, err := os.Open("non-existing"); err != nil { if errors.Is(err, fs.ErrNotExist) { fmt.Println("file does not exist") } else { fmt.Println(err) } } }
Output: file does not exist
func Join ¶ added in v1.20.0
Joinは、指定されたエラーをラップするエラーを返します。 nilエラー値は破棄されます。 errsのすべての値がnilの場合、Joinはnilを返します。 エラーは、errsの各要素のErrorメソッドを呼び出して得られた文字列を連結したもので、 各文字列の間に改行が挿入されたものとしてフォーマットされます。
Joinによって返されるnilでないエラーは、Unwrap() []errorメソッドを実装します。
Example ¶
package main import ( "github.com/shogo82148/std/errors" "github.com/shogo82148/std/fmt" ) func main() { err1 := errors.New("err1") err2 := errors.New("err2") err := errors.Join(err1, err2) fmt.Println(err) if errors.Is(err, err1) { fmt.Println("err is err1") } if errors.Is(err, err2) { fmt.Println("err is err2") } }
Output: err1 err2 err is err1 err is err2
func New ¶
Newは、指定されたテキストをフォーマットするエラーを返します。 テキストが同じであっても、Newの各呼び出しは異なるエラー値を返します。
Example ¶
package main import ( "github.com/shogo82148/std/errors" "github.com/shogo82148/std/fmt" ) func main() { err := errors.New("emit macho dwarf: elf header corrupted") if err != nil { fmt.Print(err) } }
Output: emit macho dwarf: elf header corrupted
Example (Errorf) ¶
The fmt package's Errorf function lets us use the package's formatting features to create descriptive error messages.
package main import ( "github.com/shogo82148/std/fmt" ) func main() { const name, id = "bimmler", 17 err := fmt.Errorf("user %q (id %d) not found", name, id) if err != nil { fmt.Print(err) } }
Output: user "bimmler" (id 17) not found
func Unwrap ¶ added in v1.13.0
Unwrapは、errの型にUnwrapメソッドが含まれている場合、 errのUnwrapメソッドを呼び出した結果を返します。 それ以外の場合、Unwrapはnilを返します。
Unwrapは、"Unwrap() error"形式のメソッドのみを呼び出します。 特に、Unwrapは Join によって返されたエラーをアンラップしません。
Example ¶
package main import ( "github.com/shogo82148/std/errors" "github.com/shogo82148/std/fmt" ) func main() { err1 := errors.New("error1") err2 := fmt.Errorf("error2: [%w]", err1) fmt.Println(err2) fmt.Println(errors.Unwrap(err2)) // Output // error2: [error1] // error1 }
Output:
Types ¶
This section is empty.