Euphoria v4.0 svn3117

8.5.2.10 get_integer16

include std/io.e 
public function get_integer16(integer fh)

Read the next two bytes from a file and returns them as a single integer.

8.5.2.10.1 Parameters:

fh : an integer, the handle to an open file to read from.

8.5.2.10.2 Returns:

An atom, made of the bytes that could be read from the file.

8.5.2.10.3 Comments:

This function is normally used with files opened in binary mode, "rb".
Assumes that there at least two bytes available to be read.

8.5.2.10.4 Example 1:

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

8.5.2.10.5 See Also:

8.5.2.11 put_integer32

include std/io.e 
public procedure put_integer32(integer fh, integer val)

Write the supplied integer as four bytes to a file.

8.5.2.11.1 Parameters:

fh : an integer, the handle to an open file to write to.
val : an integer

8.5.2.11.2 Comments:

This function is normally used with files opened in binary mode, "wb".

8.5.2.11.3 Example 1:

 
integer fn 
fn = open("temp", "wb") 
 
put_integer32(fn, 1234)

8.5.2.11.4 See Also:

8.5.2.12 put_integer16

include std/io.e 
public procedure put_integer16(integer fh, integer val)

Write the supplied integer as two bytes to a file.

8.5.2.12.1 Parameters:

fh : an integer, the handle to an open file to write to.
val : an integer

8.5.2.12.2 Comments:

This function is normally used with files opened in binary mode, "wb".

8.5.2.12.3 Example 1:

 
integer fn 
fn = open("temp", "wb") 
 
put_integer16(fn, 1234)

8.5.2.12.4 See Also:

mod, Relational operators, Operations on sequences

8.5.2.13 get_dstring

include std/io.e 
public function get_dstring(integer fh, integer delim = 0)

Read a delimited byte string from an opened file .

8.5.2.13.1 Parameters:

fh : an integer, the handle to an open file to read from.
delim : an integer, the delimiter that marks the end of a byte string. If omitted, a zero is assumed.

8.5.2.13.2 Returns:

An sequence, made of the bytes that could be read from the file.

8.5.2.13.3 Comments:

If the end-of-file is found before the delimiter, the delimiter is appended to the returned string.

8.5.2.13.4 Example 1:

 
integer fn 
fn = open("temp", "rb")  -- an existing file 
 
sequence text 
text = get_dstring(fn)	-- Get a zero-delimited string 
text = get_dstring(fn, '$')	-- Get a '$'-delimited string

8.5.2.13.5 See Also:

getc, gets, get_bytes, get_integer32

8.5.3 Low Level File/Device Handling

8.5.3.1 LOCK_SHARED

include std/io.e 
public enum LOCK_SHARED

8.5.3.2 LOCK_EXCLUSIVE

include std/io.e 
public enum LOCK_EXCLUSIVE

8.5.3.3 file_number

include std/io.e 
public type file_number(integer f)

File number type

8.5.3.4 file_position

include std/io.e 
public type file_position(atom p)

File position type

8.5.3.5 lock_type

include std/io.e 
public type lock_type(integer t)

Lock Type

8.5.3.6 byte_range

include std/io.e 
public type byte_range(sequence r)

Byte Range Type

8.5.3.7 open

<built-in> function open(sequence path, sequence mode, integer cleanup = 0)

Open a file or device, to get the file number.

8.5.3.7.1 Parameters:

path : a string, the path to the file or device to open.
mode : a string, the mode being used o open the file.
cleanup : an integer, if 0, then the file must be manually closed by the coder. If 1, then the file will be closed when either the file handle's references goes to 0, or if called as a parameter to delete().

8.5.3.7.2 Returns:

A small integer, -1 on failure, else 0 or more.

8.5.3.7.3 Errors:

There is a limit on the number of files that can be simultaneously opened, currently 40. If this limit is reached, the next attempt to open() a file will error out.

The length of path should not exceed 1,024 characters.

8.5.3.7.4 Comments:

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

On Windows, 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. On Unix, all files are binary files, so "r" mode and "rb" mode are equivalent, as are "w" and "wb", "u" and "ub", and "a" and "ab".

8.5.3.7.6 Some typical devices that you can open on 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

Close a file or device when done with it, flushing out any still-buffered characters prior.

WIN32 and Unix: Long filenames are fully supported for reading and writing and creating.

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

8.5.3.7.7 Example 1:

integer file_num, file_num95 
sequence first_line 
constant ERROR = 2 
 
file_num = open("my_file", "r") 
if file_num = -1 then 
    puts(ERROR, "couldn't open my_file\n") 
else 
    first_line = gets(file_num) 
end if 
 
file_num = open("PRN", "w") -- open printer for output 
 
-- on Windows 95: 
file_num95 = open("big_directory_name\\very_long_file_name.abcdefg", 
                  "r") 
if file_num95 != -1 then 
    puts(STDOUT, "it worked!\n") 
end if

8.5.3.8 close

<built-in> procedure close(atom fn)

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

8.5.3.8.1 Parameters:

fn : an integer, the handle to the file or device to query.

8.5.3.8.2 Errors:

The target file or device must be open.

8.5.3.8.3 Comments:

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

8.5.3.9 seek

include std/io.e 
public function seek(file_number fn, file_position pos)

Seek (move) to any byte position in a file.

8.5.3.9.1 Parameters:

fn : an integer, the handle to the file or device to seek()
pos : an atom, either an absolute 0-based position or -1 to seek to end of file.

8.5.3.9.2 Returns:

An integer, 0 on success, 1 on failure.

8.5.3.9.3 Errors:

The target file or device must be open.

8.5.3.9.4 Comments:

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. It is possible to seek past the end of a file. If you seek past the end of the file, and write some data, undefined bytes will be inserted into the gap between the original end of file and your new data.

After seeking and reading (writing) a series of bytes, you may need to call seek() explicitly before you switch to writing (reading) bytes, even though the file position should already be what you want.

This function is normally used with files opened in binary mode. In text mode, Windows converts CR LF to LF on input, and LF to CR LF on output, which can cause great confusion when you are trying to count bytes because seek() counts the Windows end of line sequences as two bytes, even if the file has been opened in text mode.

8.5.3.9.5 Example 1:

include std/io.e 
 
integer fn 
fn = open("my.data", "rb") 
-- read and display first line of file 3 times: 
for i = 1 to 3 do 
    puts(STDOUT, gets(fn)) 
    if seek(fn, 0) then 
        puts(STDOUT, "rewind failed!\n") 
    end if 
end for

8.5.3.9.6 See Also:

get_bytes, puts, where

8.5.3.10 where

include std/io.e 
public function where(file_number fn)

Retrieves the current file position for an opened file or device.

8.5.3.10.1 Parameters:

fn : an integer, the handle to the file or device to query.

8.5.3.10.2 Returns:

An atom, the current byte position in the file.

8.5.3.10.3 Errors:

The target file or device must be open.

8.5.3.10.4 Comments:

The file position is is the place in the file where the next byte will be read from, or written to. It is updated by reads, writes and seeks on the file. This procedure always counts Windows end of line sequences (CR LF) as two bytes even when the file number has been opened in text mode.

8.5.3.11 flush

include std/io.e 
public procedure flush(file_number fn)

Force writing any buffered data to an open file or device.

8.5.3.11.1 Parameters:

fn : an integer, the handle to the file or device to close.

8.5.3.11.2 Errors:

The target file or device must be open.

8.5.3.11.3 Comments:

When you write data to a file, EUPHORIA normally stores the data in a memory buffer until a large enough chunk of data has accumulated. This large chunk can then be written to disk very efficiently. Sometimes you may want to force, or flush, all data out immediately, even if the memory buffer is not full. To do this you must call flush(fn), where fn is the file number of a file open for writing or appending.

When a file is closed, (see close()), all buffered data is flushed out. When a program terminates, all open files are flushed and closed automatically. Use flush() when another process may need to see all of the data written so far, but you are not ready to close the file yet. flush() is also used in crash routines, where files may not be closed in the cleanest possible way.

8.5.3.11.4 Example 1:

f = open("file.log", "w") 
puts(f, "Record#1\n") 
puts(STDOUT, "Press Enter when ready\n") 
 
flush(f)  -- This forces "Record #1" into "file.log" on disk. 
          -- Without this, "file.log" will appear to have 
          -- 0 characters when we stop for keyboard input. 
 
s = gets(0) -- wait for keyboard input

8.5.3.11.5 See Also:

close, crash_routine

8.5.3.12 lock_file

include std/io.e 
public function lock_file(file_number fn, lock_type t, byte_range r = {})

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.

8.5.3.12.1 Parameters:

fn : an integer, the handle to the file or device to (partially) lock.
t : an integer which defines the kind of lock to apply.
r : a sequence, defining a section of the file to be locked, or {} for the whole file (the default).

8.5.3.12.2 Returns:

An integer, 0 on failure, 1 on success.

8.5.3.12.3 Errors:

The target file or device must be open.

8.5.3.12.4 Comments:

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 Unix, there are two types of locks that you can request using the t parameter. (Under WIN32 the parameter t 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. io.e contains the following declarations:

public enum 
    LOCK_SHARED, 
    LOCK_EXCLUSIVE

On /WIN32 you can lock a specified portion of a file using the r parameter. r 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, or don't specify it at all, as this is the default. In the current release for Unix, locks always apply to the whole file, and you should use this default value.

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.

On Unix, 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 locks are enforced by the operating system.

8.5.3.12.5 Example 1:

include std/io.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(STDOUT, "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)

8.5.3.12.6 See Also:

unlock_file

8.5.3.13 unlock_file

include std/io.e 
public procedure unlock_file(file_number fn, byte_range r = {})

Unlock (a portion of) an open file.

8.5.3.13.1 Parameters:

fn : an integer, the handle to the file or device to (partially) lock.
r : a sequence, defining a section of the file to be locked, or {} for the whole file (the default).

8.5.3.13.2 Errors:

The target file or device must be open.

8.5.3.13.3 Comments:

You must have previously locked the file using lock_file(). On WIN32 you can unlock a range of bytes within a file by specifying the r as {first_byte, last_byte}. The same range of bytes must have been locked by a previous call to lock_file(). On Unix you can currently only lock or unlock an entire file. r should be {} when you want to unlock an entire file. On Unix, r must always be {}, which is the default.

You should unlock a file as soon as possible so other processes can use it.

Any files that you have locked, will automatically be unlocked when your program terminates.

8.5.3.13.4 See Also:

lock_file

8.5.4 File Reading/Writing

8.5.4.1 read_lines

include std/io.e 
public function read_lines(object file)

Read the contents of a file as a sequence of lines.

8.5.4.1.1 Parameters:

file : an object, either a file path or the handle to an open file. If this is an empty string, STDIN (the console) is used.

8.5.4.1.2 Returns:

A sequence, made of lines from the file, as gets could read them.

8.5.4.1.3 Comments:

If file was a sequence, the file will be closed on completion. Otherwise, it will remain open, but at end of file.

8.5.4.1.4 Example 1:

data = read_lines("my_file.txt") 
-- data contains the entire contents of ##my_file.txt##, 1 sequence per line: 
-- {"Line 1", "Line 2", "Line 3"}

8.5.4.1.5 Example 2:

fh = open("my_file.txt", "r") 
data = read_lines(fh) 
close(fh) 
 
-- data contains the entire contents of ##my_file.txt##, 1 sequence per line: 
-- {"Line 1", "Line 2", "Line 3"}

8.5.4.1.6 See Also:

gets, write_lines, read_file

8.5.4.2 process_lines

include std/io.e 
public function process_lines(object file, integer proc, object user_data = 0)

Process the contents of a file, one line at a time.

8.5.4.2.1 Parameters:

file : an object. Either a file path or the handle to an open file. An empty string signifies STDIN - the console keyboard.
proc : an integer. The routine_id of a function that will process the line.
user_data : on object. This is passed untouched to proc for each line.

8.5.4.2.2 Returns:

An object. If 0 then all the file was processed successfully. Anything else means that something went wrong and this is whatever value was returned by proc.

8.5.4.2.3 Comments:

The function proc must accept three parameters ...

A sequence: The line to process. It will not contain an end-of-line character.
An integer: The line number.
An object : This is the user_data that was passed to process_lines.

If file was a sequence, the file will be closed on completion. Otherwise, it will remain open, and be positioned where ever reading stopped.

8.5.4.2.4 Example:

-- Format each supplied line according to the format pattern supplied as well. 
function show(sequence aLine, integer line_no, object data) 
  writefln( data[1], {line_no, aLine}) 
  if data[2] > 0 and line_no = data[2] then 
  	return 1 
  else 
  	return 0 
  end if 
end function 
-- Show the first 20 lines. 
process_lines("sample.txt", routine_id("show"), {"[1z:4] : [2]", 20})

8.5.4.2.5 See Also:

gets, read_lines, read_file

8.5.4.3 write_lines

include std/io.e 
public function write_lines(object file, sequence lines)

Write a sequence of lines to a file.

8.5.4.3.1 Parameters:

file : an object, either a file path or the handle to an open file.
lines : the sequence of lines to write

8.5.4.3.2 Returns:

An integer, 1 on success, -1 on failure.

8.5.4.3.3 Errors:

If puts() cannot write some line of text, a runtime error will occur.

8.5.4.3.4 Comments:

If file was a sequence, the file will be closed on completion. Otherwise, it will remain open, but at end of file.

Whatever integer the lines in lines holds will be truncated to its 8 lowest bits so as to fall in the 0.255 range.

8.5.4.3.5 Example 1:

if write_lines("data.txt", {"This is important data", "Goodbye"}) != -1 then 
    puts(STDERR, "Failed to write data\n") 
end if

8.5.4.3.6 See Also:

read_lines, write_file, puts

8.5.4.4 append_lines

include std/io.e 
public function append_lines(sequence file, sequence lines)

Append a sequence of lines to a file.

8.5.4.4.1 Parameters:

file : an object, either a file path or the handle to an open file.
lines : the sequence of lines to write

8.5.4.4.2 Returns:

An integer, 1 on success, -1 on failure.

8.5.4.4.3 Errors:

If puts() cannot write some line of text, a runtime error will occur.

8.5.4.4.4 Comments:

file is opened, written to and then closed.

8.5.4.4.5 Example 1:

if append_lines("data.txt", {"This is important data", "Goodbye"}) != -1 then 
    puts(STDERR, "Failed to append data\n") 
end if

8.5.4.4.6 See Also:

write_lines, puts

8.5.4.5 BINARY_MODE

include std/io.e 
public enum BINARY_MODE

8.5.4.6 TEXT_MODE

include std/io.e 
public enum TEXT_MODE

8.5.4.7 UNIX_TEXT

include std/io.e 
public enum UNIX_TEXT

8.5.4.8 DOS_TEXT

include std/io.e 
public enum DOS_TEXT

8.5.4.9 ANSI

include std/io.e 
public enum ANSI

8.5.4.10 UTF

include std/io.e 
public enum UTF

8.5.4.11 UTF_8

include std/io.e 
public enum UTF_8

8.5.4.12 UTF_16

include std/io.e 
public enum UTF_16

8.5.4.13 UTF_16BE

include std/io.e 
public enum UTF_16BE

8.5.4.14 UTF_16LE

include std/io.e 
public enum UTF_16LE

8.5.4.15 UTF_32

include std/io.e 
public enum UTF_32

8.5.4.16 UTF_32BE

include std/io.e 
public enum UTF_32BE

8.5.4.17 UTF_32LE

include std/io.e 
public enum UTF_32LE

8.5.4.18 read_file

include std/io.e 
public function read_file(object file, integer as_text = BINARY_MODE, integer encoding = ANSI)

Read the contents of a file as a single sequence of bytes.

8.5.4.18.1 Parameters:

file : an object, either a file path or the handle to an open file.
as_text : integer, BINARY_MODE (the default) assumes binary mode that causes every byte to be read in, and TEXT_MODE assumes text mode that ensures that lines end with just a Ctrl-J (NewLine) character, and the first byte value of 26 (Ctrl-Z) is interpreted as End-Of-File.
encoding: An integer. One of ANSI, UTF, UTF_8, UTF_16, UTF_16BE, UTF_16LE, UTF_32, UTF_32BE, UTF_32LE. The default is ANSI.

8.5.4.18.2 Returns:

A sequence, holding the entire file.

Comments

When using BINARY_MODE, each byte in the file is returned as an element in the return sequence.
When not using BINARY_MODE, the file will be interpreted as a text file. This means that all line endings will be transformed to a single 0x0A character and the first 0x1A character (Ctrl-Z) will indicate the end of file (all data after this will not be returned to the caller.)
Text files are always returned as UTF_32 encoded files.
Encoding ...

ANSI: no interpretation of the file data is done. All bytes are simply returned as characters.
UTF: The file data is examined to work out which UTF encoding method was used to create the file. If the file starts with a valid Byte Order Marker (BOM) it can quickly decide between UTF_8, UTF_16 and UTF_32. For files without a BOM, if the file is completely valid UTF_8 encoding then that is what is used. Failing that, if there are no null bytes, the ANSI is assumed. Failing that, it is tested for being a valid UTF_16 or UTF_32 format. As a last resort, it will be assumed to be an ANSI file.
UTF_8: Any valid UTF_8 BOM is removed and the data is converted to UTF_32 format before returning. This means that if it contains any invalidly encoded Unicode characters, they will be ignored.
UTF_16: Any valid UTF_16 BOM is removed and the data is converted to UTF_32 format before returning. This means that if it contains any invalidly encoded Unicode characters, they will be ignored.
UTF_16LE: Any valid little-endian UTF_16 BOM is removed and the data is converted to UTF_32 format before returning. This means that if it contains any invalidly encoded Unicode characters, they will be ignored.
UTF_16BE: Any valid big-endian UTF_16 BOM is removed and the data is converted to UTF_32 format before returning. This means that if it contains any invalidly encoded Unicode characters, they will be ignored.
UTF_32: Any valid UTF_32 BOM is removed.
UTF_32LE: Any valid little-endian UTF_32 BOM is removed.
UTF_32BE: Any valid big-endian UTF_32 BOM is removed.

If one of the UTF_32 encodings is supplied, invalid Unicode characters are not stripped out but are returned in the file data.

8.5.4.18.3 Example 1:

data = read_file("my_file.txt") 
-- data contains the entire contents of ##my_file.txt##

8.5.4.18.4 Example 2:

fh = open("my_file.txt", "r") 
data = read_file(fh) 
close(fh) 
 
-- data contains the entire contents of ##my_file.txt##

8.5.4.18.5 Example 3:

data = read_file("my_file.txt", TEXT_MODE, UTF_8) 
-- The UTF encoded contents of ##my_file.txt## is stored in 'data' as UTF_32

8.5.4.18.6 See Also:

write_file, read_lines

8.5.4.19 write_file

include std/io.e 
public function write_file(object file, sequence data, integer as_text = BINARY_MODE, integer encoding = ANSI, integer with_bom = 1)

Write a sequence of bytes to a file.

8.5.4.19.1 Parameters:

file : an object, either a file path or the handle to an open file.
data : the sequence of bytes to write
as_text : integer

BINARY_MODE (the default) assumes binary mode that causes every byte to be written out as is,
TEXT_MODE assumes text mode that causes a NewLine to be written out according to the operating system's end of line convention. In Unix this is Ctrl-J and in Windows this is the pair {Ctrl-L, Ctrl-J}.
UNIX_TEXT ensures that lines are written out with unix style line endings (Ctrl-J).
DOS_TEXT ensures that lines are written out with Windows style line endings {Ctrl-L, Ctrl-J}.

encoding: an integer. One of ANSI, UTF_8, UTF_16LE, UTF_16BE, UTF_32LE, UTF_32BE. The default is ANSI.
with_bom: an integer. Either 0 or 1. If 1 then when encoding as a UTF file, this will prepend a Byte Order Marker (BOM) to the file output.

8.5.4.19.2 Returns:

An integer, 1 on success, -1 on failure.

8.5.4.19.3 Comments:

UTF_16LE, and UTF_32LE create little-endian files, which are the normal ones for Intel based CPUs. Big-endian files are more commonly found on Motorola CPUs.

8.5.4.19.4 Errors:

If puts cannot write data, a runtime error will occur.

8.5.4.19.5 Comments:

When file is a file handle, the file is not closed after writing is finished. When file is a file name, it is opened, written to and then closed.
Note that when writing the file in ony of the text modes, the file is truncated at the first Ctrl-Z character in the input data.

8.5.4.19.6 Example 1:

if write_file("data.txt", "This is important data\nGoodbye") = -1 then 
    puts(STDERR, "Failed to write data\n") 
end if

8.5.4.19.7 See Also:

read_file, write_lines

8.5.4.20 writef

include std/io.e 
public procedure writef(object fm, object data = {}, object fn = 1, object data_not_string = 0)

Write formatted text to a file..

8.5.4.20.1 Parameters:

There are two ways to pass arguments to this function,

Traditional way with first arg being a file handle.

: integer, The file handle.
: sequence, The format pattern.
: object, The data that will be formatted.
data_not_string: object, If not 0 then the data is not a string. By default this is 0 meaning that data could be a single string.

Alternative way with first argument being the format pattern.

: sequence, Format pattern.
: sequence, The data that will be formatted,
: object, The file to receive the formatted output. Default is to the STDOUT device (console).
data_not_string: object, If not 0 then the data is not a string. By default this is 0 meaning that data could be a single string.

8.5.4.20.2 Comments:

With the traditional arguments, the first argument must be an integer file handle.
With the alternative arguments, the thrid argument can be a file name string, in which case it is opened for output, written to and then closed.
With the alternative arguments, the third argument can be a two-element sequence containing a file name string and an output type ("a" for append, "w" for write), in which case it is opened accordingly, written to and then closed.
With the alternative arguments, the third argument can a file handle, in which case it is written to only
The format pattern uses the formatting codes defined in text.e:format.
When the data to be formatted is a single text string, it does not have to be enclosed in braces,

8.5.4.20.3 Example 1:

-- To console 
writef("Today is [4], [u2:3] [3:02], [1:4].", {Year, MonthName, Day, DayName}) 
-- To "sample.txt" 
writef("Today is [4], [u2:3] [3:02], [1:4].", {Year, MonthName, Day, DayName}, "sample.txt") 
-- To "sample.dat" 
integer dat = open("sample.dat", "w") 
writef("Today is [4], [u2:3] [3:02], [1:4].", {Year, MonthName, Day, DayName}, dat) 
-- Appended to "sample.log" 
writef("Today is [4], [u2:3] [3:02], [1:4].", {Year, MonthName, Day, DayName}, {"sample.log", "a"}) 
-- Simple message to console 
writef("A message") 
-- Another console message 
writef(STDERR, "This is a []", "message") 
-- Outputs two numbers 
writef(STDERR, "First [], second []", {65, 100},, 1) -- Note that {65, 100} is also "Ad"

8.5.4.20.4 See Also:

text.e:format, writefln, write_lines

8.5.4.21 writefln

include std/io.e 
public procedure writefln(object fm, object data = {}, object fn = 1, object data_not_string = 0)

Write formatted text to a file, ensuring that a new line is also output.

8.5.4.21.1 Parameters:

fm : sequence, Format pattern.
data : sequence, The data that will be formatted,
fn : object, The file to receive the formatted output. Default is to the STDOUT device (console).
data_not_string: object, If not 0 then the data is not a string. By default this is 0 meaning that data could be a single string.

8.5.4.21.2 Comments:

This is the same as writef, except that it always adds a New Line to the output.
When fn is a file name string, it is opened for output, written to and then closed.
When fn is a two-element sequence containing a file name string and an output type ("a" for append, "w" for write), it is opened accordingly, written to and then closed.
When fn is a file handle, it is written to only
The fm uses the formatting codes defined in text.e:format.

8.5.4.21.3 Example 1:

-- To console 
writefln("Today is [4], [u2:3] [3:02], [1:4].", {Year, MonthName, Day, DayName}) 
-- To "sample.txt" 
writefln("Today is [4], [u2:3] [3:02], [1:4].", {Year, MonthName, Day, DayName}, "sample.txt") 
-- Appended to "sample.log" 
writefln("Today is [4], [u2:3] [3:02], [1:4].", {Year, MonthName, Day, DayName}, {"sample.log", "a"})

8.5.4.21.4 See Also:

text.e:format, writef, write_lines

8.6 Math

---------- Sign and comparisons

---------------- abs

---------------- sign

---------------- max

---------------- min

---------------- ensure_in_range

---------------- ensure_in_list

---------- Roundings and remainders

---------------- remainder

---------------- mod

---------------- trunc

---------------- frac

---------------- intdiv

---------------- floor

---------------- ceil

---------------- round

---------- Trigonometry

---------------- arctan

---------------- tan

---------------- cos

---------------- sin

---------------- arccos

---------------- arcsin

---------------- atan2

---------------- rad2deg

---------------- deg2rad

---------- Logarithms and powers.

---------------- log

---------------- log10

---------------- exp

---------------- power

---------------- sqrt

---------- Hyperbolic trigonometry

---------------- cosh

---------------- sinh

---------------- tanh

---------------- arcsinh

---------------- arccosh

---------------- arctanh

---------- Accumulation

---------------- sum

---------------- product

---------------- or_all

---------- Bitwise operations

---------------- and_bits

---------------- xor_bits

---------------- or_bits

---------------- not_bits

---------------- shift_bits

---------------- rotate_bits

---------------- gcd

---------------- approx

---------------- powof2

---------------- is_even

---------------- is_even_obj

8.6.1 Sign and comparisons

8.6.1.1 abs

include std/math.e 
public function abs(object a)

Returns the absolute value of numbers.

8.6.1.1.1 Parameters:

value : an object, each atom is processed, no matter how deeply nested.

8.6.1.1.2 Returns:

An object, the same shape as value. When value is an atom, the result is the same if not less than zero, and the opposite value otherwise.

8.6.1.1.3 Comments:

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

8.6.1.1.4 Example 1:

x = abs({10.5, -12, 3}) 
-- x is {10.5, 12, 3} 
 
i = abs(-4) 
-- i is 4

8.6.1.1.5 See Also:

sign

8.6.1.2 sign

include std/math.e 
public function sign(object a)

Return -1, 0 or 1 for each element according to it being negative, zero or positive

8.6.1.2.1 Parameters:

value : an object, each atom of which will be acted upon, no matter how deeply nested.

8.6.1.2.2 Returns:

An object, the same shape as value. When value is an atom, the result is -1 if value is less than zero, 1 if greater and 0 if equal.

8.6.1.2.3 Comments:

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

For an atom, sign(x) is the same as compare(x,0).

8.6.1.2.4 Example 1:

i = sign(5) 
i is 1 
 
i = sign(0) 
-- i is 0 
 
i = sign(-2) 
-- i is -1

8.6.1.2.5 See Also:

compare

8.6.1.3 max

include std/math.e 
public function max(object a)

Computes the maximum value among all the argument's elements

8.6.1.3.1 Parameters:

values : an object, all atoms of which will be inspected, no matter how deeply nested.

8.6.1.3.2 Returns:

An atom, the maximum of all atoms in flatten(values).

8.6.1.3.3 Comments:

This function may be applied to an atom or to a sequence of any shape.

8.6.1.3.4 Example 1:

a = max({10,15.4,3}) 
-- a is 15.4

8.6.1.3.5 See Also:

min, compare, flatten

8.6.1.4 min

include std/math.e 
public function min(object a)

Computes the minimum value among all the argument's elements

8.6.1.4.1 Parameters:

values : an object, all atoms of which will be inspected, no matter how deeply nested.

8.6.1.4.2 Returns:

An atom, the minimum of all atoms in flatten(values).

8.6.1.4.3 Comments:

This function may be applied to an atom or to a sequence of any shape.

8.6.1.4.4 Example 1:

a = min({10,15.4,3}) 
-- a is 3

8.6.1.5 ensure_in_range

include std/math.e 
public function ensure_in_range(object item, sequence range_limits)

Ensures that the item is in a range of values supplied by inclusive range_limits

8.6.1.5.1 Parameters:

item : The object to test for.
range_limits : A sequence of two or more elements. The first is assumed to be the smallest value and the last is assumed to be the highest value.

8.6.1.5.2 Returns:

A object, If item is lower than the first item in the range_limits it returns the first item. If item is higher than the last element in the range_limits it returns the last item. Otherwise it returns item.

8.6.1.5.3 Example 1:

object valid_data = ensure_in_range(user_data, {2, 75}) 
if not equal(valid_data, user_data) then 
    errmsg("Invalid input supplied. Using %d instead.", valid_data) 
end if 
procA(valid_data)

8.6.1.6 ensure_in_list

include std/math.e 
public function ensure_in_list(object item, sequence list, integer default = 1)

Ensures that the item is in a list of values supplied by list

8.6.1.6.1 Parameters:

item : The object to test for.
list : A sequence of elements that item should be a member of.
default : an integer, the index of the list item to return if item is not found. Defaults to 1.

8.6.1.6.2 Returns:

An object, if item is not in the list, it returns the list item of index default, otherwise it returns item.

8.6.1.6.3 Comments:

If default is set to an invalid index, the first item on the list is returned instead when item is not on the list.

8.6.1.6.4 Example 1:

object valid_data = ensure_in_list(user_data, {100, 45, 2, 75, 121}) 
if not equal(valid_data, user_data) then 
    errmsg("Invalid input supplied. Using %d instead.", valid_data) 
end if 
procA(valid_data)

8.6.2 Roundings and remainders

8.6.2.1 remainder

<built-in> function remainder(object dividend, object divisor)

Compute the remainder of the division of two objects using truncated division.

8.6.2.1.1 Parameters:

dividend : any EUPHORIA object.
divisor : any EUPHORIA object.

8.6.2.1.2 Returns:

An object, the shape of which depends on dividend's and divisor's. For two atoms, this is the remainder of dividing dividend by divisor, with dividend's sign.

8.6.2.1.3 Errors:

If any atom in divisor is 0, this is an error condition as it amounts to an attempt to divide by zero.
If both dividend and divisor are sequences, they must be the same length as each other.

8.6.2.1.4 Comments:

There is a integer N such that dividend = N * divisor + result.
The result has the sign of dividend and lesser magnitude than divisor.
The result has the same sign as the dividend.
This differs from mod() in that when the operands' signs are different this function rounds dividend/divisior towards zero whereas mod() rounds away from zero.

The arguments to this function may be atoms or sequences. The rules for operations on sequences apply, and determine the shape of the returned object.

8.6.2.1.5 Example 1:

a = remainder(9, 4) 
-- a is 1

8.6.2.1.6 Example 2:

s = remainder({81, -3.5, -9, 5.5}, {8, -1.7, 2, -4}) 
-- s is {1, -0.1, -1, 1.5}

8.6.2.1.7 Example 3:

s = remainder({17, 12, 34}, 16) 
-- s is {1, 12, 2}

8.6.2.1.8 Example 4:

s = remainder(16, {2, 3, 5}) 
-- s is {0, 1, 1}

8.6.2.1.9 See Also:

8.6.2.2 mod

include std/math.e 
public function mod(object x, object y)

Compute the remainder of the division of two objects using floored division.

8.6.2.2.1 Parameters:

dividend : any EUPHORIA object.
divisor : any EUPHORIA object.

8.6.2.2.2 Returns:

An object, the shape of which depends on dividend's and divisor's. For two atoms, this is the remainder of dividing dividend by divisor, with divisor's sign.

8.6.2.2.3 Comments:

There is a integer N such that dividend = N * divisor + result.
The result is non-negative and has lesser magnitude than divisor . n needs not fit in an EUPHORIA integer.
The result has the same sign as the dividend.
The arguments to this function may be atoms or sequences. The rules for operations on sequences apply, and determine the shape of the returned object.
When both arguments have the same sign, mod() and remainder() return the same result.
This differs from remainder() in that when the operands' signs are different this function rounds dividend/divisior away from zero whereas remainder() rounds towards zero.

8.6.2.2.4 Example 1:

a = mod(9, 4) 
-- a is 1

8.6.2.2.5 Example 2:

s = mod({81, -3.5, -9, 5.5}, {8, -1.7, 2, -4}) 
-- s is {1,-0.1,1,-2.5}

8.6.2.2.6 Example 3:

s = mod({17, 12, 34}, 16) 
-- s is {1, 12, 2}

8.6.2.2.7 Example 4:

s = mod(16, {2, 3, 5}) 
-- s is {0, 1, 1}

8.6.2.2.8 See Also:

remainder, Relational operators, Operations on sequences

8.6.2.3 trunc

include std/math.e 
public function trunc(object x)

Return the integer portion of a number.

8.6.2.3.1 Parameters:

value : any EUPHORIA object.

8.6.2.3.2 Returns:

An object, the shape of which depends on values 's. Each item in the returned object will be an integer. These are the same corresponding items in value except with any fractional portion removed.

8.6.2.3.3 Comments:

This is essentially done by always rounding towards zero. The floor() function rounds towards negative infinity, which means it rounds towards zero for positive values and away from zero for negative values.
Note that trunc(x) + frac(x) = x

8.6.2.3.4 Example 1:

a = trunc(9.4) 
-- a is 9

8.6.2.3.5 Example 2:

s = trunc({81, -3.5, -9.999, 5.5}) 
-- s is {81,-3, -9, 5}

8.6.2.3.6 See Also:

floor frac

8.6.2.4 frac

include std/math.e 
public function frac(object x)

Return the fractional portion of a number.

8.6.2.4.1 Parameters:

value : any EUPHORIA object.

8.6.2.4.2 Returns:

An object, the shape of which depends on values 's. Each item in the returned object will be the same corresponding items in value except with the integer portion removed.

8.6.2.4.3 Comments:

Note that trunc(x) + frac(x) = x

8.6.2.4.4 Example 1:

a = frac(9.4) 
-- a is 0.4

8.6.2.4.5 Example 2:

s = frac({81, -3.5, -9.999, 5.5}) 
-- s is {0, -0.5, -0.999, 0.5}

8.6.2.4.6 See Also:

trunc

8.6.2.5 intdiv

include std/math.e 
public function intdiv(object a, object b)

Return an integral division of two objects.

8.6.2.5.1 Parameters:

divided : any EUPHORIA object.
divisor : any EUPHORIA object.

8.6.2.5.2 Returns:

An object, which will be a sequence if either dividend or divisor is a sequence.

8.6.2.5.3 Comments:

This calculates how many non-empty sets when dividend is divided by divisor.
The result's sign is the same as the dividend's sign.

8.6.2.5.4 Example 1:

object Tokens = 101 
object MaxPerEnvelope = 5 
integer Envelopes = intdiv( Tokens, MaxPerEnvelope) --> 21

8.6.2.6 floor

<built-in> function floor(object value)

Rounds value down to the next integer less than or equal to value. It does not simply truncate the fractional part, but actually rounds towards negative infinity.

8.6.2.6.1 Parameters:

value : any EUPHORIA object; each atom in value will be acted upon.

8.6.2.6.2 Returns:

An object, the same shape as value but with each item guarenteed to be an integer less than or equal to the corresponding item in value.

8.6.2.6.3 Example 1:

y = floor({0.5, -1.6, 9.99, 100}) 
-- y is {0, -2, 9, 100}

8.6.2.6.4 See Also:

ceil, round

8.6.2.7 ceil

include std/math.e 
public function ceil(object a)

Computes the next integer equal or greater than the argument.

8.6.2.7.1 Parameters:

value : an object, each atom of which processed, no matter how deeply nested.

8.6.2.7.2 Returns:

An object, the same shape as value. Each atom in value is returned as an integer that is the smallest integer equal to or greater than the corresponding atom in value .

8.6.2.7.3 Comments:

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

ceil(X) is 1 more than floor(X) for non-integers. For integers, X = floor(X) = ceil(X).

8.6.2.7.4 Example 1:

sequence nums 
nums = {8, -5, 3.14, 4.89, -7.62, -4.3} 
nums = ceil(nums) -- {8, -5, 4, 5, -7, -4}

8.6.2.7.5 See Also:

floor, round

8.6.2.8 round

include std/math.e 
public function round(object a, object precision = 1)

Return the argument's elements rounded to some precision

8.6.2.8.1 Parameters:

value : an object, each atom of which will be acted upon, no matter how deeply nested.
precision : an object, the rounding precision(s). If not passed, this defaults to 1.

8.6.2.8.2 Returns:

An object, the same shape as value. When value is an atom, the result is that atom rounded to the nearest integer multiple of 1/precision.

8.6.2.8.3 Comments:

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

8.6.2.8.4 Example 1:

round(5.2) -- 5 
round({4.12, 4.67, -5.8, -5.21}, 10) -- {4.1, 4.7, -5.8, -5.2} 
round(12.2512, 100) -- 12.25

8.6.2.8.5 See Also:

floor, ceil

8.6.3 Trigonometry

8.6.3.1 arctan

<built-in> function arctan(object tangent)

Return an angle with given tangent.

8.6.3.1.1 Parameters:

tangent : an object, each atom of which will be converted, no matter how deeply nested.

8.6.3.1.2 Returns:

An object, of the same shape as tangent. For each atom in flatten(tangent), the angle with smallest magnitude that has this atom as tangent is computed.

8.6.3.1.3 Comments:

All atoms in the returned value lie between -PI/2 and PI/2, exclusive.

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

arctan() is faster than arcsin() or arccos().

8.6.3.1.4 Example 1:

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

8.6.3.1.5 See Also:

arcsin, arccos, tan, flatten

8.6.3.2 tan

<built-in> function tan(object angle)

Return the tangent of an angle, or a sequence of angles.

8.6.3.2.1 Parameters:

angle : an object, each atom of which will be converted, no matter how deeply nested.

8.6.3.2.2 Returns:

An object, of the same shape as angle. Each atom in the flattened angle is replaced by its tangent.

8.6.3.2.3 Errors:

If any atom in angle is an odd multiple of PI/2, an error occurs, as its tangent would be infinite.

8.6.3.2.4 Comments:

This function may be applied to an atom or to all elements of a sequence of arbitrary shape, recursively.

8.6.3.2.5 Example 1:

t = tan(1.0) 
-- t is 1.55741

8.6.3.2.6 See Also:

sin, cos, arctan

8.6.3.3 cos

<built-in> function cos(object angle)

Return the cosine of an angle expressed in radians

8.6.3.3.1 Parameters:

angle : an object, each atom of which will be converted, no matter how deeply nested.

8.6.3.3.2 Returns:

An object, the same shape as angle. Each atom in angle is turned into its cosine.

8.6.3.3.3 Comments:

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

The cosine of an angle is an atom between -1 and 1 inclusive. 0.0 is hit by odd multiples of PI/2 only.

8.6.3.3.4 Example 1:

x = cos({.5, .6, .7}) 
-- x is {0.8775826, 0.8253356, 0.7648422}

8.6.3.3.5 See Also:

sin, tan, arccos, PI, deg2rad

8.6.3.4 sin

<built-in> function sin(object angle)

Return the sine of an angle expressed in radians

8.6.3.4.1 Parameters:

angle : an object, each atom in which will be acted upon.

8.6.3.4.2 Returns:

An object, the same shape as angle. When angle is an atom, the result is the sine of angle.

8.6.3.4.3 Comments:

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

The sine of an angle is an atom between -1 and 1 inclusive. 0.0 is hit by integer multiples of PI only.

8.6.3.4.4 Example 1:

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

8.6.3.4.5 See Also:

cos, arcsin, PI, deg2rad

8.6.3.5 arccos

include std/math.e 
public function arccos(trig_range x)

Return an angle given its cosine.

8.6.3.5.1 Parameters:

value : an object, each atom in which will be acted upon.

8.6.3.5.2 Returns:

An object, the same shape as value. When value is an atom, the result is an atom, an angle whose cosine is value.

8.6.3.5.3 Errors:

If any atom in value is not in the -1..1 range, it cannot be the cosine of a real number, and an error occurs.

8.6.3.5.4 Comments:

A value between 0 and PI radians will be returned.

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

arccos() is not as fast as arctan().

8.6.3.5.5 Example 1:

s = arccos({-1,0,1}) 
-- s is {3.141592654, 1.570796327, 0}

8.6.3.5.6 See Also:

cos, PI, arctan

8.6.3.6 arcsin

include std/math.e 
public function arcsin(trig_range x)

Return an angle given its sine.

8.6.3.6.1 Parameters:

value : an object, each atom in which will be acted upon.

8.6.3.6.2 Returns:

An object, the same shape as value. When value is an atom, the result is an atom, an angle whose sine is value.

8.6.3.6.3 Errors:

If any atom in value is not in the -1..1 range, it cannot be the sine of a real number, and an error occurs.

8.6.3.6.4 Comments:

A value between -PI/2 and +PI/2 (radians) inclusive will be returned.

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

arcsin() is not as fast as arctan().

8.6.3.6.5 Example 1:

s = arcsin({-1,0,1}) 
s is {-1.570796327, 0, 1.570796327}

8.6.3.6.6 See Also:

arccos, arccos, sin

8.6.3.7 atan2

include std/math.e 
public function atan2(atom y, atom x)

Calculate the arctangent of a ratio.

8.6.3.7.1 Parameters:

y : an atom, the numerator of the ratio
x : an atom, the denominator of the ratio

8.6.3.7.2 Returns:

An atom, which is equal to arctan (y/x), except that it can handle zero denominator and is more accurate.

8.6.3.7.3 Example 1:

a = atan2(10.5, 3.1) 
-- a is 1.283713958

8.6.3.7.4 See Also:

arctan

8.6.3.8 rad2deg

include std/math.e 
public function rad2deg(object x)

Convert an angle measured in radians to an angle measured in degrees

8.6.3.8.1 Parameters:

angle : an object, all atoms of which will be converted, no matter how deeply nested.

8.6.3.8.2 Returns:

An object, the same shape as angle, all atoms of which were multiplied by 180/PI.

8.6.3.8.3 Comments:

This function may be applied to an atom or sequence. A flat angle is PI radians and 180 degrees.

arcsin(), arccos() and arctan() return angles in radians.

8.6.3.8.4 Example 1:

x = rad2deg(3.385938749) 
-- x is 194

8.6.3.8.5 See Also:

deg2rad

8.6.3.9 deg2rad

include std/math.e 
public function deg2rad(object x)

Convert an angle measured in degrees to an angle measured in radians

8.6.3.9.1 Parameters:

angle : an object, all atoms of which will be converted, no matter how deeply nested.

8.6.3.9.2 Returns:

An object, the same shape as angle, all atoms of which were multiplied by PI/180.

8.6.3.9.3 Comments:

This function may be applied to an atom or sequence. A flat angle is PI radians and 180 degrees. sin(), cos() and tan() expect angles in radians.

8.6.3.9.4 Example 1:

x = deg2rad(194) 
-- x is 3.385938749

8.6.3.9.5 See Also:

rad2deg

8.6.4 Logarithms and powers.

8.6.4.1 log

<built-in> function log(object value)

Return the natural logarithm of a positive number.

8.6.4.1.1 Parameters:

value : an object, any atom of which log() acts upon.

8.6.4.1.2 Returns:

An object, the same shape as value. For an atom, the returned atom is its logarithm of base E.

8.6.4.1.3 Errors:

If any atom in value is not greater than zero, an error occurs as its logarithm is not defined.

8.6.4.1.4 Comments:

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

To compute the inverse, you can use power(E, x) where E is 2.7182818284590452, or equivalently exp(x). Beware that the logarithm grows very slowly with x, so that exp () grows very fast.

8.6.4.1.5 Example 1:

a = log(100) 
-- a is 4.60517

8.6.4.1.6 See Also:

E, exp, log10

8.6.4.2 log10

include std/math.e 
public function log10(object x1)

Return the base 10 logarithm of a number.

8.6.4.2.1 Parameters:

value : an object, each atom of which will be converted, no matter how deeply nested.

8.6.4.2.2 Returns:

An object, the same shape as value. When value is an atom, raising 10 to the returned atom yields value back.

8.6.4.2.3 Errors:

If any atom in value is not greater than zero, its logarithm is not a real number and an error occurs.

8.6.4.2.4 Comments:

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

log10() is proportional to log() by a factor of 1/log(10), which is about 0.435 .

8.6.4.2.5 Example 1:

a = log10(12) 
-- a is 2.48490665

8.6.4.2.6 See Also:

log

8.6.4.3 exp

include std/math.e 
public function exp(atom x)

Computes some power of E.

8.6.4.3.1 Parameters:

value : an object, all atoms of which will be acted upon, no matter how deeply nested.

8.6.4.3.2 Returns:

An object, the same shape as value. When value is an atom, its exponential is being returned.

8.6.4.3.3 Comments:

This function can be applied to a single atom or to a sequence of any shape.

Due to its rapid growth, the returned values start losing accuracy as soon as values are greater than 10. Values above 710 will cause an overflow in hardware.

8.6.4.3.4 Example 1:

x = exp(5.4) 
-- x is 221.4064162

8.6.4.3.5 See Also:

log

8.6.4.4 power

<built-in> function power(object base, object exponent)

Raise a base value to some power.

8.6.4.4.1 Parameters:

base : an object, the value(s) to raise to some power.
exponent : an object, the exponent(s) to apply to base .

8.6.4.4.2 Returns:

An object, the shape of which depends on base 's and exponent's. For two atoms, this will be base raised to the power exponent.

8.6.4.4.3 Errors:

If some atom in base is negative and is raised to a non integer exponent, an error will occur, as the result is undefined.

If 0 is raised to any negative power, this is the same as a zero divide and causes an error.

power(0,0) is illegal, because there is not an unique value that can be assigned to that quantity.

8.6.4.4.4 Comments:

The arguments to this function may be atoms or sequences. The rules for operations on sequences apply.

Powers of 2 are calculated very efficiently.

Other languages have a ** or ^ operator to perform the same action. But they don't have sequences.

8.6.4.4.5 Example 1:

? power(5, 2) 
-- 25 is printed

8.6.4.4.6 Example 2:

? power({5, 4, 3.5}, {2, 1, -0.5}) 
-- {25, 4, 0.534522} is printed

8.6.4.4.7 Example 3:

? power(2, {1, 2, 3, 4}) 
-- {2, 4, 8, 16}

8.6.4.4.8 Example 4:

? power({1, 2, 3, 4}, 2) 
-- {1, 4, 9, 16}

8.6.4.4.9 See Also:

log, Operations on sequences

8.6.4.5 sqrt

<built-in> function sqrt(object value)

Calculate the square root of a number.

8.6.4.5.1 Parameters:

value : an object, each atom in which will be acted upon.

8.6.4.5.2 Returns:

An object, the same shape as value. When value is an atom, the result is the positive atom whose square is value.

8.6.4.5.3 Errors:

If any atom in value is less than zero, an error will occur, as no squared real can be less than zero.

8.6.4.5.4 Comments:

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

8.6.4.5.5 Example 1:

r = sqrt(16) 
-- r is 4

8.6.4.5.6 See Also:

power, Operations on sequences

8.6.5 Hyperbolic trigonometry

8.6.5.1 cosh

include std/math.e 
public function cosh(object a)

Computes the hyperbolic cosine of an object.

8.6.5.1.1 Parameters:

x : the object to process.

8.6.5.1.2 Returns:

An object, the same shape as x, each atom of which was acted upon.

8.6.5.1.3 Comments:

The hyperbolic cosine grows like the exponential function.

For all reals, power(cosh(x), 2) - power(sinh(x), 2) = 1. Compare with ordinary trigonometry.

8.6.5.1.4 Example 1:

? cosh(LN2) -- prints out 1.25

8.6.5.1.5 See Also:

cos, sinh, arccosh

8.6.5.2 sinh

include std/math.e 
public function sinh(object a)

Computes the hyperbolic sine of an object.

8.6.5.2.1 Parameters:

x : the object to process.

8.6.5.2.2 Returns:

An object, the same shape as x, each atom of which was acted upon.

8.6.5.2.3 Comments:

The hyperbolic sine grows like the exponential function.

For all reals, power(cosh(x), 2) - power(sinh(x), 2) = 1. Compare with ordinary trigonometry.

8.6.5.2.4 Example 1:

? sinh(LN2) -- prints out 0.75

8.6.5.2.5 See Also:

cosh, sin, arcsinh

8.6.5.3 tanh

include std/math.e 
public function tanh(object a)

Computes the hyperbolic tangent of an object.

8.6.5.3.1 Parameters:

x : the object to process.

8.6.5.3.2 Returns:

An object, the same shape as x, each atom of which was acted upon.

8.6.5.3.3 Comments:

The hyperbolic tangent takes values from -1 to +1.

tanh() is the ratio sinh() / cosh(). Compare with ordinary trigonometry.

8.6.5.3.4 Example 1:

? tanh(LN2) -- prints out 0.6

8.6.5.3.5 See Also:

cosh, sinh, tan, arctanh

8.6.5.4 arcsinh

include std/math.e 
public function arcsinh(object a)

Computes the reverse hyperbolic sine of an object.

8.6.5.4.1 Parameters:

x : the object to process.

8.6.5.4.2 Returns:

An object, the same shape as x, each atom of which was acted upon.

8.6.5.4.3 Comments:

The hyperbolic sine grows like the logarithm function.

8.6.5.4.4 Example 1:

? arcsinh(1) -- prints out 0,4812118250596034

8.6.5.4.5 See Also:

arccosh, arcsin, sinh

8.6.5.5 arccosh

include std/math.e 
public function arccosh(not_below_1 a)

Computes the reverse hyperbolic cosine of an object.

8.6.5.5.1 Parameters:

x : the object to process.

8.6.5.5.2 Returns:

An object, the same shape as x, each atom of which was acted upon.

8.6.5.5.3 Errors:

Since cosh only takes values not below 1, an argument below 1 causes an error.

8.6.5.5.4 Comments:

The hyperbolic cosine grows like the logarithm function.

8.6.5.5.5 Example 1:

? arccosh(1) -- prints out 0

8.6.5.5.6 See Also:

arccos, arcsinh, cosh

8.6.5.6 arctanh

include std/math.e 
public function arctanh(abs_below_1 a)

Computes the reverse hyperbolic tangent of an object.

8.6.5.6.1 Parameters:

x : the object to process.

8.6.5.6.2 Returns:

An object, the same shape as x, each atom of which was acted upon.

8.6.5.6.3 Errors:

Since tanh only takes values between -1 and +1 excluded, an out of range argument causes an error.

8.6.5.6.4 Comments:

The hyperbolic cosine grows like the logarithm function.

8.6.5.6.5 Example 1:

? arctanh(1/2) -- prints out 0,5493061443340548456976

8.6.5.6.6 See Also:

arccos, arcsinh, cosh

8.6.6 Accumulation

8.6.6.1 sum

include std/math.e 
public function sum(object a)

Compute the sum of all atoms in the argument, no matter how deeply nested

8.6.6.1.1 Parameters:

values : an object, all atoms of which will be added up, no matter how nested.

8.6.6.1.2 Returns:

An atom, the sum of all atoms in flatten(values).

8.6.6.1.3 Comments:

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

8.6.6.1.4 Example 1:

a = sum({10, 20, 30}) 
-- a is 60 
 
a = sum({10.5, {11.2} , 8.1}) 
-- a is 29.8

8.6.6.1.5 See Also:

can_add, product, or_all

8.6.6.2 product

include std/math.e 
public function product(object a)

Compute the product of all the atom in the argument, no matter how deeply nested.

8.6.6.2.1 Parameters:

values : an object, all atoms of which will be multiplied up, no matter how nested.

8.6.6.2.2 Returns:

An atom, the product of all atoms in flatten(values).

8.6.6.2.3 Comments:

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

8.6.6.2.4 Example 1:

a = product({10, 20, 30}) 
-- a is 6000 
 
a = product({10.5, {11.2} , 8.1}) 
-- a is 952.56

8.6.6.2.5 See Also:

can_add, sum, or_all

8.6.6.3 or_all

include std/math.e 
public function or_all(object a)

Or's together all atoms in the argument, no matter how deeply nested.

8.6.6.3.1 Parameters:

values : an object, all atoms of which will be added up, no matter how nested.

8.6.6.3.2 Returns:

An atom, the result of or'ing all atoms in flatten(values).

8.6.6.3.3 Comments:

This function may be applied to an atom or to all elements of a sequence. It performs or_bits() operations repeatedly.

8.6.6.3.4 Example 1:

a = sum({10, 7, 35}) 
-- a is 47

8.6.6.3.5 See Also:

can_add, sum, product, or_bits

8.6.7 Bitwise operations

8.6.7.1 and_bits

<built-in> function and_bits(object a, object b)

Perform the logical AND operation on corresponding bits in two objects. A bit in the result will be 1 only if the corresponding bits in both arguments are 1.

8.6.7.1.1 Parameters:

a : one of the objects involved
b : the second object

8.6.7.1.2 Returns:

An object, whose shape depends on the shape of both arguments. Each atom in this object is obtained by logical AND between atoms on both objects.

8.6.7.1.3 Comments:

The arguments to this function may be atoms or sequences. The rules for operations on sequences apply. The atoms in 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(). Using int_to_bits() is an even more direct approach.

8.6.7.1.4 Example 1:

 a = and_bits(#0F0F0000, #12345678) 
-- a is #02040000

8.6.7.1.5 Example 2:

 a = and_bits(#FF, {#123456, #876543, #2211}) 
-- a is {#56, #43, #11}

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

8.6.7.1.7 See Also:

or_bits, xor_bits, not_bits, int_to_bits

8.6.7.2 xor_bits

<built-in> function xor_bits(object a, object b)

Perform the logical XOR operation on corresponding bits in two objects. A bit in the result will be 1 only if the corresponding bits in both arguments are different.

8.6.7.2.1 Parameters:

a : one of the objects involved
b : the second object

8.6.7.2.2 Returns:

An object, whose shape depends on the shape of both arguments. Each atom in this object is obtained by logical XOR between atoms on both objects.

8.6.7.2.3 Comments:

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.

8.6.7.2.4 Example 1:

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

8.6.7.2.5 See Also:

and_bits, or_bits, not_bits, int_to_bits

8.6.7.3 or_bits

<built-in> function or_bits(object a, object b)

Perform the logical OR operation on corresponding bits in two objects. A bit in the result will be 1 only if the corresponding bits in both arguments are both 0.

8.6.7.3.1 Parameters:

a : one of the objects involved
b : the second object

8.6.7.3.2 Returns:

An object, whose shape depends on the shape of both arguments. Each atom in this object is obtained by logical XOR between atoms on both objects.

8.6.7.3.3 Comments:

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.

8.6.7.3.4 Example 1:

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

8.6.7.3.5 Example 2:

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

8.6.7.3.6 See Also:

and_bits, xor_bits, not_bits, int_to_bits

8.6.7.4 not_bits

<built-in> function not_bits(object a)

Perform the logical NOT operation on each bit in an object. A bit in the result will be 1 when the corresponding bit in x1 is 0, and will be 0 when the corresponding bit in x1 is 1.

8.6.7.4.1 Parameters:

a : the object to invert the bits of.

8.6.7.4.2 Returns:

An object, the same shape as a. Each bit in an atom of the result is the reverse of the corresponding bit inside a.

8.6.7.4.3 Comments:

The argument to this function may be an atom or a sequence.

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.

A simple equality holds for an atom a: a + not_bits(a) = -1.

8.6.7.4.4 Example 1:

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

8.6.7.4.5 See Also:

and_bits, or_bits, xor_bits, int_to_bits

8.6.7.5 shift_bits

include std/math.e 
public function shift_bits(object source_number, integer shift_distance)

Moves the bits in the input value by the specified distance.

8.6.7.5.1 Parameters:

source_number : object: The value(s) whose bits will be be moved.
shift_distance : integer: number of bits to be moved by.

8.6.7.5.2 Comments:

If source_number is a sequence, each element is shifted.
The value(s) in source_number are first truncated to a 32-bit integer.
The output is truncated to a 32-bit integer.
Vacated bits are replaced with zero.
If shift_distance is negative, the bits in source_number are moved left.
If shift_distance is positive, the bits in source_number are moved right.
If shift_distance is zero, the bits in source_number are not moved.

8.6.7.5.3 Returns:

Atom(s) containing a 32-bit integer. A single atom in source_number is an atom, or a sequence in the same form as source_number containing 32-bit integers.

8.6.7.5.4 Example 1:

? shift_bits((7, -3) --> 56 
? shift_bits((0, -9) --> 0 
? shift_bits((4, -7) --> 512 
? shift_bits((8, -4) --> 128 
? shift_bits((0xFE427AAC, -7) --> 0x213D5600 
? shift_bits((-7, -3) --> -56  which is 0xFFFFFFC8  
? shift_bits((131, 0) --> 131 
? shift_bits((184.464, 0) --> 184 
? shift_bits((999_999_999_999_999, 0) --> -1530494977 which is 0xA4C67FFF 
? shift_bits((184, 3) -- 23 
? shift_bits((48, 2) --> 12 
? shift_bits((121, 3) --> 15 
? shift_bits((0xFE427AAC, 7) -->  0x01FC84F5 
? shift_bits((-7, 3) --> 0x1FFFFFFF 
? shift_bits({48, 121}, 2) --> {12, 30}

8.6.7.5.5 See Also:

rotate_bits

8.6.7.6 rotate_bits

include std/math.e 
public function rotate_bits(object source_number, integer shift_distance)

Rotates the bits in the input value by the specified distance.

8.6.7.6.1 Parameters:

source_number : object: value(s) whose bits will be be rotated.
shift_distance : integer: number of bits to be moved by.

8.6.7.6.2 Comments:

If source_number is a sequence, each element is rotated.
The value(s) in source_number are first truncated to a 32-bit integer.
The output is truncated to a 32-bit integer.
If shift_distance is negative, the bits in source_number are rotated left.
If shift_distance is positive, the bits in source_number are rotated right.
If shift_distance is zero, the bits in source_number are not rotated.

8.6.7.6.3 Returns:

Atom(s) containing a 32-bit integer. A single atom in source_number is an atom, or a sequence in the same form as source_number containing 32-bit integers.

8.6.7.6.4 Example 1:

? rotate_bits(7, -3) --> 56 
? rotate_bits(0, -9) --> 0 
? rotate_bits(4, -7) --> 512 
? rotate_bits(8, -4) --> 128 
? rotate_bits(0xFE427AAC, -7) --> 0x213D567F 
? rotate_bits(-7, -3) --> -49  which is 0xFFFFFFCF  
? rotate_bits(131, 0) --> 131 
? rotate_bits(184.464, 0) --> 184 
? rotate_bits(999_999_999_999_999, 0) --> -1530494977 which is 0xA4C67FFF 
? rotate_bits(184, 3) -- 23 
? rotate_bits(48, 2) --> 12 
? rotate_bits(121, 3) --> 536870927 
? rotate_bits(0xFE427AAC, 7) -->  0x59FC84F5 
? rotate_bits(-7, 3) --> 0x3FFFFFFF 
? rotate_bits({48, 121}, 2) --> {12, 1073741854}

8.6.7.6.5 See Also:

shift_bits

Arithmetics

8.6.7.7 gcd

include std/math.e 
public function gcd(atom p, atom q)

Returns the greater common divisor of to atoms

8.6.7.7.1 Parameters:

p : one of the atoms to consider
q : the other atom.

8.6.7.7.2 Returns:

A positive atom, without a fractional part, evenly dividing both parameters, and is the greatest value with those properties.

8.6.7.7.3 Comments:

Signs are ignored. Atoms are rounded down to integers.

Any zero parameter causes 0 to be returned.

Parameters and return value are atoms so as to take mathematical integers up to power(2,53).

8.6.7.7.4 Example 1:

? gcd(76.3, -114) -- prints out gcd(76,114), which is 38

Floating Point

8.6.7.8 approx

include std/math.e 
public function approx(object p, object q, atom epsilon = 0.005)

Compares two (sets of) numbers based on approximate equality.

8.6.7.8.1 Parameters:

p : an object, one of the sets to consider
q : an object, the other set.
epsilon : an atom used to define the amount of inequality allowed. This must be a positive value. Default is 0.005

8.6.7.8.2 Returns:

An integer,

1 when p > (q + epsilon) : P is definitely greater than q.
-1 when p < (q - epsilon) : P is definitely less than q.
0 when p >= (q - epsilon) and p <= (q + epsilon) : p and q are approximately equal.

8.6.7.8.3 Comments:

This can be used to see if two numbers are near enough to each other.

Also, because of the way floating point numbers are stored, it not always possible express every real number exactly, especially after a series of arithmetic operations. You can use approx() to see if two floating point numbers are almost the same value.

If p and q are both sequences, they must be the same length as each other.

If p or q is a sequence, but the other is not, then the result is a sequence of results whose length is the same as the sequence argument.

8.6.7.8.4 Example 1:

? approx(10, 33.33 * 30.01 / 100) --> 0 because 10 and 10.002333 are within 0.005 of each other 
? approx(10, 10.001) -> 0 because 10 and 10.001 are within 0.005 of each other 
? approx(10, {10.001,9.999, 9.98, 10.04}) --> {0,0,1,-1} 
? approx({10.001,9.999, 9.98, 10.04}, 10) --> {0,0,-1,1} 
? approx({10.001,{9.999, 10.01}, 9.98, 10.04}, {10.01,9.99, 9.8, 10.4}) --> {-1,{1,1},1,-1} 
? approx(23,32, 10) -> 0 because 23 and 32 are within 10 of each other.

8.6.7.9 powof2

include std/math.e 
public function powof2(object p)

Tests for power of 2

8.6.7.9.1 Parameters:

p : an object. The item to test. This can be an integer, atom or sequence.

8.6.7.9.2 Returns:

An integer,

1 for each item in p that is a power of two, eg. 2,4,8,16,32, ...
0 for each item in p that is not a power of two, eg. 3, 54.322, -2

8.6.7.9.3 Example 1:

for i = 1 to 10 do 
  ? {i, powof2(i)} 
end for 
-- output ...  
-- {1,1} 
-- {2,1} 
-- {3,0} 
-- {4,1} 
-- {5,0} 
-- {6,0} 
-- {7,0} 
-- {8,1} 
-- {9,0} 
-- {10,0}

8.6.7.10 is_even

include std/math.e 
public function is_even(integer test_integer)

Test if the supplied integer is a even or odd number.

8.6.7.10.1 Parameters:

test_integer : an integer. The item to test.

8.6.7.10.2 Returns:

An integer,

1 if its even.
0 if its odd.

8.6.7.10.3 Example 1:

for i = 1 to 10 do 
  ? {i, is_even(i)} 
end for 
-- output ...  
-- {1,0} 
-- {2,1} 
-- {3,0} 
-- {4,1} 
-- {5,0} 
-- {6,1} 
-- {7,0} 
-- {8,1} 
-- {9,0} 
-- {10,1}

8.6.7.11 is_even_obj

include std/math.e 
public function is_even_obj(object test_object)

Test if the supplied EUPHORIA object is even or odd.

8.6.7.11.1 Parameters:

test_object : any EUPHORIA object. The item to test.

8.6.7.11.2 Returns:

An object,

If test_object is an integer...

1 if its even.
0 if its odd.

Otherwise if test_object is an atom this always returns 0
otherwise if test_object is an sequence it tests each element recursively, returning a sequence of the same structure containing ones and zeros for each element. A 1 means that the element at this position was even otherwise it was odd.

8.6.7.11.3 Example 1:

for i = 1 to 5 do 
  ? {i, is_even_obj(i)} 
end for 
-- output ...  
-- {1,0} 
-- {2,1} 
-- {3,0} 
-- {4,1} 
-- {5,0}

8.6.7.11.4 Example 2:

? is_even_obj(3.4) --> 0

8.6.7.11.5 Example 3:

? is_even_obj({{1,2,3}, {{4,5},6,{7,8}},9}) --> {{0,1,0},{{1,0},1,{0,1}},0}

8.7 Math Constants

---------- Constants

---------------- PI

---------------- QUARTPI

---------------- HALFPI

---------------- TWOPI

---------------- PISQR

---------------- INVSQ2PI

---------------- PHI

---------------- E

---------------- LN2

---------------- INVLN2

---------------- LN10

---------------- INVLN10

---------------- SQRT2

---------------- HALFSQRT2

---------------- SQRT3

---------------- DEGREES_TO_RADIANS

---------------- RADIANS_TO_DEGREES

---------------- EULER_GAMMA

---------------- SQRTE

---------------- PINF

---------------- MINF

8.7.1 Constants

8.7.1.1 PI

include std/mathcons.e 
public constant PI

PI is the ratio of a circle's circumference to it's diameter.

PI = C / D :: C = PI * D :: C = PI * 2 * R(radius)

8.7.1.2 QUARTPI

include std/mathcons.e 
public constant QUARTPI

Quarter of PI

8.7.1.3 HALFPI

include std/mathcons.e 
public constant HALFPI

Half of PI

8.7.1.4 TWOPI

include std/mathcons.e 
public constant TWOPI

Two times PI

8.7.1.5 PISQR

include std/mathcons.e 
public constant PISQR

PI ^ 2

8.7.1.6 INVSQ2PI

include std/mathcons.e 
public constant INVSQ2PI

1 / (sqrt(2PI))

8.7.1.7 PHI

include std/mathcons.e 
public constant PHI

phi => Golden Ratio = (1 + sqrt(5)) / 2

8.7.1.8 E

include std/mathcons.e 
public constant E

Euler (e)The base of the natural logarithm.

8.7.1.9 LN2

include std/mathcons.e 
public constant LN2

ln(2) :: 2 = power(E, LN2)

8.7.1.10 INVLN2

include std/mathcons.e 
public constant INVLN2

1 / (ln(2))

8.7.1.11 LN10

include std/mathcons.e 
public constant LN10

ln(10) :: 10 = power(E, LN10)

8.7.1.12 INVLN10

include std/mathcons.e 
public constant INVLN10

1 / ln(10)

8.7.1.13 SQRT2

include std/mathcons.e 
public constant SQRT2

sqrt(2)

8.7.1.14 HALFSQRT2

include std/mathcons.e 
public constant HALFSQRT2

sqrt(2)/ 2

8.7.1.15 SQRT3

include std/mathcons.e 
public constant SQRT3

Square root of 3

8.7.1.16 DEGREES_TO_RADIANS

include std/mathcons.e 
public constant DEGREES_TO_RADIANS

Conversion factor: Degrees to Radians = PI / 180

8.7.1.17 RADIANS_TO_DEGREES

include std/mathcons.e 
public constant RADIANS_TO_DEGREES

Conversion factor: Radians to Degrees = 180 / PI

8.7.1.18 EULER_GAMMA

include std/mathcons.e 
public constant EULER_GAMMA

Gamma (Euler Gamma)

8.7.1.19 SQRTE

include std/mathcons.e 
public constant SQRTE

sqrt(e)

8.7.1.20 PINF

include std/mathcons.e 
public constant PINF

Positive Infinity

8.7.1.21 MINF

include std/mathcons.e 
public constant MINF

Negative Infinity

8.8 Random Numbers

---------------- rand

---------------- rand_range

---------------- rnd

---------------- rnd_1

---------------- set_rand

---------------- chance

---------------- roll

---------------- sample

8.8.1 rand

<built-in> function rand(object maximum)

Return a random positive integer.

8.8.1.1 Parameters:

maximum : an atom, a cap on the value to return.

8.8.1.1.1 Returns:

An integer, from 1 to maximum.

8.8.1.1.2 Errors:

If ceil(maximum) is not a positive integer <= 1073741823, an error will occur. It must also be at least 1.

8.8.1.1.3 Comments:

This function may be applied to an atom or to all elements of a sequence. In order to get reproducible results from this function, you should call set_rand() with a reproducible value prior.

8.8.1.1.4 Example 1:

s = rand({10, 20, 30}) 
-- s might be: {5, 17, 23} or {9, 3, 12} etc.

8.8.1.1.5 See Also:

set_rand, ceil

8.8.1.2 rand_range

include std/rand.e 
public function rand_range(integer lo, integer hi)

Return a random integer from a specified inclusive integer range.

8.8.1.2.1 Parameters:

lo : an integer, the lower bound of the range
hi : an integer, the upper bound of the range.

8.8.1.2.2 Returns:

An integer, randomly drawn between lo and hi inclusive.

8.8.1.2.3 Errors:

If lo is not less than hi, an error will occur.

8.8.1.2.4 Comments:

This function may be applied to an atom or to all elements of a sequence. In order to get reproducible results from this function, you should call set_rand() with a reproducible value prior.

8.8.1.2.5 Example 1:

s = rand_range(18, 24) 
-- s could be any of: 18, 19, 20, 21, 22, 23 or 24

8.8.1.2.6 See Also:

rand, set_rand, rnd

8.8.1.3 rnd

include std/rand.e 
public function rnd()

Return a random floating point number in the range 0 to 1.

8.8.1.3.1 Parameters:

None.

8.8.1.3.2 Returns:

An atom, randomly drawn between 0.0 and 1.0 inclusive.

8.8.1.3.3 Comments:

In order to get reproducible results from this function, you should call set_rand() with a reproducible value prior to calling this.

8.8.1.3.4 Example 1:

set_rand(1001) 
s = rnd() 
  -- s is 0.2634879318

8.8.1.3.5 See Also:

rand, set_rand, rand_range

8.8.1.4 rnd_1

include std/rand.e 
public function rnd_1()

Return a random floating point number in the range 0 to less than 1.

8.8.1.4.1 Parameters:

None.

8.8.1.4.2 Returns:

An atom, randomly drawn between 0.0 and a number less than 1.0

8.8.1.4.3 Comments:

In order to get reproducible results from this function, you should call set_rand() with a reproducible value prior to calling this.

8.8.1.4.4 Example 1:

set_rand(1001) 
s = rnd_1() 
  -- s is 0.2634879318

8.8.1.4.5 See Also:

rand, set_rand, rand_range

8.8.1.5 set_rand

include std/rand.e 
public procedure set_rand(object seed)

Reset the random number generator.

8.8.1.5.1 Parameters:

seed : an object. The generator uses this initialize itself for the next random number generated. This can be a single integer or atom, or a sequence of two integers, or an empty sequence or any other sort of sequence.

8.8.1.5.2 Comments:

Starting from a seed, the values returned by rand () are reproducible. This is useful for demos and stress tests based on random data. 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.
Internally there are actually two seed values.

When set_rand() is called with a single integer or atom, the two internal seeds are derived from the parameter.
When set_rand() is called with a sequence of exactly two integers/atoms the internal seeds are set to the parameter values.
When set_rand() is called with an empty sequence, the internal seeds are set to random values and are unpredictable. This is how to reset the generator.
When set_rand() is called with any other sequence, the internal seeds are set based on the length of the sequence and the hashed value of the sequence.

Aside from an empty seed parameter, this sets the generator to a known state and the random numbers generated after come in a predicable order, though they still appear to be random.

8.8.1.5.3 Example 1:

 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 
set_rand("") -- Reset the generator to an unknown seed. 
t[1] = rand(10)  -- Could be anything now, no way to predict it.

8.8.1.5.4 See Also:

rand

8.8.1.6 chance

include std/rand.e 
public function chance(atom my_limit, atom top_limit = 100)

Simulates the probability of a desired outcome.

8.8.1.6.1 Parameters:

my_limit : an atom. The desired chance of something happening.
top_limit: an atom. The maximum chance of something happening. The default is 100.

8.8.1.6.2 Returns:

an integer. 1 if the desired chance happened otherwise 0.

8.8.1.6.3 Comments:

This simulates the chance of something happening. For example, if you wnat something to happen with a probablity of 25 times out of 100 times then you code chance(25) and if you want something to (most likely) occur 345 times out of 999 times, you code chance(345, 999)#.

8.8.1.6.4 Example 1:

 -- 65% of the days are sunny, so ... 
 if chance(65) then 
     puts(1, "Today will be a sunny day") 
 elsif chance(40) then 
     -- And 40% of non-sunny days it will rain. 
     puts(1, "It will rain today") 
 else 
     puts(1, "Today will be a overcast day") 
 end if

8.8.1.6.5 See Also:

rnd, roll

8.8.1.7 roll

include std/rand.e 
public function roll(object desired, integer sides = 6)

Simulates the probability of a dice throw.

8.8.1.7.1 Parameters:

desired : an object. One or more desired outcomes.
sides: an integer. The number of sides on the dice. Default is 6.

8.8.1.7.2 Returns:

an integer. 0 if none of the desired outcomes occured, otherwise the face number that was rolled.

8.8.1.7.3 Comments:

The minimum number of sides is 2 and there is no maximum.

8.8.1.7.4 Example 1:

res = roll(1, 2) -- Simulate a coin toss. 
res = roll({1,6}) -- Try for a 1 or a 6 from a standard die toss. 
res = roll({1,2,3,4}, 20) -- Looking for any number under 5 from a 20-sided die.

8.8.1.7.5 See Also:

rnd, chance

8.8.1.8 sample

include std/rand.e 
public function sample(sequence full_set, integer sample_size, integer return_remaining = 0)

Selects a random sample sub-set of items from a population set.

8.8.1.8.1 Parameters:

full_set : a sequence. The set of items from which to take a sample.
sample_size: an integer. The number of samples to take.
return_remaining: an integer. If non-zero, the sub-set not selected is also returned. If zero, the default, only the sampled set is returned.

8.8.1.8.2 Returns:

a sequence. When return_remaining = 0 then this is the set of samples, otherwise it returns a two-element sequence; the first is the samples, and the second is the remainder of the population (in the original order).

8.8.1.8.3 Comments:

If sample_size is less than 1, an empty set is returned.
If sample_size is greater than or equal to the population count, the entire population set is returned, but in a random order.

8.8.1.8.4 Example 1:

set_rand("example") 
printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", 1)})  --> "t" 
printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", 5)})  --> "flukq" 
printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", -1)}) --> "" 
printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", 26)}) --> "kghrsxmjoeubaywlzftcpivqnd" 
printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", 25)}) --> "omntrqsbjguaikzywvxflpedc"

8.8.1.8.5 Example 2:

-- Deal 4 hands of 5 cards from a standard deck of cards. 
sequence theDeck 
sequence hands = {} 
sequence rt 
function new_deck() 
	sequence nd = {} 
	for i = 1 to 4 do 
		for j = 1 to 13 do 
			nd = append(nd, {i,j}) 
		end for 
	end for 
	return nd 
end function 
theDeck = new_deck() 
for i = 1 to 4 do 
	rt = sample(theDeck, 5, 1) 
	theDeck = rt[2] 
	hands = append(hands, rt[1]) 
end for

8.9 Mouse

---------- Requirements

---------- Constants

---------------- MOVE

---------------- LEFT_DOWN

---------------- LEFT_UP

---------------- RIGHT_DOWN

---------------- RIGHT_UP

---------------- MIDDLE_DOWN

---------------- MIDDLE_UP

---------------- ANY_UP

---------- Routines

---------------- get_mouse

---------------- mouse_events

---------------- mouse_pointer

8.9.1 Requirements

Linux -- you need GPM server to be running
Windows -- not implemented yet for the text console
FreeBSD -- not implemented
OS X -- not implemented

8.9.2 Constants

The following constants can be used to identify and specify mouse events.

8.9.2.1 MOVE

include std/mouse.e 
public integer MOVE

8.9.2.2 LEFT_DOWN

include std/mouse.e 
public integer LEFT_DOWN

8.9.2.3 LEFT_UP

include std/mouse.e 
public integer LEFT_UP

8.9.2.4 RIGHT_DOWN

include std/mouse.e 
public integer RIGHT_DOWN

8.9.2.5 RIGHT_UP

include std/mouse.e 
public integer RIGHT_UP

8.9.2.6 MIDDLE_DOWN

include std/mouse.e 
public integer MIDDLE_DOWN

8.9.2.7 MIDDLE_UP

include std/mouse.e 
public integer MIDDLE_UP

8.9.2.8 ANY_UP

include std/mouse.e 
public integer ANY_UP

8.9.3 Routines

8.9.3.1 get_mouse

include std/mouse.e 
public function get_mouse()

Queries the last mouse event.

8.9.3.1.1 Returns:

An object, either -1 if there has not been a mouse event since the last time get_mouse() was called. Otherwise, returns a triple {event, x, y}.

Constants have been defined in mouse.e for the possible mouse events (the values for event):

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

8.9.3.1.2 Comments:

get_mouse() returns immediately with either a -1 or a mouse event, without waiting for an event to occur. So, you must check it frequently enough to avoid missing an event: when the next event occurs, the current event will be lost, if you haven't read it. In practice it is not hard to catch almost all events. Losing a MOVE event is generally not too serious, as the next MOVE will tell you where the mouse pointer is.

Sometimes multiple events will be reported. For example, if the mouse is moving when the left button is clicked, get_mouse() will report an event value of LEFT_DOWN+MOVE, i.e. 2+1 or 3. For this reason you should test for a particular event using and_bits(). See examples below. Further, you can determine which events will be reported using mouse_events.

In Linux, no scaling is required - x and y correspond to the line and column on the screen, with (1,1) at the top left.

In Linux, mouse movement events are not reported in an xterm window, only in the text console.

In Linux, LEFT_UP, RIGHT_UP and MIDDLE_UP are not distinguishable from one another.

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

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.

8.9.3.1.3 Example 1:

8.9.3.1.4 a return value of:

{2, 100, 50} would indicate that the left button was pressed down when the mouse pointer was at location x=100, y=50 on the screen.

8.9.3.1.5 Example 2:

To test for LEFT_DOWN, write something like the following:

while 1 do 
    object event = get_mouse() 
    if sequence(event) then 
        if and_bits(event[1], LEFT_DOWN) then 
            -- left button was pressed 
            exit 
        end if 
    end if 
end while

8.9.3.1.6 See Also:

mouse_events, mouse_pointer

8.9.3.2 mouse_events

include std/mouse.e 
public procedure mouse_events(integer events)

Select the mouse events get_mouse() is to report.

8.9.3.2.1 Parameters:

events: an integer, all requested event codes or'ed together.

8.9.3.2.2 Comments:

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 Unix, mouse_events() currently has no effect.

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.

8.9.3.2.3 Example 1:

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.

8.9.3.2.4 See Also:

get_mouse, mouse_pointer

8.9.3.3 mouse_pointer

include std/mouse.e 
public procedure mouse_pointer(integer show_it)

Turn mouse pointer on or off.

8.9.3.3.1 Parameters:

show_it : an integer, 0 to hide and 1 to show.

8.9.3.3.2 Comments:

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

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.

8.9.3.3.3 See Also:

get_mouse, mouse_pointer

8.10 Operating System Helpers

---------------- CMD_SWITCHES

---------- Operating System Constants

---------------- WIN32

---------------- LINUX

---------------- OSX

---------------- SUNOS

---------------- OPENBSD

---------------- NETBSD

---------------- FREEBSD

---------- Environment.

---------------- instance

---------------- get_pid

---------------- uname

---------------- is_win_nt

---------------- getenv

---------------- setenv

---------------- unsetenv

---------------- platform

---------- Interacting with the OS

---------------- system

---------------- system_exec

---------- Miscellaneous

---------------- sleep

---------------- include_paths

---------- Pipe Input/Output

---------------- Notes

---------- Accessor Constants

---------------- STDIN

---------------- STDOUT

---------------- STDERR

---------------- PID

---------------- PARENT

---------------- CHILD

---------- Opening/Closing

---------------- process

---------------- close

---------------- kill

---------- Read/Write Process

---------------- read

---------------- write

---------------- error_no

---------------- create

---------------- exec

8.10.1 CMD_SWITCHES

include std/os.e 
public constant CMD_SWITCHES

8.10.2 Operating System Constants

8.10.2.1 WIN32

include std/os.e 
public enum WIN32

8.10.2.2 LINUX

include std/os.e 
public enum LINUX

8.10.2.3 OSX

include std/os.e 
public enum OSX

8.10.2.4 SUNOS

include std/os.e 
public enum SUNOS

8.10.2.5 OPENBSD

include std/os.e 
public enum OPENBSD

8.10.2.6 NETBSD

include std/os.e 
public enum NETBSD

8.10.2.7 FREEBSD

include std/os.e 
public enum FREEBSD

These constants are returned by the platform function.

WIN32 -- Host operating system is Windows
LINUX -- Host operating system is Linux
FREEBSD -- Host operating system is FreeBSD
OSX -- Host operating system is Mac OS X
SUNOS -- Host operating system is Sun's OpenSolaris
OPENBSD -- Host operating system is OpenBSD
NETBSD -- Host operating system is NetBSD

8.10.2.7.1 Note:

Via the platform call, there is no way to determine if you are on Linux or FreeBSD. This was done to provide a generic UNIX return value for platform.

In most situations you are better off to test the host platform by using the ifdef statement. It is both more precise and faster.

8.10.3 Environment.

8.10.3.1 instance

include std/os.e 
public function instance()

Return hInstance on Windows and Process ID (pid) on Unix.

8.10.3.1.1 Comments:

On Windows the hInstance can be passed around to various Windows routines.

8.10.3.2 get_pid

include std/os.e 
public function get_pid()

Return the ID of the current Process (pid)

8.10.3.2.1 Returns:

An atom: The current process' id.

8.10.3.2.2 Example:

mypid = get_pid()

8.10.3.3 uname

include std/os.e 
public function uname()

Retrieves the name of the host OS.

8.10.3.3.1 Returns:

A sequence, starting with the OS name. If identification fails, returns an OS name of UNKNOWN. Extra information depends on the OS.

On Unix, returns the same information as the uname() syscall in the same order as the struct utsname. This information is: OS Name/Kernel Name Local Hostname Kernel Version/Kernel Release Kernel Specific Version information (This is usually the date that the kernel was compiled on and the name of the host that performed the compiling.) Architecture Name (Usually a string of i386 vs x86_64 vs ARM vs etc)

On Windows, returns the following in order: Windows Platform (out of WinCE, Win9x, WinNT, Win32s, or Unknown Windows) Name of Windows OS (Windows 3.1, Win95, WinXP, etc) Platform Number Build Number Minor OS version number Major OS version number

On UNKNOWN, returns an OS name of "UNKNOWN". No other information is returned.

Returns a string of "" if an internal error has occured.

8.10.3.3.2 Comments:

On Unix, M_UNAME is defined as a machine_func() and this is passed to the C backend. If the M_UNAME call fails, the raw machine_func() returns -1. On non Unix platforms, calling the machine_func() directly returns 0.

8.10.3.4 is_win_nt

include std/os.e 
public function is_win_nt()

Decides whether the host system is a newer Windows version (NT/2K/XP/Vista).

8.10.3.4.1 Returns:

An integer, 1 if host system is a newer Windows (NT/2K/XP/Vista), else 0.

8.10.3.5 getenv

<built-in> function getenv(sequence var_name)

Return the value of an environment variable.

8.10.3.5.1 Parameters:

var_name : a string, the name of the variable being queried.

8.10.3.5.2 Returns:

An object, -1 if the variable does not exist, else a sequence holding its value.

8.10.3.5.3 Comments:

Both the argument and the return value, may, or may not be, case sensitive. You might need to test this on your own system.

8.10.3.5.4 Example:

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

8.10.3.5.5 See Also:

setenv, command_line

8.10.3.6 setenv

include std/os.e 
public function setenv(sequence name, sequence val, integer overwrite = 1)

Set an environment variable.

8.10.3.6.1 Parameters:

name : a string, the environment variable name
val : a string, the value to set to
overwrite : an integer, nonzero to overwrite an existing variable, 0 to disallow this.

8.10.3.6.2 Example 1:

? setenv("NAME", "John Doe") 
? setenv("NAME", "Jane Doe") 
? setenv("NAME", "Jim Doe", 0)

8.10.3.6.3 See Also:

getenv, unsetenv

8.10.3.7 unsetenv

include std/os.e 
public function unsetenv(sequence env)

Unset an environment variable

8.10.3.7.1 Parameters:

name : name of environment variable to unset

8.10.3.7.2 Example 1:

? unsetenv("NAME")

8.10.3.7.3 See Also:

setenv, getenv

8.10.3.8 platform

<built-in> function platform()

Indicates the platform that the program is being executed on.

8.10.3.8.1 Returns:

An integer,

public constant 
    WIN32, 
    LINUX, 
    FREEBSD, 
    OSX, 
    SUNOS, 
   OPENBSD, 
    NETBSD, 
    FREEBSD

8.10.3.8.2 Comments:

The ifdef statement is much more versatile and in most cases supersedes platform().

platform() used to be the way to execute different code depending on which platform the program is running on. Additional platforms will be added as EUPHORIA is ported to new machines and operating environments.

8.10.3.8.3 Example 1:

 ifdef WIN32 then 
    -- call system Beep routine 
    err = c_func(Beep, {0,0}) 
elsedef 
    -- do nothing (Linux/FreeBSD) 
end if

8.10.3.8.4 See Also:

Platform-Specific Issues, ifdef statement

8.10.4 Interacting with the OS

8.10.4.1 system

<built-in> procedure system(sequence command, integer mode=0)

Pass a command string to the operating system command interpreter.

8.10.4.1.1 Parameters:

command : a string to be passed to the shell
mode : an integer, indicating the manner in which to return from the call.

8.10.4.1.2 Errors:

command should not exceed 1,024 characters.

8.10.4.1.3 Comments:

Allowable values for mode are:

0: the previous graphics mode is restored and the screen is cleared.
1: a beep sound will be made and the program will wait for the user to press a key before the previous graphics mode is restored.
2: the graphics mode is not restored and the screen is not cleared.

mode = 2 should only be used when it is known that the command executed by system() will not change the graphics mode.

You can use EUPHORIA as a sophisticated "batch" (.bat) language by making calls to system() and system_exec().

system() will start a new command shell.

system() allows you to use command-line redirection of standard input and output in command.

8.10.4.1.4 Example 1:

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

8.10.4.1.5 Example 2:

 system("eui \\test\\myprog.ex < indata > outdata", 2) 
-- executes myprog by redirecting standard input and 
-- standard output

8.10.4.1.6 See Also:

system_exec, command_line, current_dir, getenv

8.10.4.2 system_exec

<built-in> function system_exec(sequence command, integer mode=0)

Try to run the a shell executable command

8.10.4.2.1 Parameters:

command : a string to be passed to the shell, representing an executable command
mode : an integer, indicating the manner in which to return from the call.

8.10.4.2.2 Returns:

An integer, basically the exit/return code from the called process.

8.10.4.2.3 Errors:

command should not exceed 1,024 characters.

8.10.4.2.4 Comments:

Allowable values for mode are:

0 -- the previous graphics mode is restored and the screen is cleared.
1 -- a beep sound will be made and the program will wait for the user to press a key before the previous graphics mode is restored.
2 -- the graphics mode is not restored and the screen is not cleared.

If it is not possible to run the program, system_exec() will return -1.

On WIN32, system_exec() will only run .exe and .com programs. To run .bat files, or built-in shell commands, you need system(). Some commands, such as DEL, are not programs, they are actually built-in to the command interpreter.

On WIN32, system_exec() does not allow the use of command-line redirection in command. Nor does it allow you to quote strings that contain blanks, such as file names.

exit codes from Windows programs are normally in the range 0 to 255, with 0 indicating "success".

You can run a EUPHORIA program using system_exec(). A EUPHORIA program can return an exit code using abort ().

system_exec() does not start a new command shell.

8.10.4.2.5 Example 1:

 integer exit_code 
exit_code = system_exec("xcopy temp1.dat temp2.dat", 2) 
 
if exit_code = -1 then 
    puts(2, "\n couldn't run xcopy.exe\n") 
elsif exit_code = 0 then 
    puts(2, "\n xcopy succeeded\n") 
else 
    printf(2, "\n xcopy failed with code %d\n", exit_code) 
end if

8.10.4.2.6 Example 2:

 -- executes myprog with two file names as arguments 
if system_exec("eui \\test\\myprog.ex indata outdata", 2) then 
    puts(2, "failure!\n") 
end if

8.10.4.2.7 See Also:

system, abort

8.10.5 Miscellaneous

8.10.5.1 sleep

include std/os.e 
public procedure sleep(atom t)

Suspend thread execution. for t seconds.

8.10.5.1.1 Parameters:

t : an atom, the number of seconds for which to sleep.

8.10.5.1.2 Comments:

The operating system will suspend your process and schedule other processes.

With multiple tasks, the whole program sleeps, not just the current task. To make just the current task sleep, you can call task_schedule(task_self(), {i, i}) and then execute task_yield(). Another option is to call task_delay().

8.10.5.1.3 Example:

puts(1, "Waiting 15 seconds and a quarter...\n") 
sleep(15.25) 
puts(1, "Done.\n")

8.10.5.1.4 See Also:

task_schedule, task_yield, task_delay

8.10.5.2 include_paths

<built-in> function include_paths(integer convert)

Returns the list of include paths, in the order in which they are searched

8.10.5.2.1 Parameters:

convert : an integer, nonzero to include converted path entries that were not validated yet.

8.10.5.2.2 Returns:

A sequence, of strings, each holding a fully qualified include path.

8.10.5.2.3 Comments:

convert is checked only under Windows. If a path has accented characters in it, then it may or may not be valid to convert those to the OEM code page. Setting convert to a nonzero value will force conversion for path entries that have accents and which have not been checked to be valid yet. The extra entries, if any, are returned at the end of the returned sequence.

8.10.5.2.4 The paths are ordered in the order they are searched:

current directory
configuration file,
command line switches,
EUINC
a default based on EUDIR.

8.10.5.2.5 Example 1:

sequence s = include_paths(0) 
-- s might contain 
{ 
  "/usr/euphoria/tests", 
  "/usr/euphoria/include", 
  "./include", 
  "../include" 
}

8.10.5.2.6 See Also:

eu.cfg, include, option_switches

8.10.6 Pipe Input/Output

8.10.6.1 Notes

Due to a bug, EUPHORIA does not handle STDERR properly STDERR cannot captured for EUPHORIA programs (other programs will work fully) The IO functions currently work with file handles, a future version might wrap them in streams so that they can be used directly alongside other file/socket/other-streams with a stream_select() function.

8.10.7 Accessor Constants

8.10.7.1 STDIN

include std/pipeio.e 
public enum STDIN

Child processes standard input

8.10.7.2 STDOUT

include std/pipeio.e 
public enum STDOUT

Child processes standard output

8.10.7.3 STDERR

include std/pipeio.e 
public enum STDERR

Child processes standard error

8.10.7.4 PID

include std/pipeio.e 
public enum PID

Process ID

8.10.7.5 PARENT

include std/pipeio.e 
public enum PARENT

Set of pipes that are for the use of the parent

8.10.7.6 CHILD

include std/pipeio.e 
public enum CHILD

Set of pipes that are given to the child - should not be used by the parent

8.10.8 Opening/Closing

8.10.8.1 process

include std/pipeio.e 
public type process(object o)

Process Type

8.10.8.2 close

include std/pipeio.e 
public function close(atom fd)

Close handle fd

8.10.8.2.1 Returns:

An integer, 0 on success, -1 on failure

8.10.8.2.2 Example 1:

integer status = pipeio:close(p[STDIN])

8.10.8.3 kill

include std/pipeio.e 
public procedure kill(process p, atom signal = 15)

Close pipes and kill process p with signal signal (default 15)

8.10.8.3.1 Comments:

Signal is ignored on Windows.

8.10.8.3.2 Example 1:

kill(p)

8.10.9 Read/Write Process

8.10.9.1 read

include std/pipeio.e 
public function read(atom fd, integer bytes)

Read bytes bytes from handle fd

8.10.9.1.1 Returns:

A sequence, containing data, an empty sequence on EOF or an error code. Similar to get_bytes.

8.10.9.1.2 Example 1:

sequence data=read(p[STDOUT],256)

Write bytes to handle fd

8.10.9.1.3 Returns:

A integer, number of bytes written, or -1 on error

8.10.9.1.4 Example 1:

integer bytes_written = write(p[STDIN],"Hello World!")

8.10.9.2 write

include std/pipeio.e 
public function write(atom fd, sequence str)

8.10.9.3 error_no

include std/pipeio.e 
public function error_no()

Get error no from last call to a pipe function

8.10.9.3.1 Comments:

Value returned will be OS-specific, and is not always set on Windows at least

8.10.9.3.2 Example 1:

integer error = error_no()

8.10.9.4 create

include std/pipeio.e 
public function create()

Create pipes for inter-process communication

8.10.9.4.1 Returns:

A handle, process handles { {parent side pipes},{child side pipes} }

8.10.9.4.2 Example 1:

object p = exec("dir", create())

8.10.9.5 exec

include std/pipeio.e 
public function exec(sequence cmd, sequence pipe)

Open process with command line cmd

8.10.9.5.1 Returns:

A handle, process handles { PID, STDIN, STDOUT, STDERR }

8.10.9.5.2 Example 1:

object p = exec("dir", create())

8.11 Pretty Printing

Page Contents

---------------- PRETTY_DEFAULT

---------------- DISPLAY_ASCII

---------------- INDENT

---------------- START_COLUMN

---------------- WRAP

---------------- INT_FORMAT

---------------- FP_FORMAT

---------------- MIN_ASCII

---------------- MAX_ASCII

---------------- MAX_LINES

---------------- LINE_BREAKS

---------- Routines

---------------- pretty_print

---------------- pretty_sprint

8.11.1 PRETTY_DEFAULT

include std/pretty.e 
public constant PRETTY_DEFAULT

8.11.1.1 DISPLAY_ASCII

include std/pretty.e 
public enum DISPLAY_ASCII

8.11.1.2 INDENT

include std/pretty.e 
public enum INDENT

8.11.1.3 START_COLUMN

include std/pretty.e 
public enum START_COLUMN

8.11.1.4 WRAP

include std/pretty.e 
public enum WRAP

8.11.1.5 INT_FORMAT

include std/pretty.e 
public enum INT_FORMAT

8.11.1.6 FP_FORMAT

include std/pretty.e 
public enum FP_FORMAT

8.11.1.7 MIN_ASCII

include std/pretty.e 
public enum MIN_ASCII

8.11.1.8 MAX_ASCII

include std/pretty.e 
public enum MAX_ASCII

8.11.1.9 MAX_LINES

include std/pretty.e 
public enum MAX_LINES

8.11.1.10 LINE_BREAKS

include std/pretty.e 
public enum LINE_BREAKS

8.11.2 Routines

8.11.2.1 pretty_print

include std/pretty.e 
public procedure pretty_print(integer fn, object x, sequence options = PRETTY_DEFAULT)

Print an object to a file or device, using braces { , , , }, indentation, and multiple lines to show the structure.

8.11.2.1.1 Parameters:

fn : an integer, the file/device number to write to
x : the object to display/convert to printable form
options : is an (up to) 10-element options sequence.

8.11.2.1.2 Comments:

Pass {} in options to select the defaults, or set options as below:

display ASCII characters:

0 -- never
1 -- alongside any integers in printable ASCII range (default)
2 -- display as "string" when all integers of a sequence are in ASCII range
3 -- show strings, and quoted characters (only) for any integers in ASCII range as well as the characters: \t \r \n

amount to indent for each level of sequence nesting -- default: 2
column we are starting at -- default: 1
approximate column to wrap at -- default: 78
format to use for integers -- default: "%d"
format to use for floating-point numbers -- default: "%.10g"
minimum value for printable ASCII -- default 32
maximum value for printable ASCII -- default 127
maximum number of lines to output
line breaks between elements -- default 1 (0 = no line breaks, -1 = line breaks to wrap only)

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

The default options can be applied using the public constant PRETTY_DEFAULT, and the elements may be accessed using the following public enum:

DISPLAY_ASCII
INDENT
START_COLUMN
WRAP
INT_FORMAT
FP_FORMAT
MIN_ASCII
MAX_ASCII
MAX_LINES
LINE_BREAKS

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

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

8.11.2.1.3 Example 1:

pretty_print(1, "ABC", {})     
 
{65'A',66'B',67'C'}

8.11.2.1.4 Example 2:

pretty_print(1, {{1,2,3}, {4,5,6}}, {})   
 
{ 
  {1,2,3}, 
  {4,5,6} 
}

8.11.2.1.5 Example 3:

pretty_print(1, {"EUPHORIA", "Programming", "Language"}, {2})   
 
{ 
  "EUPHORIA", 
  "Programming", 
  "Language" 
}

8.11.2.1.6 Example 4:

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

8.11.2.1.7 See Also:

print, sprint, printf, sprintf, pretty_sprint

8.11.2.2 pretty_sprint

include std/pretty.e 
public function pretty_sprint(object x, sequence options = PRETTY_DEFAULT)

Format an object using braces { , , , }, indentation, and multiple lines to show the structure.

8.11.2.2.1 Parameters:

x : the object to display
options : is an (up to) 10-element options sequence: Pass {} to select the defaults, or set options

8.11.2.2.2 Returns:

A sequence, of printable characters, representing x in an human-readable form.

8.11.2.2.3 Comments:

This function formats objects the same as pretty_print(), but returns the sequence obtained instead of sending it to some file..

8.11.2.2.4 See Also:

pretty_print, sprint

8.12 Statistics

Page Contents

---------- Routines

---------------- small

---------------- largest

---------------- smallest

---------------- range

---------------- ST_FULLPOP

---------------- ST_SAMPLE

---------------- ST_ALLNUM

---------------- ST_IGNSTR

---------------- ST_ZEROSTR

---------------- stdev

---------------- avedev

---------------- sum

---------------- count

---------------- average

---------------- geomean

---------------- harmean

---------------- movavg

---------------- emovavg

---------------- median

---------------- raw_frequency

---------------- mode

---------------- central_moment

---------------- sum_central_moments

---------------- skewness

---------------- kurtosis

8.12.1 Routines

8.12.1.1 small

include std/stats.e 
public function small(sequence data_set, integer ordinal_idx)

Determines the k-th smallest value from the supplied set of numbers.

8.12.1.1.1 Parameters:

data_set : The list of values from which the smallest value is chosen.
ordinal_idx : The relative index of the desired smallest value.

8.12.1.1.2 Returns:

A sequence, {The k-th smallest value, its index in the set}

8.12.1.1.3 Comments:

small() is used to return a value based on its size relative to all the other elements in the sequence. When index is 1, the smallest index is returned. Use index = length(data_set) to return the highest.

If ordinal_idx is less than one, or greater then length of data_set, an empty sequence is returned.

The set of values does not have to be in any particular order. The values may be any EUPHORIA object.

8.12.1.1.4 Example 1:

? small( {4,5,6,8,5,4,3,"text"}, 3 ) -- Ans: {4,1} (The 3rd smallest value) 
? small( {4,5,6,8,5,4,3,"text"}, 1 ) -- Ans: {3,7} (The 1st smallest value) 
? small( {4,5,6,8,5,4,3,"text"}, 7 ) -- Ans: {8,4} (The 7th smallest value) 
? small( {"def", "qwe", "abc", "try"}, 2 ) -- Ans: {"def", 1} (The 2nd smallest value) 
? small( {1,2,3,4}, -1) -- Ans: {} -- no-value 
? small( {1,2,3,4}, 10) -- Ans: {} -- no-value

8.12.1.2 largest

include std/stats.e 
public function largest(object data_set)

Returns the largest of the data points that are atoms.

8.12.1.2.1 Parameters:

data_set : a list of 1 or more numbers among which you want the largest.

8.12.1.2.2 Returns:

An object, either of:

an atom (the largest value) if there is at least one atom item in the set
{} if there is no largest value.

8.12.1.2.3 Comments:

Any data_set element which is not an atom is ignored.

8.12.1.2.4 Example 1:

? largest( {7,2,8,5,6,6,4,8,6,6,3,3,4,1,8,"text"} ) -- Ans: 8 
? largest( {"just","text"} ) -- Ans: {}

8.12.1.2.5 See also:

range

8.12.1.3 smallest

include std/stats.e 
public function smallest(object data_set)

Returns the smallest of the data points.

8.12.1.3.1 Parameters:

data_set : A list of 1 or more numbers for which you want the smallest. Note: only atom elements are included and any sub-sequences elements are ignored.

8.12.1.3.2 Returns:

An object, either of:

an atom (the smallest value) if there is at least one atom item in the set
{} if there is no largest value.

8.12.1.3.3 Comments:

Any data_set element which is not an atom is ignored.

8.12.1.3.4 Example 1:

? smallest( {7,2,8,5,6,6,4,8,6,6,3,3,4,1,8,"text"} ) -- Ans: 1 
? smallest( {"just","text"} ) -- Ans: {}

8.12.1.3.5 See also:

range

8.12.1.4 range

include std/stats.e 
public function range(object data_set)

Determines a number of range statistics for the data set.

8.12.1.4.1 Parameters:

data_set : a list of 1 or more numbers for which you want the range data.

8.12.1.4.2 Returns:

A sequence, empty if no atoms were found, else like {Lowest, Highest, Range, Mid-range}

8.12.1.4.3 Comments:

Any sequence element in data_set is ignored.

8.12.1.4.4 Example 1:

? range( {7,2,8,5,6,6,4,8,6,16,3,3,4,1,8,"text"} ) -- Ans: {1, 16, 15, 8.5}

8.12.1.4.5 See also:

smallest largest

Enums used to influence the results of some of these functions.

8.12.1.5 ST_FULLPOP

include std/stats.e 
public enum ST_FULLPOP

The supplied data is the entire population.

8.12.1.6 ST_SAMPLE

include std/stats.e 
public enum ST_SAMPLE

The supplied data is only a random sample of the population.

8.12.1.7 ST_ALLNUM

include std/stats.e 
public enum ST_ALLNUM

The supplied data consists of only atoms.

8.12.1.8 ST_IGNSTR

include std/stats.e 
public enum ST_IGNSTR

Any sub-sequences (eg. strings) in the supplied data are ignored.

8.12.1.9 ST_ZEROSTR

include std/stats.e 
public enum ST_ZEROSTR

Any sub-sequences (eg. strings) in the supplied data are assumed to have the value zero.

8.12.1.10 stdev

include std/stats.e 
public function stdev(sequence data_set, object subseq_opt = ST_ALLNUM, integer population_type = ST_SAMPLE)

Returns the standard deviation based of the population.

8.12.1.10.1 Parameters:

data_set : a list of 1 or more numbers for which you want the estimated standard deviation.
subseq_opt : an object. When this is ST_ALLNUM (the default) it means that data_set is assumed to contain no sub-sequences otherwise this gives instructions about how to treat sub-sequences. See comments for details.
population_type : an integer. ST_SAMPLE (the default) assumes that data_set is a random sample of the total population. ST_FULLPOP means that data_set is the entire population.

8.12.1.10.2 Returns:

An atom, the estimated standard deviation. An empty sequence means that there is no meaningful data to calculate from.

8.12.1.10.3 Comments:

stdev() is a measure of how values are different from the average.

The numbers in data_set can either be the entire population of values or just a random subset. You indicate which in the population_type parameter. By default data_set represents a sample and not the entire population. When using this function with sample data, the result is an estimated standard deviation.

If the data can contain sub-sequences, such as strings, you need to let the the function know about this otherwise it assumes every value in data_set is an number. If that is not the case then the function will crash. So it is important that if it can possibly contain sub-sequences that you tell this function what to do with them. Your choices are to ignore them or assume they have the value zero. To ignore them, use ST_IGNSTR as the subseq_opt parameter value otherwise use ST_ZEROSTR. However, if you know that data_set only contains numbers use the default subseq_opt value, ST_ALLNUM. Note It is faster if the data only contains numbers.

8.12.1.10.4 The equation for standard deviation is:

stdev(X) ==> SQRT(SUM(SQ(X{1..N} - MEAN)) / (N))

8.12.1.10.5 Example 1:

? stdev( {4,5,6,7,5,4,3,7} )                             -- Ans: 1.457737974 
? stdev( {4,5,6,7,5,4,3,7} ,, ST_FULLPOP)                -- Ans: 1.363589014 
? stdev( {4,5,6,7,5,4,3,"text"} , ST_IGNSTR)             -- Ans: 1.345185418 
? stdev( {4,5,6,7,5,4,3,"text"}, ST_IGNSTR, ST_FULLPOP ) -- Ans: 1.245399698 
? stdev( {4,5,6,7,5,4,3,"text"} , 0)                     -- Ans: 2.121320344 
? stdev( {4,5,6,7,5,4,3,"text"}, 0, ST_FULLPOP )         -- Ans: 1.984313483

8.12.1.10.6 See also:

average, avedev

8.12.1.11 avedev

include std/stats.e 
public function avedev(sequence data_set, object subseq_opt = ST_ALLNUM, integer population_type = ST_SAMPLE)

Returns the average of the absolute deviations of data points from their mean.

8.12.1.11.1 Parameters:

data_set : a list of 1 or more numbers for which you want the mean of the absolute deviations.
subseq_opt : an object. When this is ST_ALLNUM (the default) it means that data_set is assumed to contain no sub-sequences otherwise this gives instructions about how to treat sub-sequences. See comments for details.
population_type : an integer. ST_SAMPLE (the default) assumes that data_set is a random sample of the total population. ST_FULLPOP means that data_set is the entire population.

8.12.1.11.2 Returns:

An atom , the deviation from the mean.
An empty sequence, means that there is no meaningful data to calculate from.

8.12.1.11.3 Comments:

avedev() is a measure of the variability in a data set. Its statistical properties are less well behaved than those of the standard deviation, which is why it is used less.

The equation for absolute average deviation is:

avedev(X) ==> SUM( ABS(X{1..N} - MEAN(X)) ) / N

8.12.1.11.4 Example 1:

? avedev( {7,2,8,5,6,6,4,8,6,6,3,3,4,1,8,7} ) -- Ans: 1.966666667 
? avedev( {7,2,8,5,6,6,4,8,6,6,3,3,4,1,8,7},, ST_FULLPOP ) -- Ans: 1.84375 
? avedev( {7,2,8,5,6,6,4,8,6,6,3,3,4,1,8,"text"}, ST_IGNSTR  ) -- Ans: 1.99047619 
? avedev( {7,2,8,5,6,6,4,8,6,6,3,3,4,1,8,"text"}, ST_IGNSTR,ST_FULLPOP ) -- Ans: 1.857777778 
? avedev( {7,2,8,5,6,6,4,8,6,6,3,3,4,1,8,"text"}, 0 ) -- Ans: 2.225 
? avedev( {7,2,8,5,6,6,4,8,6,6,3,3,4,1,8,"text"}, 0, ST_FULLPOP ) -- Ans: 2.0859375

8.12.1.11.5 See also:

average, stdev

8.12.1.12 sum

include std/stats.e 
public function sum(object data_set, object subseq_opt = ST_ALLNUM)

Returns the sum of all the atoms in an object.

8.12.1.12.1 Parameters:

data_set : Either an atom or a list of numbers to sum.
subseq_opt : an object. When this is ST_ALLNUM (the default) it means that data_set is assumed to contain no sub-sequences otherwise this gives instructions about how to treat sub-sequences. See comments for details.

8.12.1.12.2 Returns:

An atom, the sum of the set.

8.12.1.12.3 Comments:

sum() is used as a measure of the magnitude of a sequence of positive values.

The equation is:

sum(X) ==> SUM( X{1..N} )

8.12.1.12.4 Example 1:

? sum( {7,2,8.5,6,6,-4.8,6,6,3.341,-8,"text"}, 0 ) -- Ans: 32.041

8.12.1.12.5 See also:

8.12.1.13 count

include std/stats.e 
public function count(object data_set, object subseq_opt = ST_ALLNUM)

Returns the count of all the atoms in an object.

8.12.1.13.1 Parameters:

data_set : either an atom or a list.
subseq_opt : an object. When this is ST_ALLNUM (the default) it means that data_set is assumed to contain no sub-sequences otherwise this gives instructions about how to treat sub-sequences. See comments for details.

8.12.1.13.2 Comments:

This returns the number of numbers in data_set

8.12.1.13.3 Returns:

An integer, the number of atoms in the set. When data_set is an atom, 1 is returned.

8.12.1.13.4 Example 1:

? count( {7,2,8.5,6,6,-4.8,6,6,3.341,-8,"text"} ) -- Ans: 10 
? count( {"cat", "dog", "lamb", "cow", "rabbit"} ) -- Ans: 0 (no atoms) 
? count( 5 ) -- Ans: 1

8.12.1.13.5 See also:

average, sum

8.12.1.14 average

include std/stats.e 
public function average(object data_set, object subseq_opt = ST_ALLNUM)

Returns the average (mean) of the data points.

8.12.1.14.1 Parameters:

data_set : A list of 1 or more numbers for which you want the mean.
subseq_opt : an object. When this is ST_ALLNUM (the default) it means that data_set is assumed to contain no sub-sequences otherwise this gives instructions about how to treat sub-sequences. See comments for details.

8.12.1.14.2 Returns:

An object,

{} (the empty sequence) if there are no atoms in the set.
an atom (the mean) if there are one or more atoms in the set.

8.12.1.14.3 Comments:

average() is the theoretical probable value of a randomly selected item from the set.

8.12.1.14.4 The equation for average is:

average(X) ==> SUM( X{1..N} ) / N

8.12.1.14.5 Example 1:

? average( {7,2,8,5,6,6,4,8,6,6,3,3,4,1,8,"text"}, ST_IGNSTR ) -- Ans: 5.13333333

8.12.1.14.6 See also:

geomean, harmean, movavg, emovavg

8.12.1.15 geomean

include std/stats.e 
public function geomean(object data_set, object subseq_opt = ST_ALLNUM)

Returns the geometric mean of the atoms in a sequence.

8.12.1.15.1 Parameters:

data_set : the values to take the geometric mean of.
subseq_opt : an object. When this is ST_ALLNUM (the default) it means that data_set is assumed to contain no sub-sequences otherwise this gives instructions about how to treat sub-sequences. See comments for details.

8.12.1.15.2 Returns:

An atom, the geometric mean of the atoms in data_set. If there is no atom to take the mean of, 1 is returned.

8.12.1.15.3 Comments:

The geometric mean of N atoms is the N-th root of their product. Signs are ignored.

This is useful to compute average growth rates.

8.12.1.15.4 Example 1:

? geomean({3, "abc", -2, 6}, ST_IGNSTR) -- prints out power(36,1/3) = 3,30192724889462669 
? geomean({1,2,3,4,5,6,7,8,9,10}) -- = 4.528728688

8.12.1.15.5 See Also:

8.12.1.16 harmean

include std/stats.e 
public function harmean(sequence data_set, object subseq_opt = ST_ALLNUM)

Returns the harmonic mean of the atoms in a sequence.

8.12.1.16.1 Parameters:

data_set : the values to take the harmonic mean of.
subseq_opt : an object. When this is ST_ALLNUM (the default) it means that data_set is assumed to contain no sub-sequences otherwise this gives instructions about how to treat sub-sequences. See comments for details.

8.12.1.16.2 Returns:

An atom, the harmonic mean of the atoms in data_set.

8.12.1.16.3 Comments:

The harmonic mean is the inverse of the average of their inverses.

This is useful in engineering to compute equivalent capacities and resistances.

8.12.1.16.4 Example 1:

? harmean({3, "abc", -2, 6}, ST_IGNSTR) -- =  0. 
? harmean({{2, 3, 4}) -- 3 / (1/2 + 1/3 + 1/4) = 2.769230769

8.12.1.16.5 See Also:

8.12.1.17 movavg

include std/stats.e 
public function movavg(object data_set, object period_delta)

Returns the average (mean) of the data points for overlaping periods. This can be either a simple or weighted moving average.

8.12.1.17.1 Parameters:

data_set : a list of 1 or more numbers for which you want a moving average.
period_delta : an object, either

an integer representing the size of the period, or
a list of weightings to apply to the respective period positions.

8.12.1.17.2 Returns:

A sequence, either the requested averages or {} if the Data sequence is empty or the supplied period is less than one.

If a list of weights was supplied, the result is a weighted average; otherwise, it is a simple average.

8.12.1.17.3 Comments:

A moving average is used to smooth out a set of data points over a period.
For example, given a period of 5:

the first returned element is the average of the first five data points [1..5],
the second returned element is the average of the second five data points [2..6],
and so on
until the last returned value is the average of the last 5 data points [$-4 .. $].

When period_delta is an atom, it is rounded down to the width of the average. When it is a sequence, the width is its length. If there are not enough data points, zeroes are inserted.

Note that only atom elements are included and any sub-sequence elements are ignored.

8.12.1.17.4 Example 1:

? movavg( {7,2,8,5,6,6,4,8,6,6,3,3,4,1,8}, 10 )  
 -- Ans: {5.8, 5.4, 5.5, 5.1, 4.7, 4.9} 
? movavg( {7,2,8,5,6}, 2 )  
 -- Ans: {4.5, 5, 6.5, 5.5} 
? movavg( {7,2,8,5,6}, {0.5, 1.5} )  
 -- Ans: {3.25, 6.5, 5.75, 5.75}

8.12.1.17.5 See also:

8.12.1.18 emovavg

include std/stats.e 
public function emovavg(object data_set, atom smoothing_factor)

Returns the exponential moving average of a set of data points.

8.12.1.18.1 Parameters:

data_set : a list of 1 or more numbers for which you want a moving average.
smoothing_factor : an atom, the smoothing factor, typically between 0 and 1.

8.12.1.18.2 Returns:

A sequence, made of the requested averages, or {} if data_set is empty or the supplied period is less than one.

8.12.1.18.3 Comments:

A moving average is used to smooth out a set of data points over a period.

The formula used is:

Y_i = Y_i-1 + F * (X_i - Y_i-1)

Note that only atom elements are included and any sub-sequences elements are ignored.

The smoothing factor controls how data is smoothed. 0 smooths everything to 0, and 1 means no smoothing at all.

Any value for smoothing_factor outside the 0.0..1.0 range causes smoothing_factor to be set to the periodic factor (2/(N+1)).

8.12.1.18.4 Example 1:

? emovavg( {7,2,8,5,6}, 0.75 )  
 -- Ans: {5.25,2.8125,6.703125,5.42578125,5.856445313} 
? emovavg( {7,2,8,5,6}, 0.25 )  
 -- Ans: {1.75,1.8125,3.359375,3.76953125,4.327148438} 
? emovavg( {7,2,8,5,6}, -1 )  
 -- Ans: {2.333333333,2.222222222,4.148148148,4.432098765,4.95473251}

8.12.1.18.5 See also:

8.12.1.19 median

include std/stats.e 
public function median(object data_set, object subseq_opt = ST_ALLNUM)

Returns the mid point of the data points.

8.12.1.19.1 Parameters:

data_set : a list of 1 or more numbers for which you want the mean.
subseq_opt : an object. When this is ST_ALLNUM (the default) it means that data_set is assumed to contain no sub-sequences otherwise this gives instructions about how to treat sub-sequences. See comments for details.

8.12.1.19.2 Returns:

An object, either {} if there are no items in the set, or an atom (the median) otherwise.

8.12.1.19.3 Comments:

median() is the item for which half the items are below it and half are above it.

All elements are included; any sequence elements are assumed to have the value zero.

8.12.1.19.4 The equation for average is:

median(X) ==> sort(X)[N/2]

8.12.1.19.5 Example 1:

? median( {7,2,8,5,6,6,4,8,6,6,3,3,4,1,8,4} ) -- Ans: 5

8.12.1.19.6 See also:

average, geomean, harmean, movavg, emovavg

8.12.1.20 raw_frequency

include std/stats.e 
public function raw_frequency(object data_set, object subseq_opt = ST_ALLNUM)

Returns the frequency of each unique item in the data set.

8.12.1.20.1 Parameters:

data_set : a list of 1 or more numbers for which you want the frequencies.
subseq_opt : an object. When this is ST_ALLNUM (the default) it means that data_set is assumed to contain no sub-sequences otherwise this gives instructions about how to treat sub-sequences. See comments for details.

8.12.1.20.2 Returns:

A sequence. This will contain zero or more 2-element sub-sequences. The first element is the frequency count and the second element is the data item that was counted. The returned values are in descending order, meaning that the highest frequencies are at the beginning of the returned list.

8.12.1.20.3 Comments:

8.12.1.20.4 Example 1:

? raw_frequency("the cat is the hatter")

This returns

{ 
{5,116}, 
{4,32}, 
{3,104}, 
{3,101}, 
{2,97}, 
{1,115}, 
{1,114}, 
{1,105}, 
{1,99} 
}

8.12.1.21 mode

include std/stats.e 
public function mode(object data_set, object subseq_opt = ST_ALLNUM)

Returns the most frequent point(s) of the data set.

8.12.1.21.1 Parameters:

data_set : a list of 1 or more numbers for which you want the mode.
subseq_opt : an object. When this is ST_ALLNUM (the default) it means that data_set is assumed to contain no sub-sequences otherwise this gives instructions about how to treat sub-sequences. See comments for details.

8.12.1.21.2 Returns:

A sequence. The list of modal items in the data set.

8.12.1.21.3 Comments:

It is possible for the mode() to return more than one item when more than one item in the set has the same highest frequency count.

8.12.1.21.4 Example 1:

mode( {7,2,8,5,6,6,4,8,6,6,3,3,4,1,8,4} ) -- Ans: {6} 
mode( {8,2,8,5,6,6,4,8,6,6,3,3,4,1,8,4} ) -- Ans: {8,6}

8.12.1.21.5 See also:

average, geomean, harmean, movavg, emovavg

8.12.1.22 central_moment

include std/stats.e 
public function central_moment(object data_set, object datum, integer order_mag = 1, object subseq_opt = ST_ALLNUM)

Returns the distance between a supplied value and the mean, to some supplied order of magnitude. This is used to get a measure of the shape of a data set.

8.12.1.22.1 Parameters:

data_set : a list of 1 or more numbers whose mean is used.
datum: either a single value or a list of values for which you require the central moments.
order_mag: An integer. This is the order of magnitude required. Usually a number from 1 to 4, but can be anything.
subseq_opt : an object. When this is ST_ALLNUM (the default) it means that data_set is assumed to contain no sub-sequences otherwise this gives instructions about how to treat sub-sequences. See comments for details.

8.12.1.22.2 Returns:

An object. The same data type as datum. This is the set of calculated central moments.

8.12.1.22.3 Comments:

For each of the items in #datum, its central moment is calculated as ...

CM = power( ITEM - AVG, MAGNITUDE)

8.12.1.22.4 Example 1:

central_moment("the cat is the hatter", "the",1) --> {23.14285714, 11.14285714, 8.142857143} 
central_moment("the cat is the hatter", 't',2) -->   535.5918367                           
central_moment("the cat is the hatter", 't',3) -->   12395.12536

8.12.1.22.5 See also:

task_create, task_schedule, task_suspend

8.12.1.23 sum_central_moments

include std/stats.e 
public function sum_central_moments(object data_set, integer order_mag = 1, object subseq_opt = ST_ALLNUM)

Returns sum of the central moments of each item in a data set.

8.12.1.23.1 Parameters:

data_set : a list of 1 or more numbers whose mean is used.
order_mag: An integer. This is the order of magnitude required. Usually a number from 1 to 4, but can be anything.
subseq_opt : an object. When this is ST_ALLNUM (the default) it means that data_set is assumed to contain no sub-sequences otherwise this gives instructions about how to treat sub-sequences. See comments for details.

8.12.1.23.2 Returns:

An atom. The total of the central moments calculated for each of the items in data_set.

8.12.1.23.3 Comments:

8.12.1.23.4 Example 1:

sum_central_moments("the cat is the hatter", 1) --> -8.526512829e-14 
sum_central_moments("the cat is the hatter", 2) --> 19220.57143      
sum_central_moments("the cat is the hatter", 3) --> -811341.551      
sum_central_moments("the cat is the hatter", 4) --> 56824083.71

8.12.1.23.5 See also:

central_moment, average

8.12.1.24 skewness

include std/stats.e 
public function skewness(object data_set, object subseq_opt = ST_ALLNUM)

Returns a measure of the asymmetry of a data set. Usually the data_set is a probablity distribution but it can be anything. This value is used to assess how suitable the data set is in representing the required analysis. It can help detect if there are too many extreme values in the data set.

8.12.1.24.1 Parameters:

data_set : a list of 1 or more numbers whose mean is used.
subseq_opt : an object. When this is ST_ALLNUM (the default) it means that data_set is assumed to contain no sub-sequences otherwise this gives instructions about how to treat sub-sequences. See comments for details.

8.12.1.24.2 Returns:

An atom. The skewness measure of the data set.

8.12.1.24.3 Comments:

Generally speaking, a negative return indicates that most of the values are lower than the mean, while positive values indicate that most values are greater than the mean. However this might not be the case when there are a few extreme values on one side of the mean.

The larger the magnitude of the returned value, the more the data is skewed in that direction.

A returned value of zero indicates that the mean and median values are identical and that the data is symmetrical.

8.12.1.24.4 Example 1:

skewness("the cat is the hatter") --> -1.296820819 
skewness("thecatisthehatter")     --> 0.1029393238

8.12.1.24.5 See also:

kurtosis

8.12.1.25 kurtosis

include std/stats.e 
public function kurtosis(object data_set, object subseq_opt = ST_ALLNUM)

Returns a measure of the spread of values in a dataset when compared to a normal probability curve.

8.12.1.25.1 Parameters:

data_set : a list of 1 or more numbers whose kurtosis is required.
subseq_opt : an object. When this is ST_ALLNUM (the default) it means that data_set is assumed to contain no sub-sequences otherwise this gives instructions about how to treat sub-sequences. See comments for details.

8.12.1.25.2 Returns:

An object. If this is an atom it is the kurtosis measure of the data set. Othewise it is a sequence containing an error integer. The return value {0} indicates that an empty dataset was passed, {1} indicates that the standard deviation is zero (all values are the same).

8.12.1.25.3 Comments:

Generally speaking, a negative return indicates that most of the values are further from the mean, while positive values indicate that most values are nearer to the mean.

The larger the magnitude of the returned value, the more the data is 'peaked' or 'flatter' in that direction.

8.12.1.25.4 Example 1:

kurtosis("thecatisthehatter")     --> -1.737889192

8.12.1.25.5 See also:

skewness

8.13 Multi-tasking

Page Contents

---------- General Notes

---------- Warning

---------- Routines

---------------- task_delay

---------------- task_clock_start

---------------- task_clock_stop

---------------- task_create

---------------- task_list

---------------- task_schedule

---------------- task_self

---------------- task_status

---------------- task_suspend

---------------- task_yield

8.13.1 General Notes

For a complete overview of the task system, please see the mini-guide Multitasking in EUPHORIA.

8.13.2 Warning

The task system does not yet function in a shared library. Task routine calls that are compiled into a shared library are emitted as a NOP (no operation) and will therefore have no effect.

It is planned to allow the task system to function in shared libraries in future versions of OpenEUPHORIA.

8.13.3 Routines

8.13.3.1 task_delay

include std/task.e 
public procedure task_delay(atom delaytime)

Suspends a task for a short period, allowing other tasks to run in the meantime.

8.13.3.1.1 Parameters:

delaytime : an atom, the duration of the delay in seconds.

8.13.3.1.2 Comments:

This procedure is similar to sleep(), but allows for other tasks to run by yielding on a regular basis. Like sleep(), its argument needs not being an integer.

8.13.3.1.3 See Also:

sleep

8.13.3.2 task_clock_start

<built-in> procedure task_clock_start()

Restart the clock used for scheduling real-time tasks.

8.13.3.2.1 Comments:

Call this routine, some time after calling task_clock_stop(), when you want scheduling of real-time tasks to continue.

task_clock_stop() and task_clock_start() can be used to freeze the scheduling of real-time tasks.

task_clock_start() causes the scheduled times of all real-time tasks to be incremented by the amount of time since task_clock_stop() was called. This allows a game, simulation, or other program to continue smoothly.

Time-shared tasks are not affected.

8.13.3.2.2 Example 1:

 -- freeze the game while the player answers the phone 
task_clock_stop() 
while get_key() = -1 do 
end while 
task_clock_start()

8.13.3.2.3 See Also:

task_clock_stop, task_schedule, task_yield, task_suspend, task_delay

8.13.3.3 task_clock_stop

<built-in> procedure task_clock_stop()

Stop the scheduling of real-time tasks.

8.13.3.3.1 Comments:

Call task_clock_stop() when you want to take time out from scheduling real-time tasks. For instance, you want to temporarily suspend a game or simulation for a period of time.

Scheduling will resume when task_clock_start() is called.

Time-shared tasks can continue. The current task can also continue, unless it's a real-time task and it yields.

The time() function is not affected by this.

8.13.3.3.2 See Also:

task_clock_start, task_schedule, task_yield, task_suspend, task_delay

8.13.3.4 task_create

<built-in> function task_create(integer rid, sequence args)

Create a new task, given a home procedure and the arguments passed to it.

8.13.3.4.1 Parameters:

rid : an integer, the routine_id of a user-defined EUPHORIA procedure.
args : a sequence, the list of arguments that will be passed to this procedure when the task starts executing.

8.13.3.4.2 Returns:

An atom, a task identifier, created by the system. It can be used to identify this task to the other EUPHORIA multitasking routines.

8.13.3.4.3 Errors:

There must be at most 12 parameters in args.

8.13.3.4.4 Comments:

task_create() creates a new task, but does not start it executing. You must call task_schedule() for this purpose.

Each task has its own set of private variables and its own call stack. Global and local variables are shared between all tasks.

If a run-time error is detected, the traceback will include information on all tasks, with the offending task listed first.

Many tasks can be created that all run the same procedure, possibly with different parameters.

A task cannot be based on a function, since there would be no way of using the function result.

Each task id is unique. task_create() never returns the same task id as it did before. Task id's are integer-valued atoms and can be as large as the largest integer-valued atom (15 digits).

8.13.3.4.5 Example 1:

 mytask = task_create(routine_id("myproc"), {5, 9, "ABC"})

8.13.3.4.6 See Also:

task_schedule, task_yield, task_suspend, task_self

8.13.3.5 task_list

<built-in> function task_list()

Get a sequence containing the task id's for all active or suspended tasks.

8.13.3.5.1 Returns:

A sequence, of atoms, the list of all task that are or may be scheduled.

8.13.3.5.2 Comments:

This function lets you find out which tasks currently exist. Tasks that have terminated are not included. You can pass a task id to task_status() to find out more about a particular task.

8.13.3.5.3 Example 1:

 sequence tasks 
 
tasks = task_list() 
for i = 1 to length(tasks) do 
    if task_status(tasks[i]) > 0 then 
        printf(1, "task %d is active\n", tasks[i]) 
    end if 
end for

8.13.3.5.4 See Also:

task_status, task_create, task_schedule, task_yield, task_suspend

8.13.3.6 task_schedule

<built-in> procedure task_schedule(atom task_id, object schedule)

Schedule a task to run using a scheduling parameter.

8.13.3.6.1 Parameters:

task_id : an atom, the identifier of a task that did not terminate yet.
schedule : an object, describing when and how often to run the task.

8.13.3.6.2 Comments:

task_id must have been returned by task_create().

The task scheduler, which is built-in to the EUPHORIA run-time system, will use schedule as a guide when scheduling this task. It may not always be possible to achieve the desired number of consecutive runs, or the desired time frame. For instance, a task might take so long before yielding control, that another task misses its desired time window.

schedule is being interpreted as follows:

schedule is an integer:

This defines task_id as time shared, and tells the task scheduler how many times it should the task in one burst before it considers running other tasks. schedule must be greater than zero then.

Increasing this count will increase the percentage of CPU time given to the selected task, while decreasing the percentage given to other time-shared tasks. Use trial and error to find the optimal trade off. It will also increase the efficiency of the program, since each actual task switch wastes a bit of time.

schedule is a sequence:

In this case, it must be a pair of positive atoms, the first one not being less than the second one. This defines task_id as a real time task. The pair states the minimum and maximum times, in seconds, to wait before running the task. The pair also sets the time interval for subsequent runs of the task, until the next call to task_schedule() or task_suspend().

Real-time tasks have a higher priority. Time-shared tasks are run when no real-time task is ready to execute.

A task can switch back and forth between real-time and time-shared. It all depends on the last call to task_schedule() for that task. The scheduler never runs a real-time task before the start of its time frame (min value in the {min, max} pair), and it tries to avoid missing the task's deadline (max value).

For precise timing, you can specify the same value for min and max. However, by specifying a range of times, you give the scheduler some flexibility. This allows it to schedule tasks more efficiently, and avoid non-productive delays. When the scheduler must delay, it calls sleep(), unless the required delay is very short. sleep() lets the operating system run other programs.

The min and max values can be fractional. If the min value is smaller than the resolution of the scheduler's clock (currently 0.01 seconds on Windows or Unix) then accurate time scheduling cannot be performed, but the scheduler will try to run the task several times in a row to approximate what is desired.

For example, if you ask for a min time of 0.002 seconds, then the scheduler will try to run your task .01/.002 = 5 times in a row before waiting for the clock to "click" ahead by .01. During the next 0.01 seconds it will run your task (up to) another 5 times etc. provided your task can be completed 5 times in one clock period.

At program start-up there is a single task running. Its task id is 0, and initially it's a time-shared task allowed 1 run per task_yield(). No other task can run until task 0 executes a task_yield().

If task 0 (top-level) runs off the end of the main file, the whole program terminates, regardless of what other tasks may still be active.

If the scheduler finds that no task is active, i.e. no task will ever run again (not even task 0), it terminates the program with a 0 exit code, similar to abort(0).

8.13.3.6.3 Example 1:

-- Task t1 will be executed up to 10 times in a row before 
-- other time-shared tasks are given control. If a real-time 
-- task needs control, t1 will lose control to the real-time task. 
task_schedule(t1, 10) 
 
-- Task t2 will be scheduled to run some time between 4 and 5 seconds 
-- from now. Barring any rescheduling of t2, it will continue to 
-- execute every 4 to 5 seconds thereafter. 
task_schedule(t2, {4, 5})

8.13.3.6.4 See Also:

task_create, task_yield, task_suspend

8.13.3.7 task_self

<built-in> function task_self()

Return the task id of the current task.

8.13.3.7.1 Comments:

This value may be needed, if a task wants to schedule or suspend itself.

8.13.3.7.2 Example 1:

 -- schedule self 
task_schedule(task_self(), {5.9, 6.0})

8.13.3.7.3 See Also:

task_create, task_schedule, task_yield, task_suspend

8.13.3.8 task_status

<built-in> function task_status(atom task_id)

Return the status of a task.

8.13.3.8.1 Parameters:

task_id : an atom, the id of the task being queried.

8.13.3.8.2 Returns:

An integer,

-1 -- task does not exist, or terminated
0 -- task is suspended
1 -- task is active

8.13.3.8.3 Comments:

A task might want to know the status of one or more other tasks when deciding whether to proceed with some processing.

8.13.3.8.4 Example 1:

 integer s 
 
s = task_status(tid) 
if s = 1 then 
    puts(1, "ACTIVE\n") 
elsif s = 0 then 
    puts(1, "SUSPENDED\n") 
else 
    puts(1, "DOESN'T EXIST\n") 
end if

8.13.3.8.5 See Also:

task_list, task_create, task_schedule, task_suspend

8.13.3.9 task_suspend

<built-in> procedure task_suspend(atom task_id)

Suspend execution of a task.

8.13.3.9.1 Parameters:

task_id : an atom, the id of the task to suspend.

8.13.3.9.2 Comments:

A suspended task will not be executed again unless there is a call to task_schedule() for the task.

task_id is a task id returned from task_create(). - Any task can suspend any other task. If a task suspends itself, the suspension will start as soon as the task calls task_yield().

Suspending a task and never scheduling it again is how to kill a task. There is no task_kill() primitives because undead tasks were creating too much trouble and confusion. As a general fact, nothing that impacts a running task can be effective as long as the task has not yielded.

8.13.3.9.3 Example 1:

 -- suspend task 15 
task_suspend(15) 
 
-- suspend current task 
task_suspend(task_self())

8.13.3.9.4 See Also:

task_create, task_schedule, task_self, task_yield

8.13.3.10 task_yield

<built-in> procedure task_yield()

Yield control to the scheduler. The scheduler can then choose another task to run, or perhaps let the current task continue running.

8.13.3.10.1 Comments:

Tasks should call task_yield() periodically so other tasks will have a chance to run. Only when task_yield() is called, is there a way for the scheduler to take back control from a task. This is what's known as cooperative multitasking.

A task can have calls to task_yield() in many different places in its code, and at any depth of subroutine call.

The scheduler will use the current scheduling parameter (see task_schedule), in determining when to return to the current task.

When control returns, execution will continue with the statement that follows task_yield(). The call-stack and all private variables will remain as they were when task_yield() was called. Global and local variables may have changed, due to the execution of other tasks.

Tasks should try to call task_yield() often enough to avoid causing real-time tasks to miss their time window, and to avoid blocking time-shared tasks for an excessive period of time. On the other hand, there is a bit of overhead in calling task_yield (), and this overhead is slightly larger when an actual switch to a different task takes place. A task_yield() where the same task continues executing takes less time.

A task should avoid calling task_yield() when it is in the middle of a delicate operation that requires exclusive access to some data. Otherwise a race condition could occur, where one task might interfere with an operation being carried out by another task. In some cases a task might need to mark some data as "locked" or "unlocked" in order to prevent this possibility. With cooperative multitasking, these concurrency issues are much less of a problem than with the preemptive multitasking that other languages support.

8.13.3.10.2 Example 1:

 -- From Language war game. 
-- This small task deducts life support energy from either the 
-- large EUPHORIA ship or the small shuttle. 
-- It seems to run "forever" in an infinite loop,  
-- but it's actually a real-time task that is called 
-- every 1.7 to 1.8 seconds throughout the game. 
-- It deducts either 3 units or 13 units of life support energy each time. 
 
procedure task_life() 
-- independent task: subtract life support energy  
    while TRUE do 
        if shuttle then 
            p_energy(-3) 
        else 
            p_energy(-13) 
        end if 
        task_yield() 
    end while 
end procedure

8.13.3.10.3 See Also:

8.14 Types - Extended

---------------- OBJ_UNASSIGNED

---------------- OBJ_INTEGER

---------------- OBJ_ATOM

---------------- OBJ_SEQUENCE

---------------- object

---------------- integer

---------------- atom

---------------- sequence

---------------- FALSE

---------------- TRUE

---------------- CS_FIRST

---------- Support Functions

---------------- char_test

---------------- set_default_charsets

---------------- get_charsets

---------------- set_charsets

---------- Types

---------------- boolean

---------------- t_boolean

---------------- t_alnum

---------------- t_identifier

---------------- t_alpha

---------------- t_ascii

---------------- t_cntrl

---------------- t_digit

---------------- t_graph

---------------- t_specword

---------------- t_bytearray

---------------- t_lower

---------------- t_print

---------------- t_display

---------------- t_punct

---------------- t_space

---------------- t_upper

---------------- t_xdigit

---------------- t_vowel

---------------- t_consonant

---------------- integer_array

---------------- t_text

---------------- number_array

---------------- sequence_array

---------------- ascii_string

---------------- string

8.14.1 OBJ_UNASSIGNED

include std/types.e 
public constant OBJ_UNASSIGNED

Object not assigned

8.14.1.1 OBJ_INTEGER

include std/types.e 
public constant OBJ_INTEGER

Object is integer

8.14.1.2 OBJ_ATOM

include std/types.e 
public constant OBJ_ATOM

Object is atom

8.14.1.3 OBJ_SEQUENCE

include std/types.e 
public constant OBJ_SEQUENCE

Object is sequence

8.14.1.4 object

<built-in> function object(object x)

Returns information about the object type of the supplied argument x.

8.14.1.4.1 Returns:

An integer.

OBJ_UNASSIGNED if x has not been assigned anything yet.
OBJ_INTEGER if x holds an integer value.
OBJ_ATOM if x holds a number that is not an integer.
OBJ_SEQUENCE if x holds a sequence value.

8.14.1.4.2 Example 1:

? object(1) --> OBJ_INTEGER 
? object(1.1) --> OBJ_ATOM 
? object("1") --> OBJ_SEQUENCE 
object x 
? object(x) --> OBJ_UNASSIGNED

8.14.1.4.3 See Also:

sequence(), integer (), atom()

8.14.1.5 integer

<built-in> function integer(object x)

Tests the supplied argument x to see if it is an integer or not.

8.14.1.5.1 Returns:

An integer.

1 if x is an integer.
0 if x is not an integer.

8.14.1.5.2 Example 1:

? integer(1) --> 1 
? integer(1.1) --> 0 
? integer("1") --> 0

8.14.1.5.3 See Also:

sequence(), object(), atom()

8.14.1.6 atom

<built-in> function atom(object x)

Tests the supplied argument x to see if it is an atom or not.

8.14.1.6.1 Returns:

An integer.

1 if x is an atom.
0 if x is not an atom.

8.14.1.6.2 Example 1:

? atom(1) --> 1 
? atom(1.1) --> 1 
? atom("1") --> 0

8.14.1.6.3 See Also:

sequence(), object(), integer()

8.14.1.7 sequence

<built-in> function sequence( object x)

Tests the supplied argument x to see if it is a sequence or not.

8.14.1.7.1 Returns:

An integer.

1 if x is a sequence.
0 if x is not an sequence.

8.14.1.7.2 Example 1:

? integer(1) --> 0 
? integer(1.1) --> 0 
? integer("1") --> 1

8.14.1.7.3 See Also:

integer(), object(), atom()

8.14.1.8 FALSE

include std/types.e 
public constant FALSE

Boolean FALSE value

8.14.1.9 TRUE

include std/types.e 
public constant TRUE

Boolean TRUE value

8.14.1.10 CS_FIRST

include std/types.e 
public enum CS_FIRST

8.14.1.10.1 Predefined character sets:

8.14.2 Support Functions

8.14.2.1 char_test

include std/types.e 
public function char_test(object test_data, sequence char_set)

Determine whether one or more characters are in a given character set.

8.14.2.1.1 Parameters:

test_data : an object to test, either a character or a string
char_set : a sequence, either a list of allowable characters, or a list of pairs representing allowable ranges.

8.14.2.1.2 Returns:

An integer, 1 if all characters are allowed, else 0.

8.14.2.1.3 Comments:

pCharset is either a simple sequence of characters eg. "qwertyuiop[]
" or a sequence of character pairs, which represent allowable ranges of characters. eg. Alphabetic is defined as {{'a','z'}, {'A', 'Z'}}

To add an isolated character to a character set which is defined using ranges, present it as a range of length 1, like in {%,%} .

8.14.2.1.4 Example 1:

char_test("ABCD", {{'A', 'D'}}) 
-- TRUE, every char is in the range 'A' to 'D' 
 
char_test("ABCD", {{'A', 'C'}}) 
-- FALSE, not every char is in the range 'A' to 'C' 
 
char_test("Harry", {{'a', 'z'}, {'D', 'J'}}) 
-- TRUE, every char is either in the range 'a' to 'z', or in the range 'D' to 'J' 
 
char_test("Potter", "novel") 
-- FALSE, not every character is in the set 'n', 'o', 'v', 'e', 'l'

8.14.2.2 set_default_charsets

include std/types.e 
public procedure set_default_charsets()

Sets all the defined character sets to their default definitions.

8.14.2.2.1 Example 1:

set_default_charsets()

8.14.2.3 get_charsets

include std/types.e 
public function get_charsets()

Gets the definition for each of the defined character sets.

8.14.2.3.1 Returns:

A sequence, of pairs. The first element of each pair is the character set id , eg. CS_Whitespace, and the second is the definition of that character set.

8.14.2.3.2 Comments:

This is the same format required for the set_charsets() routine.

8.14.2.3.3 Example 1:

sequence sets 
sets = get_charsets()

8.14.2.3.4 See Also:

set_charsets, set_default_charsets

8.14.2.4 set_charsets

include std/types.e 
public procedure set_charsets(sequence charset_list)

Sets the definition for one or more defined character sets.

8.14.2.4.1 Parameters:

charset_list : a sequence of zero or more character set definitions.

8.14.2.4.2 Comments:

charset_list must be a sequence of pairs. The first element of each pair is the character set id , eg. CS_Whitespace, and the second is the definition of that character set.

This is the same format returned by the get_charsets() routine.

You cannot create new character sets using this routine.

8.14.2.4.3 Example 1:

set_charsets({{CS_Whitespace, " \t"}}) 
t_space('\n') --> FALSE 
 
t_specword('$') --> FALSE 
set_charsets({{CS_SpecWord, "_-#$%"}}) 
t_specword('$') --> TRUE

8.14.2.4.4 See Also:

get_charsets

8.14.3 Types

8.14.3.1 boolean

include std/types.e 
public type boolean(object test_data)

Returns TRUE if argument is 1 or 0

Returns FALSE if the argument is anything else other than 1 or 0.

8.14.3.1.1 Example 1:

boolean(-1)            -- FALSE 
boolean(0)             -- TRUE 
boolean(1)             -- TRUE 
boolean(1.234)         -- FALSE 
boolean('A')           -- FALSE 
boolean('9')           -- FALSE 
boolean('?')           -- FALSE 
boolean("abc")         -- FALSE 
boolean("ab3")         -- FALSE 
boolean({1,2,"abc"})   -- FALSE 
boolean({1, 2, 9.7)    -- FALSE 
boolean({})            -- FALSE (empty sequence)

8.14.3.2 t_boolean

include std/types.e 
public type t_boolean(object test_data)

Returns TRUE if argument is boolean (1 or 0) or if every element of the argument is boolean.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-boolean elements

8.14.3.2.1 Example 1:

t_boolean(-1)            -- FALSE 
t_boolean(0)             -- TRUE 
t_boolean(1)             -- TRUE 
t_boolean({1, 1, 0})     -- TRUE 
t_boolean({1, 1, 9.7})    -- FALSE 
t_boolean({})            -- FALSE (empty sequence)

8.14.3.3 t_alnum

include std/types.e 
public type t_alnum(object test_data)

Returns TRUE if argument is an alphanumeric character or if every element of the argument is an alphanumeric character.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-alphanumeric elements

8.14.3.3.1 Example 1:

t_alnum(-1)            -- FALSE 
t_alnum(0)             -- FALSE 
t_alnum(1)             -- FALSE 
t_alnum(1.234)         -- FALSE 
t_alnum('A')           -- TRUE 
t_alnum('9')           -- TRUE 
t_alnum('?')           -- FALSE 
t_alnum("abc")         -- TRUE (every element is alphabetic or a digit) 
t_alnum("ab3")         -- TRUE 
t_alnum({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_alnum({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_alnum({})            -- FALSE (empty sequence)

8.14.3.4 t_identifier

include std/types.e 
public type t_identifier(object test_data)

Returns TRUE if argument is an alphanumeric character or if every element of the argument is an alphanumeric character and that the first character is not numeric and the whole group of characters are not all numeric.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-alphanumeric elements

8.14.3.4.1 Example 1:

t_identifier(-1)            -- FALSE 
t_identifier(0)             -- FALSE 
t_identifier(1)             -- FALSE 
t_identifier(1.234)         -- FALSE 
t_identifier('A')           -- TRUE 
t_identifier('9')           -- FALSE 
t_identifier('?')           -- FALSE 
t_identifier("abc")         -- TRUE (every element is alphabetic or a digit) 
t_identifier("ab3")         -- TRUE 
t_identifier("ab_3")        -- TRUE (underscore is allowed) 
t_identifier("1abc")        -- FALSE (identifier cannot start with a number) 
t_identifier("102")         -- FALSE (identifier cannot be all numeric) 
t_identifier({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_identifier({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_identifier({})            -- FALSE (empty sequence)

8.14.3.5 t_alpha

include std/types.e 
public type t_alpha(object test_data)

Returns TRUE if argument is an alphabetic character or if every element of the argument is an alphabetic character.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-alphabetic elements

8.14.3.5.1 Example 1:

t_alpha(-1)            -- FALSE 
t_alpha(0)             -- FALSE 
t_alpha(1)             -- FALSE 
t_alpha(1.234)         -- FALSE 
t_alpha('A')           -- TRUE 
t_alpha('9')           -- FALSE 
t_alpha('?')           -- FALSE 
t_alpha("abc")         -- TRUE (every element is alphabetic) 
t_alpha("ab3")         -- FALSE 
t_alpha({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_alpha({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_alpha({})            -- FALSE (empty sequence)

8.14.3.6 t_ascii

include std/types.e 
public type t_ascii(object test_data)

Returns TRUE if argument is an ASCII character or if every element of the argument is an ASCII character.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-ASCII elements

8.14.3.6.1 Example 1:

t_ascii(-1)            -- FALSE 
t_ascii(0)             -- TRUE 
t_ascii(1)             -- TRUE 
t_ascii(1.234)         -- FALSE 
t_ascii('A')           -- TRUE 
t_ascii('9')           -- TRUE 
t_ascii('?')           -- TRUE 
t_ascii("abc")         -- TRUE (every element is ascii) 
t_ascii("ab3")         -- TRUE 
t_ascii({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_ascii({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_ascii({})            -- FALSE (empty sequence)

8.14.3.7 t_cntrl

include std/types.e 
public type t_cntrl(object test_data)

Returns TRUE if argument is an Control character or if every element of the argument is an Control character.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-Control elements

8.14.3.7.1 Example 1:

t_cntrl(-1)            -- FALSE 
t_cntrl(0)             -- TRUE 
t_cntrl(1)             -- TRUE 
t_cntrl(1.234)         -- FALSE 
t_cntrl('A')           -- FALSE 
t_cntrl('9')           -- FALSE 
t_cntrl('?')           -- FALSE 
t_cntrl("abc")         -- FALSE (every element is ascii) 
t_cntrl("ab3")         -- FALSE 
t_cntrl({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_cntrl({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_cntrl({1, 2, 'a'})    -- FALSE (contains a non-control) 
t_cntrl({})            -- FALSE (empty sequence)

8.14.3.8 t_digit

include std/types.e 
public type t_digit(object test_data)

Returns TRUE if argument is an digit character or if every element of the argument is an digit character.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-digits

8.14.3.8.1 Example 1:

t_digit(-1)            -- FALSE 
t_digit(0)             -- FALSE 
t_digit(1)             -- FALSE 
t_digit(1.234)         -- FALSE 
t_digit('A')           -- FALSE 
t_digit('9')           -- TRUE 
t_digit('?')           -- FALSE 
t_digit("abc")         -- FALSE 
t_digit("ab3")         -- FALSE 
t_digit("123")         -- TRUE 
t_digit({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_digit({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_digit({1, 2, 'a'})    -- FALSE (contains a non-digit) 
t_digit({})            -- FALSE (empty sequence)

8.14.3.9 t_graph

include std/types.e 
public type t_graph(object test_data)

Returns TRUE if argument is a glyph character or if every element of the argument is a glyph character. (One that is visible when displayed)

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-glyph

8.14.3.9.1 Example 1:

t_graph(-1)            -- FALSE 
t_graph(0)             -- FALSE 
t_graph(1)             -- FALSE 
t_graph(1.234)         -- FALSE 
t_graph('A')           -- TRUE 
t_graph('9')           -- TRUE 
t_graph('?')           -- TRUE 
t_graph(' ')           -- FALSE 
t_graph("abc")         -- TRUE 
t_graph("ab3")         -- TRUE 
t_graph("123")         -- TRUE 
t_graph({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_graph({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_graph({1, 2, 'a'})    -- FALSE (control chars (1,2) don't have glyphs) 
t_graph({})            -- FALSE (empty sequence)

8.14.3.10 t_specword

include std/types.e 
public type t_specword(object test_data)

Returns TRUE if argument is a special word character or if every element of the argument is a special word character.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-special-word characters.

8.14.3.10.1 Comments:

A special word character is any character that is not normally part of a word but in certain cases may be considered. This is most commonly used when looking for words in programming source code which allows an underscore as a word character.

8.14.3.10.2 Example 1:

t_specword(-1)            -- FALSE 
t_specword(0)             -- FALSE 
t_specword(1)             -- FALSE 
t_specword(1.234)         -- FALSE 
t_specword('A')           -- FALSE 
t_specword('9')           -- FALSE 
t_specword('?')           -- FALSE 
t_specword('_')           -- TRUE 
t_specword("abc")         -- FALSE 
t_specword("ab3")         -- FALSE 
t_specword("123")         -- FALSE 
t_specword({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_specword({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_specword({1, 2, 'a'})    -- FALSE (control chars (1,2) don't have glyphs) 
t_specword({})            -- FALSE (empty sequence)

8.14.3.11 t_bytearray

include std/types.e 
public type t_bytearray(object test_data)

Returns TRUE if argument is a byte or if every element of the argument is a byte. (Integers from 0 to 255)

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-byte

8.14.3.11.1 Example 1:

t_bytearray(-1)            -- FALSE (contains value less than zero) 
t_bytearray(0)             -- TRUE 
t_bytearray(1)             -- TRUE 
t_bytearray(10)            -- TRUE 
t_bytearray(100)           -- TRUE 
t_bytearray(1000)          -- FALSE (greater than 255) 
t_bytearray(1.234)         -- FALSE (contains a floating number) 
t_bytearray('A')           -- TRUE 
t_bytearray('9')           -- TRUE 
t_bytearray('?')           -- TRUE 
t_bytearray(' ')           -- TRUE 
t_bytearray("abc")         -- TRUE 
t_bytearray("ab3")         -- TRUE 
t_bytearray("123")         -- TRUE 
t_bytearray({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_bytearray({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_bytearray({1, 2, 'a'})    -- TRUE 
t_bytearray({})            -- FALSE (empty sequence)

8.14.3.12 t_lower

include std/types.e 
public type t_lower(object test_data)

Returns TRUE if argument is a lowercase character or if every element of the argument is an lowercase character.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-lowercase

8.14.3.12.1 Example 1:

t_lower(-1)            -- FALSE 
t_lower(0)             -- FALSE 
t_lower(1)             -- FALSE 
t_lower(1.234)         -- FALSE 
t_lower('A')           -- FALSE 
t_lower('9')           -- FALSE 
t_lower('?')           -- FALSE 
t_lower("abc")         -- TRUE 
t_lower("ab3")         -- FALSE 
t_lower("123")         -- TRUE 
t_lower({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_lower({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_lower({1, 2, 'a'})    -- FALSE (contains a non-digit) 
t_lower({})            -- FALSE (empty sequence)

8.14.3.13 t_print

include std/types.e 
public type t_print(object test_data)

Returns TRUE if argument is a character that has an ASCII glyph or if every element of the argument is a character that has an ASCII glyph.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains characters that do not have an ASCII glyph.

8.14.3.13.1 Example 1:

t_print(-1)            -- FALSE 
t_print(0)             -- FALSE 
t_print(1)             -- FALSE 
t_print(1.234)         -- FALSE 
t_print('A')           -- TRUE 
t_print('9')           -- TRUE 
t_print('?')           -- TRUE 
t_print("abc")         -- TRUE 
t_print("ab3")         -- TRUE 
t_print("123")         -- TRUE 
t_print("123 ")        -- FALSE (contains a space) 
t_print("123\n")       -- FALSE (contains a new-line) 
t_print({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_print({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_print({1, 2, 'a'})    -- FALSE 
t_print({})            -- FALSE (empty sequence)

8.14.3.14 t_display

include std/types.e 
public type t_display(object test_data)

Returns TRUE if argument is a character that can be displayed or if every element of the argument is a character that can be displayed.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains characters that cannot be displayed.

8.14.3.14.1 Example 1:

t_display(-1)            -- FALSE 
t_display(0)             -- FALSE 
t_display(1)             -- FALSE 
t_display(1.234)         -- FALSE 
t_display('A')           -- TRUE 
t_display('9')           -- TRUE 
t_display('?')           -- TRUE 
t_display("abc")         -- TRUE 
t_display("ab3")         -- TRUE 
t_display("123")         -- TRUE 
t_display("123 ")        -- TRUE 
t_display("123\n")       -- TRUE 
t_display({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_display({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_display({1, 2, 'a'})    -- FALSE 
t_display({})            -- FALSE (empty sequence)

8.14.3.15 t_punct

include std/types.e 
public type t_punct(object test_data)

Returns TRUE if argument is an punctuation character or if every element of the argument is an punctuation character.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-punctuation symbols.

8.14.3.15.1 Example 1:

t_punct(-1)            -- FALSE 
t_punct(0)             -- FALSE 
t_punct(1)             -- FALSE 
t_punct(1.234)         -- FALSE 
t_punct('A')           -- FALSE 
t_punct('9')           -- FALSE 
t_punct('?')           -- TRUE 
t_punct("abc")         -- FALSE 
t_punct("(-)")         -- TRUE 
t_punct("123")         -- TRUE 
t_punct({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_punct({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_punct({1, 2, 'a'})    -- FALSE (contains a non-digit) 
t_punct({})            -- FALSE (empty sequence)

8.14.3.16 t_space

include std/types.e 
public type t_space(object test_data)

Returns TRUE if argument is a whitespace character or if every element of the argument is an whitespace character.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-whitespace character.

8.14.3.16.1 Example 1:

t_space(-1)            -- FALSE 
t_space(0)             -- FALSE 
t_space(1)             -- FALSE 
t_space(1.234)         -- FALSE 
t_space('A')           -- FALSE 
t_space('9')           -- FALSE 
t_space('\t')          -- TRUE 
t_space("abc")         -- FALSE 
t_space("123")         -- FALSE 
t_space({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_space({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_space({1, 2, 'a'})    -- FALSE (contains a non-digit) 
t_space({})            -- FALSE (empty sequence)

8.14.3.17 t_upper

include std/types.e 
public type t_upper(object test_data)

Returns TRUE if argument is an uppercase character or if every element of the argument is an uppercase character.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-uppercase characters.

8.14.3.17.1 Example 1:

t_upper(-1)            -- FALSE 
t_upper(0)             -- FALSE 
t_upper(1)             -- FALSE 
t_upper(1.234)         -- FALSE 
t_upper('A')           -- TRUE 
t_upper('9')           -- FALSE 
t_upper('?')           -- FALSE 
t_upper("abc")         -- FALSE 
t_upper("ABC")         -- TRUE 
t_upper("123")         -- FALSE 
t_upper({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_upper({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_upper({1, 2, 'a'})    -- FALSE (contains a non-digit) 
t_upper({})            -- FALSE (empty sequence)

8.14.3.18 t_xdigit

include std/types.e 
public type t_xdigit(object test_data)

Returns TRUE if argument is an hexadecimal digit character or if every element of the argument is an hexadecimal digit character.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-hexadecimal character.

8.14.3.18.1 Example 1:

t_xdigit(-1)            -- FALSE 
t_xdigit(0)             -- FALSE 
t_xdigit(1)             -- FALSE 
t_xdigit(1.234)         -- FALSE 
t_xdigit('A')           -- TRUE 
t_xdigit('9')           -- TRUE 
t_xdigit('?')           -- FALSE 
t_xdigit("abc")         -- TRUE 
t_xdigit("fgh")         -- FALSE 
t_xdigit("123")         -- TRUE 
t_xdigit({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_xdigit({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_xdigit({1, 2, 'a'})    -- FALSE (contains a non-digit) 
t_xdigit({})            -- FALSE (empty sequence)

8.14.3.19 t_vowel

include std/types.e 
public type t_vowel(object test_data)

Returns TRUE if argument is a vowel or if every element of the argument is a vowel character.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-vowels

8.14.3.19.1 Example 1:

t_vowel(-1)            -- FALSE 
t_vowel(0)             -- FALSE 
t_vowel(1)             -- FALSE 
t_vowel(1.234)         -- FALSE 
t_vowel('A')           -- TRUE 
t_vowel('9')           -- FALSE 
t_vowel('?')           -- FALSE 
t_vowel("abc")         -- FALSE 
t_vowel("aiu")         -- TRUE 
t_vowel("123")         -- FALSE 
t_vowel({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_vowel({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_vowel({1, 2, 'a'})    -- FALSE (contains a non-digit) 
t_vowel({})            -- FALSE (empty sequence)

8.14.3.20 t_consonant

include std/types.e 
public type t_consonant(object test_data)

Returns TRUE if argument is a consonant character or if every element of the argument is an consonant character.

Returns FALSE if the argument is an empty sequence, or contains sequences, or contains non-consonant character.

8.14.3.20.1 Example 1:

t_consonant(-1)            -- FALSE 
t_consonant(0)             -- FALSE 
t_consonant(1)             -- FALSE 
t_consonant(1.234)         -- FALSE 
t_consonant('A')           -- FALSE 
t_consonant('9')           -- FALSE 
t_consonant('?')           -- FALSE 
t_consonant("abc")         -- FALSE 
t_consonant("rTfM")        -- TRUE 
t_consonant("123")         -- FALSE 
t_consonant({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_consonant({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_consonant({1, 2, 'a'})    -- FALSE (contains a non-digit) 
t_consonant({})            -- FALSE (empty sequence)

8.14.3.21 integer_array

include std/types.e 
public type integer_array(object x)

8.14.3.21.1 Returns:

TRUE if argument is a sequence that only contains zero or more integers.

8.14.3.21.2 Example 1:

integer_array(-1)            -- FALSE (not a sequence) 
integer_array("abc")         -- TRUE (all single characters) 
integer_array({1, 2, "abc"}) -- FALSE (contains a sequence) 
integer_array({1, 2, 9.7})    -- FALSE (contains a non-integer) 
integer_array({1, 2, 'a'})    -- TRUE 
integer_array({})            -- TRUE

8.14.3.22 t_text

include std/types.e 
public type t_text(object x)

8.14.3.22.1 Returns:

TRUE if argument is a sequence that only contains zero or more characters.

8.14.3.22.2 Comment:

A 'character' is defined as a positive integer or zero. This is a broad definition that may be refined once proper UNICODE support is implemented.

8.14.3.22.3 Example 1:

t_text(-1)            -- FALSE (not a sequence) 
t_text("abc")         -- TRUE (all single characters) 
t_text({1, 2, "abc"}) -- FALSE (contains a sequence) 
t_text({1, 2, 9.7})    -- FALSE (contains a non-integer) 
t_text({1, 2, 'a'})    -- TRUE 
t_text({1, -2, 'a'})   -- FALSE (contains a negative integer) 
t_text({})            -- TRUE

8.14.3.23 number_array

include std/types.e 
public type number_array(object x)

8.14.3.23.1 Returns:

TRUE if argument is a sequence that only contains zero or more numbers.

8.14.3.23.2 Example 1:

number_array(-1)            -- FALSE (not a sequence) 
number_array("abc")         -- TRUE (all single characters) 
number_array({1, 2, "abc"}) -- FALSE (contains a sequence) 
number_array(1, 2, 9.7})    -- TRUE 
number_array(1, 2, 'a'})    -- TRUE 
number_array({})            -- TRUE

8.14.3.24 sequence_array

include std/types.e 
public type sequence_array(object x)

8.14.3.24.1 Returns:

TRUE if argument is a sequence that only contains zero or more sequences.

8.14.3.24.2 Example 1:

sequence_array(-1)            -- FALSE (not a sequence) 
sequence_array("abc")         -- FALSE (all single characters) 
sequence_array({1, 2, "abc"}) -- FALSE (contains some atoms) 
sequence_array({1, 2, 9.7})   -- FALSE 
sequence_array({1, 2, 'a'})   -- FALSE 
sequence_array({"abc", {3.4, 99182.78737}}) -- TRUE 
sequence_array({})            -- TRUE

8.14.3.25 ascii_string

include std/types.e 
public type ascii_string(object x)

8.14.3.25.1 Returns:

TRUE if argument is a sequence that only contains zero or more ASCII characters.

8.14.3.25.2 Comment:

An ASCII 'character' is defined as a integer in the range [0 to 127].

8.14.3.25.3 Example 1:

ascii_string(-1)            -- FALSE (not a sequence) 
ascii_string("abc")         -- TRUE (all single ASCII characters) 
ascii_string({1, 2, "abc"}) -- FALSE (contains a sequence) 
ascii_string({1, 2, 9.7})    -- FALSE (contains a non-integer) 
ascii_string({1, 2, 'a'})    -- TRUE 
ascii_string({1, -2, 'a'})   -- FALSE (contains a negative integer) 
ascii_string({})            -- TRUE

8.14.3.26 string

include std/types.e 
public type string(object x)

8.14.3.26.1 Returns:

TRUE if argument is a sequence that only contains zero or more byte characters.

8.14.3.26.2 Comment:

A byte 'character' is defined as a integer in the range [0 to 255].

8.14.3.26.3 Example 1:

string(-1)            -- FALSE (not a sequence) 
string("abc'6")       -- TRUE (all single byte characters) 
string({1, 2, "abc'6"}) -- FALSE (contains a sequence) 
string({1, 2, 9.7})    -- FALSE (contains a non-integer) 
string({1, 2, 'a'})    -- TRUE 
string({1, -2, 'a'})   -- FALSE (contains a negative integer) 
string({})            -- TRUE

9 Sequence Centric Routines

Data type conversion

---------- Routines

Input Routines

---------- Error Status Constants

---------- Answer Types

---------- Routines

Searching

---------- Equality

---------- Finding

---------- Matching

Sequence Manipulation

---------- Constants

---------- Basic routines

---------- Building sequences

---------- Adding to sequences

---------- Extracting, removing, replacing from/into a sequence

---------- Changing the shape of a sequence

Serialization of EUPHORIA Objects

---------- Routines

Sorting

---------- Constants

---------- Routines

9.1 Data type conversion

---------- Routines

---------------- int_to_bytes

---------------- bytes_to_int

---------------- int_to_bits

---------------- bits_to_int

---------------- atom_to_float64

---------------- atom_to_float32

---------------- float64_to_atom

---------------- float32_to_atom

---------------- hex_text

---------------- set_decimal_mark

---------------- to_number

---------------- to_integer

9.1.1 Routines

9.1.1.1 int_to_bytes

include std/convert.e 
public function int_to_bytes(atom x)

Converts an atom that represents an integer to a sequence of 4 bytes.

9.1.1.1.1 Parameters:

x : an atom, the value to convert.

9.1.1.1.2 Returns:

A sequence, of 4 bytes, lowest significant byte first.

9.1.1.1.3 Comments:

If the atom does not fit into a 32-bit integer, things may still work right:

If there is a fractional part, the first element in the returned value will carry it. If you poke the sequence to RAM, that fraction will be discarded anyway.
If x is simply too big, the first three bytes will still be correct, and the 4th element will be floor(x/power(2,24)). If this is not a byte sized integer, some truncation may occur, but usually no error.

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

9.1.1.1.4 Example 1:

s = int_to_bytes(999) 
-- s is {231, 3, 0, 0}

9.1.1.1.5 Example 2:

s = int_to_bytes(-999) 
-- s is {-231, -4, -1, -1}

9.1.1.1.6 See Also:

bytes_to_int, int_to_bits, atom_to_float64, poke4

9.1.1.2 bytes_to_int

include std/convert.e 
public function bytes_to_int(sequence s)

Converts a sequence of at most 4 bytes into an atom.

9.1.1.2.1 Parameters:

s : the sequence to convert

9.1.1.2.2 Returns:

An atom, the value of the concatenated bytes of s.

9.1.1.2.3 Comments:

This performs the reverse operation from int_to_bytes

An atom is being returned, because the converted value may be bigger than what can fit in an EUPHORIA integer.

9.1.1.2.4 Example 1:

atom int32 
 
int32 = bytes_to_int({37,1,0,0}) 
-- int32 is 37 + 256*1 = 293

9.1.1.2.5 See Also:

bits_to_int, float64_to_atom, int_to_bytes, peek, peek4s, peek4u, poke4

9.1.1.3 int_to_bits

include std/convert.e 
public function int_to_bits(atom x, integer nbits = 32)

Extracts the lower bits from an integer.

9.1.1.3.1 Parameters:

x : the atom to convert
nbits : the number of bits requested. The default is 32.

9.1.1.3.2 Returns:

A sequence, of length nbits, made of 1's and 0's.

9.1.1.3.3 Comments:

x should have no fractional part. If it does, then the first "bit" will be an atom between 0 and 2.

The bits are returned lowest first.

For negative numbers the two's complement bit pattern is returned.

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.

9.1.1.3.4 Example 1:

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

9.1.1.3.5 See Also:

bits_to_int, int_to_bytes, Relational operators, operations on sequences

9.1.1.4 bits_to_int

include std/convert.e 
public function bits_to_int(sequence bits)

Converts a sequence of bits to an atom that has no fractional part.

9.1.1.4.1 Parameters:

bits : the sequence to convert.

9.1.1.4.2 Returns:

A positive atom, whose machine representation was given by bits.

9.1.1.4.3 Comments:

An element in bits can be any atom. If nonzero, it counts for 1, else for 0.

The first elements in bits represent the bits with the least weight in the returned value. Only the 52 last bits will matter, as the PC hardware cannot hold an integer with more digits than this.

If you print s the bits will appear in "reverse" order, but it is convenient to have increasing subscripts access bits of increasing significance.

9.1.1.4.4 Example 1:

a = bits_to_int({1,1,1,0,1}) 
-- a is 23 (binary 10111)

9.1.1.4.5 See Also:

bytes_to_int, int_to_bits, operations on sequences

9.1.1.5 atom_to_float64

include std/convert.e 
public function atom_to_float64(atom a)

Convert an atom to a sequence of 8 bytes in IEEE 64-bit format

9.1.1.5.1 Parameters:

a : the atom to convert:

9.1.1.5.2 Returns:

A sequence, of 8 bytes, which can be poked in memory to represent a.

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

9.1.1.5.4 Example:

fn = open("numbers.dat", "wb") 
puts(fn, atom_to_float64(157.82)) -- write 8 bytes to a file

9.1.1.5.5 See Also:

float64_to_atom, int_to_bytes, atom_to_float32

9.1.1.6 atom_to_float32

include std/convert.e 
public function atom_to_float32(atom a)

Convert an atom to a sequence of 4 bytes in IEEE 32-bit format

9.1.1.6.1 Parameters:

a : the atom to convert:

9.1.1.6.2 Returns:

A sequence, of 4 bytes, which can be poked in memory to represent a.

9.1.1.6.3 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). To avoid this, you can use atom_to_float64().

Integer values will also be converted to 32-bit floating-point format.

On modern computers, computations on 64 bit floats are no slower than on 32 bit floats. Internally, the PC stores them in 80 bit registers anyway. EUPHORIA does not support these so called long doubles. Not all C compilers do.

9.1.1.6.4 Example 1:

fn = open("numbers.dat", "wb") 
puts(fn, atom_to_float32(157.82)) -- write 4 bytes to a file

9.1.1.6.5 See Also:

float32_to_atom, int_to_bytes, atom_to_float64

9.1.1.7 float64_to_atom

include std/convert.e 
public function float64_to_atom(sequence_8 ieee64)

Convert a sequence of 8 bytes in IEEE 64-bit format to an atom

9.1.1.7.1 Parameters:

ieee64 : the sequence to convert:

9.1.1.7.2 Returns:

An atom, the same value as the FPU would see by peeking ieee64 from RAM.

9.1.1.7.3 Comments:

Any 64-bit IEEE floating-point number can be converted to an atom.

9.1.1.7.4 Example 1:

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)

9.1.1.7.5 See Also:

float32_to_atom, bytes_to_int, atom_to_float64

9.1.1.8 float32_to_atom

include std/convert.e 
public function float32_to_atom(sequence_4 ieee32)

Convert a sequence of 4 bytes in IEEE 32-bit format to an atom

9.1.1.8.1 Parameters:

ieee32 : the sequence to convert:

9.1.1.8.2 Returns:

An atom, the same value as the FPU would see by peeking ieee64 from RAM.

9.1.1.8.3 Comments:

Any 32-bit IEEE floating-point number can be converted to an atom.

9.1.1.8.4 Example 1:

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)

9.1.1.8.5 See Also:

float64_to_atom, bytes_to_int, atom_to_float32

9.1.1.9 hex_text

include std/convert.e 
public function hex_text(sequence text)

Convert a text representation of a hexadecimal number to an atom

9.1.1.9.1 Parameters:

text : the text to convert.

9.1.1.9.2 Returns:

An atom, the numeric equivalent to text

9.1.1.9.3 Comments:

The text can optionally begin with '#' which is ignored.
The text can have any number of underscores, all of which are ignored.
The text can have one leading '-', indicating a negative number.
The text can have any number of underscores, all of which are ignored.

9.1.1.9.4 Example 1:

 atom h = hex_text("-#3_4FA.00E_1BD") 
 -- h is now -13562.003444492816925 
 atom h = hex_text("DEADBEEF") 
 -- h is now 3735928559

9.1.1.9.5 See Also:

value

9.1.1.10 set_decimal_mark

include std/convert.e 
public function set_decimal_mark(integer new_mark)

Gets, and possibly sets, the decimal mark that to_number() uses.

9.1.1.10.1 Parameters:

new_mark : An integer: Either a comma (,), a period (.) or any other integer.

9.1.1.10.2 Returns:

An integer, The current value, before new_mark changes it.

9.1.1.10.3 Comments:

When new_mark is a period it will cause to_number() to interpret a dot (.) as the decimal point symbol. The pre-changed value is returned.
When new_mark is a comma it will cause to_number() to interpret a comma (,) as the decimal point symbol. The pre-changed value is returned.
Any other value does not change the current setting. Instead it just returns the current value.
The initial value of the decimal marker is a period.

9.1.1.11 to_number

include std/convert.e 
public function to_number(sequence text_in, integer return_bad_pos = 0)

Converts the text into a number.

9.1.1.11.1 Parameters:

text_in : A string containing the text representation of a number.
return_bad_pos : An integer.

If 0 (the default) then this will return a number based on the supplied text and it will not return any position in text_in that caused an incomplete conversion.
If return_bad_pos is -1 then if the conversion of text_in was complete the resulting number is returned otherwise a single-element sequence containing the position within text_in where the conversion stopped.
If not 0 then this returns both the converted value up to the point of failure (if any) and the position in text_in that caused the failure. If that position is 0 then there was no failure.

9.1.1.11.2 Returns:

an atom, If return_bad_pos is zero, the number represented by text_in. If text_in contains invalid characters, zero is returned.
a sequence, If return_bad_pos is non-zero. If return_bad_pos is -1 it returns a 1-element sequence containing the spot inside text_in where conversion stopped. Otherwise it returns a 2-element sequence containing the number represented by text_in and either 0 or the position in text_in where conversion stopped.

9.1.1.11.3 Comments:

You can supply Hexadecimal values if the value is preceded by a '#' character, Octal values if the value is preceded by a '@' character, and Binary values if the value is preceded by a '!' character. With hexadecimal values, the case of the digits 'A' - 'F' is not important. Also, any decimal marker embedded in the number is used with the correct base.
Any underscore characters or thousands separators, that are embedded in the text number are ignored. These can be used to help visual clarity for long numbers. The thousands separator is a ',' when the decimal mark is '.' (the default), or '.' if the decimal mark is ','. You inspect and set it using set_decimal_mark().
You can supply a single leading or trailing sign. Either a minus (-) or plus (+).
You can supply one or more trailing adjacent percentage signs. The first one causes the resulting value to be divided by 100, and each subsequent one divides the result by a further 10. Thus 3845% gives a value of (3845 / 100) ==> 38.45, and 3845%% gives a value of (3845 / 1000) ==> 3.845.
You can have single currency symbol before the first digit or after the last digit. A currency symbol is any character of the string: "$£¤¥�".
You can have any number of whitespace characters before the first digit and after the last digit.
The currency, sign and base symbols can appear in any order. Thus "$ -21.10" is the same as " -$21.10 ", which is also the same as "21.10$-", etc.
This function can optionally return information about invalid numbers. If return_bad_pos is not zero, a two-element sequence is returned. The first element is the converted number value , and the second is the position in the text where conversion stopped. If no errors were found then the second element is zero.
When converting floating point text numbers to atoms, you need to be aware that many numbers cannot be accurately converted to the exact value expected due to the limitations of the 64-bit IEEEE Floating point format.

9.1.1.11.4 Examples:

    object val 
    val = to_number("12.34", 1)  ---> {12.34, 0} -- No errors. 
    val = to_number("12.34", -1)  ---> 12.34 -- No errors. 
    val = to_number("12.34a", 1) ---> {12.34, 6} -- Error at position 6 
    val = to_number("12.34a", -1) ---> {6} -- Error at position 6 
    val = to_number("12.34a")  ---> 0 because its not a valid number 
    val = to_number("#f80c") --> 63500 
    val = to_number("#f80c.7aa") --> 63500.47900390625 
    val = to_number("@1703") --> 963 
    val = to_number("!101101") --> 45 
    val = to_number("12_583_891") --> 12583891 
    val = to_number("12_583_891%") --> 125838.91 
    val = to_number("12,583,891%%") --> 12583.891

9.1.1.12 to_integer

include std/convert.e 
public function to_integer(object data_in, integer def_value = 0)

Converts an object into a integer.

9.1.1.12.1 Parameters:

data_in : Any EUPHORIA object.
def_value : An integer. This is returned if data_in cannot be converted into an integer. If omitted, zero is returned.

9.1.1.12.2 Returns:

An integer, either the integer rendition of data_in or def_value if it has no integer value.

9.1.1.12.3 Comments:

The returned value is guaranteed to be a valid EUPHORIA integer.

9.1.1.12.4 Examples:

? to_integer(12)       --> 12 
? to_integer(12.4)     --> 12 
? to_integer("12")     --> 12 
? to_integer("12.9")   --> 12 
? to_integer("a12")    --> 0 (not a valid number) 
? to_integer("a12",-1) --> -1 (not a valid number) 
? to_integer({"12"})   --> 0 (sub-sequence found) 
? to_integer(#3FFFFFFF)   --> 1073741823 
? to_integer(#3FFFFFFF + 1)   --> 0 (too big for a EUPHORIA integer)

9.2 Input Routines

---------- Error Status Constants

---------------- GET_SUCCESS

---------------- GET_EOF

---------------- GET_FAIL

---------------- GET_NOTHING

---------- Answer Types

---------------- GET_SHORT_ANSWER

---------------- GET_LONG_ANSWER

---------- Routines

---------------- get

---------------- value

---------------- defaulted_value

9.2.1 Error Status Constants

These are returned from get and value.

9.2.1.1 GET_SUCCESS

include std/get.e 
public constant GET_SUCCESS

9.2.1.2 GET_EOF

include std/get.e 
public constant GET_EOF

9.2.1.3 GET_FAIL

include std/get.e 
public constant GET_FAIL

9.2.1.4 GET_NOTHING

include std/get.e 
public constant GET_NOTHING

9.2.2 Answer Types

9.2.2.1 GET_SHORT_ANSWER

include std/get.e 
public constant GET_SHORT_ANSWER

9.2.2.2 GET_LONG_ANSWER

include std/get.e 
public constant GET_LONG_ANSWER

9.2.3 Routines

9.2.3.1 get

include std/get.e 
public function get(integer file, integer offset = 0, integer answer = GET_SHORT_ANSWER)

Input, from an open file, a human-readable string of characters representing a EUPHORIA object. Convert the string into the numeric value of that object.

9.2.3.1.1 Parameters:

file : an integer, the handle to an open file from which to read
offset : an integer, an offset to apply to file position before reading. Defaults to 0.
answer : an integer, either GET_SHORT_ANSWER (the default) or GET_LONG_ANSWER.

9.2.3.1.2 Returns:

A sequence, of length 2 (GET_SHORT_ANSWER) or 4 (GET_LONG_ANSWER), made of

an integer, the return status. This is any of:

GET_SUCCESS -- object was read successfully
GET_EOF -- end of file before object was read completely
GET_FAIL -- object is not syntactically correct
GET_NOTHING -- nothing was read, even a partial object string, before end of input

an object, the value that was read. This is valid only if return status is GET_SUCCESS.
an integer, the number of characters read. On an error, this is the point at which the error was detected.
an integer, the amount of initial whitespace read before the first active character was found

9.2.3.1.3 Comments:

When answer is not specified, or explicitly GET_SHORT_ANSWER, only the first two elements in the returned sequence are actually returned.

The GET_NOTHING return status will not be returned if answer is GET_SHORT_ANSWER.

get() can read arbitrarily complicated EUPHORIA objects. You could have a long sequence of values in braces and separated by commas and comments, e.g. {23, {49, 57}, 0.5, -1, 99, 'A', "john"} . A single call to get() will read in this entire sequence and return its value as a result, as well as complementary information.

If a nonzero offset is supplied, it is interpreted as an offset to the current file position, and the file will be seek()ed there first.

get() returns a 2 or 4 element sequence, like value() does:

a status code (success/error/end of file/no value at all)
the value just read (meaningful only when the status code is GET_SUCCESS) (optionally)
the total number of characters read
the amount of initial whitespace read.

Using the default value for answer, or setting it to GET_SHORT_ANSWER, returns 2 elements. Setting it to GET_LONG_ANSWER causes 4 elements to be returned.

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

-- something\nBut no value

and the input stream stops right there, you'll receive a status code of GET_NOTHING, because nothing but whitespace or comments was read. If you had opted for a short answer, you'd get GET_EOF instead.

Multiple "top-level" objects in the input stream must be separated from each other with one or more "whitespace" characters (blank, tab, \r or \n). At the very least, a top level number must be followed by a white space from the following object. Whitespace is not necessary within a top-level object. Comments, terminated by either '\n' or '\r', are allowed anywhere inside sequences, and ignored if at the top level. A call to get() will read one entire top-level object, plus possibly one additional (whitespace) character, after a top level number, even though the next object may have an identifiable starting point.

The combination of print() and get() can be used to save a EUPHORIA object to disk and later read it back. This technique could be used to implement a database as one or more large EUPHORIA sequences stored in disk files. The sequences could be read into memory, updated and then written back to disk after each series of transactions is complete. Remember to write out a whitespace character (using puts()) after each call to print(), at least when a top level number was just printed.

The value returned is not meaningful unless you have a GET_SUCCESS status.

9.2.3.1.4 Example 1:

-- If he types 77.5, get(0) would return: 
{GET_SUCCESS, 77.5} 
 
-- whereas gets(0) would return: 
"77.5\n"

9.2.3.1.5 Example 2:

See bin\mydata.ex

9.2.3.1.6 See Also:

value

9.2.3.2 value

include std/get.e 
public function value(sequence st, integer start_point = 1, integer answer = GET_SHORT_ANSWER)

Read, from a string, a human-readable string of characters representing a EUPHORIA object. Convert the string into the numeric value of that object.

9.2.3.2.1 Parameters:

st : a sequence, from which to read text
offset : an integer, the position at which to start reading. Defaults to 1.
answer : an integer, either GET_SHORT_ANSWER (the default) or GET_LONG_ANSWER.

9.2.3.2.2 Returns:

A sequence, of length 2 (GET_SHORT_ANSWER) or 4 (GET_LONG_ANSWER), made of

an integer, the return status. This is any of

GET_SUCCESS -- object was read successfully
GET_EOF -- end of file before object was read completely
GET_FAIL -- object is not syntactically correct
GET_NOTHING -- nothing was read, even a partial object string, before end of input

an object, the value that was read. This is valid only if return status is GET_SUCCESS.
an integer, the number of characters read. On an error, this is the point at which the error was detected.
an integer, the amount of initial whitespace read before the first active character was found

9.2.3.2.3 Comments:

When answer is not specified, or explicitly GET_SHORT_ANSWER, only the first two elements in the returned sequence are actually returned.

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

After reading one valid representation of a EUPHORIA object, value() will stop reading and ignore any additional characters in the string. For example, "36" and "36P" will both give you {GET_SUCCESS, 36}.

The function returns {return_status, value} if the answer type is not passed or set to GET_SHORT_ANSWER. If set to GET_LONG_ANSWER, the number of characters read and the amount of leading whitespace are returned in 3rd and 4th position. The GET_NOTHING return status can occur only on a long answer.

9.2.3.2.4 Example 1:

s = value("12345"} 
s is {GET_SUCCESS, 12345}

9.2.3.2.5 Example 2:

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

9.2.3.2.6 Example 3:

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

9.2.3.2.7 See Also:

get

9.2.3.3 defaulted_value

include std/get.e 
public function defaulted_value(object st, object def, integer start_point = 1)

Perform a value() operation on a sequence, returning the value on success or the default on failure.

9.2.3.3.1 Parameters:

st : object to retrieve value from.
def : the value returned if st is an atom or value(st) fails.
start_point : an integer, the position in st at which to start getting the value from. Defaults to 1

9.2.3.3.2 Returns:

If st, is an atom then def is returned.
If value(st), call is a success, then value()[2], otherwise it will return the parameter #def#.

9.2.3.3.3 Examples:

object i = defaulted_value("10", 0) 
-- i is 10 
 
i = defaulted_value("abc", 39) 
-- i is 39 
 
i = defaulted_value(12, 42) 
-- i is 42 
 
i = defaulted_value("{1,2}", 42) 
-- i is {1,2}

9.2.3.3.4 See Also:

value

9.3 Searching

Page Contents

---------- Equality

---------------- compare

---------------- equal

---------- Finding

---------------- find

---------------- find_from

---------------- find_any

---------------- find_all

---------------- NESTED_ANY

---------------- NESTED_ALL

---------------- NESTED_INDEX

---------------- NESTED_BACKWARD

---------------- find_nested

---------------- rfind

---------------- find_replace

---------------- match_replace

---------------- binary_search

---------- Matching

---------------- match

---------------- match_from

---------------- match_all

---------------- rmatch

---------------- begins

---------------- ends

---------------- is_in_range

---------------- is_in_list

---------------- lookup

---------------- vlookup

9.3.1 Equality

9.3.1.1 compare

<built-in> function compare(object compared, object reference)

Compare two items returning less than, equal or greater than.

9.3.1.1.1 Parameters:

compared : the compared object
reference : the reference object

9.3.1.1.2 Returns:

An integer,

0 -- if objects are identical
1 -- if compared is greater than reference
-1 -- if compared is less than reference

9.3.1.1.3 Comments:

Atoms are considered to be less than sequences. Sequences are compared alphabetically starting with the first element until a difference is found or one of the sequences is exhausted. Atoms are compared as ordinary reals.

9.3.1.1.4 Example 1:

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

9.3.1.1.5 Example 2:

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

9.3.1.1.6 Example 3:

x = compare('a', "a") 
-- x will be -1 because 'a' is an atom 
-- while "a" is a sequence

9.3.1.1.7 See Also:

equal, relational operators, operations on sequences, sort

9.3.1.2 equal

<built-in> function equal(object left, object right)

Compare two EUPHORIA objects to see if they are the same.

9.3.1.2.1 Parameters:

left : one of the objects to test
right : the other object

9.3.1.2.2 Returns:

An integer, 1 if the two objects are identical, else 0.

9.3.1.2.3 Comments:

This is equivalent to the expression: compare(left, right) = 0 .

This routine, like most other built-in routines, is very fast. It does not have any subroutine call overhead.

9.3.1.2.4 Example 1:

if equal(PI, 3.14) then 
    puts(1, "give me a better value for PI!\n") 
end if

9.3.1.2.5 Example 2:

if equal(name, "George") or equal(name, "GEORGE") then 
   puts(1, "name is George\n") 
end if

9.3.1.2.6 See Also:

compare

9.3.2 Finding

9.3.2.1 find

<built-in> function find(object needle, sequence haystack, integer start)

Find the first occurrence of a "needle" as an element of a "haystack", starting from position "start"..

9.3.2.1.1 Parameters:

needle : an object whose presence is being queried
haystack : a sequence, which is being looked up for needle
start : an integer, the position at which to start searching. Defaults to 1.

9.3.2.1.2 Returns:

An integer, 0 if needle is not on haystack, else the smallest index of an element of haystack that equals needle.

9.3.2.1.3 Comments:

find() and find_from() are identical, but you can omit giving find() a starting point.

9.3.2.1.4 Example 1:

location = find(11, {5, 8, 11, 2, 3}) 
-- location is set to 3

9.3.2.1.5 Example 2:

names = {"fred", "rob", "george", "mary", ""} 
location = find("mary", names) 
-- location is set to 4

9.3.2.1.6 See Also:

find_from, match, match_from, compare

9.3.2.2 find_from

<built-in> function find_from(object needle, object haystack, integer start)

Find the first occurrence of a "needle" as an element of a "haystack". Search starts at a specified index.

9.3.2.2.1 Parameters:

needle : an object whose presence is being queried
haystack : a sequence, which is being looked up for needle
start : an integer, the index in haystack at which to start searching.

9.3.2.2.2 Returns:

An integer, 0 if needle is not on haystack past position start, else the smallest index, not less than start, of an element of haystack that equals needle.

9.3.2.2.3 Comments:

start may have any value from 1 to the length of haystack plus 1. (Analogous to the first index of a slice of haystack).

find() and find_from() are identical, but you can omit giving find() a starting point.

9.3.2.2.4 Example 1:

location = find_from(11, {11, 8, 11, 2, 3}, 2) 
-- location is set to 3

9.3.2.2.5 Example 2:

names = {"mary", "rob", "george", "mary", ""} 
location = find_from("mary", names, 3) 
-- location is set to 4

9.3.2.2.6 See Also:

find, match, match_from, compare

9.3.2.3 find_any

include std/search.e 
public function find_any(sequence needles, sequence haystack, integer start = 1)

Find any element from a list inside a sequence. Returns the location of the first hit.

9.3.2.3.1 Parameters:

needles : a sequence, the list of items to look for
haystack : a sequence, in which "needles" are looked for
start : an integer, the starting point of the search. Defaults to 1.

9.3.2.3.2 Returns:

An integer, the smallest index in haystack of an element of needles, or 0 if no needle is found.

9.3.2.3.3 Comments:

This function may be applied to a string sequence or a complex sequence.

9.3.2.3.4 Example 1:

location = find_any("aeiou", "John Smith", 3) 
-- location is 8

9.3.2.3.5 Example 2:

location = find_any("aeiou", "John Doe") 
-- location is 2

9.3.2.3.6 See Also:

find, find_from

9.3.2.4 find_all

include std/search.e 
public function find_all(object needle, sequence haystack, integer start = 1)

Find all occurrences of an object inside a sequence, starting at some specified point.

9.3.2.4.1 Parameters:

needle : an object, what to look for
haystack : a sequence to search in
start : an integer, the starting index position (defaults to 1)

9.3.2.4.2 Returns:

A sequence, the list of all indexes no less than start of elements of haystack that equal needle. This sequence is empty if no match found.

9.3.2.4.3 Example 1:

s = find_all('A', "ABCABAB") 
-- s is {1,4,6}

9.3.2.4.4 See Also:

find, match, match_all

9.3.2.5 NESTED_ANY

include std/search.e 
public constant NESTED_ANY

9.3.2.6 NESTED_ALL

include std/search.e 
public constant NESTED_ALL

9.3.2.7 NESTED_INDEX

include std/search.e 
public constant NESTED_INDEX

9.3.2.8 NESTED_BACKWARD

include std/search.e 
public constant NESTED_BACKWARD

9.3.2.9 find_nested

include std/search.e 
public function find_nested(object needle, sequence haystack, integer flags = 0, integer rtn_id = - 1)

Find any object (among a list) in a sequence of arbitrary shape at arbitrary nesting.

9.3.2.9.1 Parameters:

needle : an object, either what to look up, or a list of items to look up
haystack : a sequence, where to look up
flags : options to the function, see Comments section. Defaults to 0.
routine : an integer, the routine_id of an user supplied equal function. Defaults to -1.

9.3.2.9.2 Returns:

A possibly empty sequence, of results, one for each hit.

9.3.2.9.3 Comments:

Each item in the returned sequence is either a sequence of indexes, or a pair {sequence of indexes, index in needle}.

9.3.2.9.4 The following flags are available to fine tune the search:

NESTED_BACKWARD -- if on flags, search is performed backward. Default is forward.
NESTED_ALL -- if on flags, all occurrences are looked for. Default is one hit only.
NESTED_ANY -- if present on flags, needle is a list of items to look for. Not the default.
NESTED_INDEXES -- if present on flags, an individual result is a pair {position, index in needle}. Default is just return the position.

If s is a single index list, or position, from the returned sequence, then fetch(haystack, s) = needle.

If a routine id is supplied, the routine must behave like equal() if the NESTED_ANY flag is not supplied, and like find() if it is. The routine is being passed the current haystack item and needle. The returned integer is interpreted as if returned by equal() or find().

If the NESTED_ANY flag is specified, and needle is an atom, then the flag is removed.

9.3.2.9.5 Example 1:

sequence s = find_nested(3, {5, {4, {3, {2}}}}) 
-- s is {2 ,2 ,1}

9.3.2.9.6 Example 2:

sequence s = find_nested({3, 2}, {1, 3, {2,3}}, NESTED_ANY + NESTED_BACKWARD + NESTED_ALL) 
-- s is {{3,2}, {3,1}, {2}}

9.3.2.9.7 Example 3:

sequence s = find_nested({3, 2}, {1, 3, {2,3}}, NESTED_ANY + NESTED_INDEXES + NESTED_ALL) 
-- s is {{{2}, 1}, {{3, 1}, 2}, {{3, 2}, 1}}

9.3.2.9.8 See Also:

find, rfind, find_any, fetch

9.3.2.10 rfind

include std/search.e 
public function rfind(object needle, sequence haystack, integer start = length(haystack))

Find a needle in a haystack in reverse order.

9.3.2.10.1 Parameters:

needle : an object to search for
haystack : a sequence to search in
start : an integer, the starting index position (defaults to length(haystack))

9.3.2.10.2 Returns:

An integer, 0 if no instance of needle can be found on haystack before index start, or the highest such index otherwise.

9.3.2.10.3 Comments:

If start is less than 1, it will be added once to length(haystack) to designate a position counted backwards. Thus, if start is -1, the first element to be queried in haystack will be haystack[$-1], then haystack[$-2] and so on.

9.3.2.10.4 Example 1:

location = rfind(11, {5, 8, 11, 2, 11, 3}) 
-- location is set to 5

9.3.2.10.5 Example 2:

names = {"fred", "rob", "rob", "george", "mary"} 
location = rfind("rob", names) 
-- location is set to 3 
location = rfind("rob", names, -4) 
-- location is set to 2

9.3.2.10.6 See Also:

find, rmatch

9.3.2.11 find_replace

include std/search.e 
public function find_replace(object needle, sequence haystack, object replacement, integer max = 0)

Finds a "needle" in a "haystack", and replace any, or only the first few, occurrences with a replacement.

9.3.2.11.1 Parameters:

needle : an object to search and perhaps replace
haystack : a sequence to be inspected
replacement : an object to substitute for any (first) instance of needle
max : an integer, 0 to replace all occurrences

9.3.2.11.2 Returns:

A sequence, the modified haystack.

9.3.2.11.3 Comments:

Replacements will not be made recursively on the part of haystack that was already changed.

If max is 0 or less, any occurrence of needle in haystack will be replaced by replacement. Otherwise, only the first max occurrences are.

9.3.2.11.4 Example 1:

s = find_replace('b', "The batty book was all but in Canada.", 'c', 0) 
-- s is "The catty cook was all cut in Canada."

9.3.2.11.5 Example 2:

s = find_replace('/', "/euphoria/demo/unix", '\\', 2) 
-- s is "\\euphoria\\demo/unix"

9.3.2.11.6 Example 3:

s = find_replace("theater", { "the", "theater", "theif" }, "theatre") 
-- s is { "the", "theatre", "theif" }

9.3.2.11.7 See Also:

find, replace, match_replace

9.3.2.12 match_replace

include std/search.e 
public function match_replace(object needle, sequence haystack, object replacement, integer max = 0)

Finds a "needle" in a "haystack", and replace any, or only the first few, occurrences with a replacement.

9.3.2.12.1 Parameters:

needle : an object to search and perhaps replace
haystack : a sequence to be inspected
replacement : an object to substitute for any (first) instance of needle
max : an integer, 0 to replace all occurrences

9.3.2.12.2 Returns:

A sequence, the modified haystack.

9.3.2.12.3 Comments:

Replacements will not be made recursively on the part of haystack that was already changed.

If max is 0 or less, any occurrence of needle in haystack will be replaced by replacement. Otherwise, only the first max occurrences are.

If either needle or replacement are atoms they will be treated as if you had passed in a length-1 sequence containing the said atom.

9.3.2.12.4 Example 1:

s = match_replace("the", "the cat ate the food under the table", "THE", 0) 
-- s is "THE cat ate THE food under THE table"

9.3.2.12.5 Example 2:

s = match_replace("the", "the cat ate the food under the table", "THE", 2) 
-- s is "THE cat ate THE food under the table"

9.3.2.12.6 Example 3:

s = match_replace('/', "/euphoria/demo/unix", '\\', 2) 
-- s is "\\euphoria\\demo/unix"

9.3.2.12.7 See Also:

find, replace, find_replace

9.3.2.13 binary_search

include std/search.e 
public function binary_search(object needle, sequence haystack, integer start_point = 1, integer end_point = 0)

Finds a "needle" in an ordered "haystack". Start and end point can be given for the search.

9.3.2.13.1 Parameters:

needle : an object to look for
haystack : a sequence to search in
start_point : an integer, the index at which to start searching. Defaults to 1.
end_point : an integer, the end point of the search. Defaults to 0, ie search to end.

9.3.2.13.2 Returns:

An integer, either:

a positive integer i, which means haystack[i] equals needle.
a negative integer, -i, with i between adjusted start and end points. This means that needle is not in the searched slice of haystack, but would be at index i if it were there.
a negative integer -i with i out of the searched range. This means than needlemight be either below the start point if i is below the start point, or above the end point if i is.

9.3.2.13.3 Comments:

If end_point is not greater than zero, it is added to length(haystack) once only. Then, the end point of the search is adjusted to length(haystack) if out of bounds.
The start point is adjusted to 1 if below 1.
The way this function returns is very similar to what db_find_key does. They use variants of the same algorithm. The latter is all the more efficient as haystack is long.
haystack is assumed to be in ascending order. Results are undefined if it is not.
If duplicate copies of needle exist in the range searched on haystack, any of the possible contiguous indexes may be returned.

9.3.2.13.4 See Also:

find, db_find_key

9.3.3 Matching

9.3.3.1 match

<built-in> function match(sequence needle, sequence haystack, integer start)

Try to match a "needle" against some slice of a "haystack", starting at position "start".

9.3.3.1.1 Parameters:

needle : a sequence whose presence as a "substring" is being queried
haystack : a sequence, which is being looked up for needle as a sub-sequence
start : an integer, the point from which matching is attempted. Defaults to 1.

9.3.3.1.2 Returns:

An integer, 0 if no slice of haystack is needle, else the smallest index at which such a slice starts.

9.3.3.1.3 Comments:

match() and match_from() are identical, but you can omit giving match() a starting point.

9.3.3.1.4 Example 1:

location = match("pho", "EUPHORIA") 
-- location is set to 3

9.3.3.1.5 See Also:

find, find_from, compare, match_from, wildcard_match

9.3.3.2 match_from

<built-in> function match_from(sequence needle, sequence haystack, integer start)

Try to match a "needle" against some slice of a "haystack", starting from some index.

9.3.3.2.1 Parameters:

needle : an sequence whose presence as a sub-sequence is being queried
haystack : a sequence, which is being looked up for needle as a sub-sequence
start : an integer, the index in haystack at which to start searching.

9.3.3.2.2 Returns:

An integer, 0 if no slice of haystack with lower index at least start is needle, else the smallest such index.

9.3.3.2.3 Comments:

start may have any value from 1 to the length of haystack plus 1. (Just like the first index of a slice of haystack.)

match() and match_from() are identical, but you can omit giving match() a starting point.

9.3.3.2.4 Example 1:

location = match_from("pho", "phoEUPHORIA", 4) 
-- location is set to 6

9.3.3.2.5 See Also:

find, find_from, match, compare, wildcard_match, regex:find

9.3.3.3 match_all

include std/search.e 
public function match_all(sequence needle, sequence haystack, integer start = 1)

Match all items of haystack in needle.

9.3.3.3.1 Parameters:

needle : a sequence, what to look for
haystack : a sequence to search in
start : an integer, the starting index position (defaults to 1)

9.3.3.3.2 Returns:

A sequence, of integers, the list of all lower indexes, not less than start, of all slices in haystack that equal needle. The list may be empty.

9.3.3.3.3 Example 1:

s = match_all("the", "the dog chased the cat under the table.") 
-- s is {1,16,30}

9.3.3.3.4 See Also:

match, find, find_all

9.3.3.4 rmatch

include std/search.e 
public function rmatch(sequence needle, sequence haystack, integer start = length(haystack))

Try to match a needle against some slice of a haystack in reverse order.

9.3.3.4.1 Parameters:

needle : a sequence to search for
haystack : a sequence to search in
start : an integer, the starting index position (defaults to length(haystack))

9.3.3.4.2 Returns:

An integer, either 0 if no slice of haystack starting before start equals needle, else the highest lower index of such a slice.

9.3.3.4.3 Comments:

9.3.3.4.4 Example 1:

location = rmatch("the", "the dog ate the steak from the table.") 
-- location is set to 28 (3rd 'the') 
location = rmatch("the", "the dog ate the steak from the table.", -11) 
-- location is set to 13 (2nd 'the')

9.3.3.4.5 See Also:

rfind, match

9.3.3.5 begins

include std/search.e 
public function begins(object sub_text, sequence full_text)

Test whether a sequence is the head of another one.

9.3.3.5.1 Parameters:

sub_text : an object to be looked for
full_text : a sequence, the head of which is being inspected.

9.3.3.5.2 Returns:

An integer, 1 if sub_text begins full_text, else 0.

9.3.3.5.3 Example 1:

s = begins("abc", "abcdef") 
-- s is 1 
s = begins("bcd", "abcdef") 
-- s is 0

9.3.3.5.4 See Also:

ends, head

9.3.3.6 ends

include std/search.e 
public function ends(object sub_text, sequence full_text)

Test whether a sequence ends another one.

9.3.3.6.1 Parameters:

sub_text : an object to be looked for
full_text : a sequence, the tail of which is being inspected.

9.3.3.6.2 Returns:

An integer, 1 if sub_text ends full_text, else 0.

9.3.3.6.3 Example 1:

s = ends("def", "abcdef") 
-- s is 1 
s = begins("bcd", "abcdef") 
-- s is 0

9.3.3.6.4 See Also:

begins, tail

9.3.3.7 is_in_range

include std/search.e 
public function is_in_range(object item, sequence range_limits, sequence boundries = "[]")

Tests to see if the item is in a range of values supplied by range_limits

9.3.3.7.1 Parameters:

item : The object to test for.
range_limits : A sequence of two or more elements. The first is assumed to be the smallest value and the last is assumed to be the highest value.
boundries: a sequence. This determines if the range limits are inclusive or not. Must be one of "[]" (the default), "[)", "(]", or "()".

9.3.3.7.2 Returns:

An integer, 0 if item is not in the range_limits otherwise it returns 1.

9.3.3.7.3 Comments:

In boundries#, square brackets mean inclusive and round brackets mean exclusive. Thus "[]" includes both limits in the range, while "()" excludes both limits. And, "[)" includes the lower limit and excludes the upper limits while "(]" does the reverse.

9.3.3.7.4 Example 1:

if is_in_range(2, {2, 75}) then 
    procA(user_data) -- Gets run (both limits included) 
end if 
if is_in_range(2, {2, 75}, "(]") then 
    procA(user_data) -- Does not get run 
end if

9.3.3.8 is_in_list

include std/search.e 
public function is_in_list(object item, sequence list)

Tests to see if the item is in a list of values supplied by list

9.3.3.8.1 Parameters:

item : The object to test for.
list : A sequence of elements that item could be a member of.

9.3.3.8.2 Returns:

An integer, 0 if item is not in the list, otherwise it returns 1.

9.3.3.8.3 Example 1:

if is_in_list(user_data, {100, 45, 2, 75, 121}) then 
    procA(user_data) 
end if

9.3.3.9 lookup

include std/search.e 
public function lookup(object find_item, sequence source_list, sequence target_list, object def_value = 0)

If the supplied item is in the source list, this returns the corresponding element from the target list.

9.3.3.9.1 Parameters:

find_item: an object that might exist in source_list .
source_list: a sequence that might contain pITem.
target_list: a sequence from which the corresponding item will be returned.
def_value: an object (defaults to zero). This is returned when find_item is not in source_list and target_list is not longer than source_list.

9.3.3.9.2 Returns:

an object

If find_item is found in source_list then this is the corresponding element from target_list
If find_item is not in source_list then if target_list is longer than source_list then the last item in target_list is returned otherwise def_value is returned.

9.3.3.9.3 Examples:

lookup('a', "cat", "dog") --> 'o' 
lookup('d', "cat", "dogx") --> 'x' 
lookup('d', "cat", "dog") --> 0 
lookup('d', "cat", "dog", -1) --> -1 
lookup("ant", {"ant","bear","cat"}, {"spider","seal","dog","unknown"}) --> "spider" 
lookup("dog", {"ant","bear","cat"}, {"spider","seal","dog","unknown"}) --> "unknown"

9.3.3.10 vlookup

include std/search.e 
public function vlookup(object find_item, sequence grid_data, integer source_col, integer target_col, object def_value = 0)

If the supplied item is in a source grid column, this returns the corresponding element from the target column.

9.3.3.10.1 Parameters:

find_item: an object that might exist in source_col .
grid_data: a 2D grid sequence that might contain pITem .
source_col: an integer. The column number to look for find_item.
target_col: an integer. The column number from which the corresponding item will be returned.
def_value: an object (defaults to zero). This is returned when find_item is not found in the source_col column, or if found but the target column does not exist.

9.3.3.10.2 Comments:

If a row in the grid is actually a single atom, the row is ignored.
If a row's length is less than the source_col, the row is ignored.

9.3.3.10.3 Returns:

an object

If find_item is found in the source_col column then this is the corresponding element from the target_col column.

9.3.3.10.4 Examples:

sequence grid 
grid = { 
       {"ant", "spider", "mortein"}, 
       {"bear", "seal", "gun"}, 
       {"cat", "dog", "ranger"}, 
       $ 
 } 
vlookup("ant", grid, 1, 2, "?") --> "spider" 
vlookup("ant", grid, 1, 3, "?") --> "mortein" 
vlookup("seal", grid, 2, 3, "?") --> "gun" 
vlookup("seal", grid, 2, 1, "?") --> "bear" 
vlookup("mouse", grid, 2, 3, "?") --> "?"

9.4 Sequence Manipulation

---------- Constants

---------------- ADD_PREPEND

---------------- ADD_APPEND

---------------- ADD_SORT_UP

---------------- ADD_SORT_DOWN

---------------- ROTATE_LEFT

---------------- ROTATE_RIGHT

---------- Basic routines

---------------- can_add

---------------- fetch

---------------- store

---------------- valid_index

---------------- rotate

---------------- columnize

---------------- apply

---------------- mapping

---------------- length

---------------- reverse

---------------- shuffle

---------- Building sequences

---------------- linear

---------------- repeat_pattern

---------------- repeat

---------- Adding to sequences

---------------- append

---------------- prepend

---------------- insert

---------------- splice

---------------- pad_head

---------------- pad_tail

---------------- add_item

---------------- remove_item

---------- Extracting, removing, replacing from/into a sequence

---------------- head

---------------- tail

---------------- mid

---------------- slice

---------------- vslice

---------------- remove

---------------- patch

---------------- remove_all

---------------- retain_all

---------------- filter

---------------- STDFLTR_ALPHA

---------------- replace

---------------- replace_all

---------------- extract

---------------- project

---------- Changing the shape of a sequence

---------------- split

---------------- split_any

---------------- join

---------------- BK_LEN

---------------- BK_PIECES

---------------- breakup

---------------- flatten

---------------- pivot

---------------- build_list

---------------- transform

---------------- sim_index

---------------- SEQ_NOALT

---------------- remove_subseq

---------------- RD_INPLACE

---------------- remove_dups

---------------- COMBINE_UNSORTED

---------------- COMBINE_SORTED

---------------- combine

---------------- minsize

9.4.1 Constants

9.4.1.1 ADD_PREPEND

include std/sequence.e 
public enum ADD_PREPEND

9.4.1.2 ADD_APPEND

include std/sequence.e 
public enum ADD_APPEND

9.4.1.3 ADD_SORT_UP

include std/sequence.e 
public enum ADD_SORT_UP

9.4.1.4 ADD_SORT_DOWN

include std/sequence.e 
public enum ADD_SORT_DOWN

9.4.1.5 ROTATE_LEFT

include std/sequence.e 
public constant ROTATE_LEFT

9.4.1.6 ROTATE_RIGHT

include std/sequence.e 
public constant ROTATE_RIGHT

9.4.2 Basic routines

9.4.2.1 can_add

include std/sequence.e 
public function can_add(object a, object b)

Checks whether two objects can be legally added together.

9.4.2.1.1 Parameters:

a : one of the objects to test for compatible shape
b : the other object

9.4.2.1.2 Returns:

An integer, 1 if an addition (or any of the Relational operators) are possible between a and b , else 0.

9.4.2.1.3 Example 1:

i = can_add({1,2,3},{4,5}) 
-- i is 0 
 
i = can_add({1,2,3},4) 
-- i is 1 
 
i = can_add({1,2,3},{4,{5,6},7}) 
-- i is 1

9.4.2.1.4 See Also:

linear

9.4.2.2 fetch

include std/sequence.e 
public function fetch(sequence source, sequence indexes)

Retrieves an element nested arbitrarily deep into a sequence.

9.4.2.2.1 Parameters:

source : the sequence from which to fetch
indexes : a sequence of integers, the path to follow to reach the element to return.

9.4.2.2.2 Returns:

An object, which is source[indexes[1]][indexes[2]]...[indexes[$]]

9.4.2.2.3 Errors:

If the path cannot be followed to its end, an error about reading a nonexistent element, or subscripting an atom, will occur.

9.4.2.2.4 Comments:

The last element of indexes may be a pair {lower,upper}, in which case a slice of the innermost referenced sequence is returned.

9.4.2.2.5 Example 1:

x = fetch({0,1,2,3,{"abc","def","ghi"},6},{5,2,3}) 
-- x is 'f', or 102.

9.4.2.2.6 See Also:

store, Subscripting of Sequences

9.4.2.3 store

include std/sequence.e 
public function store(sequence target, sequence indexes, object x)

Stores something at a location nested arbitrarily deep into a sequence.

9.4.2.3.1 Parameters:

target : the sequence in which to store something
indexes : a sequence of integers, the path to follow to reach the place where to store
x : the object to store.

9.4.2.3.2 Returns:

A sequence, a copy of target with the specified place indexes modified by storing x into it.

9.4.2.3.3 Errors:

If the path to storage location cannot be followed to its end, or an index is not what one would expect or is not valid, an error about illegal sequence operations will occur.

9.4.2.3.4 Comments:

If the last element of indexes is a pair of integers, x will be stored as a slice three, the bounding indexes being given in the pair as {lower,upper}..

In EUPHORIA, you can never modify an object by passing it to a routine. You have to get a modified copy and then assign it back to the original.

9.4.2.3.5 Example 1:

s = store({0,1,2,3,{"abc","def","ghi"},6},{5,2,3},108) 
-- s is {0,1,2,3,{"abc","del","ghi"},6}

9.4.2.3.6 See Also:

fetch, Subscripting of Sequences

9.4.2.4 valid_index

include std/sequence.e 
public function valid_index(sequence st, object x)

Checks whether an index exists on a sequence.

9.4.2.4.1 Parameters:

s : the sequence for which to check
x : an object, the index to check.

9.4.2.4.2 Returns:

An integer, 1 if s[x] makes sense, else 0.

9.4.2.4.3 Example 1:

i = valid_index({51,27,33,14},2) 
-- i is 1

9.4.2.4.4 See Also:

Subscripting of Sequences

9.4.2.5 rotate

include std/sequence.e 
public function rotate(sequence source, integer shift, integer start = 1, integer stop = length(source))

Rotates a slice of a sequence.

9.4.2.5.1 Parameters:

source : sequence to be rotated
shift : direction and count to be shifted (ROTATE_LEFT or ROTATE_RIGHT)
start : starting position for shift, defaults o 1
stop : stopping position for shift, defaults to length(source)

9.4.2.5.2 Comments:

Use amount * direction to specify the shift. direction is either ROTATE_LEFT or ROTATE_RIGHT. This enables to shift multiple places in a single call. For instance, use ROTATE_LEFT * 5 to rotate left, 5 positions.

A null shift does nothing and returns source unchanged.

9.4.2.5.3 Example 1:

s = rotate({1, 2, 3, 4, 5}, ROTATE_LEFT) 
-- s is {2, 3, 4, 5, 1}

9.4.2.5.4 Example 2:

s = rotate({1, 2, 3, 4, 5}, ROTATE_RIGHT * 2) 
-- s is {4, 5, 1, 2, 3}

9.4.2.5.5 Example 3:

s = rotate({11,13,15,17,19,23}, ROTATE_LEFT, 2, 5) 
-- s is {11,15,17,19,13,23}

9.4.2.5.6 Example 4:

s = rotate({11,13,15,17,19,23}, ROTATE_RIGHT, 2, 5) 
-- s is {11,19,13,15,17,23}

9.4.2.5.7 See Also:

slice, head, tail

9.4.2.6 columnize

include std/sequence.e 
public function columnize(sequence source, object cols = {}, object defval = 0)

Converts a set of sub sequences into a set of 'columns'.

9.4.2.6.1 Parameters:

source : sequence containing the sub-sequences
cols : either a specific column number or a set of column numbers. Default is 0, which returns the maximum number of columns.
defval : an object. Used when a column value is not available. Default is 0

9.4.2.6.2 Comments:

Any atoms found in source are treated as if they are a 1-element sequence.

9.4.2.6.3 Example 1:

s = columnize({{1, 2}, {3, 4}, {5, 6}}) 
-- s is { {1,3,5}, {2,4,6}}

9.4.2.6.4 Example 2:

s = columnize({{1, 2}, {3, 4}, {5, 6, 7}}) 
-- s is { {1,3,5}, {2,4,6}, {0,0,7} } 
s = columnize({{1, 2}, {3, 4}, {5, 6, 7},,-999}) -- Change the not-available value. 
-- s is { {1,3,5}, {2,4,6}, {-999,-999,7} }

9.4.2.6.5 Example 3:

s = columnize({{1, 2}, {3, 4}, {5, 6, 7}}, 2) 
-- s is { {2,4,6} } -- Column 2 only

9.4.2.6.6 Example 4:

s = columnize({{1, 2}, {3, 4}, {5, 6, 7}}, {2,1}) 
-- s is { {2,4,6}, {1,3,5} } -- Column 2 then column 1

9.4.2.6.7 Example 5:

s = columnize({"abc", "def", "ghi"}) 
-- s is {"adg", "beh", "cfi" }

9.4.2.7 apply

include std/sequence.e 
public function apply(sequence source, integer rid, object userdata = {})

Apply a function to every element of a sequence returning a new sequence of the same size.

9.4.2.7.1 Parameters:

source : the sequence to map
rid : the routine_id of function to use as converter
userdata : an object passed to each invocation of rid . If omitted, {} is used.

9.4.2.7.2 Returns:

A sequence, the length of source. Each element there is the corresponding element in source mapped using the routine referred to by rid.

9.4.2.7.3 Comments:

The supplied routine must take two parameters. The type of the first parameter must be compatible with all the elements in source. The second parameter is an object containing userdata .

9.4.2.7.4 Example 1:

function greeter(object o, object d) 
    return o[1] & ", " & o[2] & d 
end function 
 
s = apply({{"Hello", "John"}, {"Goodbye", "John"}}, routine_id("greeter"), "!") 
-- s is {"Hello, John!", "Goodbye, John!"}

9.4.2.7.5 See Also:

filter

9.4.2.8 mapping

include std/sequence.e 
public function mapping(object source_arg, sequence from_set, sequence to_set, integer one_level = 0)

Each item from source_arg found in from_set is changed into the corresponding item in to_set

9.4.2.8.1 Parameters:

source_arg : Any EUPHORIA object to be transformed.
from_set : A sequence of objects representing the only items from source_arg that are actually transformed.
to_set : A sequence of objects representing the transformed equivalents of those found in from_set.
one_level : An integer. 0 (the default) means that mapping applies to every atom in every level of sub-sequences. 1 means that mapping only applies to the items at the first level in source_arg .

9.4.2.8.2 Returns:

An object, The transformed version of source_arg.

9.4.2.8.3 Comments:

When one_level is zero or omitted, for each item in source_arg,

if it is an atom then it may be transformed
if it is a sequence, then the mapping is performed recursively on the sequence.
This option required from_set to only contain atoms and contain no sub-sequences.

When one_level is not zero, for each item in source_arg ,

regardless of whether it is an atom or sequence, if it is found in from_set then it is mapped to the corresponding object in to_set..

Mapping occurs when an item in source_arg is found in from_set, then it is replaced by the corresponding object in to_set.

9.4.2.8.4 Example 1:

res = mapping("The Cat in the Hat", "aeiou", "AEIOU") 
-- res is now "ThE CAt In thE HAt"

9.4.2.9 length

<built-in> function length(sequence target)

Return the length of a sequence.

9.4.2.9.1 Parameters:

target : the sequence being queried

9.4.2.9.2 Returns:

An integer, the number of elements target has.

9.4.2.9.3 Comments:

The length of each sequence is stored internally by the interpreter for fast access. In some other languages this operation requires a search through memory for an end marker.

9.4.2.9.4 Example 1:

length({{1,2}, {3,4}, {5,6}})   -- 3 
length("")	 -- 0 
length({})	 -- 0

9.4.2.9.5 See Also:

append, prepend, &

9.4.2.10 reverse

include std/sequence.e 
public function reverse(object target, integer pFrom = 1, integer pTo = 0)

Reverse the order of elements in a sequence.

9.4.2.10.1 Parameters:

target : the sequence to reverse.
pFrom : an integer, the starting point. Defaults to 1.
pTo : an integer, the end point. Defaults to 0.

9.4.2.10.2 Returns:

A sequence, if target is a sequence, the same length as target and the same elements, but those with index between pFrom and pTo appear in reverse order.

9.4.2.10.3 Comments:

In the result sequence, some or all top-level elements appear in reverse order compared to the original sequence. This does not reverse any sub-sequences found in the original sequence.
The pTo parameter can be negative, which indicates an offset from the last element. Thus -1 means the second-last element and 0 means the last element.

9.4.2.10.4 Example 1:

reverse({1,3,5,7})          -- {7,5,3,1} 
reverse({1,3,5,7,9}, 2, -1) -- {1,7,5,3,9} 
reverse({1,3,5,7,9}, 2)     -- {1,9,7,5,3} 
reverse({{1,2,3}, {4,5,6}}) -- {{4,5,6}, {1,2,3}} 
reverse({99})               -- {99} 
reverse({})                 -- {} 
reverse(42)                 -- 42

9.4.2.11 shuffle

include std/sequence.e 
public function shuffle(sequence seq)

Shuffle the elements of a sequence.

9.4.2.11.1 Parameters:

seq: the sequence to shuffle.

9.4.2.11.2 Returns:

A sequence

9.4.2.11.3 Comments:

The input sequence does not have to be in any specific order and can contain duplicates. The output will be in an unpredictable order, which might even be the same as the input order.

9.4.2.11.4 Example 1:

shuffle({1,2,3,3}) -- {3,1,3,2} 
shuffle({1,2,3,3}) -- {2,3,1,3} 
shuffle({1,2,3,3}) -- {1,2,3,3}

9.4.3 Building sequences

9.4.3.1 linear

include std/sequence.e 
public function linear(object start, object increment, integer count)

Returns a sequence in arithmetic progression.

9.4.3.1.1 Parameters:

start : the initial value from which to start
increment : the value to recursively add to start to get new elements
count : an integer, the number of additions to perform.

9.4.3.1.2 Returns:

An object, either 0 on failure or {start, start+increment,...,start+count*increment}

9.4.3.1.3 Comments:

If count is negative, or if adding start to increment would prove to be impossible, then 0 is returned. Otherwise, a sequence, of length count+1, staring with start and whose adjacent elements differ exactly by increment , is returned.

9.4.3.1.4 Example 1:

s = linear({1,2,3},4,3) 
-- s is {{1,2,3},{5,6,7},{9,10,11}}

9.4.3.1.5 See Also:

repeat_pattern

9.4.3.2 repeat_pattern

include std/sequence.e 
public function repeat_pattern(sequence pattern, integer count)

Returns a periodic sequence, given a pattern and a count.

9.4.3.2.1 Parameters:

pattern : the sequence whose elements are to be repeated
count : an integer, the number of times the pattern is to be repeated.

9.4.3.2.2 Returns:

A sequence, empty on failure, and of length count*length(pattern) otherwise. The first elements of the returned sequence are those of pattern. So are those that follow, on to the end.

9.4.3.2.3 Example 1:

s = repeat_pattern({1,2,5},3) 
-- s is {1,2,5,1,2,5,1,2,5}

9.4.3.2.4 See Also:

repeat, linear

9.4.3.3 repeat

<built-in> function repeat(object item, atom count)

Create a sequence whose all elements are identical, with given length.

9.4.3.3.1 Parameters:

item : an object, to which all elements of the result will be equal
count : an atom, the requested length of the result sequence. This must be a value from zero to 0x3FFFFFFF. Any floating point values are first floored.

9.4.3.3.2 Returns:

A sequence, of length count each element of which is item.

9.4.3.3.3 Errors:

count cannot be less than zero and cannot be greater than 1,073,741,823.

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

9.4.3.3.5 Example 1:

repeat(0, 10)	  -- {0,0,0,0,0,0,0,0,0,0} 
 
repeat("JOHN", 4)  -- {"JOHN", "JOHN", "JOHN", "JOHN"} 
-- The interpreter will create only one copy of "JOHN" 
-- in memory and create a sequence containing four references to it.

9.4.3.3.6 See Also:

repeat_pattern, linear

9.4.4 Adding to sequences

9.4.4.1 append

<built-in> function append(sequence target, object x)

Adds an object as the last element of a sequence.

9.4.4.1.1 Parameters:

source : the sequence to add to
x : the object to add

9.4.4.1.2 Returns:

A sequence, whose first elements are those of target and whose last element is x.

9.4.4.1.3 Comments:

The length of the resulting sequence will be length(target) + 1 , no matter what x is.

If x is an atom this is equivalent to result = target & 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 target itself is append()ed to (as in Example 1 below) is highly optimized.

9.4.4.1.4 Example 1:

  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}

9.4.4.1.5 Example 2:

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

9.4.4.1.6 See Also:

prepend, &

9.4.4.2 prepend

<built-in> function prepend(sequence target, object x)

Adds an object as the first element of a sequence.

9.4.4.2.1 Parameters:

source : the sequence to add to
x : the object to add

9.4.4.2.2 Returns:

A sequence, whose last elements are those of target and whose first element is x.

9.4.4.2.3 Comments:

The length of the returned sequence will be length(target) + 1 always.

If x is an atom this is the same as result = x & target . If x is a sequence it is not the same.

The case where target itself is prepend()ed to is handled very efficiently.

9.4.4.2.4 Example 1:

prepend({1,2,3}, {0,0})	 -- {{0,0}, 1, 2, 3} 
-- Compare with concatenation: 
{0,0} & {1,2,3}			 -- {0, 0, 1, 2, 3}

9.4.4.2.5 Example 2:

s = {} 
for i = 1 to 10 do 
   s = prepend(s, i) 
end for 
-- s is {10,9,8,7,6,5,4,3,2,1}

9.4.4.2.6 See Also:

append, &

9.4.4.3 insert

<built-in> function insert(sequence target, object what, integer index)

Insert an object into a sequence as a new element at a given location.

9.4.4.3.1 Parameters:

target : the sequence to insert into
what : the object to insert
index : an integer, the position in target where what should appear

9.4.4.3.2 Returns:

A sequence, which is target with one more element at index, which is what.

9.4.4.3.3 Comments:

target can be a sequence of any shape, and what any kind of object.

The length of the returned sequence is length(target)+1 always.

insert()ing a sequence into a string returns a sequence which is no longer a string.

9.4.4.3.4 Example 1:

s = insert("John Doe", " Middle", 5) 
-- s is {'J','o','h','n'," Middle ",'D','o','e'}

9.4.4.3.5 Example 2:

s = insert({10,30,40}, 20, 2) 
-- s is {10,20,30,40}

9.4.4.3.6 See Also:

remove, splice, append, prepend

9.4.4.4 splice

<built-in> function splice(sequence target, object what, integer index)

Inserts an object as a new slice in a sequence at a given position.

9.4.4.4.1 Parameters:

target : the sequence to insert into
what : the object to insert
index : an integer, the position in target where what should appear

9.4.4.4.2 Returns:

A sequence, which is target with one or more elements, those of what, inserted at locations starting at index.

9.4.4.4.3 Comments:

target can be a sequence of any shape, and what any kind of object.

The length of this new sequence is the sum of the lengths of target and what (atoms are of length 1 for this purpose). splice() is equivalent to insert() when what is an atom, but not when it is a sequence.

Splicing a string into a string results into a new string.

9.4.4.4.4 Example 1:

s = splice("John Doe", " Middle", 5) 
-- s is "John Middle Doe"

9.4.4.4.5 Example 2:

s = splice({10,30,40}, 20, 2) 
-- s is {10,20,30,40}

9.4.4.4.6 See Also:

insert, remove, replace, &

9.4.4.5 pad_head

include std/sequence.e 
public function pad_head(sequence target, integer size, object ch = ' ')

Pad the beginning of a sequence with an object so as to meet a minimum length condition.

9.4.4.5.1 Parameters:

target : the sequence to pad.
size : an integer, the target minimum size for target
padding : an object, usually the character to pad to (defaults to ' ').

9.4.4.5.2 Returns:

A sequence, either target if it was long enough, or a sequence of length size whose last elements are those of target and whose first few head elements all equal padding.

9.4.4.5.3 Comments:

pad_head() will not remove characters. If length(target) is greater than size, this function simply returns target. See head() if you wish to truncate long sequences.

9.4.4.5.4 Example 1:

s = pad_head("ABC", 6) 
-- s is "   ABC" 
 
s = pad_head("ABC", 6, '-') 
-- s is "---ABC"

9.4.4.5.5 See Also:

trim_head, pad_tail , head

9.4.4.6 pad_tail

include std/sequence.e 
public function pad_tail(sequence target, integer size, object ch = ' ')

Pad the end of a sequence with an object so as to meet a minimum length condition.

9.4.4.6.1 Parameters:

target : the sequence to pad.
size : an integer, the target minimum size for target
padding : an object, usually the character to pad to (defaults to ' ').

9.4.4.6.2 Returns:

A sequence, either target if it was long enough, or a sequence of length size whose first elements are those of target and whose last few head elements all equal padding.

9.4.4.6.3 Comments:

pad_tail() will not remove characters. If length(target) is greater than size, this function simply returns target. See tail() if you wish to truncate long sequences.

9.4.4.6.4 Comments:

pad_tail() will not remove characters. If length(str) is greater than params, this function simply returns str. see tail() if you wish to truncate long sequences.

9.4.4.6.5 Example 1:

s = pad_tail("ABC", 6) 
-- s is "ABC   " 
 
s = pad_tail("ABC", 6, '-') 
-- s is "ABC---"

9.4.4.6.6 See Also:

trim_tail, pad_head , tail

9.4.4.7 add_item

include std/sequence.e 
public function add_item(object needle, sequence haystack, integer pOrder = 1)

Adds an item to the sequence if its not already there. If it already exists in the list, the list is returned unchanged.

9.4.4.7.1 Parameters:

needle : object to add.
haystack : sequence to add it to.
order : an integer; determines how the needle affects the haystack. It can be added to the front (prepended), to the back (appended), or sorted after adding. The default is to prepend it.

9.4.4.7.2 Returns:

A sequence, which is haystack with needle added to it.

9.4.4.7.3 Comments:

An error occurs if an invalid order argument is supplied.

The following enum is provided for specifying order:

ADD_PREPEND -- prepend needle to haystack . This is the default option.
ADD_APPEND -- append needle to haystack.
ADD_SORT_UP -- sort haystack in ascending order after inserting needle
ADD_SORT_DOWN -- sort haystack in descending order after inserting needle

9.4.4.7.4 Example 1:

s = add_item( 1, {3,4,2}, ADD_PREPEND ) -- prepend 
-- s is {1,3,4,2}

9.4.4.7.5 Example 2:

s = add_item( 1, {3,4,2}, ADD_APPEND ) -- append 
-- s is {3,4,2,1}

9.4.4.7.6 Example 3:

s = add_item( 1, {3,4,2}, ADD_SORT_UP ) -- ascending 
-- s is {1,2,3,4}

9.4.4.7.7 Example 4:

s = add_item( 1, {3,4,2}, ADD_SORT_DOWN ) -- descending 
-- s is {4,3,2,1}

9.4.4.7.8 Example 5:

s = add_item( 1, {3,1,4,2} ) 
-- s is {3,1,4,2} -- Item was already in list so no change.

9.4.4.8 remove_item

include std/sequence.e 
public function remove_item(object needle, sequence haystack)

Removes an item from the sequence.

9.4.4.8.1 Parameters:

needle : object to remove.
haystack : sequence to remove it from.

9.4.4.8.2 Returns:

A sequence, which is haystack with needle removed from it.

9.4.4.8.3 Comments:

If needle is not in haystack then haystack is returned unchanged.

9.4.4.8.4 Example 1:

s = remove_item( 1, {3,4,2,1} ) --> {3,4,2} 
s = remove_item( 5, {3,4,2,1} ) --> {3,4,2,1}

9.4.5 Extracting, removing, replacing from/into a sequence

9.4.5.1 head

<built-in> function head(sequence source, atom size=1)

Return the first item(s) of a sequence.

9.4.5.1.1 Parameters:

source : the sequence from which elements will be returned
size : an integer, how many head elements at most will be returned. Defaults to 1.

9.4.5.1.2 Returns:

A sequence, source if its length is not greater than size, or the size first elements of source otherwise.

9.4.5.1.3 Example 1:

s2 = head("John Doe", 4) 
-- s2 is John

9.4.5.1.4 Example 2:

s2 = head("John Doe", 50) 
-- s2 is John Doe

9.4.5.1.5 Example 3:

s2 = head({1, 5.4, "John", 30}, 3) 
-- s2 is {1, 5.4, "John"}

9.4.5.1.6 See Also:

tail, mid, slice

9.4.5.2 tail

<built-in> function tail(sequence source, atom n=length(source) - 1)

Return the last items of a sequence.

9.4.5.2.1 Parameters:

source : the sequence to get the tail of.
size : an integer, the number of items to return. (defaults to length(source) - 1)

9.4.5.2.2 Returns:

A sequence, of length at most size. If the length is less than size, then source was returned. Otherwise, the size last elements of source were returned.

9.4.5.2.3 Comments:

source can be any type of sequence, including nested sequences.

9.4.5.2.4 Example 1:

s2 = tail("John Doe", 3) 
-- s2 is "Doe"

9.4.5.2.5 Example 2:

s2 = tail("John Doe", 50) 
-- s2 is "John Doe"

9.4.5.2.6 Example 3:

s2 = tail({1, 5.4, "John", 30}, 3) 
-- s2 is {5.4, "John", 30}

9.4.5.2.7 See Also:

head, mid, slice

9.4.5.3 mid

include std/sequence.e 
public function mid(sequence source, atom start, atom len)

Returns a slice of a sequence, given by a starting point and a length.

9.4.5.3.1 Parameters:

source : the sequence some elements of which will be returned
start : an integer, the lower index of the slice to return
len : an integer, the length of the slice to return

9.4.5.3.2 Returns:

A sequence, made of at most len elements of source. These elements are at contiguous positions in source starting at start.

9.4.5.3.3 Errors:

If len is less than -length(source), an error occurs.

9.4.5.3.4 Comments:

len may be negative, in which case it is added length(source) once.

9.4.5.3.5 Example 1:

s2 = mid("John Middle Doe", 6, 6) 
-- s2 is Middle

9.4.5.3.6 Example 2:

s2 = mid("John Middle Doe", 6, 50) 
-- s2 is Middle Doe

9.4.5.3.7 Example 3:

s2 = mid({1, 5.4, "John", 30}, 2, 2) 
-- s2 is {5.4, "John"}

9.4.5.3.8 See Also:

head, tail, slice

9.4.5.4 slice

include std/sequence.e 
public function slice(sequence source, atom start = 1, atom stop = 0)

Return a portion of the supplied sequence.

9.4.5.4.1 Parameters:

source : the sequence from which to get a portion
start : an integer, the starting point of the portion. Default is 1.
stop : an integer, the ending point of the portion. Default is length(source).

9.4.5.4.2 Returns:

A sequence.

9.4.5.4.3 Comments:

If the supplied start is less than 1 then it set to 1.
If the supplied stop is less than 1 then length(source) is added to it. In this way, 0 represents the end of source, -1 represents one element in from the end of source and so on.
If the supplied stop is greater than length(source) then it is set to the end.
After these adjustments, and if source[start..stop] makes sense, it is returned, otherwise, {} is returned.

9.4.5.4.4 Examples:

s2 = slice("John Doe", 6, 8)--> "Doe" 
s2 = slice("John Doe", 6, 50) --> "Doe" 
s2 = slice({1, 5.4, "John", 30}, 2, 3) --> {5.4, "John"} 
s2 = slice({1,2,3,4,5}, 2, -1) --> {2,3,4} 
s2 = slice({1,2,3,4,5}, 2) --> {2,3,4,5} 
s2 = slice({1,2,3,4,5}, , 4) --> {1,2,3,4}

9.4.5.4.5 See Also:

head, mid, tail

9.4.5.5 vslice

include std/sequence.e 
public function vslice(sequence source, atom colno, object error_control = 0)

Perform a vertical slice on a nested sequence

9.4.5.5.1 Parameters:

source : the sequence to take a vertical slice from
colno : an atom, the column number to extract (rounded down)
error_control : an object which says what to do if some element does not exist. Defaults to 0 (crash in such a circumstance).

9.4.5.5.2 Returns:

A sequence, usually of the same length as source, made of all the source[x][colno].

9.4.5.5.3 Errors:

If an element is not defined and error_control is 0, an error occurs. If colno is less than 1, it cannot be any valid column, and an error occurs.

9.4.5.5.4 Comments:

If it is not possible to return the sequence of all source[x][colno]] for all available x, the outcome is decided by error_control:

If 0 (the default), program is aborted.
If a nonzero atom, the short vertical slice is returned.
Otherwise, elements of error_control will be taken to make for any missing element. A short vertical slice is returned if error_control is exhausted.

9.4.5.5.5 Example 1:

s = vslice({{5,1}, {5,2}, {5,3}}, 2) 
-- s is {1,2,3} 
 
s = vslice({{5,1}, {5,2}, {5,3}}, 1) 
-- s is {5,5,5}

9.4.5.5.6 See Also:

slice, project

9.4.5.6 remove

<built-in> function remove(sequence target, atom start, atom stop=start)

Remove an item, or a range of items from a sequence.

9.4.5.6.1 Parameters:

target : the sequence to remove from.
start : an atom, the (starting) index at which to remove
stop : an atom, the index at which to stop removing (defaults to start)

9.4.5.6.2 Returns:

A sequence, obtained from target by carving the start..stop slice out of it.

9.4.5.6.3 Comments:

A new sequence is created. target can be a string or complex sequence.

9.4.5.6.4 Example 1:

s = remove("Johnn Doe", 4) 
-- s is "John Doe"

9.4.5.6.5 Example 2:

s = remove({1,2,3,3,4}, 4) 
-- s is {1,2,3,4}

9.4.5.6.6 Example 3:

s = remove("John Middle Doe", 6, 12) 
-- s is "John Doe"

9.4.5.6.7 Example 4:

s = remove({1,2,3,3,4,4}, 4, 5) 
-- s is {1,2,3,4}

9.4.5.6.8 See Also:

replace, insert, splice, remove_all

9.4.5.7 patch

include std/sequence.e 
public function patch(sequence target, sequence source, integer start, object filler = ' ')

Changes a sequence slice, possibly with padding

9.4.5.7.1 Parameters:

target : a sequence, a modified copy of which will be returned
source : a sequence, to be patched inside or outside target
start : an integer, the position at which to patch
filler : an object, used for filling gaps. Defaults to ' '

9.4.5.7.2 Returns:

A sequence, which looks like target, but a slice starting at start equals source.

9.4.5.7.3 Comments:

In some cases, this call will result in the same result as replace().

If source doesn't fit into target because of the lengths and the supplied start value, gaps will be created, and filler is used to fill them in.

Notionally, target has an infinite amount of filler on both sides, and start counts position relative to where target actually starts. Then, notionally, a replace() operation is performed.

9.4.5.7.4 Example 1:

sequence source = "abc", target = "John Doe" 
sequence s = patch(target, source, 11,'0') 
-- s is now "John Doe00abc"

9.4.5.7.5 Example 2:

sequence source = "abc", target = "John Doe" 
sequence s = patch(target, source, -1) 
-- s is now "abcohn Doe" 
Note that there was no gap to fill. 
Since -1 = 1 - 2, the patching started 2 positions before the initial 'J'.

9.4.5.7.6 Example 3:

sequence source = "abc", target = "John Doe" 
sequence s = patch(target, source, 6) 
-- s is now "John Dabc"

9.4.5.7.7 See Also:

mid, replace

9.4.5.8 remove_all

include std/sequence.e 
public function remove_all(object needle, sequence haystack)

Removes all occurrences of some object from a sequence.

9.4.5.8.1 Parameters:

needle : the object to remove.
haystack : the sequence to remove from.

9.4.5.8.2 Returns:

A sequence, of length at most length(haystack) , and which has the same elements, without any copy of needle left

9.4.5.8.3 Comments:

This function weeds elements out, not sub-sequences.

9.4.5.8.4 Example 1:

s = remove_all( 1, {1,2,4,1,3,2,4,1,2,3} ) 
-- s is {2,4,3,2,4,2,3}

9.4.5.8.5 Example 2:

s = remove_all("x", "I'm toox secxksy for my shixrt.") 
-- s is "I'm too secksy for my shirt."

9.4.5.8.6 See Also:

remove, replace

9.4.5.9 retain_all

include std/sequence.e 
public function retain_all(object needles, sequence haystack)

Keeps all occurrences of a set of objects from a sequence and removes all others.

9.4.5.9.1 Parameters:

needles : the set of objects to retain.
haystack : the sequence to remove items not in needles .

9.4.5.9.2 Returns:

A sequence containing only those objects from haystack that are also in needles.

9.4.5.9.3 Example:

s = retain_all( {1,3,5}, {1,2,4,1,3,2,4,1,2,3} ) --> {1,1,3,1,3} 
s = retain_all("0123456789", "+34 (04) 555-44392") -> "340455544392"

9.4.5.9.4 See Also:

remove, replace, remove_all

9.4.5.10 filter

include std/sequence.e 
public function filter(sequence source, object rid, object userdata = {}, object rangetype = "")

Filter a sequence based on a user supplied comparator function.

9.4.5.10.1 Parameters:

source : sequence to filter
rid : Either a routine_id of function to use as comparator or one of the predefined comparitors.
userdata : an object passed to each invocation of rid . If omitted, {} is used.
rangetype: A sequence. Only used when rid is "in" or "out". This is used to let the function know how to interpret userdata. When rangetype is an empty string (which is the default), then userdata is treated as a set of zero or more discrete items such that "in" will only return items from source that are in the set of item in userdata and "out" returns those not in userdata. The other values for rangetype mean that userdata must be a set of exactly two items, that represent the lower and upper limits of a range of values.

9.4.5.10.2 Returns:

A sequence, made of the elements in source which passed the comparitor test.

9.4.5.10.3 Comments:

The only items from source that are returned are those that pass the test.
When rid is a routine_id, that user defined routine must be a function. Each item in source, along with the userdata is passed to the function. The function must return a non-zero atom if the item is to be included in the result sequence, otherwise it should return zero to exclude it from the result.
The predefined comparitors are...

"<" or "lt"	return items in `source` that are less than `userdata`
"<=" or "le"	return items in `source` that are less than or equal to `userdata`
"=" or "==" or "eq"	return items in `source` that are equal to `userdata`
"!=" or "ne"	return items in `source` that are not equal to `userdata`
">" or "gt"	return items in `source` that are greater than `userdata`
">=" or "ge"	return items in `source` that are greater than or equal to `userdata`
"in"	return items in `source` that are in `userdata`
"out"	return items in `source` that are not in `userdata`

Range Type Usage

Range Type	Meaning
"[]"	Inclusive range. Lower and upper are in the range.
"[)"	Low Inclusive range. Lower is in the range but upper is not.
"(]"	High Inclusive range. Lower is not in the range but upper is.
"()"	Exclusive range. Lower and upper are not in the range.

9.4.5.10.4 Example 1:

function mask_nums(atom a, object t) 
    if sequence(t) then 
        return 0 
    end if 
    return and_bits(a, t) != 0 
end function 
 
function even_nums(atom a, atom t) 
    return and_bits(a,1) = 0 
end function 
 
constant data = {5,8,20,19,3,2,10} 
filter(data, routine_id("mask_nums"), 1) --> {5,19,3} 
filter(data, routine_id("mask_nums"), 2) -->{19, 3, 2, 10} 
filter(data, routine_id("even_nums")) -->{8, 20, 2, 10} 
 
-- Using 'in' and 'out' with sets. 
filter(data, "in", {3,4,5,6,7,8}) -->{5,8,3} 
filter(data, "out", {3,4,5,6,7,8}) -->{20,19,2,10} 
 
-- Using 'in' and 'out' with ranges. 
filter(data, "in",  {3,8}, "[]") --> {5,8,3} 
filter(data, "in",  {3,8}, "[)") --> {5,3} 
filter(data, "in",  {3,8}, "(]") --> {5,8} 
filter(data, "in",  {3,8}, "()") --> {5} 
filter(data, "out", {3,8}, "[]") --> {20,19,2,10} 
filter(data, "out", {3,8}, "[)") --> {8,20,19,2,10} 
filter(data, "out", {3,8}, "(]") --> {20,19,3,2,10} 
filter(data, "out", {3,8}, "()") --> {8,20,19,3,2,10}

9.4.5.10.5 Example 3:

function quiksort(sequence s) 
	if length(s) < 2 then 
		return s 
	end if 
	return quiksort( filter(s[2..$], "<=", s[1]) ) & s[1] & quiksort(filter(s[2..$], ">", s[1])) 
end function 
? quiksort( {5,4,7,2,4,9,1,0,4,32,7,54,2,5,8,445,67} ) 
--> {0,1,2,2,4,4,4,5,5,7,7,8,9,32,54,67,445}

9.4.5.10.6 See Also:

apply

9.4.5.11 STDFLTR_ALPHA

public constant STDFLTR_ALPHA

Predefined routine_id for use with filter().

9.4.5.11.1 Comments:

Used to filter out non-alphabetic characters from a string.

9.4.5.11.2 Example:

-- Collect only the alphabetic characters from 'text' 
 result = filter(text, STDFLTR_ALPHA)

9.4.5.12 replace

<built-in> function replace(sequence target, object replacement, integer start, integer stop=start)

Replace a slice in a sequence by an object.

9.4.5.12.1 Parameters:

target : the sequence in which replacement will be done.
replacement : an object, the item to replace with.
start : an integer, the starting index of the slice to replace.
stop : an integer, the stopping index of the slice to replace.

9.4.5.12.2 Returns:

A sequence, which is made of target with the start..stop slice removed and replaced by replacement , which is splice()d in.

9.4.5.12.3 Comments:

A new sequence is created. target can be a string or complex sequence of any shape.

To replace by just one element, enclose replacement in curly braces, which will be removed at replace time.

9.4.5.12.4 Example 1:

s = replace("John Middle Doe", "Smith", 6, 11) 
-- s is "John Smith Doe" 
 
s = replace({45.3, "John", 5, {10, 20}}, 25, 2, 3) 
-- s is {45.3, 25, {10, 20}}

9.4.5.12.5 See Also:

splice, remove, remove_all

9.4.5.13 replace_all

include std/sequence.e 
public function replace_all(sequence source, object olddata, object newdata)

Replaces all occurrences of olddata with newdata

9.4.5.13.1 Parameters:

source : the sequence in which replacements will be done.
olddata : the sequence/item which is going to be replaced. If this is an empty sequence, the source is returned as is.
newdata : the sequence/item which will be the replacement.

9.4.5.13.2 Returns:

A sequence, which is made of source with all olddata occurrences replaced by newdata.

9.4.5.13.3 Comments:

This also removes all olddata occurrences when newdata is "".

9.4.5.13.4 Example:

s = replace_all("abracadabra", 'a', 'X') 
-- s is now "XbrXcXdXbrX" 
s = replace_all("abracadabra", "ra", 'X') 
-- s is now "abXcadabX" 
s = replace_all("abracadabra", "a", "aa") 
-- s is now "aabraacaadaabraa" 
s = replace_all("abracadabra", "a", "") 
-- s is now "brcdbr"

9.4.5.13.5 See Also:

replace, remove_all

9.4.5.14 extract

include std/sequence.e 
public function extract(sequence source, sequence indexes)

Turns a sequences of indexes into the sequence of elements in a source that have such indexes.

9.4.5.14.1 Parameters:

source : the sequence from which to extract elements
indexes : a sequence of atoms, the indexes of the elements to be fetched in source.

9.4.5.14.2 Returns:

A sequence, of length at most length(indexes) . If p is the r-th element of indexes which is valid on source, then result[r] is source[p].

9.4.5.14.3 Example 1:

s = extract({11,13,15,17},{3,1,2,1,4}) 
-- s is {15,11,13,11,17}

9.4.5.14.4 See Also:

slice

9.4.5.15 project

include std/sequence.e 
public function project(sequence source, sequence coords)

Creates a list of sequences based on selected elements from sequences in the source.

9.4.5.15.1 Parameters:

source : a list of sequences.
coords : a list of index lists.

9.4.5.15.2 Returns:

A sequence, with the same length as source . Each of its elements is a sequence, the length of coords. Each innermost sequence is made of the elements from the corresponding source sub-sequence.

9.4.5.15.3 Comments:

For each sequence in source, a set of sub-sequences is created; one for each index list in coords. An index list is just a sequence containing indexes for items in a sequence.

9.4.5.15.4 Example 1:

s = project({ "ABCD",  "789"},  {{1,2}, {3,1}, {2}}) 
-- s is {{"AB","CA","B"},{"78","97","8"}}

9.4.5.15.5 See Also:

vslice, extract

9.4.6 Changing the shape of a sequence

9.4.6.1 split

include std/sequence.e 
public function split(sequence st, object delim = ' ', integer limit = 0, integer no_empty = 0)

Split a sequence on separator delimiters into a number of sub-sequences.

9.4.6.1.1 Parameters:

source : the sequence to split.
delim : an object (default is ' '). The delimiter that separates items in source.
limit : an integer (default is 0). The maximum number of sub-sequences to create. If zero, there is no limit.
no_empty : an integer (default is 0). If not zero then all zero-length sub-sequences are removed from the returned sequence. Use this when leading, trailing and duplicated delimiters are not significant.

9.4.6.1.2 Returns:

A sequence, of sub-sequences of source. Delimiters are removed.

9.4.6.1.3 Comments:

This function may be applied to a string sequence or a complex sequence.

If limit is > 0, this is the maximum number of sub-sequences that will created, otherwise there is no limit.

9.4.6.1.4 Example 1:

result = split("John Middle Doe") 
-- result is {"John", "Middle", "Doe"}

9.4.6.1.5 Example 2:

result = split("John,Middle,Doe", ",", 2) 
-- result is {"John", "Middle,Doe"}

9.4.6.1.6 See Also:

split_any, breakup, join

9.4.6.2 split_any

include std/sequence.e 
public function split_any(sequence source, object delim, integer limit = 0, integer no_empty = 0)

Split a sequence by any of the separators in the list of delimiters.

If limit is > 0 then limit the number of tokens that will be split to limit.

9.4.6.2.1 Parameters:

source : the sequence to split.
delim : a list of delimiters to split by.
limit : an integer (default is 0). The maximum number of sub-sequences to create. If zero, there is no limit.
no_empty : an integer (default is 0). If not zero then all zero-length sub-sequences removed from the returned sequence. Use this when leading, trailing and duplicated delimiters are not significant.

9.4.6.2.2 Comments:

This function may be applied to a string sequence or a complex sequence.

It works like split(), but in this case delim is a set of potential delimiters rather than a single delimiter.

9.4.6.2.3 Example 1:

result = split_any("One,Two|Three.Four", ".,|") 
-- result is {"One", "Two", "Three", "Four"} 
result = split_any(",One,,Two|.Three||.Four,", ".,|",,1) -- No Empty option 
-- result is {"One", "Two", "Three", "Four"}

9.4.6.2.4 See Also:

split, breakup, join

9.4.6.3 join

include std/sequence.e 
public function join(sequence items, object delim = " ")

Join sequences together using a delimiter.

9.4.6.3.1 Parameters:

items : the sequence of items to join.
delim : an object, the delimiter to join by. Defaults to " ".

9.4.6.3.2 Comments:

This function may be applied to a string sequence or a complex sequence

9.4.6.3.3 Example 1:

result = join({"John", "Middle", "Doe"}) 
-- result is "John Middle Doe"

9.4.6.3.4 Example 2:

result = join({"John", "Middle", "Doe"}, ",") 
-- result is "John,Middle,Doe"

9.4.6.3.5 See Also:

split, split_any, breakup

9.4.6.4 BK_LEN

include std/sequence.e 
public enum BK_LEN

Indicates that size parameter is maximum length of sub-sequence. See breakup

9.4.6.5 BK_PIECES

include std/sequence.e 
public enum BK_PIECES

Indicates that size parameter is maximum number of sub-sequence. See breakup

9.4.6.6 breakup

include std/sequence.e 
public function breakup(sequence source, object size, integer style = BK_LEN)

Breaks up a sequence into multiple sequences of a given length.

9.4.6.6.1 Parameters:

source : the sequence to be broken up into sub-sequences.
size : an object, if an integer it is either the maximum length of each resulting sub-sequence or the maximum number of sub-sequences to break source into.
If size is a sequence, it is a list of element counts for the sub-sequences it creates.
style : an integer, Either BK_LEN if size integer represents the sub-sequences' maximum length, or BK_PIECES if the size integer represents the maximum number of sub-sequences (pieces) to break source into.

9.4.6.6.2 Returns:

A sequence, of sequences.

9.4.6.6.3 Comments:

When size is an integer and style is BK_LEN...
The sub-sequences have length size, except possibly the last one, which may be shorter. For example if source has 11 items and size is 3, then the first three sub-sequences will get 3 items each and the remaining 2 items will go into the last sub-sequence. If size is less than 1 or greater than the length of the source, the source is returned as the only sub-sequence.

When size is an integer and style is BK_PIECES...
There is exactly size sub-sequences created. If the source is not evenly divisible into that many pieces, then the lefthand sub-sequences will contain one more element than the right-hand sub-sequences. For example, if source contains 10 items and we break it into 3 pieces, piece #1 gets 4 elements, piece #2 gets 3 items and piece #3 gets 3 items - a total of 10. If source had 11 elements then the pieces will have 4,4, and 3 respectively.

When size is a sequence...
The style parameter is ignored in this case. The source will be broken up according to the counts contained in the size parameter. For example, if size was {3,4,0,1} then piece #1 gets 3 items, #2 gets 4 items, #3 gets 0 items, and #4 gets 1 item. Note that if not all items from source are placed into the sub-sequences defined by size , and extra sub-sequence is appended that contains the remaining items from source.

In all cases, when concatenated these sub-sequences will be identical to the original source.

9.4.6.6.4 Example 1:

s = breakup("5545112133234454", 4) 
-- s is {"5545", "1121", "3323", "4454"}

9.4.6.6.5 Example 2:

s = breakup("12345", 2) 
-- s is {"12", "34", "5"}

9.4.6.6.6 Example 3:

s = breakup({1,2,3,4,5,6}, 3) 
-- s is {{1,2,3}, {4,5,6}}

9.4.6.6.7 Example 4:

s = breakup("ABCDEF", 0) 
-- s is {"ABCDEF"}

9.4.6.6.8 See Also:

split flatten

9.4.6.7 flatten

include std/sequence.e 
public function flatten(sequence s, object delim = "")

Remove all nesting from a sequence.

9.4.6.7.1 Parameters:

s : the sequence to flatten out.
delim : An optional delimiter to place after each flattened sub-sequence (except the last one).

9.4.6.7.2 Returns:

A sequence, of atoms, all the atoms in s enumerated.

9.4.6.7.3 Comments:

If you consider a sequence as a tree, then the enumeration is performed by left-right reading of the tree. The elements are simply read left to right, without any care for braces.
Empty sub-sequences are stripped out entirely.

9.4.6.7.4 Example 1:

s = flatten({{18, 19}, 45, {18.4, 29.3}}) 
-- s is {18, 19, 45, 18.4, 29.3}

9.4.6.7.5 Example 2:

s = flatten({18,{ 19, {45}}, {18.4, {}, 29.3}}) 
-- s is {18, 19, 45, 18.4, 29.3}

9.4.6.7.6 Example 3:

Using the delimiter argument. 
s = flatten({"abc", "def", "ghi"}, ", ") 
-- s is "abc, def, ghi"

9.4.6.8 pivot

include std/sequence.e 
public function pivot(object data_p, object pivot_p = 0)

Returns a sequence of three sub-sequences. The sub-sequences contain all the elements less than the supplied pivot value, equal to the pivot, and greater than the pivot.

9.4.6.8.1 Parameters:

data_p : Either an atom or a list. An atom is treated as if it is one-element sequence.
pivot_p : An object. Default is zero.

9.4.6.8.2 Returns:

A sequence, { {less than pivot}, {equal to pivot}, {greater than pivot} }

9.4.6.8.3 Comments:

pivot() is used as a split up a sequence relative to a specific value.

9.4.6.8.4 Example 1:

? pivot( {7, 2, 8.5, 6, 6, -4.8, 6, 6, 3.341, -8, "text"}, 6 ) 
  -- Ans: {{2, -4.8, 3.341, -8}, {6, 6, 6, 6}, {7, 8.5, "text"}} 
? pivot( {4, 1, -4, 6, -1, -7, 9, 10} ) 
  -- Ans: {{-4, -1, -7}, {}, {4, 1, 6, 9, 10}} 
? pivot( 5 ) 
  -- Ans: {{}, {}, {5}}

9.4.6.8.5 Example 2:

function quiksort(sequence s) 
	if length(s) < 2 then 
		return s 
	end if 
	sequence k 
	 
	k = pivot(s, s[rand(length(s))]) 
	 
	return quiksort(k[1]) & k[2] & quiksort(k[3]) 
end function 
sequence t2 = {5,4,7,2,4,9,1,0,4,32,7,54,2,5,8,445,67} 
? quiksort(t2) --> {0,1,2,2,4,4,4,5,5,7,7,8,9,32,54,67,445}

9.4.6.9 build_list

include std/sequence.e 
public function build_list(sequence source, object transformer, integer singleton = 1, object user_data = {})

Implements "List Comprehension" or building a list based on the contents of another list.

9.4.6.9.1 Parameters:

source : A sequence. The list of items to base the new list upon.
transformer : One or more routine_ids. These are routine ids of functions that must receive three parameters (object x, sequence i, object u) where 'x' is an item in the source list, 'i' contains the position that 'x' is found in the source list and the length of source, and 'u' is the user_data value. Each transformer must return a two-element sequence. If the first element is zero, then build_list() continues on with the next transformer function for the same 'x'. If the first element is not zero, the second element is added to the new list being built (other elements are ignored) and build_list skips the rest of the transformers and processes the next element in source.
singleton : An integer. If zero then the transformer functions return multiple list elements. If not zero then the transformer functions return a single item (which might be a sequence).
user_data : Any object. This is passed unchanged to each transformer function.

9.4.6.9.2 Returns:

A sequence, The new list of items.

9.4.6.9.3 Comments:

If the transformer is -1, then the source item is just copied.

9.4.6.9.4 Example 1:

function remitem(object x, sequence i, object q) 
	if (x < q) then 
		return {0} -- no output 
	else 
		return {1,x} -- copy 'x' 
	end if 
end function 
 
sequence s 
-- Remove negative elements (x < 0) 
s = build_list({-3, 0, 1.1, -2, 2, 3, -1.5}, routine_id("remitem"), , 0) 
-- s is {0, 1.1, 2, 3}

9.4.6.10 transform

include std/sequence.e 
public function transform(sequence source_data, object transformer_rids)

Transforms the input sequence by using one or more user-supplied transformers.

9.4.6.10.1 Parameters:

source_data : A sequence to be transformed.
transformer_rids : An object. One or more routine_ids used to transform the input.

9.4.6.10.2 Returns:

The source sequence, that has been transformed.

9.4.6.10.3 Comments:

This works by calling each transformer in order, passing to it the result of the previous transformation. Of course, the first transformer gets the original sequence as passed to this routine.
Each transformer routine takes one or more parameters. The first is a source sequence to be transformed and others are any user data that may have been supplied to the transform routine.
Each transformer routine returns a transformed sequence.
The transformer_rids parameters is either a single routine_id or a sequence of routine_ids. In this second case, the routine_id may actually be a multi-element sequence containing the real routine_id and some user data to pass to the transformer routine. If there is no user data then the transformer is called with only one parameter.

9.4.6.10.4 Examples:

res = transform(" hello    ", { 
                      {routine_id("trim"), " ",0}, 
                      routine_id("upper"), 
                      {routine_id("replace_all"), "O", "A"} 
                  }) 
--> "HELLA"

9.4.6.11 sim_index

include std/sequence.e 
public function sim_index(sequence A, sequence B)

Calculates the similarity between two sequences.

9.4.6.11.1 Parameters:

A : A sequence.
B : A sequence.

9.4.6.11.2 Returns:

An atom, the closer to zero, the more the two sequences are alike.

9.4.6.11.3 Comments:

The calculation is weighted to give mismatched elements towards the front of the sequences larger scores. This means that sequences that differ near the begining are considered more un-alike than mismatches towards the end of the sequences. Also, unmatched elements from the first sequence are weighted more than unmatched elements from the second sequence.

Two identical sequences return zero. A non-zero means that they are not the same and larger values indicate a larger differences.

9.4.6.11.4 Example 1:

? sim_index("sit",      "sin")      --> 0.08784 
? sim_index("sit",      "sat")      --> 0.32394 
? sim_index("sit",      "skit")     --> 0.34324 
? sim_index("sit",      "its")      --> 0.68293 
? sim_index("sit",      "kit")      --> 0.86603 
 
? sim_index("knitting", "knitting") --> 0.00000 
? sim_index("kitting",  "kitten")   --> 0.09068 
? sim_index("knitting", "knotting") --> 0.27717 
? sim_index("knitting", "kitten")   --> 0.35332 
? sim_index("abacus","zoological")  --> 0.76304

9.4.6.12 SEQ_NOALT

include std/sequence.e 
public constant SEQ_NOALT

Indicates that remove_subseq() must not replace removed sub-sequences with an alternative value.

9.4.6.13 remove_subseq

include std/sequence.e 
public function remove_subseq(sequence source_list, object alt_value = SEQ_NOALT)

Removes all sub-sequences from the supplied sequence, optionally replacing them with a supplied alternative value. One common use is to remove all strings from a mixed set of numbers and strings.

9.4.6.13.1 Parameters:

source_list : A sequence from which sub-sequences are removed.
alt_value : An object. The default is SEQ_NOALT, which causes sub-sequences to be physically removed, otherwise any other value will be used to replace the sub-sequence.

9.4.6.13.2 Returns:

A sequence, which contains only the atoms from source_list and optionally the alt_value where sub-sequences used to be.

9.4.6.13.3 Example:

sequence s = remove_subseq({4,6,"Apple",0.1, {1,2,3}, 4}) 
-- 's' is now {4, 6, 0.1, 4} -- length now 4 
s = remove_subseq({4,6,"Apple",0.1, {1,2,3}, 4}, -1) 
-- 's' is now {4, 6, -1, 0.1, -1, 4} -- length unchanged.

9.4.6.14 RD_INPLACE

include std/sequence.e 
public enum RD_INPLACE

These are used with the remove_dups() function.

RD_INPLACE removes items while preserving the original order of the unique items.
RD_PRESORTED assumes that the elements in source_data are already sorted. If they are not already sorted, this option merely removed adjacent duplicate elements.
RD_SORT will return the unique elements in ascending sorted order.

9.4.6.15 remove_dups

include std/sequence.e 
public function remove_dups(sequence source_data, integer proc_option = RD_PRESORTED)

Removes duplicate elements

9.4.6.15.1 Parameters:

source_data : A sequence that may contain duplicated elements
proc_option : One of RD_INPLACE, RD_PRESORTED, or RD_SORT.

RD_INPLACE removes items while preserving the original order of the unique items.
RD_PRESORTED assumes that the elements in source_data are already sorted. If they are not already sorted, this option merely removed adjacent duplicate elements.
RD_SORT will return the unique elements in ascending sorted order.

9.4.6.15.2 Returns:

A sequence, that contains only the unique elements from source_data.

9.4.6.15.3 Example 1:

sequence s = { 4,7,9,7,2,5,5,9,0,4,4,5,6,5} 
? remove_dups(s, RD_INPLACE) --> {4,7,9,2,5,0,6} 
? remove_dups(s, RD_SORT) --> {0,2,4,5,6,7,9} 
? remove_dups(s, RD_PRESORTED) --> {4,7,9,7,2,5,9,0,4,5,6,5} 
? remove_dups(sort(s), RD_PRESORTED) --> {0,2,4,5,6,7,9}

9.4.6.16 COMBINE_UNSORTED

include std/sequence.e 
public enum COMBINE_UNSORTED

9.4.6.17 COMBINE_SORTED

include std/sequence.e 
public enum COMBINE_SORTED

9.4.6.18 combine

include std/sequence.e 
public function combine(sequence source_data, integer proc_option = COMBINE_SORTED)

Combines all the sub-sequences into a single, optionally sorted, list

9.4.6.18.1 Parameters:

source_data : A sequence that contains sub-sequences to be combined.
proc_option : An integer; COMBINE_UNSORTED to return a non-sorted list and COMBINE_SORTED (the default) to return a sorted list.

9.4.6.18.2 Returns:

A sequence, that contains all the elements from all the first-level of sub-sequences from source_data.

9.4.6.18.3 Comments:

The elements in the sub-sequences do not have to be pre-sorted.

Only one level of sub-sequence is combined.

9.4.6.18.4 Example 1:

sequence s = { {4,7,9}, {7,2,5,9}, {0,4}, {5}, {6,5}} 
? combine(s, COMBINE_SORTED)   --> {0,2,4,4,5,5,5,6,7,7,9,9} 
? combine(s, COMBINE_UNSORTED) --> {4,7,9,7,2,5,9,0,4,5,6,5}

9.4.6.18.5 Example 2:

sequence s = { {"cat", "dog"}, {"fish", "whale"}, {"wolf"}, {"snail", "worm"}} 
? combine(s)                   --> {"cat","dog","fish","snail","whale","wolf","worm"} 
? combine(s, COMBINE_UNSORTED) --> {"cat","dog","fish","whale","wolf","snail","worm"}

9.4.6.18.6 Example 3:

sequence s = { "cat", "dog","fish", "whale", "wolf", "snail", "worm"} 
? combine(s)                   --> "aaacdeffghhiilllmnooorsstwww" 
? combine(s, COMBINE_UNSORTED) --> "catdogfishwhalewolfsnailworm"

9.4.6.19 minsize

include std/sequence.e 
public function minsize(sequence source_data, integer min_size, object new_data)

Ensures that the supplied sequence is at least the supplied minimum length.

9.4.6.19.1 Parameters:

source_data : A sequence that might need extending.
min_size: An integer. The minimum length that source_data must be.
new_data: An object. This used to when source_data needs to be extended, in which case it is appended as many times as required to make the length equal to min_size.

9.4.6.19.2 Returns:

A sequence.

9.4.6.19.3 Example:

sequence s 
s = minsize({4,3,6,2,7,1,2}, 10, -1) --> {4,3,6,2,7,1,2,-1,-1,-1} 
s = minsize({4,3,6,2,7,1,2},  5, -1) --> {4,3,6,2,7,1,2}

9.5 Serialization of EUPHORIA Objects

---------- Routines

---------------- deserialize

---------------- serialize

---------------- dump

---------------- load

9.5.1 Routines

9.5.1.1 deserialize

include std/serialize.e 
public function deserialize(object sdata, integer pos = 1)

Convert a serialized object in to a standard EUPHORIA object.

9.5.1.1.1 Parameters:

sdata : either a sequence containing one or more concatenated serialized objects or an open file handle. If this is a file handle, the current position in the file is assumed to be at a serialized object in the file.
pos : optional index into sdata. If omitted 1 is assumed. The index must point to the start of a serialized object.

9.5.1.1.2 Returns:

The return value, depends on the input type.

If sdata is a file handle then this function returns a EUPHORIA object that had been stored in the file, and moves the current file to the first byte after the stored object.
If sdata is a sequence then this returns a two-element sequence. The first element is the EUPHORIA object that corresponds to the serialized object that begins at index pos, and the second element is the index position in the input parameter just after the serialized object.

9.5.1.1.3 Comments:

A serialized object is one that has been returned from the serialize function.

9.5.1.1.4 Example 1:

 sequence objcache 
 objcache = serialize(FirstName) & 
            serialize(LastName) & 
            serialize(PhoneNumber) & 
            serialize(Address) 
 
 sequence res 
 integer pos = 1 
 res = deserialize( objcache , pos) 
 FirstName = res[1] pos = res[2] 
 res = deserialize( objcache , pos) 
 LastName = res[1] pos = res[2] 
 res = deserialize( objcache , pos) 
 PhoneNumber = res[1] pos = res[2] 
 res = deserialize( objcache , pos) 
 Address = res[1] pos = res[2]

9.5.1.1.5 Example 2:

 sequence objcache 
 objcache = serialize({FirstName, 
                      LastName, 
                      PhoneNumber, 
                      Address}) 
 
 sequence res 
 res = deserialize( objcache ) 
 FirstName = res[1][1] 
 LastName = res[1][2] 
 PhoneNumber = res[1][3] 
 Address = res[1][4]

9.5.1.1.6 Example 3:

 integer fh 
 fh = open("cust.dat", "wb") 
 puts(fh, serialize(FirstName)) 
 puts(fh, serialize(LastName)) 
 puts(fh, serialize(PhoneNumber)) 
 puts(fh, serialize(Address)) 
 close(fh) 
 
 fh = open("cust.dat", "rb") 
 FirstName = deserialize(fh) 
 LastName = deserialize(fh) 
 PhoneNumber = deserialize(fh) 
 Address = deserialize(fh) 
 close(fh)

9.5.1.1.7 Example 4:

 integer fh 
 fh = open("cust.dat", "wb") 
 puts(fh, serialize({FirstName, 
                     LastName, 
                     PhoneNumber, 
                     Address})) 
 close(fh) 
 
 sequence res 
 fh = open("cust.dat", "rb") 
 res = deserialize(fh) 
 close(fh) 
 FirstName = res[1] 
 LastName = res[2] 
 PhoneNumber = res[3] 
 Address = res[4]

9.5.1.2 serialize

include std/serialize.e 
public function serialize(object x)

Convert a standard EUPHORIA object in to a serialized version of it.

9.5.1.2.1 Parameters:

euobj : any EUPHORIA object.

9.5.1.2.2 Returns:

A sequence, this is the serialized version of the input object.

9.5.1.2.3 Comments:

A serialized object is one that has been converted to a set of byte values. This can then by written directly out to a file for storage.

You can use the deserialize function to convert it back into a standard EUPHORIA object.

9.5.1.2.4 Example 1:

 integer fh 
 fh = open("cust.dat", "wb") 
 puts(fh, serialize(FirstName)) 
 puts(fh, serialize(LastName)) 
 puts(fh, serialize(PhoneNumber)) 
 puts(fh, serialize(Address)) 
 close(fh) 
 
 fh = open("cust.dat", "rb") 
 FirstName = deserialize(fh) 
 LastName = deserialize(fh) 
 PhoneNumber = deserialize(fh) 
 Address = deserialize(fh) 
 close(fh)

9.5.1.2.5 Example 2:

 integer fh 
 fh = open("cust.dat", "wb") 
 puts(fh, serialize({FirstName, 
                     LastName, 
                     PhoneNumber, 
                     Address})) 
 close(fh) 
 
 sequence res 
 fh = open("cust.dat", "rb") 
 res = deserialize(fh) 
 close(fh) 
 FirstName = res[1] 
 LastName = res[2] 
 PhoneNumber = res[3] 
 Address = res[4]

9.5.1.3 dump

include std/serialize.e 
public function dump(sequence data, sequence filename)

Saves a EUPHORIA object to disk in a binary format.

9.5.1.3.1 Parameters:

data : any EUPHORIA object.
filename : the name of the file to save it to.

9.5.1.3.2 Returns:

An integer, 0 if the function fails, otherwise the number of bytes in the created file.

9.5.1.3.3 Comments:

If the named file doesn't exist it is created, otherwise it is overwritten.

You can use the load function to recover the data from the file.

9.5.1.3.4 Example :

include std/serialize.e 
integer size = dump(myData, theFileName)  
if size = 0 then 
    puts(1, "Failed to save data to file\n") 
else 
    printf(1, "Saved file is %d bytes long\n", size) 
end if

9.5.1.4 load

include std/serialize.e 
public function load(sequence filename)

Restores a EUPHORIA object that has been saved to disk by dump.

9.5.1.4.1 Parameters:

filename : the name of the file to restore it from.

9.5.1.4.2 Returns:

A sequence, the first element is the result code. If the result code is 0 then it means that the function failed, otherwise the restored data is in the second element.

9.5.1.4.3 Comments:

This is used to load back data from a file created by the dump function.

9.5.1.4.4 Example :

include std/serialize.e 
sequence mydata = load(theFileName)  
if mydata[1] = 0 then 
    puts(1, "Failed to load data from file\n") 
else 
    mydata = mydata[2] -- Restored data is in second element. 
end if

9.6 Sorting

---------- Constants

---------------- ASCENDING

---------------- NORMAL_ORDER

---------------- DESCENDING

---------------- REVERSE_ORDER

---------- Routines

---------------- sort

---------------- custom_sort

---------------- sort_columns

---------------- merge

---------------- insertion_sort

9.6.1 Constants

9.6.1.1 ASCENDING

include std/sort.e 
public constant ASCENDING

ascending sort order, always the default.

When a sequence is sorted in ASCENDING order, its first element is the smallest as per the sort order and its last element is the largest

9.6.1.2 NORMAL_ORDER

include std/sort.e 
public constant NORMAL_ORDER

The normal sort order used by the custom comparison routine.

9.6.1.3 DESCENDING

include std/sort.e 
public constant DESCENDING

descending sort order, which is the reverse of ASCENDING.

9.6.1.4 REVERSE_ORDER

include std/sort.e 
public constant REVERSE_ORDER

Reverses the sense of the order returned by a custom comparison routine.

9.6.2 Routines

9.6.2.1 sort

include std/sort.e 
public function sort(sequence x, integer order = ASCENDING)

Sort the elements of a sequence into ascending order.

9.6.2.1.1 Parameters:

x : The sequence to be sorted.
order : the sort order. Default is ASCENDING.

9.6.2.1.2 Returns:

A sequence, a copy of the original sequence in ascending order

9.6.2.1.3 Comments:

The elements can be atoms or sequences.

The standard compare() routine is used to compare elements. This means that "y is greater than x" is defined by compare(y, x)=1.

This function uses the "Shell" sort algorithm. This sort is not "stable", i.e. elements that are considered equal might change position relative to each other.

9.6.2.1.4 Example 1:

constant student_ages = {18,21,16,23,17,16,20,20,19} 
sequence sorted_ages 
sorted_ages = sort( student_ages ) 
-- result is {16,16,17,18,19,20,20,21,23}

9.6.2.1.5 See Also:

compare, custom_sort

9.6.2.2 custom_sort

include std/sort.e 
public function custom_sort(integer custom_compare, sequence x, object data = {}, integer order = NORMAL_ORDER)

Sort the elements of a sequence according to a user-defined order.

9.6.2.2.1 Parameters:

custom_compare : an integer, the routine-id of the user defined routine that compares two items which appear in the sequence to sort.
x : the sequence of items to be sorted.
data : an object, either {} (no custom data, the default), an atom or a non-empty sequence.
order : an integer, either NORMAL_ORDER (the default) or REVERSE_ORDER.

9.6.2.2.2 Returns:

A sequence, a copy of the original sequence in sorted order

9.6.2.2.3 Errors:

If the user defined routine does not return according to the specifications in the Comments section below, an error will occur.

9.6.2.2.4 Comments:

If some user data is being provided, that data must be either an atom or a sequence with at least one element. NOTE only the first element is passed to the user defined comparison routine, any other elements are just ignored. The user data is not used or inspected it in any way other than passing it to the user defined routine.

The user defined routine must return an integer comparison result

a negative value if object A must appear before object B
a positive value if object B must appear before object A
0 if the order does not matter

NOTE: The meaning of the value returned by the user-defined routine is reversed when order = REVERSE_ORDER. The default is order = NORMAL_ORDER , which sorts in order returned by the custom comparison routine.

When no user data is provided, the user defined routine must accept two objects (A, B) and return just the comparison result.

When some user data is provided, the user defined routine must take three objects (A, B , data). It must return either...

an integer, which is a comparison result
a two-element sequence, in which the first element is a comparison result and the second element is the updated user data that is to be used for the next call to the user defined routine.

The elements of x can be atoms or sequences. Each time that the sort needs to compare two items in the sequence, it calls the user-defined function to determine the order.

This function uses the "Shell" sort algorithm. This sort is not "stable", i.e. elements that are considered equal might change position relative to each other.

9.6.2.2.5 Example 1:

constant students = {{"Anne",18},   {"Bob",21}, 
                     {"Chris",16},  {"Diane",23}, 
                     {"Eddy",17},   {"Freya",16}, 
                     {"George",20}, {"Heidi",20}, 
                     {"Ian",19}} 
sequence sorted_byage 
function byage(object a, object b) 
 ----- If the ages are the same, compare the names otherwise just compare ages. 
    if equal(a[2], b[2]) then 
        return compare(upper(a[1]), upper(b[1])) 
    end if 
    return compare(a[2], b[2]) 
end function 
 
sorted_byage = custom_sort( routine_id("byage"), students ) 
-- result is {{"Chris",16}, {"Freya",16}, 
--            {"Eddy",17},  {"Anne",18}, 
--            {"Ian",19},   {"George",20}, 
--            {"Heidi",20}, {"Bob",21}, 
--            {"Diane",23}} 
 
sorted_byage = custom_sort( routine_id("byage"), students,, REVERSE_ORDER ) 
-- result is {{"Diane",23}, {"Bob",21}, 
--            {"Heidi",20}, {"George",20}, 
--            {"Ian",19},   {"Anne",18}, 
--            {"Eddy",17},  {"Freya",16}, 
--            {"Chris",16}} 
--

9.6.2.2.6 Example 2:

constant students = {{"Anne","Baxter",18}, {"Bob","Palmer",21}, 
                     {"Chris","du Pont",16},{"Diane","Fry",23}, 
                     {"Eddy","Ammon",17},{"Freya","Brash",16}, 
                     {"George","Gungle",20},{"Heidi","Smith",20}, 
                     {"Ian","Sidebottom",19}} 
sequence sorted 
function colsort(object a, object b, sequence cols) 
    integer sign 
    for i = 1 to length(cols) do 
        if cols[i] < 0 then 
            sign = -1 
            cols[i] = -cols[i] 
        else 
            sign = 1 
        end if 
        if not equal(a[cols[i]], b[cols[i]]) then 
            return sign * compare(upper(a[cols[i]]), upper(b[cols[i]])) 
        end if 
    end for 
 
    return 0 
end function 
 
-- Order is age:descending, Surname, Given Name 
sequence column_order = {-3,2,1} 
sorted = custom_sort( routine_id("colsort"), students, {column_order} ) 
-- result is 
{ 
    {"Diane","Fry",23}, 
    {"Bob","Palmer",21}, 
    {"George","Gungle",20}, 
    {"Heidi","Smith",20}, 
    {"Ian","Sidebottom",19}, 
    {"Anne", "Baxter", 18 }, 
    {"Eddy","Ammon",17}, 
    {"Freya","Brash",16}, 
    {"Chris","du Pont",16} 
} 
 
sorted = custom_sort( routine_id("colsort"), students, {column_order}, REVERSE_ORDER ) 
-- result is 
{ 
    {"Chris","du Pont",16}, 
    {"Freya","Brash",16}, 
    {"Eddy","Ammon",17}, 
    {"Anne", "Baxter", 18 }, 
    {"Ian","Sidebottom",19}, 
    {"Heidi","Smith",20}, 
    {"George","Gungle",20}, 
    {"Bob","Palmer",21}, 
    {"Diane","Fry",23} 
}

9.6.2.2.7 See Also:

compare, sort

9.6.2.3 sort_columns

include std/sort.e 
public function sort_columns(sequence x, sequence column_list)

Sort the rows in a sequence according to a user-defined column order.

9.6.2.3.1 Parameters:

x : a sequence, holding the sequences to be sorted.
column_list : a list of columns indexes x is to be sorted by.

9.6.2.3.2 Returns:

A sequence, a copy of the original sequence in sorted order.

9.6.2.3.3 Comments:

x must be a sequence of sequences.

A non-existent column is treated as coming before an existing column. This allows sorting of records that are shorter than the columns in the column list.

By default, columns are sorted in ascending order. To sort in descending order, make the column number negative.

This function uses the "Shell" sort algorithm. This sort is not "stable", i.e. elements that are considered equal might change position relative to each other.

9.6.2.3.4 Example 1:

sequence dirlist 
dirlist = dir("c:\\temp") 
sequence sorted 
-- Order is Size:descending, Name 
sorted = sort_columns( dirlist, {-D_SIZE, D_NAME} )

9.6.2.3.5 See Also:

compare, sort

9.6.2.4 merge

include std/sort.e 
public function merge(sequence a, sequence b, integer compfunc = - 1, object userdata = "")

Merge two pre-sorted sequences into a single sequence.

9.6.2.4.1 Parameters:

a : a sequence, holding pre-sorted data.
b : a sequence, holding pre-sorted data.
compfunc : an integer, either -1 or the routine id of a user-defined comparision function.

9.6.2.4.2 Returns:

A sequence, consisting of a and b merged together.

9.6.2.4.3 Comments:

If a or b is not already sorted, the resulting sequence might not be sorted either.
The input sequences do not have to be the same size.
The user-defined comparision function must accept two objects and return an integer. It returns -1 if the first object must appear before the second one, and 1 if the first object must after before the second one, and 0 if the order doesn't matter.

9.6.2.4.4 Example 1:

sequence X,Y 
X = sort( {5,3,7,1,9,0} ) --> {0,1,3,5,7,9} 
Y = sort( {6,8,10,2} ) --> {2,6,8,10} 
? merge(X,Y) --> {0,1,2,3,5,6,7,8,9,10}

9.6.2.4.5 See Also:

compare, sort

9.6.2.5 insertion_sort

include std/sort.e 
public function insertion_sort(sequence s, object e = "", integer compfunc = - 1, object userdata = "")

Sort a sequence, and optionally another object together.

9.6.2.5.1 Parameters:

s : a sequence, holding data to be sorted.
e : an object. If this is an atom, it is sorted in with s. If this is a non-empty sequence then s and e are both sorted independantly using this insertion_sort function and then the results are merged and returned.
compfunc : an integer, either -1 or the routine id of a user-defined comparision function.

9.6.2.5.2 Returns:

A sequence, consisting of s and e sorted together.

9.6.2.5.3 Comments:

This routine is usually a lot faster than the standard sort when s and e are (mostly) sorted before calling the function. For example, you can use this routine to quickly add to a sorted list.
The input sequences do not have to be the same size.
The user-defined comparision function must accept two objects and return an integer. It returns -1 if the first object must appear before the second one, and 1 if the first object must after before the second one, and 0 if the order doesn't matter.

9.6.2.5.4 Example 1:

sequence X = {} 
while true do 
   newdata = get_data() 
   if compare(-1, newdata) then 
      exit 
   end if 
   X = insertion_sort(X, newdata) 
   process(new_data) 
end while

9.6.2.5.5 See Also:

compare, sort, merge

10 String Centric Routines

Locale Routines

---------- Message translation functions

---------- Time/Number Translation

---------- Constants

---------- Locale Name Translation

Regular Expressions

---------- Introduction

---------- General Use

---------- Option Constants

---------- Error Constants

---------- Create/Destroy

---------- Utility Routines

---------- Find/Match

---------- Splitting

---------- Replacement

Text Manipulation

---------- Routines

Unicode

Wildcard Matching

---------- Routines

10.1 Locale Routines

Page Contents

---------- Message translation functions

---------------- set_lang_path

---------------- get_lang_path

---------------- lang_load

---------------- set_def_lang

---------------- get_def_lang

---------------- translate

---------------- trsprintf

---------- Time/Number Translation

---------------- set

---------------- get

---------------- money

---------------- number

---------------- datetime

---------- Constants

---------------- w32_names

---------------- w32_name_canonical

---------------- posix_names

---------------- locale_canonical

---------------- platform_locale

---------- Locale Name Translation

---------------- canonical

---------------- decanonical

---------------- canon2win

10.1.1 Message translation functions

10.1.1.1 set_lang_path

include std/locale.e 
public procedure set_lang_path(object pp)

Set the language path.

10.1.1.1.1 Parameters:

pp : an object, either an actual path or an atom.

10.1.1.1.2 Comments:

When the language path is not set, and it is unset by default, set() does not load any language file.

10.1.1.1.3 See Also:

10.1.1.2 get_lang_path

include std/locale.e 
public function get_lang_path()

Get the language path.

10.1.1.2.1 Returns:

An object, the current language path.

10.1.1.2.2 See Also:

get_lang_path

10.1.1.3 lang_load

include std/locale.e 
public function lang_load(sequence filename)

Load a language file.

10.1.1.3.1 Parameters:

filename : a sequence, the name of the file to load. If no file extension is supplied, then ".lng" is used.

10.1.1.3.2 Returns:

A language map, if successful. This is to be used when calling translate().

If the load fails it returns a zero.

10.1.1.3.3 Comments:

The language file must be made of lines which are either comments, empty lines or translations. Note that leading whitespace is ignored on all lines except continuation lines.

Comments are lines that begin with a # character and extend to the end of the line.
Empty Lines are ignored.
Translations have two forms ...

keyword translation_text

In which the 'keyword' is a word that must not have any spaces in it.

keyphrase = translation_text

In which the 'keyphrase' is anything up to the first '=' symbol.

It is possible to have the translation text span multiple lines. You do this by having '&' as the last character of the line. These are placed by newline characters when loading.

10.1.1.3.4 Example:

# Example translation file 
# 
 
 
hello Hola 
world Mundo 
greeting %s, %s! 
 
help text = & 
This is an example of some & 
translation text that spans & 
multiple lines. 
 
# End of example PO #2

10.1.1.3.5 See Also:

translate

10.1.1.4 set_def_lang

include std/locale.e 
public procedure set_def_lang(object langmap)

Sets the default language (translation) map

10.1.1.4.1 Parameters:

langmap : A value returned by lang_load(), or zero to remove any default map.

10.1.1.4.2 Example:

  set_def_lang( lang_load("appmsgs") )

10.1.1.5 get_def_lang

include std/locale.e 
public function get_def_lang()

Gets the default language (translation) map

10.1.1.5.1 Parameters:

none.

10.1.1.5.2 Returns:

An object, a language map, or zero if there is no default language map yet.

10.1.1.5.3 Example:

  object langmap = get_def_lang()

10.1.1.6 translate

include std/locale.e 
public function translate(sequence word, object langmap = 0, object defval = "", integer mode = 0)

Translates a word, using the current language file.

10.1.1.6.1 Parameters:

word : a sequence, the word to translate.
langmap : Either a value returned by lang_load() or zero to use the default language map
defval : a object. The value to return if the word cannot be translated. Default is "". If defval is PINF then the word is returned if it can't be translated.
mode : an integer. If zero (the default) it uses word as the keyword and returns the translation text. If not zero it uses word as the translation and returns the keyword.

10.1.1.6.2 Returns:

A sequence, the value associated with word , or defval if there is no association.

10.1.1.6.3 Example 1:

sequence newword 
newword = translate(msgtext) 
if length(msgtext) = 0 then 
   error_message(msgtext) 
else 
   error_message(newword) 
end if

10.1.1.6.4 Example 2:

error_message(translate(msgtext, , PINF))

10.1.1.6.5 See Also:

set, lang_load

10.1.1.7 trsprintf

include std/locale.e 
public function trsprintf(sequence fmt, sequence data, object langmap = 0)

Returns a formatted string with automatic translation performed on the parameters.

10.1.1.7.1 Parameters:

fmt : A sequence. Contains the formatting string. see printf() for details.
data : A sequence. Contains the data that goes into the formatted result. see printf for details.
langmap : An object. Either 0 (the default) to use the default language maps, or the result returned from lang_load() to specify a particular language map.

10.1.1.7.2 Returns:

A sequence, the formatted result.

10.1.1.7.3 Comments:

This works very much like the sprintf() function. The difference is that the fmt sequence and sequences contained in the data parameter are translated before passing them to sprintf. If an item has no translation, it remains unchanged.

Further more, after the translation pass, if the result text begins with "__", the "__" is removed. This method can be used when you do not want an item to be translated.

10.1.1.7.4 Examples:

-- Assuming a language has been loaded and 
--   "greeting" translates as '%s %s, %s' 
--   "hello"  translates as "G'day" 
--   "how are you today" translates as "How's the family?" 
sequence UserName = "Bob" 
sequence result = trsprintf( "greeting", {"hello", "__" & UserName, "how are you today"}) 
   --> "G'day Bob, How's the family?"

10.1.2 Time/Number Translation

10.1.2.1 set

include std/locale.e 
public function set(sequence new_locale)

Set the computer locale, and possibly load appropriate translation file.

10.1.2.1.1 Parameters:

new_locale : a sequence representing a new locale.

10.1.2.1.2 Returns:

An integer, either 0 on failure or 1 on success.

10.1.2.1.3 Comments:

Locale strings have the following format: xx_YY or xx_YY.xyz . The xx part refers to a culture, or main language/script. For instance, "en" refers to English, "de" refers to German, and so on. For some language, a script may be specified, like in "mn_Cyrl_MN" (mongolian in cyrillic transcription).

The YY part refers to a subculture, or variant, of the main language. For instance, "fr_FR" refers to metropolitan France, while "fr_BE" refers to the variant spoken in Wallonie, the French speaking region of Belgium.

The optional .xyz part specifies an encoding, like .utf8 or .1252 . This is required in some cases.

10.1.2.2 get

include std/locale.e 
public function get()

Get current locale string

10.1.2.2.1 Returns:

A sequence, a locale string.

10.1.2.2.2 See Also:

upper, proper, set_encoding_properties, get_encoding_properties

10.1.2.3 money

include std/locale.e 
public function money(object amount)

Converts an amount of currency into a string representing that amount.

10.1.2.3.1 Parameters:

amount : an atom, the value to write out.

10.1.2.3.2 Returns:

A sequence, a string that writes out amount of current currency.

10.1.2.3.3 Example 1:

-- Assuming an en_US locale 
? money(1020.5) -- returns"$1,020.50"

10.1.2.3.4 See Also:

set, number

10.1.2.4 number

include std/locale.e 
public function number(object num)

Converts a number into a string representing that number.

10.1.2.4.1 Parameters:

num : an atom, the value to write out.

10.1.2.4.2 Returns:

A sequence, a string that writes out num.

10.1.2.4.3 Example 1:

-- Assuming an en_US locale 
? number(1020.5) -- returns "1,020.50"

10.1.2.4.4 See Also:

set, money

10.1.2.5 datetime

include std/locale.e 
public function datetime(sequence fmt, dt :datetime dtm)

Formats a date according to current locale.

10.1.2.5.1 Parameters:

fmt : A format string, as described in datetime: format
dtm : the datetime to write out.

10.1.2.5.2 Returns:

A sequence, representing the formatted date.

10.1.2.5.3 Example 1:

? datetime("Today is a %A",dt:now())

10.1.2.5.4 See Also:

datetime:format

10.1.3 Constants

Win32 locale names:

af-ZA	sq-AL	gsw-FR	am-ET	ar-DZ	ar-BH	ar-EG	ar-IQ
ar-JO	ar-KW	ar-LB	ar-LY	ar-MA	ar-OM	ar-QA	ar-SA
ar-SY	ar-TN	ar-AE	ar-YE	hy-AM	as-IN	az-Cyrl-AZ	az-Latn-AZ
ba-RU	eu-ES	be-BY	bn-IN	bs-Cyrl-BA	bs-Latn-BA	br-FR	bg-BG
ca-ES	zh-HK	zh-MO	zh-CN	zh-SG	zh-TW	co-FR	hr-BA
hr-HR	cs-CZ	da-DK	prs-AF	dv-MV	nl-BE	nl-NL	en-AU
en-BZ	en-CA	en-029	en-IN	en-IE	en-JM	en-MY	en-NZ
en-PH	en-SG	en-ZA	en-TT	en-GB	en-US	en-ZW	et-EE
fo-FO	fil-PH	fi-FI	fr-BE	fr-CA	fr-FR	fr-LU	fr-MC
fr-CH	fy-NL	gl-ES	ka-GE	de-AT	de-DE	de-LI	de-LU
de-CH	el-GR	kl-GL	gu-IN	ha-Latn-NG	he-IL	hi-IN	hu-HU
is-IS	ig-NG	id-ID	iu-Latn-CA	iu-Cans-CA	ga-IE	it-IT	it-CH
ja-JP	kn-IN	kk-KZ	kh-KH	qut-GT	rw-RW	kok-IN	ko-KR
ky-KG	lo-LA	lv-LV	lt-LT	dsb-DE	lb-LU	mk-MK	ms-BN
ms-MY	ml-IN	mt-MT	mi-NZ	arn-CL	mr-IN	moh-CA	mn-Cyrl-MN
mn-Mong-CN	ne-IN	ne-NP	nb-NO	nn-NO	oc-FR	or-IN	ps-AF
fa-IR	pl-PL	pt-BR	pt-PT	pa-IN	quz-BO	quz-EC	quz-PE
ro-RO	rm-CH	ru-RU	smn-FI	smj-NO	smj-SE	se-FI	se-NO
se-SE	sms-FI	sma-NO	sma-SE	sa-IN	sr-Cyrl-BA	sr-Latn-BA	sr-Cyrl-CS
sr-Latn-CS	ns-ZA	tn-ZA	si-LK	sk-SK	sl-SI	es-AR	es-BO
es-CL	es-CO	es-CR	es-DO	es-EC	es-SV	es-GT	es-HN
es-MX	es-NI	es-PA	es-PY	es-PE	es-PR	es-ES	es-ES_tradnl
es-US	es-UY	es-VE	sw-KE	sv-FI	sv-SE	syr-SY	tg-Cyrl-TJ
tmz-Latn-DZ	ta-IN	tt-RU	te-IN	th-TH	bo-BT	bo-CN	tr-TR
tk-TM	ug-CN	uk-UA	wen-DE	tr-IN	ur-PK	uz-Cyrl-UZ	uz-Latn-UZ
vi-VN	cy-GB	wo-SN	xh-ZA	sah-RU	ii-CN	yo-NG	zu-ZA

10.1.3.1 w32_names

include std/localeconv.e 
public constant w32_names

10.1.3.2 w32_name_canonical

include std/localeconv.e 
public constant w32_name_canonical

Canonical locale names for WIN32:

Afrikaans_South Africa	Afrikaans_South Africa	Afrikaans_South Africa
Afrikaans_South Africa	Afrikaans_South Africa	Afrikaans_South Africa
Afrikaans_South Africa	Afrikaans_South Africa	Afrikaans_South Africa
Afrikaans_South Africa	Afrikaans_South Africa	Afrikaans_South Africa
Afrikaans_South Africa	Afrikaans_South Africa	Afrikaans_South Africa
Afrikaans_South Africa	Afrikaans_South Africa	Afrikaans_South Africa
Afrikaans_South Africa	Afrikaans_South Africa	Afrikaans_South Africa
Afrikaans_South Africa	Afrikaans_South Africa	Afrikaans_South Africa
Basque_Spain	Basque_Spain	Belarusian_Belarus
Belarusian_Belarus	Belarusian_Belarus	Belarusian_Belarus
Belarusian_Belarus	Belarusian_Belarus	Catalan_Spain
Catalan_Spain	Catalan_Spain	Catalan_Spain
Catalan_Spain	Catalan_Spain	Catalan_Spain
Catalan_Spain	Catalan_Spain	Catalan_Spain
Danish_Denmark	Danish_Denmark	Danish_Denmark
Danish_Denmark	Danish_Denmark	English_Australia
English_United States	English_United States	English_United States
English_United States	English_United States	English_United States
English_United States	English_United States	English_United States
English_United States	English_United States	English_United States
English_United States	English_United States	English_United States
English_United States	English_United States	English_United States
Finnish_Finland	French_France	French_France
French_France	French_France	French_France
French_France	French_France	French_France
French_France	French_France	French_France
French_France	French_France	French_France
French_France	French_France	French_France
French_France	French_France	French_France
Hungarian_Hungary	Hungarian_Hungary	Hungarian_Hungary
Hungarian_Hungary	Hungarian_Hungary	Hungarian_Hungary
Hungarian_Hungary	Italian_Italy	Italian_Italy
Italian_Italy	Italian_Italy	Italian_Italy
Italian_Italy	Italian_Italy	Italian_Italy
Italian_Italy	Italian_Italy	Italian_Italy
Italian_Italy	Italian_Italy	Italian_Italy
Italian_Italy	Italian_Italy	Italian_Italy
Italian_Italy	Italian_Italy	Italian_Italy
Italian_Italy	Italian_Italy	Italian_Italy
Italian_Italy	Italian_Italy	Italian_Italy
Italian_Italy	Italian_Italy	Italian_Italy
Italian_Italy	Italian_Italy	Italian_Italy
Italian_Italy	Italian_Italy	Italian_Italy
Italian_Italy	Italian_Italy	Italian_Italy
Italian_Italy	Italian_Italy	Italian_Italy
Italian_Italy	Romanian_Romania	Romanian_Romania
Russian_Russia	Russian_Russia	Russian_Russia
Russian_Russia	Serbian (Cyrillic)_Serbia	Serbian (Cyrillic)_Serbia
Serbian (Cyrillic)_Serbia	Serbian (Cyrillic)_Serbia	Serbian (Cyrillic)_Serbia
Serbian (Cyrillic)_Serbia	Serbian (Cyrillic)_Serbia	Serbian (Cyrillic)_Serbia
Serbian (Cyrillic)_Serbia	Serbian (Cyrillic)_Serbia	Serbian (Cyrillic)_Serbia
Serbian (Cyrillic)_Serbia	Serbian (Cyrillic)_Serbia	Serbian (Cyrillic)_Serbia
Serbian (Cyrillic)_Serbia	Slovak_Slovakia	Estonian_Estonia
Estonian_Estonia	Estonian_Estonia	Estonian_Estonia
Estonian_Estonia	Estonian_Estonia	Estonian_Estonia
Estonian_Estonia	Estonian_Estonia	Estonian_Estonia
Estonian_Estonia	Estonian_Estonia	Estonian_Estonia
Estonian_Estonia	Estonian_Estonia	Estonian_Estonia
Estonian_Estonia	Estonian_Estonia	Estonian_Estonia
Estonian_Estonia	Estonian_Estonia	Swedish_Sweden
Swedish_Sweden	Swedish_Sweden	Swedish_Sweden
Swedish_Sweden	Swedish_Sweden	Swedish_Sweden
Swedish_Sweden	Swedish_Sweden	Swedish_Sweden
Swedish_Sweden	Swedish_Sweden	Swedish_Sweden
Swedish_Sweden	Swedish_Sweden	Ukrainian_Ukraine
Ukrainian_Ukraine	Ukrainian_Ukraine	Ukrainian_Ukraine
Ukrainian_Ukraine	Ukrainian_Ukraine	Ukrainian_Ukraine
Ukrainian_Ukraine	Ukrainian_Ukraine	Ukrainian_Ukraine
Ukrainian_Ukraine	Ukrainian_Ukraine	Ukrainian_Ukraine
Ukrainian_Ukraine

10.1.3.3 posix_names

include std/localeconv.e 
public constant posix_names

10.1.3.3.1 POSIX locale names:

af_ZA	sq_AL	gsw_FR	am_ET	ar_DZ	ar_BH	ar_EG	ar_IQ
ar_JO	ar_KW	ar_LB	ar_LY	ar_MA	ar_OM	ar_QA	ar_SA
ar_SY	ar_TN	ar_AE	ar_YE	hy_AM	as_IN	az_Cyrl_AZ	az_Latn_AZ
ba_RU	eu_ES	be_BY	bn_IN	bs_Cyrl_BA	bs_Latn_BA	br_FR	bg_BG
ca_ES	zh_HK	zh_MO	zh_CN	zh_SG	zh_TW	co_FR	hr_BA
hr_HR	cs_CZ	da_DK	prs_AF	dv_MV	nl_BE	nl_NL	en_AU
en_BZ	en_CA	en_029	en_IN	en_IE	en_JM	en_MY	en_NZ
en_PH	en_SG	en_ZA	en_TT	en_GB	en_US	en_ZW	et_EE
fo_FO	fil_PH	fi_FI	fr_BE	fr_CA	fr_FR	fr_LU	fr_MC
fr_CH	fy_NL	gl_ES	ka_GE	de_AT	de_DE	de_LI	de_LU
de_CH	el_GR	kl_GL	gu_IN	ha_Latn_NG	he_IL	hi_IN	hu_HU
is_IS	ig_NG	id_ID	iu_Latn_CA	iu_Cans_CA	ga_IE	it_IT	it_CH
ja_JP	kn_IN	kk_KZ	kh_KH	qut_GT	rw_RW	kok_IN	ko_KR
ky_KG	lo_LA	lv_LV	lt_LT	dsb_DE	lb_LU	mk_MK	ms_BN
ms_MY	ml_IN	mt_MT	mi_NZ	arn_CL	mr_IN	moh_CA	mn_Cyrl_MN
mn_Mong_CN	ne_IN	ne_NP	nb_NO	nn_NO	oc_FR	or_IN	ps_AF
fa_IR	pl_PL	pt_BR	pt_PT	pa_IN	quz_BO	quz_EC	quz_PE
ro_RO	rm_CH	ru_RU	smn_FI	smj_NO	smj_SE	se_FI	se_NO
se_SE	sms_FI	sma_NO	sma_SE	sa_IN	sr_Cyrl_BA	sr_Latn_BA	sr_Cyrl_CS
sr_Latn_CS	ns_ZA	tn_ZA	si_LK	sk_SK	sl_SI	es_AR	es_BO
es_CL	es_CO	es_CR	es_DO	es_EC	es_SV	es_GT	es_HN
es_MX	es_NI	es_PA	es_PY	es_PE	es_PR	es_ES	es_ES_tradnl
es_US	es_UY	es_VE	sw_KE	sv_FI	sv_SE	syr_SY	tg_Cyrl_TJ
tmz_Latn_DZ	ta_IN	tt_RU	te_IN	th_TH	bo_BT	bo_CN	tr_TR
tk_TM	ug_CN	uk_UA	wen_DE	tr_IN	ur_PK	uz_Cyrl_UZ	uz_Latn_UZ
vi_VN	cy_GB	wo_SN	xh_ZA	sah_RU	ii_CN	yo_NG	zu_ZA

10.1.3.4 locale_canonical

include std/localeconv.e 
public constant locale_canonical

10.1.3.5 platform_locale

include std/localeconv.e 
public constant platform_locale

10.1.4 Locale Name Translation

10.1.4.1 canonical

include std/localeconv.e 
public function canonical(sequence new_locale)

Get canonical name for a locale.

10.1.4.1.1 Parameters:

new_locale : a sequence, the string for the locale.

10.1.4.1.2 Returns:

A sequence, either the translated locale on success or new_locale on failure.

10.1.4.1.3 See Also:

get, set, decanonical

10.1.4.2 decanonical

include std/localeconv.e 
public function decanonical(sequence new_locale)

Get the translation of a locale string for current platform.

10.1.4.2.1 Parameters:

new_locale: a sequence, the string for the locale.

10.1.4.2.2 Returns:

A sequence, either the translated locale on success or new_locale on failure.

10.1.4.2.3 See Also:

get, set, canonical

10.1.4.3 canon2win

include std/localeconv.e 
public function canon2win(sequence new_locale)

TODO: document

10.2 Regular Expressions

---------- Introduction

---------- General Use

---------- Option Constants

---------------- DEFAULT

---------------- CASELESS

---------------- MULTILINE

---------------- DOTALL

---------------- EXTENDED

---------------- ANCHORED

---------------- DOLLAR_ENDONLY

---------------- EXTRA

---------------- NOTBOL

---------------- NOTEOL

---------------- UNGREEDY

---------------- NOTEMPTY

---------------- UTF8

---------------- NO_AUTO_CAPTURE

---------------- NO_UTF8_CHECK

---------------- AUTO_CALLOUT

---------------- PARTIAL

---------------- DFA_SHORTEST

---------------- DFA_RESTART

---------------- FIRSTLINE

---------------- DUPNAMES

---------------- NEWLINE_CR

---------------- NEWLINE_LF

---------------- NEWLINE_CRLF

---------------- NEWLINE_ANY

---------------- NEWLINE_ANYCRLF

---------------- BSR_ANYCRLF

---------------- BSR_UNICODE

---------------- STRING_OFFSETS

---------- Error Constants

---------------- ERROR_NOMATCH

---------------- ERROR_NULL

---------------- ERROR_BADOPTION

---------------- ERROR_BADMAGIC

---------------- ERROR_UNKNOWN_OPCODE

---------------- ERROR_UNKNOWN_NODE

---------------- ERROR_NOMEMORY

---------------- ERROR_NOSUBSTRING

---------------- ERROR_MATCHLIMIT

---------------- ERROR_CALLOUT

---------------- ERROR_BADUTF8

---------------- ERROR_BADUTF8_OFFSET

---------------- ERROR_PARTIAL

---------------- ERROR_BADPARTIAL

---------------- ERROR_INTERNAL

---------------- ERROR_BADCOUNT

---------------- ERROR_DFA_UITEM

---------------- ERROR_DFA_UCOND

---------------- ERROR_DFA_UMLIMIT

---------------- ERROR_DFA_WSSIZE

---------------- ERROR_DFA_RECURSE

---------------- ERROR_RECURSIONLIMIT

---------------- ERROR_NULLWSLIMIT

---------------- ERROR_BADNEWLINE

---------- Create/Destroy

---------------- regex

---------------- new

---------------- error_message

---------- Utility Routines

---------------- escape

---------------- get_ovector_size

---------- Find/Match

---------------- find

---------------- find_all

---------------- has_match

---------------- is_match

---------------- matches

---------------- all_matches

---------- Splitting

---------------- split

---------------- split_limit

---------- Replacement

---------------- find_replace

---------------- find_replace_limit

---------------- find_replace_callback

10.2.1 Introduction

Regular expressions in EUPHORIA are based on the PCRE (Perl Compatible Regular Expressions) library created by Philip Hazel.

This document will detail the EUPHORIA interface to Regular Expressions, not really regular expression syntax. It is a very complex subject that many books have been written on. Here are a few good resources online that can help while learning regular expressions.

EUForum Article
Perl Regular Expressions Man Page
Regular Expression Library (user supplied regular expressions for just about any task).
WikiPedia Regular Expression Article

10.2.2 General Use

Many functions take an optional options parameter. This parameter can be either a single option constant (see Option Constants, multiple option constants or'ed together into a single atom or a sequence of options, in which the function will take care of ensuring the are or'ed together correctly.

10.2.3 Option Constants

10.2.3.1 DEFAULT

include std/regex.e 
public constant DEFAULT

10.2.3.2 CASELESS

include std/regex.e 
public constant CASELESS

10.2.3.3 MULTILINE

include std/regex.e 
public constant MULTILINE

10.2.3.4 DOTALL

include std/regex.e 
public constant DOTALL

10.2.3.5 EXTENDED

include std/regex.e 
public constant EXTENDED

10.2.3.6 ANCHORED

include std/regex.e 
public constant ANCHORED

10.2.3.7 DOLLAR_ENDONLY

include std/regex.e 
public constant DOLLAR_ENDONLY

10.2.3.8 EXTRA

include std/regex.e 
public constant EXTRA

10.2.3.9 NOTBOL

include std/regex.e 
public constant NOTBOL

10.2.3.10 NOTEOL

include std/regex.e 
public constant NOTEOL

10.2.3.11 UNGREEDY

include std/regex.e 
public constant UNGREEDY

10.2.3.12 NOTEMPTY

include std/regex.e 
public constant NOTEMPTY

10.2.3.13 UTF8

include std/regex.e 
public constant UTF8

10.2.3.14 NO_AUTO_CAPTURE

include std/regex.e 
public constant NO_AUTO_CAPTURE

10.2.3.15 NO_UTF8_CHECK

include std/regex.e 
public constant NO_UTF8_CHECK

10.2.3.16 AUTO_CALLOUT

include std/regex.e 
public constant AUTO_CALLOUT

10.2.3.17 PARTIAL

include std/regex.e 
public constant PARTIAL

10.2.3.18 DFA_SHORTEST

include std/regex.e 
public constant DFA_SHORTEST

10.2.3.19 DFA_RESTART

include std/regex.e 
public constant DFA_RESTART

10.2.3.20 FIRSTLINE

include std/regex.e 
public constant FIRSTLINE

10.2.3.21 DUPNAMES

include std/regex.e 
public constant DUPNAMES

10.2.3.22 NEWLINE_CR

include std/regex.e 
public constant NEWLINE_CR

10.2.3.23 NEWLINE_LF

include std/regex.e 
public constant NEWLINE_LF

10.2.3.24 NEWLINE_CRLF

include std/regex.e 
public constant NEWLINE_CRLF

10.2.3.25 NEWLINE_ANY

include std/regex.e 
public constant NEWLINE_ANY

10.2.3.26 NEWLINE_ANYCRLF

include std/regex.e 
public constant NEWLINE_ANYCRLF

10.2.3.27 BSR_ANYCRLF

include std/regex.e 
public constant BSR_ANYCRLF

10.2.3.28 BSR_UNICODE

include std/regex.e 
public constant BSR_UNICODE

10.2.3.29 STRING_OFFSETS

include std/regex.e 
public constant STRING_OFFSETS

10.2.4 Error Constants

10.2.4.1 ERROR_NOMATCH

include std/regex.e 
public constant ERROR_NOMATCH

10.2.4.2 ERROR_NULL

include std/regex.e 
public constant ERROR_NULL

10.2.4.3 ERROR_BADOPTION

include std/regex.e 
public constant ERROR_BADOPTION

10.2.4.4 ERROR_BADMAGIC

include std/regex.e 
public constant ERROR_BADMAGIC

10.2.4.5 ERROR_UNKNOWN_OPCODE

include std/regex.e 
public constant ERROR_UNKNOWN_OPCODE

10.2.4.6 ERROR_UNKNOWN_NODE

include std/regex.e 
public constant ERROR_UNKNOWN_NODE

10.2.4.7 ERROR_NOMEMORY

include std/regex.e 
public constant ERROR_NOMEMORY

10.2.4.8 ERROR_NOSUBSTRING

include std/regex.e 
public constant ERROR_NOSUBSTRING

10.2.4.9 ERROR_MATCHLIMIT

include std/regex.e 
public constant ERROR_MATCHLIMIT

10.2.4.10 ERROR_CALLOUT

include std/regex.e 
public constant ERROR_CALLOUT

10.2.4.11 ERROR_BADUTF8

include std/regex.e 
public constant ERROR_BADUTF8

10.2.4.12 ERROR_BADUTF8_OFFSET

include std/regex.e 
public constant ERROR_BADUTF8_OFFSET

10.2.4.13 ERROR_PARTIAL

include std/regex.e 
public constant ERROR_PARTIAL

10.2.4.14 ERROR_BADPARTIAL

include std/regex.e 
public constant ERROR_BADPARTIAL

10.2.4.15 ERROR_INTERNAL

include std/regex.e 
public constant ERROR_INTERNAL

10.2.4.16 ERROR_BADCOUNT

include std/regex.e 
public constant ERROR_BADCOUNT

10.2.4.17 ERROR_DFA_UITEM

include std/regex.e 
public constant ERROR_DFA_UITEM

10.2.4.18 ERROR_DFA_UCOND

include std/regex.e 
public constant ERROR_DFA_UCOND

10.2.4.19 ERROR_DFA_UMLIMIT

include std/regex.e 
public constant ERROR_DFA_UMLIMIT

10.2.4.20 ERROR_DFA_WSSIZE

include std/regex.e 
public constant ERROR_DFA_WSSIZE

10.2.4.21 ERROR_DFA_RECURSE

include std/regex.e 
public constant ERROR_DFA_RECURSE

10.2.4.22 ERROR_RECURSIONLIMIT

include std/regex.e 
public constant ERROR_RECURSIONLIMIT

10.2.4.23 ERROR_NULLWSLIMIT

include std/regex.e 
public constant ERROR_NULLWSLIMIT

10.2.4.24 ERROR_BADNEWLINE

include std/regex.e 
public constant ERROR_BADNEWLINE

10.2.5 Create/Destroy

10.2.5.1 regex

include std/regex.e 
public type regex(object o)

Regular expression type

10.2.5.2 new

include std/regex.e 
public function new(sequence pattern, object options = DEFAULT)

Return an allocated regular expression

10.2.5.2.1 Parameters:

pattern : a sequence representing a human readable regular expression
options : defaults to DEFAULT. See Option Constants.

10.2.5.2.2 Returns:

A regex, which other regular expression routines can work on or an atom to indicate an error. If an error, you can call error_message to get a detailed error message.

10.2.5.2.3 Comments:

This is the only routine that accepts a human readable regular expression. The string is compiled and a regex is returned. Analyzing and compiling a regular expression is a costly operation and should not be done more than necessary. For instance, if your application looks for an email address among text frequently, you should create the regular expression as a constant accessible to your source code and any files that may use it, thus, the regular expression is analyzed and compiled only once per run of your application.

-- Bad Example 
  
while sequence(line) do 
    re:regex proper_name = re:new("[A-Z][a-z]+ [A-Z][a-z]+") 
    if re:match(line) then 
        -- code 
    end if 
end while

-- Good Example 
constant re_proper_name = re:new("[A-Z][a-z]+ [A-Z][a-z]+") 
while sequence(line) do 
    if re:match(line) then 
        -- code 
    end if 
end while

10.2.5.2.4 Example 1:

include regex.e as re 
re:regex number = re:new("[0-9]+")

10.2.5.2.5 Note:

For simple finds, matches or even simple wildcard matches, the built-in EUPHORIA routines find, match and wildcard_match are often times easier to use and a little faster. Regular expressions are faster for complex searching/matching.

10.2.5.2.6 See Also:

error_message, find , find_all

10.2.5.3 error_message

include std/regex.e 
public function error_message(object re)

If new() returns an atom, this function will return a text error message as to the reason.

10.2.5.3.1 Parameters:

re: Regular expression to get the error message from

10.2.5.3.2 Returns:

An atom (0) when no error message exists, otherwise a sequence describing the error.

10.2.5.3.3 Example 1:

object r = regex:new("[A-Z[a-z]*") 
if atom(r) then 
  printf(1, "Regex failed to compile: %s\n", { regex:error_message(r) }) 
end if

10.2.6 Utility Routines

10.2.6.1 escape

include std/regex.e 
public function escape(sequence s)

Escape special regular expression characters that may be entered into a search string from user input.

10.2.6.1.1 Notes:

10.2.6.1.2 Special regex characters are:

. \ + * ? [ ^ ] $ ( ) { } = ! < > | : -

10.2.6.1.3 Parameters:

s: string sequence to escape

10.2.6.1.4 Returns:

An escaped sequence representing s.

10.2.6.1.5 Example 1:

sequence search_s = escape("Payroll is $***15.00") 
-- search_s = "Payroll is \\$\\*\\*\\*15\\.00"

10.2.6.2 get_ovector_size

include std/regex.e 
public function get_ovector_size(regex ex, integer maxsize = 0)

Returns the number of capturing subpatterns (the ovector size) for a regex

10.2.6.2.1 Parameters:

ex : a regex
maxsize : optional maximum number of named groups to get data from

10.2.6.2.2 Returns:

An integer

10.2.7 Find/Match

10.2.7.1 find

include std/regex.e 
public function find(regex re, sequence haystack, integer from = 1, object options = DEFAULT, integer size = get_ovector_size(re, 30))

Find the first match of re in haystack. You can optionally start at the position from.

10.2.7.1.1 Parameters:

re : a regex for a subject to be matched against
haystack : a string in which to searched
from : an integer setting the starting position to begin searching from. Defaults to 1
options : defaults to DEFAULT. See Option Constants.
size : internal (how large an array the C backend should allocate). Defaults to 90, in rare cases this number may need to be increased in order to accomodate complex regex expressions.

10.2.7.1.2 Returns:

An object, which is either an atom of 0, meaning nothing found or a sequence of matched pairs. For the explanation of the returned sequence, please see the first example.

10.2.7.1.3 Example 1:

r = re:new("([A-Za-z]+) ([0-9]+)") -- John 20 or Jane 45 
object result = re:find(r, "John 20") 
 
-- The return value will be: 
-- { 
--    { 1, 7 }, -- Total match 
--    { 1, 4 }, -- First grouping "John" ([A-Za-z]+) 
--    { 6, 7 }  -- Second grouping "20" ([0-9]+) 
-- }

10.2.7.2 find_all

include std/regex.e 
public function find_all(regex re, sequence haystack, integer from = 1, object options = DEFAULT)

Find all occurrences of re in haystack optionally starting at the sequence position from.

10.2.7.2.1 Parameters:

re : a regex for a subject to be matched against
haystack : a string in which to searched
from : an integer setting the starting position to begin searching from. Defaults to 1
options : defaults to DEFAULT. See Option Constants.

10.2.7.2.2 Returns:

A sequence, of matches. Please see find for a detailed description of the return value.

10.2.7.2.3 Example 1:

constant re_number = re:new("[0-9]+") 
object matches = re:find_all(re_number, "10 20 30") 
 
-- matches is: 
-- { 
--     {1, 2}, 
--     {4, 5}, 
--     {7, 8} 
-- }

10.2.7.3 has_match

include std/regex.e 
public function has_match(regex re, sequence haystack, integer from = 1, object options = DEFAULT)

Determine if re matches any portion of haystack.

10.2.7.3.1 Parameters:

re : a regex for a subject to be matched against
haystack : a string in which to searched
from : an integer setting the starting position to begin searching from. Defaults to 1
options : defaults to DEFAULT. See Option Constants.

10.2.7.3.2 Returns:

An atom, 1 if re matches any portion of haystack or 0 if not.

10.2.7.4 is_match

include std/regex.e 
public function is_match(regex re, sequence haystack, integer from = 1, object options = DEFAULT)

Determine if the entire haystack matches re.

10.2.7.4.1 Parameters:

re : a regex for a subject to be matched against
haystack : a string in which to searched
from : an integer setting the starting position to begin searching from. Defaults to 1
options : defaults to DEFAULT. See Option Constants.

10.2.7.4.2 Returns:

An atom, 1 if re matches the entire haystack or 0 if not.

10.2.7.5 matches

include std/regex.e 
public function matches(regex re, sequence haystack, integer from = 1, object options = DEFAULT)

Get the matched text only.

10.2.7.5.1 Parameters:

re : a regex for a subject to be matched against
haystack : a string in which to searched
from : an integer setting the starting position to begin searching from. Defaults to 1
options : defaults to DEFAULT. See Option Constants.

10.2.7.5.2 Returns:

Returns a sequence, of strings, the first being the entire match and subsequent items being each of the captured groups. The size of the sequence is the number of groups in the expression plus one (for the entire match).

If options contains the bit STRING_OFFSETS, then the result is different. For each item, a sequence is returned containing the matched text, the starting index in haystack and the ending index in haystack.

10.2.7.5.3 Example 1:

constant re_name = re:new("([A-Z][a-z]+) ([A-Z][a-z]+)") 
 
object matches = re:matches(re_name, "John Doe and Jane Doe") 
-- matches is: 
-- { 
--   "John Doe", -- full match data 
--   "John",     -- first group 
--   "Doe"       -- second group 
-- } 
 
matches = re:matches(re_name, "John Doe and Jane Doe", STRING_OFFSETS) 
-- matches is: 
-- { 
--   { "John Doe", 1, 8 }, -- full match data 
--   { "John",     1, 4 }, -- first group 
--   { "Doe",      6, 8 }  -- second group 
-- }

10.2.7.5.4 See Also:

all_matches

10.2.7.6 all_matches

include std/regex.e 
public function all_matches(regex re, sequence haystack, integer from = 1, object options = DEFAULT)

Get the text of all matches

10.2.7.6.1 Parameters:

re : a regex for a subject to be matched against
haystack : a string in which to searched
from : an integer setting the starting position to begin searching from. Defaults to 1
options : options, defaults to DEFAULT . See Option Constants.

10.2.7.6.2 Returns:

Returns a sequence, of a sequence of strings, the first being the entire match and subsequent items being each of the captured groups. The size of the sequence is the number of groups in the expression plus one (for the entire match).

10.2.7.6.3 Example 1:

constant re_name = re:new("([A-Z][a-z]+) ([A-Z][a-z]+)") 
 
object matches = re:match_all(re_name, "John Doe and Jane Doe") 
-- matches is: 
-- { 
--   {             -- first match 
--     "John Doe", -- full match data 
--     "John",     -- first group 
--     "Doe"       -- second group 
--   }, 
--   {             -- second match 
--     "Jane Doe", -- full match data 
--     "Jane",     -- first group 
--     "Doe"       -- second group 
--   } 
-- } 
 
matches = re:match_all(re_name, "John Doe and Jane Doe") 
-- matches is: 
-- { 
--   {                         -- first match 
--     { "John Doe",  1,  8 }, -- full match data 
--     { "John",      1,  4 }, -- first group 
--     { "Doe",       6,  8 }  -- second group 
--   }, 
--   {                         -- second match 
--     { "Jane Doe", 14, 21 }, -- full match data 
--     { "Jane",     14, 17 }, -- first group 
--     { "Doe",      19, 21 }  -- second group 
--   } 
 }--

10.2.7.6.4 See Also:

matches]]

10.2.8 Splitting

10.2.8.1 split

include std/regex.e 
public function split(regex re, sequence text, integer from = 1, object options = DEFAULT)

Split a string based on a regex as a delimiter

10.2.8.1.1 Parameters:

re : a regex which will be used for matching
text : a string on which search and replace will apply
from : optional start position
options : options, defaults to DEFAULT . See Option Constants.

10.2.8.1.2 Returns:

A sequence, of string values split at the delimiter.

10.2.8.1.3 Example 1:

regex comma_space_re = re:new(`\s,`) 
sequence data = re:split(comma_space_re, "euphoria programming, source code, reference data") 
-- data is 
-- { 
--   "euphoria programming", 
--   "source code", 
--   "reference data" 
-- }

10.2.8.2 split_limit

include std/regex.e 
public function split_limit(regex re, sequence text, integer limit = 0, integer from = 1, object options = DEFAULT)

10.2.9 Replacement

10.2.9.1 find_replace

include std/regex.e 
public function find_replace(regex ex, sequence text, sequence replacement, integer from = 1, object options = DEFAULT)

Replaces all matches of a regex with the replacement text.

10.2.9.1.1 Parameters:

re : a regex which will be used for matching
text : a string on which search and replace will apply
replacement : a string, used to replace each of the full matches found
from : optional start position
options : options, defaults to DEFAULT

10.2.9.1.2 Returns:

A sequence, the modified text.

10.2.9.1.3 Special replacement operators:

\ -- Causes the next character to lose its special meaning.
\n ~ -- Inserts a 0x0A (LF) character.
\r -- Inserts a 0x0D (CR) character.
\t -- Inserts a 0x09 (TAB) character.
\1 to \9 -- Recalls stored substrings from registers (\1, \2, \3, to \9).
\0 -- Recalls entire matched pattern.
\u -- Convert next character to uppercase
\l -- Convert next character to lowercase
\U -- Convert to uppercase till \E or \e
\L -- Convert to lowercase till \E or \e
\E or \e -- Terminate a \\U or \L conversion

10.2.9.1.4 Example 1:

regex r = new(`([A-Za-z]+)\.([A-Za-z]+)`) 
sequence details = find_replace(r, "hello.txt", `Filename: \U\1\e Extension: \U\2\e`) 
-- details = "Filename: HELLO Extension: TXT"

10.2.9.2 find_replace_limit

include std/regex.e 
public function find_replace_limit(regex ex, sequence text, sequence replacement, integer limit, integer from = 1, object options = DEFAULT)

Replaces up to limit matches of ex in text .

This function is identical to find_replace except it allows you to limit the number of replacements to perform. Please see the documentation for find_replace for all the details.

10.2.9.2.1 Parameters:

re : a regex which will be used for matching
text : a string on which search and replace will apply
replacement : a string, used to replace each of the full matches found
limit : the number of matches to process
from : optional start position
options : options, defaults to DEFAULT

10.2.9.2.2 Returns:

A sequence, the modified text.

10.2.9.2.3 See Also:

find_replace

10.2.9.3 find_replace_callback

include std/regex.e 
public function find_replace_callback(regex ex, sequence text, integer rid, integer limit = 0, integer from = 1, object options = DEFAULT)

Replaces up to limit matches of ex in text with the result of a user defined callback. The callback should take one sequence which will contain a string representing the entire match and also a string for every group within the regular expression.

10.2.9.3.1 Parameters:

re : a regex which will be used for matching
text : a string on which search and replace will apply
rid : routine id to execute for each match
limit : the number of matches to process
from : optional start position
options : options, defaults to DEFAULT

10.2.9.3.2 Returns:

A sequence, the modified text.

10.2.9.3.3 Example 1:

function my_convert(sequence params) 
    switch params[1] do 
        case "1" then  
            return "one " 
        case "2" then 
            return "two " 
        case else 
            return "unknown " 
    end switch 
end function 
 
regex r = re:new(`\d`) 
sequence result = re:find_replace_callback(r, "125", routine_id("my_convert")) 
-- result = "one two unknown "

10.3 Text Manipulation

Page Contents

---------- Routines

---------------- sprintf

---------------- sprint

---------------- trim_head

---------------- trim_tail

---------------- trim

---------------- set_encoding_properties

---------------- get_encoding_properties

---------------- lower

---------------- upper

---------------- proper

---------------- keyvalues

---------------- escape

---------------- quote

---------------- dequote

---------------- format

---------------- get_text

10.3.1 Routines

10.3.1.1 sprintf

<built-in> function sprintf(sequence format, object values)

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.

10.3.1.1.1 Parameters:

format : a sequence, the text to print. This text may contain format specifiers.
values : usually, a sequence of values. It should have as many elements as format specifiers in format, as these values will be substituted to the specifiers.

10.3.1.1.2 Returns:

A sequence, of printable characters, representing format with the values in values spliced in.

10.3.1.1.3 Comments:

printf(fn, st, x) is equivalent to puts(fn, sprintf(st, x)).

Some typical uses of sprintf() are:

Converting numbers to strings.
Creating strings to pass to system().
Creating formatted error messages that can be passed to a common error message handler.

10.3.1.1.4 Example 1:

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

10.3.1.1.5 See Also:

printf, sprint, format

10.3.1.2 sprint

include std/text.e 
public function sprint(object x)

Returns the representation of any EUPHORIA object as a string of characters.

10.3.1.2.1 Parameters:

x : Any EUPHORIA object.

10.3.1.2.2 Returns:

A sequence, a string representation of x.

10.3.1.2.3 Comments:

This is exactly the same as print(fn, x), except that the output is returned as a sequence of characters, rather than being sent to a file or device. x can be any EUPHORIA object.

The atoms contained within x will be displayed to a maximum of 10 significant digits, just as with print().

10.3.1.2.4 Example 1:

s = sprint(12345) 
-- s is "12345"

10.3.1.2.5 Example 2:

s = sprint({10,20,30}+5) 
-- s is "{15,25,35}"

10.3.1.2.6 See Also:

sprintf, printf

10.3.1.3 trim_head

include std/text.e 
public function trim_head(sequence source, object what = " \t\r\n", integer ret_index = 0)

Trim all items in the supplied set from the leftmost (start or head) of a sequence.

10.3.1.3.1 Parameters:

source : the sequence to trim.
what : the set of item to trim from source (defaults to " \t\r\n").
ret_index : If zero (the default) returns the trimmed sequence, otherwise it returns the index of the leftmost item not in what.

10.3.1.3.2 Returns:

A sequence, if ret_index is zero, which is the trimmed version of source
A integer, if ret_index is not zero, which is index of the leftmost element in source that is not in what.

10.3.1.3.3 Example 1:

object s 
s = trim_head("\r\nSentence read from a file\r\n", "\r\n") 
-- s is "Sentence read from a file\r\n" 
s = trim_head("\r\nSentence read from a file\r\n", "\r\n", TRUE) 
-- s is 3

10.3.1.3.4 See Also:

trim_tail, trim, pad_head

10.3.1.4 trim_tail

include std/text.e 
public function trim_tail(sequence source, object what = " \t\r\n", integer ret_index = 0)

Trim all items in the supplied set from the rightmost (end or tail) of a sequence.

10.3.1.4.1 Parameters:

source : the sequence to trim.
what : the set of item to trim from source (defaults to " \t\r\n").
ret_index : If zero (the default) returns the trimmed sequence, otherwise it returns the index of the rightmost item not in what.

10.3.1.4.2 Returns:

A sequence, if ret_index is zero, which is the trimmed version of source
A integer, if ret_index is not zero, which is index of the rightmost element in source that is not in what.

10.3.1.4.3 Example 1:

object s 
s = trim_tail("\r\nSentence read from a file\r\n", "\r\n") 
-- s is "\r\nSentence read from a file" 
s = trim_tail("\r\nSentence read from a file\r\n", "\r\n", TRUE) 
-- s is 27

10.3.1.4.4 See Also:

trim_head, trim, pad_tail

10.3.1.5 trim

include std/text.e 
public function trim(sequence source, object what = " \t\r\n", integer ret_index = 0)

Trim all items in the supplied set from both the left end (head/start) and right end (tail/end) of a sequence.

10.3.1.5.1 Parameters:

source : the sequence to trim.
what : the set of item to trim from source (defaults to " \t\r\n").
ret_index : If zero (the default) returns the trimmed sequence, otherwise it returns a 2-element sequence containing the index of the leftmost item and rightmost item not in what.

10.3.1.5.2 Returns:

A sequence, if ret_index is zero, which is the trimmed version of source
A 2-element sequence, if ret_index is not zero, in the form {left_index, right_index}.

10.3.1.5.3 Example 1:

object s 
s = trim("\r\nSentence read from a file\r\n", "\r\n") 
-- s is "Sentence read from a file" 
s = trim("\r\nSentence read from a file\r\n", "\r\n", TRUE) 
-- s is {3,27}

10.3.1.5.4 See Also:

trim_head, trim_tail

10.3.1.6 set_encoding_properties

include std/text.e 
public procedure set_encoding_properties(sequence en = "", sequence lc = "", sequence uc = "")

Sets the table of lowercase and uppercase characters that is used by lower and upper

10.3.1.6.1 Parameters:

en : The name of the encoding represented by these character sets
lc : The set of lowercase characters
uc : The set of upper case characters

10.3.1.6.2 Comments:

lc and uc must be the same length.
If no parameters are given, the default ASCII table is set.

10.3.1.6.3 Example 1:

set_encoding_properties( "Elvish", "aeiouy", "AEIOUY")

10.3.1.6.4 Example 1:

set_encoding_properties( "1251") -- Loads a predefined code page.

10.3.1.6.5 See Also:

lower, upper, get_encoding_properties

10.3.1.7 get_encoding_properties

include std/text.e 
public function get_encoding_properties()

Gets the table of lowercase and uppercase characters that is used by lower and upper

10.3.1.7.1 Parameters:

none

10.3.1.7.2 Returns:

A sequence, containing three items.
{Encoding_Name, LowerCase_Set, UpperCase_Set}

10.3.1.7.3 Example 1:

encode_sets = get_encoding_properties()

10.3.1.7.4 See Also:

lower, upper, set_encoding_properties

10.3.1.8 lower

include std/text.e 
public function lower(object x)

Convert an atom or sequence to lower case.

10.3.1.8.1 Parameters:

x : Any EUPHORIA object.

10.3.1.8.2 Returns:

A sequence, the lowercase version of x

10.3.1.8.3 Comments:

For Windows systems, this uses the current code page for conversion
For non-Windows, this only works on ASCII characters. It alters characters in the 'a'..'z' range. If you need to do case conversion with other encodings use the set_encoding_properties first.
x may be a sequence of any shape, all atoms of which will be acted upon.

WARNING, When using ASCII encoding, this can also affects floating point numbers in the range 65 to 90.

10.3.1.8.4 Example 1:

s = lower("EUPHORIA") 
-- s is "euphoria" 
 
a = lower('B') 
-- a is 'b' 
 
s = lower({"EUPHORIA", "Programming"}) 
-- s is {"euphoria", "programming"}

10.3.1.8.5 See Also:

10.3.1.9 upper

include std/text.e 
public function upper(object x)

Convert an atom or sequence to upper case.

10.3.1.9.1 Parameters:

x : Any EUPHORIA object.

10.3.1.9.2 Returns:

A sequence, the uppercase version of x

10.3.1.9.3 Comments:

For Windows systems, this uses the current code page for conversion
For non-Windows, this only works on ASCII characters. It alters characters in the 'a'..'z' range. If you need to do case conversion with other encodings use the set_encoding_properties first.
x may be a sequence of any shape, all atoms of which will be acted upon.

WARNING, When using ASCII encoding, this can also affects floating point numbers in the range 97 to 122.

10.3.1.9.4 Example 1:

s = upper("EUPHORIA") 
-- s is "EUPHORIA" 
 
a = upper('b') 
-- a is 'B' 
 
s = upper({"EUPHORIA", "Programming"}) 
-- s is {"EUPHORIA", "PROGRAMMING"}

10.3.1.9.5 See Also:

lower, proper, set_encoding_properties, get_encoding_properties

10.3.1.10 proper

include std/text.e 
public function proper(sequence x)

Convert a text sequence to capitalized words.

10.3.1.10.1 Parameters:

x : A text sequence.

10.3.1.10.2 Returns:

A sequence, the Capitalized Version of x

10.3.1.10.3 Comments:

A text sequence is one in which all elements are either characters or text sequences. This means that if a non-character is found in the input, it is not converted. However this rule only applies to elements on the same level, meaning that sub-sequences could be converted if they are actually text sequences.

10.3.1.10.4 Example 1:

s = proper("euphoria programming language") 
-- s is "EUPHORIA Programming Language" 
s = proper("EUPHORIA PROGRAMMING LANGUAGE") 
-- s is "EUPHORIA Programming Language" 
s = proper({"EUPHORIA PROGRAMMING", "language", "rapid dEPLOYMENT", "sOfTwArE"}) 
-- s is {"EUPHORIA Programming", "Language", "Rapid Deployment", "Software"} 
s = proper({'a', 'b', 'c'}) 
-- s is {'A', 'b', c'} -- "Abc" 
s = proper({'a', 'b', 'c', 3.1472}) 
-- s is {'a', 'b', c', 3.1472} -- Unchanged because it contains a non-character. 
s = proper({"abc", 3.1472}) 
-- s is {"Abc", 3.1472} -- The embedded text sequence is converted.

10.3.1.10.5 See Also:

lower upper

10.3.1.11 keyvalues

include std/text.e 
public function keyvalues(sequence source, object pair_delim = ";,", object kv_delim = ":=", object quotes = "\"'`", object whitespace = " \t\n\r", integer haskeys = 1)

Converts a string containing Key/Value pairs into a set of sequences, one per K/V pair.

10.3.1.11.1 Parameters:

source : a text sequence, containing the representation of the key/values.
pair_delim : an object containing a list of elements that delimit one key/value pair from the next. The defaults are semi-colon (;) and comma (,).
kv_delim : an object containing a list of elements that delimit the key from its value. The defaults are colon (:) and equal (=).
quotes : an object containing a list of elements that can be used to enclose either keys or values that contain delimiters or whitespace. The defaults are double-quote ("), single-quote (') and back-quote (`)
whitespace : an object containing a list of elements that are regarded as whitespace characters. The defaults are space, tab, new-line, and carriage-return.
haskeys : an integer containing true or false. The default is true. When true, the kv_delim values are used to separate keys from values, but when false it is assumed that each 'pair' is actually just a value.

10.3.1.11.2 Returns:

A sequence, of pairs. Each pair is in the form {key, value}.

10.3.1.11.3 Comments:

String representations of atoms are not converted, either in the key or value part, but returned as any regular string instead.

If haskeys is true, but a substring only holds what appears to be a value, the key is synthesized as p[n], where n is the number of the pair. See example #2.

By default, pairs can be delimited by either a comma or semi-colon ",;" and a key is delimited from its value by either an equal or a colon "=:". Whitespace between pairs, and between delimiters is ignored.

If you need to have one of the delimiters in the value data, enclose it in quotation marks. You can use any of single, double and back quotes, which also means you can quote quotation marks themselves. See example #3.

It is possible that the value data itself is a nested set of pairs. To do this enclose the value in parentheses. Nested sets can nested to any level. See example #4.

If a sub-list has only data values and not keys, enclose it in either braces or square brackets. See example #5. If you need to have a bracket as the first character in a data value, prefix it with a tilde. Actually a leading tilde will always just be stripped off regardless of what it prefixes. See example #6.

10.3.1.11.4 Example 1:

s = keyvalues("foo=bar, qwe=1234, asdf='contains space, comma, and equal(=)'") 
-- s is { {"foo", "bar"}, {"qwe", "1234"}, {"asdf", "contains space, comma, and equal(=)"}}

10.3.1.11.5 Example 2:

s = keyvalues("abc fgh=ijk def") 
-- s is { {"p[1]", "abc"}, {"fgh", "ijk"}, {"p[3]", "def"} }

10.3.1.11.6 Example 3:

s = keyvalues("abc=`'quoted'`") 
-- s is { {"abc", "'quoted'"} }

10.3.1.11.7 Example 4:

s = keyvalues("colors=(a=black, b=blue, c=red)") 
-- s is { {"colors", {{"a", "black"}, {"b", "blue"},{"c", "red"}}  } } 
s = keyvalues("colors=(black=[0,0,0], blue=[0,0,FF], red=[FF,0,0])") 
-- s is { {"colors", {{"black",{"0", "0", "0"}}, {"blue",{"0", "0", "FF"}},{"red", {"FF","0","0"}}}} }

10.3.1.11.8 Example 5:

s = keyvalues("colors=[black, blue, red]") 
-- s is { {"colors", { "black", "blue", "red"}  } }

10.3.1.11.9 Example 6:

s = keyvalues("colors=~[black, blue, red]") 
-- s is { {"colors", "[black, blue, red]"}  } } 
-- The following is another way to do the same. 
s = keyvalues("colors=`[black, blue, red]`") 
-- s is { {"colors", "[black, blue, red]"}  } }

10.3.1.12 escape

include std/text.e 
public function escape(sequence s, sequence what = "\"")

Escape special characters in a string

10.3.1.12.1 Parameters:

s: string to escape
what: sequence of characters to escape defaults to escaping a double quote.

10.3.1.12.2 Returns:

An escaped sequence representing s.

10.3.1.12.3 Example 1:

sequence s = escape("John \"Mc\" Doe") 
puts(1, s) 
-- output is: John \"Mc\" Doe

10.3.1.12.4 See Also:

quote

10.3.1.13 quote

include std/text.e 
public function quote(sequence text_in, object quote_pair = {"\"", "\""}, integer esc = - 1, t_text sp = "")

Return a quoted version of the first argument.

10.3.1.13.1 Parameters:

text_in : The string or set of strings to quote.
quote_pair : A sequence of two strings. The first string is the opening quote to use, and the second string is the closing quote to use. The default is {"\"", "\""} which means that the output will be enclosed by double-quotation marks.
esc : A single escape character. If this is not negative (the default), then this is used to 'escape' any embedded quote characters and 'esc' characters already in the text_in string.
sp : A list of zero or more special characters. The text_in is only quoted if it contains any of the special characters. The default is "" which means that the text_in is always quoted.

10.3.1.13.2 Returns:

A sequence, the quoted version of text_in.

10.3.1.13.3 Example 1:

-- Using the defaults. Output enclosed in double-quotes, no escapes and no specials. 
s = quote("The small man") 
-- 's' now contains '"the small man"' including the double-quote characters.

10.3.1.13.4 Example 2:

s = quote("The small man", {"(", ")"} ) 
-- 's' now contains '(the small man)'

10.3.1.13.5 Example 3:

s = quote("The (small) man", {"(", ")"}, '~' ) 
-- 's' now contains '(the ~(small~) man)'

10.3.1.13.6 Example 4:

s = quote("The (small) man", {"(", ")"}, '~', "#" ) 
-- 's' now contains "the (small) man" 
-- because the input did not contain a '#' character.

10.3.1.13.7 Example 5:

s = quote("The #1 (small) man", {"(", ")"}, '~', "#" ) 
-- 's' now contains '(the #1 ~(small~) man)' 
-- because the input did contain a '#' character.

10.3.1.13.8 Example 6:

-- input is a set of strings... 
s = quote({"a b c", "def", "g hi"},) 
-- 's' now contains three quoted strings: '"a b c"', '"def"', and '"g hi"'

10.3.1.13.9 See Also:

escape

10.3.1.14 dequote

include std/text.e 
public function dequote(object text_in, sequence quote_pairs = {{"\"", "\""}}, integer esc = - 1)

Removes 'quotation' text from the argument.

10.3.1.14.1 Parameters:

text_in : The string or set of strings to de-quote.
quote_pairs : A set of one or more sub-sequences of two strings. The first string in each sub-sequence is the opening quote to look for, and the second string is the closing quote. The default is "\"", "\"" which means that the output is 'quoted' if it is enclosed by double-quotation marks.
esc : A single escape character. If this is not negative (the default), then this is used to 'escape' any embedded occurrences of the quote characters. In which case the 'escape' character is also removed.

10.3.1.14.2 Returns:

A sequence, the original text but with 'quote' strings stripped of quotes.

10.3.1.14.3 Example 1:

-- Using the defaults. 
s = quote("\"The small man\"") 
-- 's' now contains "The small man"

10.3.1.14.4 Example 2:

-- Using the defaults. 
s = quote("(The small ?(?) man)", {{"[","]"}}, '?') 
-- 's' now contains "The small () man"

10.3.1.15 format

include std/text.e 
public function format(sequence format_pattern, object arg_list = {})

Formats a set of arguments in to a string based on a supplied pattern.

10.3.1.15.1 Parameters:

format_pattern : A sequence: the pattern string that contains zero or more tokens.
arg_list : An object: Zero or more arguments used in token replacement.

10.3.1.15.2 Returns:

A string sequence, the original format_pattern but with tokens replaced by corresponding arguments.

10.3.1.15.3 Comments:

The format_pattern string contains text and argument tokens. The resulting string is the same as the format string except that each token is replaced by an item from the argument list.

A token has the form [<Q>], where <Q> is are optional qualifier codes.

The qualifier. <Q> is a set of zero or more codes that modify the default way that the argument is used to replace the token. The default replacement method is to convert the argument to its shortest string representation and use that to replace the token. This may be modified by the following codes, which can occur in any order.

Qualifier	Usage
N	('N' is an integer) The index of the argument to use
{id}	Uses the argument that begins with "id=" where "id" is an identifier name.
%envvar%	Uses the Environment Symbol 'envar' as an argument
w	For string arguments, if capitalizes the first letter in each word
u	For string arguments, it converts it to upper case.
l	For string arguments, it converts it to lower case.
<	For numeric arguments, it left justifies it.
>	For string arguments, it right justifies it.
c	Centers the argument.
z	For numbers, it zero fills the left side.
:S	('S' is an integer) The maximum size of the resulting field. Also, if 'S' begins with '0' the field will be zero-filled if the argument is an integer
.N	('N' is an integer) The number of digits after the decimal point
+	For positive numbers, show a leading plus sign
(	For negative numbers, enclose them in parentheses
b	For numbers, causes zero to be all blanks
s	If the resulting field would otherwise be zero length, this ensures that at least one space occurs between this token's field
t	After token replacement, the resulting string up to this point is trimmed.
X	Outputs integer arguments using hexadecimal digits.
B	Outputs integer arguments using binary digits.
?	The corresponding argument is a set of two strings. This uses the first string if the previous token's argument is not the value 1 or a zero-length string, otherwise it uses the second string.
[	Does not use any argument. Outputs a left-square-bracket symbol
,X	Insert thousands separators. The <X> is the character to use. If this is a dot "." then the decimal point is rendered using a comma. Does not apply to zero-filled fields. N.B. if hex or binary output was specified, the separators are every 4 digits otherwise they are every three digits.

Clearly, certain combinations of these qualifier codes do not make sense and in those situations, the rightmost clashing code is used and the others are ignored.

Any tokens in the format that have no corresponding argument are simply removed from the result. Any arguments that are not used in the result are ignored.

Any sequence argument that is not a string will be converted to its pretty format before being used in token replacement.

If a token is going to be replaced by a zero-length argument, all white space following the token until the next non-whitespace character is not copied to the result string.

10.3.1.15.4 Examples:

format("Cannot open file '[]' - code []", {"/usr/temp/work.dat", 32}) 
-- "Cannot open file '/usr/temp/work.dat' - code 32" 
 
format("Err-[2], Cannot open file '[1]'", {"/usr/temp/work.dat", 32}) 
-- "Err-32, Cannot open file '/usr/temp/work.dat'" 
 
format("[4w] [3z:2] [6] [5l] [2z:2], [1:4]", {2009,4,21,"DAY","MONTH","of"}) 
-- "Day 21 of month 04, 2009" 
 
format("The answer is [:6.2]%", {35.22341}) 
-- "The answer is  35.22%" 
 
format("The answer is [.6]", {1.2345}) 
-- "The answer is 1.234500" 
 
format("The answer is [,,.2]", {1234.56}) 
-- "The answer is 1,234.56" 
 
format("The answer is [,..2]", {1234.56}) 
-- "The answer is 1.234,56" 
 
format("The answer is [,:.2]", {1234.56}) 
-- "The answer is 1:234.56" 
 
format("[] [?]", {5, {"cats", "cat"}}) 
-- "5 cats" 
 
format("[] [?]", {1, {"cats", "cat"}}) 
-- "1 cat" 
 
format("[<:4]", {"abcdef"}) 
-- "abcd" 
 
format("[>:4]", {"abcdef"}) 
-- "cdef" 
 
format("[>:8]", {"abcdef"}) 
-- "  abcdef" 
 
format("seq is []", {{1.2, 5, "abcdef", {3}}}) 
-- `seq is {1.2,5,"abcdef",{3}}` 
 
format("Today is [{day}], the [{date}]", {"date=10/Oct/2012", "day=Wednesday"}) 
-- "Today is Wednesday, the 10/Oct/2012"

10.3.1.15.5 See Also:

sprintf

10.3.1.16 get_text

include std/text.e 
public function get_text(integer MsgNum, sequence LocalQuals = {}, sequence DBBase = "teksto")

Get the text associated with the message number in the requested locale.

10.3.1.16.1 Parameters:

MsgNum : An integer. The message number whose text you are trying to get.
LocalQuals : A sequence. Zero or more locale codes. Default is {}.
DBBase: A sequence. The base name for the database files containing the locale text strings. The default is "teksto".

10.3.1.16.2 Returns:

A string sequence, the text associated with the message number and locale.
An integer, if not associated text can be found.

10.3.1.16.3 Comments:

This first scans the database(s) linked to the locale codes supplied.
The database name for each locale takes the format of "<DBBase>_<Locale>.edb" so if the default DBBase is used, and the locales supplied are {"enus", "enau"} the databases scanned are "teksto_enus.edb" and "teksto_enau.edb". The database table name searched is "1" with the key being the message number, and the text is the record data.
If the message is not found in these databases (or the databases don't exist) a database called "<DBBase>.edb" is searched. Again the table name is "1" but it first looks for keys with the format {<locale>,msgnum} and failing that it looks for keys in the format {"", msgnum}, and if that fails it looks for a key of just the msgnum.

10.4 Unicode

Unicode is not complete. This API will change, even in 4.1 release.

By default, EUPHORIA strings contain UCS-4 code points (characters). Page Contents

---------------- isUChar

---------------- utf_8

---------------- utf_16

---------------- utf_32

---------------- BOM_8

---------------- BOM_16be

---------------- BOM_16le

---------------- BOM_32be

---------------- BOM_32le

---------------- get_seqlen

---------------- chars_before

---------------- char_count

---------------- get_char

---------------- encode

---------------- code_length

---------------- validate

---------------- toUTF

---------------- isAlpha

---------------- isUpper

---------------- isLower

---------------- isTitle

---------------- isAlphaNum

---------------- isDigit

---------------- isNumber

---------------- isSeparator

---------------- isSpace

---------------- isLine

---------------- isParagraph

---------------- isMark

---------------- isNonSpacing

---------------- isPunctuation

---------------- isSymbol

---------------- isCurrency

---------------- isOther

---------------- isControl

---------------- isFormat

---------------- isSurrogate

---------------- isPrivate

---------------- isGraph

---------------- isPrint

---------------- isDirWhiteSpace

---------------- isDirLTR

---------------- isDirRTL

---------------- isDirStrong

---------------- isDirWeak

---------------- isDirNeutral

---------------- isDirSeparator

---------------- isBlock

---------------- isSegment

---------------- isNonBreaking

---------------- isMirroring

---------------- toLower

---------------- toUpper

---------------- toTitle

---------------- toMirror

---------------- getNumericValue

10.4.1 isUChar

include std/unicode.e 
public function isUChar(object test_char, integer is_strict = 0)

Tests if a value is a valid code point.

10.4.1.1 Parameters:

test_char : an object, the value to test.
is_strict: an integer, if non-zero then non-character code points are rejected. The default (zero) means that non-character code points are accepted.

10.4.1.1.1 Returns:

An integer. 1 means that test_char is valid and 0 means that it is not.

10.4.1.1.2 Example:

for i = 1 to length(s) do 
   if not isUChar(s[i]) then 
      return 0 -- String is not a utf-32 string. 
   end if 
end for

10.4.1.2 utf_8

include std/unicode.e 
public enum utf_8

10.4.1.3 utf_16

include std/unicode.e 
public enum utf_16

10.4.1.4 utf_32

include std/unicode.e 
public enum utf_32

10.4.1.5 BOM_8

include std/unicode.e 
public constant BOM_8

10.4.1.6 BOM_16be

include std/unicode.e 
public constant BOM_16be

10.4.1.7 BOM_16le

include std/unicode.e 
public constant BOM_16le

10.4.1.8 BOM_32be

include std/unicode.e 
public constant BOM_32be

10.4.1.9 BOM_32le

include std/unicode.e 
public constant BOM_32le

10.4.1.10 get_seqlen

include std/unicode.e 
public function get_seqlen(sequence input_string, integer from_index, integer encoding_format = utf_8)

Returns the length of an encoded UTF sequence.

10.4.1.10.1 Parameters:

input_string : a sequence. Contains a UTF encoded string.
from_index: an integer. The index of a code sequence starting point in input_string.
encoding_format: One of utf_8, utf_16, or utf_32. The default is utf_8.

10.4.1.10.2 Returns:

An integer. The number of elements in input_string, starting from from_index that form the code sequence. If 255 (0xFF) is returned, it means that either from_index was not at the start of a code sequence, or an invalid encoding_format parameter was supplied.

10.4.1.10.3 Example:

? get_seqlen("abc", 2) --> 1

10.4.1.11 chars_before

include std/unicode.e 
public function chars_before(sequence input_string, integer from_index, integer encoding_format = utf_8)

Returns the length of an encoded UTF sequence.

10.4.1.11.1 Parameters:

input_string : a sequence. Contains a UTF encoded string.
from_index: an integer. The index of a code sequence starting point in pString.
encoding_format: One of utf_8, utf_16, or utf_32. The default is utf_8.

10.4.1.11.2 Returns:

An integer. The number of UCS characters in input_string that occur before from_index. However, if from_index is invalid it returns -1, and if an invalid UTF sequence is found, it returns -2.

10.4.1.11.3 Example:

? chars_before(x"7a C2A9 E6B0B4 F09d849e", 4) --> 2

10.4.1.12 char_count

include std/unicode.e 
public function char_count(sequence input_string, integer encoding_format = utf_8)

Returns the number of UCS characters in a UTF string.

10.4.1.12.1 Parameters:

input_string : a sequence. Contains a UTF encoded string.
encoding_format: One of utf_8, utf_16, or utf_32. The default is utf_8.

10.4.1.12.2 Returns:

An integer. The number of UCS characters in input_string. However, if an invalid UTF sequence is found it returns -2.

10.4.1.12.3 Example:

? char_count(x"7a C2A9 E6B0B4 F09d849e") --> 4

10.4.1.13 get_char

include std/unicode.e 
public function get_char(sequence input_string, integer from_index, integer encoding_format = utf_8, integer is_strict = 0)

Returns the UCS character from a specific location in a UTF string

10.4.1.13.1 Parameters:

input_string : a sequence. Contains a UTF encoded string.
from_index: an integer. The index of a code sequence starting point in input_string.
encoding_format: One of utf_8, utf_16, or utf_32. The default is utf_8.
is_strict:an integer. If non-zero, then non-character code points are deemed to be invalid characters. The default is zero, which allows non-character code points.

10.4.1.13.2 Returns:

If from_index points to a valid character then a sequence is returned. The first element is the code point value of the encoded USC character in input_string at from_index, and the second element is the index of the next character in input_string .
If from_index does not point to a valid character then an integer is returned.

1 An element in the coded character is invalid.
2 In utf_8 encodings, the leading encoded byte is not valid.
3 The value of from_index is invalid or the length of input_string is too short.
4 In utf_8 encodings, the non-leading byte is not valid
5 The UCS character is not a valid one.
6 The encoding_format parameter is not valid
7 For utf_16 encodings, the leading surrogate is invalid
8 For utf_16 encodings, the trailing surrogate is invalid

10.4.1.13.3 Example:

? get_char(u"d834 dd1e", 1, utf_16) --> 0x1D11E

10.4.1.14 encode

include std/unicode.e 
public function encode(atom ucs_char, integer encoding_format = utf_8)

Returns the UTF string representation of a UCS character (code point)

10.4.1.14.1 Parameters:

ucs_char : An atom. The UCS character, also known as a code point, to encode.
encoding_format: The format at return. One of utf_8 , utf_16, or utf_32. The default is utf_8.

10.4.1.14.2 Returns:

A sequence. The UTF encoding form of the ucs_char. Note that if the UCS value supplied if not a valid character, or encoding_format is invalid, an empty sequence is returned.

10.4.1.14.3 Example:

atom G_Clef = 0x1d11e 
? encode(G_Clef, utf_8)) --> x"f09d849e"

10.4.1.15 code_length

include std/unicode.e 
public function code_length(atom ucs_char, integer encoding_format = utf_8)

Returns the length of the UTF string representation of a UCS character (code point)

10.4.1.15.1 Parameters:

ucs_char : An atom. The UCS character, also known as a code point.
encoding_format: The format at return. One of utf_8 , utf_16, or utf_32. The default is utf_8.

10.4.1.15.2 Returns:

An integer. The number of elements to make up the UTF encoded form of ucs_char. Note that if the UCS value supplied if not a valid character, or encoding_format is invalid, zero is returned.

10.4.1.15.3 Example:

atom G_Clef = 0x1d11e 
? encode(G_Clef, utf_8)) --> 4

10.4.1.16 validate

include std/unicode.e 
public function validate(object input_string, integer encoding_format = utf_8, integer is_strict = 0)

Returns the UTF string representation of a UCS character (code point)

10.4.1.16.1 Parameters:

input_string : A sequence. The UTF encoded text to validate.
encoding_format: The format of input_string. One of utf_8, utf_16, or utf_32. The default is utf_8.
is_strict:an integer. If non-zero, then non-character code points are deemed to be invalid characters. The default is zero, which allows non-character code points.

10.4.1.16.2 Returns:

An integer.

0 means that the text is valid for the given format.
n>0 is the index into input_string where the first invalid element was found.

10.4.1.16.3 Example:

? validate(x"7aE289", utf_8) --> 2

10.4.1.17 toUTF

include std/unicode.e 
public function toUTF(sequence input_string, integer source_encoding = utf_32, integer result_encoding = utf_8)

Converts the UTF encoding of the given text to another UTF encoding format.

10.4.1.17.1 Parameters:

input_string : A sequence. The UTF encoded text to convert.
source_encoding: The format of input_string. One of utf_8, utf_16, or utf_32. The default is utf_32.
result_encoding: The format of returned result. One of utf_8, utf_16, or utf_32. The default is utf_8.

10.4.1.17.2 Returns:

If input_string is not a valid UTF string, this returns the index into it where the first invalid element was found.
Otherwise it returns a sequence, which is the converted form of input_string.

10.4.1.17.3 Example:

? toUTF(x"7a C2A9 E6B0B4 F09d849e", utf_8, utf_16)) --> u"7a A9 6c34 d834 dd1e"

10.4.1.18 isAlpha

include std/ucstypes.e 
public function isAlpha(atom ucs_char)

The code point is a 'letter'.

10.4.1.18.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.18.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.19 isUpper

include std/ucstypes.e 
public function isUpper(atom ucs_char)

The code point is an uppercase 'letter'.

10.4.1.19.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.19.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.20 isLower

include std/ucstypes.e 
public function isLower(atom ucs_char)

The code point is a lowercase 'letter'.

10.4.1.20.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.20.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.21 isTitle

include std/ucstypes.e 
public function isTitle(atom ucs_char)

The code point is a Title case 'letter'.

10.4.1.21.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.21.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.22 isAlphaNum

include std/ucstypes.e 
public function isAlphaNum(atom ucs_char)

The code point is either a 'letter' or a 'digit'.

10.4.1.22.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.22.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.23 isDigit

include std/ucstypes.e 
public function isDigit(atom ucs_char)

The code point is a 'digit'.

10.4.1.23.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.23.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.24 isNumber

include std/ucstypes.e 
public function isNumber(atom ucs_char)

The code point is a 'number'. Some code points represent fractional numbers.

10.4.1.24.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.24.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.25 isSeparator

include std/ucstypes.e 
public function isSeparator(atom ucs_char)

The code point is a word separator.

10.4.1.25.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.25.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.26 isSpace

include std/ucstypes.e 
public function isSpace(atom ucs_char)

The code point is a 'space' character.

10.4.1.26.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.26.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.27 isLine

include std/ucstypes.e 
public function isLine(atom ucs_char)

The code point is a line separator.

10.4.1.27.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.27.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.28 isParagraph

include std/ucstypes.e 
public function isParagraph(atom ucs_char)

The code point is a paragraph separator

10.4.1.28.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.28.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.29 isMark

include std/ucstypes.e 
public function isMark(atom ucs_char)

The code point is a textual 'marker'.

10.4.1.29.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.29.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.30 isNonSpacing

include std/ucstypes.e 
public function isNonSpacing(atom ucs_char)

The code point is a non-spacing letter.

10.4.1.30.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.30.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.31 isPunctuation

include std/ucstypes.e 
public function isPunctuation(atom ucs_char)

The code point is a punctuation mark.

10.4.1.31.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.31.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.32 isSymbol

include std/ucstypes.e 
public function isSymbol(atom ucs_char)

The code point is a 'symbol'.

10.4.1.32.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.32.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.33 isCurrency

include std/ucstypes.e 
public function isCurrency(atom ucs_char)

The code point is a 'symbol'.

10.4.1.33.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.33.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.34 isOther

include std/ucstypes.e 
public function isOther(atom ucs_char)

The code point is a functional item, such as a control character, or private-use.

10.4.1.34.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.34.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.35 isControl

include std/ucstypes.e 
public function isControl(atom ucs_char)

The code point is a control item.

10.4.1.35.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.35.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.36 isFormat

include std/ucstypes.e 
public function isFormat(atom ucs_char)

The code point is a formatting item.

10.4.1.36.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.36.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.37 isSurrogate

include std/ucstypes.e 
public function isSurrogate(atom ucs_char)

The code point is a surrogate code.

10.4.1.37.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.37.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.38 isPrivate

include std/ucstypes.e 
public function isPrivate(atom ucs_char)

The code point is a private-use item.

10.4.1.38.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.38.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.39 isGraph

include std/ucstypes.e 
public function isGraph(atom ucs_char)

The code point is a character with a glyph.

10.4.1.39.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.39.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.40 isPrint

include std/ucstypes.e 
public function isPrint(atom ucs_char)

The code point is a character that is printable.

10.4.1.40.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.40.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.41 isDirWhiteSpace

include std/ucstypes.e 
public function isDirWhiteSpace(atom ucs_char)

The code point is a directional white space character.

10.4.1.41.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.41.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.42 isDirLTR

include std/ucstypes.e 
public function isDirLTR(atom ucs_char)

The code point is a left-to-right character.

10.4.1.42.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.42.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.43 isDirRTL

include std/ucstypes.e 
public function isDirRTL(atom ucs_char)

The code point is a right-to-left character.

10.4.1.43.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.43.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.44 isDirStrong

include std/ucstypes.e 
public function isDirStrong(atom ucs_char)

The code point has an exact directional aspect. It must be always be LtR or RtL.

10.4.1.44.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.44.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.45 isDirWeak

include std/ucstypes.e 
public function isDirWeak(atom ucs_char)

The code point has an implied directional aspect, that depends on context.

10.4.1.45.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.45.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.46 isDirNeutral

include std/ucstypes.e 
public function isDirNeutral(atom ucs_char)

The code point has no directional aspect.

10.4.1.46.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.46.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.47 isDirSeparator

include std/ucstypes.e 
public function isDirSeparator(atom ucs_char)

The code point is a directional separator.

10.4.1.47.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.47.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.48 isBlock

include std/ucstypes.e 
public function isBlock(atom ucs_char)

The code point is a block separator.

10.4.1.48.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.48.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.49 isSegment

include std/ucstypes.e 
public function isSegment(atom ucs_char)

The code point is a segment separator.

10.4.1.49.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.49.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.50 isNonBreaking

include std/ucstypes.e 
public function isNonBreaking(atom ucs_char)

The code point is a non-breaking character.

10.4.1.50.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.50.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.51 isMirroring

include std/ucstypes.e 
public function isMirroring(atom ucs_char)

The code point has a mirror (matching) character, such as parenthesis.

10.4.1.51.1 Parameters:

ucs_char: An atom. The code point to test.

10.4.1.51.2 Returns:

TRUE when ucs_char is in the set, FALSE otherwise.

10.4.1.52 toLower

include std/ucstypes.e 
public function toLower(object ucs_char)

Converts the input to lower case.

10.4.1.52.1 Parameters:

ucs_char: An object. Either a single code point to convert or a text string.

10.4.1.52.2 Returns:

The converted input.

10.4.1.53 toUpper

include std/ucstypes.e 
public function toUpper(object ucs_char)

Converts the input to upperer case.

10.4.1.53.1 Parameters:

ucs_char: An object. Either a single code point to convert or a text string.

10.4.1.53.2 Returns:

The converted input.

10.4.1.54 toTitle

include std/ucstypes.e 
public function toTitle(atom ucs_char)

Converts the input to lower case.

10.4.1.54.1 Parameters:

ucs_char: An atom. The code point to convert.

10.4.1.54.2 Returns:

The converted input.

10.4.1.55 toMirror

include std/ucstypes.e 
public function toMirror(atom ucs_char)

Gets the matching charater for the supplied code point.

10.4.1.55.1 Parameters:

ucs_char: An atom. The code point to match.

10.4.1.55.2 Returns:

If the code point has no matching value, the code point is returned, otherwise the matching (mirror) code point is returned.

10.4.1.56 getNumericValue

include std/ucstypes.e 
public function getNumericValue(atom ucs_char)

Gets the numerical value of the character.

10.4.1.56.1 Parameters:

ucs_char: An atom. The code point to convert.

10.4.1.56.2 Returns:

An atom: -1 if the code point has no numerical value, -2 if the value is not known, otherwise the numerical value of it.

10.5 Wildcard Matching

Page Contents

---------- Routines

---------------- wildcard_match

---------------- wildcard_file

10.5.1 Routines

10.5.1.1 wildcard_match

include std/wildcard.e 
public function wildcard_match(sequence pattern, sequence string)

Determine whether a string matches a pattern. The pattern may contain * and ? wildcards.

10.5.1.1.1 Parameters:

pattern : a string, the pattern to match
string : the string to be matched against

10.5.1.1.2 Returns:

An integer, TRUE if string matches pattern, else FALSE.

10.5.1.1.3 Comments:

Character comparisons are case sensitive. If you want case insensitive comparisons, pass both pattern and string 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.

10.5.1.1.4 Example 1:

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

10.5.1.1.5 Example 2:

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

10.5.1.1.6 Example 3:

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

10.5.1.1.7 Example 4:

bin/search.ex

10.5.1.1.8 See Also:

wildcard_file, upper , lower, Regular expressions

10.5.1.2 wildcard_file

include std/wildcard.e 
public function wildcard_file(sequence pattern, sequence filename)

Determine whether a file name matches a wildcard pattern.

10.5.1.2.1 Parameters:

pattern : a string, the pattern to match
filename : the string to be matched against

10.5.1.2.2 Returns:

An integer, TRUE if filename matches pattern, else FALSE.

10.5.1.2.3 Comments:

* matches any 0 or more characters, ? matches any single character. On Unix the character comparisons are case sensitive. On Windows they are not.

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.

10.5.1.2.4 Example 1:

 i = wildcard_file("AB*CD.?", "aB123cD.e") 
-- i is set to 1 on Windows, 0 on Linux or FreeBSD

10.5.1.2.5 Example 2:

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

10.5.1.2.6 Example 3:

bin/search.ex

10.5.1.2.7 See Also:

wildcard_match, dir

11 Data Structures

EUPHORIA Database (EDS)

---------- Database File Format

---------- Error Status Constants

---------- Lock Type Constants

---------- Error Code Constants

---------- Variables

---------- Routines

---------- Managing databases

Prime Numbers

---------- Routines

Map (hash table)

---------- Hashing Algorithms

---------- Operation codes for put

---------- Types of Maps

---------- Types

---------- Routines

Stack

---------- Constants

---------- Types

---------- Routines

Sets

---------- Types

---------- Inclusion and belonging.

---------- Basic set-theoretic operations.

---------- Maps between sets.

---------- Reverse mappings

---------- Products

---------- Constants

---------- Operations on sets

11.1 EUPHORIA Database (EDS)

---------- Database File Format

---------------- Header

---------------- Block of table headers

---------------- Table header

---------------- Index block

---------------- Block of key pointers

---------------- Free list

---------- Error Status Constants

---------------- DB_OK

---------------- DB_OPEN_FAIL

---------------- DB_EXISTS_ALREADY

---------------- DB_LOCK_FAIL

---------------- DB_FATAL_FAIL

---------- Lock Type Constants

---------------- DB_LOCK_NO

---------------- DB_LOCK_SHARED

---------------- DB_LOCK_EXCLUSIVE

---------- Error Code Constants

---------------- MISSING_END

---------------- NO_DATABASE

---------------- BAD_SEEK

---------------- NO_TABLE

---------------- DUP_TABLE

---------------- BAD_RECNO

---------------- INSERT_FAILED

---------------- LAST_ERROR_CODE

---------- Variables

---------------- db_fatal_id

---------- Routines

---------------- db_get_errors

---------------- db_dump

---------------- check_free_list

---------- Managing databases

---------------- db_create

---------------- db_open

---------------- db_select

---------------- db_close

---------------- db_select_table

---------------- Managing tables

---------------- db_current_table

---------------- db_create_table

---------------- db_delete_table

---------------- db_clear_table

---------------- db_rename_table

---------------- db_table_list

---------------- Managing Records

---------------- db_find_key

---------------- db_get_recid

---------------- db_insert

---------------- db_delete_record

---------------- db_replace_recid

---------------- db_replace_data

---------------- db_table_size

---------------- db_record_data

---------------- db_fetch_record

---------------- db_record_key

---------------- db_record_recid

---------------- db_compress

---------------- db_current

---------------- db_cache_clear

---------------- db_set_caching

11.1.1 Database File Format

11.1.1.1 Header

byte 0: magic number for this file-type: 77
byte 1: version number (major)
byte 2: version number (minor)
byte 3: 4-byte pointer to block of table headers
byte 7: number of free blocks
byte 11: 4-byte pointer to block of free blocks

11.1.1.2 Block of table headers

-4: allocated size of this block (for possible reallocation)
0: number of table headers currently in use
4: table header1
16: table header2
28: etc.

11.1.1.3 Table header

0: pointer to the name of this table
4: total number of records in this table
8: number of blocks of records
12: pointer to the index block for this table

There are two levels of pointers. The logical array of key pointers is split up across many physical blocks. A single index block is used to select the correct small block. This allows inserts and deletes to be made without having to shift a large number of key pointers. Only one small block needs to be adjusted. This is particularly helpful when the table contains many thousands of records.

11.1.1.4 Index block

one per table

-4: allocated size of index block
0: number of records in 1st block of key pointers
4: pointer to 1st block
8: number of records in 2nd " "
12: pointer to 2nd block
16: etc.

11.1.1.5 Block of key pointers

many per table

-4: allocated size of this block in bytes
0: key pointer 1
4: key pointer 2
8: etc.

11.1.1.6 Free list

in ascending order of address

-4: allocated size of block of free blocks
0: address of 1st free block
4: size of 1st free block
8: address of 2nd free block
12: size of 2nd free block
16: etc.

The key value and the data value for a record are allocated space as needed. A pointer to the data value is stored just before the key value. EUPHORIA objects, key and data, are stored in a compact form.

All allocated blocks have the size of the block in bytes, stored in the four bytes just before the address.

11.1.2 Error Status Constants

11.1.2.1 DB_OK

include std/eds.e 
public constant DB_OK

Database is OK, not error has occurred.

11.1.2.2 DB_OPEN_FAIL

include std/eds.e 
public constant DB_OPEN_FAIL

The database could not be opened.

11.1.2.3 DB_EXISTS_ALREADY

include std/eds.e 
public constant DB_EXISTS_ALREADY

The database could not be created, it already exists.

11.1.2.4 DB_LOCK_FAIL

include std/eds.e 
public constant DB_LOCK_FAIL

A lock could not be gained on the database.

11.1.2.5 DB_FATAL_FAIL

include std/eds.e 
public constant DB_FATAL_FAIL

A fatal error has occurred.

11.1.3 Lock Type Constants

11.1.3.1 DB_LOCK_NO

include std/eds.e 
public enum DB_LOCK_NO

Do not lock the file.

11.1.3.2 DB_LOCK_SHARED

include std/eds.e 
public enum DB_LOCK_SHARED

Open the database with read-only access.

11.1.3.3 DB_LOCK_EXCLUSIVE

include std/eds.e 
public enum DB_LOCK_EXCLUSIVE

Open the database with read and write access.

11.1.4 Error Code Constants

11.1.4.1 MISSING_END

include std/eds.e 
public enum MISSING_END

Missing 0 terminator

11.1.4.2 NO_DATABASE

include std/eds.e 
public enum NO_DATABASE

current_db is not set

11.1.4.3 BAD_SEEK

include std/eds.e 
public enum BAD_SEEK

seek() failed.

11.1.4.4 NO_TABLE

include std/eds.e 
public enum NO_TABLE

no table was found.

11.1.4.5 DUP_TABLE

include std/eds.e 
public enum DUP_TABLE

this table already exists.

11.1.4.6 BAD_RECNO

include std/eds.e 
public enum BAD_RECNO

unknown key_location index was supplied.

11.1.4.7 INSERT_FAILED

include std/eds.e 
public enum INSERT_FAILED

couldn't insert a new record.

11.1.4.8 LAST_ERROR_CODE

include std/eds.e 
public enum LAST_ERROR_CODE

last error code

11.1.5 Variables

11.1.5.1 db_fatal_id

include std/eds.e 
public integer db_fatal_id db_fatal_id

Exception handler
Set this to a valid routine_id value for a procedure that will be called whenever the library detects a serious error. You procedure will be passed a single text string that describes the error. It may also call db_get_errors to get more detail about the cause of the error.

11.1.6 Routines

11.1.6.1 db_get_errors

include std/eds.e 
public function db_get_errors(integer clearing = 1)

Fetches the most recent set of errors recorded by the library.

11.1.6.1.1 Parameters:

clearing : if zero the set of errors is not reset, otherwise it will be cleared out. The default is to clear the set.

11.1.6.1.2 Returns:

A sequence, each element is a set of four fields.

Error Code.
Error Text.
Name of library routine that recorded the error.
Parameters passed to that routine.

11.1.6.1.3 Comments:

A number of library routines can detect errors. If the routine is a function, it usually returns an error code. However, procedures that detect an error can't do that. Instead, they record the error details and you can query that after calling the library routine.
Both functions and procedures that detect errors record the details in the Last Error Set, which is fetched by this function.

11.1.6.1.4 Example 1:

db_replace_data(recno, new_data) 
errs = db_get_errors() 
if length(errs) != 0 then 
    display_errors(errs) 
    abort(1) 
end if

11.1.6.2 db_dump

include std/eds.e 
public procedure db_dump(object file_id, integer low_level_too = 0)

print the current database in readable form to file fn

11.1.6.2.1 Parameters:

fn : the destination file for printing the current EUPHORIA database;
low_level_too : a boolean. If true, a byte-by-byte binary dump is presented as well; otherwise this step is skipped. If omitted, false is assumed.

11.1.6.2.2 Errors:

If the current database is not defined, an error will occur.

11.1.6.2.3 Comments:

All records in all tables are shown.
If low_level_too is non-zero, then a low-level byte-by-byte dump is also shown. The low-level dump will only be meaningful to someone who is familiar with the internal format of a EUPHORIA database.

11.1.6.2.4 Example 1:

if db_open("mydata", DB_LOCK_SHARED) != DB_OK then 
    puts(2, "Couldn't open the database!\n") 
    abort(1) 
end if 
fn = open("db.txt", "w") 
db_dump(fn) -- Simple output 
db_dump("lowlvl_db.txt", 1) -- Full low-level dump created.

11.1.6.3 check_free_list

include std/eds.e 
public procedure check_free_list()

Detects corruption of the free list in a EUPHORIA database.

11.1.6.3.1 Comments:

This is a debug routine used by RDS to detect corruption of the free list. Users do not normally call this.

11.1.7 Managing databases

11.1.7.1 db_create

include std/eds.e 
public function db_create(sequence path, integer lock_method = DB_LOCK_NO, integer init_tables = INIT_TABLES, integer init_free = INIT_FREE)

Create a new database, given a file path and a lock method.

11.1.7.1.1 Parameters:

path : a sequence, the path to the file that will contain the database.
lock_method : an integer specifying which type of access can be granted to the database. The value of lock_method can be either DB_LOCK_NO (no lock) or DB_LOCK_EXCLUSIVE (exclusive lock).
init_tables : an integer giving the initial number of tables to reserve space for. The default is 5 and the minimum is 1.
init_free : an integer giving the initial amount of free space pointers to reserve space for. The default is 5 and the minimum is 0.

11.1.7.1.2 Returns:

An integer, status code, either DB_OK if creation successful or anything else on an error.

11.1.7.1.3 Comments:

On success, the newly created database becomes the current database to which all other database operations will apply.

If the path, s, does not end in .edb, it will be added automatically.

A version number is stored in the database file so future versions of the database software can recognize the format, and possibly read it and deal with it in some way.

If the database already exists, it will not be overwritten. db_create() will return DB_EXISTS_ALREADY.

11.1.7.1.4 Example 1:

if db_create("mydata", DB_LOCK_NO) != DB_OK then 
    puts(2, "Couldn't create the database!\n") 
    abort(1) 
end if

11.1.7.1.5 See Also:

db_open, db_select

11.1.7.2 db_open

include std/eds.e 
public function db_open(sequence path, integer lock_method = DB_LOCK_NO)

Open an existing EUPHORIA database.

11.1.7.2.1 Parameters:

path : a sequence, the path to the file containing the database
lock_method : an integer specifying which sort of access can be granted to the database. The types of lock that you can use are:

DB_LOCK_NO : (no lock) - The default
DB_LOCK_SHARED : (shared lock for read-only access)
DB_LOCK_EXCLUSIVE : (for read/write access).

11.1.7.2.2 Returns:

An integer, status code, either DB_OK if creation successful or anything else on an error.

11.1.7.2.3 The return codes are:

public constant 
    DB_OK = 0          -- success 
    DB_OPEN_FAIL = -1  -- could not open the file 
    DB_LOCK_FAIL = -3  -- could not lock the file in the 
                       -- manner requested

11.1.7.2.4 Comments:

DB_LOCK_SHARED is only supported on Unix platforms. It allows you to read the database, but not write anything to it. If you request DB_LOCK_SHARED on WIN32 it will be treated as if you had asked for DB_LOCK_EXCLUSIVE.

If the lock fails, your program should wait a few seconds and try again. Another process might be currently accessing the database.

11.1.7.2.5 Example 1:

tries = 0 
while 1 do 
    err = db_open("mydata", DB_LOCK_SHARED) 
    if err = DB_OK then 
        exit 
    elsif err = DB_LOCK_FAIL then 
        tries += 1 
        if tries > 10 then 
            puts(2, "too many tries, giving up\n") 
            abort(1) 
        else 
            sleep(5) 
        end if 
    else 
        puts(2, "Couldn't open the database!\n") 
        abort(1) 
    end if 
end while

11.1.7.2.6 See Also:

db_create, db_select

11.1.7.3 db_select

include std/eds.e 
public function db_select(sequence path, integer lock_method = - 1)

Choose a new, already open, database to be the current database.

11.1.7.3.1 Parameters:

path : a sequence, the path to the database to be the new current database.
lock_method : an integer. Optional locking method.

11.1.7.3.2 Returns:

An integer, DB_OK on success or an error code.

11.1.7.3.3 Comments:

Subsequent database operations will apply to this database. path is the path of the database file as it was originally opened with db_open() or db_create().
When you create (db_create) or open (db_open) a database, it automatically becomes the current database. Use db_select() when you want to switch back and forth between open databases, perhaps to copy records from one to the other. After selecting a new database, you should select a table within that database using db_select_table().
If the lock_method is omitted and the database has not already been opened, this function will fail. However, if lock_method is a valid lock type for db_open and the database is not open yet, this function will attempt to open it. It may still fail if the database cannot be opened.

11.1.7.3.4 Example 1:

if db_select("employees") != DB_OK then 
    puts(2, "Could not select employees database\n") 
end if

11.1.7.3.5 Example 2:

if db_select("customer", DB_LOCK_SHARED) != DB_OK then 
    puts(2, "Could not open or select Customer database\n") 
end if

11.1.7.3.6 See Also:

db_open, db_select

11.1.7.4 db_close

include std/eds.e 
public procedure db_close()

Unlock and close the current database.

11.1.7.4.1 Comments:

Call this procedure when you are finished with the current database. Any lock will be removed, allowing other processes to access the database file. The current database becomes undefined.

11.1.7.5 db_select_table

include std/eds.e 
public function db_select_table(sequence name)

11.1.7.6 Managing tables

11.1.7.6.1 Parameters:

name : a sequence which defines the name of the new current table.

On success, the table with name given by name becomes the current table.

11.1.7.6.2 Returns:

An integer, either DB_OK on success or DB_OPEN_FAIL otherwise.

11.1.7.6.3 Errors:

An error occurs if the current database is not defined.

11.1.7.6.4 Comments:

All record-level database operations apply automatically to the current table.

11.1.7.6.5 Example 1:

if db_select_table("salary") != DB_OK then 
    puts(2, "Couldn't find salary table!\n") 
    abort(1) 
end if

11.1.7.6.6 See Also:

db_table_list

11.1.7.7 db_current_table

include std/eds.e 
public function db_current_table()

Get name of currently selected table

11.1.7.7.1 Parameters:

None.

11.1.7.7.2 Returns:

A sequence, the name of the current table. An empty string means that no table is currently selected.

11.1.7.7.3 Example 1:

s = db_current_table()

11.1.7.7.4 See Also:

db_select_table, db_table_list

11.1.7.8 db_create_table

include std/eds.e 
public function db_create_table(sequence name, integer init_records = INIT_RECORDS)

Create a new table within the current database.

11.1.7.8.1 Parameters:

name : a sequence, the name of the new table.
init_records : The number of records to initially reserve space for. (Default is 50)

11.1.7.8.2 Returns:

An integer, either DB_OK on success or DB_EXISTS_ALREADY on failure.

11.1.7.8.3 Errors:

An error occurs if the current database is not defined.

11.1.7.8.4 Comments:

The supplied name must not exist already on the current database.
The table that you create will initially have 0 records. However it will reserve some space for a number of records, which will improve the initial data load for the table.
It becomes the current table.

11.1.7.8.5 Example 1:

if db_create_table("my_new_table") != DB_OK then 
    puts(2, "Could not create my_new_table!\n") 
end if

11.1.7.8.6 See Also:

db_select_table, db_table_list

11.1.7.9 db_delete_table

include std/eds.e 
public procedure db_delete_table(sequence name)

Delete a table in the current database.

11.1.7.9.1 Parameters:

name : a sequence, the name of the table to delete.

11.1.7.9.2 Errors:

An error occurs if the current database is not defined.

11.1.7.9.3 Comments:

If there is no table with the name given by name, then nothing happens. On success, all records are deleted and all space used by the table is freed up. If the table was the current table, the current table becomes undefined.

11.1.7.9.4 See Also:

db_table_list, db_select_table, db_clear_table

11.1.7.10 db_clear_table

include std/eds.e 
public procedure db_clear_table(sequence name, integer init_records = INIT_RECORDS)

Clears a table of all its records, in the current database.

11.1.7.10.1 Parameters:

name : a sequence, the name of the table to clear.

11.1.7.10.2 Errors:

An error occurs if the current database is not defined.

11.1.7.10.3 Comments:

If there is no table with the name given by name, then nothing happens. On success, all records are deleted and all space used by the table is freed up. If this is the current table, after this operation it will still be the current table.

11.1.7.10.4 See Also:

db_table_list, db_select_table, db_delete_table

11.1.7.11 db_rename_table

include std/eds.e 
public procedure db_rename_table(sequence name, sequence new_name)

Rename a table in the current database.

11.1.7.11.1 Parameters:

name : a sequence, the name of the table to rename
new_name : a sequence, the new name for the table

11.1.7.11.2 Errors:

An error occurs if the current database is not defined.
If name does not exist on the current database, or if new_name does exist on the current database, an error will occur.

11.1.7.11.3 Comments:

The table to be renamed can be the current table, or some other table in the current database.

11.1.7.11.4 See Also:

db_table_list

11.1.7.12 db_table_list

include std/eds.e 
public function db_table_list()

Lists all tables on the current database.

11.1.7.12.1 Returns:

A sequence, of all the table names in the current database. Each element of this sequence is a sequence, the name of a table.

11.1.7.12.2 Errors:

An error occurs if the current database is undefined.

11.1.7.12.3 Example 1:

sequence names = db_table_list() 
for i = 1 to length(names) do 
    puts(1, names[i] & '\n') 
end for

11.1.7.12.4 See Also:

db_select_table, db_create_table

11.1.7.13 Managing Records

11.1.7.14 db_find_key

include std/eds.e 
public function db_find_key(object key, object table_name = current_table_name)

Find the record in the current table with supplied key.

11.1.7.14.1 Parameters:

key : the identifier of the record to be looked up.
table_name : optional name of table to find key in

11.1.7.14.2 Returns:

An integer, either greater or less than zero:

If above zero, the record identified by key was found on the current table, and the returned integer is its record number.
If less than zero, the record was not found. The returned integer is the opposite of what the record number would have been, had the record been found.
If equal to zero, an error occured.

11.1.7.14.3 Errors:

If the current table is not defined, it returns 0.

11.1.7.14.4 Comments:

A fast binary search is used to find the key in the current table. The number of comparisons is proportional to the log of the number of records in the table. The key is unique--a table is more like a dictionary than like a spreadsheet.

You can select a range of records by searching for the first and last key values in the range. If those key values don't exist, you'll at least get a negative value showing where they would be, if they existed. e.g. Suppose you want to know which records have keys greater than "GGG" and less than "MMM". If -5 is returned for key "GGG", it means a record with "GGG" as a key would be inserted as record number 5. -27 for "MMM" means a record with "MMM" as its key would be inserted as record number 27. This quickly tells you that all records, >= 5 and < 27 qualify.

11.1.7.14.5 Example 1:

rec_num = db_find_key("Millennium") 
if rec_num > 0 then 
    ? db_record_key(rec_num) 
    ? db_record_data(rec_num) 
else 
    puts(2, "Not found, but if you insert it,\n") 
 
    printf(2, "it will be #%d\n", -rec_num) 
end if

11.1.7.14.6 See Also:

db_insert, db_replace_data, db_delete_record, db_get_recid

11.1.7.15 db_get_recid

include std/eds.e 
public function db_get_recid(object key, object table_name = current_table_name)

Returns the unique record identifier (recid) value for the record.

11.1.7.15.1 Parameters:

key : the identifier of the record to be looked up.
table_name : optional name of table to find key in

11.1.7.15.2 Returns:

An atom, either greater or equal to zero:

If above zero, it is a recid.
If less than zero, the record wasn't found.
If equal to zero, an error occured.

11.1.7.15.3 Errors:

If the table is not defined, an error is raised.

11.1.7.15.4 Comments:

A recid is a number that uniquely identifies a record in the database. No two records in a database has the same recid value. They can be used instead of keys to quickly refetch a record, as they avoid the overhead of looking for a matching record key. They can also be used without selecting a table first, as the recid is unique to the database and not just a table. However, they only remain valid while a database is open and so long as it doesn't get compressed. Compressing the database will give each record a new recid value.

Because it is faster to fetch a record with a recid rather than with its key, these are used when you know you have to refetch a record.

11.1.7.15.5 Example 1:

rec_num = db_get_recid("Millennium") 
if rec_num > 0 then 
    ? db_record_recid(rec_num) -- fetch key and data. 
else 
    puts(2, "Not found\n") 
end if

11.1.7.15.6 See Also:

db_insert, db_replace_data, db_delete_record, db_find_key

11.1.7.16 db_insert

include std/eds.e 
public function db_insert(object key, object data, object table_name = current_table_name)

Insert a new record into the current table.

11.1.7.16.1 Parameters:

key : an object, the record key, which uniquely identifies it inside the current table
data : an object, associated to key.
table_name : optional table name to insert record into

11.1.7.16.2 Returns:

An integer, either DB_OK on success or an error code on failure.

11.1.7.16.3 Comments:

Within a table, all keys must be unique. db_insert() will fail with DB_EXISTS_ALREADY if a record already exists on current table with the same key value.

Both key and data can be any EUPHORIA data objects, atoms or sequences.

11.1.7.16.4 Example 1:

if db_insert("Smith", {"Peter", 100, 34.5}) != DB_OK then 
    puts(2, "insert failed!\n") 
end if

11.1.7.16.5 See Also:

db_delete_record

11.1.7.17 db_delete_record

include std/eds.e 
public procedure db_delete_record(integer key_location, object table_name = current_table_name)

Delete record number key_location from the current table.

11.1.7.17.1 Parameter:

key_location : a positive integer, designating the record to delete.
table_name : optional table name to delete record from.

11.1.7.17.2 Errors:

If the current table is not defined, or key_location is not a valid record index, an error will occur. Valid record indexes are between 1 and the number of records in the table.

11.1.7.17.3 Example 1:

db_delete_record(55)

11.1.7.17.4 See Also:

db_find_key

11.1.7.18 db_replace_recid

include std/eds.e 
public procedure db_replace_recid(integer recid, object data)

In the current database, replace the data portion of a record with new data. This can be used to quickly update records that have already been located by calling db_get_recid. This operation is faster than using db_replace_data

11.1.7.18.1 Parameters:

recid : an atom, the recid of the record to be updated.
data : an object, the new value of the record.

11.1.7.18.2 Comments:

recid must be fetched using db_get_recid first.
data is an EUPHORIA object of any kind, atom or sequence.
The recid does not have to be from the current table.
This does no error checking. It assumes the database is open and valid.

11.1.7.18.3 Example 1:

rid = db_get_recid("Peter") 
rec = db_record_recid(rid) 
rec[2][3] *= 1.10 
db_replace_recid(rid, rec[2])

11.1.7.18.4 See Also:

db_replace_data, db_find_key, db_get_recid

11.1.7.19 db_replace_data

include std/eds.e 
public procedure db_replace_data(integer key_location, object data, object table_name = current_table_name)

In the current table, replace the data portion of a record with new data.

11.1.7.19.1 Parameters:

key_location: an integer, the index of the record the data is to be altered.
data: an object , the new value associated to the key of the record.
table_name: optional table name of record to replace data in.

11.1.7.19.2 Comments:

key_location must be from 1 to the number of records in the current table. data is an EUPHORIA object of any kind, atom or sequence.

11.1.7.19.3 Example 1:

db_replace_data(67, {"Peter", 150, 34.5})

11.1.7.19.4 See Also:

db_find_key

11.1.7.20 db_table_size

include std/eds.e 
public function db_table_size(object table_name = current_table_name)

Get the size (number of records) of the default table.

11.1.7.20.1 Parameters:

table_name : optional table name to get the size of.

Returns An integer, the current number of records in the current table. If a value less than zero is returned, it means that an error occured.

11.1.7.20.2 Errors:

If the current table is undefined, an error will occur.

11.1.7.20.3 Example 1:

-- look at all records in the current table 
for i = 1 to db_table_size() do 
    if db_record_key(i) = 0 then 
    	puts(1, "0 key found\n") 
    	exit 
    end if 
end for

11.1.7.20.4 See Also:

db_replace_data

11.1.7.21 db_record_data

include std/eds.e 
public function db_record_data(integer key_location, object table_name = current_table_name)

Returns the data in a record queried by position.

11.1.7.21.1 Parameters:

key_location : the index of the record the data of which is being fetched.
table_name : optional table name to get record data from.

11.1.7.21.2 Returns:

An object, the data portion of requested record.
NOTE This function calls fatal() and returns a value of -1 if an error prevented the correct data being returned.

11.1.7.21.3 Comments:

Each record in a EUPHORIA database consists of a key portion and a data portion. Each of these can be any EUPHORIA atom or sequence.

11.1.7.21.4 Errors:

If the current table is not defined, or if the record index is invalid, an error will occur.

11.1.7.21.5 Example 1:

puts(1, "The 6th record has data value: ") 
? db_record_data(6)

11.1.7.21.6 See Also:

db_find_key, db_replace_data

11.1.7.22 db_fetch_record

include std/eds.e 
public function db_fetch_record(object key, object table_name = current_table_name)

Returns the data for the record with supplied key.

11.1.7.22.1 Parameters:

key : the identifier of the record to be looked up.
table_name : optional name of table to find key in

11.1.7.22.2 Returns:

An integer,

If less than zero, the record was not found. The returned integer is the opposite of what the record number would have been, had the record been found.
If equal to zero, an error occured. A sequence, the data for the record.

11.1.7.22.3 Errors:

If the current table is not defined, it returns 0.

11.1.7.22.4 Comments:

Each record in a EUPHORIA database consists of a key portion and a data portion. Each of these can be any EUPHORIA atom or sequence. NOTE This function does not support records that data consists of a single non-sequence value. In those cases you will need to use db_find_key and db_record_data.

11.1.7.22.5 Example 1:

printf(1, "The record['%s'] has data value:\n", {"foo"}) 
? db_fetch_record("foo")

11.1.7.22.6 See Also:

db_find_key, db_record_data

11.1.7.23 db_record_key

include std/eds.e 
public function db_record_key(integer key_location, object table_name = current_table_name)

11.1.7.23.1 Parameters:

key_location : an integer, the index of the record the key is being requested.
table_name : optional table name to get record key from.

Returns An object, the key of the record being queried by index.
NOTE This function calls fatal() and returns a value of -1 if an error prevented the correct data being returned.

11.1.7.23.2 Errors:

If the current table is not defined, or if the record index is invalid, an error will occur.

11.1.7.23.3 Comments:

Each record in a EUPHORIA database consists of a key portion and a data portion. Each of these can be any EUPHORIA atom or sequence.

11.1.7.23.4 Example 1:

puts(1, "The 6th record has key value: ") 
? db_record_key(6)

11.1.7.23.5 See Also:

db_record_data

11.1.7.24 db_record_recid

include std/eds.e 
public function db_record_recid(integer recid)

Returns the key and data in a record queried by recid.

11.1.7.24.1 Parameters:

recid : the recid of the required record, which has been previously fetched using db_get_recid .

11.1.7.24.2 Returns:

An sequence, the first element is the key and the second element is the data portion of requested record.

11.1.7.24.3 Comments:

This is much faster than calling db_record_key and db_record_data.
This does no error checking. It assumes the database is open and valid.
This function does not need the requested record to be from the current table. The recid can refer to a record in any table.

11.1.7.24.4 Example 1:

rid = db_get_recid("SomeKey") 
? db_record_recid(rid)

11.1.7.24.5 See Also:

db_get_recid, db_replace_recid

11.1.7.25 db_compress

include std/eds.e 
public function db_compress()

Compresses the current database.

11.1.7.25.1 Returns:

An integer, either DB_OK on success or an error code on failure.

11.1.7.25.2 Comments:

The current database is copied to a new file such that any blocks of unused space are eliminated. If successful, the return value will be set to DB_OK, and the new compressed database file will retain the same name. The current table will be undefined. As a backup, the original, uncompressed file will be renamed with an extension of .t0 (or .t1, .t2, ..., .t99). In the highly unusual case that the compression is unsuccessful, the database will be left unchanged, and no backup will be made.

When you delete items from a database, you create blocks of free space within the database file. The system keeps track of these blocks and tries to use them for storing new data that you insert. db_compress() will copy the current database without copying these free areas. The size of the database file may therefore be reduced. If the backup filenames reach .t99 you will have to delete some of them.

11.1.7.25.3 Example 1:

if db_compress() != DB_OK then 
    puts(2, "compress failed!\n") 
end if

11.1.7.26 db_current

include std/eds.e 
public function db_current()

Get name of currently selected database.

11.1.7.26.1 Parameters:

None.

11.1.7.26.2 Returns:

A sequence, the name of the current database. An empty string means that no database is currently selected.

11.1.7.26.3 Comments:

The actual name returned is the path as supplied to the db_open routine.

11.1.7.26.4 Example 1:

s = db_current_database()

11.1.7.26.5 See Also:

db_select

11.1.7.27 db_cache_clear

include std/eds.e 
public procedure db_cache_clear()

Forces the database index cache to be cleared.

11.1.7.27.1 Parameters:

None

11.1.7.27.2 Comments:

This is not normally required to the run. You might run it to set up a predetermined state for performance timing, or to release some memory back to the application.

11.1.7.27.3 Example 1:

db_cache_clear() -- Clear the cache.

11.1.7.28 db_set_caching

include std/eds.e 
public function db_set_caching(atom new_setting)

Sets the key cache behavior.
Initially, the cache option is turned on. This means that when possible, the keys of a table are kept in RAM rather than read from disk each time db_select_table() is called. For most databases, this will improve performance when you have more than one table in it.

11.1.7.28.1 Parameters:

integer : 0 will turn of caching, 1 will turn it back on.

11.1.7.28.2 Returns:

An integer, the previous setting of the option.

11.1.7.28.3 Comments:

When caching is turned off, the current cache contents is totally cleared.

11.1.7.28.4 Example 1:

x = db_set_caching(0) -- Turn off key caching.

11.2 Prime Numbers

Page Contents

---------- Routines

---------------- calc_primes

---------------- next_prime

---------------- prime_list

11.2.1 Routines

11.2.1.1 calc_primes

include std/primes.e 
public function calc_primes(integer max_p, atom time_limit_p = 10)

Returns all the prime numbers below some threshold, with a cap on computation time.

11.2.1.1.1 Parameters:

max_p : an integer, the last prime returned is the next prime after or on this value.
time_out_p : an atom, the maximum number of seconds that this function can run for. The default is 10 (ten) seconds.

11.2.1.1.2 Returns:

A sequence, made of prime numbers in increasing order. The last value is the next prime number that falls on or after the value of max_p.

11.2.1.1.3 Comments:

The returned sequence contains all the prime numbers less than its last element.

If the function times out, it may not hold all primes below max_p, but only the largest ones will be absent. If the last element returned is less than max_p then the function timed out.

To disable the timeout, simply give it a negative value.

11.2.1.1.4 Example 1:

? calc_primes(1000, 5) 
-- On a very slow computer, you may only get all primes up to say 719.  
-- On a faster computer, the last element printed out will be 997.  
-- This call will never take longer than 5 seconds.

11.2.1.1.5 See Also:

next_prime prime_list

11.2.1.2 next_prime

include std/primes.e 
public function next_prime(integer n, object fail_signal_p = - 1, atom time_out_p = 1)

Return the next prime number on or after the supplied number

11.2.1.2.1 Parameters:

n : an integer, the starting point for the search
fail_signal_p : an integer, used to signal error. Defaults to -1.

11.2.1.2.2 Returns:

An integer, which is prime only if it took less than 1 second to determine the next prime greater or equal to n .

11.2.1.2.3 Comments:

The default value of -1 will alert you about an invalid returned value, since a prime not less than n is expected. However, you can pass another value for this parameter.

11.2.1.2.4 Example 1:

? next_prime(997) 
-- On a very slow computer, you might get -997, but 1003 is expected.

11.2.1.2.5 See Also:

calc_primes

11.2.1.3 prime_list

include std/primes.e 
public function prime_list(integer top_prime_p = 0)

Returns a list of prime numbers.

11.2.1.3.1 Parameters:

top_prime_p : The list will end with the prime less than or equal to this value. If this is zero, the current list calculated primes is returned.

11.2.1.3.2 Returns:

An sequence, a list of prime numbers from 2 to top_prime_p

11.2.1.3.3 Example 1:

sequence pList = prime_list(1000) 
-- pList will now contain all the primes from 2 up to the largest less than or 
--    equal to 1000.

11.2.1.3.4 See Also:

calc_primes, next_prime

11.3 Map (hash table)

---------------- hash

---------- Hashing Algorithms

---------------- HSIEH32

---------------- FLETCHER32

---------------- ADLER32

---------------- MD5

---------------- SHA256

---------- Operation codes for put

---------------- PUT

---------------- ADD

---------------- SUBTRACT

---------------- MULTIPLY

---------------- DIVIDE

---------------- APPEND

---------------- CONCAT

---------------- LEAVE

---------- Types of Maps

---------------- SMALLMAP

---------- Types

---------------- map

---------- Routines

---------------- calc_hash

---------------- threshold

---------------- type_of

---------------- rehash

---------------- new

---------------- new_extra

---------------- compare

---------------- has

---------------- get

---------------- nested_get

---------------- put

---------------- nested_put

---------------- remove

---------------- clear

---------------- size

---------------- NUM_ENTRIES

---------------- statistics

---------------- keys

---------------- values

---------------- pairs

---------------- optimize

---------------- load_map

---------------- SM_TEXT

---------------- save_map

---------------- copy

---------------- new_from_kvpairs

---------------- new_from_string

---------------- for_each

A map is a special array, often called an associative array or dictionary, in which the index to the data can be any EUPHORIA object and not just an integer. These sort of indexes are also called keys. For example we can code things like this...

   custrec = new() -- Create a new map 
   put(custrec, "Name", "Joe Blow") 
   put(custrec, "Address", "555 High Street") 
   put(custrec, "Phone", 555675632)

This creates three elements in the map, and they are indexed by "Name", "Address" and "Phone", meaning that to get the data associated with those keys we can code ...

   object data = get(custrec, "Phone") 
   -- data now set to 555675632

Note: Only one instance of a given key can exist in a given map, meaning for example, we couldn't have two separate "Name" values in the above custrec map.

Maps automatically grow to accommodate all the elements placed into it.

Associative arrays can be implemented in many different ways, depending on what efficiency trade-offs have been made. This implementation allows you to decide if you want a small map or a large map.

small map: Faster for small numbers of elements. Speed is usually proportional to the number of elements.
large map: Faster for large number of elements. Speed is usually the same regardless of how many elements are in the map. The speed is often slower than a small map.
Note: If the number of elements placed into a small map take it over the initial size of the map, it is automatically converted to a large map.

11.3.1 hash

<built-in> function hash(object source, atom algo)

Calculates a hash value from key using the algorithm algo

11.3.1.1 Parameters:

source : Any EUPHORIA object
algo : A code indicating which algorithm to use.

-5 uses Hsieh. Fastest and good dispersion
-4 uses Fletcher. Very fast and good dispersion
-3 uses Adler. Very fast and reasonable dispersion, especially for small strings
-2 uses MD5 (not implemented yet) Slower but very good dispersion. Suitable for signatures.
-1 uses SHA256 (not implemented yet) Slow but excellent dispersion. Suitable for signatures. More secure than MD5.
0 and above (integers and decimals) and non-integers less than zero use the cyclic variant (hash = hash * algo + c). This is a fast and good to excellent dispersion depending on the value of algo. Decimals give better dispersion but are slightly slower.

11.3.1.1.1 Returns:

An integer, Except for the MD5 and SHA256 algorithms, this is a 32-bit integer.
A sequence, MD5 returns a 4-element sequence of integers
SHA256 returns a 8-element sequence of integers.

11.3.1.1.2 Comments:

For algo values from zero to less than 1, that actual value used is (algo + 69096).

11.3.1.1.3 Example 1:

x = hash("The quick brown fox jumps over the lazy dog", 0) 
-- x is 242399616 
x = hash("The quick brown fox jumps over the lazy dog", 99.94) 
-- x is 723158 
x = hash("The quick brown fox jumps over the lazy dog", -99.94) 
-- x is 4175585990 
x = hash("The quick brown fox jumps over the lazy dog", -4) 
-- x is 467406810

11.3.2 Hashing Algorithms

11.3.2.1 HSIEH32

include std/map.e 
public enum HSIEH32

11.3.2.2 FLETCHER32

include std/map.e 
public enum FLETCHER32

11.3.2.3 ADLER32

include std/map.e 
public enum ADLER32

11.3.2.4 MD5

include std/map.e 
public enum MD5

11.3.2.5 SHA256

include std/map.e 
public enum SHA256

11.3.3 Operation codes for put

11.3.3.1 PUT

include std/map.e 
public enum PUT

11.3.3.2 ADD

include std/map.e 
public enum ADD

11.3.3.3 SUBTRACT

include std/map.e 
public enum SUBTRACT

11.3.3.4 MULTIPLY

include std/map.e 
public enum MULTIPLY

11.3.3.5 DIVIDE

include std/map.e 
public enum DIVIDE

11.3.3.6 APPEND

include std/map.e 
public enum APPEND

11.3.3.7 CONCAT

include std/map.e 
public enum CONCAT

11.3.3.8 LEAVE

include std/map.e 
public enum LEAVE

11.3.4 Types of Maps

11.3.4.1 SMALLMAP

include std/map.e 
public constant SMALLMAP

11.3.5 Types

11.3.5.1 map

include std/map.e 
public type map(object obj_p)

Defines the datatype 'map'

11.3.5.1.1 Comments:

Used when declaring a map variable.

11.3.5.1.2 Example:

map SymbolTable = new() -- Create a new map to hold the symbol table.

11.3.6 Routines

11.3.6.1 calc_hash

include std/map.e 
public function calc_hash(object key_p, integer max_hash_p = 0)

Calculate a Hashing value from the supplied data.

11.3.6.1.1 Parameters:

pData : The data for which you want a hash value calculated.
max_hash_p : (default = 0) The returned value will be no larger than this value. However, a value of 0 or lower means that it can grow as large as the maximum integer value.

11.3.6.1.2 Returns:

An integer, the value of which depends only on the supplied data.

11.3.6.1.3 Comments:

This is used whenever you need a single number to represent the data you supply. It can calculate the number based on all the data you give it, which can be an atom or sequence of any value.

11.3.6.1.4 Example 1:

integer h1 
h1 = calc_hash( symbol_name )

11.3.6.2 threshold

include std/map.e 
public function threshold(integer new_value_p = 0)

Gets or Sets the threshold value that determines at what point a small map converts into a large map structure. Initially this has been set to 50, meaning that maps up to 50 elements use the small map structure.

11.3.6.2.1 Parameters:

new_value_p : If this is greater than zero then it sets the threshold value.

11.3.6.2.2 Returns:

An integer, the current value (when new_value_p is less than 1) or the old value prior to setting it to new_value_p .

11.3.6.3 type_of

include std/map.e 
public function type_of(map the_map_p)

Determines the type of the map.

11.3.6.3.1 Parameters:

m : A map

11.3.6.3.2 Returns:

An integer, Either SMALLMAP or LARGEMAP

11.3.6.4 rehash

include std/map.e 
public procedure rehash(map the_map_p, integer requested_bucket_size_p = 0)

Changes the width, i.e. the number of buckets, of a map. Only effects large maps.

11.3.6.4.1 Parameters:

m : the map to resize
requested_bucket_size_p : a lower limit for the new size.

11.3.6.4.2 Returns:

A map, with the same data in, but more evenly dispatched and hence faster to use.

11.3.6.4.3 Comment:

If requested_bucket_size_p is not greater than zero, a new width is automatically derived from the current one.

11.3.6.4.4 See Also:

statistics, optimize

11.3.6.5 new

include std/map.e 
public function new(integer initial_size_p = 690)

Create a new map data structure

11.3.6.5.1 Parameters:

initial_size_p : An estimate of how many initial elements will be stored in the map. If this value is less than the threshold value, the map will initially be a small map otherwise it will be a large map.

11.3.6.5.2 Returns:

An empty map.

11.3.6.5.3 Comments:

A new object of type map is created. The resources allocated for the map will be automatically cleaned up if the reference count of the returned value drops to zero, or if passed in a call to delete.

11.3.6.5.4 Example 1:

map m = new()  -- m is now an empty map 
map x = new(threshold()) -- Forces a small map to be initialized 
x = new()    -- the resources for the map previously stored in x are released automatically 
delete( m )  -- the resources for the map are released

11.3.6.6 new_extra

include std/map.e 
public function new_extra(object the_map_p, integer initial_size_p = 690)

Returns either the supplied map or a new map.

11.3.6.6.1 Parameters:

the_map_p : An object, that could be an existing map
initial_size_p : An estimate of how many initial elements will be stored in a new map.

11.3.6.6.2 Returns:

A map, If m is an existing map then it is returned otherwise this returns a new empty map.

11.3.6.6.3 Comments:

This is used to return a new map if the supplied variable isn't already a map.

11.3.6.6.4 Example 1:

map m = new_extra( foo() ) -- If foo() returns a map it is used, otherwise 
                           --  a new map is created.

11.3.6.7 compare

include std/map.e 
public function compare(map map_1_p, map map_2_p, integer scope_p = 'd')

Compares two maps to test equality.

11.3.6.7.1 Parameters:

map_1_p : A map
map_2_p : A map
scope_p : An integer that specifies what to compare.

'k' or 'K' to only compare keys.
'v' or 'V' to only compare values.
'd' or 'D' to compare both keys and values. This is the default.

11.3.6.7.2 Returns:

An integer,

-1 if they are not equal.
0 if they are literally the same map.
1 if they contain the same keys and/or values.

11.3.6.7.3 Example 1:

map map_1_p = foo() 
map map_2_p = bar() 
if compare(map_1_p, map_2_p, 'k') >= 0 then 
     ... -- two maps have the same keys

11.3.6.8 has

include std/map.e 
public function has(map the_map_p, object the_key_p)

Check whether map has a given key.

11.3.6.8.1 Parameters:

the_map_p : the map to inspect
the_key_p : an object to be looked up

11.3.6.8.2 Returns:

An integer, 0 if not present, 1 if present.

11.3.6.8.3 Example 1:

map the_map_p 
the_map_p = new() 
put(the_map_p, "name", "John") 
? has(the_map_p, "name") -- 1 
? has(the_map_p, "age")  -- 0

11.3.6.8.4 See Also:

get

11.3.6.9 get

include std/map.e 
public function get(map the_map_p, object the_key_p, object default_value_p = 0)

Retrieves the value associated to a key in a map.

11.3.6.9.1 Parameters:

the_map_p : the map to inspect
the_key_p : an object, the the_key_p being looked tp
default_value_p : an object, a default value returned if the_key_p not found. The default is 0.

11.3.6.9.2 Returns:

An object, the value that corresponds to the_key_p in the_map_p. If the_key_p is not in the_map_p, default_value_p is returned instead.

11.3.6.9.3 Example 1:

map ages 
ages = new() 
put(ages, "Andy", 12) 
put(ages, "Budi", 13) 
 
integer age 
age = get(ages, "Budi", -1) 
if age = -1 then 
    puts(1, "Age unknown") 
else 
    printf(1, "The age is %d", age) 
end if

11.3.6.9.4 See Also:

has

11.3.6.10 nested_get

include std/map.e 
public function nested_get(map the_map_p, sequence the_keys_p, object default_value_p = 0)

Returns the value that corresponds to the object the_keys_p in the nested map the_map_p. the_keys_p is a sequence of keys. If any key is not in the map, the object default_value_p is returned instead.

11.3.6.11 put

include std/map.e 
public procedure put(map the_map_p, object the_key_p, object the_value_p, integer operation_p = PUT, integer trigger_p = 100)

Adds or updates an entry on a map.

11.3.6.11.1 Parameters:

the_map_p : the map where an entry is being added or updated
the_key_p : an object, the the_key_p to look up
the_value_p : an object, the value to add, or to use for updating.
operation : an integer, indicating what is to be done with the_value_p. Defaults to PUT.
trigger_p : an integer. Default is 100. See Comments for details.

11.3.6.11.2 Returns:

The updated map.

11.3.6.11.3 Comments:

The operation parameter can be used to modify the existing value. Valid operations are:

PUT -- This is the default, and it replaces any value in there already
ADD -- Equivalent to using the += operator
SUBTRACT -- Equivalent to using the -= operator
MULTIPLY -- Equivalent to using the *= operator
DIVIDE -- Equivalent to using the /= operator
APPEND -- Appends the value to the existing data
CONCAT -- Equivalent to using the &= operator
LEAVE -- If it already exists, the current value is left unchanged otherwise the new value is added to the map.

The trigger parameter is used when you need to keep the average number of keys in a hash bucket to a specific maximum. The trigger value is the maximum allowed. Each time a put operation increases the hash table's average bucket size to be more than the trigger value the table is expanded by a factor of 3.5 and the keys are rehashed into the enlarged table. This can be a time intensive action so set the value to one that is appropriate to your application.

By keeping the average bucket size to a certain maximum, it can speed up lookup times.
If you set the trigger to zero, it will not check to see if the table needs reorganizing. You might do this if you created the original bucket size to an optimal value. See new on how to do this.

11.3.6.11.4 Example 1:

map ages 
ages = new() 
put(ages, "Andy", 12) 
put(ages, "Budi", 13) 
put(ages, "Budi", 14) 
 
-- ages now contains 2 entries: "Andy" => 12, "Budi" => 14

11.3.6.11.5 See Also:

remove, has, nested_put

11.3.6.12 nested_put

include std/map.e 
public procedure nested_put(map the_map_p, sequence the_keys_p, object the_value_p, integer operation_p = PUT, integer trigger_p = 51)

Adds or updates an entry on a map.

11.3.6.12.1 Parameters:

the_map_p : the map where an entry is being added or updated
the_keys_p : a sequence of keys for the nested maps
the_value_p : an object, the value to add, or to use for updating.
operation_p : an integer, indicating what is to be done with value. Defaults to PUT.
trigger_p : an integer. Default is 51. See Comments for details.

11.3.6.12.2 Valid operations are:

PUT -- This is the default, and it replaces any value in there already
ADD -- Equivalent to using the += operator
SUBTRACT -- Equivalent to using the -= operator
MULTIPLY -- Equivalent to using the *= operator
DIVIDE -- Equivalent to using the /= operator
APPEND -- Appends the value to the existing data
CONCAT -- Equivalent to using the &= operator

11.3.6.12.3 Returns:

The modified map.

11.3.6.12.4 Comments:

If existing entry with the same key is already in the map, the value of the entry is updated.
The trigger parameter is used when you need to keep the average number of keys in a hash bucket to a specific maximum. The trigger value is the maximum allowed. Each time a put operation increases the hash table's average bucket size to be more than the trigger value the table is expanded by a factor 3.5 and the keys are rehashed into the enlarged table. This can be a time intensive action so set the value to one that is appropriate to your application.

By keeping the average bucket size to a certain maximum, it can speed up lookup times.
If you set the trigger to zero, it will not check to see if the table needs reorganizing. You might do this if you created the original bucket size to an optimal value. See new on how to do this.

11.3.6.12.5 Example 1:

map city_population 
city_population = new() 
nested_put(city_population, {"United States", "California", "Los Angeles"}, 3819951 ) 
nested_put(city_population, {"Canada",        "Ontario",    "Toronto"},     2503281 )

11.3.6.13 remove

include std/map.e 
public procedure remove(map the_map_p, object the_key_p)

Remove an entry with given key from a map.

11.3.6.13.1 Parameters:

the_map_p : the map to operate on
key : an object, the key to remove.

11.3.6.13.2 Returns:

The modified map.

11.3.6.13.3 Comments:

If key is not on the_map_p, the the_map_p is returned unchanged.
If you need to remove all entries, see clear

11.3.6.13.4 Example 1:

map the_map_p 
the_map_p = new() 
put(the_map_p, "Amy", 66.9) 
remove(the_map_p, "Amy") 
-- the_map_p is now an empty map again

11.3.6.13.5 See Also:

clear, has

11.3.6.14 clear

include std/map.e 
public procedure clear(map the_map_p)

Remove all entries in a map.

11.3.6.14.1 Parameters:

the_map_p : the map to operate on

11.3.6.14.2 Comments:

This is much faster than removing each entry individually.
If you need to remove just one entry, see remove

11.3.6.14.3 Example 1:

map the_map_p 
the_map_p = new() 
put(the_map_p, "Amy", 66.9) 
put(the_map_p, "Betty", 67.8) 
put(the_map_p, "Claire", 64.1) 
... 
clear(the_map_p) 
-- the_map_p is now an empty map again

11.3.6.14.4 See Also:

remove, has

11.3.6.15 size

include std/map.e 
public function size(map the_map_p)

Return the number of entries in a map.

11.3.6.15.1 Parameters:

the_map_p : the map being queried

11.3.6.15.2 Returns:

An integer, the number of entries it has.

11.3.6.15.3 Comments:

For an empty map, size will be zero

11.3.6.15.4 Example 1:

map the_map_p 
put(the_map_p, 1, "a") 
put(the_map_p, 2, "b") 
? size(the_map_p) -- outputs 2

11.3.6.15.5 See Also:

statistics

11.3.6.16 NUM_ENTRIES

include std/map.e 
public enum NUM_ENTRIES

Retrieves characteristics of a map.

11.3.6.16.1 Parameters:

the_map_p : the map being queried

11.3.6.16.2 Returns:

A sequence, of 7 integers:

NUM_ENTRIES -- number of entries
NUM_IN_USE -- number of buckets in use
NUM_BUCKETS -- number of buckets
LARGEST_BUCKET -- size of largest bucket
SMALLEST_BUCKET -- size of smallest bucket
AVERAGE_BUCKET -- average size for a bucket
STDEV_BUCKET -- standard deviation for the bucket length series

11.3.6.16.3 Example 1:

sequence s = statistics(mymap) 
printf(1, "The average size of the buckets is %d", s[AVERAGE_BUCKET])

11.3.6.17 statistics

include std/map.e 
public function statistics(map the_map_p)

11.3.6.18 keys

include std/map.e 
public function keys(map the_map_p, integer sorted_result = 0)

Return all keys in a map.

Parameters;

the_map_p: the map being queried
sorted_result: optional integer. 0 [default] means do not sort the output and 1 means to sort the output before returning.

11.3.6.18.1 Returns:

A sequence made of all the keys in the map.

11.3.6.18.2 Comments:

If sorted_result is not used, the order of the keys returned is not predicable.

11.3.6.18.3 Example 1:

map the_map_p 
the_map_p = new() 
put(the_map_p, 10, "ten") 
put(the_map_p, 20, "twenty") 
put(the_map_p, 30, "thirty") 
put(the_map_p, 40, "forty") 
 
sequence keys 
keys = keys(the_map_p) -- keys might be {20,40,10,30} or some other order 
keys = keys(the_map_p, 1) -- keys will be {10,20,30,40}

11.3.6.18.4 See Also:

has, values, pairs

11.3.6.19 values

include std/map.e 
public function values(map the_map, object keys = 0, object default_values = 0)

Return values, without their keys, from a map.

11.3.6.19.1 Parameters:

the_map : the map being queried
keys : optional, key list of values to return.
default_values : optional default values for keys list

11.3.6.19.2 Returns:

A sequence, of all values stored in the_map .

11.3.6.19.3 Comments:

The order of the values returned may not be the same as the putting order.
Duplicate values are not removed.
You use the keys parameter to return a specific set of values from the map. They are returned in the same order as the keys parameter. If no default_values is given and one is needed, 0 will be used.
If default_values is an atom, it represents the default value for all values in keys.
If default_values is a sequence, and its length is less than keys, then the last item in default_values is used for the rest of the keys.

11.3.6.19.4 Example 1:

map the_map_p 
the_map_p = new() 
put(the_map_p, 10, "ten") 
put(the_map_p, 20, "twenty") 
put(the_map_p, 30, "thirty") 
put(the_map_p, 40, "forty") 
 
sequence values 
values = values(the_map_p) 
-- values might be {"twenty","forty","ten","thirty"} 
-- or some other order

11.3.6.19.5 Example 2:

map the_map_p 
the_map_p = new() 
put(the_map_p, 10, "ten") 
put(the_map_p, 20, "twenty") 
put(the_map_p, 30, "thirty") 
put(the_map_p, 40, "forty") 
 
sequence values 
values = values(the_map_p, { 10, 50, 30, 9000 }) 
-- values WILL be { "ten", 0, "thirty", 0 } 
values = values(the_map_p, { 10, 50, 30, 9000 }, {-1,-2,-3,-4}) 
-- values WILL be { "ten", -2, "thirty", -4 }

11.3.6.19.6 See Also:

get, keys, pairs

11.3.6.20 pairs

include std/map.e 
public function pairs(map the_map_p, integer sorted_result = 0)

Return all key/value pairs in a map.

11.3.6.20.1 Parameters:

the_map_p : the map to get the data from
sorted_result : optional integer. 0 [default] means do not sort the output and 1 means to sort the output before returning.

11.3.6.20.2 Returns:

A sequence, of all key/value pairs stored in the_map_p. Each pair is a sub-sequence in the form {key, value}

11.3.6.20.3 Comments:

If sorted_result is not used, the order of the values returned is not predicable.

11.3.6.20.4 Example 1:

map the_map_p 
the_map_p = new() 
put(the_map_p, 10, "ten") 
put(the_map_p, 20, "twenty") 
put(the_map_p, 30, "thirty") 
put(the_map_p, 40, "forty") 
 
sequence keyvals 
keyvals = pairs(the_map_p) -- might be {{20,"twenty"},{40,"forty"},{10,"ten"},{30,"thirty"}} 
keyvals = pairs(the_map_p, 1) -- will be {{10,"ten"},{20,"twenty"},{30,"thirty"},{40,"forty"}}

11.3.6.20.5 See Also:

get, keys, values

11.3.6.21 optimize

include std/map.e 
public procedure optimize(map the_map_p, integer max_p = 25, atom grow_p = 1.333)

Widens a map to increase performance.

11.3.6.21.1 Parameters:

the_map_p : the map being optimized
max_p : an integer, the maximum desired size of a bucket. Default is 25. This must be 3 or higher.
grow_p : an atom, the factor to grow the number of buckets for each iteration of rehashing. Default is 1.333. This must be greater than 1.

11.3.6.21.2 Returns:

The optimized map.

11.3.6.21.3 Comments:

This rehashes the map until either the maximum bucket size is less than the desired maximum or the maximum bucket size is less than the largest size statistically expected (mean + 3 standard deviations).

11.3.6.21.4 See Also:

statistics, rehash

11.3.6.22 load_map

include std/map.e 
public function load_map(object file_name_p)

Loads a map from a file

11.3.6.22.1 Parameters:

file_name_p : The file to load from. This file may have been created by the save_map function. This can either be a name of a file or an already opened file handle.

11.3.6.22.2 Returns:

Either a map, with all the entries found in file_name_p, or -1 if the file failed to open.

11.3.6.22.3 Comments:

If file_name_p is an already opened file handle, this routine will write to that file and not close it. Otherwise, the named file will be created and closed by this routine.

The input file can be either one created by the save_map function or a manually created/edited text file. See save_map for details about the required layout of the text file.

11.3.6.22.4 Example 1:

   object loaded 
   map AppOptions 
   sequence SavedMap = "c:\myapp\options.txt" 
   loaded = load_map(SavedMap) 
   if equal(loaded, -1) then 
      crash("Map '%s' failed to open", SavedMap) 
   end if 
   -- By now we know that it was loaded and a new map created, 
   -- so we can assign it to a 'map' variable. 
   AppOptions = loaded 
   if get(AppOptions, "verbose", 1) = 3 then 
       ShowIntructions() 
   end if

11.3.6.22.5 See Also:

new, save_map

11.3.6.23 SM_TEXT

include std/map.e 
public enum SM_TEXT

Saves a map to a file.

11.3.6.23.1 Parameters:

m : a map.
file_name_p : Either a sequence, the name of the file to save to, or an open file handle as returned by open ().
type : an integer. SM_TEXT for a human-readable format (default), SM_RAW for a smaller and faster format, but not human-readable.

11.3.6.23.2 Returns:

An integer, the number of keys saved to the file, or -1 if the save failed.

11.3.6.23.3 Comments:

If file_name_p is an already opened file handle, this routine will write to that file and not close it. Otherwise, the named file will be created and closed by this routine.

The SM_TEXT type saves the map keys and values in a text format which can be read and edited by standard text editor. Each entry in the map is saved as a KEY/VALUE pair in the form

key = value

Note that if the 'key' value is a normal string value, it can be enclosed in double quotes. If it is not thus quoted, the first character of the key determines its EUPHORIA value type. A dash or digit implies an atom, an left-brace implies a sequence, an alphabetic character implies a text string that extends to the next equal '=' symbol, and anything else is ignored.

Note that if a line contains a double-dash, then all text from the double-dash to the end of the line will be ignored. This is so you can optionally add comments to the saved map. Also, any blank lines are ignored too.

All text after the '=' symbol is assumed to be the map item's value data.

The SM_RAW type saves the map in an efficient manner. It is generally smaller than the text format and is faster to process, but it is not human readable and standard text editors can not be used to edit it. In this format, the file will

11.3.6.23.4 contain three serialized sequences:

Header sequence: {integer:format version, string: date and time of save (YYMMDDhhmmss), sequence: euphoria version {major, minor, revision, patch}}
Keys. A list of all the keys
Values. A list of the corresponding values for the keys.

11.3.6.23.5 Example 1:

   map AppOptions 
   if save_map(AppOptions, "c:\myapp\options.txt") = -1 
       Error("Failed to save application options") 
   end if 
   if save_map(AppOptions, "c:\myapp\options.dat", SM_RAW) = -1 
       Error("Failed to save application options") 
   end if

11.3.6.23.6 See Also:

load_map

11.3.6.24 save_map

include std/map.e 
public function save_map(map the_map_, object file_name_p, integer type_ = SM_TEXT)

11.3.6.25 copy

include std/map.e 
public function copy(map source_map, object dest_map = 0, integer put_operation = PUT)

Duplicates a map.

11.3.6.25.1 Parameters:

source_map : map to copy from
dest_map : optional, map to copy to
put_operation : optional, operation to use when dest map## is used. The default is PUT.

11.3.6.25.2 Returns:

If dest_map was not provided, an exact duplicate of source_map otherwise dest_map, which does not have to be empty, is returned with the new values copied from source_map, according to the put_operation value.

11.3.6.25.3 Example 1:

map m1 = new() 
put(m1, 1, "one") 
put(m1, 2, "two") 
 
map m2 = copy(m1) 
printf(1, "%s, %s\n", { get(m2, 1), get(m2, 2) }) 
-- one, two 
 
put(m1, 1, "one hundred") 
printf(1, "%s, %s\n", { get(m1, 1), get(m1, 2) }) 
-- one hundred, two 
 
printf(1, "%s, %s\n", { get(m2, 1), get(m2, 2) }) 
-- one, two

11.3.6.25.4 Example 2:

map m1 = new() 
map m2 = new() 
 
put(m1, 1, "one") 
put(m1, 2, "two") 
put(m2, 3, "three") 
 
copy(m1, m2) 
 
? keys(m2) 
-- { 1, 2, 3 }

11.3.6.25.5 Example 3:

map m1 = new() 
map m2 = new() 
 
put(m1, "XY", 1) 
put(m1, "AB", 2) 
put(m2, "XY", 3) 
 
? pairs(m1)  -- { {"AB", 2}, {"XY", 1} } 
? pairs(m2)  -- { {"XY", 3} } 
 
-- Add same keys' values. 
copy(m1, m2, ADD) 
 
? pairs(m2) 
-- { {"AB", 2}, {"XY", 4} }

11.3.6.25.6 See Also:

put

11.3.6.26 new_from_kvpairs

include std/map.e 
public function new_from_kvpairs(sequence kv_pairs)

Converts a set of Key-Value pairs to a map.

11.3.6.26.1 Parameters:

kv_pairs : A seqeuence containing any number of subsequences that have the format {KEY, VALUE}. These are loaded into a new map which is then returned by this function.

11.3.6.26.2 Returns:

A map, containing the data from kv_pairs

11.3.6.26.3 Example 1:

map m1 = new_from_kvpairs( { 
        {"application", "EUPHORIA"}, 
        {"version", "4.0"}, 
        {"genre", "programming language"}, 
        {"crc", 0x4F71AE10} 
           }) 
 
v = map:get(m1, "application") --> "EUPHORIA"

11.3.6.27 new_from_string

include std/map.e 
public function new_from_string(sequence kv_string)

Converts a set of Key-Value pairs contained in a string to a map.

11.3.6.27.1 Parameters:

kv_string : A string containing any number of lines that have the format KEY=VALUE. These are loaded into a new map which is then returned by this function.

11.3.6.27.2 Returns:

A map, containing the data from kv_string

11.3.6.27.3 Comment:

This function actually calls keyvalues () to convert the string to key-value pairs, which are then used to create the map.

11.3.6.27.4 Example 1:

Given that a file called "xyz.config" contains the lines ...

application = EUPHORIA, 
version     = 4.0, 
genre       = "programming language", 
crc         = 4F71AE10

map m1 = new_from_string( read_file("xyz.config", TEXT_MODE)) 
 
printf(1, "%s\n", {map:get(m1, "application")}) --> "EUPHORIA" 
printf(1, "%s\n", {map:get(m1, "genre")})       --> "programming language" 
printf(1, "%s\n", {map:get(m1, "version")})     --> "4.0" 
printf(1, "%s\n", {map:get(m1, "crc")})         --> "4F71AE10"

11.3.6.28 for_each

include std/map.e 
public function for_each(map source_map, integer user_rid, object user_data = 0, integer in_sorted_order = 0)

Calls a user-defined routine for each of the items in a map.

11.3.6.28.1 Parameters:

source_map : The map containing the data to process
user_rid: The routine_id of a user defined processing function
user_data: An object. Optional. This is passed, unchanged to each call of the user defined routine. By default, zero (0) is used.
in_sorted_order: An integer. Optional. If non-zero the items in the map are processed in ascending key sequence otherwise the order is undefined. By default they are not sorted.

11.3.6.28.2 Returns:

An integer: 0 means that all the items were processed, and anything else is whatever was returned by the user routine to abort the for_each() process.

11.3.6.28.3 Comment:

The user defined routine is a function that must accept four parameters.

Object: an Item Key
Object: an Item Value
Object: The user_data value. This is never used by for_each() itself, merely passed to the user routine.
Integer: Progress code.

The abs() value of the progress code is the ordinal call number. That is 1 means the first call, 2 means the second call, etc ...
If the progress code is negative, it is also the last call to the routine.
If the progress code is zero, it means that the map is empty and thus the item key and value cannot be used.

The user routine must return 0 to get the next map item. Anything else will cause for_each() to stop running, and is returned to whatever called for_each().

11.3.6.28.4 Example 1:

include std/map.e 
include std/math.e 
include std/io.e 
  function Process_A(object k, object v, object d, integer pc) 
    writefln("[] = []", {k, v}) 
    return 0 
  end function 
 
  function Process_B(object k, object v, object d, integer pc) 
    if pc = 0 then 
      writefln("The map is empty") 
    else 
      integer c 
      c = abs(pc) 
      if c = 1 then 
          writefln("---[]---", {d}) -- Write the report title. 
      end if 
      writefln("[]: [:15] = []", {c, k, v}) 
      if pc < 0 then 
          writefln(repeat('-', length(d) + 6), {}) -- Write the report end. 
      end if 
    end if 
    return 0 
  end function 
 
  map m1 = new() 
  map:put(m1, "application", "EUPHORIA") 
  map:put(m1, "version", "4.0") 
  map:put(m1, "genre", "programming language") 
  map:put(m1, "crc", "4F71AE10") 
 
  -- Unsorted  
  map:for_each(m1, routine_id("Process_A")) 
  -- Sorted 
  map:for_each(m1, routine_id("Process_B"), "List of Items", 1)

The output from the first call could be...

application = EUPHORIA 
version = 4.0 
genre = programming language 
crc = 4F71AE10

The output from the second call should be...

---List of Items--- 
1: application     = EUPHORIA 
2: crc             = 4F71AE10 
3: genre           = programming language 
4: version         = 4.0 
-------------------

11.4 Stack

Page Contents

---------- Constants

---------------- FIFO

---------- Types

---------------- stack

---------- Routines

---------------- new

---------------- is_empty

---------------- size

---------------- at

---------------- push

---------------- top

---------------- last

---------------- pop

---------------- peek_top

---------------- peek_end

---------------- swap

---------------- dup

---------------- set

---------------- clear

11.4.1 Constants

11.4.1.1 FIFO

include std/stack.e 
public constant FIFO

Stack types

FIFO: like people standing in line: first item in is first item out
FILO: like for a stack of plates : first item in is last item out

11.4.2 Types

11.4.2.1 stack

include std/stack.e 
public type stack(object obj_p)

A stack is a sequence of objects with some internal data.

11.4.3 Routines

11.4.3.1 new

include std/stack.e 
public function new(integer typ = FILO)

Create a new stack.

11.4.3.1.1 Parameters:

stack_type : an integer, defining the semantics of the stack. The default is FILO.

11.4.3.1.2 Returns:

An empty stack, note that the variable storing the stack must not be an integer. The resources allocated for the stack will be automatically cleaned up if the reference count of the returned value drops to zero, or if passed in a call to delete .

11.4.3.1.3 Comments:

There are two sorts of stacks, designated by the types FIFO and FILO:

A FIFO stack is one where the first item to be pushed is popped first. People standing in queue form a FIFO stack.
A FILO stack is one where the item pushed last is popped first. A column of coins is of the FILO kind.

11.4.3.1.4 See Also:

is_empty

11.4.3.2 is_empty

include std/stack.e 
public function is_empty(stack sk)

Determine whether a stack is empty.

11.4.3.2.1 Parameters:

sk : the stack being queried.

11.4.3.2.2 Returns:

An integer, 1 if the stack is empty, else 0.

11.4.3.2.3 See Also:

size

11.4.3.3 size

include std/stack.e 
public function size(stack sk)

Returns how many elements a stack has.

11.4.3.3.1 Parameters:

sk : the stack being queried.

11.4.3.3.2 Returns:

An integer, the number of elements in sk.

11.4.3.4 at

include std/stack.e 
public function at(stack sk, integer idx = 1)

Fetch a value from the stack without removing it from the stack.

11.4.3.4.1 Parameters:

sk : the stack being queried
idx : an integer, the place to inspect. The default is 1 (top item).

11.4.3.4.2 Returns:

An object, the idx-th item of the stack.

11.4.3.4.3 Errors:

If the supplied value of idx does not correspond to an existing element, an error occurs.

11.4.3.4.4 Comments:

For FIFO stacks (queues), the top item is the oldest item in the stack.
For FILO stacks, the top item is the newest item in the stack.

idx can be less than 1, in which case it refers relative to the end item. Thus, 0 stands for the end element.

11.4.3.4.5 Example 1:

stack sk = new(FILO) 
push(sk,5) 
push(sk,"abc") 
push(sk,2.3) 
? at(sk,0) -- 5 
? at(sk,-1) -- "abc" 
? at(sk,1) -- 2.3 
? at(sk,2) -- "abc"

11.4.3.4.6 Example 2:

stack sk = new(FIFO) 
push(sk,5) 
push(sk,"abc") 
push(sk,2.3) 
? at(sk,0) -- 2.3 
? at(sk,-1) -- "abc" 
? at(sk,1) -- 5 
? at(sk,2) -- "abc"

11.4.3.4.7 See Also:

size, top, peek_top, peek_end

11.4.3.5 push

include std/stack.e 
public procedure push(stack sk, object value)

Adds something to a stack.

11.4.3.5.1 Parameters:

sk : the stack to augment
value : an object, the value to push.

11.4.3.5.2 Comments:

value appears at the end of FIFO stacks and the top of FILO stacks. The size of the stack increases by one.

11.4.3.5.3 Example 1:

stack sk = new(FIFO) 
push(sk,5) 
push(sk,"abc") 
push(sk, 2.3) 
? top(sk) -- 5 
? last(sk) -- 2.3

11.4.3.5.4 Example 2:

stack sk = new(FILO) 
push(sk,5) 
push(sk,"abc") 
push(sk, 2.3) 
? top(sk) -- 2.3 
? last(sk) -- 5

11.4.3.5.5 See Also:

pop, top

11.4.3.6 top

include std/stack.e 
public function top(stack sk)

Retrieve the top element on a stack.

11.4.3.6.1 Parameters:

sk : the stack to inspect.

11.4.3.6.2 Returns:

An object, the top element on a stack.

11.4.3.6.3 Comments:

This call is equivalent to at(sk,1).

11.4.3.6.4 Example 1:

stack sk = new(FILO) 
push(sk,5) 
push(sk,"abc") 
push(sk, 2.3) 
? top(sk) -- 2.3

11.4.3.6.5 Example 1:

stack sk = new(FIFO) 
push(sk,5) 
push(sk,"abc") 
push(sk, 2.3) 
? top(sk) -- 5

11.4.3.6.6 See Also:

at, pop, peek_top, last

11.4.3.7 last

include std/stack.e 
public function last(stack sk)

Retrieve the end element on a stack.

11.4.3.7.1 Parameters:

sk : the stack to inspect.

11.4.3.7.2 Returns:

An object, the end element on a stack.

11.4.3.7.3 Comments:

This call is equivalent to at(sk,0).

11.4.3.7.4 Example 1:

stack sk = new(FILO) 
push(sk,5) 
push(sk,"abc") 
push(sk, 2.3) 
? last(sk) -- 5

11.4.3.7.5 Example 2:

stack sk = new(FIFO) 
push(sk,5) 
push(sk,"abc") 
push(sk, 2.3) 
? last(sk) -- 2.3

11.4.3.7.6 See Also:

at, pop, peek_end, top

11.4.3.8 pop

include std/stack.e 
public function pop(stack sk, integer idx = 1)

Removes an object from a stack.

11.4.3.8.1 Parameters:

sk : the stack to pop
idx : integer. The n-th item to pick from the stack. The default is 1.

11.4.3.8.2 Returns:

An item, from the stack, which is also removed from the stack.

11.4.3.8.3 Errors:

If the stack is empty, an error occurs.
If the idx is greater than the number of items in the stack, an error occurs.

11.4.3.8.4 Comments:

For FIFO stacks (queues), the top item is the oldest item in the stack.
For FILO stacks, the top item is the newest item in the stack.

When idx is omitted the 'top' of the stack is removed and returned. When idx is supplied, it represents the N-th item from the top to be removed and returned. Thus an idx of 2 returns the 2nd item from the top, a value of 3 returns the 3rd item from the top, etc ...

11.4.3.8.5 Example 1:

stack sk = new(FIFO) 
push(sk, 1) 
push(sk, 2) 
push(sk, 3) 
? size(sk) -- 3 
? pop(sk) -- 1 
? size(sk) -- 2 
? pop(sk) -- 2 
? size(sk) -- 1 
? pop(sk) -- 3 
? size(sk) -- 0 
? pop(sk) -- *error*

11.4.3.8.6 Example 2:

stack sk = new(FILO) 
push(sk, 1) 
push(sk, 2) 
push(sk, 3) 
? size(sk) -- 3 
? pop(sk) -- 3 
? size(sk) -- 2 
? pop(sk) -- 2 
? size(sk) -- 1 
? pop(sk) -- 1 
? size(sk) -- 0 
? pop(sk) -- *error*

11.4.3.8.7 Example 3:

stack sk = new(FILO) 
push(sk, 1) 
push(sk, 2) 
push(sk, 3) 
push(sk, 4) 
-- stack contains {1,2,3,4} (oldest to newest) 
? size(sk) -- 4 
? pop(sk, 2) -- Pluck out the 2nd newest item .. 3 
? size(sk) -- 3  
-- stack now contains {1,2,4}

11.4.3.8.8 Example 4:

stack sk = new(FIFO) 
push(sk, 1) 
push(sk, 2) 
push(sk, 3) 
push(sk, 4) 
-- stack contains {1,2,3,4} (oldest to newest) 
? size(sk) -- 4 
? pop(sk, 2) -- Pluck out the 2nd oldest item .. 2 
? size(sk) -- 3  
-- stack now contains {1,3,4}

11.4.3.8.9 See Also:

push, top, is_empty

11.4.3.9 peek_top

include std/stack.e 
public function peek_top(stack sk, integer idx = 1)

Gets an object, relative to the top, from a stack.

11.4.3.9.1 Parameters:

sk : the stack to get from.
idx : integer. The n-th item to get from the stack. The default is 1.

11.4.3.9.2 Returns:

An item, from the stack, which is not removed from the stack.

11.4.3.9.3 Errors:

If the stack is empty, an error occurs.
If the idx is greater than the number of items in the stack, an error occurs.

11.4.3.9.4 Comments:

This is identical to pop except that it does not remove the item.

For FIFO stacks (queues), the top item is the oldest item in the stack.
For FILO stacks, the top item is the newest item in the stack.

When idx is omitted the 'top' of the stack is returned. When idx is supplied, it represents the N-th item from the top to be returned. Thus an idx of 2 returns the 2nd item from the top, a value of 3 returns the 3rd item from the top, etc ...

11.4.3.9.5 Example 1:

stack sk = new(FIFO) 
push(sk, 1) 
push(sk, 2) 
push(sk, 3) 
? peek_top(sk) -- 1 
? peek_top(sk,2) -- 2 
? peek_top(sk,3) -- 3 
? peek_top(sk,4) -- *error* 
? peek_top(sk, size(sk)) -- 3 (end item)

11.4.3.9.6 Example 2:

stack sk = new(FILO) 
push(sk, 1) 
push(sk, 2) 
push(sk, 3) 
? peek_top(sk) -- 3 
? peek_top(sk,2) -- 2 
? peek_top(sk,3) -- 1 
? peek_top(sk,4) -- *error* 
? peek_top(sk, size(sk)) -- 1 (end item)

11.4.3.9.7 See Also:

pop, top, is_empty, size, peek_end

11.4.3.10 peek_end

include std/stack.e 
public function peek_end(stack sk, integer idx = 1)

Gets an object, relative to the end, from a stack.

11.4.3.10.1 Parameters:

sk : the stack to get from.
idx : integer. The n-th item from the end to get from the stack. The default is 1.

11.4.3.10.2 Returns:

An item, from the stack, which is not removed from the stack.

11.4.3.10.3 Errors:

If the stack is empty, an error occurs.
If the idx is greater than the number of items in the stack, an error occurs.

11.4.3.10.4 Comments:

For FIFO stacks (queues), the end item is the newest item in the stack.
For FILO stacks, the end item is the oldest item in the stack.

When idx is omitted the 'end' of the stack is returned. When idx is supplied, it represents the N-th item from the end to be returned. Thus an idx of 2 returns the 2nd item from the end, a value of 3 returns the 3rd item from the end, etc ...

11.4.3.10.5 Example 1:

stack sk = new(FIFO) 
push(sk, 1) 
push(sk, 2) 
push(sk, 3) 
? peek_end(sk) -- 3 
? peek_end(sk,2) -- 2 
? peek_end(sk,3) -- 1 
? peek_end(sk,4) -- *error* 
? peek_end(sk, size(sk)) -- 3 (top item)

11.4.3.10.6 Example 2:

stack sk = new(FILO) 
push(sk, 1) 
push(sk, 2) 
push(sk, 3) 
? peek_end(sk) -- 1 
? peek_end(sk,2) -- 2 
? peek_end(sk,3) -- 3 
? peek_end(sk,4) -- *error* 
? peek_end(sk, size(sk)) -- 3 (top item)

11.4.3.10.7 See Also:

pop, top, is_empty, size, peek_top

11.4.3.11 swap

include std/stack.e 
public procedure swap(stack sk)

Swap the top two elements of a stack

11.4.3.11.1 Parameters:

sk : the stack to swap.

11.4.3.11.2 Returns:

A copy, of the original stack, with the top two elements swapped.

11.4.3.11.3 Comments:

For FIFO stacks (queues), the top item is the oldest item in the stack.
For FILO stacks, the top item is the newest item in the stack.

11.4.3.11.4 Errors:

If the stack has less than two elements, an error occurs.

11.4.3.11.5 Example 1:

stack sk = new(FILO) 
push(sk,5) 
push(sk,"abc") 
push(sk, 2.3) 
push(sk, "") 
? peek_top(sk,1)  -- "" 
? peek_top(sk,2)  -- 2.3 
swap(sk) 
? peek_top(sk,1)  -- 2.3 
? peek_top(sk,2)  -- ""

11.4.3.11.6 Example 2:

stack sk = new(FIFO) 
push(sk,5) 
push(sk,"abc") 
push(sk, 2.3) 
push(sk, "") 
? peek_top(sk,1)  -- 5 
? peek_top(sk,2)  -- "abc" 
swap(sk) 
? peek_top(sk,1)  -- "abc" 
? peek_top(sk,2)  -- 5

11.4.3.12 dup

include std/stack.e 
public procedure dup(stack sk)

Repeat the top element of a stack.

11.4.3.12.1 Parameters:

sk : the stack.

11.4.3.12.2 Side effects:

The value of top() is pushed onto the stack, thus the stack size grows by one.

11.4.3.12.3 Comments:

For FIFO stacks (queues), the top item is the oldest item in the stack.
For FILO stacks, the top item is the newest item in the stack.

11.4.3.12.4 Errors:

If the stack has no elements, an error occurs.

11.4.3.12.5 Example 1:

stack sk = new(FILO) 
push(sk,5) 
push(sk,"abc") 
push(sk, "") 
dup(sk) 
? peek_top(sk,1)  -- "" 
? peek_top(sk,2)  -- "abc" 
? size(sk)  -- 3 
dup(sk) 
? peek_top(sk,1)  -- "" 
? peek_top(sk,2)  -- "" 
? peek_top(sk,3)  -- "abc" 
? size(sk)  -- 4

11.4.3.12.6 Example 1:

stack sk = new(FIFO) 
push(sk,5) 
push(sk,"abc") 
push(sk, "") 
dup(sk) 
? peek_top(sk,1)  -- 5 
? peek_top(sk,2)  -- "abc" 
? size(sk)  -- 3 
dup(sk) 
? peek_top(sk,1)  -- 5 
? peek_top(sk,2)  -- 5 
? peek_top(sk,3)  -- "abc" 
? size(sk)  -- 4

11.4.3.13 set

include std/stack.e 
public procedure set(stack sk, object val, integer idx = 1)

Update a value on the stack

11.4.3.13.1 Parameters:

sk : the stack being queried
val : an object, the value to place on the stack
idx : an integer, the place to inspect. The default is 1 (the top item)

11.4.3.13.2 Errors:

If the supplied value of idx does not correspond to an existing element, an error occurs.

11.4.3.13.3 Comments:

For FIFO stacks (queues), the top item is the oldest item in the stack.
For FILO stacks, the top item is the newest item in the stack.

idx can be less than 1, in which case it refers to an element relative to the end of the stack. Thus, 0 stands for the end element.

11.4.3.13.4 See Also:

size, top

11.4.3.14 clear

include std/stack.e 
public procedure clear(stack sk)

Wipe out a stack.

11.4.3.14.1 Parameters:

sk : the stack to clear.

11.4.3.14.2 Side effect:

The stack contents is emptied.

11.4.3.14.3 See Also:

new, is_empty

11.5 Sets

---------- Types

---------------- set

---------------- map

---------------- operation

---------- Inclusion and belonging.

---------------- sequence_to_set

---------------- cardinal

---------------- belongs_to

---------------- add_to

---------------- remove_from

---------------- is_subset

---------------- embedding

---------------- embed_union

---------------- subsets

---------- Basic set-theoretic operations.

---------------- intersection

---------------- union

---------------- delta

---------------- difference

---------------- product

---------- Maps between sets.

---------------- define_map

---------------- sequences_to_map

---------------- image

---------------- range

---------------- direct_map

---------------- restrict

---------------- change_target

---------------- combine_maps

---------------- compose_map

---------------- diagram_commutes

---------------- is_injective

---------------- is_surjective

---------------- is_bijective

---------- Reverse mappings

---------------- fiber_over

---------------- reverse_map

---------------- section

---------- Products

---------------- product_map

---------------- amalgamated_sum

---------------- fiber_product

---------- Constants

---------------- SIDE_NONE

---------- Operations on sets

---------------- define_operation

---------------- is_symmetric

---------------- is_associative

---------------- all_left_units

---------------- all_right_units

---------------- has_unit

---------------- is_unit

---------------- has_inverse

---------------- distributes_over

The sets.e module defines a type for sets and provides basic tools for handling them.

Other modules may be built upon them, for instance graph handling or simple topology, finite groups etc.

11.5.1 Notes:

A set is an ordered sequence in ascending order, not more, not less
A map from setA to setB is a sequence the length of setA whose elements are indexes into setB, followed by {length(setA),length(setB)}.
An operation of E x F ==> G is a two dimensional sequence of elements of G, indexed by E x F, and the triple {card(E),card(F),card(G)}.

11.5.2 Types

11.5.2.1 set

include std/sets.e 
public type set(object s)

A set is a sequence in which each item is greater than the previous item.

11.5.2.1.1 See Also:

compare

11.5.2.2 map

include std/sets.e 
public type map(object s)

Returns 1 if a sequence of integers is a valid map descriptor, else 0.

11.5.2.2.1 Comments:

A map is a sequence of indexes. Each index is between 1 and the maximum allowed for the particular map.

Actually, what is being called a map is a class of maps, as the elements of the input sequence, except for the last two, are ordinals rather than set elements. A map contains the information required to map as expected the elements of a set, given by index, to another set, where the images are indexes again. Technically, those are maps of the category of finite sets quotiented by equality of cardinal.

The objects that map.e handle are completely unrelated to these.

11.5.2.2.2 Example 1:

sequence s0 = {2, 3, 4, 1, 4, 2, 6, 4} 
? map(s0)   -- prints out 1.

11.5.2.2.3 See also:

define_map, fiber_over, restrict, direct_map, [[:reverse_map], is_injective , is_surjective, is_bijective

11.5.2.3 operation

include std/sets.e 
public type operation(object s)

Returns 1 if the data represents a map from the product of two sets to a third one.

11.5.2.3.1 Comments:

An operation from FxG to H is defined as a sequence of mappings from G to H, plus the cardinals of the sets F, G and H. If the input data is consistent with this description, 1 is returned, else 0.

11.5.2.3.2 Example 1:

sequence s = {{{2, 3}, {3, 1}, {1, 2}, {2, 3}, {3, 1}}, {5,2,3}} 
-- s represents the addition modulo 3 from {0, 1, 2, 3, 4} x {1, 2} to {0, 1, 2} 
? operation(s)   -- prints out 1.

11.5.3 Inclusion and belonging.

11.5.3.1 sequence_to_set

include std/sets.e 
public function sequence_to_set(sequence s)

Makes a set out of a sequence by sorting it and removing duplicate elements.

11.5.3.1.1 Parameters:

s : the sequence to transform.

11.5.3.1.2 Returns:

A set, which is the ordered list of distinct elements in s.

11.5.3.1.3 Example 1:

  sequence s0 s0={1,3,7,5,7,4,1} 
  set s1 s1=sequence_to_set(s0)   -- s1 is now {1,3,4,5,7}

11.5.3.1.4 See also:

11.5.3.2 cardinal

include std/sets.e 
public function cardinal(set S)

Return the cardinal of a set

11.5.3.2.1 Parameters:

S : the set being queried.

11.5.3.2.2 Returns:

An integer, the count of elements in S.

11.5.3.2.3 See Also: