PC Consument 1998 January/PCC11998.bin/demos/euphor.exe/LIBRARY.DOC

Text File | 1997-03-20 | 123.8 KB | 3,245 lines

            Part II - Library Routines

 1. Introduction

 A large number of library routines are provided. Some are built right into
 the interpreter, ex.exe. Others are written in Euphoria and you must include
 one of the .e files in euphoria\include to use them. Where this is the case,
 the appropriate include file is noted in the "Syntax" part of the description.
 Of course an include file need only be included once in your program. The
 editor displays in magenta those routines that are built into the interpreter,
 ex.exe, and require no include file. You can override the definition of these
 built-in routines by defining your own routine with the same name. You will
 get a suppressible warning if you do this.

 To indicate what kind of object may be passed in and returned, the following
 prefixes are used:

   x - a general object (atom or sequence)
   s - a sequence
   a - an atom
   i - an integer
  fn - an integer used as a file number
  st - a string sequence, or single-character atom

 An error will result if an illegal argument value is passed to any of these
 routines.


 2. Routines by Application Area

 2.1  Predefined Types

      As well as declaring variables with these types, you can also call them
      just like ordinary functions, in order to test if a value is a certain
      type.

      integer     - test if an object is an integer
      atom        - test if an object is an atom
      sequence     - test if an object is a sequence

 2.2  Sequence Manipulation

      length     - return the length of a sequence
      repeat     - repeat an object n times to form a sequence of length n
      append     - add a new element to the end of a sequence
      prepend     - add a new element to the beginning of a sequence

 2.3  Searching and Sorting

      compare     - compare two objects
      find        - find an object in a sequence
      match       - find a sequence as a slice of another sequence
      sort        - sort the elements of a sequence into ascending order

 2.4  Pattern Matching

      lower     - convert an atom or sequence to lower case
      upper     - convert an atom or sequence to upper case
      wildcard_match - match a pattern containing ? and * wildcards
      wildcard_file  - match a file name against a wild card specification

 2.5  Math

      These routines can be applied to individual atoms or to sequences of
      values. See "Operations on Sequences" in chapter 2 of REFMAN.DOC.

      sqrt    - calculate the square root of an object
      rand    - generate random numbers
      sin    - calculate the sine of an angle
      cos    - calculate the cosine of an angle
      tan    - calculate the tangent of an angle
      arctan    - calculate the arc tangent of a number
      log    - calculate the natural logarithm
      floor    - round down to the nearest integer
      remainder    - calculate the remainder when a number is divided by another
      power    - calculate a number raised to a power

 2.6  Bitwise Logical Operations

      These routines treat numbers as collections of binary bits,
      and logical operations are performed on corresponding
      bits in the binary representation of the numbers. There are
      no routines for shifting bits left or right, but you can
      achieve the same effect by multiplying or dividing by
      powers of 2.

      and_bits  - perform logical AND on corresponding bits
      or_bits   - perform logical OR on corresponding bits
      xor_bits  - perform logical XOR on corresponding bits
      not_bits  - perform logical NOT on all bits

 2.7  File and Device I/O

      To do input or output on a file or device you must first open the file
      or device, then use the routines below to read or write to it, then close
      the file or device. open() will give you a file number to use as the
      first argument of the other I/O routines. Certain files/devices are
      opened for you automatically (as text files):

         0 - standard input
         1 - standard output
         2 - standard error

      Unless you redirect them on the command line, standard input comes from
      the keyboard, standard output and standard error go to the screen. When
      you write something to the screen it is written immediately without
      buffering. If you write to a file, your characters are put into a buffer
      until there are enough of them to write out efficiently. When you close
      the file or device, any remaining characters are written out. Input from
      files is also buffered. When your program terminates, any files that are
      still open will be closed for you automatically.

      Note: If a program (written in Euphoria or any other language) has a
      file open for writing, and you are forced to reboot your computer for
      any reason, you should immediately run CHKDSK or SCANDISK to repair any
      damage to the file system that may have occurred.

      open    - open a file or device
      close    - close a file or device
      print    - print a Euphoria object with {,,} to show the structure
      ? x    - shorthand for print(1, x)
      printf    - formatted print to a file or device
      sprintf   - formatted print returned as a string sequence
      puts    - output a string sequence to a file or device
      getc    - read the next character from a file or device
      gets    - read the next line from a file or device
      get_key    - check for key pressed by the user, don't wait
      wait_key  - wait for user to press a key
      get    - read the representation of any Euphoria object from a file
      value    - read the representation of any Euphoria object from a string
      seek    - move to any character position within an open file
      where    - report the current character position in an open file
      current_dir - return the name of the current directory
      dir      - return complete info on all files in a directory
      allow_break - allow control-C/control-Break to terminate your program
                    or not
      check_break - check if user has pressed control-C or control-Break

 2.8  Mouse Support

      get_mouse        - return mouse "events" (clicks, movements)
      mouse_events  - select mouse events to watch for
      mouse_pointer - display or hide the mouse pointer

 2.9  Operating System

      time       - number of seconds since a fixed point in the past
      tick_rate    - set the number of clock ticks per second
      date       - current year, month, day, hour, minute, second etc.
      command_line - DOS command-line used to run this program
      getenv       - get value of an environment variable
      system       - execute a DOS command line
      abort       - terminate execution

 2.10 Special Machine-dependent routines

      machine_func - specialized operations in ex.exe with return value
      machine_proc - specialized operations in ex.exe - no return value

 2.11 Debugging

      trace    - dynamically turns tracing on or off

 2.12 Graphics & Sound

      The following routines let you display information on the screen. The
      PC screen can be placed into one of many graphics modes. See the top
      of include\graphics.e for a description of the modes. There are two
      basic types of graphics mode available. "Text" modes divide the screen
      up into lines, where each line has a certain number of characters.
      "Pixel-graphics" modes divide the screen up into many rows of dots,
      or "pixels". Each pixel can be a different color. In text modes you can
      display text only, with the choice of a foreground and a background
      color for each character. In pixel-graphics modes you can display lines,
      circles, dots, and also text.

      We've also included a routine for making sound on your PC speaker.
      To make more sophisticated sounds, get the Sound Blaster library
      developed by Jacques Deschenes. It's available on the Euphoria
      Web page.

      The following routines work in all text and pixel-graphics modes:

        clear_screen     - clear the screen
        position     - set cursor line and column
        get_position     - return cursor line and column
        graphics_mode    - select a new pixel-graphics or text mode
        video_config     - return parameters of current mode
        scroll             - scroll text up or down
        wrap             - control line wrap at right edge of screen
        text_color       - set foreground text color
        bk_color         - set background color
        palette             - change color for one color number
        all_palette      - change color for all color numbers
        get_all_palette  - get the palette values for all colors
        read_bitmap      - read a bitmap (.BMP) file and return a palette and
                           a 2-d sequence of pixels
        save_bitmap      - create a bitmap (.BMP) file, given a palette and
                           a 2-d sequence of pixels
        get_active_page  - return the page currently being written to
        set_active_page  - change the page currently being written to
        get_display_page - return the page currently being displayed
        set_display_page - change the page currently being displayed
        sound             - make a sound on the PC speaker

      The following routines work in text modes only:

        cursor               - select cursor shape
        text_rows       - set number of lines on text screen
        save_text_image    - save a rectangular region from a text screen
        display_text_image - display an image on the text screen

      The following routines work in pixel-graphics modes only.

        pixel          - set color of a pixel or set of pixels
        get_pixel     - read color of a pixel or set of pixels
        draw_line     - connect a series of graphics points with a line
        polygon          - draw an n-sided figure
        ellipse          - draw an ellipse or circle
        save_screen   - save the screen to a bitmap (.BMP) file
        save_image    - save a rectangular region from a pixel-graphics screen
        display_image - display an image on the pixel-graphics screen

 2.13 Machine Level Interface

      We've grouped here a number of routines that you can use to access your
      machine at a low-level. With this low-level machine interface you can
      read and write to memory. You can also set up your own 386+ machine
      language routines and call them.

      Some of the routines listed below are unsafe, in the sense that Euphoria
      can't protect you if you use them incorrectly. You could crash your
      program or even your system. If you reference a bad memory address it
      will often be safely caught by the Causeway DOS extender, and you'll
      get an error message on the screen plus a dump of machine-level
      information in the file CW.ERR.

      These routines are important because they allow Euphoria programmers
      to access low-level features of the hardware and operating system.
      For those with specialized applications this could be crucial.

      Machine code routines can be written by hand, or taken from the
      disassembled output of a compiler for C or some other language.
      Remember that your machine code will be running in 32-bit protected
      mode. See demo\callmach.ex for an example.

      peek           - read one or more bytes from memory
      poke          - write one or more bytes to memory
      mem_copy        - copy a block of memory
      mem_set         - set a block of memory to a value
      call          - call a machine language routine
      dos_interrupt   - call a DOS software interrupt routine
      allocate          - allocate a block of memory
      free          - deallocate a block of memory
      allocate_low    - allocate a block of low memory (address less than 1Mb)
      free_low          - free a block allocated with allocate_low
      get_vector      - return address of interrupt handler
      set_vector      - set address of interrupt handler
      lock_memory     - ensure that a region of memory will never be swapped out
      int_to_bytes    - convert an integer to 4 bytes
      bytes_to_int    - convert 4 bytes to an integer
      int_to_bits     - convert an integer to a sequence of bits
      bits_to_int     - convert a sequence of bits to an integer
      atom_to_float64 - convert an atom, to a sequence of 8 bytes in IEEE
                        64-bit floating-point format
      atom_to_float32 - convert an atom, to a sequence of 4 bytes in IEEE
                        32-bit floating-point format
      float64_to_atom - convert a sequence of 8 bytes in IEEE 64-bit floating-
                        point format, to an atom
      float32_to_atom - convert a sequence of 4 bytes in IEEE 32-bit floating-
                        point format, to an atom
      set_rand          - set the random number generator so it will generate
                      a repeatable series of random numbers
      use_vesa        - force the use of the VESA graphics standard
      crash_message   - specify a message to be printed if Euphoria detects an
                      error in your program


 3. Alphabetical Listing of all Routines



