Книга: Язык программирования Euphoria. Справочное руководство

3. Алфавитный справочник по стандартным подпрограммам

от A до B

?

Синтаксис:

? x

Описание:

Это просто короткая форма записи для команды: pretty_print(1, x, {}), по которой на экране осуществляется печать величины объекта, заданного выражением. Для более наглядного отображения структуры объекта печать производится в столбик со скобками, запятыми и отступами. Единственное отличие от pretty_print() заключается в том, что печать по команде ? завершается ещё и автоматическим переводом курсора в начало новой строки.

Пример:

? {1, 2} + {3, 4} -- будет напечатано {4, 6}

См. также:

pretty_print, print

abort

Синтаксис:

abort(i)

Описание:

Прерывает исполнение программы. Аргумент i представляет собой небольшую целочисленную величину кода окончания программы, выдаваемого в операционную систему. Код окончания 0 в общем случае соответствует успешному завершению программы. Другие коды используются для указания на характер ошибки, по которой программа прервана. Пакетные программы DOS (.bat-файлы) могут считывать величину этого кода с помощью команды errorlevel. Программы Euphoria могут считывать эту величину, если дочерняя программа была запущена из подпрограммы system_exec().

Комментарии:

Подпрограмма abort() бывает особенно полезна, когда необходимо немедленно прервать исполнение программы изнутри глубоко вложенных вызовов подпрограмм, например, из-за обнаруженной опасной ошибки.

Если вы не применяете abort(), а программа завершается естественным порядком, интерпретаторы ex.exe/exw.exe/exu выдают в операционную систему код окончания 0. Если ваша программа прерывается по обнаруженной Euphoria ошибке времени компиляции или времени исполнения, выдаётся код 1.

Пример:

if x = 0 then
puts(ERR, "не могу делить на 0 !!!n")
abort(1)
else
z = y / x
end if

См. также:

crash_message, system_exec

all_palette

Платформа:

DOS32

Синтаксис:

include graphics.e

all_palette(s)

Описание:

Задаёт новые интенсивности цветов для всего набора цветов текущего графического режима. Аргумент s является рядом формы: {{r,g,b}, {r,g,b}, ..., {r,g,b}}

Каждый элемент ряда задаёт новую интенсивность цвета {красный, зелёный, синий} для соответствующего номера цвета, начиная с номера 0. Величины для красного (r), зелёного (g) и синего (b) должны быть в пределах от 0 до 63.

Комментарии:

Данная процедура исполняется значительно быстрее, чем если бы вы использовали palette() для задания новых интенсивностей цвета поочерёдно. Эта процедура может быть использована с read_bitmap() для быстрого вывода изображения на экран.

Пример программы:

demodos32bitmap.ex

См. также:

get_all_palette, palette, read_bitmap, video_config, graphics_mode

allocate

Синтаксис:

include machine.e

a = allocate(i)

Описание:

Подготавливает участок памяти, включающий i последовательных байтов. Выдаёт начальный адрес этого участка или 0, если память не может быть выделена. Выданный адрес позволит, как минимум, разместить очередные 4 байта, то есть, память выделяется участками, длина которых кратна 4, даже если i не кратно 4.

Комментарии:

Когда вы завершаете использование участка, вам следует подать адрес участка в процедуру free(). Тем самым участок будет освобожден и память станет доступной для других целей в пределах нужд вашей программы. Euphoria никогда не освободит ваш участок для повторного использования, если вы явно не вызвали free(). Когда ваша программа завершается, вся занятая ею память освобождается операционной системой для использования другими программами.

Пример:

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

См. также:

free, allocate_low, peek, poke, mem_set, call

allocate_low

Платформа:

DOS32

Синтаксис:

include machine.e

i2 = allocate_low(i1)

Описание:

Подготавливает i1 последовательных байтов в нижней памяти, т.е. в стандартной памяти (адрес ниже 1 мегабайта). Выдаёт начальный адрес участка памяти или 0, если память не может быть выделена.

Комментарии:

Некоторые обработчики прерываний DOS требуют, чтобы вы заносили в регистры один или несколько адресов. Эти адреса должны принадлежать к области стандартной памяти, чтобы DOS была способна читать и записывать по этим адресам.

Пример программы:

demodos32dosint.ex

См. также:

dos_interrupt, free_low, allocate, peek, poke

allocate_string

Синтаксис:

include machine.e

a = allocate_string(s)

Описание:

Подготавливает в памяти пространство для строкового (символьного) ряда s. Копирует ряд s в это пространство, заканчивая строку служебным символом 0, и трактуя каждый элемент ряда как единственный байт. Такой формат требуется для Си-строк. Выдаёт начальный адрес строки в памяти. Если участок памяти достаточного размера недоступен, выдаёт 0.

Комментарии:

Для освобождения пространства, отведённого под строку, используйте free() с адресом строки в качестве аргумента.

Пример:

atom title
title = allocate_string("The Wizard of Oz")

Пример программы:

demowin32window.exw

См. также:

allocate, free

allow_break

Синтаксис:

include file.e

allow_break(i)

Описание:

Если аргумент i = 1 (истина), команды control-c и control-Break получают возможность прервать вашу программу, когда она пытается в очередной раз обратиться к клавиатуре.

Если i = 0 (ложь), ваша программа не будет реагировать на команды control-c или control-Break.

Комментарии:

При нажатии клавиш control-c или control-Break DOS будет выводить ^C на экран, даже если ваша программа не может быть прервана.

Изначально ваша программа может быть прервана в любой точке, где она пытается читать с клавиатуры. Она может быть также прервана другими операциями ввода/вывода в зависимости от режима, установленного пользователем в его файле config.sys (уточните по руководству MS-DOS особенности команды BREAK). Но для некоторых типов программ возможность такого внезапного прерывание с клавиатуры может иметь некоторые негативные последствия и даже приводить в результате к потере данных. Вызов allow_break(0) позволяет вам избежать подобных опасных ситуаций.

И вы можете проверять, не нажимал ли пользователь control-c или control-Break, чтобы продуманно отреагировать на это нажатие и безопасно прервать программу. Для такой проверки служит функция check_break().

Пример:

allow_break(0) -- не дайте пользователю прикончить меня!

См. также:

check_break

and_bits

Синтаксис:

x3 = and_bits(x1, x2)

Описание:

Выполняет логическую операцию AND над соответствующими битами в x1 и x2. Бит в x3 устанавливается в 1, только если соответствующие биты в x1 и x2 оба равны 1.

Комментарии:

Аргументами данной функции могут быть атомы и ряды. Если аргументы являются рядами, применяются правила операций на рядах.

Аргументы должны быть представлены как 32-битные числа, со знаком или без знака.

Если вы намерены манипулировать полными 32-битными величинами, вы должны объявить переменные как atom, но не как integer. В Euphoria тип integer ограничен 31-битом.

Результат трактуется как число со знаком. Оно будет отрицательным, когда старший бит является 1.

Для лучшего понимания двоичного представления числа вы можете вызвать его на отображение в шестнадцатеричной записи. Используйте для этого команду printf() с форматом %x.

Пример 1:

a = and_bits(#0F0F0000, #12345678)
-- a равно #02040000

Пример 2:

a = and_bits(#FF, {#123456, #876543, #2211})
-- a равно {#56, #43, #11}

Пример 3:

a = and_bits(#FFFFFFFF, #FFFFFFFF)
-- a равно -1
-- заметьте, что #FFFFFFFF является положительным числом,
-- но результат побитовой логической операции трактуется
-- как 32-битное число со знаком, так что он отрицателен.

См. также:

or_bits, xor_bits, not_bits, int_to_bits

append

Синтаксис:

s2 = append(s1, x)

Описание:

Создаёт на базе s1 новый ряд, с x, добавленным в конец ряда s1 в качестве последнего элемента ряда s2. Длина ряда s2 будет равна length(s1) + 1, то есть, на один элемент больше длины исходного ряда s1.

Комментарии:

Если x является атомом, операция эквивалентна s2 = s1 & x Если x является рядом, - не эквивалентна.

Необходимая дополнительная память выделяется автоматически и очень эффективно, благодаря динамическому распределению памяти, работающему в Euphoria. Случай, когда s1 и s2 в действительности являются одним и тем же рядом (как в Примере 1 ниже), особенно оптимален.

Пример 1:

Вы можете применить append() для динамического удлинения ряда, т.е.

sequence x
x = {}
for i = 1 to 10 do
x = append(x, i)
end for
-- x теперь равен {1,2,3,4,5,6,7,8,9,10}

Пример 2:

Любой объект Euphoria может быть добавлен к ряду, т.е.

sequence x, y, z
x = {"fred", "barney"}
y = append(x, "wilma")
-- y теперь равен {"fred", "barney", "wilma"}
z = append(append(y, "betty"), {"bam", "bam"})
-- z теперь равен {"fred", "barney", "wilma", "betty", {"bam", "bam"}}

См. также:

prepend, оператор сцепления &, оператор формирования ряда

arccos

Синтаксис:

include misc.e

x2 = arccos(x1)

Описание:

Выдаёт угол, косинус которого равен x1.

Комментарии:

Аргумент, x1, должен быть в пределах от -1 до +1 включительно.

Результат, выраженный в радианах, будет находиться между 0 и PI.

Данная функция может быть применена к атому или ко всем элементам ряда.

Функция arccos() вычисляется не так быстро, как arctan().

Пример:

s = arccos({-1,0,1})
-- s равно {3.141592654, 1.570796327, 0}

См. также:

cos, arcsin, arctan

arcsin

Синтаксис:

include misc.e

x2 = arcsin(x1)

Описание:

Выдаёт угол, синус которого равен x1.

Комментарии:

Аргумент, x1, должен быть в пределах от -1 до +1 включительно.

Результат, выраженный в радианах, будет находиться между -PI/2 и +PI/2.

Данная функция может быть применена к атому или ко всем элементам ряда.

Функция arcsin() вычисляется не так быстро, как arctan().

Пример:

s = arcsin({-1,0,1})
-- s равно {-1.570796327, 0, 1.570796327}

См. также:

sin, arccos, arctan

arctan

Синтаксис:

x2 = arctan(x1)

Описание:

Выдаёт угол, тангенс которого равен x1.

Комментарии:

Результат, выраженный в радианах, будет между -PI/2 и PI/2.

Данная функция может быть применена к атому или ко всем элементам ряда.

Функция arctan() вычисляется быстрее, чем arcsin() или arccos().

Пример:

s = arctan({1,2,3})
-- s равно {0.785398, 1.10715, 1.24905}

См. также:

tan, arcsin, arccos

atom

Синтаксис:

i = atom(x)

Описание:

Выдаёт 1, если x является атомом, иначе выдаёт 0.

Комментарии:

Данная команда, в основном, служит для объявления переменных типа atom. Но вы можете также применять её подобно вызову функции, чтобы определить, не является ли объект атомом.

Пример 1:

atom a
a = 5.99

Пример 2:

object line
line = gets(0)
if atom(line) then
puts(SCREEN, "конец файлаn")
end if

См. также:

sequence, object, integer, атомы и ряды

atom_to_float32

Синтаксис:

include machine.e

s = atom_to_float32(a1)

Описание:

Преобразует атом Euphoria в ряд из 4-х однобайтовых величин. Эти 4 байта содержат представление числа с плавающей точкой в 32-х битном формате по стандарту IEEE.

Комментарии:

Атомы Euphoria могут иметь величины, соответствующие 64-битным числам с плавающей точкой стандарта IEEE, так что вы можете потерять точность при преобразовании их к 32-битным числам (16 значащих цифр против 7). Диапазон показателей экспонент также намного шире для 64-битных чисел, чем в 32-битном формате (308 против 38), поэтому некоторые атомы могут оказаться слишком большими или слишком маленькими для представления их в 32-битном формате. В этом случае вы получите одну из специальных 32-битных величин: inf или -inf (бесконечность или -бесконечность). Чтобы избежать этих ограничений, вы можете применить atom_to_float64().

Целочисленные величины также могут быть преобразованы в 32-битный формат с плавающей точкой.

Пример:

fn = open("numbers.dat", "wb")
puts(fn, atom_to_float32(157.82)) -- запись 4-х байтов в файл

См. также:

atom_to_float64, float32_to_atom

atom_to_float64

Синтаксис:

include machine.e

s = atom_to_float64(a1)

Описание:

Преобразует атом Euphoria в ряд, состоящий из 8 однобайтовых величин. Эти 8 байтов содержат представление числа с плавающей точкой в 64-битном формате по стандарту IEEE.

Комментарии:

Все атомы Euphoria имеют величины, которые могут быть представлены как 64-битные числа с плавающей точкой в формате по стандарту IEEE, поэтому вы можете преобразовать любой атом в 64-битный формат без всяких потерь точности.

Целочисленные величины также могут быть преобразованы в 64-битный формат с плавающей точкой.

Пример:

fn = open("numbers.dat", "wb")
puts(fn, atom_to_float64(157.82)) -- запись 8 байтов в файл

См. также:

atom_to_float32, float64_to_atom

bits_to_int

Синтаксис:

include machine.e

a = bits_to_int(s)

Описание:

Преобразует ряд, состоящий из единиц и нулей, дающих двоичное представление числа, в положительное десятичное число. Младший значащий "бит" должен быть первым членом ряда, s[1].

Комментарии:

Если вывести ряд s на печать, то младшие биты будут находиться слева, то есть в "инверсном" порядке по отношению к обычной форме записи, принятой для многоразрядных чисел, но это соглашение удобно, так как позволяет иметь возрастающие индексы для доступа к битам по мере возрастания веса битов.

Пример:

a = bits_to_int({1,1,1,0,1})
-- a равно 23 (двоичное 10111)

См. также:

int_to_bits, операции на рядах

bk_color

Синтаксис:

include graphics.e

bk_color(i)

Описание:

Устанавливает цвет фона в один из 16 стандартных цветов. В пиксельных режимах весь экран перекрашивается немедленно. В текстовых режимах любые новые символы, которые вы печатаете, будут появляться на фоне с новым цветом. В некоторых текстовых режимах для фона доступны только 8 различных цветов.

Комментарии:

16 стандартных цветов определены как константы в файле graphics.e.

В пиксельных режимах цвет 0, который обычно соответствует чёрному (BLACK), будет установлен в то самое значение палитры {r,g,b}, что и цвет номера i.

В некоторых пиксельных режимах на краю экрана появляется цветной бордюр. В 256-цветных режимах цвет бордюра соответствует 17-ому цвету палитры. Вы можете управлять цветом бордюра подобно всем другим цветам, используя процедуру palette().

В текстовых режимах для того, чтобы восстановить исходный цвет фона, когда ваша программа заканчивается, т.е. 0 - ЧЁРНЫЙ, вы должны вызвать процедуру bk_color(0). Если курсор находится на нижней строке экрана, целесообразно напечатать что-нибудь перед остановкой вашей программы. Напечатайте хотя бы 'n', и этого может быть достаточно.

Пример:

bk_color(BLACK)

См. также:

text_color, palette

bytes_to_int

Синтаксис:

include machine.e

a = bytes_to_int(s)

Описание:

Преобразует 4-х элементный ряд, состоящий из байтов, в атом. Элементы ряда s должны находиться в порядке, предусмотренном для 32-битных целых чисел на машинах 386+, т.е. младший значащий байт первый - s[1].

Комментарии:

Результат может быть больше, чем допускает тип integer, поэтому вы должны присваивать его значение атому.

Ряд s будет обычно содержать положительные величины, которые ранее были прочитаны оператором peek() из 4-х последовательных ячеек памяти.

Пример:

atom int32
int32 = bytes_to_int({37,1,0,0})
-- int32 равно 37 + 256*1 = 293

См. также:

int_to_bytes, bits_to_int, peek, peek4s, peek4u, poke

...

Оглавление книги