Euphoria - Library Routines

A large number of library routines are provided. Some are built right into the interpreter, ex.exe, exw.exe or exu. Others are written in Euphoria and you must include one of the .e files in euphoria\include directory to use them.

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

S.No	Prefix & Description
1	x a general object (atom or sequence)
2	s a sequence
3	a an atom
4	i an integer
5	fn an integer used as a file number
6	st a string sequence, or single-character atom

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
object	−	test if an object is an object (always true)

Sequence Manipulation

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

Searching and Sorting

compare	−	compare two objects
equal	−	test if two objects are identical
find	−	find an object in a sequence - start searching from element number 1
find_from	−	find an object in a sequence - start searching from any element number
match	−	find a sequence as a slice of another sequence - start searching from element number 1
match_from	−	find a sequence as a slice of another sequence - start searching from any element number
sort	−	sort the elements of a sequence into ascending order
custom_sort	−	sort the elements of a sequence based on a compare function that you supply

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

Math

These routines can be applied to individual atoms or to sequences of values.

sqrt	−	calculate the square root of an object
rand	−	generate random numbers
sin	−	calculate the sine of an angle
arcsin	−	calculate the angle with a given sine
cos	−	calculate the cosine of an angle
arccos	−	calculate the angle with a given cosine
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
PI	−	the mathematical value PI (3.14159...)

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

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

open	−	open a file or device
close	−	close a file or device
flush	−	flush out buffered data to a file or device
lock_file	−	lock a file or device
unlock_file	−	unlock a file or device
print	−	print a Euphoria object on one line, with braces and commas {,,} to show the structure
pretty_print	−	print a Euphoria object in a nice readable form, using multiple lines and appropriate indentation
? x	−	shorthand for print(1, x)
sprint	−	return a printed Euphoria object as a string sequence
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_bytes	−	read the next n bytes from a file or device
prompt_string	−	prompt the user to enter a string
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
prompt_number	−	prompt the user to enter a number
value	−	read the representation of any Euphoria object from a string
seek	−	move to any byte position within an open file
where	−	report the current byte position in an open file
current_dir	−	return the name of the current directory
chdir	−	change to a new current directory
dir	−	return complete info on all files in a directory
walk_dir	−	recursively walk through 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

Mouse Support (DOS32 and Linux)

On Windows XP, if you want the DOS mouse to work in a (non-full-screen) window, you must disable QuickEdit mode in the Properties for the DOS Window.

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

Operating System

time	−	number of seconds since a fixed point in the past
tick_rate	−	set the number of clock ticks per second (DOS32)
date	−	current year, month, day, hour, minute, second etc.
command_line	−	command-line used to run this program
getenv	−	get value of an environment variable
system	−	execute an operating system command line
system_exec	−	execute a program and get its exit code
abort	−	terminate execution
sleep	−	suspend execution for a period of time
platform	−	find out which operating system are we running on

Special Machine-Dependent Routines

machine_func	−	specialized internal operations with a return value
machine_proc	−	specialized internal operations with no return value

Debugging

trace	−	dynamically turns tracing on or off
profile	−	dynamically turns profiling on or off

Graphics & Sound

The following routines let you display information on the screen. In DOS, the PC screen can be placed into one of many graphics modes.
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 (DOS32)
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 (DOS32)
all_palette	−	change color for all color numbers (DOS32)
get_all_palette	−	get the palette values for all colors (DOS32)
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 (DOS32)
set_active_page	−	change the page currently being written to (DOS32)
get_display_page	−	return the page currently being displayed (DOS32)
set_display_page	−	change the page currently being displayed (DOS32)
sound	−	make a sound on the PC speaker (DOS32)

The following routines work in text in modes only

cursor	−	select cursor shape
text_rows	−	set number of lines on text screen
get_screen_char	−	get one character from the screen
put_screen_char	−	put one or more characters on the 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 (DOS32)

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

Multitasking

task_clock_start	−	restart the scheduler's clock
task_clock_stop	−	stop the scheduler's clock
task_create	−	create a new task
task_list	−	get a list of all tasks
task_schedule	−	schedule a task for execution
task_self	−	return the task id of the current task
task_status	−	the current status (active, suspended, terminated) of a task
task_suspend	−	Suspend a task.
task_yield	−	Yield control, so the scheduler can pick a new task to run.