golang标准库笔记

May 14, 2023

builtin

package main

import (
    "fmt"
    "runtime"
)

func thread() {
    defer func() {
        if err := recover(); err != nil {
            fmt.Println(err)
        }
    }()
    // 在 recover 函数之后的 panic 才会被捕获
    panic("Oops! panic")
}

func main() {
    go thread() // recover函数仅对当前goroutine有效

    defer func() { // recover函数必须置于defer函数内，且在panic代码之前
        if err := recover(); err != nil {

            switch err.(type) {
            case runtime.Error:
                fmt.Println("[runtime.Error]", err)
            default:
                fmt.Println("[Error]:", err)
            }

        }
    }()

    var ptr *int
    fmt.Println(*ptr) // 访问空指针
}

fmt

fmt.Print(x)
// 相当于
fmt.Printf("%v", x)

package main

import "fmt"

func echo(format string, a ...any) {
    // fmt.Printf("%-20s %-6s", fmt.Sprint(a...), format)
    fmt.Printf(format, a...)
    fmt.Println()
}

type TypeStruct struct {
    Public  string
    private string
}

func main() {
    t := TypeStruct{"PUBLIC", "PRIVATE"}
    echo("%v", t)  // {PUBLIC PRIVATE}
    echo("%+v", t) // {Public:PUBLIC private:PRIVATE}
    echo("%#v", t) // main.TypeStruct{Public:"PUBLIC", private:"PRIVATE"}
    echo("%T", t)  // main.TypeStruct
    // 注：匿名结构体的输出有所不同，此处略
    // s := struct{ Public string; private string } {"PUBLIC", "PRIVATE"}

    n := 42
    echo("%c", n) // * （Unicode）
    echo("%q", n) // '*'
    echo("%U", n) // U+002A
    echo("%b", n) // 101010 （二进制）
    echo("%d", n) // 42 （十进制）
    echo("%o", n) // 52 （八进制）
    echo("%O", n) // 0o52 （八进制）
    echo("%x", n) // 2a （十六进制）
    echo("%X", n) // 2A

    f := 12.34
    echo("%b", f) // 6946802425218990p-49
    echo("%e", f) // 1.234000e+01
    echo("%E", f) // 1.234000E+01
    echo("%f", f) // 12.340000
    echo("%F", f) // 12.340000 （同上，没有区别）
    echo("%g", f) // 12.34
    echo("%G", f) // 12.34
    echo("%x", f) // 0x1.8ae147ae147aep+03
    echo("%X", f) // 0X1.8AE147AE147AEP+03

    s := "golang"
    echo("%s", s) // golang
    echo("%q", s) // "golang"
    echo("%x", s) // 676f6c616e67
    echo("%X", s) // 676F6C616E67
    // 注：若 s := []byte("golang") 结果相同

    a := []int{2, 3, 3} // 注意这是切片不是数组
    echo("%p", a)       // 0xc0000aa0f0 （地址不是固定的）

    echo("%t", true)  // true
    echo("%t", false) // false

    echo("%v", false)                  // 相当于 %t
    echo("%v", int(-42))               // 相当于 %d
    echo("%v", uint(42))               // 相当于 %d
    echo("%v", float32(12.34))         // 相当于 %g
    echo("%v", s)                      // 相当于 %s
    echo("%v", make(chan interface{})) // 相当于 %p
    echo("%v", &s)                     // 相当于 %p
}

%[标志][最小宽度][.精度][长度]类型
精度以 Unicode 码点计数（而不是像 C 一样以字节计数）

errors

package main

import (
    "errors"
    "fmt"
    "io/fs"
    "os"
)

