string-expression  binary numeric-expression
  OR
  with binary numeric-expression

binary can be used in several different ways: mathematical operator, prefix operator, or open modifier. Each is described in turn below.

As a mathematical operator, it is used to process a string of 1 to 4 characters as if it were a sequence of 8 to 32 bits, and to yield the number represented by the sequence. This can be very useful when processing binary data in files, where numbers are often stored as bit sequences rather than as string representations.

For example, a word processor that uses escape codes and character counts to indicate the length of a given sequence might specify that the next 90 bytes should be underlined by two characters "%21#%90#. (The "%21#" character is also known as a "Control-U" character, obtained by pressing the CTRL-U on the keyboard. The "%90#" is also the letter "z".) This representation is more succinct than using the character "90" to represent the length.

In OmniMark, converting a value such as "z" into its decimal value (in this example, 90) is done using the binary operator. As long as the string values are one-character long (a zero-length string may not be converted), the order of evaluation is obvious.

A problem arises when a numeric value is represented with more than one byte. On some systems, the higher the byte position, the more significant its value; on others, the lower bytes are more significant. Some other systems only swap bytes within each pair: the higher pair could be more significant, but within each pair the lower byte would be more significant.

The binary operator can be used in two different ways. The general form takes two operands:

1. the string expression containing the binary representation of the number.
2. a numeric expression specifying how bytes are ordered in binary representation.

The more compact form of binary takes only the string-expression operand. The default ordering is 0. This can be changed with the binary-input declaration.

binary can be used as a prefix operator when the desired byte ordering is the same as:

• the one set by the binary-input declaration.
• zero if there is no binary-input.

binary can also be used as an open modifier. In this form, binary is followed by a numeric expression that evaluates to a valid binary ordering number (0, 1, 2, or 3). The binary modifier specifies the default byte ordering code to use in "%b" format items written to that stream. It overrides the default established by the binary-output declaration.

The following list describes the meaning of each byte-ordering value.The example shows how different values affect conversion on the string "%10r{1,2,3,4}".

• 0: The first bytes (the highest) contain the high-order bits of the number, the last contain the low-order bits. The above string would be converted to the number 1 * 16,777,216 + 2 * 65536 + 3 * 256 + 4 =16,909,060.
• 1: The bytes are taken from the string in pairs and the bytes within the pairs are swapped: The first pair contains the high-order bits of the number, the last pair contains the low-order bits. Within each pair, which contains 16 bits of the number, the first character contains the low-order 8 bits, and the second contains the high-order 8 bits. The above string would be converted to 2 * 16,777,216 + 1 * 65536 + 4 * 256 + 3 = 33,620,995.
• 2: The bytes are taken from the string in pairs, and the pairs are swapped:The first pair contains the low-order bits of the number, the last pair contains the high-order bits. Within each pair, which contains 16 bits of the number, the first character contains the high-order 8 bits, and the second contains the low-order 8 bits. The above string would be converted to 3 * 16,777,216 + 4 * 65536 + 1 * 256 + 2 = 50,594,050.
• 3: The first character contains the low-order bits of the number, the last contains the high-order bits. The string would be converted to 4 * 16,777,216 + 3 * 65536 + 2 * 256 + 1 = 67,305,985.

Code numbers greater than 3 are divided by 4, and the remainder is used (that is the code number "modulo" 4 is used). Code numbers less than zero are in error.

The following example demonstrates the use of the binary operator to convert binary data to a numeric expression:

  cross-translate

  find any {1 to 4} => word
     local counter i
     set i to word binary 0
     output "The value is %d(i)%n"