Debian Codegraph @

io/types.ha

raw
1 // SPDX-License-Identifier: MPL-2.0
2 // (c) Hare authors <https://harelang.org>
3
4 use errors;
5
6 // Returned by [[readall]] if the I/O handle returned [[EOF]] prior to
7 // completely reading an item. Stores the amount that was succesfully read.
8 export type underread = !size;
9
10 // Any error which may be returned from an I/O function.
11 export type error = !(...errors::error | underread | nomem);
12
13 // Indicates an end-of-file condition.
14 export type EOF = done;
15
16 // Converts an I/O [[error]] into a user-friendly string.
17 export fn strerror(err: error) str = {
18 match (err) {
19 case underread =>
20 return "Insufficient data to read entire item";
21 case nomem =>
22 return errors::strerror(nomem);
23 case let err: errors::error =>
24 return errors::strerror(err);
25 };
26 };
27
28 // Used to indicate if a stream should be used for reading, or writing, or both.
29 export type mode = enum u8 {
30 NONE = 0,
31 READ = 1 << 0,
32 WRITE = 1 << 1,
33 RDWR = READ | WRITE,
34 };
35
36 // From "whence" a seek operation should occur.
37 export type whence = enum {
38 SET = 0, // Relative to beginning (i.e. set absolute position).
39 CUR = 1, // Relative to current position.
40 END = 2, // Relative to end of handle.
41 };
42
43 // The interface for a stream which can be read from. Reads up to len(buf)
44 // bytes from the reader into the given buffer, returning the number of bytes
45 // read or an error.
46 export type reader = fn(s: *stream, buf: []u8) (size | EOF | error);
47
48 // The interface for a stream which can be written to. Writes up to len(buf)
49 // bytes to the writer from the given buffer, returning the number of bytes
50 // written or an error.
51 export type writer = fn(s: *stream, buf: const []u8) (size | error);
52
53 // The interface for a stream which can be closed. This function should close
54 // and free any underlying resources, and cannot be used again.
55 export type closer = fn(s: *stream) (void | error);
56
57 // The interface for a stream which provides an efficient path for copying data
58 // from a second I/O source.
59 //
60 // Returns the number of bytes copied, or an error if one occured. Do not close
61 // either "to" or "from".
62 //
63 // Most implementations of copier only support certain configurations of "to"
64 // and "from", such as requiring both to be the same kind of [[stream]]. In case
65 // of an unsupported configuration, return [[errors::unsupported]]. [[copy]]
66 // falls back to a read/write loop in this case.
67 export type copier = fn(to: *stream, from: handle) (size | error);
68
69 // The interface for a stream which can be seeked. Sets the offset for the next
70 // read or write to offset, interpreted according to whence:
71 // whence::SET means relative to the start of the file,
72 // whence::CUR means relative to the current offset, and
73 // whence::END means relative to the end.
74 //
75 // Returns the new offset relative to the start or an error.
76 export type seeker = fn(s: *stream, off: off, w: whence) (off | error);