func main() {
    // func New(text string) error
    // 给定字符串生成（独一无二的）错误
    // 参见：fmt.Errorf()
    err := errors.New("emit macho dwarf: elf header corrupted")
    if err != nil {
        fmt.Print(err)
    }

    // func As(err error, target any) bool
    // 将错误 err 断言为错误 target，返回是否断言成功
    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)
        }
    }

    // func Is(err, target error) bool
    // 判断错误 err 是否为错误 target
    if _, err := os.Open("non-existing"); err != nil {
        if errors.Is(err, fs.ErrNotExist) {
            fmt.Println("file does not exist")
        } else {
            fmt.Println(err)
        }
    }

    // func Join(errs ...error) error
    // 提供包装给定的多个错误生成新错误
    // 在给定的错误中，是 nil 的错误会被丢弃
    err1 := errors.New("err1")
    err2 := errors.New("err2")
    err3 := errors.Join(err1, err2)
    fmt.Println(err3) // 该错误的字符串是其包装的错误字符串之间加上换行
    if errors.Is(err3, err1) {
        fmt.Println("err3 is err1")
    }
    if errors.Is(err3, err2) {
        fmt.Println("err3 is err2")
    }

    // func Unwrap(err error) error
    // 若给定错误 err 对象实现了方法 Unwrap()，则调用该方法返回错误
    // 否则，返回 nil
    err4 := errors.New("error4")
    err5 := fmt.Errorf("error5: %w", err4)   // 参见：https://pkg.go.dev/fmt#Errorf
    fmt.Println(errors.Unwrap(err5) == err4) // true
}

io

type Reader interface {
    // 读取最多 len(p) 个字节到 p，返回读取的字节数 0 <= n <= len(p) 及任何遇到的错误（如果有）
    // 即使 n < len(p) 也可能在调用期间 p 的所有空间作为暂存空间
    // 并且，此时 Read() 一般直接返回读取的数据（p 未填满），而不会继续等待更多的数据（以填满 p）
    Read(p []byte) (n int, err error)
}

type Writer interface {
    // 写入 len(p) 个字节到底层的数据流，返回写入的字节数 0 <= n <= len(p) 及任何遇到的错误（如果有）
    // 若返回的 n < len(p) 则必须返回非 nil 的错误
    // Write() 不允许修改切片 p 中的数据（如果要实现此接口）
    Write(p []byte) (n int, err error)
}

type Closer interface {
    // 包装基本的关闭方法。重复调用此方法的行为是未定义的
    Close() error
}

const (
    SeekStart   = 0 // 相对于文件起始位置
    SeekCurrent = 1 // 相对于当前位置
    SeekEnd     = 2 // 相对于文件结尾 (for example, offset = -2 specifies the penultimate byte of the file)
)

type Seeker interface {
    // 设定下一次读写的偏移量为 offset
    // whence 可取常量 SeekStart SeekCurrent SeekEnd（其含义参见上面的解释）
    // 返回新的偏移量（相对于文件起始位置）及任何可能的错误
    Seek(offset int64, whence int) (int64, error)
}

注意：io/ioutil 包已废弃。其功能拆分到了 io 和 os 包里

os

os 包主要提供了文件。进程相关的跨平台 API

参见 File 类方法

func Open(name string) (*File, error)
// 文件描述符是 O_RDONLY。若发生错误，返回的错误类型是 *PathError

func Create(name string) (*File, error)
// 若文件已存在，会被清空。否则将以 0666 模式创建（before umask）。
// 文件描述符是 O_RDWR。若发生错误，返回的错误类型是 *PathError

type PathError struct {
    Op   string
    Path string
    Err  error
}

参见 Process 类方法及 ProcessState 类方法

func FindProcess(pid int) (*Process, error)
func StartProcess(name string, argv []string, attr *ProcAttr) (*Process, error)
// 一般使用 os/exec 包提供的高层接口，而不是此函数

常量

