recno

Documentation

Overview

Package recno implements the record number access method of Berkeley DB 1.85: records of a flat text file addressed by their position.

Keys are record numbers starting at 1, encoded as 4 bytes in native byte order, see binary.NativeEndian.

Example

package main

import (
	"encoding/binary"
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/dim13/db"
	"github.com/dim13/db/recno"
)

func key(n uint32) []byte {
	return binary.NativeEndian.AppendUint32(nil, n)
}

func main() {
	name := filepath.Join(os.TempDir(), "example.txt")
	defer os.Remove(name)
	if err := os.WriteFile(name, []byte("one\ntwo\nthree\n"), 0644); err != nil {
		log.Fatal(err)
	}

	f, err := os.OpenFile(name, os.O_RDWR, 0)
	if err != nil {
		log.Fatal(err)
	}
	d, err := recno.New(f, nil)
	if err != nil {
		log.Fatal(err)
	}

	v, _ := d.Get(key(2), db.RNone)
	fmt.Printf("%s\n", v)

	d.Del(key(1), db.RNone)                   // "two" becomes record 1
	d.Put(key(3), []byte("four"), db.RNone)   // append
	d.Put(key(1), []byte("one"), db.RIBefore) // insert at the front
	if err := d.Close(); err != nil {         // writes the file back
		log.Fatal(err)
	}

	b, _ := os.ReadFile(name)
	fmt.Printf("%s", b)
}

Output:
two
one
two
three
four

Index

• type DB
  • func New(file *os.File, info *Info) (*DB, error)
  • func (r *DB) Close() error
  • func (r *DB) Del(key []byte, flag db.Flag) (err error)
  • func (r *DB) Fd() uintptr
  • func (r *DB) Get(key []byte, flag db.Flag) (data []byte, err error)
  • func (r *DB) Put(key, data []byte, flag db.Flag) (rkey []byte, err error)
  • func (r *DB) Seq(key []byte, flag db.Flag) (rkey, data []byte, err error)
  • func (r *DB) Sync(flag db.Flag) error
• type Flag
• type Info

Examples

• Package

Types

type DB

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

DB is an open record number database, safe for concurrent use: Get calls run in parallel, other methods one at a time; Seq has a single cursor shared by all callers.

func New

func New(file *os.File, info *Info) (*DB, error)

New opens a database of the records in a flat text file, or an in-memory one if file is nil. Records are read from the file as needed and written back by Sync or Close, so the caller must Close the database, which also closes file and Info.BTreeFile.

func (*DB) Close

func (r *DB) Close() error

Close writes changed records back to the flat file and closes it and the btree file.

func (*DB) Del

func (r *DB) Del(key []byte, flag db.Flag) (err error)

Del deletes the record numbered key, or with RCursor the record at the cursor, renumbering the records after it.

func (*DB) Fd

func (r *DB) Fd() uintptr

Fd returns the file descriptor of the flat file, or ^uintptr(0) if there is none.

func (*DB) Get

func (r *DB) Get(key []byte, flag db.Flag) (data []byte, err error)

Get returns the record numbered key, or ErrNotFound.

func (*DB) Put

func (r *DB) Put(key, data []byte, flag db.Flag) (rkey []byte, err error)

Put stores data as record key and returns its record number. Missing records before key are created empty. RIBefore and RIAfter insert before or after record key, RSetCursor also moves the cursor there, RCursor replaces the record at the cursor, and RNoOverwrite returns ErrKeyExist for an existing record.

func (*DB) Seq

func (r *DB) Seq(key []byte, flag db.Flag) (rkey, data []byte, err error)

Seq returns the next record number and record, or ErrNotFound at the end. RFirst and RLast start at either end, RCursor at record key; RNext and RPrev continue the scan.

func (*DB) Sync

func (r *DB) Sync(flag db.Flag) error

Sync writes the records back to the flat file. With RRecnoSync it syncs only the btree file.

type Flag

type Flag uint

Flag is an option of Info.Flags.

const (
	RFixedLen Flag = 1 << iota // records of Info.RecordLen bytes
	RNoKey                     // accepted, has no effect
	RSnapshot                  // read the whole file in New
)

Info flags

type Info

type Info struct {
	Flags     Flag             // RFixedLen, RNoKey, RSnapshot
	PageSize  int              // of a new btree file, default 4096
	CacheSize int              // bytes of btree pages cached, default 1 MiB, at least 5 pages
	ByteOrder binary.ByteOrder // byte order, nil for native
	RecordLen int              // length of fixed-length records
	Delimiter byte             // delimiter, newline if zero; pad byte of fixed-length records
	BTreeFile *os.File         // btree file, nil for in-memory tree
	ReadOnly  bool             // refuse changes, never write
}

Info holds options for New. Zero fields and a nil Info select defaults.