palette

Platform: DOS32
Syntax: include graphics.e
x = palette(i, s)
Description: Change the color for color number i to s, where s is a sequence of color intensities: {red, green, blue}. Each value in s can be from 0 to 63. If successful, a 3-element sequence containing the previous color for i will be returned, and all pixels on the screen with value i will be set to the new color. If unsuccessful, the atom -1 will be returned.
Example: 
x = palette(0, {15, 40, 10})
-- color number 0 (normally black) is changed to a shade
-- of mainly green.
See Also: all_palette

peek

Syntax: i = peek(a)
or ...
s = peek({a, i})
Description: Return a single byte value in the range 0 to 255 from machine address a, or return a sequence containing i consecutive byte values starting at address a in memory.
Comments: Since addresses are 32-bit numbers, they can be larger than the largest value of type integer (31-bits). Variables that hold an address should therefore be declared as atoms.

It is faster to read several bytes at once using the second form of peek() than it is to read one byte at a time in a loop.

Remember that peek takes just one argument, which in the second form is actually a 2-element sequence.

Example: The following are equivalent: 

-- method 1
s = {peek(100), peek(101), peek(102), peek(103)}

-- method 2
s = peek({100, 4})
See Also: poke, peek4s, peek4u, allocate, free, allocate_low, free_low, call

peek4s

Syntax: a2 = peek4s(a1)
or ...
s = peek4s({a1, i})
Description: Return a 4-byte (32-bit) signed value in the range -2147483648 to +2147483647 from machine address a1, or return a sequence containing i consecutive 4-byte signed values starting at address a1 in memory.
Comments: The 32-bit values returned by peek4s() may be too large for the Euphoria integer type (31-bits), so you should use atom variables.

Since machine addresses are 32-bit numbers, they can also be too large for Euphoria's integer type. Variables that hold an address should therefore be declared as atoms.

It is faster to read several 4-byte values at once using the second form of peek4s() than it is to read one 4-byte value at a time in a loop.

Remember that peek4s() takes just one argument, which in the second form is actually a 2-element sequence.

Example: The following are equivalent: 

-- method 1
s = {peek4s(100), peek4s(104), peek4s(108), peek4s(112)}

-- method 2
s = peek4s({100, 4})
See Also: peek4u, peek, poke4, allocate, free, allocate_low, free_low, call

peek4u

Syntax: a2 = peek4u(a1)
or ...
s = peek4u({a1, i})
Description: Return a 4-byte (32-bit) unsigned value in the range 0 to 4294967295 from machine address a1, or return a sequence containing i consecutive 4-byte unsigned values starting at address a1 in memory.
Comments: The 32-bit values returned by peek4u() may be too large for the Euphoria integer type (31-bits), so you should use atom variables.

Since machine addresses are 32-bit numbers, they can also be too large for Euphoria's integer type. Variables that hold an address should therefore be declared as atoms.

It is faster to read several 4-byte values at once using the second form of peek4u() than it is to read one 4-byte value at a time in a loop.

Remember that peek4u() takes just one argument, which in the second form is actually a 2-element sequence.

Example: The following are equivalent: 

-- method 1
s = {peek4u(100), peek4u(104), peek4u(108), peek4u(112)}

-- method 2
s = peek4u({100, 4})
See Also: peek4s, peek, poke4, allocate, free, allocate_low, free_low, call

PI

Syntax: include misc.e
PI
Description: PI (3.14159...) has been defined as a global constant.
Comments: Enough digits have been used to attain the maximum accuracy possible for a Euphoria atom.
Example: 
x = PI  -- x is 3.14159...
See Also: sin, cos, tan

pixel

Platform: DOS32
Syntax: pixel(x1, s)
Description: Set one or more pixels on a pixel-graphics screen starting at point s, where s is a 2-element screen coordinate {x, y}. If x1 is an atom, one pixel will be set to the color indicated by x1. If x1 is a sequence then a number of pixels will be set, starting at s and moving to the right (increasing x value, same y value).
Comments: When x1 is a sequence, a very fast algorithm is used to put the pixels on the screen. It is much faster to call pixel() once, with a sequence of pixel colors, than it is to call it many times, plotting one pixel color at a time.

In graphics mode 19, pixel() is highly optimized.

