bgzf

Documentation

Overview

Package bgzf implements BGZF format reading and writing according to the SAM specification.

The specification is available at https://github.com/samtools/hts-specs.

Index

• Constants
• Variables
• func HasEOF(r io.ReaderAt) (bool, error)
• type Block
• type Cache
• type Chunk
• type Offset
• type Reader
  • func NewReader(r io.Reader, rd int) (*Reader, error)
  • func (bg *Reader) Begin() Tx
  • func (bg *Reader) BlockLen() int
  • func (bg *Reader) Close() error
  • func (bg *Reader) LastChunk() Chunk
  • func (bg *Reader) Read(p []byte) (int, error)
  • func (bg *Reader) Seek(off Offset) error
  • func (bg *Reader) SetCache(c Cache)
• type Tx
  • func (t *Tx) End() Chunk
• type Wrapper
• type Writer
  • func NewWriter(w io.Writer, wc int) *Writer
  • func NewWriterLevel(w io.Writer, level, wc int) (*Writer, error)
  • func (bg *Writer) Close() error
  • func (bg *Writer) Error() error
  • func (bg *Writer) Flush() error
  • func (bg *Writer) Next() (int, error)
  • func (bg *Writer) Wait() error
  • func (bg *Writer) Write(b []byte) (int, error)

Constants

const (
	BlockSize    = 0x0ff00 // The maximum size of an uncompressed input data block.
	MaxBlockSize = 0x10000 // The maximum size of a compressed output block.
)

Variables

var (
	ErrClosed            = errors.New("bgzf: use of closed writer")
	ErrBlockOverflow     = errors.New("bgzf: block overflow")
	ErrWrongFileType     = errors.New("bgzf: file is a directory")
	ErrNoEnd             = errors.New("bgzf: cannot determine offset from end")
	ErrNotASeeker        = errors.New("bgzf: not a seeker")
	ErrContaminatedCache = errors.New("bgzf: cache owner mismatch")
	ErrNoBlockSize       = errors.New("bgzf: could not determine block size")
	ErrBlockSizeMismatch = errors.New("bgzf: unexpected block size")
)

Functions

func HasEOF

func HasEOF(r io.ReaderAt) (bool, error)

HasEOF checks for the presence of a BGZF magic EOF block. The magic block is defined in the SAM specification. A magic block is written by a Writer on calling Close. The ReaderAt must provide some method for determining valid ReadAt offsets.

Types

type Block

type Block interface {
	// Base returns the file offset of the start of
	// the gzip member from which the Block data was
	// decompressed.
	Base() int64

	io.Reader

	// Used returns whether one or more bytes have
	// been read from the Block.
	Used() bool

	// NextBase returns the expected position of the next
	// BGZF block. It returns -1 if the Block is not valid.
	NextBase() int64
	// contains filtered or unexported methods
}

Block wraps interaction with decompressed BGZF data blocks.

type Cache

type Cache interface {
	// Get returns the Block in the Cache with the specified
	// base or a nil Block if it does not exist. The returned
	// Block must be removed from the Cache.
	Get(base int64) Block

	// Put inserts a Block into the Cache, returning the Block
	// that was evicted or nil if no eviction was necessary and
	// a boolean indicating whether the put Block was retained
	// by the Cache.
	Put(Block) (evicted Block, retained bool)

	// Peek returns whether a Block exists in the cache for the
	// given base. If a Block satisfies the request, then exists
	// is returned as true with the offset for the next Block in
	// the stream, otherwise false and -1.
	Peek(base int64) (exists bool, next int64)
}

Cache is a Block caching type. Basic cache implementations are provided in the cache package. A Cache must be safe for concurrent use.

If a Cache is a Wrapper, its Wrap method is called on newly created blocks.

type Chunk

type Chunk struct {
	Begin Offset
	End   Offset
}

Chunk is a region of a BGZF file.

type Offset

type Offset struct {
	File  int64
	Block uint16
}

Offset is a BGZF virtual offset.

type Reader

type Reader struct {
	gzip.Header

	// Blocked specifies the behaviour of the
	// Reader at the end of a BGZF member.
	// If the Reader is Blocked, a Read that
	// reaches the end of a BGZF block will
	// return io.EOF. This error is not sticky,
	// so a subsequent Read will progress to
	// the next block if it is available.
	Blocked bool
	// contains filtered or unexported fields
}

Reader implements BGZF blocked gzip decompression.

func NewReader

func NewReader(r io.Reader, rd int) (*Reader, error)

NewReader returns a new BGZF reader.

The number of concurrent read decompressors is specified by rd. If rd is 0, GOMAXPROCS concurrent will be created. The returned Reader should be closed after use to avoid leaking resources.

func (*Reader) Begin

func (bg *Reader) Begin() Tx

Begin returns a Tx that starts at the current virtual offset.

func (*Reader) BlockLen

func (bg *Reader) BlockLen() int

BlockLen returns the number of bytes remaining to be read from the current BGZF block.

func (*Reader) Close

func (bg *Reader) Close() error

Close closes the reader and releases resources.

func (*Reader) LastChunk

func (bg *Reader) LastChunk() Chunk

LastChunk returns the region of the BGZF file read by the last read operation or the resulting virtual offset of the last successful seek operation.

func (*Reader) Read

func (bg *Reader) Read(p []byte) (int, error)

Read implements the io.Reader interface.

func (*Reader) Seek

func (bg *Reader) Seek(off Offset) error

Seek performs a seek operation to the given virtual offset.

func (*Reader) SetCache

func (bg *Reader) SetCache(c Cache)

SetCache sets the cache to be used by the Reader.

type Tx

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

Tx represents a multi-read transaction.

func (*Tx) End

func (t *Tx) End() Chunk

End returns the Chunk spanning the transaction. After return the Tx is no longer valid.

type Wrapper

type Wrapper interface {
	Wrap(Block) Block
}

Wrapper defines Cache types that need to modify a Block at its creation.

type Writer

type Writer struct {
	gzip.Header
	// contains filtered or unexported fields
}

Writer implements BGZF blocked gzip compression.

func NewWriter

func NewWriter(w io.Writer, wc int) *Writer

NewWriter returns a new Writer. Writes to the returned writer are compressed and written to w.

The number of concurrent write compressors is specified by wc.

func NewWriterLevel

func NewWriterLevel(w io.Writer, level, wc int) (*Writer, error)

NewWriterLevel returns a new Writer using the specified compression level instead of gzip.DefaultCompression. Allowable level options are integer values between between gzip.BestSpeed and gzip.BestCompression inclusive.

The number of concurrent write compressors is specified by wc.

func (*Writer) Close

func (bg *Writer) Close() error

Close closes the Writer, waiting for any pending writes before returning the final error of the Writer.

func (*Writer) Error

func (bg *Writer) Error() error

Error returns the error state of the Writer.

func (*Writer) Flush

func (bg *Writer) Flush() error

Flush writes unwritten data to the underlying io.Writer. Flush does not block.

func (*Writer) Next

func (bg *Writer) Next() (int, error)

Next returns the index of the start of the next write within the decompressed data block.

func (*Writer) Wait

func (bg *Writer) Wait() error

Wait waits for all pending writes to complete and returns the subsequent error state of the Writer.

func (*Writer) Write

func (bg *Writer) Write(b []byte) (int, error)

Write writes the compressed form of b to the underlying io.Writer. Decompressed data blocks are limited to BlockSize, so individual byte slices may span block boundaries, however the Writer attempts to keep each write within a single data block.