──────────────────────────────────────<?>───────────────────────────────────────

 Syntax:      ? x

 Description: This is just a shorthand way of saying:  print(1, x)
           i.e. printing the value of an expression to the standard output.

 Example:
          ? {1, 2} + {3, 4}

          would display {4, 6}.

 Comments:    ? differs slightly from print() since it will add new-lines to
           make the output more readable on your screen or wherever you
           have directed standard output.

 See Also:    print

────────────────────────────────────<abort>─────────────────────────────────────

 Syntax:      abort(i)

 Description: Abort execution of the program. The argument i is an 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.

 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.

          Normally ex.exe returns 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

─────────────────────────────────<all_palette>──────────────────────────────────

 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\bitmap.ex

 See Also:    palette, read_bitmap, video_config, graphics_mode

───────────────────────────────────<allocate>───────────────────────────────────

 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.

 Example:     buffer = allocate(100)
           for i = 0 to 99 do
                 poke(buffer+i, 0)
           end for

 See Also:    free, allocate_low, peek, poke, call

─────────────────────────────────<allocate_low>─────────────────────────────────

 Syntax:      include machine.e
           i2 = allocate_low(i1)

 Description: Allocate i1 contiguous bytes of low memory, i.e. conventional
            memory with an address below 1 megabyte. Return the address
           of the block of memory, or return 0 if the memory can't be
           allocated.

 Comment:     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\dosint.ex

 See Also:    dos_interrupt, free_low, allocate, peek, poke

─────────────────────────────────<allow_break>──────────────────────────────────

 Syntax:      include machine.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:    The operating system will still 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. (See the MS-DOS 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

───────────────────────────────────<and_bits>───────────────────────────────────

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

────────────────────────────────────<append>────────────────────────────────────

 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 (&) and sequence-formation {,,} operators
           in refman.doc

────────────────────────────────────<arctan>────────────────────────────────────

 Syntax:      x2 = arctan(x1)

 Description: Return the arctangent of x1.

 Comments:    The result will always be in the range -pi/2 to +pi/2 radians.

              This function may be applied to an atom or to all elements
           of a sequence.

 Example:     s = arctan({1,2,3})
              -- s is {0.785398, 1.10715, 1.24905}

 See Also:    tan, sin, cos

─────────────────────────────────────<atom>─────────────────────────────────────

 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:
           line = gets(0)
           if atom(line) then
                puts(SCREEN, "end of file\n")
           end if

 See Also:    sequence

───────────────────────────────<atom_to_float32>────────────────────────────────

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

              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

───────────────────────────────<atom_to_float64>────────────────────────────────

 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_float32(157.82)) -- write 8 bytes to a file

 See Also:    atom_to_float32, float64_to_atom

─────────────────────────────────<bits_to_int>──────────────────────────────────

 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, and/or/not of sequences in refman.doc

───────────────────────────────────<bk_color>───────────────────────────────────

 Syntax:      include graphics.e
           bk_color(i)

 Description: Set the background color. 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.

 Comments:    The various 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 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

─────────────────────────────────<bytes_to_int>─────────────────────────────────

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

─────────────────────────────────────<call>─────────────────────────────────────

 Syntax:      call(a)

 Description: Call a machine language routine that starts at address a. This
          routine must execute a RET instruction #C3 to return control
          to Euphoria. The routine should save and restore any registers
          that it uses.

 Comments:    You can allocate a block of memory for the routine and then poke
            in the bytes of machine code. You might allocate other blocks of
            memory for data and parameters that the machine code can operate
            on. The addresses of these blocks could be poked into the
            machine code.

 Example Program: see demo\callmach.ex

 See Also:    allocate, free, peek, poke

─────────────────────────────────<check_break>──────────────────────────────────

 Syntax:      include machine.e
              i = check_break()

 Description: Return the number of times that control-c or control-break have
              been pressed since the last call to check_break(), or since the
              beginning of the program if this is the first call.

 Comments:    This is useful after you have called allow_break(0) which
              prevents control-c or control-break from terminating your
              program. You can use check_break() to find out if the user
              has pressed one of these keys. You might then perform some action
              such as a graceful shutdown of your program.

              Neither control-c nor control-break will be returned as input
              characters when you read the keyboard. You can only detect
              them by calling check_break().

 Example:
              k = get_key()
              if check_break() then
                  temp = graphics_mode(-1)
                  puts(1, "Shutting down...")
                  save_all_user_data()
                  abort(1)
              end if

 See Also: allow_break, get_key

─────────────────────────────────<clear_screen>─────────────────────────────────

 Syntax:      clear_screen()

 Description: Clear the screen using the current background color (may be set
           by bk_color()).

 Comments:    This works in all text and pixel-graphics modes.

 See Also:    bk_color, graphics_mode

────────────────────────────────────<close>─────────────────────────────────────

 Syntax:      close(fn)

 Description: Close a file or device and flush out any still-buffered
           characters.

 Comments:    Any still-open files will be closed automatically when your
           program terminates.

 See Also:    open

────────────────────────────────<command_line>──────────────────────────────────

 Syntax:      s = command_line()

 Description: Return a sequence of strings, where each string is a word from
           the command line that started your program. The first word will
           be the path to either the Euphoria executable, ex.exe or to
           your bound .exe file. The next word is either the name of your
           Euphoria .ex file, or the path to your bound .exe file. After
           that will come any extra words typed by the user. You can use
           these words in your program.

 Comments:    Euphoria (ex.exe) does not use any command line options. You
           are free to use any options for your own program.

           If you bind your program you will find that all command line
           arguments remain the same, except for the first two, even
           though your user no longer types "ex" (see examples below).

 Example 1:   -- The user types:  ex myprog myfile.dat 12345

           cmd = command_line()

           -- cmd will be:  {"C:\EUPHORIA\BIN\EX.EXE",
                       "myprog",
                       "myfile.dat",
                       "12345"}

 Example 2:   -- Your program is bound with the name "myprog.exe"
           -- and is stored in the directory c:\myfiles
           -- The user types:  myprog myfile.dat 12345

           cmd = command_line()

           -- cmd will be:  {"C:\MYFILES\MYPROG.EXE",
                       "C:\MYFILES\MYPROG.EXE", -- spacer
                       "myfile.dat",
                       "12345"}

          -- Note that all arguments remain the same as Example 1
          -- except for the first two. The second argument is always
          -- the same as the first and is inserted to keep the numbering
          -- of the subsequent arguments the same, whether your program
          -- is bound as a .exe or not.

 See Also:    getenv

───────────────────────────────────<compare>────────────────────────────────────

 Syntax:      i = compare(x1, x2)

 Description: Return 0 if objects x1 and x2 are identical, 1 if x1 is greater
          than x2, -1 if x1 is less than x2. Atoms are considered to be
          less than sequences. Sequences are compared "alphabetically"
          starting with the first element until a difference is found.

 Example 1:   x = compare({1,2,{3,{4}},5}, {2-1,1+1,{3,{4}},6-1})
           -- identical, x is 0

 Example 2:   if compare("ABC", "ABCD") < 0 then   -- -1
         -- will be true: ABC is "less" because it is shorter
           end if

 Example 3:   x = compare({12345, 99999, -1, 700, 2},
                          {12345, 99999, -1, 699, 3, 0})
              -- x will be 1 because 700 > 699

 See Also:    equals (=) operator in refman.doc

