ellipse

Platform: | DOS32
Syntax: | include graphics.e ellipse(i1, i2, s1, s2)
Description: | Draw an ellipse with color i1 on a pixel-graphics screen. The ellipse will neatly fit inside the rectangle defined by diagonal points s1 {x1, y1} and s2 {x2, y2}. If the rectangle is a square then the ellipse will be a circle. Fill the ellipse when i2 is 1. Don't fill when i2 is 0.
Example: |
    ellipse(MAGENTA, 0, {10, 10}, {20, 20})

    -- This would make a magenta colored circle just fitting
    -- inside the square:
    --        {10, 10}, {10, 20}, {20, 20}, {20, 10}.
Example Program: | demo\dos32\sb.ex
See Also: | polygon, draw_line

equal

Syntax: | i = equal(x1, x2)
Description: | Compare two Euphoria objects to see if they are the same. Return 1 (true) if they are the same. Return 0 (false) if they are different.
Comments: | This is equivalent to the expression: compare(x1, x2) = 0 This routine, like most other built-in routines, is very fast. It does not have any subroutine call overhead.
Example 1: |
    if equal(PI, 3.14) then
        puts(1, "give me a better value for PI!\n")
    end if
Example 2: |
    if equal(name, "George") or equal(name, "GEORGE") then
        puts(1, "name is George\n")
    end if
See Also: | compare, equals operator (=)

find

Syntax: | i = find(x, s)
Description: | Find x as an element of s. If successful, return the index of the first element of s that matches. If unsuccessful return 0.
Example 1: |
    location = find(11, {5, 8, 11, 2, 3})
    -- location is set to 3
Example 2: |
    names = {"fred", "rob", "george", "mary", ""}
    location = find("mary", names)
    -- location is set to 4
See Also: | find_from, match, match_from, compare

find_from

Syntax: | i1 = find_from(x, s, i2)
Description: | Find x as an element of s. Start the search at index i2. If successful, return the index of the first element of s that matches. If unsuccessful return 0. i2 may have any value from 1 to the length of s plus 1. (Analogous to the first index of a slice of s).
Example 1: |
    location = find_from(11, {11, 8, 11, 2, 3}, 2)
    -- location is set to 3
Example 2: |
    names = {"mary", "rob", "george", "mary", ""}
    location = find_from("mary", names, 3)
    -- location is set to 4
See Also: | find, match, match_from, compare

float32_to_atom

Syntax: | include machine.e a1 = float32_to_atom(s)
Description: | Convert a sequence of 4 bytes to an atom. These 4 bytes must contain an IEEE floating-point number in 32-bit format.
Comments: | Any 32-bit IEEE floating-point number can be converted to an atom.
Example: |
    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, atom_to_float32

float64_to_atom

Syntax: | include machine.e a1 = float64_to_atom(s)
Description: | Convert a sequence of 8 bytes to an atom. These 8 bytes must contain an IEEE floating-point number in 64-bit format.
Comments: | Any 64-bit IEEE floating-point number can be converted to an atom.
Example: |
    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, atom_to_float64

floor

Syntax: | x2 = floor(x1)
Description: | Return the greatest integer less than or equal to x1. (Round down to an integer.)
Comments: | This function may be applied to an atom or to all elements of a sequence.
Example: |
    y = floor({0.5, -1.6, 9.99, 100})
    -- y is {0, -2, 9, 100}
See Also: | remainder

flush

Syntax: | include file.e flush(fn)
Description: | When you write data to a file, Euphoria normally stores the data in a memory buffer until a large enough chunk of data has accumulated. This large chunk can then be written to disk very efficiently. Sometimes you may want to force, or flush, all data out immediately, even if the memory buffer is not full. To do this you must call flush(fn), where fn is the file number of a file open for writing or appending.
Comments: | When a file is closed, (see close()), all buffered data is flushed out. When a program terminates, all open files are flushed and closed automatically. Use flush() when another process may need to see all of the data written so far, but you aren't ready to close the file yet.
Example: |
    f = open("logfile", "w")
    puts(f, "Record#1\n")
    puts(1, "Press Enter when ready\n")

    flush(f)  -- This forces "Record #1" into "logfile" on disk.
              -- Without this, "logfile" will appear to have
              -- 0 characters when we stop for keyboard input.

    s = gets(0) -- wait for keyboard input