Any off-screen pixels will be safely clipped.

Example 1: 
pixel(BLUE, {50, 60})
-- the point {50,60} is set to the color BLUE
Example 2: 
pixel({BLUE, GREEN, WHITE, RED}, {50,60})
-- {50,60} set to BLUE
-- {51,60} set to GREEN
-- {52,60} set to WHITE
-- {53,60} set to RED
See Also: get_pixel, graphics_mode

platform

Syntax: i = platform()
Description: platform() is a function built-in to the interpreter. It indicates the platform that the program is being executed on: DOS32, WIN32, Linux or FreeBSD.
Comments: When ex.exe is running, the platform is DOS32. When exw.exe is running the platform is WIN32. When exu is running the platform is LINUX (or FREEBSD).

The include file misc.e contains the following constants: 

    global constant DOS32 = 1,
                    WIN32 = 2,
                    LINUX = 3,
                    FREEBSD = 3
Use platform() when you want to execute different code depending on which platform the program is running on.

Additional platforms will be added as Euphoria is ported to new machines and operating environments.

The call to platform() costs nothing. It is optimized at compile-time into the appropriate integer value: 1, 2 or 3.

Example 1: 
if platform() = WIN32 then
    -- call system Beep routine
    err = c_func(Beep, {0,0})
elsif platform() = DOS32 then
    -- make beep
    sound(500)
    t = time()
    while time() < t + 0.5 do
    end while
    sound(0)
else
    -- do nothing (Linux/FreeBSD)
end if
See Also: platform.doc

poke

Syntax: poke(a, x)
Description: If x is an atom, write a single byte value to memory address a.

If x is a sequence, write a sequence of byte values to consecutive memory locations starting at location a.

Comments: The lower 8-bits of each byte value, i.e. remainder(x, 256), is actually stored in memory.

It is faster to write several bytes at once by poking a sequence of values, than it is to write one byte at a time in a loop.

Writing to the screen memory with poke() can be much faster than using puts() or printf(), but the programming is more difficult. In most cases the speed is not needed. For example, the Euphoria editor, ed, never uses poke().

Example: 
a = allocate(100)   -- allocate 100 bytes in memory

-- poke one byte at a time:
poke(a, 97)
poke(a+1, 98)
poke(a+2, 99)

-- poke 3 bytes at once:
poke(a, {97, 98, 99})
Example Program: demo\callmach.ex
See Also: peek, poke4, allocate, free, allocate_low, free_low, call, safe.e

poke4

Syntax: poke4(a, x)
Description: If x is an atom, write a 4-byte (32-bit) value to memory address a.

If x is a sequence, write a sequence of 4-byte values to consecutive memory locations starting at location a.

Comments: The value or values to be stored must not exceed 32-bits in size.

It is faster to write several 4-byte values at once by poking a sequence of values, than it is to write one 4-byte value at a time in a loop.

The 4-byte values to be stored can be negative or positive. You can read them back with either peek4s() or peek4u().

Example: 
a = allocate(100)   -- allocate 100 bytes in memory

