Install

The goinstall command can be used:

goinstall github.com/djimenez/iconv.go

Or, you can clone the repository and use gomake instead

git clone git://github.com/djimenez/iconv.go.git iconv
cd iconv
gomake install

Usage

To use the package, you'll need the appropriate import statement:

import (
	// if you used goinstall, you'll want this import
	iconv "github.com/djimenez/iconv.go"

	// if you used gomake install directly, you'll want this import
	iconv
)

Converting string Values

Converting a string can be done with two methods. First, there's iconv.ConvertString(input, fromEncoding, toEncoding string)

output,_ := iconv.ConvertString("Hello World!", "utf-8", "windows-1252")

Alternatively, you can create a converter and use its ConvertString method. This mostly just saves having to parse the from and to encodings when converting many strings in the same way.

converter := iconv.NewConverter("utf-8", "windows-1252")
output,_ := converter.ConvertString("Hello World!")

Converting []byte Values

Converting a []byte can similarly be done with two methods. First, there's iconv.Convert(input, output []byte, fromEncoding, toEncoding string). You'll immediately notice this requires you to give it both the input and output buffer. Ideally, the output buffer should be sized so that it can hold all converted bytes from input, but if it cannot, then Convert will put as many bytes as it can into the buffer without creating an invalid sequence. For example, if iconv only has a single byte left in the output buffer but needs 2 or more for the complete character in a multibyte encoding it will stop writing to the buffer and return with an iconv.E2BIG error.

input := []byte("Hello World!")
output := make([]byte, len(input))

bytesRead, bytesWritten, error := iconv.Convert(input, output, "utf-8", "windows-1252")

Just like with ConvertString, there is also a Convert method on Converter that can be used.

...
converter := iconv.NewConverter("utf-8", "windows-1252")

bytesRead, bytesWritten, error := converter.Convert(input, output)

Converting an *io.Reader

The iconv.Reader allows any other *io.Reader to be wrapped and have its bytes transcoded as they are read.

// We're wrapping stdin for simplicity, but a File or network reader could be wrapped as well
reader,_ := iconv.NewReader(os.Stdin, "utf-8", "windows-1252")

Converting an *io.Writer

To be written.

Piping a Conversion

To be written.