// 文件描述符，类型是 uintptr。例如：func NewFile(fd uintptr, name string) *File
const (
    // 必须指定下面三个之中的一个
    O_RDONLY int = syscall.O_RDONLY // open the file read-only.
    O_WRONLY int = syscall.O_WRONLY // open the file write-only.
    O_RDWR   int = syscall.O_RDWR   // open the file read-write.
    // The remaining values may be or'ed in to control behavior.
    O_APPEND int = syscall.O_APPEND // append data to the file when writing.
    O_CREATE int = syscall.O_CREAT  // create a new file if none exists.
    O_EXCL   int = syscall.O_EXCL   // used with O_CREATE, file must not exist.
    O_SYNC   int = syscall.O_SYNC   // open for synchronous I/O.
    O_TRUNC  int = syscall.O_TRUNC  // truncate regular writable file when opened.
)
// 指定如何解释偏移量。例如：func (f *File) Seek(offset int64, whence int) (ret int64, err error)
// Deprecated: Use io.SeekStart, io.SeekCurrent, and io.SeekEnd.
const (
    SEEK_SET int = 0 // 相当于文件起始
    SEEK_CUR int = 1 // 相对于当前偏移量
    SEEK_END int = 2 // 相对于文件结尾
)
const (
    PathSeparator     = '/' // OS-specific path separator
    PathListSeparator = ':' // OS-specific path list separator
)

io/fs

type File interface {
    Stat() (FileInfo, error)
    Read([]byte) (int, error)
    Close() error
}
type FileInfo interface {
    Name() string       // 文件名，basename
    Size() int64        // length in bytes for regular files; system-dependent for others
    Mode() FileMode     // file mode bits
    ModTime() time.Time // 修改时间
    IsDir() bool        // 即 Mode().IsDir()
    Sys() any           // underlying data source (can return nil)
}
type DirEntry interface {
    // 返回文件或目录名。仅名称，非完整路径
    Name() string
    IsDir() bool
    Type() FileMode
    // 返回子项（文件或子目录）的信息。返回的 FileInfo 既可能在读取父目录时发生，也可能在调用Info方法时发生
    // 若文件在父目录被读取后被删除或重命名，Info方法可能返回一个满足 errors.Is(err, ErrNotExist) 的错误
    // 若文件是符号链接，info方法返回符号链接自身的信息
    Info() (FileInfo, error)
}

// 具体参见 FileMode 类方法
// https://pkg.go.dev/io/fs#FileMode
type FileMode uint32
const (
    // The single letters are the abbreviations
    // used by the String method's formatting.
    ModeDir        FileMode = 1 << (32 - 1 - iota) // d: is a directory
    ModeAppend                                     // a: append-only
    ModeExclusive                                  // l: exclusive use
    ModeTemporary                                  // T: temporary file; Plan 9 only
    ModeSymlink                                    // L: symbolic link
    ModeDevice                                     // D: device file
    ModeNamedPipe                                  // p: named pipe (FIFO)
    ModeSocket                                     // S: Unix domain socket
    ModeSetuid                                     // u: setuid
    ModeSetgid                                     // g: setgid
    ModeCharDevice                                 // c: Unix character device, when ModeDevice is set
    ModeSticky                                     // t: sticky
    ModeIrregular                                  // ?: non-regular file; nothing else is known about this file

    // Mask for the type bits. For regular files, none will be set.
    ModeType = ModeDir | ModeSymlink | ModeNamedPipe | ModeSocket | ModeDevice | ModeCharDevice | ModeIrregular

    ModePerm FileMode = 0777 // Unix permission bits
)

path

注意：path 包用于处理正斜线分隔路径（及 URL）
跨平台时使用 path/filepath 包，该包还提供了正反斜线转换的函数
此外还提供了用于递归遍历目录的 Walk() 和 WalkDir() 函数

strings

Builder 类可用于构造字符串

var sb strings.Builder
sb.WriteString("hello,")
sb.Write([]byte("world"))
fmt.Print(sb.String())

bytes

bytes 包类似于 strings 包，提供了 byte 切片（[]byte）相关的实用函数

strconv

strconv 包实现了基本数据类型与字符串之间的转换

encoding/json

参见：https://go.dev/blog/json

func Marshal(v any) ([]byte, error)

func Unmarshal(data []byte, v any) error

time

此处略：Duration
参见：https://go.dev/blog/concurrency-timeouts

Location

var Local *Location = &localLoc
var UTC *Location = &utcLoc
func FixedZone(name string, offset int) *Location

utc_negative_8 := time.FixedZone("UTC-8", -8*60*60)

Time

