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

REBOL 3 Functions: transcode

transcode  source  /next  /only  /error

Translates UTF-8 binary source to values. Returns [value binary].

Arguments:

source [binary!] - Must be Unicode UTF-8 encoded

Refinements:

/next - Translate next complete value (blocks as single value)

/only - Translate only a single value (blocks dissected)

/error - Do not throw errors - return error object as value

See also:

to-block  

Contents

Description
Input
Refinements
Output

Description

The transcode function translates source code and data into the block value memory format that can be interpreted by REBOL.

Input

The source input to transcode must be Unicode UTF-8. This is a binary! encoded format, and should not be confused with a string!, which is a decoded in-memory indexable string.

If you need to transcode a string, you must convert it to a UTF-8 binary first. This can be done with to-binary.

data: transcode to-binary string
Reduced efficiency

In general, conversions to and from UTF-8 require extra time to for the Unicode conversion process. Therefore, is not a good idea to write REBOL code like TCL or PERL where computations are done on strings.

Don't write code such as:

do append "1 +" n

Because you can just as easily write:

do append [1 +] n

in REBOL.

Refinements

Without refinements, transcode will convert the entire input string.

Refinements are provided for partial translation:

/nextTranslate the next full value. If it is a block, translate the entire block.
/onlyTranslate the next singular value. If it is a block, translate only the first element of the block, and return it within a block.
/errorConvert syntax errors to error objects and output them rather than throwing them as an error.

These refinements can be used in various ways to parse REBOL source a value at a time.

Output

The output from transcode is a block! containing two values:

  1. The translated value, block of values, or error! object.
  2. The binary! source at the point where the translation ended.

For example:

a: to-binary "a b c"
#{6120622063}
transcode/only a
[a #{20622063}]


  TOC < Back Next > REBOL.com - WIP Wiki Feedback Admin