─────────────────────────────────────<cos>──────────────────────────────────────

 Syntax:      x2 = cos(x1)

 Description: Return the cosine of x1, where x1 is in radians.

 Comments:    This function may be applied to an atom or to all elements
           of a sequence.

 Example:     x = cos({.5, .6, .7})

           -- x is {0.8775826, 0.8253356, 0.7648422}

 See Also:    sin, tan, log, sqrt

────────────────────────────────<crash_message>─────────────────────────────────

 Syntax:      include machine.e
           crash_message(s)

 Description: Specify a string, s, to be printed on the screen in the event
           that Euphoria must stop your program due to a compile-time or
           run-time error.

 Comments:    Normally Euphoria prints a diagnostic message such as
           "syntax error" or "divide by zero" on the screen, as well as
           dumping debugging information into "ex.err". Euphoria's error
           messages will not be meaningful for your users unless they
           happen to be Euphoria programmers. By calling crash_message()
           you can control the message that will appear on the screen.
           Debugging information will still be stored in ex.err. You won't
           lose any information by doing this.

           s may contain '\n', new-line characters so your message can
           span several lines on the screen. Euphoria will switch to the
           top of a clear text-mode screen before printing your message.

           You can call crash_message() as many times as you like from
           different parts of your program. The message specified by the
           last call will be the one displayed.

           Your crash message will always be displayed if a compile-time
           error (syntax, undeclared variable etc.) occurs. In the case of
           a run-time error (subscript out of bounds, uninitialized
           variable, divide by zero etc.) your program must be executed
           by the Complete Edition EX.EXE, or have been bound using
           the Complete Edition PDEX.EXE, or be under 300 statements.

 Example:     crash_message("An unexpected error has occurred!\n" &
                 "Please contact [e-mail]\n" &
                 "Do not delete the file \"ex.err\".\n")

 See Also:    abort
           Debugging section of refman.doc

─────────────────────────────────<current_dir>──────────────────────────────────

 Syntax:      include file.e
           s = current_dir()

 Description: Return the name of the current working directory.

 Example:
           sequence s
           s = current_dir()
           -- s would have "C:\EUPHORIA\DOC" if you were in that directory

 See Also:    dir, getenv

────────────────────────────────────<cursor>────────────────────────────────────

 Syntax:      include graphics.e
           cursor(i)

 Description: Select a style of cursor. graphics.e contains:

        global constant NO_CURSOR      = #2000,
             UNDERLINE_CURSOR       = #0607,
             THICK_UNDERLINE_CURSOR = #0507,
             HALF_BLOCK_CURSOR      = #0407,
             BLOCK_CURSOR           = #0007

           The second and fourth hex digits (from the left) determine the
           top and bottom rows of pixels in the cursor. The first digit
           controls whether the cursor will be visible or not. For example,
           #0407 turns on the 4th through 7th rows.

 Comments:    In pixel-graphics modes there is no cursor.

 Example:     cursor(BLOCK_CURSOR)

─────────────────────────────────────<date>─────────────────────────────────────

 Syntax:      s = date()

 Description: Return a sequence with the following information:
         { year (since 1900),
           month (January = 1),
           day (day of month, starting at 1),
           hour (0 to 23),
           minute (0 to 59),
           second (0 to 59),
           day of the week (Sunday = 1),
           day of the year (January 1st = 1) }

 Example:     now = date()
           -- now has: {95,3,24,23,47,38,6,83}
           -- i.e. Friday March 24, 1995 at 11:47:38pm, day 83 of the year

 See Also:    time

─────────────────────────────────────<dir>──────────────────────────────────────

 Syntax:      include file.e
           x = dir(st)

 Description: Return directory information for the file or directory named by
            st. If there is no file or directory with this name then -1 is
            returned.

           This information is similar to what you would get from the DOS
           DIR command. A sequence is returned where each element is a
           sequence that describes one file or subdirectory.

          If st names a directory you may have entries for "." and "..",
          just as with the DOS DIR command. If st names a file then x will
          have just one entry, i.e. length(x) will be 1.

          Each entry contains the name, attributes and file size as well
          as the year, month, day, hour, minute and second of the last
          modification. You can refer to the elements of an entry with
          the following constants defined in file.e:

        global constant
            D_NAME = 1,
            D_ATTRIBUTES = 2,
            D_SIZE = 3,

            D_YEAR = 4,
            D_MONTH = 5,
            D_DAY = 6,

            D_HOUR = 7,
            D_MINUTE = 8,
            D_SECOND = 9

          The attributes element is a string sequence containing
          characters chosen from:

            d - directory
            r - read only file
            h - hidden file
            s - system file
            v - volume-id entry
            a - archive file

          A normal file without special attributes would just have an empty
          string, "", in this field.

 Comments:    The top level directory, e.g. c:\ does not have "." or ".."
          entries.

          This function is often used just to test if a file or
          directory exists.

          Under Windows 95, st can have a long file or directory name
          anywhere in the path.

          The file name returned in D_NAME will be a standard DOS 8.3 name,
          even on Windows 95 or Windows NT. A new long-filename element
          may be added in a future release of Euphoria.

 Example:
          d = dir(current_dir())

          -- d might have:
        {
             {".",    "d",     0  1994, 1, 18,  9, 30, 02},
             {"..",   "d",     0  1994, 1, 18,  9, 20, 14},
             {"fred", "ra", 2350, 1994, 1, 22, 17, 22, 40},
             {"sub",  "d" ,    0, 1993, 9, 20,  8, 50, 12}
        }

          d[3][D_NAME] would be "fred"

 Example Programs: bin\search.ex, install.ex

 See Also: wildcard_file, current_dir, open

────────────────────────────────<display_image>─────────────────────────────────

 Syntax:      include image.e
           display_image(s1, s2)

 Description: Display at point s1 on a pixel-graphics screen the 2-d sequence
              of pixels contained in s2. s1 is a two-element sequence {x, y}.
              s2 is a sequence of sequences, where each sequence is one
              horizontal line of pixel colors to be displayed. The first pixel
              of the first sequence is displayed at s1. It is the top-left
              pixel. All other pixels appear to the right or below of this
              point.

 Comments:    s2 might be the result of a previous call to save_image(), or
           read_bitmap(), or it could be something you have created.

          You could use save_image/display_image in a graphical user
          interface, to allow "pop-up" dialog boxes, and drop-down menus
          to appear and disappear without losing what was previously on
          the screen.

          The sequences (rows) of the image do not have to all be the
          same length.

 Example:     display_image({20,30}, {{1,5,9},
                       {2,4},
                       {1,0,1,0,4},
                       {5,5,5}})
           -- displays a small 4-line image at {20,30}, with the pixels
              appearing in the same relative positions as the layout
              above would indicate

 Example Program: see demo\bitmap.ex

 See Also:    save_image, read_bitmap, display_text_image

─────────────────────────────<display_text_image>───────────────────────────────

 Syntax:      include image.e
           display_text_image(s1, s2)

 Description: Display the 2-d sequence of characters and attributes contained
            in s2 at line s1[1], column s1[2]. s2 is a sequence of sequences,
            where each sequence is a string of characters and attributes to
            be displayed. The top-left character is displayed at s1. Other
            characters appear to the right or below of this position. The
            attributes indicate the foreground and background color of the
            preceding character.

 Comments:    s2 would normally be the result of a previous call to
           save_text_image(), although you could construct it yourself.

          This routine only works in text modes.

          You might use save_text_image/display_text_image in a text-mode
          graphical user interface, to allow "pop-up" dialog boxes, and
          drop-down menus to appear and disappear without losing what was
          previously on the screen.

           The sequences of the text image do not have to all be the same
           length.

 Example:     clear_screen()
           display_text_image({1,1}, {{'A', WHITE, 'B', GREEN},
                       {'C', RED+16*WHITE},
                       {'D', BLUE}})
           -- displays:  AB
                     C
                     D
             in the appropriate colors at the top left corner of the screen

 See Also:    save_text_image, display_image

────────────────────────────────<dos_interrupt>─────────────────────────────────
 Syntax:      include machine.e
           s2 = dos_interrupt(i, s1)

 Description: Call DOS software interrupt number i. s1 is a 10-element
          sequence of 16-bit register values to be used as input to the
          routine. s2 is a similar 10-element sequence containing
          output register values after the call returns. machine.e
          has the following declaration which shows the order of
          the register values in the input and output sequences.

        global constant REG_DI = 1,
                REG_SI = 2,
                REG_BP = 3,
                REG_BX = 4,
                REG_DX = 5,
                REG_CX = 6,
                REG_AX = 7,
                REG_FLAGS = 8,
                REG_ES = 9,
                REG_DS = 10

 Comments:    The register values returned in s2 are always positive values
           between 0 and #FFFF (65535).

           The flags value in s1[REG_FLAGS] is ignored on input. On output
          the least significant bit of s2[REG_FLAGS] has the carry flag,
          which usually indicates failure if it is set to 1.

          Certain interrupts require that you supply addresses of blocks of
          memory. These addresses must be conventional, low-memory
          addresses. You can allocate/deallocate low-memory using
          allocate_low() and free_low().

          With DOS software interrupts you can perform a wide variety
          of specialized operations, anything from formatting your
          floppy drive to rebooting your computer. For documentation
          on these interrupts consult a technical manual such as
          Peter Norton's "PC Programmer's Bible", or download Ralf
          Brown's Interrupt List from the WEB:

           http://www.cs.cmu.edu/afs/cs.cmu.edu/user/ralf/pub/WWW/files.html

 Example Program: demo\dosint.ex

 See Also:      allocate_low, free_low