func Now() Time
func Date(year int, month Month, day, hour, min, sec, nsec int, loc *Location) Time
func Unix(sec int64, nsec int64) Time
func UnixMicro(usec int64) Time
func UnixMilli(msec int64) Time
func Parse(layout, value string) (Time, error)
func (t Time) Format(layout string) string

layout 可取（或者说格式为）

const (
    Layout      = "01/02 03:04:05PM '06 -0700" // The reference time, in numerical order.
    ANSIC       = "Mon Jan _2 15:04:05 2006"
    UnixDate    = "Mon Jan _2 15:04:05 MST 2006"
    RubyDate    = "Mon Jan 02 15:04:05 -0700 2006"
    RFC822      = "02 Jan 06 15:04 MST"
    RFC822Z     = "02 Jan 06 15:04 -0700" // RFC822 with numeric zone
    RFC850      = "Monday, 02-Jan-06 15:04:05 MST"
    RFC1123     = "Mon, 02 Jan 2006 15:04:05 MST"
    RFC1123Z    = "Mon, 02 Jan 2006 15:04:05 -0700" // RFC1123 with numeric zone
    RFC3339     = "2006-01-02T15:04:05Z07:00"
    RFC3339Nano = "2006-01-02T15:04:05.999999999Z07:00"
    Kitchen     = "3:04PM"
    // Handy time stamps.
    Stamp      = "Jan _2 15:04:05"
    StampMilli = "Jan _2 15:04:05.000"
    StampMicro = "Jan _2 15:04:05.000000"
    StampNano  = "Jan _2 15:04:05.000000000"
    DateTime   = "2006-01-02 15:04:05"
    DateOnly   = "2006-01-02"
    TimeOnly   = "15:04:05"
)

Timer

type Timer struct {
    C <-chan Time
    // contains filtered or unexported fields
}

Timer 类型表示一个单一的事件。当 Timer（计时器）到期时，当前时间会发送到信道 C（除非这个 Timer 是通过 AfterFunc 函数创建的）
Timer 类必须通过 NewTimer 或 AfterFunc 函数创建。

Ticker

type Ticker struct {
    C <-chan Time // 这是 tick 将要发送到的信道
    // contains filtered or unexported fields
}

Ticker 类型持有一个信道，会定期向该信道发送 ticks。
注：通过 NewTicker 函数创建

regexp

func main() {
    matched, err := regexp.MatchString(`^[A-Z]+?[A-Za-z]*$`, "Admin")
    fmt.Println(matched, err) // true <nil>
}

对于更复杂的正则表达式，应构造 Regexp 对象

func Compile(expr string) (*Regexp, error)
func MustCompile(str string) *Regexp
func (re *Regexp) FindStringSubmatch(s string) []string

embed

//go:embed 指令可被用于导出和非导出变量，取决于使用此指令的包是否要向其它包公开此变量。此指令只能用于包作用域的变量，不能用于局部变量。

import _ "embed"

//go:embed hello.txt
var s string
print(s)

//go:embed hello.txt
var b []byte
print(string(b))

//go:embed hello.txt
var f embed.FS
data, _ := f.ReadFile("hello.txt")
print(string(data))

// The difference is that ‘image/*’ embeds ‘image/.tempfile’ while ‘image’ does not.
// Neither embeds ‘image/dir/.tempfile’.
import "embed"
//go:embed image/* template/*
//go:embed html/index.html
var content embed.FS
//go:embed image template html/index.html
var content embed.FS
// If a pattern begins with the prefix ‘all:’, then the rule for walking directories is changed to include those files beginning with ‘.’ or ‘_’.
// For example, ‘all:image’ embeds both ‘image/.tempfile’ and ‘image/dir/.tempfile’.

func (f FS) Open(name string) (fs.File, error)
func (f FS) ReadDir(name string) ([]fs.DirEntry, error)
func (f FS) ReadFile(name string) ([]byte, error)

context

参见：Go Concurrency Patterns: Context

sync

sync 包提供了基本的同步原语

reflect

参见：https://go.dev/blog/laws-of-reflection

←Back to home