Module async_std::io

source ·
Expand description

Traits, helpers, and type definitions for core I/O functionality.

The async_std::io module contains a number of common things you’ll need when doing input and output. The most core part of this module is the Read and Write traits, which provide the most general interface for reading and writing input and output.

This module is an async version of std::io.

Read and Write

Because they are traits, Read and Write are implemented by a number of other types, and you can implement them for your types too. As such, you’ll see a few different types of I/O throughout the documentation in this module: Files, TcpStreams, and sometimes even Vec<T>s. For example, Read adds a read method, which we can use on Files:

use async_std::fs::File;
use async_std::prelude::*;

let mut f = File::open("foo.txt").await?;
let mut buffer = [0; 10];

// read up to 10 bytes
let n = f.read(&mut buffer).await?;

println!("The bytes: {:?}", &buffer[..n]);

Read and Write are so important, implementors of the two traits have a nickname: readers and writers. So you’ll sometimes see ‘a reader’ instead of ‘a type that implements the Read trait’. Much easier!

Seek and BufRead

Beyond that, there are two important traits that are provided: Seek and BufRead. Both of these build on top of a reader to control how the reading happens. Seek lets you control where the next byte is coming from:

use async_std::fs::File;
use async_std::io::SeekFrom;
use async_std::prelude::*;

let mut f = File::open("foo.txt").await?;
let mut buffer = [0; 10];

// skip to the last 10 bytes of the file
f.seek(SeekFrom::End(-10)).await?;

// read up to 10 bytes
let n = f.read(&mut buffer).await?;

println!("The bytes: {:?}", &buffer[..n]);

BufRead uses an internal buffer to provide a number of other ways to read, but to show it off, we’ll need to talk about buffers in general. Keep reading!

BufReader and BufWriter

Byte-based interfaces are unwieldy and can be inefficient, as we’d need to be making near-constant calls to the operating system. To help with this, std::io comes with two structs, BufReader and BufWriter, which wrap readers and writers. The wrapper uses a buffer, reducing the number of calls and providing nicer methods for accessing exactly what you want.

For example, BufReader works with the BufRead trait to add extra methods to any reader:

use async_std::fs::File;
use async_std::io::BufReader;
use async_std::prelude::*;

let f = File::open("foo.txt").await?;
let mut reader = BufReader::new(f);
let mut buffer = String::new();

// read a line into buffer
reader.read_line(&mut buffer).await?;

println!("{}", buffer);

BufWriter doesn’t add any new ways of writing; it just buffers every call to write:

use async_std::fs::File;
use async_std::io::prelude::*;
use async_std::io::BufWriter;

let f = File::create("foo.txt").await?;
{
    let mut writer = BufWriter::new(f);

    // write a byte to the buffer
    writer.write(&[42]).await?;
} // the buffer is flushed once writer goes out of scope
//

Standard input and output

A very common source of input is standard input:

use async_std::io;

let mut input = String::new();

io::stdin().read_line(&mut input).await?;

println!("You typed: {}", input.trim());

Note that you cannot use the ? operator in functions that do not return a Result<T, E>. Instead, you can call .unwrap() or match on the return value to catch any possible errors:

use async_std::io;

let mut input = String::new();

io::stdin().read_line(&mut input).await.unwrap();

And a very common source of output is standard output:

use async_std::io;
use async_std::io::prelude::*;

io::stdout().write(&[42]).await?;

Of course, using io::stdout directly is less common than something like println!.

Iterator types

A large number of the structures provided by std::io are for various ways of iterating over I/O. For example, Lines is used to split over lines:

use async_std::fs::File;
use async_std::io::BufReader;
use async_std::prelude::*;

let f = File::open("foo.txt").await?;
let reader = BufReader::new(f);

let mut lines = reader.lines();
while let Some(line) = lines.next().await {
    println!("{}", line?);
}

Functions

There are a number of functions that offer access to various features. For example, we can use three of these functions to copy everything from standard input to standard output:

use async_std::io;

io::copy(&mut io::stdin(), &mut io::stdout()).await?;

io::Result

Last, but certainly not least, is io::Result. This type is used as the return type of many std::io functions that can cause an error, and can be returned from your own functions as well. Many of the examples in this module use the ? operator:

#![allow(dead_code)]
use async_std::io;

async fn read_input() -> io::Result<()> {
    let mut input = String::new();

    io::stdin().read_line(&mut input).await?;

    println!("You typed: {}", input.trim());

    Ok(())
}

The return type of read_input, io::Result<()>, is a very common type for functions which don’t have a ‘real’ return value, but do want to return errors if they happen. In this case, the only purpose of this function is to read the line and print it, so we use ().

Platform-specific behavior

Many I/O functions throughout the standard library are documented to indicate what various library or syscalls they are delegated to. This is done to help applications both understand what’s happening under the hood as well as investigate any possibly unclear semantics. Note, however, that this is informative, not a binding contract. The implementation of many of these functions are subject to change over time and may call fewer or more syscalls/library functions.

Modules

Structs

  • BufReader
    Adds buffering to any reader.
  • BufWriter
    Wraps a writer and buffers its output.
  • Bytes
    A stream over u8 values of a reader.
  • Chain
    Adaptor to chain together two readers.
  • Cursor
    A Cursor wraps an in-memory buffer and provides it with a Seek implementation.
  • Empty
    A reader that contains no data.
  • Error
    The error type for I/O operations of the Read, Write, Seek, and associated traits.
  • IntoInnerError
    An error returned by into_inner which combines an error that happened while writing out the buffer, and the buffered writer object which may be used to recover from the condition.
  • IoSlice
    A buffer type used with Write::write_vectored.
  • IoSliceMut
    A buffer type used with Read::read_vectored.
  • Lines
    A stream of lines in a byte stream.
  • Repeat
    A reader which yields one byte over and over and over and over and over and…
  • Sink
    A writer that consumes and drops all data.
  • Split
    A stream over the contents of an instance of BufRead split on a particular byte.
  • Stderr
    A handle to the standard error of the current process.
  • Stdin
    A handle to the standard input of the current process.
  • Stdout
    A handle to the standard output of the current process.
  • Take
    Reader adaptor which limits the bytes read from an underlying reader.

Enums

  • ErrorKind
    A list specifying general categories of I/O error.
  • SeekFrom
    Enumeration of possible methods to seek within an I/O object.

Traits

Functions

  • copy
    Copies the entire contents of a reader into a writer.
  • empty
    Creates a reader that contains no data.
  • repeat
    Creates an instance of a reader that infinitely repeats one byte.
  • sink
    Creates a writer that consumes and drops all data.
  • stderr
    Constructs a new handle to the standard error of the current process.
  • stdin
    Constructs a new handle to the standard input of the current process.
  • stdout
    Constructs a new handle to the standard output of the current process.
  • timeout
    Awaits an I/O future or times out after a duration of time.

Type Aliases