Справочное руководство Ada 2005

A.4.3 Обработка строк фиксированной длины

В языке определённый пакет Strings.Fixed предоставляет подпрограммы для обработки строк фиксированной длины; то есть, для значений типа Standard.String. Несколько из этих подпрограмм являются процедурами, которые изменяют содержимое строки, переданной в качестве параметра out или in out; каждая из них имеет дополнительные параметры для управления эффектом, когда логическая длина результата отличается от длины параметра.

Для каждой функции, возвращающей String, нижняя граница возвращаемого значения равна 1.

Основная модель, воплощённая в пакете, заключается в том, что строка фиксированной длины состоит из значимых символов и, возможно, заполнения (пробелами) с одной или обеих сторон. Когда более короткая строка копируется в более длинную строку, вставляется заполнение, а когда более длинная строка копируется в более короткую, заполнение удаляется. Процедура Move в пакете Strings.Fixed, которая принимает String в качестве параметра out, позволяет программисту управлять этими эффектами. Аналогичный контроль предоставляют процедуры преобразования строк.

Статическая семантика

Пакет библиотеки Strings.Fixed имеет следующее объявление:

with Ada.Strings.Maps;
package Ada.Strings.Fixed is
pragma Preelaborate(Fixed);

-- "Копирование" процедуры для строк с возможной разной длиной

procedure Move (Source : in String;
Target : out String;
Drop : in Truncation := Error;
Justify : in Alignment := Left;
Pad : in Character := Space);

-- Подпрограммы поиска

function Index (Source : in String;
Pattern : in String;
From : in Positive;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping := Maps.Identity)
return Natural;

function Index (Source : in String;
Pattern : in String;
From : in Positive;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping_Function)
return Natural;

function Index (Source : in String;
Pattern : in String;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping
:= Maps.Identity)
return Natural;

function Index (Source : in String;
Pattern : in String;
Going : in Direction := Forward;
Mapping : in Maps.Character_Mapping_Function)
return Natural;

function Index (Source : in String;
Set : in Maps.Character_Set;
From : in Positive;
Test : in Membership := Inside;
Going : in Direction := Forward)
return Natural;

function Index (Source : in String;
Set : in Maps.Character_Set;
Test : in Membership := Inside;
Going : in Direction := Forward)
return Natural;

function Index_Non_Blank (Source : in String;
From : in Positive;
Going : in Direction := Forward)
return Natural;

function Index_Non_Blank (Source : in String;
Going : in Direction := Forward)
return Natural;

function Count (Source : in String;
Pattern : in String;
Mapping : in Maps.Character_Mapping
:= Maps.Identity)
return Natural;

function Count (Source : in String;
Pattern : in String;
Mapping : in Maps.Character_Mapping_Function)
return Natural;

function Count (Source : in String;
Set : in Maps.Character_Set)
return Natural;

procedure Find_Token (Source : in String;
Set : in Maps.Character_Set;
Test : in Membership;
First : out Positive;
Last : out Natural);

-- Подпрограммы перевода строк

function Translate (Source : in String;
Mapping : in Maps.Character_Mapping)
return String;

procedure Translate (Source : in out String;
Mapping : in Maps.Character_Mapping);

function Translate (Source : in String;
Mapping : in Maps.Character_Mapping_Function)
return String;

procedure Translate (Source : in out String;
Mapping : in Maps.Character_Mapping_Function);

-- Подпрограммы преобразования строк

function Replace_Slice (Source : in String;
Low : in Positive;
High : in Natural;
By : in String)
return String;

procedure Replace_Slice (Source : in out String;
Low : in Positive;
High : in Natural;
By : in String;
Drop : in Truncation := Error;
Justify : in Alignment := Left;
Pad : in Character := Space);

function Insert (Source : in String;
Before : in Positive;
New_Item : in String)
return String;

procedure Insert (Source : in out String;
Before : in Positive;
New_Item : in String;
Drop : in Truncation := Error);

function Overwrite (Source : in String;
Position : in Positive;
New_Item : in String)
return String;

procedure Overwrite (Source : in out String;
Position : in Positive;
New_Item : in String;
Drop : in Truncation := Right);

function Delete (Source : in String;
From : in Positive;
Through : in Natural)
return String;

procedure Delete (Source : in out String;
From : in Positive;
Through : in Natural;
Justify : in Alignment := Left;
Pad : in Character := Space);

--Подпрограммы селектора строк
function Trim (Source : in String;
Side : in Trim_End)
return String;