See Also: | close, lock_file

free

Syntax: | include machine.e free(a)
Description: | Free up a previously allocated block of memory by specifying the address of the start of the block, i.e. the address that was returned by allocate().
Comments: | Use free() to recycle blocks of memory during execution. This will reduce the chance of running out of memory or getting into excessive virtual memory swapping to disk. Do not reference a block of memory that has been freed. When your program terminates, all allocated memory will be returned to the system. Do not use free() to deallocate memory that was allocated using allocate_low(). Use free_low() for this purpose.
Example Program: | demo\callmach.ex
See Also: | allocate, free_low

free_console

Platform: | WIN32, Linux, FreeBSD
Syntax: | include dll.e free_console()
Description: | Free (delete) any console window associated with your program.
Comments: | Euphoria will create a console text window for your program the first time that your program prints something to the screen, reads something from the keyboard, or in some way needs a console (similar to a DOS-prompt window). On WIN32 this window will automatically disappear when your program terminates, but you can call free_console() to make it disappear sooner. On Linux or FreeBSD, the text mode console is always there, but an xterm window will disappear after Euphoria issues a "Press Enter" prompt at the end of execution. On Linux or FreeBSD, free_console() will set the terminal parameters back to normal, undoing the effect that curses has on the screen. In a Linux or FreeBSD xterm window, a call to free_console(), without any further printing to the screen or reading from the keyboard, will eliminate the "Press Enter" prompt that Euphoria normally issues at the end of execution. After freeing the console window, you can create a new console window by printing something to the screen, or simply calling clear_screen(), position() or any other routine that needs a console. When you use the trace facility, or when your program has an error, Euphoria will automatically create a console window to display trace information, error messages etc. There's a WIN32 API routine, FreeConsole() that does something similar to free_console(). You should use free_console(), because it lets the interpreter know that there is no longer a console.
See Also: | clear_screen, platform.doc

free_low

Platform: | DOS32
Syntax: | include machine.e free_low(i)
Description: | Free up a previously allocated block of conventional memory by specifying the address of the start of the block, i.e. the address that was returned by allocate_low().
Comments: | Use free_low() to recycle blocks of conventional memory during execution. This will reduce the chance of running out of conventional memory. Do not reference a block of memory that has been freed. When your program terminates, all allocated memory will be returned to the system. Do not use free_low() to deallocate memory that was allocated using allocate(). Use free() for this purpose.
Example Program: | demo\dos32\dosint.ex
See Also: | allocate_low, dos_interrupt, free

get

Syntax: | include get.e s = get(fn)
Description: | Input, from file fn, a human-readable string of characters representing a Euphoria object. Convert the string into the numeric value of that object. s will be a 2-element sequence: {error status, value}. Error status codes are:
        GET_SUCCESS -- object was read successfully
        GET_EOF     -- end of file before object was read
        GET_FAIL    -- object is not syntactically correct
| get() can read arbitrarily complicated Euphoria objects. You could have a long sequence of values in braces and separated by commas, e.g. {23, {49, 57}, 0.5, -1, 99, 'A', "john"}. A single call to get() will read in this entire sequence and return it's value as a result. Each call to get() picks up where the previous call left off. For instance, a series of 5 calls to get() would be needed to read in: 99 5.2 {1,2,3} "Hello" -1 On the sixth and any subsequent call to get() you would see a GET_EOF status. If you had something like: {1, 2, xxx} in the input stream you would see a GET_FAIL error status because xxx is not a Euphoria object. Multiple "top-level" objects in the input stream must be separated from each other with one or more "whitespace" characters (blank, tab, \r or \n). Whitespace is not necessary within a top-level object. A call to get() will read one entire top-level object, plus one additional (whitespace) character.
Comments: | The combination of print() and get() can be used to save a Euphoria object to disk and later read it back. This technique could be used to implement a database as one or more large Euphoria sequences stored in disk files. The sequences could be read into memory, updated and then written back to disk after each series of transactions is complete. Remember to write out a whitespace character (using puts()) after each call to print(). The value returned is not meaningful unless you have a GET_SUCCESS status.
Example: | Suppose your program asks the user to enter a number from the keyboard.
    -- If he types 77.5, get(0) would return:

    {GET_SUCCESS, 77.5}

    -- whereas gets(0) would return:

    "77.5\n"
