REBOL 3 Docs Guide Concepts Functions Datatypes Errors
  TOC < Back Next >   Updated: 30-Apr-2010 Edit History  

REBOL 3 Datatypes: Binary!

Different from R2

The binary datatype has changed significantly in REBOL 3.

  1. operations on binary have a different meaning. The biggest change is that a single element of a binary series is an integer ranging from 0-255, not a char! datatype. That is, if you get a single byte (e.g. pick) you'll get an integer. If you insert or poke an binary, an integer value is will taken as-is, not converted to a character representation.
  2. a string! datatype may be Unicode so converting a string containing non-ASCII characters will result in a binary string that is UTF-8 encoded. For example a string of length five may produce an output larger than five bytes.

We plan to add a lot more documentation to this page to explain how to properly use the binary datatype for releases beyond R3-A98.



The binary! datatype is a series of bytes (8-bits each, octets).

Binary is the raw storage format for all files and networking. It holds encoded data such as images, sounds, strings (in formats like UTF-8 and others), movies, compressed data, encrypted data, and others.

The meaning of an specific binary value depends on what it holds. For example, if you read a JPEG image, it's just a sequence of bytes. Once you've decoded those bytes, it becomes an image! datatype.


The source format for binary data can be base-2 (binary), base-16 (hex), and base-64. The default base for binary data in REBOL is base-16.

Binary strings are written as a number sign (#) followed by a string enclosed in braces. The characters within the string are encoded in one of several formats as specified by an optional number prior to the number sign. Base-16 is the default format.

#{3A18427F 899AEFD8} ; default base-16
2#{10010110110010101001011011001011} ; base-2
64#{LmNvbSA8yw9CB0aGvXmgUkVCu2Uz934b} ; base-64

Spaces, tabs and newlines are permitted within the string. Binary data can span multiple lines.

probe #{

Strings should contain the correct number of characters to create a binary result which is an integral number of bytes (integral multiple of 8 bits).


The to-binary function converts data to the binary! datatype at the default base set in system/options/binary-base:

probe to-binary "123"
probe to-binary "today is the day..."

To convert an integer into its binary value, pass it in a block:

probe to-binary [1]
probe to-binary [11]

Converting a series of integers into a binary, returns the bit conversion for each integer concatenated into a single binary value:

probe to-binary [1 1 1 1]


Use binary? determine whether a value is an binary! datatype.

probe binary? #{616263}

Binary values are a type of series:

probe series? #{616263}
probe length? #{616263} ; three hex values in this binary

Closely related to working with binary! datatypes are the functions enbase and debase. The enbase function converts strings to their base-2, base-16 or base-64 representations as strings. The debase function converts enbased strings to a binary value of the base specified in system/options/binary-base.

  TOC < Back Next > - WIP Wiki Feedback Admin