OpenEuphoria: Euphoria v4.1

# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.12 Utilities | Up: 8 API Reference | 8.14 Input Routines > | 9 Release Notes >>

## 8.13 Data Type Conversion

### 8.13.1 Routines

#### 8.13.1.1 int_to_bytes

    include std/convert.e
    namespace convert
    public function int_to_bytes(atom x, integer size = 4)

converts an atom that represents an integer to a sequence of 4 bytes.

##### Parameters:

1. `x` : an atom, the value to convert.

##### Returns:

A sequence, of 4 bytes, lowest significant byte first.

##### Comments:

If the atom does not fit into a 32-bit integer, things may still work right:

- If there is a fractional part, the first element in the returned value will carry it. If you poke the sequence to RAM, that fraction will be discarded anyway.
- If `x` is simply too big, the first three bytes will still be correct, and the 4th element will be `floor(x/power(2,24))`. If this is not a byte sized integer, some truncation may occur, but usually no error.

The integer can be negative. Negative byte-values will be returned, but after poking them into memory you will have the correct (two's complement) representation for the 386+.

##### Example 1:

    s = int_to_bytes(999)
    -- s is {231, 3, 0, 0}

##### Example 2:

    s = int_to_bytes(-999)
    -- s is {-231, -4, -1, -1}

##### See Also:

bytes_to_int, int_to_bits, atom_to_float64, poke4

#### 8.13.1.2 bytes_to_int

    include std/convert.e
    namespace convert
    public function bytes_to_int(sequence s)

converts a sequence of at most 4 bytes into an atom.

##### Parameters:

1. `s` : the sequence to convert

##### Returns:

An atom, the value of the concatenated bytes of `s`.

##### Comments:

This performs the reverse operation from int_to_bytes

An atom is being returned, because the converted value may be bigger than what can fit in an Euphoria integer.

##### Example 1:

    atom int32

    int32 = bytes_to_int({37,1,0,0})
    -- int32 is 37 + 256*1 = 293

##### See Also:

bits_to_int, float64_to_atom, int_to_bytes, peek, peek4s, peek4u, poke4

#### 8.13.1.3 int_to_bits

    include std/convert.e
    namespace convert
    public function int_to_bits(atom x, integer nbits = 32)

extracts the lower bits from an integer.

##### Parameters:

1. `x` : the atom to convert
2. `nbits` : the number of bits requested. The default is 32.

##### Returns:

A sequence, of length `nbits`, made of 1's and 0's.

##### Comments:

`x` should have no fractional part. If it does, then the first "bit" will be an atom between 0 and 2.

The bits are returned lowest first.

For negative numbers the two's complement bit pattern is returned.

You can use operators like subscripting/slicing/and/or/xor/not on entire sequences to manipulate sequences of bits. Shifting of bits and rotating of bits are easy to perform.

##### Example 1:

    s = int_to_bits(177, 8)
    -- s is {1,0,0,0,1,1,0,1} -- "reverse" order

##### See Also:

bits_to_int, int_to_bytes, Relational operators, operations on sequences

#### 8.13.1.4 bits_to_int

    include std/convert.e
    namespace convert
    public function bits_to_int(sequence bits)

converts a sequence of bits to an atom that has no fractional part.

##### Parameters:

1. `bits` : the sequence to convert.

##### Returns:

A positive atom, whose machine representation was given by `bits`.

##### Comments:

An element in `bits` can be any atom. If nonzero, it counts for 1, else for 0.

The first elements in `bits` represent the bits with the least weight in the returned value. Only the 52 last bits will matter, as the PC hardware cannot hold an integer with more digits than this.

If you print s the bits will appear in "reverse" order, but it is convenient to have increasing subscripts access bits of increasing significance.

##### Example 1:

    a = bits_to_int({1,1,1,0,1})
    -- a is 23 (binary 10111)

##### See Also:

bytes_to_int, int_to_bits, operations on sequences

#### 8.13.1.5 atom_to_float64

    include std/convert.e
    namespace convert
    public function atom_to_float64(atom a)

converts an atom to a sequence of 8 bytes in IEEE 64-bit format.

##### Parameters:

1. `a` : the atom to convert:

##### Returns:

A sequence, of 8 bytes, which can be poked in memory to represent `a`.

##### Comments:

All Euphoria atoms have values which can be represented as 64-bit IEEE floating-point numbers, so you can convert any atom to 64-bit format without losing any precision.

Integer values will also be converted to 64-bit floating-point format.

##### Example 1:

    fn = open("numbers.dat", "wb")
    puts(fn, atom_to_float64(157.82)) -- write 8 bytes to a file

##### See Also:

float64_to_atom, int_to_bytes, atom_to_float32

#### 8.13.1.6 atom_to_float80

    include std/convert.e
    namespace convert
    public function atom_to_float80(atom a)

#### 8.13.1.7 float80_to_atom

    include std/convert.e
    namespace convert
    public function float80_to_atom(sequence bytes)

#### 8.13.1.8 atom_to_float32

    include std/convert.e
    namespace convert
    public function atom_to_float32(atom a)

converts an atom to a sequence of 4 bytes in IEEE 32-bit format.

##### Parameters:

1. `a` : the atom to convert:

##### Returns:

A sequence, of 4 bytes, which can be poked in memory to represent `a`.

##### Comments:

Euphoria atoms can have values which are 64-bit IEEE floating-point numbers, so you may lose precision when you convert to 32-bits (16 significant digits versus 7). The range of exponents is much larger in 64-bit format (10 to the 308, versus 10 to the 38), so some atoms may be too large or too small to represent in 32-bit format. In this case you will get one of the special 32-bit values: `inf` or `-inf` (infinity or -infinity). To avoid this, you can use atom_to_float64.

Integer values will also be converted to 32-bit floating-point format.

On modern computers, computations on 64 bit floats are no slower than on 32 bit floats. Internally, the PC stores them in 80 bit registers anyway. Euphoria does not support these so called long doubles. Not all C compilers do.

##### Example 1:

    fn = open("numbers.dat", "wb")
    puts(fn, atom_to_float32(157.82)) -- write 4 bytes to a file

##### See Also:

float32_to_atom, int_to_bytes, atom_to_float64

#### 8.13.1.9 float64_to_atom

    include std/convert.e
    namespace convert
    public function float64_to_atom(sequence_8 ieee64)

converts a sequence of 8 bytes in IEEE 64-bit format to an atom.

##### Parameters:

1. `ieee64` : the sequence to convert.

##### Returns:

An atom, the same value as the FPU would see by peeking `ieee64` from RAM.

##### Comments:

Any 64-bit IEEE floating-point number can be converted to an atom.

##### Example 1:

    f = repeat(0, 8)
    fn = open("numbers.dat", "rb")  -- read binary
    for i = 1 to 8 do
        f[i] = getc(fn)
    end for
    a = float64_to_atom(f)

##### See Also:

float32_to_atom, bytes_to_int, atom_to_float64

#### 8.13.1.10 float32_to_atom

    include std/convert.e
    namespace convert
    public function float32_to_atom(sequence_4 ieee32)

converts a sequence of 4 bytes in IEEE 32-bit format to an atom.

##### Parameters:

1. `ieee32` : the sequence to convert.

##### Returns:

An atom, the same value as the FPU would see by peeking `ieee64` from RAM.

##### Comments:

Any 32-bit IEEE floating-point number can be converted to an atom.

##### Example 1:

    f = repeat(0, 4)
    fn = open("numbers.dat", "rb") -- read binary
    f[1] = getc(fn)
    f[2] = getc(fn)
    f[3] = getc(fn)
    f[4] = getc(fn)
    a = float32_to_atom(f)

##### See Also:

float64_to_atom, bytes_to_int, atom_to_float32

#### 8.13.1.11 hex_text

    include std/convert.e
    namespace convert
    public function hex_text(sequence text)

converts a text representation of a hexadecimal number to an atom.

##### Parameters:

1. `text` : the text to convert.

##### Returns:

An atom, the numeric equivalent to `text`

##### Comments:

- The text can optionally begin with `'#'` which is ignored.
- The text can have any number of underscores, all of which are ignored.
- The text can have one leading `'-'`, indicating a negative number.
- The text can have any number of underscores, all of which are ignored.
- Any other characters in the text stops the parsing and returns the value thus far.

##### Example 1:

    atom h = hex_text("-#3_4FA.00E_1BD")
     -- h is now -13562.003444492816925
     atom h = hex_text("DEADBEEF")
     -- h is now 3735928559

##### See Also:

value

#### 8.13.1.12 set_decimal_mark

    include std/convert.e
    namespace convert
    public function set_decimal_mark(integer new_mark)

gets, and possibly sets, the decimal mark that to_number uses.

##### Parameters:

1. `new_mark` : An integer: Either a comma (,), a period (.) or any other integer.

##### Returns:

An integer, The current value, before `new_mark` changes it.

##### Comments:

- When `new_mark` is a period it will cause `to_number` to interpret a dot `(.)` as the decimal point symbol. The pre-changed value is returned.
- When `new_mark` is a comma it will cause `to_number` to interpret a comma `(,)` as the decimal point symbol. The pre-changed value is returned.
- Any other value does not change the current setting. Instead it just returns the current value.
- The initial value of the decimal marker is a period.

#### 8.13.1.13 to_number

    include std/convert.e
    namespace convert
    public function to_number(sequence text_in, integer return_bad_pos = 0)

converts the text into a number.

##### Parameters:

1. `text_in` : A string containing the text representation of a number.
2. `return_bad_pos` : An integer.
   - If 0 (the default) then this will return a number based on the supplied text and it will not return any position in `text_in` that caused an incomplete conversion.
   - If `return_bad_pos` is -1 then if the conversion of `text_in` was complete the resulting number is returned otherwise a single-element sequence containing the position within `text_in` where the conversion stopped.
   - If not 0 then this returns both the converted value up to the point of failure (if any) and the position in `text_in` that caused the failure. If that position is 0 then there was no failure.

##### Returns:

- an atom, If `return_bad_pos` is zero, the number represented by `text_in`. If `text_in` contains invalid characters, zero is returned.
- a sequence, If `return_bad_pos` is non-zero. If `return_bad_pos` is -1 it returns a 1-element sequence containing the spot inside `text_in` where conversion stopped. Otherwise it returns a 2-element sequence containing the number represented by `text_in` and either 0 or the position in `text_in` where conversion stopped.

##### Comments:

1. You can supply Hexadecimal values if the value is preceded by a '#' character, Octal values if the value is preceded by a '@' character, and Binary values if the value is preceded by a '!' character. With hexadecimal values, the case of the digits 'A' - 'F' is not important. Also, any decimal marker embedded in the number is used with the correct base.
2. Any underscore characters or thousands separators, that are embedded in the text number are ignored. These can be used to help visual clarity for long numbers. The thousands separator is a ',' when the decimal mark is '.' (the default), or '.' if the decimal mark is ','. You inspect and set it using set_decimal_mark().
3. You can supply a single leading or trailing sign. Either a minus (-) or plus (+).
4. You can supply one or more trailing adjacent percentage signs. The first one causes the resulting value to be divided by 100, and each subsequent one divides the result by a further 10. Thus `3845%` gives a value of `(3845 / 100) ==> 38.45`, and `3845%%` gives a value of `(3845 / 1000) ==> 3.845`.
5. You can have single currency symbol before the first digit or after the last digit. A currency symbol is any character of the string: "$£¤¥€".
6. You can have any number of whitespace characters before the first digit and after the last digit.
7. The currency, sign and base symbols can appear in any order. Thus `"$ -21.10"` is the same as `" -$21.10 "`, which is also the same as `"21.10$-"`, and so on.
8. This function can optionally return information about invalid numbers. If `return_bad_pos` is not zero, a two-element sequence is returned. The first element is the converted number value , and the second is the position in the text where conversion stopped. If no errors were found then the second element is zero.
9. When converting floating point text numbers to atoms, you need to be aware that many numbers cannot be accurately converted to the exact value expected due to the limitations of the 64-bit IEEEE Floating point format.

##### Example 1:

    object val
    val = to_number("12.34")      ---> 12.34 -- No errors and no error return needed.
    val = to_number("12.34", 1)   ---> {12.34, 0} -- No errors.
    val = to_number("12.34", -1)  ---> 12.34 -- No errors.
    val = to_number("12.34a", 1)  ---> {12.34, 6} -- Error at position 6
    val = to_number("12.34a", -1) ---> {6} -- Error at position 6
    val = to_number("12.34a")     ---> 0 because its not a valid number

    val = to_number("#f80c")        --> 63500
    val = to_number("#f80c.7aa")    --> 63500.47900390625
    val = to_number("@1703")        --> 963
    val = to_number("!101101")      --> 45
    val = to_number("12_583_891")   --> 12583891
    val = to_number("12_583_891%")  --> 125838.91
    val = to_number("12,583,891%%") --> 12583.891

#### 8.13.1.14 to_integer

    include std/convert.e
    namespace convert
    public function to_integer(object data_in, integer def_value = 0)

converts an object into a integer.

##### Parameters:

1. `data_in` : Any Euphoria object.
2. `def_value` : An integer. This is returned if `data_in` cannot be converted into an integer. If omitted, zero is returned.

##### Returns:

An integer, either the integer rendition of `data_in` or `def_value` if it has no integer value.

##### Comments:

The returned value is guaranteed to be a valid Euphoria integer.

##### Example 1:

    ? to_integer(12)            --> 12
    ? to_integer(12.4)          --> 12
    ? to_integer("12")          --> 12
    ? to_integer("12.9")        --> 12

    ? to_integer("a12")         --> 0 (not a valid number)
    ? to_integer("a12",-1)      --> -1 (not a valid number)
    ? to_integer({"12"})        --> 0 (sub-sequence found)
    ? to_integer(#3FFFFFFF)     --> 1073741823
    ? to_integer(#3FFFFFFF + 1) --> 0 (too big for a Euphoria integer)

#### 8.13.1.15 to_string

    include std/convert.e
    namespace convert
    public function to_string(object data_in, integer string_quote = 0,
            integer embed_string_quote = '"')

converts an object into a text string.

##### Parameters:

1. `data_in` : Any Euphoria object.
2. `string_quote` : An integer. If not zero (the default) this will be used to enclose `data_in`, if it is already a string.
3. `embed_string_quote` : An integer. This will be used to enclose any strings embedded inside `data_in`. The default is '"'

##### Returns:

A sequence. This is the string repesentation of `data_in`.

##### Comments:

- The returned value is guaranteed to be a displayable text string.
- `string_quote` is only used if `data_in` is already a string. In this case, all occurances of `string_quote` already in `data_in` are prefixed with the '\' escape character, as are any preexisting escape characters. Then `string_quote` is added to both ends of `data_in`, resulting in a quoted string.
- `embed_string_quote` is only used if `data_in` is a sequence that contains strings. In this case, it is used as the enclosing quote for embedded strings.

##### Example 1:

    include std/console.e
    display(to_string(12))           --> 12
    display(to_string("abc"))        --> abc
    display(to_string("abc",'"'))    --> "abc"
    display(to_string(`abc\"`,'"'))  --> "abc\\\""
    display(to_string({12,"abc",{4.5, -99}}))    --> {12, "abc", {4.5, -99}}
    display(to_string({12,"abc",{4.5, -99}},,0)) --> {12, abc, {4.5, -99}}

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.12 Utilities | Up: 8 API Reference | 8.14 Input Routines > | 9 Release Notes >>