Example Program: | demo\mydata.ex
See Also: | print, value, gets, getc, prompt_number, prompt_string

get_active_page

Platform: | DOS32
Syntax: | include image.e i = get_active_page()
Description: | Some graphics modes on most video cards have multiple pages of memory. This lets you write screen output to one page while displaying a different page. get_active_page() returns the current page number that screen output is being sent to.
Comments: | The active and display pages are both 0 by default. video_config() will tell you how many pages are available in the current graphics mode.
See Also: | set_active_page, get_display_page, video_config

get_all_palette

Platform: | DOS32
Syntax: | include image.e s = get_all_palette()
Description: | Retrieve 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 color intensity {red, green, blue} for the corresponding color number, starting with color number 0. The values for red, green and blue will be in the range 0 to 63.
Comments: | This function might be used to get the palette values needed by save_bitmap(). Remember to multiply these values by 4 before calling save_bitmap(), since save_bitmap() expects values in the range 0 to 255.
See Also: | palette, all_palette, read_bitmap, save_bitmap, save_screen

get_bytes

Syntax: | include get.e s = get_bytes(fn, i)
Description: | Read the next i bytes from file number fn. Return the bytes as a sequence. The sequence will be of length i, except when there are fewer than i bytes remaining to be read in the file.
Comments: | When i > 0 and length(s) < i you know you've reached the end of file. Eventually, an empty sequence will be returned for s. This function is normally used with files opened in binary mode, "rb". This avoids the confusing situation in text mode where DOS will convert CR LF pairs to LF.
Example: |
    include get.e

    integer fn
    fn = open("temp", "rb")  -- an existing file

    sequence whole_file
    whole_file = {}

    sequence chunk

    while 1 do
        chunk = get_bytes(fn, 100) -- read 100 bytes at a time
        whole_file &= chunk        -- chunk might be empty, that's ok
        if length(chunk) < 100 then
            exit
        end if
    end while

    close(fn)
    ? length(whole_file)  -- should match DIR size of "temp"
See Also: | getc, gets

get_display_page

Platform: | DOS32
Syntax: | include image.e i = get_display_page()
Description: | Some graphics modes on most video cards have multiple pages of memory. This lets you write screen output to one page while displaying another. get_display_page() returns the current page number that is being displayed on the monitor.
Comments: | The active and display pages are both 0 by default. video_config() will tell you how many pages are available in the current graphics mode.
See Also: | set_display_page, get_active_page, video_config

get_key

Syntax: | i = get_key()
Description: | Return the key that was pressed by the user, without waiting. Return -1 if no key was pressed. Special codes are returned for the function keys, arrow keys etc.
Comments: | The operating system can hold a small number of key-hits in its keyboard buffer. get_key() will return the next one from the buffer, or -1 if the buffer is empty. Run the key.bat program to see what key code is generated for each key on your keyboard.
See Also: | wait_key, getc

get_mouse

Platform: | DOS32, Linux
Syntax: | include mouse.e x1 = get_mouse()
Description: | Return the last mouse event in the form: {event, x, y} or return -1 if there has not been a mouse event since the last time get_mouse() was called. Constants have been defined in mouse.e for the possible mouse events:
        global constant MOVE = 1,
                   LEFT_DOWN = 2,
                     LEFT_UP = 4,
                  RIGHT_DOWN = 8,
                    RIGHT_UP = 16,
                 MIDDLE_DOWN = 32,
                   MIDDLE_UP = 64
