io

Documentation

Overview

Package io provides reading and writing DataFrames to/from external formats.

Supported Formats

• CSV (read/write) — the most common data interchange format

Design Notes

We follow pandas' philosophy: reading is lenient (try to infer types), writing is explicit (always quote strings, handle nulls consistently).

CSV Type Inference

When reading CSV, every value is initially a string. We try to parse each column's values in order of specificity:

1. int64 (most specific — exact integer)
2. float64 (less specific — any decimal)
3. bool ("true"/"false"/"1"/"0")
4. null (empty cells)
5. string (fallback — keep as-is)

This matches pandas' read_csv() behavior with dtype inference enabled.

Index

• func ReadCSV(r io.Reader, opts *ReadCSVOptions) (*dataframe.DataFrame, error)
• func ReadCSVFile(path string, opts *ReadCSVOptions) (*dataframe.DataFrame, error)
• func WriteCSV(df *dataframe.DataFrame, w io.Writer, opts *WriteCSVOptions) error
• func WriteCSVFile(df *dataframe.DataFrame, path string, opts *WriteCSVOptions) error
• type ReadCSVOptions
• type WriteCSVOptions

Functions

func ReadCSV

func ReadCSV(r io.Reader, opts *ReadCSVOptions) (*dataframe.DataFrame, error)

ReadCSV reads CSV from any io.Reader and returns a DataFrame. Useful for reading from HTTP responses, in-memory buffers, etc.

func ReadCSVFile

func ReadCSVFile(path string, opts *ReadCSVOptions) (*dataframe.DataFrame, error)

ReadCSVFile reads a CSV file from disk and returns a DataFrame.

This is the most common entry point, equivalent to pd.read_csv("file.csv").

Example:

df, err := io.ReadCSVFile("data.csv", nil)
if err != nil { log.Fatal(err) }
fmt.Println(df)

func WriteCSV

func WriteCSV(df *dataframe.DataFrame, w io.Writer, opts *WriteCSVOptions) error

WriteCSV writes a DataFrame to any io.Writer in CSV format.

func WriteCSVFile

func WriteCSVFile(df *dataframe.DataFrame, path string, opts *WriteCSVOptions) error

WriteCSVFile writes a DataFrame to a CSV file. Equivalent to df.to_csv("file.csv") in pandas.

Types

type ReadCSVOptions

type ReadCSVOptions struct {
	// Delimiter is the field separator (default: ',').
	// Use '\t' for TSV files.
	Delimiter rune

	// HasHeader indicates whether the first row contains column names (default: true).
	HasHeader bool

	// NullValues is the set of strings treated as null (default: {"", "NA", "null", "NULL", "N/A"}).
	// This mirrors pandas' na_values parameter.
	NullValues map[string]bool

	// InferTypes controls automatic type detection (default: true).
	// If false, all columns are stored as strings.
	InferTypes bool

	// MaxRows limits the number of data rows read (0 = unlimited).
	MaxRows int
}

ReadCSVOptions configures CSV parsing behavior. Zero value provides sensible defaults matching pandas' read_csv() defaults.

type WriteCSVOptions

type WriteCSVOptions struct {
	// Delimiter is the output field separator (default: ',').
	Delimiter rune

	// NullValue is the string written for null values (default: "").
	// Use "NA" or "NaN" to match pandas' na_rep parameter.
	NullValue string

	// FloatFormat controls float formatting (default: 6 significant digits).
	// Use "" for Go's default %g formatting.
	FloatFormat string

	// WriteHeader controls whether to write the column header row (default: true).
	WriteHeader bool
}

WriteCSVOptions configures CSV output.