System/Docu/ru/Strings.odc

Strings
ENGLISH
Редакция перевода: Ф.В.Ткачев, 2010-10-07.

DEFINITION Strings;

	CONST
		charCode = -1; decimal = 10; hexadecimal = -2; roman = -3;
		digitspace = 8FX;
		hideBase = FALSE; showBase = TRUE;

	PROCEDURE Valid (IN s: ARRAY OF CHAR): BOOLEAN;
	PROCEDURE Extract (s: ARRAY OF CHAR; pos, len: INTEGER; OUT res: ARRAY OF CHAR);
	PROCEDURE Find (IN s: ARRAY OF CHAR; IN pat: ARRAY OF CHAR; start: INTEGER;
									OUT pos: INTEGER);
	PROCEDURE Replace (VAR s: ARRAY OF CHAR; pos, len: INTEGER; IN rep: ARRAY OF CHAR);
	PROCEDURE Lower (ch: CHAR): CHAR;
	PROCEDURE Upper (ch: CHAR): CHAR;
	PROCEDURE ToLower (in: ARRAY OF CHAR; OUT out: ARRAY OF CHAR);
	PROCEDURE ToUpper (in: ARRAY OF CHAR; OUT out: ARRAY OF CHAR);

	PROCEDURE IntToString (x: LONGINT; OUT s: ARRAY OF CHAR);
	PROCEDURE IntToStringForm (x: LONGINT; form, minWidth: INTEGER; fillCh: CHAR;
													showBase: BOOLEAN; OUT s: ARRAY OF CHAR);
	PROCEDURE RealToString (x: REAL; OUT s: ARRAY OF CHAR);
	PROCEDURE RealToStringForm (x: REAL; precision, minW, expW: INTEGER; fillCh: CHAR;
															OUT s: ARRAY OF CHAR);
	PROCEDURE StringToInt (IN s: ARRAY OF CHAR; OUT x, res: INTEGER);
	PROCEDURE StringToLInt (IN s: ARRAY OF CHAR; OUT x: LONGINT; OUT res: INTEGER);
	PROCEDURE StringToReal (IN s: ARRAY OF CHAR; OUT x: REAL; OUT res: INTEGER);

END Strings.


Модуль Strings  это небольшая простая билиотека для работы с литерными цепочками. Ее цель  предоставить несколько операций с цепочками, которые нужны часто и в то же время сложны для реализации, в том числе преобразования между числами и литерными цепочками. Библиотека оптимизирована в отношении удобства использования, а не эффективности.
Этот выбор проявляется в том, что некоторые операции, такие как Extract, используют параметры-значения вместо параметров-переменных IN. Это позволяет передавать одну и ту же переменную одновременно для ввода и вывода, что часто удобно (переменную никогда не следует передавать в несколько параметров IN/OUT/VAR одновременно, поскольку между ними могут возникнуть нежелательные взаимодействия).
Не ставилась цель предоставить операции для всех возможных обстоятельств, так как это нереально: обработка литерных цепочек в разных приложениях выполняется слишком по-разному. Часто полезно написать несколько операций для цепочек, приспособленных для конкретного приложения, что обычно сделать несложно. Более того, такие специальные операции могут быть оптимизированы по скорости, что невозможно для средств общего назначения.
Заметим, что язык Компонентный Паскаль предоставляет эффективную встроенную поддержку для присваиваний цепочек (неявных или явных с помощью оператора "$"), для конкатенации цепочек (посредством оператора "+") и для подсчета литер в цепочке (LEN(string$)).


CONST charCode
Возможное значение для параметра form процедуры IntToStringForm, запрашивающее преобразование целых в формат числового представления литерных констант Компонентного Паскаля, например, 0DX или 37X.

CONST decimal
Возможное значение для параметра form процедуры IntToStringForm, запрашивающее представление целых в десятичной форме.

CONST hexadecimal
Возможное значение для параметра form процедуры IntToStringForm, запрашивающее представление целых в шестнадцатиричной форме.

CONST roman
Возможное значение для параметра form процедуры IntToStringForm, запрашивающее представление целых в римской нотации.

CONST digitspace
Цифровой пробел имеет ширину цифры ноль (0), которая в большинстве шрифтов равна ширинам всех цифр и поэтому может быть использована для форматирования чисел.

CONST hideBase, showBase
Возможные значения для параметра showBase процедуры IntToStringForm, запрашивающий показ / подавление основания позиционного представления.


PROCEDURE  Valid (IN s: ARRAY OF CHAR): BOOLEAN
Возвращает TRUE, если и только если массив s содержит хотя бы один знак конца цепочки 0X.

Постусловие
s содержит символ 0X
	result = TRUE
s не содержит символ 0X
	result = FALSE