| x and y are the coordinates of the mouse pointer at the time that the event occurred. get_mouse() returns immediately with either a -1 or a mouse event. It does not wait for an event to occur. You must check it frequently enough to avoid missing an event. When the next event occurs, the current event will be lost, if you haven't read it. In practice it is not hard to catch almost all events. Losing a MOVE event is generally not too serious, as the next MOVE will tell you where the mouse pointer is. Sometimes multiple events will be reported. For example, if the mouse is moving when the left button is clicked, get_mouse() will report an event value of LEFT_DOWN+MOVE, i.e. 2+1 or 3. For this reason you should test for a particular event using and_bits(). See examples below.
Comments: | In pixel-graphics modes that are 320 pixels wide, you need to divide the x value by 2 to get the correct position on the screen. (A strange feature of DOS.) In DOS32 text modes you need to scale the x and y coordinates to get line and column positions. In Linux, no scaling is required - x and y correspond to the line and column on the screen, with (1,1) at the top left. In DOS32, you need a DOS mouse driver to use this routine. In Linux, GPM Server must be running. In Linux, mouse movement events are not reported in an xterm window, only in the text console. In Linux, LEFT_UP, RIGHT_UP and MIDDLE_UP are not distinguishable from one another. You can use get_mouse() in most text and pixel-graphics modes. The first call that you make to get_mouse() will turn on a mouse pointer, or a highlighted character. DOS generally does not support the use of a mouse in SVGA graphics modes (beyond 640x480 pixels). This restriction has been removed in Windows 95 (DOS 7.0). Graeme Burke, Peter Blue and others have contributed mouse routines that get around the problems with using a mouse in SVGA. See the Euphoria Archive Web page. The x,y coordinate returned could be that of the very tip of the mouse pointer or might refer to the pixel pointed-to by the mouse pointer. Test this if you are trying to read the pixel color using get_pixel(). You may have to read x-1,y-1 instead.
Example 1: | a return value of:
    {2, 100, 50}
| would indicate that the left button was pressed down when the mouse pointer was at location x=100, y=50 on the screen.
Example 2: | To test for LEFT_DOWN, write something like the following:
    object event

    while 1 do
        event = get_mouse()
        if sequence(event) then
            if and_bits(event[1], LEFT_DOWN) then
                -- left button was pressed
                exit
            end if
        end if
    end while
See Also: | mouse_events, mouse_pointer, and_bits

get_pixel

Platform: | DOS32
Syntax: | x = get_pixel(s)
Description: | When s is a 2-element screen coordinate {x, y}, get_pixel() returns the color (a small integer) of the pixel on the pixel-graphics screen at that point. When s is a 3-element sequence of the form: {x, y, n} get_pixel() returns a sequence of n colors for the points starting at {x, y} and moving to the right {x+1, y}, {x+2, y} etc. Points off the screen have unpredictable color values.
Comments: | When n is specified, a very fast algorithm is used to read the pixel colors on the screen. It is much faster to call get_pixel() once, specifying a large value of n, than it is to call it many times, reading one pixel color at a time.
Example: |
    object x

    x = get_pixel({30,40})
    -- x is set to the color value of point x=30, y=40

    x = get_pixel({30,40,100})
    -- x is set to a sequence of 100 integer values, representing
    -- the colors starting at {30,40} and going to the right
See Also: | pixel, graphics_mode, get_position

get_position

Syntax: | include graphics.e s = get_position()
Description: | Return the current line and column position of the cursor as a 2-element sequence {line, column}.
Comments: | get_position() works in both text and pixel-graphics modes. In pixel-graphics modes no cursor will be displayed, but get_position() will return the line and column where the next character will be displayed. 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. get_position() returns the current line and column for the text that you are displaying, not the pixels that you may be plotting. There is no corresponding routine for getting the current pixel position.
See Also: | position, get_pixel

get_screen_char

Syntax: | include image.e s = get_screen_char(i1, i2)
Description: | Return a 2-element sequence s, of the form {ascii-code, attributes} for the character on the screen at line i1, column i2. s consists of two atoms. The first is the ASCII code for the character. The second is an atom that contains the foreground and background color of the character, and possibly other information describing the appearance of the character on the screen.
Comments: | With get_screen_char() and put_screen_char() you can save and restore a character on the screen along with its attributes.
Example: |
    -- read character and attributes at top left corner
    s = get_screen_char(1,1)
    -- store character and attributes at line 25, column 10
    put_screen_char(25, 10, {s})
See Also: | put_screen_char, save_text_image

get_vector

