csvutil

README

csvutil

csvutil is a set of types and funcs to deal with CSV data files in a somewhat convenient way.

Installation

$> go get go-hep.org/x/hep/csvutil

Documentation

Documentation is available on godoc:

godoc.org/go-hep.org/x/hep/csvutil

Example

Reading CSV into a struct

package main

import (
	"io"
	"log"

	"go-hep.org/x/hep/csvutil"
)

func main() {
	fname := "testdata/simple.csv"
	tbl, err := csvutil.Open(fname)
	if err != nil {
		log.Fatalf("could not open %s: %v\n", fname, err)
	}
	defer tbl.Close()
	tbl.Reader.Comma = ';'
	tbl.Reader.Comment = '#'

	rows, err := tbl.ReadRows(0, 10)
	if err != nil {
		log.Fatalf("could read rows [0, 10): %v\n", err)
	}
	defer rows.Close()

	irow := 0
	for rows.Next() {
		data := struct {
			I int
			F float64
			S string
		}{}
		err = rows.Scan(&data)
		if err != nil {
			log.Fatalf("error reading row %d: %v\n", irow, err)
		}
	}
	err = rows.Err()
	if err != nil {
		log.Fatalf("error: %v\n", err)
	}
}

Reading CSV into a slice of values

package main

import (
	"io"
	"log"

	"go-hep.org/x/hep/csvutil"
)

func main() {
	fname := "testdata/simple.csv"
	tbl, err := csvutil.Open(fname)
	if err != nil {
		log.Fatalf("could not open %s: %v\n", fname, err)
	}
	defer tbl.Close()
	tbl.Reader.Comma = ';'
	tbl.Reader.Comment = '#'

	rows, err := tbl.ReadRows(0, 10)
	if err != nil {
		log.Fatalf("could read rows [0, 10): %v\n", err)
	}
	defer rows.Close()

	irow := 0
	for rows.Next() {
		var (
			I int
			F float64
			S string
		)
		err = rows.Scan(&I, &F, &S)
		if err != nil {
			log.Fatalf("error reading row %d: %v\n", irow, err)
		}
	}
	err = rows.Err()
	if err != nil {
		log.Fatalf("error: %v\n", err)
	}
}

Writing CSV from a struct

package main

import (
	"log"

	"go-hep.org/x/hep/csvutil"
)

func main() {
	fname := "testdata/out.csv"
	tbl, err := csvutil.Create(fname)
	if err != nil {
		log.Fatalf("could not create %s: %v\n", fname, err)
	}
	defer tbl.Close()
	tbl.Writer.Comma = ';'

	err = tbl.WriteHeader("## a simple set of data: int64;float64;string\n")
	if err != nil {
		log.Fatalf("error writing header: %v\n", err)
	}

	for i := 0; i < 10; i++ {
		data := struct {
			I int
			F float64
			S string
		}{
			I: i,
			F: float64(i),
			S: fmt.Sprintf("str-%d", i),
		}
		err = tbl.WriteRow(data)
		if err != nil {
			log.Fatalf("error writing row %d: %v\n", i, err)
		}
	}

	err = tbl.Close()
	if err != nil {
		log.Fatalf("error closing table: %v\n", err)
	}
}

Writing from a slice of values

package main

import (
	"log"

	"go-hep.org/x/hep/csvutil"
)

func main() {
	fname := "testdata/out.csv"
	tbl, err := csvutil.Create(fname)
	if err != nil {
		log.Fatalf("could not create %s: %v\n", fname, err)
	}
	defer tbl.Close()
	tbl.Writer.Comma = ';'

	err = tbl.WriteHeader("## a simple set of data: int64;float64;string\n")
	if err != nil {
		log.Fatalf("error writing header: %v\n", err)
	}

	for i := 0; i < 10; i++ {
		var (
			f = float64(i)
			s = fmt.Sprintf("str-%d", i)
		)
		err = tbl.WriteRow(i, f, s)
		if err != nil {
			log.Fatalf("error writing row %d: %v\n", i, err)
		}
	}

	err = tbl.Close()
	if err != nil {
		log.Fatalf("error closing table: %v\n", err)
	}
}

Documentation

Overview

Package csvutil exposes functions and types to easily handle CSV files. csvutil builds upon the encoding/csv package and provides the Table type. A Table can read data from a CSV file into a struct value whose fields are the various columns of the CSV file. Conversely, a Table can write data into a CSV file from a struct value.

Example (ReadSlice)

fname := "testdata/simple.csv"
tbl, err := Open(fname)
if err != nil {
	log.Fatalf("could not open %s: %v\n", fname, err)
}
defer tbl.Close()
tbl.Reader.Comma = ';'
tbl.Reader.Comment = '#'

rows, err := tbl.ReadRows(0, 10)
if err != nil {
	log.Fatalf("could read rows [0, 10): %v\n", err)
}
defer rows.Close()

irow := 0
for rows.Next() {
	var (
		I int
		F float64
		S string
	)
	err = rows.Scan(&I, &F, &S)
	if err != nil {
		log.Fatalf("error reading row %d: %v\n", irow, err)
	}
}
err = rows.Err()
if err != nil {
	log.Fatalf("error: %v\n", err)
}

Example (ReadStruct)

fname := "testdata/simple.csv"
tbl, err := Open(fname)
if err != nil {
	log.Fatalf("could not open %s: %v\n", fname, err)
}
defer tbl.Close()
tbl.Reader.Comma = ';'
tbl.Reader.Comment = '#'

