oi

README

go-oi

Package oi provides useful tools to be used with the Go programming language's standard "io" package.

For example, did you know that when you call the Write method on something that fits the io.Writer interface, that it is possible that not everything was be written?!

I.e., that a short write happened.

That just doing the following is (in general) not enough:

n, err := writer.Write(p)

That, for example, you should be checking if err == io.ErrShortWrite, and then maybe calling the Write method again but only with what didn't get written.

For a simple example of this (that actually is not sufficient to solve this problem, but illustrates the direction you would need to go to solve this problem is):

n, err := w.Write(p)

if io.ErrShortWrite == err {
	n2, err2 := w.Write(p[n:])
}

Note that the second call to the Write method passed p[n:] (instead of just p), to account for the n bytes already being written (with the first call to the Write method).

A more "production quality" version of this would likely be in a loop, but such that that the loop had "guards" against looping forever, and also possibly looping for "too long".

Well package oi provides tools that helps you deal with this and other problems. For example, you can handle a short write with the following oi func:

n, err := oi.LongWrite(writer, p)

Documention

Online documentation, which includes examples, can be found at: http://godoc.org/github.com/reiver/go-oi

Example

import (
	"github.com/reiver/go-oi"
)

// ...

p := []byte("It is important that this message be written!!!")

n, err := oi.LongWrite(writer, p)
if nil != err {
	//@TODO: Handle error.
	return
}

Documentation

Overview

Package oi provides useful tools to be used with Go's standard "io" package.

For example, did you know that when you call the Write method on something that fits the io.Writer interface, that it is possible that not everything was be written?!

I.e., that a 'short write' happened.

That just doing the following is (in general) not enough:

n, err := writer.Write(p)

That, for example, you should be checking if "err == io.ErrShortWrite", and then maybe calling the Write method again but only with what didn't get written.

For a simple example of this (that actually is not sufficient to solve this problem, but illustrates the direction you would need to go to solve this problem is):

n, err := w.Write(p)

if io.ErrShortWrite == err {
	n2, err2 := w.Write(p[n:])
}

Note that the second call to the Write method passed "p[n:]" (instead of just "p"), to account for the "n" bytes already being written (with the first call to the `Write` method).

A more "production quality" version of this would likely be in a loop, but such that that the loop had "guards" against looping forever, and also possibly looping for "too long".

Well package oi provides tools that helps you deal with this and other problems. For example, you can handle a 'short write' with the following oi func: ``` n, err := oi.LongWrite(writer, p) ```

Index

• func LongWrite(w io.Writer, p []byte) (int64, error)
• func LongWriteByte(w io.Writer, b byte) error
• func LongWriteString(w io.Writer, s string) (int64, error)
• func WriteNopCloser(w io.Writer) io.WriteCloser

Functions

func LongWrite

func LongWrite(w io.Writer, p []byte) (int64, error)

LongWrite tries to write the bytes from 'p' to the writer 'w', such that it deals with "short writes" where w.Write would return an error of io.ErrShortWrite and n < len(p).

Note that LongWrite still could return the error io.ErrShortWrite; but this would only be after trying to handle the io.ErrShortWrite a number of times, and then eventually giving up.

func LongWriteByte

func LongWriteByte(w io.Writer, b byte) error

LongWriteByte trys to write the byte from 'b' to the writer 'w', such that it deals with "short writes" where w.Write would return an error of io.ErrShortWrite and n < 1.

Note that LongWriteByte still could return the error io.ErrShortWrite; but this would only be after trying to handle the io.ErrShortWrite a number of times, and then eventually giving up.

func LongWriteString

func LongWriteString(w io.Writer, s string) (int64, error)

LongWriteString tries to write the bytes from 's' to the writer 'w', such that it deals with "short writes" where w.Write (or w.WriteString) would return an error of io.ErrShortWrite and n < len(s).

Note that LongWriteString still could return the error io.ErrShortWrite; but this would only be after trying to handle the io.ErrShortWrite a number of times, and then eventually giving up.

func WriteNopCloser

func WriteNopCloser(w io.Writer) io.WriteCloser

WriteNopCloser takes an io.Writer and returns an io.WriteCloser where calling the Write method on the returned io.WriterCloser calls the Write method on the io.Writer it received, but whre calling the Close method on the returned io.WriterCloser does "nothing" (i.e., is a "nop").

This is useful in cases where an io.WriteCloser is expected, but you only have an io.Writer (where closing doesn't make sense) and you need to make your io.Writer fit. (I.e., you need an adaptor.)