1// Copyright 2009 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 ioutil implements some I/O utility functions.
6//
7// Deprecated: As of Go 1.16, the same functionality is now provided
8// by package [io] or package [os], and those implementations
9// should be preferred in new code.
10// See the specific function documentation for details.
11package ioutil
12
13import (
14	"io"
15	"io/fs"
16	"os"
17	"slices"
18	"strings"
19)
20
21// ReadAll reads from r until an error or EOF and returns the data it read.
22// A successful call returns err == nil, not err == EOF. Because ReadAll is
23// defined to read from src until EOF, it does not treat an EOF from Read
24// as an error to be reported.
25//
26// Deprecated: As of Go 1.16, this function simply calls [io.ReadAll].
27func ReadAll(r io.Reader) ([]byte, error) {
28	return io.ReadAll(r)
29}
30
31// ReadFile reads the file named by filename and returns the contents.
32// A successful call returns err == nil, not err == EOF. Because ReadFile
33// reads the whole file, it does not treat an EOF from Read as an error
34// to be reported.
35//
36// Deprecated: As of Go 1.16, this function simply calls [os.ReadFile].
37func ReadFile(filename string) ([]byte, error) {
38	return os.ReadFile(filename)
39}
40
41// WriteFile writes data to a file named by filename.
42// If the file does not exist, WriteFile creates it with permissions perm
43// (before umask); otherwise WriteFile truncates it before writing, without changing permissions.
44//
45// Deprecated: As of Go 1.16, this function simply calls [os.WriteFile].
46func WriteFile(filename string, data []byte, perm fs.FileMode) error {
47	return os.WriteFile(filename, data, perm)
48}
49
50// ReadDir reads the directory named by dirname and returns
51// a list of fs.FileInfo for the directory's contents,
52// sorted by filename. If an error occurs reading the directory,
53// ReadDir returns no directory entries along with the error.
54//
55// Deprecated: As of Go 1.16, [os.ReadDir] is a more efficient and correct choice:
56// it returns a list of [fs.DirEntry] instead of [fs.FileInfo],
57// and it returns partial results in the case of an error
58// midway through reading a directory.
59//
60// If you must continue obtaining a list of [fs.FileInfo], you still can:
61//
62//	entries, err := os.ReadDir(dirname)
63//	if err != nil { ... }
64//	infos := make([]fs.FileInfo, 0, len(entries))
65//	for _, entry := range entries {
66//		info, err := entry.Info()
67//		if err != nil { ... }
68//		infos = append(infos, info)
69//	}
70func ReadDir(dirname string) ([]fs.FileInfo, error) {
71	f, err := os.Open(dirname)
72	if err != nil {
73		return nil, err
74	}
75	list, err := f.Readdir(-1)
76	f.Close()
77	if err != nil {
78		return nil, err
79	}
80	slices.SortFunc(list, func(a, b os.FileInfo) int {
81		return strings.Compare(a.Name(), b.Name())
82	})
83	return list, nil
84}
85
86// NopCloser returns a ReadCloser with a no-op Close method wrapping
87// the provided Reader r.
88//
89// Deprecated: As of Go 1.16, this function simply calls [io.NopCloser].
90func NopCloser(r io.Reader) io.ReadCloser {
91	return io.NopCloser(r)
92}
93
94// Discard is an io.Writer on which all Write calls succeed
95// without doing anything.
96//
97// Deprecated: As of Go 1.16, this value is simply [io.Discard].
98var Discard io.Writer = io.Discard
99