Platform:	WIN32
Syntax:	include misc.e i = instance()
Description:	Return a handle to the current program.
Comments:	This handle value can be passed to various Windows routines to get information about the current program that is running, i.e. your program. Each time a user starts up your program, a different instance will be created. In C, this is the first parameter to WinMain(). On DOS32 and Linux/FreeBSD, instance() always returns 0.
See Also:	platform.doc

Syntax:	include machine.e s = int_to_bits(a, i)
Description:	Return 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/xor/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, operations on sequences

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

Syntax:	i = integer(x)
Description:	Return 1 if x is an integer in the range -1073741824 to +1073741823. 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

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

Syntax:	include file.e i1 = lock_file(fn, i2, s)
Description:	When multiple processes can simultaneously access a file, some kind of locking mechanism may be needed to avoid mangling the contents of the file, or causing erroneous data to be read from the file. lock_file() attempts to place a lock on an open file, fn, to stop other processes from using the file while your program is reading it or writing it. Under Linux/FreeBSD, there are two types of locks that you can request using the i2 parameter. (Under DOS32 and WIN32 the i2 parameter is ignored, but should be an integer.) Ask for a shared lock when you intend to read a file, and you want to temporarily block other processes from writing it. Ask for an exclusive lock when you intend to write to a file and you want to temporarily block other processes from reading or writing it. It's ok for many processes to simultaneously have shared locks on the same file, but only one process can have an exclusive lock, and that can happen only when no other process has any kind of lock on the file. file.e contains the following declaration:
	global constant LOCK_SHARED = 1, LOCK_EXCLUSIVE = 2
	On DOS32 and WIN32 you can lock a specified portion of a file using the s parameter. s is a sequence of the form: {first_byte, last_byte}. It indicates the first byte and last byte in the file, that the lock applies to. Specify the empty sequence {}, if you want to lock the whole file. In the current release for Linux/FreeBSD, locks always apply to the whole file, and you should specify {} for this parameter. If it is successful in obtaining the desired lock, lock_file() will return 1. If unsuccessful, it will return 0. lock_file() does not wait for other processes to relinquish their locks. You may have to call it repeatedly, before the lock request is granted.
Comments:	On Linux/FreeBSD, these locks are called advisory locks, which means they aren't enforced by the operating system. It is up to the processes that use a particular file to cooperate with each other. A process can access a file without first obtaining a lock on it. On WIN32 and DOS32, locks are enforced by the operating system.
	On DOS32, lock_file() is more useful when file sharing is enabled. It will typically return 0 (unsuccessful) under plain MS-DOS, outside of Windows.
Example:
	include misc.e include file.e integer v atom t v = open("visitor_log", "a") -- open for append t = time() while not lock_file(v, LOCK_EXCLUSIVE, {}) do if time() > t + 60 then puts(1, "One minute already ... I can't wait forever!\n") abort(1) end if sleep(5) -- let other processes run end while puts(v, "Yet another visitor\n") unlock_file(v, {}) close(v)
See Also:	unlock_file, flush, sleep

Platform:	DOS32
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:	lock_memory() should only be used in the highly-specialized situation where you have set up your own DOS hardware interrupt handler using machine code. When a hardware interrupt occurs, it is not possible for the operating system to retrieve any code or data that has been swapped out, so you need to protect any blocks of machine code or data that will be needed in servicing the interrupt.
Example Program:	demo\dos32\hardint.ex
See Also:	get_vector, set_vector

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

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

Syntax:	x1 = machine_func(a, x)
Description:	see machine_proc() below

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 might cause a machine exception if done incorrectly.
See Also:	machine_func

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

Syntax:	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 much faster.
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

Syntax:	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 much faster.
Example:
	destination = allocate(1000) mem_set(destination, ' ', 1000) -- 1000 consecutive bytes in memory will be set to 32 -- (the ASCII code for ' ')
See Also:	mem_copy, peek, poke, allocate, allocate_low

Platform:	WIN32
Syntax:	include msgbox.e i = message_box(s1, s2, x)
Description:	Display a window with title s2, containing the message string s1. x determines the combination of buttons that will be available for the user to press, plus some other characteristics. x can be an atom or a sequence. A return value of 0 indicates a failure to set up the window.
Comments:	See msgbox.e for a complete list of possible values for x and i.
Example:
	response = message_box("Do you wish to proceed?", "My Application", MB_YESNOCANCEL) if response = IDCANCEL or response = IDNO then abort(1) end if
Example Program:	demo\win32\email.exw

Platform:	DOS32, Linux
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. Under Linux, mouse_events() currently has no effect.
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

Platform:	DOS32, Linux
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(), will also turn the pointer on (once). Under Linux, mouse_pointer() currently has no effect
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

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

Syntax:	i = object(x)
Description:	Test if x is of type object. This will always be true, so object() will always return 1.
Comments:	All predefined and user-defined types can also be used as functions to test if a value belongs to the type. object() is included just for completeness. It always returns 1.
Example:
	? object({1,2,3}) -- always prints 1
See Also:	integer, atom, sequence

Syntax:	fn = open(st1, st2)
Description:	Open a file or device, to get the file number. -1 is returned if the open fails. st1 is the path name of the file or device. st2 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. Note: on some versions of DOS, a control-Z typed by the user might cause standard input to permanently appear to be at the end-of-file, until the DOS window is closed. 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 on DOS or Windows 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 Currently, files up to 2 Gb in size can be handled. Beyond that, some file operations may not work correctly. This limit will likely be increased in the future.
Comments:	DOS32: When running under Windows 95 or later, 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. WIN32, Linux and FreeBSD: Long filenames are fully supported for reading and writing and creating. DOS32: Be careful not to use the special device names in a file name, even if you add an extension. e.g. CON.TXT, CON.DAT, CON.JPG etc. all refer to the CON device, not a file.
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, lock_file

Platform:	WIN32, Linux, FreeBSD
Syntax:	include dll.e a = open_dll(st)
Description:	Open a Windows dynamic link library (.dll) file, or a Linux or FreeBSD shared library (.so) file. A 32-bit address will be returned, or 0 if the .dll can't be found. st can be a relative or an absolute file name. Windows will use the normal search path for locating .dll files.
Comments:	The value returned by open_dll() can be passed to define_c_proc(), define_c_func(), or define_c_var(). You can open the same .dll or .so file multiple times. No extra memory is used and you'll get the same number returned each time. Euphoria will close the .dll for you automatically at the end of execution.
Example:
	atom user32 user32 = open_dll("user32.dll") if user32 = 0 then puts(1, "Couldn't open user32.dll!\n") end if
See Also:	define_c_func, define_c_proc, define_c_var, c_func, c_proc, platform.doc

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