PROCEDURE Upper (ch: CHAR): CHAR
Преобразование в заглавные буквы. Обрабатывает набор символов ISO Latin-1. Литеры, не имеющие заглавного эквивалента (и литеры стандарта Unicode за пределами Latin-1), возвращаются без изменений.

PROCEDURE Lower (ch: CHAR): CHAR
Преобразование в строчные буквы. Обрабатывает набор символов ISO Latin-1. Литеры, не имеющие заглавного эквивалента (и литеры стандарта Unicode за пределами Latin-1), возвращаются без изменений.

PROCEDURE ToLower (in: ARRAY OF CHAR; OUT out: ARRAY OF CHAR)
Преобразует цепочку in к строчным буквам и записывает результат в out. Обрабатывает набор символов ISO Latin-1. Литеры, не имеющие заглавного эквивалента (и литеры стандарта Unicode за пределами Latin-1), возвращаются без изменений. Можно подставлять один и тот же фактический параметр для in и out.

Предусловие
Valid(in)	сбой индексации

Постусловие
Valid(out)

PROCEDURE ToUpper (in: ARRAY OF CHAR; OUT out: ARRAY OF CHAR)
Преобразует цепочку in к заглавным буквам и записывает результат в out. Обрабатывает набор символов ISO Latin-1. Литеры, не имеющие заглавного эквивалента (и литеры стандарта Unicode за пределами Latin-1), возвращаются без изменений. Можно подставлять один и тот же фактический параметр для in и out.

Предусловие
Valid(in)	index trap

Постусловие
Valid(out)

PROCEDURE Extract (s: ARRAY OF CHAR; pos, len: INTEGER; OUT res: ARRAY OF CHAR)
Извлекает из s фрагмент [pos, MIN(pos+len, Len(s))) и записывает его в res. Результат усекается, если res имеет недостаточный размер. Можно подставлять один и тот же фактический параметр для s и res.

Предусловие
len >= 0	20
pos >= 0	21
Valid(s)	(не проверяется)