rows, err := tbl.ReadRows(0, 10)
if err != nil {
	log.Fatalf("could read rows [0, 10): %v\n", err)
}
defer rows.Close()

irow := 0
for rows.Next() {
	data := struct {
		I int
		F float64
		S string
	}{}
	err = rows.Scan(&data)
	if err != nil {
		log.Fatalf("error reading row %d: %v\n", irow, err)
	}
}
err = rows.Err()
if err != nil {
	log.Fatalf("error: %v\n", err)
}

Example (WriteSlice)

fname := "out.csv"
tbl, err := Create(fname)
if err != nil {
	log.Fatalf("could not create %s: %v\n", fname, err)
}
defer tbl.Close()
tbl.Writer.Comma = ';'

err = tbl.WriteHeader("## a simple set of data: int64;float64;string\n")
if err != nil {
	log.Fatalf("error writing header: %v\n", err)
}

for i := 0; i < 10; i++ {
	var (
		f = float64(i)
		s = fmt.Sprintf("str-%d", i)
	)
	err = tbl.WriteRow(i, f, s)
	if err != nil {
		log.Fatalf("error writing row %d: %v\n", i, err)
	}
}

err = tbl.Close()
if err != nil {
	log.Fatalf("error closing table: %v\n", err)
}

Example (WriteStruct)

fname := "out.csv"
tbl, err := Create(fname)
if err != nil {
	log.Fatalf("could not create %s: %v\n", fname, err)
}
defer tbl.Close()
tbl.Writer.Comma = ';'

err = tbl.WriteHeader("## a simple set of data: int64;float64;string\n")
if err != nil {
	log.Fatalf("error writing header: %v\n", err)
}

for i := 0; i < 10; i++ {
	data := struct {
		I int
		F float64
		S string
	}{
		I: i,
		F: float64(i),
		S: fmt.Sprintf("str-%d", i),
	}
	err = tbl.WriteRow(data)
	if err != nil {
		log.Fatalf("error writing row %d: %v\n", i, err)
	}
}

err = tbl.Close()
if err != nil {
	log.Fatalf("error closing table: %v\n", err)
}

Index

• type Rows
  • func (rows *Rows) Close() error
  • func (rows *Rows) Err() error
  • func (rows *Rows) Fields() []string
  • func (rows *Rows) Next() bool
  • func (rows *Rows) NumFields() int
  • func (rows *Rows) Scan(dest ...interface{}) error
• type Table
  • func Append(fname string) (*Table, error)
  • func Create(fname string) (*Table, error)
  • func Open(fname string) (*Table, error)
  • func (tbl *Table) Close() error
  • func (tbl *Table) ReadRows(beg, end int64) (*Rows, error)
  • func (tbl *Table) WriteHeader(hdr string) error
  • func (tbl *Table) WriteRow(args ...interface{}) error

Examples

• Package (ReadSlice)
• Package (ReadStruct)
• Package (WriteSlice)
• Package (WriteStruct)

Types

type Rows

type Rows struct {
	// contains filtered or unexported fields
}

Rows is an iterator over an interval of rows inside a CSV file.

func (*Rows) Close

func (rows *Rows) Close() error

Close closes the Rows, preventing further enumeration. Close is idempotent and does not affect the result of Err.

func (*Rows) Err

func (rows *Rows) Err() error

Err returns the error, if any, that was encountered during iteration. Err may be called after an explicit or implicit Close.

func (*Rows) Fields

func (rows *Rows) Fields() []string

Fields returns the raw string values of the fields of the current CSV-record. Fields assumes Rows.Next() has been called at least once.

func (*Rows) Next

func (rows *Rows) Next() bool

Next prepares the next result row for reading with the Scan method. It returns true on success, false if there is no next result row. Every call to Scan, even the first one, must be preceded by a call to Next.

func (*Rows) NumFields

func (rows *Rows) NumFields() int

NumFields returns the number of fields in the current CSV-record. NumFields assumes Rows.Next() has been called at least once.

func (*Rows) Scan

func (rows *Rows) Scan(dest ...interface{}) error

Scan copies the columns in the current row into the values pointed at by dest. dest can be either: - a pointer to a struct value (whose fields will be filled with column values) - a slice of values

type Table

type Table struct {
	Reader *csv.Reader
	Writer *csv.Writer
	// contains filtered or unexported fields
}

Table provides read- or write-access to a CSV file. Table supports reading and writing data to/from a struct value.

func Append

func Append(fname string) (*Table, error)

Append opens an already existing CSV file and returns a Table in write mode. The file cursor is positioned at the end of the file so new data can be appended via the returned Table.

func Create

func Create(fname string) (*Table, error)

Create creates a new CSV file and returns a Table in write mode.

func Open

func Open(fname string) (*Table, error)

Open opens a Table in read mode connected to a CSV file.

func (*Table) Close

func (tbl *Table) Close() error

Close closes the table and the underlying CSV file.

func (*Table) ReadRows

func (tbl *Table) ReadRows(beg, end int64) (*Rows, error)

ReadRows returns a row iterator semantically equivalent to [beg,end). If end==-1, the iterator will be configured to read rows until EOF.

func (*Table) WriteHeader

func (tbl *Table) WriteHeader(hdr string) error

WriteHeader writes a header to the underlying CSV file

func (*Table) WriteRow

func (tbl *Table) WriteRow(args ...interface{}) error

WriteRow writes the data into the columns at the current row.