| Syntax: | ? x |
| Description: | This is just a shorthand way of saying: pretty_print(1, x, {}) - i.e. printing the value of an expression to the standard output, with braces and indentation to show the structure. |
| Example: | |
? {1, 2} + {3, 4} -- will display {4, 6}
| |
| See Also: | pretty_print, print |
| Syntax: | abort(i) |
| Description: | Abort execution of the program. The argument i is a small integer status value to be returned to the operating system. A value of 0 generally indicates successful completion of the program. Other values can indicate various kinds of errors. DOS batch (.bat) programs can read this value using the errorlevel feature. A Euphoria program can read this value using system_exec(). |
| Comments: | abort() is useful when a program is many levels deep in
subroutine calls, and execution must end immediately, perhaps
due to a severe error that has been detected.
If you don't use abort(), ex.exe/exw.exe/exu will normally return an exit status code of 0. If your program fails with a Euphoria-detected compile-time or run-time error then a code of 1 is returned. |
| Example: | |
if x = 0 then
puts(ERR, "can't divide by 0 !!!\n")
abort(1)
else
z = y / x
end if
| |
| See Also: | crash_message, system_exec |
| Platform: | DOS32 |
| Syntax: | include graphics.e all_palette(s) |
| Description: | Specify new color intensities for the entire set of colors in the
current graphics mode. s is a sequence of the form: {{r,g,b}, {r,g,b}, ..., {r,g,b}} Each element specifies a new color intensity {red, green, blue} for the corresponding color number, starting with color number 0. The values for red, green and blue must be in the range 0 to 63. |
| Comments: | This executes much faster than if you were to use palette() to set the new color intensities one by one. This procedure can be used with read_bitmap() to quickly display a picture on the screen. |
| Example Program: | demo\dos32\bitmap.ex |
| See Also: | get_all_palette, palette, read_bitmap, video_config, graphics_mode |
| Syntax: | include machine.e a = allocate(i) |
| Description: | Allocate i contiguous bytes of memory. Return the address of the block of memory, or return 0 if the memory can't be allocated. The address returned will be at least 4-byte aligned. |
| Comments: | When you are finished using the block, you should pass the address of the block to free(). This will free the block and make the memory available for other purposes. Euphoria will never free or reuse your block until you explicitly call free(). When your program terminates, the operating system will reclaim all memory for use with other programs. |
| Example: | |
buffer = allocate(100)
for i = 0 to 99 do
poke(buffer+i, 0)
end for
| |
| See Also: | free, allocate_low, peek, poke, mem_set, call |
| Platform: | DOS32 |
| Syntax: | include machine.e i2 = allocate_low(i1) |
| Description: | Allocate i1 contiguous bytes of low memory, i.e. conventional memory (address below 1 megabyte). Return the address of the block of memory, or return 0 if the memory can't be allocated. |
| Comments: | Some DOS software interrupts require that you pass one or more addresses in registers. These addresses must be conventional memory addresses for DOS to be able to read or write to them. |
| Example Program: | demo\dos32\dosint.ex |
| See Also: | dos_interrupt, free_low, allocate, peek, poke |
| Syntax: | include machine.e a = allocate_string(s) |
| Description: | Allocate space for string sequence s. Copy s into this space along with a 0 terminating character. This is the format expected for C strings. The memory address of the string will be returned. If there is not enough memory available, 0 will be returned. |
| Comments: | To free the string, use free(). |
| Example: | |
atom title
title = allocate_string("The Wizard of Oz")
| |
| Example Program: | demo\win32\window.exw |
| See Also: | allocate, free |
| Syntax: | include file.e allow_break(i) |
| Description: | When i is 1 (true) control-c and control-Break can terminate your program when it tries to read input from the keyboard. When i is 0 (false) your program will not be terminated by control-c or control-Break. |
| Comments: | DOS will display ^C on the screen, even when your program cannot
be terminated.
Initially your program can be terminated at any point where it tries to read from the keyboard. It could also be terminated by other input/output operations depending on options the user has set in his config.sys file. (Consult an MS-DOS manual for the BREAK command.) For some types of program this sudden termination could leave things in a messy state and might result in loss of data. allow_break(0) lets you avoid this situation. You can find out if the user has pressed control-c or control-Break by calling check_break(). |
| Example: | |
allow_break(0) -- don't let the user kill me! | |
| See Also: | check_break |
| Syntax: | x3 = and_bits(x1, x2) |
| Description: | Perform the logical AND operation on corresponding bits in x1 and x2. A bit in x3 will be 1 only if the corresponding bits in x1 and x2 are both 1. |
| Comments: | The arguments to this function may be atoms or sequences. The
rules for operations on sequences apply.
The arguments must be representable as 32-bit numbers, either signed or unsigned. If you intend to manipulate full 32-bit values, you should declare your variables as atom, rather than integer. Euphoria's integer type is limited to 31-bits. Results are treated as signed numbers. They will be negative when the highest-order bit is 1. To understand the binary representation of a number you should display it in hexadecimal notation. Use the %x format of printf(). |
| Example 1: | |
a = and_bits(#0F0F0000, #12345678) -- a is #02040000 | |
| Example 2: | |
a = and_bits(#FF, {#123456, #876543, #2211})
-- a is {#56, #43, #11}
| |
| Example 3: | |
a = and_bits(#FFFFFFFF, #FFFFFFFF) -- a is -1 -- Note that #FFFFFFFF is a positive number, -- but the result of a bitwise logical operation is interpreted -- as a signed 32-bit number, so it's negative. | |
| See Also: | or_bits, xor_bits, not_bits, int_to_bits |
| Syntax: | s2 = append(s1, x) |
| Description: | Create a new sequence identical to s1 but with x added on the end as the last element. The length of s2 will be length(s1) + 1. |
| Comments: | If x is an atom this is equivalent to s2 = s1 & x. If x is a
sequence it is not equivalent.
The extra storage is allocated automatically and very efficiently with Euphoria's dynamic storage allocation. The case where s1 and s2 are actually the same variable (as in Example 1 below) is highly optimized. |
| Example 1: | You can use append() to dynamically grow a sequence, e.g. |
sequence x
x = {}
for i = 1 to 10 do
x = append(x, i)
end for
-- x is now {1,2,3,4,5,6,7,8,9,10}
| |
| Example 2: | Any kind of Euphoria object can be appended to a sequence, e.g. |
sequence x, y, z
x = {"fred", "barney"}
y = append(x, "wilma")
-- y is now {"fred", "barney", "wilma"}
z = append(append(y, "betty"), {"bam", "bam"})
-- z is now {"fred", "barney", "wilma", "betty", {"bam", "bam"}}
| |
| See Also: | prepend, concatenation operator &, sequence-formation operator |
| Syntax: | include misc.e x2 = arccos(x1) |
| Description: | Return an angle with cosine equal to x1. |
| Comments: | The argument, x1, must be in the range -1 to +1 inclusive.
A value between 0 and PI radians will be returned. This function may be applied to an atom or to all elements of a sequence. arccos() is not as fast as arctan(). |
| Example: | |
s = arccos({-1,0,1})
-- s is {3.141592654, 1.570796327, 0}
| |
| See Also: | cos, arcsin, arctan |
| Syntax: | include misc.e x2 = arcsin(x1) |
| Description: | Return an angle with sine equal to x1. |
| Comments: | The argument, x1, must be in the range -1 to +1 inclusive.
A value between -PI/2 and +PI/2 (radians) will be returned. This function may be applied to an atom or to all elements of a sequence. arcsin() is not as fast as arctan(). |
| Example: | |
s = arcsin({-1,0,1})
-- s is {-1.570796327, 0, 1.570796327}
| |
| See Also: | sin, arccos, arctan |
| Syntax: | x2 = arctan(x1) |
| Description: | Return an angle with tangent equal to x1. |
| Comments: | A value between -PI/2 and PI/2 (radians) will be returned.
This function may be applied to an atom or to all elements of a sequence. arctan() is faster than arcsin() or arccos(). |
| Example: | |
s = arctan({1,2,3})
-- s is {0.785398, 1.10715, 1.24905}
| |
| See Also: | tan, arcsin, arccos |
| Syntax: | i = atom(x) |
| Description: | Return 1 if x is an atom else return 0. |
| Comments: | This serves to define the atom type. You can also call it like an ordinary function to determine if an object is an atom. |
| Example 1: | |
atom a a = 5.99 | |
| Example 2: | |
object line
line = gets(0)
if atom(line) then
puts(SCREEN, "end of file\n")
end if
| |
| See Also: | sequence, object, integer, atoms and sequences |
| Syntax: | include machine.e s = atom_to_float32(a1) |
| Description: | Convert a Euphoria atom to a sequence of 4 single-byte values. These 4 bytes contain the representation of an IEEE floating-point number in 32-bit format. |
| 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. |
| Example: | |
fn = open("numbers.dat", "wb")
puts(fn, atom_to_float32(157.82)) -- write 4 bytes to a file
| |
| See Also: | atom_to_float64, float32_to_atom |
| Syntax: | include machine.e s = atom_to_float64(a1) |
| Description: | Convert a Euphoria atom to a sequence of 8 single-byte values. These 8 bytes contain the representation of an IEEE floating-point number in 64-bit format. |
| 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: | atom_to_float32, float64_to_atom |
| Syntax: | include machine.e a = bits_to_int(s) |
| Description: | Convert a sequence of binary 1's and 0's into a positive number. The least-significant bit is s[1]. |
| Comments: | 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: | |
a = bits_to_int({1,1,1,0,1})
-- a is 23 (binary 10111)
| |
| See Also: | int_to_bits, operations on sequences |
| Syntax: | include graphics.e bk_color(i) |
| Description: | Set the background color to one of the 16 standard colors. In pixel-graphics modes the whole screen is affected immediately. In text modes any new characters that you print will have the new background color. In some text modes there might only be 8 distinct background colors available. |
| Comments: | The 16 standard colors are defined as constants in
graphics.e
In pixel-graphics modes, color 0 which is normally BLACK, will be set to the same {r,g,b} palette value as color number i. In some pixel-graphics modes, there is a border color that appears at the edges of the screen. In 256-color modes, this is the 17th color in the palette. You can control it as you would any other color. In text modes, to restore the original background color when your program finishes, e.g. 0 - BLACK, you must call bk_color(0). If the cursor is at the bottom line of the screen, you may have to actually print something before terminating your program. Printing '\n' may be enough. |
| Example: | |
bk_color(BLACK) | |
| See Also: | text_color, palette |
| Syntax: | include machine.e a = bytes_to_int(s) |
| Description: | Convert a 4-element sequence of byte values to an atom. The elements of s are in the order expected for a 32-bit integer on the 386+, i.e. least-significant byte first. |
| Comments: | The result could be greater than the integer type allows, so you should
assign it to an atom.
s would normally contain positive values that have been read using peek() from 4 consecutive memory locations. |
| Example: | |
atom int32
int32 = bytes_to_int({37,1,0,0})
-- int32 is 37 + 256*1 = 293
| |
| See Also: | int_to_bytes, bits_to_int, peek, peek4s, peek4u, poke |