Platform: | DOS32
Syntax: | include machine.e s = get_vector(i)
Description: | Return the current protected mode far address of the handler for interrupt number i. s will be a 2-element sequence: {16-bit segment, 32-bit offset}.
Example: |
    s = get_vector(#1C)
    -- s will be set to the far address of the clock tick
    -- interrupt handler, for example: {59, 808}
Example Program: | demo\dos32\hardint.ex
See Also: | set_vector, lock_memory

getc

Syntax: | i = getc(fn)
Description: | Get the next character (byte) from file or device fn. The character will have a value from 0 to 255. -1 is returned at end of file.
Comments: | File input using getc() is buffered, i.e. getc() does not actually go out to the disk for each character. Instead, a large block of characters will be read in at one time and returned to you one by one from a memory buffer. When getc() reads from the keyboard, it will not see any characters until the user presses Enter. Note that the user can type control-Z, which the operating system treats as "end of file". -1 will be returned.
See Also: | gets, get_key, wait_key, open

getenv

Syntax: | x = getenv(s)
Description: | Return the value of an environment variable. If the variable is undefined, return -1.
Comments: | Because either a sequence or an atom (-1) might be returned, you should probably assign the result to a variable declared as object. Both the argument and the return value, may, or may not be, case sensitive. You might need to test this on your system.
Example: |
    e = getenv("EUDIR")
    -- e will be "C:\EUPHORIA" -- or perhaps D:, E: etc.
See Also: | command_line

gets

Syntax: | x = gets(fn)
Description: | Get the next sequence (one line, including '\n') of characters from file or device fn. The characters will have values from 0 to 255. The atom -1 is returned on end of file.
Comments: | Because either a sequence or an atom (-1) might be returned, you should probably assign the result to a variable declared as object. After reading a line of text from the keyboard, you should normally output a \n character, e.g. puts(1, '\n'), before printing something. Only on the last line of the screen does the operating system automatically scroll the screen and advance to the next line. The last line in a file might not end with a new-line '\n' character. When your program reads from the keyboard, the user can type control-Z, which the operating system treats as "end of file". -1 will be returned. In SVGA modes, DOS might set the wrong cursor position, after a call to gets(0) to read the keyboard. You should set it yourself using position().
Example 1: |
    sequence buffer
    object line
    integer fn

    -- read a text file into a sequence
    fn = open("myfile.txt", "r")
    if fn = -1 then
        puts(1, "Couldn't open myfile.txt\n")
        abort(1)
    end if

    buffer = {}
    while 1 do
        line = gets(fn)
        if atom(line) then
            exit   -- -1 is returned at end of file
        end if
        buffer = append(buffer, line)
    end while
Example 2: |
    object line

    puts(1, "What is your name?\n")
    line = gets(0)  -- read standard input (keyboard)
    line = line[1..length(line)-1] -- get rid of \n character at end
    puts(1, '\n')   -- necessary
    puts(1, line & " is a nice name.\n")
See Also: | getc, puts, open

graphics_mode

Platform: | DOS32
Syntax: | include graphics.e i1 = graphics_mode(i2)
Description: | Select graphics mode i2. See graphics.e for a list of valid graphics modes. If successful, i1 is set to 0, otherwise i1 is set to 1.
Comments: | Some modes are referred to as text modes because they only let you display text. Other modes are referred to as pixel-graphics modes because you can display pixels, lines, ellipses etc., as well as text. As a convenience to your users, it is usually a good idea to switch back from a pixel-graphics mode to the standard text mode before your program terminates. You can do this with graphics_mode(-1). If a pixel-graphics program leaves your screen in a mess, you can clear it up with the DOS CLS command, or by running ex or ed. Some graphics cards will be unable to enter some SVGA modes, under some conditions. You can't always tell from the i1 value, whether the graphics mode was set up successfully. On the WIN32 and Linux/FreeBSD platforms, graphics_mode() will allocate a plain, text mode console if one does not exist yet. It will then return 0, no matter what value is passed as i2.
Example: |
    if graphics_mode(18) then
        puts(SCREEN, "need VGA graphics!\n")
        abort(1)
    end if
    draw_line(BLUE, {{0,0}, {50,50}})
See Also: | text_rows, video_config

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