errors

package
v1.21.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2023 License: MIT Imports: 0 Imported by: 0

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

View Source
var ErrUnsupported = New("unsupported operation")

ErrUnsupportedは、サポートされていないため、要求された操作を実行できないことを示します。 たとえば、ハードリンクをサポートしていないファイルシステムを使用して os.Link を呼び出す場合。

関数やメソッドは、このエラーを返すべきではありません。 代わりに、適切な文脈を含むエラーを返すべきです。

errors.Is(err, errors.ErrUnsupported)

ErrUnsupportedを直接ラップするか、Isメソッドを実装することによって、 サポートされていないことを示すエラーを返すことができます。

関数やメソッドは、このエラーをラップして返す場合があることを文書化する必要があります。

Functions

func As added in v1.13.0

func As(err error, target any) bool

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

func Is(err, target error) bool

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

func Join(errs ...error) error

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

func New(text string) error

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

func Unwrap(err error) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL