Type byte

The type byte is new in ScriptFu in GIMP v3.

It lets you read single 8-bit bytes from ports i.e. files and streams. For example, you could read sequences of RGBA bytes from an image file.

Built-in functions on the byte type

The type byte is an unsigned, 8-bit integer.

It has conversions to and from type integer.

Convert from byte type to integer type

(byte->integer <byte>) => <integer>

Converts a byte to an integer in range [0,255].

Convert from integer type to byte type

(integer->byte <integer>) => <byte>

Converts an integer to a byte. Returns the lower eight bits of the binary representation of the integer. Returns an error for negative integers.

Predicate on byte type

(byte? <any>) => [#f, #t]

Returns #t if the value has type byte.

Clarifications about the byte type

Type byte is not a numeric type

(number? (integer->byte 1)) => #f
(integer? (integer->byte 1)) => #f

eof-object is not of type byte

(byte? (read-byte)) => #f

This reads from the standard input port and when you have not typed anything it returns the eof-object, which is not of type byte.

Convert from byte type to character type

There are no direct conversion operations between byte and character. For bytes which hold single-byte chars you can use:

(integer->char (byte->integer b))

and for multi-byte chars you can write bytes into a string port to build a string.

Vectors of bytes

You can put bytes in Scheme vectors.

A vector of bytes is compact in that it is contiguous in the interpreter’s allocated memory.

A vector of bytes is not as small as you might think, since each element of a vector takes 32 bits, even if the element is of type byte.

Port operations by byte: read, write, and peek

You can use byte operations on any port. We do not distinguish ports by whether you can use byte operations on them. Other Scheme implementations have “binary-ports”. ScriptFu has no “binary-port?” predicate.

In ScriptFu TinyScheme, character operations on ports are implemented by byte operations. Character operations may read/write many bytes for one character, say for UTF-8 encoding. Generally, you would not mix byte and character operations on a port.

The standard input port is non-blocking. File ports are blocking and string ports are non-blocking. For other low-level uses and some ports to devices, a read may also block.

(byte-ready? <port>) => [#f, #t]

Returns #t if a subsequent read-byte would not block. This is only a test of the kind and state of the port. Returned #t does not guarantee that a subsequent read-byte would return other than eof-object. Returned #f means the port is a kind that could block, and is in a state that will block were read-byte to be called (unless the state changes in the meantime.)

read-byte operation

(read-byte [<port>]) => <byte> | eof-object

Reads a byte from the port and advances the port’s position. Returns a byte or the eof-object when the port is in the EOF condition. You can use “eof-object?” predicate. May yield an IO error from the OS. The port is optional, in which case it reads from the standard input port.

peek-byte operation

(peek-byte [<port>]) => <byte> | eof-object

Same as read-byte but does not advance the port’s position.

write-byte operation

(write-byte <byte> [<port>]) => [#f, #t]

Writes a byte to the port. Returns #t if successful. May yield IO errors. Illegal to pass an integer type.

The Gimp PDB and byte type