procedure Trim (Source : in out String;
Side : in Trim_End;
Justify : in Alignment := Left;
Pad : in Character := Space);

function Trim (Source : in String;
Left : in Maps.Character_Set;
Right : in Maps.Character_Set)
return String;

procedure Trim (Source : in out String;
Left : in Maps.Character_Set;
Right : in Maps.Character_Set;
Justify : in Alignment := Strings.Left;
Pad : in Character := Space);

function Head (Source : in String;
Count : in Natural;
Pad : in Character := Space)
return String;

procedure Head (Source : in out String;
Count : in Natural;
Justify : in Alignment := Left;
Pad : in Character := Space);

function Tail (Source : in String;
Count : in Natural;
Pad : in Character := Space)
return String;

procedure Tail (Source : in out String;
Count : in Natural;
Justify : in Alignment := Left;
Pad : in Character := Space);

--Функции-конструкторы строк

function "*" (Left : in Natural;
Right : in Character) return String;

function "*" (Left : in Natural;
Right : in String) return String;

end Ada.Strings.Fixed;

Действия вышеперечисленных подпрограмм следующие.

procedure Move (Source : in String;
Target : out String;
Drop : in Truncation := Error;
Justify : in Alignment := Left;
Pad : in Character := Space);

Процедура Move копирует символы из Source в Target. Если Source имеет такую же длину, как Target, то результат — присвоение Source в Target. Если Source короче Target, то:

Если Justify=Left, то Source копируется в первые Source'Length символов Target.

Если Justify=Right, то Source копируется в последние Source'Length символов Target.

Если Justify=Center, то Source копируется в средние Source'Length символов Target. В этом случае, если разница в длине между Target и Source нечётная, то дополнительный символ Pad находится справа.

Pad копируется в каждый символ Target, не назначенный иначе.

Если Source длиннее Target, то результат зависит от Drop.

Если Drop=Left, то правых Target'Length символов Source копируются в Target.

Если Drop=Right, то левых Target'Length символов Source копируются в Target.

Если Drop=Error, то результат зависит от значения параметра Justify, а также от того, могут ли какие-либо символы в Source, кроме Pad, не быть скопированы:

Если Justify=Left, и если каждый из правых Source'Length-Target'Length символов в Source — Pad, то левых Target'Length символов Source копируются в Target.

Если Justify=Right, и если каждый из левых Source'Length-Target'Length символов в Source — Pad, то правых Target'Length символов Source копируются в Target.

В противном случае возникает ошибка Length_Error.

END_OF_DOCUMENT_MARKER

функция Index (Source : вход Строка;
Pattern : вход Строка;
From : вход Положительное;
Going : вход Направление := Вперёд;
Mapping : вход Maps.Character_Mapping := Maps.Identity)
возвращает Натуральное;

функция Index (Source : вход Строка;
Pattern : вход Строка;
From : вход Положительное;
Going : вход Направление := Вперёд;
Mapping : вход Maps.Character_Mapping_Function)
возвращает Натуральное;

Каждая функция Index ищет, начиная с From, фрагмент Source длиной Pattern'Length, который соответствует Pattern относительно Mapping; параметр Going указывает направление поиска. Если From не входит в Source'Range, то возникает Index_Error. Если Going = Вперёд, то Index возвращает наименьший индекс I, который больше или равен From, такой, что фрагмент Source, начинающийся с I, соответствует Pattern. Если Going = Назад, то Index возвращает наибольший индекс I, такой, что фрагмент Source, начинающийся с I, соответствует Pattern и имеет верхнюю границу, меньшую или равную From. Если такого фрагмента нет, возвращается 0. Если Pattern — пустая строка, то возникает Pattern_Error.

функция Index (Source : вход Строка;
Pattern : вход Строка;
Going : вход Направление := Вперёд;
Mapping : вход Maps.Character_Mapping
:= Maps.Identity)
возвращает Натуральное;

функция Index (Source : вход Строка;
Pattern : вход Строка;
Going : вход Направление := Вперёд;
Mapping : вход Maps.Character_Mapping_Function)
возвращает Натуральное;

Если Going = Вперёд, возвращает

