SYNOPSIS

Perl

use HaikuR1::PositionIO;

# define MyPositionIO subclass here

my $reader = MyPositionIO->new();
my $chunk = $reader->ReadAt($position, $length);

my $writer = MyPositionIO->new();
my $length_written = $writer->WriteAt($position, $chunk);

Python

from HaikuR1.SupportKit import PositionIO

# define MyPositionIO subclass here

reader = MyPositionIO()
chunk = reader.ReadAt(position, length)

writer = MyPositionIO()
length_written = writer.WriteAt(position, chunk)

DESCRIPTION

Exposes the BPositionIO object.

For more information on PositionIO, see the Be Book class description, the Be Book overview, and the Haiku Book class description.

NATIVE OBJECTS

As a convenience, you can substitute a native IO object or a native string in place of a PositionIO; internally it will be wrapped in a C++ object. The C++ wrapper implements ReadAt using Seek and Read, and implements WriteAt is using Seek and Write. See below for language-specific counterparts of the other methods.

If you are using a custom object instead of a standard native object, the methods in your object should have the same parameters and returns as standard native IO objects. A custom object only needs to provide the methods that the function calling the hook actually uses; if you are calling a function that only calls the C++ Read hook, for example, you only need to provide the counterpart of the Read method in your custom object.

Perl

If you use an IO object, any IO::Handle subclass will work, including any handle returned by open. Custom objects should implement the following methods:

Read => read
Write => print
Seek => seek
Position => tell
Flush => flush

If you use a string, you must pass a reference to the string as the parameter, not the string itself. The wrapper will call the standard IO::Handle functions on it, as if you had called open on the string reference and passed the resulting handle.

Python

If you use an IO object, io.FileIO or io.BytesIO will work. Custom objects should implement the following methods:

Read => read
Write => write
Seek => seek
Position => tell
Flush => flush

If you use a string, keep in mind that since Python strings are immutable, this does not work if the function is going to write to the DataIO. The glue code converts the string to an io.BufferedRandom object, which means the internal wrapper will happily write to that object (and not raise an exception), but you will not have any way to access the new value.

METHODS

Constructor

Creates a PositionIO object.

Perl

HaikuR1::PositionIO->new();

Python

PositionIO()

Position

Gets the read/write position. PositionIO does not provide a default version.

Perl

$positionio->Position();

Python

positionio.Position()

ReadAt

ReadAtExactly

Reads the given number of bytes from the given position in the source. Returns the string of bytes or signals an error. PositionIO does not provide a default version. ReadAtExactly signals an error if it is unable to read the given length, whereas ReadAt may read fewer bytes.

The returned string may contain null bytes.

ReadAt may also be called as a hook in some cicumstances. Additionally, since ReadAtExactly is internally implemented using ReadAt, calling ReadAtExactly will result in ReadAt being called as a hook.

Perl

$positionio->ReadAt($position, $size);
$positionio->ReadAtExactly($position, $size);

Python

positionio.ReadAt(position, size)
positionio.ReadAtExactly(position, size)

position

An integer, the position to read from.
size

An integer, the number of bytes to read.

Seek

Sets the read/write position to the given value. Returns the new position. PositionIO does not provide a default version.

Perl

$positionio->Seek($position, $seekMode);

Python

positionio.Seek(position, seekMode)

position

An integer, the new position.
seekMode

An integer, the mode.

Perl

The mode constants SEEK_SET, SEEK_CUR, and SEEK_END are available via the Fcntl module.

use Fcntl qw(:seek);

Python

The mode constants are available via the os module.

from os import SEEK_SET, SEEK_CUR, SEEK_END

Size

GetSize

SetSize

Gets or sets the size of the IO source/destination or signals an error. The default version of GetSize uses Seek and Position to determine the size. The default version of SetSize signals B_ERROR.

Perl

$positionio->GetSize();
$positionio->SetSize($size);

Python

positionio.GetSize()
positionio.SetSize(size)

size

An integer, the new size.

WriteAt

WriteAtExactly

Writes the given string of raw bytes from the destination. Returns the number of bytes written or signals an error. PositionIO does not provide a default version. WriteAtExactly signals an error if it is unable to write the entire string, whereas WriteAt may write fewer bytes.

WriteAt may also be called as a hook in some cicumstances. Additionally, since WriteAtExactly is internally implemented using WriteAt, calling WriteAtExactly will result in WriteAt being called as a hook.

Perl

$positionio->WriteAt($position, $buffer);
$positionio->WriteAtExactly($position, $buffer);

Python

positionio.WriteAt(position, buffer)
positionio.WriteAtExactly(position, buffer)

position

An integer, the position to write to.
buffer

A string of bytes to write; may contain null bytes.

DATAIO INTERFACE

PositionIO inherits the methods and hooks of DataIO.

The following differ from the DataIO versions:

Read

The default PositionIO version implements it by calling ReadAt with the current position.

Write

The default PositionIO version implements it by calling WriteAt with the current position.