──────────────────────────────────<draw_line>───────────────────────────────────

 Syntax:      include graphics.e
           draw_line(i, s)

 Description: Draw a line on a pixel-graphics screen connecting two or more
              points in s, using color i.

 Example:     draw_line(WHITE, {{100, 100}, {200, 200}, {900, 700}})

          This would connect the three points in the sequence using a white
          line, i.e. a line would be drawn from {100, 100} to {200, 200}
          and another line would be drawn from {200, 200} to {900, 700}.

 See Also:    polygon, ellipse, pixel

───────────────────────────────────<ellipse>────────────────────────────────────

 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\sb.ex

 See Also:    polygon, draw_line

─────────────────────────────────────<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:    match, 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

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

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

           Distinct "top-level" objects in the input stream must be
           separated from each other with one or more "whitespace"
           characters (blank, tab or \n). Whitespace is not necessary
           *within* a top-level object.

 Comments:    The combination of print() and get() can be used to save any
           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.

           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: see demo\mydata.ex.

 See Also:    print, value, gets, getc

───────────────────────────────<get_active_page>────────────────────────────────

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

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

 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 for
          carriage return. Return -1 if no key was pressed. Special
          codes are returned for the function keys, arrow keys etc.

 Comments:    DOS 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>───────────────────────────────────

 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, and the ones that are lost are usually lost at a
          lower level in the system, beyond the control of your program.
          Losing a MOVE event is generally not too serious, as the next
          MOVE will tell you where the mouse pointer is.

 Comments:    You need a DOS mouse driver to use this routine.

           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.

          In text modes you will probably want to scale the x and y
          coordinates to get line and column positions.

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

          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:     a return value of:

         {2, 100, 50}

           would indicate that the left button was pressed down while the
           mouse pointer was at position x=100, y=50 on the screen.

 See Also:    mouse_events, mouse_pointer

──────────────────────────────────<get_pixel>───────────────────────────────────

 Syntax:      include graphics.e
           x = get_pixel(s)

 Description: When s is a 2-element screen coordinate {x, y}, get_pixel()
           returns the color 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 color values 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:    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_vector>──────────────────────────────────

 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\hardint.ex

 See Also:    set_vector, lock_memory

─────────────────────────────────────<getc>─────────────────────────────────────

 Syntax:      i = getc(fn)

 Description: Get the next character (byte) from file fn. -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.

 See Also:    gets, get_key, wait_key, open

────────────────────────────────────<getenv>────────────────────────────────────

 Syntax:      x = getenv(s)

 Description: Return the value of a DOS environment variable. If the variable
            is undefined return -1.

 Example:     e = getenv("EUDIR")
          -- e will be "C:\EUPHORIA" -- or perhaps D:, E: etc.

 Comments:    Because either a sequence or an atom (-1) might be returned, you
           should probably assign the result to a variable declared as
           object.

 See Also:    command_line

─────────────────────────────────────<gets>─────────────────────────────────────

 Syntax:      x = gets(fn)

 Description: Get the next sequence (one line, including '\n') of characters
           from file fn. 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.

           The last line in a file might not end with a new-line '\n'
           character.

 Example:
          sequence buffer
          object line

          -- read a text file into a sequence
          buffer = {}
          while 1 do
               line = gets(0)
               if atom(line) then
              exit   -- end of file
               end if
               buffer = append(buffer, line)
          end while

 See Also:    getc, puts, open

────────────────────────────────<graphics_mode>─────────────────────────────────

 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.

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

 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

─────────────────────────────────<int_to_bits>──────────────────────────────────

 Syntax:      include machine.e
           s = int_to_bits(a, i)

 Description: Returns the low-order i bits of a, as a sequence of 1's and 0's.
           The least significant bits come first. For negative numbers
           the two's complement bit pattern is returned.

 Comments:    You can use subscripting, slicing, and/or/not of entire
           sequences etc. to manipulate sequences of bits. Shifting
           of bits and rotating of bits are easy to perform.

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

 See Also:    bits_to_int, and_bits, or_bits, xor_bits, not_bits,
              and/or/not of entire sequences in refman.doc

─────────────────────────────────<int_to_bytes>─────────────────────────────────

 Syntax:      include machine.e
           s = int_to_bytes(a)

 Description: Convert an integer into a sequence of 4 bytes. These bytes are in
          the order expected on the 386+, i.e. least significant byte
          first.

 Comments:    You might use this routine prior to poking the 4 bytes into
           memory for use by a machine language program.

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

           This function will correctly convert integer values up to
           32-bits. For larger values, only the low-order 32-bits are
           converted. Euphoria's integer type only allows values up to
           31-bits, so declare your variables as atom if you need a
           larger range.

 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, bits_to_int, peek, poke

───────────────────────────────────<integer>────────────────────────────────────

 Syntax:      i = integer(x)

 Description: Return 1 if x is an integer in the range -1073741824 to
           [phone]. Otherwise return 0.

 Comments:    This serves to define the integer type. You can also call it
           like an ordinary function to determine if an object is an
           integer.

 Example 1:   integer z
           z = -1

 Example 2:   if integer(y/x) then
               puts(SCREEN, "y is an exact multiple of x")
           end if

 See Also:    atom, sequence, floor

────────────────────────────────────<length>────────────────────────────────────

 Syntax:      i = length(s)

 Description: Return the length of s. s must be a sequence. An error will
           occur if s is an atom.

 Comments:    The length of each sequence is stored internally by the
           interpreter for quick access. (In other languages this
           operation requires a search through memory for an end marker.)

 Example 1:   length({{1,2}, {3,4}, {5,6}})   -- 3

 Example 2:   length("")    -- 0

 Example 3:   length({})    -- 0

 See Also: sequence

─────────────────────────────────<lock_memory>──────────────────────────────────

 Syntax:      include machine.e
              lock_memory(a, i)

 Description: Prevent the block of virtual memory starting at address a,
              of length i, from ever being swapped out to disk.

 Comments:    Use this to ensure that all code and data required for
              handling interrupts is kept in memory at all times
              while your program is running.

 Example Program: demo\hardint.ex

 See Also:    get_vector, set_vector

─────────────────────────────────────<log>──────────────────────────────────────

 Syntax:      x2 = log(x1)

 Description: Return the natural logarithm of x1.

 Comments:    This function may be applied to an atom or to all elements
           of a sequence. Note that log is only defined for positive
           numbers. Your program will abort with a message if you
           try to take the log of a negative number or zero.

 Example:     a = log(100)
           -- a is 4.60517

 See Also:    sin, cos, tan, sqrt

────────────────────────────────────<lower>─────────────────────────────────────

 Syntax:      include wildcard.e
           x2 = lower(x1)

 Description: Convert an atom or sequence to lower case.

 Example:     s = lower("Euphoria")
           -- s is "euphoria"

           a = lower('B')
           -- a is 'b'

           s = lower({"Euphoria", "Programming"})
           -- s is {"euphoria", "programming"}

 See Also:    upper

─────────────────────────────────<machine_func>─────────────────────────────────

 Syntax:      x1 = machine_func(a, x)

 Description: see machine_proc() below

─────────────────────────────────<machine_proc>─────────────────────────────────

 Syntax:      machine_proc(a, x)

 Description: Perform a machine-specific operation such as graphics and sound
            effects. This routine should normally be called indirectly via
            one of the library routines in a Euphoria include file. A direct
            call can cause a machine exception if done incorrectly.

 See Also:    machine_func

────────────────────────────────────<match>─────────────────────────────────────

 Syntax:      i = match(s1, s2)

 Description: Try to match s1 against some slice of s2. If successful, return
          the element number of s2 where the (first) matching slice begins,
          else return 0.

 Example:     location = match("pho", "Euphoria")
          -- location is set to 3

 See Also:    find, compare, wildcard_match

