io
MoonBit io: provide simplified I/O abstractions similar to Go.
io
moonbit
moon add gmlewis/io@0.23.14
Download zipAuthor
Version
0.23.14
License
Apache-2.0
Repository
Last updated
9 days ago
Downloads
31K
Dependencies
- gmlewis/base640.16.11
README#gmlewis/io
This is a simplified io package based on Go's implementation:
https://cs.opensource.google/go/go/+/refs/tags/go1.23.2:src/io/io.go
which has the copyright notice:
// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.#Status
The code has been updated to support compiler:
$ moon version --all
moon 0.1.20260713 (75c7e1f 2026-07-13) ~/.moon/bin/moon
moonc v0.10.4+2cc641edf (2026-07-15) ~/.moon/bin/moonc
moonrun 0.1.20260713 (75c7e1f 2026-07-13) ~/.moon/bin/moonrun
#ByteReader
ByteReader is the interface that wraps the read_byte method.
read_byte reads and returns the next byte from the input or
any error encountered. If read_byte returns an error, no input
byte was consumed, and the returned byte value is undefined.
read_byte provides an efficient interface for byte-at-time
processing. A [Reader] that does not implement ByteReader
can be wrapped using bufio.NewReader to add this method.
#ByteScanner
ByteScanner is the interface that adds the unread_byte method to the
basic read_byte method.
unread_byte causes the next call to read_byte to return the last byte read.
If the last operation was not a successful call to read_byte, unread_byte may
return an error, unread the last byte read (or the byte prior to the
last-unread byte), or (in implementations that support the [Seeker] interface)
seek to one byte before the current offset.
#ByteWriter
ByteWriter is the interface that wraps the write_byte method.
#Closer
Closer is the interface that wraps the basic Close method.
The behavior of Close after the first call is undefined.
Specific implementations may document their own behavior.
#ReadCloser
ReadCloser is the interface that groups the basic Read and Close methods.
#ReadSeekCloser
ReadSeekCloser is the interface that groups the basic Read, Seek and Close
methods.
#ReadSeeker
ReadSeeker is the interface that groups the basic Read and Seek methods.
#ReadWriteCloser
ReadWriteCloser is the interface that groups the basic Read, Write and Close methods.
#ReadWriteSeeker
ReadWriteSeeker is the interface that groups the basic Read, Write and Seek methods.
#ReadWriter
ReadWriter is the interface that groups the basic Read and Write methods.
#Reader
Reader is the interface that wraps the basic Read method.
Read reads up to len(p) bytes into p. It returns the number of bytes
read (0 <= n <= len(p)) and any error encountered. Even if Read
returns n < len(p), it may use all of p as scratch space during the call.
If some data is available but not len(p) bytes, Read conventionally
returns what is available instead of waiting for more.
When Read encounters an error or end-of-file condition after
successfully reading n > 0 bytes, it returns the number of
bytes read. It may return the (non-None) error from the same call
or return the error (and n == 0) from a subsequent call.
An instance of this general case is that a Reader returning
a non-zero number of bytes at the end of the input stream may
return either err == eof or err == None. The next Read should
return 0, eof.
Callers should always process the n > 0 bytes returned before
considering the error err. Doing so correctly handles I/O errors
that happen after reading some bytes and also both of the
allowed eof behaviors.
If len(p) == 0, Read should always return n == 0. It may return a
non-None error if some error condition is known, such as eof.
Implementations of Read are discouraged from returning a
zero byte count with a None error, except when len(p) == 0.
Callers should treat a return of 0 and None as indicating that
nothing happened; in particular it does not indicate eof.
Implementations must not retain p.
#ReaderAt
ReaderAt is the interface that wraps the basic read_at method.
read_at reads len(p) bytes into p starting at offset off in the
underlying input source. It returns the number of bytes
read (0 <= n <= len(p)) and any error encountered.
When read_at returns n < len(p), it returns a non-None error
explaining why more bytes were not returned. In this respect,
read_at is stricter than Read.
Even if read_at returns n < len(p), it may use all of p as scratch
space during the call. If some data is available but not len(p) bytes,
read_at blocks until either all the data is available or an error occurs.
In this respect read_at is different from Read.
If the n = len(p) bytes returned by read_at are at the end of the
input source, read_at may return either err == eof or err == None.
If read_at is reading from an input source with a seek offset,
read_at should not affect nor be affected by the underlying
seek offset.
Clients of read_at can execute parallel read_at calls on the
same input source.
Implementations must not retain p.
#ReaderFrom
ReaderFrom is the interface that wraps the read_from method.
read_from reads data from r until eof or error.
The return value n is the number of bytes read.
Any error except eof encountered during the read is also returned.
The [copy] function uses [ReaderFrom] if available.
#Seeker
Seeker is the interface that wraps the basic Seek method.
Seek sets the offset for the next Read or Write to offset,
interpreted according to whence:
[SeekStart] means relative to the start of the file,
[SeekCurrent] means relative to the current offset, and
[SeekEnd] means relative to the end
(for example, offset = -2 specifies the penultimate byte of the file).
Seek returns the new offset relative to the start of the
file or an error, if any.
Seeking to an offset before the start of the file is an error.
Seeking to any positive offset may be allowed, but if the new offset exceeds
the size of the underlying object the behavior of subsequent I/O operations
is implementation-dependent.
#WriteCloser
WriteCloser is the interface that groups the basic Write and Close methods.
#WriteSeeker
WriteSeeker is the interface that groups the basic Write and Seek methods.
#Writer
Writer is the interface that wraps the basic Write method.
Write writes len(p) bytes from p to the underlying data stream.
It returns the number of bytes written from p (0 <= n <= len(p))
and any error encountered that caused the write to stop early.
Write must return a non-None error if it returns n < len(p).
Write must not modify the slice data, even temporarily.
Implementations must not retain p.
#WriterAt
WriterAt is the interface that wraps the basic write_at method.
write_at writes len(p) bytes from p to the underlying data stream
at offset off. It returns the number of bytes written from p (0 <= n <= len(p))
and any error encountered that caused the write to stop early.
write_at must return a non-None error if it returns n < len(p).
If write_at is writing to a destination with a seek offset,
write_at should not affect nor be affected by the underlying
seek offset.
Clients of write_at can execute parallel write_at calls on the same
destination if the ranges do not overlap.
Implementations must not retain p.
#WriterTo
WriterTo is the interface that wraps the write_to method.
write_to writes data to w until there's no more data to write or
when an error occurs. The return value n is the number of bytes
written. Any error encountered during the write is also returned.
The copy function uses WriterTo if available.
#IOError
#Buffer
type Bufferimpl ByteReader for Buffer
#Buffer::from_string
Buffer::from_string converts the MoonBit UTF-16 String to UTF-8
and creates a Buffer from the bytes.
#Buffer::new
Buffer::new creates a new empty Buffer with an optional size hint.
The size hint is used to preallocate memory for the buffer, which can
improve performance when the size of the data to be written is known in advance.
#Discard
type Discard#LimitedReader
type LimitedReaderA LimitedReader reads from R but limits the amount of
data returned to just N bytes. Each call to Read
updates N to reflect the new amount remaining.
Read returns eof when N <= 0 or when the underlying R returns eof.
impl Reader for LimitedReader#LimitedReader::new
LimitedReader::new returns a Reader that reads from r
but stops with eof after n bytes.
The underlying implementation is a LimitedReader.
#NopCloser
type NopCloser#OffsetWriter
type OffsetWriterAn OffsetWriter maps writes at offset base to offset base+off in the underlying writer.
#OffsetWriter::new
OffsetWriter::new returns an [OffsetWriter] that writes to w
starting at offset off.
#OffsetWriter::seek
#OffsetWriter::write
#OffsetWriter::write_at
#SectionReader
type SectionReaderSectionReader implements Read, Seek, and read_at on a section
of an underlying [ReaderAt].
#SectionReader::new
SectionReader::new returns a [SectionReader] that reads from r
starting at offset off and stops with eof after n bytes.
#SectionReader::outer
Outer returns the underlying [ReaderAt] and offsets for the section.
The returned values are the same that were passed to [SectionReader::new]
when the [SectionReader] was created.
#SectionReader::read
#SectionReader::read_at
#SectionReader::seek
#Slice
A Slice is a slice of an Array.
A separate Slice type was needed because of this issue:
https://github.com/moonbitlang/core/issues/1063
This struct is based on MoonBit's "ArrayView" implementation here:
https://github.com/moonbitlang/core/blob/main/builtin/arrayview.mbt
which has the following copyright:
Copyright 2024 International Digital Economy Academy
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
#Slice::append
append appends s to the end of the slice, reallocating the underlying
array if necessary, then returns the new slice.
#Slice::cap
cap returns the total capacity of the slice regardless of the current length.
#Slice::fold
Fold out values from a Slice according to certain rules.
#Slice::foldi
Fold out values from a Slice according to certain rules with index.
#Slice::length
length returns the length of the slice.
#Slice::op_as_view
#Slice::push
push appends e to the end of the slice, reallocating the underlying
array if necessary, then returns the new slice.
#Slice::rev_fold
Fold out values from a Slice according to certain rules in reversed turn.
#Slice::rev_foldi
Fold out values from a Slice according to certain rules in reversed turn with index.
#TeeReader
type TeeReader#TeeReader::new
TeeReader::new returns a [Reader] that writes to w what it reads from r.
All reads from r performed through it are matched with
corresponding writes to w. There is no internal buffering -
the write must complete before the read completes.
Any error encountered while writing is reported as a read error.
#copy
copy copies from src to dst until either eof is reached
on src or an error occurs. It returns the number of bytes
copied and the first error encountered while copying, if any.
A successful copy returns err == None, not err == eof.
Because copy is defined to read from src until eof, it does
not treat an eof from Read as an error to be reported.
If src implements [WriterTo],
the copy is implemented by calling src.write_to(dst).
Otherwise, if dst implements [ReaderFrom],
the copy is implemented by calling dst.read_from(src).
#copy_buffer
copy_buffer is identical to copy except that it stages through the
provided buffer (if one is required) rather than allocating a
temporary one. If buf is None, one is allocated; otherwise if it has
zero length, copy_buffer panics.
If either src implements [WriterTo] or dst implements [ReaderFrom],
buf will not be used to perform the copy.
#copy_json
copy_json copies bytes from a source reader until a valid JSON value is completed.
It returns the Json value, the number of bytes copied, and any error that occurred during the process.
#copy_n
copy_n copies n bytes (or until an error) from src to dst.
It returns the number of bytes copied and the earliest
error encountered while copying.
On return, written == n if and only if err == None.
If dst implements [ReaderFrom], the copy is implemented using it.
#copy_size
copy_size copies a specified number of bytes from a source reader to a
destination writer. It returns the number of bytes copied and any error
that occurred during the process.
#copy_until
copy_until copies bytes from a source reader to a destination writer
until a specified byte is encountered. It returns the number of bytes
copied and any error that occurred during the process.
#discard
discard is a [Writer] on which all Write calls succeed
without doing anything.
#eof
eof is the error returned by Read when no more input is available.
(Read must return eof itself, not an error wrapping eof,
because callers will test for eof using ==.)
Functions should return eof only to signal a graceful end of input.
If the eof occurs unexpectedly in a structured data stream,
the appropriate error is either [err_unexpected_eof] or some other error
giving more detail.
#err_invalid_write
err_invalid_write means that a write returned an impossible count.
#err_no_progress
err_no_progress is returned by some clients of a [Reader] when
many calls to Read have failed to return any data or error,
usually the sign of a broken [Reader] implementation.
#err_short_buffer
err_short_buffer means that a read required a longer buffer than was provided.
#err_short_write
err_short_write means that a write accepted fewer bytes than requested
but failed to return an explicit error.
#err_unexpected_eof
err_unexpected_eof means that eof was encountered in the
middle of reading a fixed-size block or data structure.
#read_all
read_all reads from r until an error or eof and returns the data it read.
A successful call returns err == None, not err == eof. Because read_all is
defined to read from src until eof, it does not treat an eof from Read
as an error to be reported.
#read_full
read_full reads exactly len(buf) bytes from r into buf.
It returns the number of bytes copied and an error if fewer bytes were read.
The error is eof only if no bytes were read.
If an eof happens after reading some but not all the bytes,
read_full returns [err_unexpected_eof].
On return, n == len(buf) if and only if err == None.
If r returns an error having read at least len(buf) bytes, the error is dropped.
Source Files
MoonBit io: provide simplified I/O abstractions similar to Go.
iomoonbit
0.23.14
Apache-2.0
Updated 9 days ago
31K downloadsDependencies
- gmlewis/base640.16.11