-- (c) Copyright - See License.txt

--****

-- == Data type conversion

--

-- <>

--

namespace convert

constant

--****

-- === Routines

--**

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

--

-- Parameters:

-- # ##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]]

integer a,b,c,d

end function

-- an 8-element sequence

end type

-- a 4-element sequence

end type

--**

-- Converts a sequence of at most 4 bytes into an atom.

--

-- Parameters:

-- # ##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]]

else

end if

end function

--**

-- Extracts the lower bits from an integer.

--

-- Parameters:

-- # ##x## : the atom to convert

-- # ##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 subscripting, slicing, and/or/xor/not of entire sequences etc.

-- 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]]

sequence bits

atom mask

end if

-- faster method

else

-- slower, but works for large x and large nbits

end if

end if

end function

--**

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

--

-- Parameters:

-- # ##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]]

-- get the (positive) value of a sequence of "bits"

atom value, p

end if

end function

--**

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

-- Parameters:

-- # ##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:

--

-- 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]]

end function

--**

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

-- Parameters:

-- # ##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]]

end function

--**

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

--

-- Parameters:

-- # ##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]]

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

end function

--**

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

-- Parameters:

-- # ##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]]

end function

--**

-- Convert a text representation of a hexadecimal number to an atom

-- Parameters:

-- # ##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]]

atom res

atom fp

integer div

integer pos

integer sign

integer n

end if

else

end if

end if

else

end if

end if

else

end if

end if

end if

end if

else

end if

end if

end function

--**

-- Gets, and possibly sets, the decimal mark that [[:to_number]]() uses.

--

-- Parameters:

-- # ##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.

integer old_mark

case ',', '.' then

case else

-- do nothing.

end switch

end function

--**

-- Converts the text into a number.

--

-- Parameters:

-- # ##text_in## : A string containing the text representation of a number.

-- # ##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:

-- # 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.

-- # 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]]().

-- # You can supply a single leading or trailing sign. Either a minus (-) or plus (+).

-- # 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.

-- # You can have single currency symbol before the first digit or after the last

-- digit. A currency symbol is any character of the string: "$£¤¥€".

-- # You can have any number of whitespace characters before the first digit and

-- after the last digit.

-- # 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$-", etc.

-- # 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.

-- # 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.

--

-- Examples:

--

-- object val

-- 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

--

-- get the numeric result of text_in

integer lCharValue

atom lResult

integer lChar

end if

case '-' then

else

end if

case '+' then

else

end if

case '#' then

else

end if

case '@' then

else

end if

case '!' then

else

end if

case '$', '£', '¤', '¥', '€' then

else

end if

case '_' then -- grouping character

end if

case '.', ',' then

else

end if

else

-- Ignore it

end if

else

end if

case '%' then

else

else

end if

end if

case '\t', ' ', #A0 then

-- skip it

else

end if

case '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',

'A', 'B', 'C', 'D', 'E', 'F',

'a', 'b', 'c', 'd', 'e', 'f' then

end if

else

end if

case else

end switch

end if

-- Error if no actual digits where converted.

end if

end if

-- Common situation optimised for speed.

else

end if

else

else

end if

end if

end if

end if

else

end if

end if

end function

--**

-- Converts an object into a integer.

--

-- Parameters:

-- # ##data_in## : Any Euphoria object.

-- # ##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.

--

-- Examples:

--

-- ? 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)

--

end if

end if

end if

else

end if

end function