Index (Source, Pattern, Source'First, Forward, Mapping);

в противном случае возвращает

Index (Source, Pattern, Source'Last, Backward, Mapping);

функция Index (Source : вход Строка;
Set : вход Maps.Character_Set;
From : вход Положительное;
Test : вход Членство := Внутри;
Going : вход Направление := Вперёд)
возвращает Натуральное;

Index ищет первое или последнее вхождение любого из набора символов (когда Test=Внутри), или любого из дополнения набора символов (когда Test=Снаружи). Если From не входит в Source'Range, то возникает Index_Error. В противном случае возвращается наименьший индекс I ≥ From (если Going=Вперёд) или наибольший индекс I ≤ From (если Going=Назад), такой, что Source(I) удовлетворяет условию Test относительно Set; возвращает 0, если такого символа в Source нет.

функция Index (Source : вход Строка;
Set : вход Maps.Character_Set;
Test : вход Членство := Внутри;
Going : вход Направление := Вперёд)
возвращает Натуральное;

Если Going = Вперёд, возвращает

Index (Source, Set, Source'First, Test, Forward);

в противном случае возвращает

Index (Source, Set, Source'Last, Test, Backward);

функция Index_Non_Blank (Source : вход Строка;
From : вход Положительное;
Going : вход Направление := Вперёд)
возвращает Натуральное;

Возвращает Index (Source, Maps.To_Set(Space), From, Outside, Going);

функция Index_Non_Blank (Source : вход Строка;
Going : вход Направление := Вперёд)
возвращает Натуральное;

Возвращает Index(Source, Maps.To_Set(Space), Outside, Going)

функция Count (Source : вход Строка;
Pattern : вход Строка;
Mapping : вход Maps.Character_Mapping
:= Maps.Identity)
возвращает Натуральное;

функция Count (Source : вход Строка;
Pattern : вход Строка;
Mapping : вход Maps.Character_Mapping_Function)
возвращает Натуральное;

Возвращает максимальное количество неперекрывающихся фрагментов Source, которые соответствуют Pattern относительно Mapping. Если Pattern — пустая строка, возникает Pattern_Error.

функция Count (Source : вход Строка;
Set : вход Maps.Character_Set)
возвращает Натуральное;

Возвращает количество вхождений в Source символов, которые находятся в Set.

процедура Find_Token (Source : вход Строка;
Set : вход Maps.Character_Set;
Test : вход Членство;
First : выход Положительное;
Last : выход Натуральное);

Find_Token возвращает в First и Last индексы начала и конца первого фрагмента Source, все элементы которого удовлетворяют условию Test, и такие, что элементы (если таковые имеются) непосредственно перед и после фрагмента условию Test не удовлетворяют. Если такого фрагмента не существует, то возвращаемое значение для Last равно нулю, а для First — Source'First; однако, если Source'First не входит в Положительное, возникает Constraint_Error.

функция Translate (Source : вход Строка;
Mapping : вход Maps.Character_Mapping)
возвращает Строка;

функция Translate (Source : вход Строка;
Mapping : вход Maps.Character_Mapping_Function)
возвращает Строка;

Возвращает строку S длиной Source'Length, такую, что S(I) — символ, в который Mapping отображает соответствующий элемент Source, для I в 1..Source'Length.

процедура Translate (Source : вход выход Строка;
Mapping : вход Maps.Character_Mapping);

процедура Translate (Source : вход выход Строка;
Mapping : вход Maps.Character_Mapping_Function);

Эквивалентно Source := Translate(Source, Mapping).

функция Replace_Slice (Source : вход Строка;
Low : вход Положительное;
High : вход Натуральное;
By : вход Строка)
возвращает Строка;

Если Low > Source'Last+1 или High < Source'First–1, то возникает Index_Error. В противном случае:

Если High ≥ Low, то возвращаемая строка состоит из Source(Source'First..Low–1) & By & Source(High+1..Source'Last), но с нижней границей 1.

Если High < Low, то возвращаемая строка — Insert(Source, Before=Low, New_Item=By).

процедура Replace_Slice (Source : вход выход Строка;
Low : вход Положительное;
High : вход Натуральное;
By : вход Строка;
Drop : вход Обрезка := Ошибка;
Justify : вход Выравнивание := Слева;
Pad : вход Символ := Пробел);

Эквивалентно Move(Replace_Slice(Source, Low, High, By), Source, Drop, Justify, Pad).

функция Insert (Source : вход Строка;
Before : вход Положительное;
New_Item : вход Строка)
возвращает Строка;

Возникает Index_Error, если Before не входит в Source'First .. Source'Last+1; в противном случае возвращается Source(Source'First..Before–1) & New_Item & Source(Before..Source'Last), но с нижней границей 1.

процедура Insert (Source : вход выход Строка;
Before : вход Положительное;
New_Item : вход Строка;
Drop : вход Обрезка := Ошибка);

Эквивалентно Move(Insert(Source, Before, New_Item), Source, Drop).

функция Overwrite (Source : вход Строка;
Position : вход Положительное;
New_Item : вход Строка)
возвращает Строка;

Возникает Index_Error, если Position не входит в Source'First .. Source'Last+1; в противном случае возвращает строку, полученную из Source заменой символов, начиная с Position, соответствующими символами из New_Item. Если конец Source достигается до того, как символы из New_Item исчерпаны, оставшиеся символы из New_Item добавляются к строке.

процедура Overwrite (Source : вход выход Строка;
Position : вход Положительное;
New_Item : вход Строка;
Drop : вход Обрезка := Справа);

Эквивалентно Move(Overwrite(Source, Position, New_Item), Source, Drop).

функция Delete (Source : вход Строка;
From : вход Положительное;
Through : вход Натуральное)
возвращает Строка;

Если From ≤ Through, возвращаемая строка — Replace_Slice(Source, From, Through, ""), иначе — Source с нижней границей 1.

процедура Delete (Source : вход выход Строка;
From : вход Положительное;
Through : вход Натуральное;
Justify : вход Выравнивание := Слева;
Pad : вход Символ := Пробел);

Эквивалентно Move(Delete(Source, From, Through), Source, Justify => Justify, Pad => Pad).

функция Trim (Source : вход Строка;
Side : вход Trim_End)
возвращает Строка;

Возвращает строку, полученную удалением из Source всех начальных пробельных символов (если Side = Слева), всех конечных пробельных символов (если Side = Справа), или всех начальных и конечных пробельных символов (если Side = Оба).

процедура Trim (Source : вход выход Строка;
Side : вход Trim_End;
Justify : вход Выравнивание := Слева;
Pad : вход Символ := Пробел);

Эквивалентно Move(Trim(Source, Side), Source, Justify=>Justify, Pad=>Pad).

функция Trim (Source : вход Строка;
Left : вход Maps.Character_Set;
Right : вход Maps.Character_Set)
возвращает Строка;

Возвращает строку, полученную удалением из Source всех начальных символов из Left и всех конечных символов из Right.

процедура Trim (Source : вход выход Строка;
Left : вход Maps.Character_Set;
Right : вход Maps.Character_Set;
Justify : вход Выравнивание := Strings.Left;
Pad : вход Символ := Пробел);

Эквивалентно Move(Trim(Source, Left, Right), Source, Justify => Justify, Pad=>Pad).

function Head (Source : in String;
Count : in Natural;
Pad : in Character := Space)
return String;

Возвращает строку длиной Count. Если Count <= Source'Length, строка состоит из первых Count символов Source. В противном случае ее содержимое — это конкатенация Source с Count–Source'Length символами Pad.

procedure Head (Source : in out String;
Count : in Natural;
Justify : in Alignment := Left;
Pad : in Character := Space);

Эквивалентно Move(Head(Source, Count, Pad), Source, Drop=>Error, Justify=>Justify, Pad=>Pad).

function Tail (Source : in String;
Count : in Natural;
Pad : in Character := Space)
return String;

Возвращает строку длиной Count. Если Count <= Source'Length, строка состоит из последних Count символов Source. В противном случае ее содержимое — это конкатенация Count-Source'Length символов Pad с Source.

procedure Tail (Source : in out String;
Count : in Natural;
Justify : in Alignment := Left;
Pad : in Character := Space);

Эквивалентно Move(Tail(Source, Count, Pad), Source, Drop=>Error, Justify=>Justify, Pad=>Pad).

function "*" (Left : in Natural;
Right : in Character) return String;

function "*" (Left : in Natural;
Right : in String) return String;

Эти функции повторяют символ или строку заданное количество раз. Первая функция возвращает строку длиной Left, каждый элемент которой равен Right. Вторая функция возвращает строку длиной Left*Right'Length и значение null, если Left = 0, а в противном случае — (Left–1)*Right & Right с нижней границей 1.

ПРИМЕЧАНИЯ

9 В функциях Index и Count, принимающих параметры Pattern и Mapping, фактический параметр String, передаваемый в Pattern, должен содержать символы, являющиеся целевыми символами отображения. В противном случае шаблон не будет соответствовать.

10 В подпрограммах Insert вставка в конец строки достигается передачей Source'Last+1 в качестве параметра Before.

11 Если в одну из подпрограмм обработки строк передана пустая функция Character_Mapping_Function, возникает исключение Constraint_Error.