Постусловие
Valid(res)
LEN(res$) = MAX(MIN(len, LEN(s'$)-pos, LEN(res)-1), 0)

PROCEDURE Replace (VAR s: ARRAY OF CHAR; pos, len: INTEGER; IN rep: ARRAY OF CHAR)
Заменяет фрагмент [pos, MIN(pos+len, Len(s))) в s на цепочку из rep. Литеры после заменяемого фрагмента, если нужно, сдвигаются. Результат усекается, если s имеет недостаточный размер.
Пояснение: если len = 0 то rep вставляется в s на позицию pos. Если LEN(rep$) = 0, то фрагмент [pos, MIN(pos+len, LEN(s$))) удаляется из s.

Предусловие
len >= 0	20
pos >= 0	21
Valid(s) & Valid(rep)	(не проверяется)

Постусловие
Valid(s)

PROCEDURE Find (IN s: ARRAY OF CHAR; IN pat: ARRAY OF CHAR; start: INTEGER;
								OUT pos: INTEGER);
Ищет первое вхождение шаблона pat в цепочке s, начиная с позиции start. Если шаблон найден, в pos возвращается позиция первой литеры шаблона в s. Если шаблон не найден, то pos = -1.

Предусловие
start >= 0	20
Valid(s) & Valid(pat)	(не проверяется)

Постусловие
шаблон найден
	pos - начальная позиция pat в s
шаблон не найден
	pos = -1

PROCEDURE  IntToStringForm (x: LONGINT; form, minWidth: INTEGER; fillCh: CHAR;
														showBase: BOOLEAN; OUT s: ARRAY OF CHAR)
Преобразует целое x в цепочку s. Если form  это charCode или hexadecimal, то x преобразуется к шестнадцатиричному представлению. В полном представлении должно быть по меньшей мере minWidth литер, причем дополнение до требуемой длины (если нужно) производится слева литерами fillCh.
Если showBase = TRUE, к представлению числа добавляется символьный суффикс, соответствующий форме представления. Значение form = charCode добавляет суффикс "X", а form = hexdecimal  суффикс "H". Кроме того, при этих значениях form для отрицательных значений используется дополнительное представление по соответствующему основанию шириной minWidth, то есть для отрицательных шестнадцатиричных чисел fillCh будет игнорироваться и вместо этого будет использоваться "F" (как для form = charCode, так и для form = hexadecimal). Для значений form в диапазоне 2..16 дополнительное представление не поддерживается.
Например
	x = -3, form = 16, minWidth = 4, fillCh = " " и showBase = FALSE даст результат -3
	x = -3, form = hexadecimal, minWidth = 4, fillCh = " " и showBase = FALSE даст результат FFFD
Если showBase = TRUE, а form  в диапазоне 2..16, то основание приписывается к числу через литеру "%" (например, "10111001%2").
Если form = roman (римские числа), то showBase игнорируется.

Следующие условия гарантируют, что массив s достаточно велик для размещения результата (Предусловие 23):
	form = roman: LEN(s) > MAX(minWidth, 15)
	(form = charCode) OR (form = hexadecimal) OR (form >= 2) & (form <= 16):
		LEN(s) > MAX(minWidth, 4 + <число цифр>)
		где <число цифр>  это 1 + Floor(Logbase(ABS(x))), если ABS(x) >= 1, и 1 в противном случае.
Заметим, что эти значения не являются наименьшими верхними границами для требуемой длины цепочки. В отдельных случаях фактические требования могут быть меньшими, но указанные границы гарантируют выполнение предусловия.

Предусловие
(form = charCode) OR (form = hexadecimal) OR (form = roman) OR ((form >= 2) & (form <= 16))	20
(form # roman) OR (form = roman) & (x > 0) & (x < 3999)	21
minWidth >= 0	22
массив s достаточно велик для размещения результат (см. выше)	23

Постусловие
Valid(s)

PROCEDURE IntToString (x: LONGINT; OUT s: ARRAY OF CHAR)
Записывает целое в формате по умолчанию.
За исключением быстродействия, эквивалентно:
	IntToStringForm(x, decimal, 0, digitspace, FALSE, s)

PROCEDURE RealToStringForm (x: REAL; precision, minW, expW: INTEGER;
														fillCh: CHAR; OUT s: ARRAY OF CHAR)
Преобразует вещественное x в цепочку s. Создаваемое представление числа может быть либо с фиксированной точкой, либо в научном формате, в зависимости от expW. precision задает количество значимых десятичных позиций (обычно 7 для коротких вещественных и 16 для обычных). minW задает минимальную длину в литерах. Если необходимо, слева будут добавлены литеры fillCh. Числа всегда округляются до последнего значимого и видимого разряда.
expW > 0: экспоненциальный формат (научный) с по меньшей мере expW цифрами в экспоненте.
expW = 0: формат с фиксированной или плавающей точкой, в зависимости от x.
expW < 0: формат с фиксированной точкой с -expW разрядами после десятичной точки.

Следующие условия подразумевают, что s достаточно велик для размещения результата (Предусловие 23):
	(x = inf) OR (x = -inf) OR (x = nan): LEN(s) > MAX(minW, 4)
	expW >= 0: LEN(s) > MAX(minW, precision + 7)
	expW < 0: LEN(s) > MAX(minW, 3 - expW + <число цифр до десятичной точки>)
	где <число цифр до десятичной точки> равно 1 + Floor(Log10(ABS(x))), если ABS(x) >= 1,
	и 1 в противном случае.
Заметим, что эти значения не являются наименьшими верхними границами для требуемой длины цепочки. В отдельных случаях фактические требования могут быть меньшими, но указанные границы гарантируют выполнение предусловия.

Предусловие
precision > 0	20
0 <= minW < LEN(s)	21
-LEN(s) < expW <= 3	22
s достаточно велик для размещения результата (см. выше)	23

Постусловие
Valid(s)

PROCEDURE RealToString (x: REAL; OUT s: ARRAY OF CHAR)
Записывает вещественное число в формате по умолчанию.
За исключением быстродействия, эквивалентно:
	RealToStringForm(x, 16, 0, 0, digitspace, s)

PROCEDURE StringToInt (IN s: ARRAY OF CHAR; OUT x, res: INTEGER)
PROCEDURE StringToLInt (IN s: ARRAY OF CHAR; OUT x: LONGINT; OUT res: INTEGER)
Преобразует число, представленное цепочкой s, в значение x. Допустимые представления числа следуют приведённым ниже синтаксическим правилам. Возможные коды результата: res = 1 при переполнении, res = 2 при синтаксической ошибке.

Синтаксис:
  number = ( [ "+" | "-" ] dec | hex ) 0X .
  dec = digit { digit } .
  hex = hexdigit { hexdigit } ("H" | "X") .
  hexdigit = digit | "A" | "B" | "C" | "D" | "E" | "F" .
  digit = "0" |  "1" |  "2" |  "3" |  "4" |  "5" |  "6" |  "7" |  "8" |  "9" .

Постусловие
s является допустимым представлением целого числа
	x  преобразованное целое число
	res = 0
s не является допустимым представлением целого числа
	res # 0

PROCEDURE StringToReal (IN s: ARRAY OF CHAR; OUT x: REAL; OUT res: INTEGER)
Преобразует цепочку s, заданную в фиксированной или научной нотации, в значение x. Возможные коды результата: res = 1 при переполнении, res = 2 при синтаксической ошибке.

Постусловие
s является допустимым представлением вещественного числа
	x  преобразованное вещественного число
	res = 0
s не является допустимым представлением вещественного числа
	res # 0