───────────────────────────────────<mem_copy>───────────────────────────────────

 Syntax:      include machine.e
              mem_copy(a1, a2, i)

 Description: Copy a block of i bytes of memory from address a2 to address a1.

 Comments:    The bytes of memory will be copied correctly even if the block
              of memory at a2 overlaps with the block of memory at a1.

              mem_copy(a1, a2, i) is equivalent to: poke(a1, peek({a2, i}))
              but is faster for i > 6, and is more than 10 times faster for
              i > 1000.

 Example:     dest = allocate(50)
              src = allocate(100)
              poke(src, {1,2,3,4,5,6,7,8,9})
              mem_copy(dest, src, 9)

 See Also:    mem_set, peek, poke, allocate, allocate_low

───────────────────────────────────<mem_set>────────────────────────────────────

 Syntax:      include machine.e
              mem_set(a1, i1, i2)

 Description: Set i2 bytes of memory, starting at address a1, to the value
              of i1.

 Comments:    The low order 8 bits of i1 are actually stored in each byte.

              mem_set(a1, i1, i2) is equivalent to: poke(a1, repeat(i1, i2))
              but is faster for i2 > 12, and is more than 25 times faster for
              i2 > 1000.

 Example:     destination = allocate(1000)
              mem_set(destination, ' ', 1000)

 See Also:    mem_copy, peek, poke, allocate, allocate_low

─────────────────────────────────<mouse_events>─────────────────────────────────

 Syntax:      include mouse.e
           mouse_events(i)

 Description: Use this procedure to select the mouse events that you want
          get_mouse() to report. By default, get_mouse() will report all
          events. mouse_events() can be called at various stages of the
          execution of your program, as the need to detect events changes.

 Comments:    It is good practice to ignore events that you are not interested
              in, particularly the very frequent MOVE event, in order to reduce
              the chance that you will miss a significant event.

            The first call that you make to mouse_events() will turn on a
            mouse pointer, or a highlighted character.

 Example:     mouse_events(LEFT_DOWN + LEFT_UP + RIGHT_DOWN)
           -- will restrict get_mouse() to reporting the left button
             being pressed down or released, and the right button
             being pressed down. All other events will be ignored.

 See Also:    get_mouse, mouse_pointer

────────────────────────────────<mouse_pointer>─────────────────────────────────

 Syntax:      include mouse.e
           mouse_pointer(i)

 Description: If i is 0 hide the mouse pointer, otherwise turn on the mouse
           pointer. Multiple calls to hide the pointer will require
          multiple calls to turn it back on. The first call to either
          get_mouse() or mouse_events() above, will also turn the pointer
          on (once).

 Comments:    It may be necessary to hide the mouse pointer temporarily when
            you update the screen.

              After a call to text_rows() you may have to call mouse_pointer(1)
              to see the mouse pointer again.

 See Also:    get_mouse, mouse_events