-- poke one 4-byte value at a time:
poke4(a, 9712345)
poke4(a+4, #FF00FF00)
poke4(a+8, -12345)

-- poke 3 4-byte values at once:
poke4(a, {9712345, #FF00FF00, -12345})
See Also: peek4u, peek4s, poke, allocate, allocate_low, call

polygon

Platform: DOS32
Syntax: include graphics.e
polygon(i1, i2, s)
Description: Draw a polygon with 3 or more vertices given in s, on a pixel-graphics screen using a certain color i1. Fill the area if i2 is 1. Don't fill if i2 is 0.
Example: 
polygon(GREEN, 1, {{100, 100}, {200, 200}, {900, 700}})
-- makes a solid green triangle.
See Also: draw_line, ellipse

position

Syntax: position(i1, i2)
Description: Set the cursor to line i1, column i2, where the top left corner of the screen is line 1, column 1. The next character displayed on the screen will be printed at this location. position() will report an error if the location is off the screen.
Comments: position() works in both text and pixel-graphics modes.

The coordinate system for displaying text is different from the one for displaying pixels. Pixels are displayed such that the top-left is (x=0,y=0) and the first coordinate controls the horizontal, left-right location. In pixel-graphics modes you can display both text and pixels. position() only sets the line and column for the text that you display, not the pixels that you plot. There is no corresponding routine for setting the next pixel position.

Example: 
position(2,1)
-- the cursor moves to the beginning of the second line from
-- the top
See Also: get_position, puts, print, printf

power

Syntax: x3 = power(x1, x2)
Description: Raise x1 to the power x2
Comments: The arguments to this function may be atoms or sequences. The rules for operations on sequences apply.

Powers of 2 are calculated very efficiently.

Example 1: 
? power(5, 2)
-- 25 is printed
Example 2: 
? power({5, 4, 3.5}, {2, 1, -0.5})
-- {25, 4, 0.534522} is printed
Example 3: 
? power(2, {1, 2, 3, 4})
-- {2, 4, 8, 16}
Example 4: 
? power({1, 2, 3, 4}, 2)
-- {1, 4, 9, 16}
See Also: log, sqrt

prepend

Syntax: s2 = prepend(s1, x)
Description: Prepend x to the start of sequence s1. The length of s2 will be length(s1) + 1.
Comments: If x is an atom this is the same as s2 = x & s1. If x is a sequence it is definitely not the same.

The case where s1 and s2 are the same variable is handled very efficiently.

Example 1: 
prepend({1,2,3}, {0,0})   -- {{0,0}, 1, 2, 3}

-- Compare with concatenation:

{0,0} & {1,2,3}           -- {0, 0, 1, 2, 3}
Example 2: 
s = {}
for i = 1 to 10 do
    s = prepend(s, i)
end for
-- s is {10,9,8,7,6,5,4,3,2,1}
See Also: append, concatenation operator &, sequence-formation operator

pretty_print

Syntax: include misc.e
pretty_print(fn, x, s)
Description: Print, to file or device fn, an object x, using braces { , , , }, indentation, and multiple lines to show the structure.

Several options may be supplied in s to control the presentation. Pass {} to select the defaults, or set options as below:
[1] display ASCII characters:
* 0: never
* 1: alongside any integers in the printable ASCII range 32..127 (default)
* 2: like 1, plus display as "string" when all integers of a sequence are in the printable ASCII range
* 3: like 2, but show *only* quoted characters, not numbers, for any integers in the printable ASCII range, as well as the whitespace characters: \t \r \n
[2] amount to indent for each level of sequence nesting - default: 2
[3] column we are starting at - default: 1
[4] approximate column to wrap at - default: 78
[5] format to use for integers - default: "%d"
[6] format to use for floating-point numbers - default: "%.10g"
[7] minimum value for printable ASCII - default 32
[8] maximum value for printable ASCII - default 127
[9] maximum number of lines to output

If the length of s is less than 8, unspecified options at the end of the sequence will keep the default values. e.g. {0, 5} will choose "never display ASCII", plus 5-character indentation, with defaults for everything else.

Comments: The display will start at the current cursor position. Normally you will want to call pretty_print() when the cursor is in column 1 (after printing a \n character). If you want to start in a different column, you should call position() and specify a value for option [3]. This will ensure that the first and last braces in a sequence line up vertically.

When specifying the format to use for integers and floating-point numbers, you can add some decoration, e.g. "(%d)" or "$ %.2f"

Example 1: 
pretty_print(1, "ABC", {})    

{65'A',66'B',67'C'}
Example 2: 
pretty_print(1, {{1,2,3}, {4,5,6}}, {})  
          
{
  {1,2,3},
  {4,5,6}
}
Example 3: 
pretty_print(1, {"Euphoria", "Programming", "Language"}, {2})  

{
  "Euphoria",
  "Programming",
  "Language"
}
Example 4: 
puts(1, "word_list = ") -- moves cursor to column 13
pretty_print(1, 
             {{"Euphoria", 8, 5.3}, 
              {"Programming", 11, -2.9}, 
              {"Language", 8, 9.8}}, 
             {2, 4, 13, 78, "%03d", "%.3f"}) -- first 6 of 8 options

word_list = {
                {
                    "Euphoria",
                    008,
                    5.300
                },
                {
                    "Programming",
                    011,
                    -2.900
                },
                {
                    "Language",
                    008,
                    9.800
                }
            }
See Also: ?, print, puts, printf

print

Syntax: print(fn, x)
Description: Print, to file or device fn, an object x with braces { , , , } to show the structure.
Example 1: 
print(1, "ABC")  -- output is:  {65, 66, 67}
puts(1, "ABC")   -- output is:  ABC
Example 2: 
print(1, repeat({10,20}, 3))
-- output is: {{10,20},{10,20},{10,20}}
See Also: ?, pretty_print, puts, printf, get

printf

Syntax: printf(fn, st, x)
Description: Print x, to file or device fn, using format string st. If x is a sequence, then format specifiers from st are matched with corresponding elements of x. If x is an atom, then normally st will contain just one format specifier and it will be applied to x, however if st contains multiple format specifiers, each one will be applied to the same value x. Thus printf() always takes exactly 3 arguments. Only the length of the last argument, containing the values to be printed, will vary. The basic format specifiers are:

%d - print an atom as a decimal integer
%x - print an atom as a hexadecimal integer. Negative numbers are printed in two's complement, so -1 will print as FFFFFFFF
%o - print an atom as an octal integer
%s - print a sequence as a string of characters, or print an atom as a single character
%e - print an atom as a floating-point number with exponential notation
%f - print an atom as a floating-point number with a decimal point but no exponent
%g - print an atom as a floating-point number using whichever format seems appropriate, given the magnitude of the number
%% - print the '%' character itself

Field widths can be added to the basic formats, e.g. %5d, %8.2f, %10.4s. The number before the decimal point is the minimum field width to be used. The number after the decimal point is the precision to be used.

If the field width is negative, e.g. %-5d then the value will be left-justified within the field. Normally it will be right-justified. If the field width starts with a leading 0, e.g. %08d then leading zeros will be supplied to fill up the field. If the field width starts with a '+' e.g. %+7d then a plus sign will be printed for positive values.

Comments: Watch out for the following common mistake: 
    name="John Smith"
    printf(1, "%s", name)     -- error!
This will print only the first character, J, of name, as each element of name is taken to be a separate value to be formatted. You must say this instead: 
    name="John Smith"
    printf(1, "%s", {name})   -- correct
Now, the third argument of printf() is a one-element sequence containing the item to be formatted.
Example 1: 
rate = 7.875
printf(myfile, "The interest rate is: %8.2f\n", rate)

      The interest rate is:     7.88
Example 2: 
name="John Smith"
score=97
printf(1, "%15s, %5d\n", {name, score})

      John Smith,    97
Example 3: 
printf(1, "%-10.4s $ %s", {"ABCDEFGHIJKLMNOP", "XXX"})

      ABCD       $ XXX
Example 4: 
printf(1, "%d  %e  %f  %g", 7.75) -- same value in different formats

      7  7.750000e+000  7.750000  7.75
See Also: sprintf, puts, open

profile

Syntax: profile(i)
Description: Enable or disable profiling at run-time. This works for both execution-count and time-profiling. If i is 1 then profiling will be enabled, and samples/counts will be recorded. If i is 0 then profiling will be disabled and samples/counts will not be recorded.
Comments: After a "with profile" or "with profile_time" statement, profiling is turned on automatically. Use profile(0) to turn it off. Use profile(1) to turn it back on when execution reaches the code that you wish to focus the profile on.
Example 1: 
with profile_time
profile(0)
  ...
procedure slow_routine()
profile(1)
  ...
profile(0)
end procedure
See Also: trace, profiling, special top-level statements

prompt_number

Syntax: include get.e
a = prompt_number(st, s)
Description: Prompt the user to enter a number. st is a string of text that will be displayed on the screen. s is a sequence of two values {lower, upper} which determine the range of values that the user may enter. If the user enters a number that is less than lower or greater than upper, he will be prompted again. s can be empty, {}, if there are no restrictions.
Comments: If this routine is too simple for your needs, feel free to copy it and make your own more specialized version.
Example 1: 
age = prompt_number("What is your age? ", {0, 150})
Example 2: 
t = prompt_number("Enter a temperature in Celcius:\n", {})
See Also: get, prompt_string

prompt_string

Syntax: include get.e
s = prompt_string(st)
Description: Prompt the user to enter a string of text. st is a string that will be displayed on the screen. The string that the user types will be returned as a sequence, minus any new-line character.
Comments: If the user happens to type control-Z (indicates end-of-file), "" will be returned.
Example: 
name = prompt_string("What is your name? ")
See Also: gets, prompt_number

put_screen_char

Syntax: include image.e
put_screen_char(i1, i2, s)
Description: Write zero or more characters onto the screen along with their attributes. i1 specifies the line, and i2 specifies the column where the first character should be written. The sequence s looks like: {ascii-code1, attribute1, ascii-code2, attribute2, ...}. Each pair of elements in s describes one character. The ascii-code atom contains the ASCII code of the character. The attributes atom contains the foreground color, background color, and possibly other platform-dependent information controlling how the character is displayed on the screen.
Comments: The length of s must be a multiple of 2. If s has 0 length, nothing will be written to the screen.

It's faster to write several characters to the screen with a single call to put_screen_char() than it is to write one character at a time.

Example: 
-- write AZ to the top left of the screen
-- (attributes are platform-dependent)
put_screen_char(1, 1, {'A', 152, 'Z', 131})
See Also: get_screen_char, display_text_image

puts

Syntax: puts(fn, x)
Description: Output, to file or device fn, a single byte (atom) or sequence of bytes. The low order 8-bits of each value is actually sent out. If fn is the screen you will see text characters displayed.
Comments: When you output a sequence of bytes it must not have any (sub)sequences within it. It must be a sequence of atoms only. (Typically a string of ASCII codes).

Avoid outputting 0's to the screen or to standard output. Your output might get truncated.

Remember that if the output file was opened in text mode, DOS and Windows will change \n (10) to \r\n (13 10). Open the file in binary mode if this is not what you want.

Example 1: 
puts(SCREEN, "Enter your first name: ")
Example 2: 
puts(output, 'A')  -- the single byte 65 will be sent to output
See Also: printf, gets, open

rand

Syntax: x2 = rand(x1)
Description: Return a random integer from 1 to x1, where x1 may be from 1 to the largest positive value of type integer (1073741823).
Comments: This function may be applied to an atom or to all elements of a sequence.
Example: 
s = rand({10, 20, 30})
-- s might be: {5, 17, 23} or {9, 3, 12} etc.
See Also: set_rand

read_bitmap

Syntax: include image.e
x = read_bitmap(st)
Description: st is the name of a .bmp "bitmap" file. The file should be in the bitmap format. The most common variations of the format are supported. If the file is read successfully the result will be a 2-element sequence. The first element is the palette, containing intensity values in the range 0 to 255. The second element is a 2-d sequence of sequences containing a pixel-graphics image. You can pass the palette to all_palette() (after dividing it by 4 to scale it). The image can be passed to display_image().

Bitmaps of 2, 4, 16 or 256 colors are supported. If the file is not in a good format, an error code (atom) is returned instead: 

    global constant BMP_OPEN_FAILED = 1,
                 BMP_UNEXPECTED_EOF = 2,
             BMP_UNSUPPORTED_FORMAT = 3
Comments: You can create your own bitmap picture files using Windows Paintbrush and many other graphics programs. You can then incorporate these pictures into your Euphoria programs.
Example: 
x = read_bitmap("c:\\windows\\arcade.bmp")
-- note: double backslash needed to get single backslash in
-- a string
Example Program: demo\dos32\bitmap.ex
See Also: palette, all_palette, display_image, save_bitmap

register_block

Syntax: include machine.e (or safe.e)
register_block(a, i)
Description: Add a block of memory to the list of safe blocks maintained by safe.e (the debug version of machine.e). The block starts at address a. The length of the block is i bytes.
Comments: This routine is only meant to be used for debugging purposes. safe.e tracks the blocks of memory that your program is allowed to peek(), poke(), mem_copy() etc. These are normally just the blocks that you have allocated using Euphoria's allocate() or allocate_low() routines, and which you have not yet freed using Euphoria's free() or free_low(). In some cases, you may acquire additional, external, blocks of memory, perhaps as a result of calling a C routine. If you are debugging your program using safe.e, you must register these external blocks of memory or safe.e will prevent you from accessing them. When you are finished using an external block you can unregister it using unregister_block().

When you include machine.e, you'll get different versions of register_block() and unregister_block() that do nothing. This makes it easy to switch back and forth between debug and non-debug runs of your program.

Example 1: 
atom addr

addr = c_func(x, {})
register_block(addr, 5)
poke(addr, "ABCDE")
unregister_block(addr)
See Also: unregister_block, safe.e

remainder

Syntax: x3 = remainder(x1, x2)
Description: Compute the remainder after dividing x1 by x2. The result will have the same sign as x1, and the magnitude of the result will be less than the magnitude of x2.
Comments: The arguments to this function may be atoms or sequences. The rules for operations on sequences apply.
Example 1: 
a = remainder(9, 4)
-- a is 1
Example 2: 
s = remainder({81, -3.5, -9, 5.5}, {8, -1.7, 2, -4})
-- s is {1, -0.1, -1, 1.5}
Example 3: 
s = remainder({17, 12, 34}, 16)
-- s is {1, 12, 2}
Example 4: 
s = remainder(16, {2, 3, 5})
-- s is {0, 1, 1}
See Also: floor

repeat

Syntax: s = repeat(x, a)
Description: Create a sequence of length a where each element is x.
Comments: When you repeat a sequence or a floating-point number the interpreter does not actually make multiple copies in memory. Rather, a single copy is "pointed to" a number of times.
Example 1: 
repeat(0, 10)      -- {0,0,0,0,0,0,0,0,0,0}
Example 2: 
repeat("JOHN", 4)  -- {"JOHN", "JOHN", "JOHN", "JOHN"}
-- The interpreter will create only one copy of "JOHN"
-- in memory
See Also: append, prepend, sequence-formation operator

reverse

Syntax: include misc.e
s2 = reverse(s1)
Description: Reverse the order of elements in a sequence.
Comments: A new sequence is created where the top-level elements appear in reverse order compared to the original sequence.
Example 1: 
reverse({1,3,5,7})          -- {7,5,3,1}
Example 2: 
reverse({{1,2,3}, {4,5,6}}) -- {{4,5,6}, {1,2,3}}
Example 3: 
reverse({99})               -- {99}
Example 4: 
reverse({})                 -- {}
See Also: append, prepend, repeat

routine_id

Syntax: i = routine_id(st)
Description: Return an integer id number, known as a routine id, for a user-defined Euphoria procedure or function. The name of the procedure or function is given by the string sequence st. -1 is returned if the named routine can't be found.
Comments: The id number can be passed to call_proc() or call_func(), to indirectly call the routine named by st.

The routine named by st must be visible, i.e. callable, at the place where routine_id() is used to get the id number. Indirect calls to the routine can appear earlier in the program than the definition of the routine, but the id number can only be obtained in code that comes after the definition of the routine - see example 2 below.

Once obtained, a valid routine id can be used at any place in the program to call a routine indirectly via call_proc()/call_func().

Some typical uses of routine_id() are:

1. Calling a routine that is defined later in a program.
2. Creating a subroutine that takes another routine as a parameter. (See Example 2 below)
3. Using a sequence of routine id's to make a case (switch) statement.
4. Setting up an Object-Oriented system.
5. Getting a routine id so you can pass it to call_back(). (See platform.doc)

Note that C routines, callable by Euphoria, also have routine id's. See define_c_proc() and define_c_func().

Example 1: 
procedure foo()
    puts(1, "Hello World\n")
end procedure

integer foo_num
foo_num = routine_id("foo")

call_proc(foo_num, {})  -- same as calling foo()
Example 2: 
function apply_to_all(sequence s, integer f)
    -- apply a function to all elements of a sequence
    sequence result
    result = {}
    for i = 1 to length(s) do
        -- we can call add1() here although it comes later in the program
        result = append(result, call_func(f, {s[i]}))
    end for
    return result
end function

function add1(atom x)
    return x + 1
end function

-- add1() is visible here, so we can ask for its routine id
? apply_to_all({1, 2, 3}, routine_id("add1"))
-- displays {2,3,4}
See Also: call_proc, call_func, call_back, define_c_func, define_c_proc, platform.doc

 

... continue
 
from A to B   |   from C to D   |   from E to G   |   from H to O   |   from P to R   |   from S to T   |   from U to Z