───────────────────────────────────<not_bits>───────────────────────────────────

 Syntax:      x2 = not_bits(x1)

 Description: Perform the logical NOT operation on each bit in x1.
              A bit in x2 will be 1 when the corresponding bit in x1
              is 0, and will be 0 when the corresponding bit in x1 is 1.

 Comments:    The argument to this function may be an atom or a sequence.
           The rules for arithmetic operations on sequences apply.

          The argument must be representable as a 32-bit number,
          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.

 Example:     a = not_bits(#000000F7)
              -- a is -248 (i.e. FFFFFF08 interpreted as a negative number)

 See Also:    and_bits, or_bits, xor_bits, int_to_bits

─────────────────────────────────────<open>─────────────────────────────────────

 Syntax:      fn = open(s1, s2)

 Description: Open a file or device, to get the file number. -1 is returned if
            the open fails. s1 is the path name of the file or device.  s2 is
            the mode in which the file is to be opened. Possible modes are:

          "r"  - open text file for reading
          "rb" - open binary file for reading
          "w"  - create text file for writing
          "wb" - create binary file for writing
          "u"  - open text file for update (reading and writing)
          "ub" - open binary file for update
          "a"  - open text file for appending
          "ab" - open binary file for appending

          Files opened for read or update must already exist. Files opened
          for write or append will be created if necessary. A file opened
          for write will be set to 0 bytes. Output to a file opened for
          append will start at the end of file.

          Output to text files will have carriage-return characters
          automatically added before linefeed characters. On input, these
          carriage-return characters are removed. A control-z character
          (ASCII 26) will signal an immediate end of file.

          I/O to binary files is not modified in any way. Any byte values
          from 0 to 255 can be read or written.

          Some typical devices that you can open are:

          "CON"    the console (screen)
          "AUX"    the serial auxiliary port
          "COM1"   serial port 1
          "COM2"   serial port 2
          "PRN"    the printer on the parallel port
          "NUL"    a non-existent device that accepts and discards output

 Comment:     When running under Windows 95, you can open any existing file
           that has a long file or directory name in its path (i.e. greater
           than the standard DOS 8.3 format) using any open mode - read,
           write etc. However, if you try to create a *new* file (open with
           "w" or "a" and the file does not already exist) then the name
           will be truncated if necessary to an 8.3 style name. We hope to
           support creation of new long-filename files in a future release.

 Example:     integer file_num, file_num95
           sequence first_line
           constant ERROR = 2

           file_num = open("myfile", "r")
          if file_num = -1 then
                 puts(ERROR, "couldn't open myfile\n")
           else
               first_line = gets(file_num)
           end if

           file_num = open("PRN", "w") -- open printer for output

           -- on Windows 95:
           file_num95 = open("bigdirectoryname\\verylongfilename.abcdefg",
                       "r")
           if file_num95 != -1 then
           puts(1, "it worked!\n")
           end if

 See Also:    close

───────────────────────────────────<or_bits>────────────────────────────────────

 Syntax:      x3 = or_bits(x1, x2)

 Description: Perform the logical OR operation on corresponding bits in
              x1 and x2. A bit in x3 will be 1 when a corresponding
              bit in either x1 or x2 is 1.

 Comments:    The arguments to this function may be atoms or sequences. The
           rules for arithmetic 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.

 Example 1:   a = or_bits(#0F0F0000, #12345678)
              -- a is #1F3F5678

 Example 2:   a = or_bits(#FF, {#123456, #876543, #2211})
              -- a is {#1234FF, #8765FF, #22FF}

 See Also:    and_bits, xor_bits, not_bits, int_to_bits

───────────────────────────────────<palette>────────────────────────────────────

 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, allocate, free, allocate_low, free_low, call

────────────────────────────────────<pixel>─────────────────────────────────────

 Syntax:      include graphics.e
           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.

 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

─────────────────────────────────────<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(value, 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 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: see demo\callmach.ex

 See Also:    peek, allocate, free, allocate_low, free_low, call

───────────────────────────────────<polygon>────────────────────────────────────

 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:    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 functions may be atoms or sequences. The
           rules for arithmetic 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. e.g.

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

         {0,0} & {1,2,3}
                -- {0, 0, 1, 2, 3}

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

 Example:     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 (&) and sequence-formation {,,} operators
           in refman.doc

────────────────────────────────────<print>─────────────────────────────────────

 Syntax:      print(fn, x)

 Description: Print, to file or device fn, an object x with braces { , , , }
           to show the structure.

 Comment:     If you want to see a string of characters, rather than just the
          ASCII codes, you need to use puts or printf.

 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:    ?, puts, printf, get

────────────────────────────────────<printf>────────────────────────────────────

 Syntax:      printf(fn, st, x)

 Description: Print x, to file or device fn, using format string st. If x is
           an atom then a single value will be printed. If x is a sequence,
           then formats from st are applied to successive elements of 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 formats are:

          %d - print an atom as a decimal integer
          %x - print an atom as a hexadecimal integer
          %o - print an atom as an octal integer
          %s - print a sequence as a string of characters
          %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 either
             the %f or %e format, whichever seems more appropriate
          %% - print the '%' character itself

          Field widths can be added to the basic formats, e.g. %5d, or
          %8.2f. 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.

 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

 Comments:    Watch out for the following common mistake:

             printf(1, "%s", name)

          This will print only the first character of name, as each element
          of name is taken to be a separate value to be formatted. You must
          say this instead:

             printf(1, "%s", {name})

           Now, the third argument of printf is a one-element sequence
           containing a single value to be formatted.

 See Also:    sprintf, puts, open

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

 Comment:     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).

 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\bitmap.ex

 See Also:    palette, display_image

──────────────────────────────────<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 arithmetic 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}

────────────────────────────────────<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"}

 See Also:    append, prepend, sequence-formation operator {,,} in refman.doc

─────────────────────────────────<save_bitmap>──────────────────────────────────

 Syntax:      include image.e
          i = save_bitmap(s, st)

 Description: Create a Windows bitmap (.BMP) file from a 2-element sequence s.
           st is the name of a .BMP "bitmap" file. s[1] is the palette:

             {{r,g,b}, {r,g,b}, ..., {r,g,b}}

           Each red, green, or blue value is in the range 0 to 255. s[2]
           is a 2-d sequence of sequences containing a pixel-graphics image.
           The sequences contained in s[2] must all have the same length.
           s is in the same format as the value returned by read_bitmap().

          The result will be one of the following codes:

        global constant
            BMP_SUCCESS = 0,
            BMP_OPEN_FAILED = 1,
            BMP_INVALID_MODE = 4   -- either invalid graphics mode
                           or invalid argument

 Comments:    If you use get_all_palette() to get the palette before calling
           this function, you must multiply the returned intensity values
           by 4 before calling save_bitmap().

           save_bitmap() produces bitmaps of 2, 4, 16, or 256 colors and
              these can all be read with read_bitmap(). Windows Paintbrush
              and some other tools do not support 4-color bitmaps.

          save_bitmap() works in both pixel-graphics modes and text modes.

 Example:     paletteData = get_all_palette() * 4
              code = save_bitmap({paletteData, imageData},
                              "c:\\example\\a1.bmp")

 See Also:    save_image, read_bitmap, save_screen, get_all_palette

──────────────────────────────────<save_image>──────────────────────────────────

 Syntax:      include image.e
           s3 = save_image(s1, s2)

 Description: Save a rectangular image from a pixel-graphics screen. The result
           is a 2-d sequence of sequences containing all the pixels
           in the image. You can redisplay the image using display_image().
           s1 is a 2-element sequence {x1, y1} specifying the top-left
           pixel in the image. s2 is a sequence {x2, y2} specifying the
           bottom-right pixel.

 Comments:    You might use this in a graphical user interface to save a
           portion of the screen before you display a drop-down menu
           or dialog box.

 Example:     s = save_image({0,0}, {50,50})
           display_image({100,200}, s)
           display_image({300,400}, s)
           -- saves a 51x51 square image, then redisplays it at {100,200}
          -- and at {300,400}

 See Also:    display_image, save_text_image

─────────────────────────────────<save_screen>──────────────────────────────────

 Syntax:      include image.e
          i = save_screen(x1, st)

 Description: Save the whole screen or a rectangular region of the screen as
              a Windows bitmap (.BMP) file. To save the whole screen, pass the
              integer 0 for x1. To save a rectangular region of the screen,
              x1 should be a sequence of 2 sequences:
                {{topLeftXPixel, topLeftYPixel},
             {bottomRightXPixel, bottomRightYPixel}}

          st is the name of a .BMP "bitmap" file.

          The result will be one of the following codes:

        global constant
            BMP_SUCCESS = 0,
            BMP_OPEN_FAILED = 1,
            BMP_INVALID_MODE = 4   -- either invalid graphics mode
                           or invalid argument

 Comments:    save_screen() produces bitmaps of 2, 4, 16, or 256 colors and
              these can all be read with read_bitmap(). Windows Paintbrush
              and some other tools do not support 4-color bitmaps.

          save_screen() only works in pixel-graphics modes, not text modes.

 Example 1:   code = save_screen(0, "c:\\example\\a1.bmp")

 Example 2:   err = save_screen({{0,0},{200, 15}}, "b1.bmp")

 See Also:    save_image, read_bitmap

───────────────────────────────<save_text_image>────────────────────────────────

 Syntax:      include image.e
           s3 = save_text_image(s1, s2)

 Description: Save a rectangular region of text from a text-mode screen.
           The result is a sequence of sequences containing ASCII characters
           and attributes from the screen. You can redisplay this text using
           display_text_image(). s1 is a 2-element sequence {line1, column1}
           specifying the top-left character. s2 is a sequence
           {line2, column2} specifying the bottom right character.

 Comments:    Because the character attributes are also saved, you will get
            the correct foreground and background color for each character
            if you redisplay the text.

          An attribute byte is made up of two 4-bit fields that
          encode the foreground and background color of a character.
          The high-order 4 bits determine the background color, while
          the low-order 4 bits determine the foreground color.

          This routine only works in text modes.

           You might use this function in a text-mode graphical user
           interface to save a portion of the screen before displaying a
           drop-down menu, dialog box, alert box etc.

           If you are flipping video pages, note that this function reads
           from the current active page.

 Example:     If the top 2 lines of the screen have:
          Hello
          World

           s = save_text_image({1,1}, {2,5})

           Then s is something like:
                   {"H-e-l-l-o-",
                         "W-o-r-l-d-"}
           where we have indicated the attribute bytes by '-'

 See Also:    display_text_image, save_image, set_active_page

────────────────────────────────────<scroll>────────────────────────────────────

 Syntax:      include graphics.e
           scroll(i1, i2, i3)

 Description: Scroll a region of text on the screen either up (i1 positive) or
            down (i1 negative) by i1 lines. The region is the series of lines
          on the screen from i2 (top line) to i3 (bottom line), inclusive.
          A    new blank line will appear at the top or bottom.

 Example Program: see bin\ed.ex

 See Also:    clear_screen, text_rows

─────────────────────────────────────<seek>─────────────────────────────────────

 Syntax:      include file.e
           i1 = seek(fn, i2)

 Description: Seek (move) to any byte position in the file fn or to the end of
            file if i2 is -1. For each open file there is a current byte
            position that is updated as a result of I/O operations on the
            file. The initial file position is 0 for files opened for read,
            write or update. The initial position is the end of file for
            files opened for append. The value returned by seek() is 0 if the
            seek was successful, and non-zero if it was unsuccessful. It is
            possible to seek past the    end of a file. In this case undefined
            bytes will be added to the file to make it long enough for the
            seek.

 See Also:    where, open

───────────────────────────────────<sequence>───────────────────────────────────

 Syntax:      i = sequence(x)

 Description: Return 1 if x is a sequence else return 0.

 Comments:    This serves to define the sequence type. You can also call
           it like an ordinary function to determine if an object is
           a sequence.

 Example 1:
           sequence s
           s = {1,2,3}

 Example 2:
           if sequence(x) then
                 sum = 0
                 for i = 1 to length(x) do
                     sum = sum + x[i]
                 end for
           else
               -- x must be an atom
               sum = x
           end if

 See Also:    atom, object type in refman.doc

───────────────────────────────<set_active_page>────────────────────────────────

 Syntax:      include image.e
           set_active_page(i)

 Description: Select video page i to send all screen output to.

 Comments:    With multiple pages you can instantaneously change the entire
           screen without causing any visible "flicker". You can also
           save the screen and bring it back quickly.

          video_config() will tell you how many pages are available in
          the current graphics mode.

           By default, the active page and the display page are both 0.

           This works under DOS, or full-screen under Windows. In a
           partial-screen window you cannot change the active page.

 Example:     include image.e

           -- active & display pages are initially both 0
           puts(1, "\nThis is page 0\n")
           set_active_page(1)     -- screen output will now go to page 1
           clear_screen()
           puts(1, "\nNow we've flipped to page 1\n")
           if getc(0) then        -- wait for key-press
           end if
           set_display_page(1)    -- "Now we've ..." becomes visible
           if getc(0) then        -- wait for key-press
           end if
          set_display_page(0)    -- "This is ..." becomes visible again
          set_active_page(0)

 See Also:    get_active_page, set_display_page

──────────────────────────────<set_display_page>────────────────────────────────

 Syntax:      include image.e
           set_display_page(i)

 Description: Set video page i to be mapped to the visible screen.

 Comments:    With multiple pages you can instantaneously change the entire
           screen without causing any visible "flicker". You can also
           save the screen and bring it back quickly.

          video_config() will tell you how many pages are available in
          the current graphics mode.

           By default, the active page and the display page are both 0.

           This works under DOS, or full-screen under Windows. In a
           partial-screen window you cannot change the active page.

 Example:     See set_active_page example.

 See Also:    get_display_page, set_active_page

──────────────────────────────────<set_rand>────────────────────────────────────

 Syntax:      include machine.e
           set_rand(a1)

 Description: Set the random number generator to a certain state, a1, so that
           you will get a known series of random numbers on subsequent
           calls to rand(). The lower 32 bits of the value of a1 are
           used.

 Comments:    Normally the numbers returned by the rand() function are totally
            unpredictable, and will be different each time you run your
            program. Sometimes however you may wish to repeat the same
            series of numbers, perhaps because you are trying to debug
            your program, or maybe you want the ability to generate the
            same output (e.g. a random picture) for your user upon request.

 Example:     sequence s, t
           s = repeat(0, 3)
           t = s

           set_rand(12345)
           s[1] = rand(10)
           s[2] = rand(100)
           s[3] = rand(1000)

           set_rand(12345)  -- same value for set_rand()
           t[1] = rand(10)  -- same arguments to rand() as before
           t[2] = rand(100)
           t[3] = rand(1000)
           -- at this point s and t will be identical

 See Also:    rand

──────────────────────────────────<set_vector>──────────────────────────────────

 Syntax:      include machine.e
              set_vector(i, s)

 Description: Set s as the new address for handling interrupt number i.
              s must be a protected mode far address in the form:
              {16-bit segment, 32-bit offset}.

 Comments:    Before calling set_vector() you must store a machine-code
              interrupt handling routine at location s in memory.

              The 16-bit segment can be the code segment used by Euphoria.
              To get the value of this segment see demo\hardint.ex.
              The offset can be the 32-bit value returned by allocate().
              Euphoria runs in protected mode with the code segment
              and data segment pointing to the same physical memory,
              but with different access modes.

              Interrupts occurring in either real-mode or protected mode
              will be passed to your handler. Your interrupt handler
              should immediately load the correct data segment before it
              tries to reference memory.

              Your handler might return from the interrupt using the
              iretd instruction, or jump to the original interrupt handler.
              It should save and restore any registers that it modifies.

              You should lock the memory used by your handler to ensure
              that it will never be swapped out. See lock_memory().

              It is highly recommended that you study demo\hardint.ex
              before trying to set up your own interrupt handler.

          You should have a good knowledge of machine-level programming
          before attempting to write your own handler.

              You can call set_vector() with the far address returned by
              get_vector(), when you want to restore the original handler.

 Example:     set_vector(#1C, {code_segment, my_handler_address})

 Example Program: demo\hardint.ex

 See Also:    get_vector, lock_memory

─────────────────────────────────────<sin>──────────────────────────────────────

 Syntax:      x2 = sin(x1)

 Description: Return the sine of x1, where x1 is in radians.

 Comments:    This function may be applied to an atom or to all elements
           of a sequence.

 Example:     sin_x = sin({.5, .9, .11})
           -- sin_x is {.479, .783, .110}

 See Also:    cos, tan

─────────────────────────────────────<sort>─────────────────────────────────────

 Syntax:      include sort.e
           s2 = sort(s1)

 Description: Sort s1 into ascending order using a fast sorting algorithm. The
            elements of s1 can be any mix of atoms or sequences. Atoms come
            before sequences, and sequences are sorted "alphabetically" where
            the first elements are more significant than the later elements.

 Comments:    By defining your own compare function to override the built-in
          compare(), you can change the ordering of values from sort(), and
          perhaps choose a field or element number on which to base the
          sort. Define your compare() as a global function before
          including sort.e.

 Example 1:   x = 0 & sort({7,5,3,8}) & 0
          -- x is set to {0, 3, 5, 7, 8, 0}

 Example 2:   y = sort({"Smith", "Jones", "Doe", 5.5, 4, 6})
           -- y is {4, 5.5, 6, "Doe", "Jones", "Smith"}

 Example 3:   database = sort({{"Smith",   95.0, 29},
                          {"Jones",   77.2, 31},
                          {"Clinton", 88.7, 44}})

          -- The 3 database "records" will be sorted by the first "field"
          -- i.e. by name. Where the first field (element) is equal it
          -- will be sorted by the second field etc.

          -- database is {{"Clinton", 88.7, 44},
                        {"Jones",   77.2, 31},
                        {"Smith",   95.0, 29}}

 See Also:    compare, match, find

────────────────────────────────────<sound>─────────────────────────────────────

 Syntax:      include graphics.e
              sound(i)

 Description: Turn on the PC speaker at frequency i. If i is 0 the speaker
           will be turned off.

 Example:     sound(1000) -- starts a fairly high pitched sound

───────────────────────────────────<sprintf>────────────────────────────────────

 Syntax:      s = sprintf(st, x)

 Description: This is exactly the same as printf(), except that the output
           is returned as a sequence of characters, rather than being
           sent to a file or device. st is a format string, x is the
           value or sequence of values to be formatted. printf(fn, st, x)
           is equivalent to puts(fn, sprintf(st, x)).

 Comments:    Some typical uses of sprintf are:

                1. Converting numbers to strings.
                2. Creating strings to pass to system().
                3. Creating formatted error messages and passing them to
                   a common error message handler.

 Example:     s = sprintf("%08d", 12345)
            -- s is "00012345"

 See Also:    printf, value, get

─────────────────────────────────────<sqrt>─────────────────────────────────────

 Syntax:      x2 = sqrt(x1)

 Description: Calculate the square root of x1.

 Comments:    This function may be applied to an atom or to all elements
           of a sequence.

           Taking the square root of a negative number will abort your
           program with a run-time error message.

 Example:     r = sqrt(16)
           -- r is 4

 See Also:    log, power

────────────────────────────────────<system>────────────────────────────────────

 Syntax:      system(s, i)

 Description: Pass a command string s to the DOS command interpreter for
           execution. The argument i indicates the manner in which to
          return from the system call.

        value of i      return action
        ----------    -------------
             0      - restore previous graphics mode
                  (clears the screen)
             1      - make a beep sound, wait for a
                  key press, then restore the
                  graphics mode
             2      - do not restore graphics mode

 Comments:    Action 2 should only be used when it is known that the system
           call will not change the graphics mode.

          You can use Euphoria as a sophisticated DOS "batch" language
          by making calls to system().

           A Euphoria program will start off using extended memory. If
           extended memory runs out the program will consume conventional
           memory. If conventional memory runs out it will use virtual
           memory, i.e. swap space on disk. The DOS command run by system()
           will fail if there is not enough conventional memory available.
           To avoid this situation you can reserve some conventional (low)
           memory by typing:

                    SET CAUSEWAY=LOWMEM:xxx

           where xxx is the number of K of conventional memory to reserve.
           Type this before running your program. You can also put this in
           a .bat file that runs your program, or in AUTOEXEC.BAT. For
           example:

                    SET CAUSEWAY=LOWMEM:80
                    ex myprog.ex

           This will reserve 80K of conventional memory, which should be
           enough to run simple DOS commands like COPY, MOVE, MKDIR etc.

 Example:     system("copy temp.txt a:\\temp.bak", 2)
           -- note use of double backslash in literal string to get
              single backslash

 Example Program: see install.ex

 See Also:    dir, current_dir, getenv, command_line

─────────────────────────────────────<tan>──────────────────────────────────────

 Syntax:      x2 = tan(x1)

 Description: Return the tangent of x1, where x1 is in radians.

 Comments:    This function may be applied to an atom or to all elements
           of a sequence.

 Example:     t = tan(1.0)
           -- t is 1.55741

 See Also:    sin, cos, arctan

──────────────────────────────────<text_color>──────────────────────────────────

 Syntax:      include graphics.e
           text_color(i)

 Description: Set the foreground text color. Add 16 to get blinking text
          in some modes. See graphics.e for a list of possible colors.

 Comments:    Text that you print *after* calling text_color will have the
           desired color.

           When your program terminates, the last color that you selected
           and actually printed on the screen will remain in effect.
           Thus you may have to print something, maybe just '\n', in
           WHITE to restore white text, especially if you are at the
           bottom line of the screen, ready to scroll up.

 Example:     text_color(BRIGHT_BLUE)

 See Also:    bk_color

──────────────────────────────────<text_rows>───────────────────────────────────

 Syntax:      include graphics.e
           i2 = text_rows(i1)

 Description: Set the number of lines on a text-mode screen to i1 if possible.
          i2 will be set to the actual new number of lines.

 Comments:    Values of 25, 28, 43 and 50 lines are supported by most video
           cards.

 See Also:    graphics_mode

──────────────────────────────────<tick_rate>───────────────────────────────────

 Syntax:      include machine.e
           tick_rate(a)

 Description: Specify the number of clock-tick interrupts per second.
              This determines the precision of the time() library
              routine. It also affects the sampling rate for time
              profiling.

 Comments:    On a PC the clock-tick interrupt normally occurs at 18.2
              interrupts per second. tick_rate() lets you increase
              that rate, but not decrease it.

              tick_rate(0) will restore the rate to the normal 18.2 rate.
              Euphoria will also restore the rate automatically when it exits,
              even when it finds an error in your program.

              While ex.exe is running, the system will maintain the correct
              time of day. However if ex.exe should crash (e.g. you see
              a "Causeway..." error) while the tick rate is high, you (or
              your user) may need to reboot the machine to restore the
              proper rate. If you don't, the system time may advance too
              quickly. This problem does not occur on Windows 95, only on DOS
              or Windows 3.1. You will always get back the correct time of day
              from the battery-operated clock in your system when you boot up
              again.

 Example:     tick_rate(100)
           -- time() will now advance in steps of .01 seconds
           -- instead of the usual .055 seconds

 See Also:    time, discussion of time profiling in refman.doc

─────────────────────────────────────<time>─────────────────────────────────────

 Syntax:      a = time()

 Description: Return the number of seconds since some fixed point in the past.
            The resolution on MS-DOS is normally about 0.05 seconds.

 Comments:    Take the difference between two readings of time(), to
           measure, for example, how long a section of code takes to
           execute.

              You can improve the resolution by calling tick_rate().

 Example:     constant ITERATIONS = 1000000
           integer p
           atom t0, loop_overhead

           t0 = time()
           for i = 1 to ITERATIONS do
           end for
           loop_overhead = time() - t0

          t0 = time()
           for i = 1 to ITERATIONS do
                 p = power(2, 20)
           end for
           ? (time() - t0 - loop_overhead)/ITERATIONS
           -- calculates time (in seconds) for one call to power

 See Also:    date, tick_rate

────────────────────────────────────<trace>─────────────────────────────────────

 Syntax:      with trace
           trace(i)

 Description: If i is 1 or 2 then turn on full-screen statement tracing. If i
           is 0 then    turn off tracing. When i is 2 a monochrome trace
           display is forced on. Tracing only occurs in subroutines that
           were compiled "with trace". See the section on Debugging in
           refman.doc.

 Comments:    Use trace(2) if the color display is hard to view on your system.

 Example:     if x < 0 then
           -- ok, here's the case I want to debug...
           trace(1)
           -- etc.
          ...
          end if

 See Also:    Chapter 3 in refman.doc.

────────────────────────────────────<upper>─────────────────────────────────────

 Syntax:      include wildcard.e
           x2 = upper(x1)

 Description: Convert an atom or sequence to upper case.

 Example:     s = upper("Euphoria")
           -- s is "EUPHORIA"

           a = upper('g')
           -- a is 'G'

           s = upper({"Euphoria", "Programming"})
           -- s is {"EUPHORIA", "PROGRAMMING"}

 See Also:    lower

──────────────────────────────────<use_vesa>────────────────────────────────────

 Syntax:      include machine.e
           use_vesa(i)

 Description: use_vesa(1) will force Euphoria to use the VESA graphics
           standard. This may cause Euphoria programs to work better
           in SVGA graphics modes with certain video cards.
           use_vesa(0) will restore Euphoria's original method of
           using the video card.

 Comments:    Most people can ignore this. However if you experience
           difficulty in SVGA graphics modes you should try calling
           use_vesa(1) at the start of your program before any calls
           to graphics_mode().

           Arguments to use_vesa() other than 0 or 1 should not be used.

 Example:     use_vesa(1)
           fail = graphics_mode(261)

 See Also:    graphics_mode

────────────────────────────────────<value>─────────────────────────────────────

 Syntax:      include get.e
           s = value(st)

 Description: Read the string representation of a Euphoria object, and compute
           the value of that object. A 2-element sequence,
           {error_status, value} is actually returned, where error_status
           can be one of:

        GET_SUCCESS     -- a valid object representation was found
        GET_EOF        -- end of string reached too soon
        GET_FAIL    -- syntax is wrong

 Comments:    This works the same as get(), but it reads from a string
           that you supply, rather than from a file or device.

 Example 1:   s = value("12345"}
           -- s is {GET_SUCCESS, 12345}

 Example 2:   s = value("{0, 1, -99.9}")
           -- s is {GET_SUCCESS, {0, 1, -99.9}}

 Example 3:   s = value("+++")
           -- s is {GET_FAIL, 0}

 See Also:    get, sprintf, print

─────────────────────────────────<video_config>─────────────────────────────────

 Syntax:      include graphics.e
           s = video_config()

 Description: Return a sequence of values describing the current video
          configuration:
        {color monitor?, graphics mode, text rows, text columns,
         xpixels, ypixels, number of colors, number of pages}

           The following constants are defined in graphics.e:

            global constant VC_COLOR = 1,
                VC_MODE  = 2,
                VC_LINES = 3,
                VC_COLUMNS = 4,
                VC_XPIXELS = 5,
                VC_YPIXELS = 6,
                VC_NCOLORS = 7,
                VC_PAGES = 8

 Comments:    This routine makes it easy for you to parameterize a program
           so it will work in many different graphics modes.

           On the PC there are two types of graphics mode. The first type,
           text mode, lets you print text only. The second type,
           pixel-graphics mode, lets you plot pixels, or points, in
           various colors, as well as text. You can tell that you are in a
           text mode, because the VC_XPIXELS and VC_YPIXELS fields will
           be 0. Library routines such as polygon, draw_line, and ellipse
           only work in a pixel-graphics mode.

 Example:     vc = video_config()  -- in mode 3 with 25-lines of text:
           -- vc is {1, 3, 25, 80, 0, 0, 32, 8}

 See Also:    graphics_mode

──────────────────────────────────<wait_key>────────────────────────────────────

 Syntax:      include get.e
           i = wait_key()

 Description: Return the next key pressed by the user. Don't return until
            a key is pressed.

 Comments:    You could achieve the same result using get_key() as follows:

                while 1 do
                    k = get_key()
                    if k != -1 then
                        exit
                    end if
                end while

           However, on multi-tasking systems like Windows, Windows NT,
           or OS/2 this "busy waiting" would slow the system down.
           wait_key() lets the operating system do other useful work
           while your program is waiting for the user to press a key.

           You could also use getc(0), assuming file number 0 was input
           from the keyboard, except that you wouldn't pick up the special
           codes for function keys, arrow keys etc.

 See Also:    get_key, getc

────────────────────────────────────<where>─────────────────────────────────────

 Syntax:      include file.e
           i = where(fn)

 Description: This function returns the current byte position in the file fn.
          This position is updated by reads, writes and seeks on the file.
          It is the place in the file where the next byte will be read
          from, or written to.

 See Also:    seek, open

────────────────────────────────<wildcard_file>─────────────────────────────────

 Syntax:      include wildcard.e
           i = wildcard_file(s1, s2)

 Description: Return 1 (TRUE) if the filename s2 matches the wild card pattern
           s1. Return 0 (FALSE) otherwise. This is similar to DOS wildcard
           matching, but better in some cases. * matches any 0 or more
           characters, ? matches any single character. Character comparisons
           are not case sensitive.

 Comments:    You might use this function to check the output of the dir()
           routine for file names that match a pattern supplied by the
           user of your program.

           In DOS "*ABC.*" will match ALL files. wildcard_file("*ABC.*", s)
           will only match when the file name part has "ABC" at the end
           (as you would expect).

 Example 1:   i = wildcard_file("AB*CD.?", "aB123cD.e")
          -- i is set to 1

 Example 2:   i = wildcard_file("AB*CD.?", "abcd.ex")
           -- i is set to 0, because the file type has 2 letters not 1

 Example Program: see bin\search.ex

 See Also:    wildcard_match, dir

────────────────────────────────<wildcard_match>────────────────────────────────

 Syntax:      include wildcard.e
           i = wildcard_match(s1, s2)

 Description: This function performs general matching of a string against a
           pattern containing * and ? wildcards. It returns 1 (TRUE) if
           string s2 matches pattern s1. It returns 0 (FALSE) otherwise.
           * matches any 0 or more characters. ? matches any
           single character. Character comparisons are case sensitive.

 Comments:    If you want case insensitive comparisons, pass both s1 and s2
           through upper(), or both through lower() before calling
           wildcard_match().

           If you want to detect a pattern anywhere within a string,
           add * to each end of the pattern:

             i = wildcard_match('*' & pattern & '*', string)

           There is currently no way to treat * or ? literally in a pattern.

 Example 1:   i = wildcard_match("A?B*", "AQBXXYY")
           -- i is 1 (TRUE)

 Example 2:   i = wildcard_match("*xyz*", "AAAbbbxyz")
           -- i is 1 (TRUE)

 Example 3:   i = wildcard_match("A*B*C", "a111b222c")
           -- i is 0 (FALSE) because upper/lower case doesn't match

 Example Program: see bin\search.ex

 See Also:    wildcard_file, match, upper, lower, compare

─────────────────────────────────────<wrap>─────────────────────────────────────

 Syntax:      include graphics.e
           wrap(i)

 Description: Allow text to wrap at the right margin (i = 1) or get truncated
            (i = 0).

 Comments:    By default text will wrap.

              Use wrap() in text modes or pixel-graphics modes when you
              are displaying long lines of text.

 Example:     puts(1, repeat('x', 100) & "\n\n")
           -- now have a line of 80 'x' followed a line of 20 more 'x'
           wrap(0)
           puts(1, repeat('x', 100) & "\n\n")
           -- creates just one line of 80 'x'

 See Also:    puts, position

───────────────────────────────────<xor_bits>───────────────────────────────────

 Syntax:      x3 = xor_bits(x1, x2)

 Description: Perform the logical XOR (exclusive OR) operation on
              corresponding bits in x1 and x2. A bit in x3 will be 1
              when one of the two corresponding bits in x1 or x2 is 1,
              and the other is 0.

 Comments:    The arguments to this function may be atoms or sequences. The
           rules for arithmetic 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.

 Example 1:   a = xor_bits(#0110, #1010)
              -- a is #1100

 See Also:    and_bits, or_bits, not_bits, int_to_bits