Справочник по Ada 2012

A.18.2 Обобщенный пакет Containers.Vectors

Определяемый языком обобщенный пакет Containers.Vectors предоставляет приватные типы Vector и Cursor, а также набор операций для каждого типа. Контейнер типа вектор позволяет вставлять и удалять элементы в любой позиции, но он оптимизирован для вставки и удаления в конце контейнера (позиции с наибольшим индексом). Контейнер типа вектор также обеспечивает произвольный доступ к элементам.

Контейнер типа вектор концептуально ведет себя как массив, который расширяется по мере необходимости при вставке элементов. Длина вектора — это количество элементов, содержащихся в векторе. Ёмкость вектора — это максимальное количество элементов, которое можно вставить в вектор перед его автоматическим расширением.

Элементы в контейнере типа вектор можно ссылаться с помощью значения индекса определённого обобщённого формального типа. Первый элемент вектора всегда имеет значение индекса, равное нижней границе формального типа.

Контейнер типа вектор может содержать пустые элементы. Пустые элементы не имеют заданного значения.

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

Обобщенный пакет библиотек Containers.Vectors имеет следующее объявление:

with Ada.Iterator_Interfaces;
generic
type Index_Type is range <>;
type Element_Type is private;
with function "=" (Left, Right : Element_Type)
return Boolean is <>;
package Ada.Containers.Vectors is
pragma Preelaborate(Vectors);
pragma Remote_Types(Vectors);

subtype Extended_Index is
Index_Type'Base range
Index_Type'First-1 ..
Index_Type'Min (Index_Type'Base'Last - 1, Index_Type'Last) + 1;
No_Index : constant Extended_Index := Extended_Index'First;

type Vector is tagged private
with Constant_Indexing => Constant_Reference,
Variable_Indexing => Reference,
Default_Iterator => Iterate,
Iterator_Element => Element_Type;
pragma Preelaborable_Initialization(Vector);

type Cursor is private;
pragma Preelaborable_Initialization(Cursor);

Empty_Vector : constant Vector;

No_Element : constant Cursor;

function Has_Element (Position : Cursor) return Boolean;

package Vector_Iterator_Interfaces is new
Ada.Iterator_Interfaces (Cursor, Has_Element);

function "=" (Left, Right : Vector) return Boolean;

function To_Vector (Length : Count_Type) return Vector;

function To_Vector
(New_Item : Element_Type;
Length : Count_Type) return Vector;

function "&" (Left, Right : Vector) return Vector;

function "&" (Left : Vector;
Right : Element_Type) return Vector;

function "&" (Left : Element_Type;
Right : Vector) return Vector;

function "&" (Left, Right : Element_Type) return Vector;

function Capacity (Container : Vector) return Count_Type;

procedure Reserve_Capacity (Container : in out Vector;
Capacity : in Count_Type);

function Length (Container : Vector) return Count_Type;

procedure Set_Length (Container : in out Vector;
Length : in Count_Type);

function Is_Empty (Container : Vector) return Boolean;

procedure Clear (Container : in out Vector);

function To_Cursor (Container : Vector;
Index : Extended_Index) return Cursor;

function To_Index (Position : Cursor) return Extended_Index;

function Element (Container : Vector;
Index : Index_Type)
return Element_Type;

function Element (Position : Cursor) return Element_Type;

procedure Replace_Element (Container : in out Vector;
Index : in Index_Type;
New_Item : in Element_Type);

procedure Replace_Element (Container : in out Vector;
Position : in Cursor;
New_item : in Element_Type);

procedure Query_Element
(Container : in Vector;
Index : in Index_Type;
Process : not null access procedure (Element : in Element_Type));

procedure Query_Element
(Position : in Cursor;
Process : not null access procedure (Element : in Element_Type));

procedure Update_Element
(Container : in out Vector;
Index : in Index_Type;
Process : not null access procedure
(Element : in out Element_Type));

procedure Update_Element
(Container : in out Vector;
Position : in Cursor;
Process : not null access procedure
(Element : in out Element_Type));

type Constant_Reference_Type
(Element : not null access constant Element_Type) is private
with Implicit_Dereference => Element;

type Reference_Type (Element : not null access Element_Type) is private
with Implicit_Dereference => Element;

function Constant_Reference (Container : aliased in Vector;
Index : in Index_Type)
return Constant_Reference_Type;

function Reference (Container : aliased in out Vector;
Index : in Index_Type)
return Reference_Type;

function Constant_Reference (Container : aliased in Vector;
Position : in Cursor)
return Constant_Reference_Type;

function Reference (Container : aliased in out Vector;
Position : in Cursor)
return Reference_Type;

procedure Assign (Target : in out Vector; Source : in Vector);

function Copy (Source : Vector; Capacity : Count_Type := 0)
return Vector;

procedure Move (Target : in out Vector;
Source : in out Vector);

procedure Insert (Container : in out Vector;
Before : in Extended_Index;
New_Item : in Vector);

procedure Insert (Container : in out Vector;
Before : in Cursor;
New_Item : in Vector);

procedure Insert (Container : in out Vector;
Before : in Cursor;
New_Item : in Vector;
Position : out Cursor);

procedure Insert (Container : in out Vector;
Before : in Extended_Index;
New_Item : in Element_Type;
Count : in Count_Type := 1);

procedure Insert (Container : in out Vector;
Before : in Cursor;
New_Item : in Element_Type;
Count : in Count_Type := 1);

procedure Insert (Container : in out Vector;
Before : in Cursor;
New_Item : in Element_Type;
Position : out Cursor;
Count : in Count_Type := 1);

procedure Insert (Container : in out Vector;
Before : in Extended_Index;
Count : in Count_Type := 1);

procedure Insert (Container : in out Vector;
Before : in Cursor;
Position : out Cursor;
Count : in Count_Type := 1);

procedure Prepend (Container : in out Vector;
New_Item : in Vector);

procedure Prepend (Container : in out Vector;
New_Item : in Element_Type;
Count : in Count_Type := 1);

procedure Append (Container : in out Vector;
New_Item : in Vector);

procedure Append (Container : in out Vector;
New_Item : in Element_Type;
Count : in Count_Type := 1);

procedure Insert_Space (Container : in out Vector;
Before : in Extended_Index;
Count : in Count_Type := 1);

procedure Insert_Space (Container : in out Vector;
Before : in Cursor;
Position : out Cursor;
Count : in Count_Type := 1);

procedure Delete (Container : in out Vector;
Index : in Extended_Index;
Count : in Count_Type := 1);

procedure Delete (Container : in out Vector;
Position : in out Cursor;
Count : in Count_Type := 1);

procedure Delete_First (Container : in out Vector;
Count : in Count_Type := 1);

procedure Delete_Last (Container : in out Vector;
Count : in Count_Type := 1);

procedure Reverse_Elements (Container : in out Vector);

procedure Swap (Container : in out Vector;
I, J : in Index_Type);

procedure Swap (Container : in out Vector;
I, J : in Cursor);

function First_Index (Container : Vector) return Index_Type;

function First (Container : Vector) return Cursor;

function First_Element (Container : Vector)
return Element_Type;

function Last_Index (Container : Vector) return Extended_Index;

function Last (Container : Vector) return Cursor;

function Last_Element (Container : Vector)
return Element_Type;

function Next (Position : Cursor) return Cursor;

procedure Next (Position : in out Cursor);

function Previous (Position : Cursor) return Cursor;

procedure Previous (Position : in out Cursor);

END_OF_DOCUMENT_MARKER

function Find_Index (Container : Vector;
Item : Element_Type;
Index : Index_Type := Index_Type'First)
return Extended_Index;

function Find (Container : Vector;
Item : Element_Type;
Position : Cursor := No_Element)
return Cursor;

function Reverse_Find_Index (Container : Vector;
Item : Element_Type;
Index : Index_Type := Index_Type'Last)
return Extended_Index;

function Reverse_Find (Container : Vector;
Item : Element_Type;
Position : Cursor := No_Element)
return Cursor;

function Contains (Container : Vector;
Item : Element_Type) return Boolean;

Этот абзац был удалён.

procedure Iterate
(Container : in Vector;
Process : not null access procedure (Position : in Cursor));

procedure Reverse_Iterate
(Container : in Vector;
Process : not null access procedure (Position : in Cursor));

function Iterate (Container : in Vector)
return Vector_Iterator_Interfaces.Reversible_Iterator'Class;

function Iterate (Container : in Vector; Start : in Cursor)
return Vector_Iterator_Interfaces.Reversible_Iterator'Class;

generic
with function "<" (Left, Right : Element_Type)
return Boolean is <>;
package Generic_Sorting is

function Is_Sorted (Container : Vector) return Boolean;

procedure Sort (Container : in out Vector);

procedure Merge (Target : in out Vector;
Source : in out Vector);

end Generic_Sorting;

private

... -- не определено языком

end Ada.Containers.Vectors;

Ожидается, что фактическая функция для обобщённого формального оператора "=" для значений Element_Type определит рефлексивное и симметричное отношение и вернёт то же значение результата каждый раз, когда она вызывается с конкретной парой значений. Если её поведение иное, функции, определённые с её использованием, возвращают неопределённое значение. Точные аргументы и количество вызовов этой обобщённой формальной функции функциями, использующими её, не определены.

Тип Vector используется для представления векторов. Тип Vector требует завершения (см. 7.6).

Empty_Vector представляет собой пустой объект вектора. Его длина равна 0. Если объект типа Vector не инициализирован иначе, он инициализируется тем же значением, что и Empty_Vector.

No_Element представляет собой курсор, который не указывает на элемент. Если объект типа Cursor не инициализирован иначе, он инициализируется тем же значением, что и No_Element.

Предопределённый оператор "=" для типа Cursor возвращает True, если оба курсора равны No_Element или указывают на тот же элемент в том же контейнере.

Выполнение стандартной реализации атрибутов Input, Output, Read или Write для типа Cursor вызывает исключение Program_Error.

Vector'Write для объекта Vector V записывает Length(V) элементов вектора в поток. Он также может записать дополнительную информацию о векторе.

Vector'Read считывает представление вектора из потока и присваивает Item вектор с такой же длиной и элементами, как был записан Vector'Write.

No_Index представляет собой позицию, которая не соответствует ни одному элементу. Подтип Extended_Index включает индексы, охватываемые Index_Type, плюс значение No_Index и, если оно существует, значение, следующее за Index_Type'Last.

Если операция пытается изменить вектор таким образом, что позиция последнего элемента будет больше, чем Index_Type'Last, то операция распространяет исключение Constraint_Error.

Некоторые операции этого обобщённого пакета имеют параметры доступа к подпрограмме. Чтобы такие операции были корректно определены, они предохраняют от определённых действий со стороны указанной подпрограммы. В частности, некоторые операции проверяют «вмешательство с курсорами» контейнера, потому что они зависят от того, чтобы набор элементов контейнера оставался постоянным, а другие проверяют «вмешательство с элементами» контейнера, потому что они зависят от того, чтобы элементы контейнера не заменялись.

Подпрограмма считается вмешивающейся с курсорами объекта вектора V, если:

она вставляет или удаляет элементы V, то есть вызывает процедуры Insert, Insert_Space, Clear, Delete или Set_Length с V в качестве параметра; или

она завершает V; или

она вызывает процедуру Assign с V в качестве параметра Target; или

она вызывает процедуру Move с V в качестве параметра.

Подпрограмма считается вмешивающейся с элементами объекта вектора V, если:

она вмешивается с курсорами V; или

она заменяет один или несколько элементов V, то есть вызывает процедуры Replace_Element, Reverse_Elements или Swap, или процедуры Sort или Merge экземпляра Generic_Sorting с V в качестве параметра.

Когда вмешательство с курсорами запрещено для конкретного объекта вектора V, Program_Error распространяется при вызове любой подпрограммы языка, которая определена как вмешивающаяся с курсорами V, оставляя V неизменным. Аналогично, когда вмешательство с элементами запрещено для конкретного объекта вектора V, Program_Error распространяется при вызове любой подпрограммы языка, которая определена как вмешивающаяся с элементами V (или с курсорами V), оставляя V неизменным. Эти проверки выполняются до любого другого определённого поведения тела подпрограммы языка.

function Has_Element (Position : Cursor) return Boolean;

Возвращает True, если Position указывает на элемент, и False в противном случае.

function "=" (Left, Right : Vector) return Boolean;

Если Left и Right обозначают один и тот же объект вектора, функция возвращает True. Если Left и Right имеют разные длины, функция возвращает False. В противном случае она сравнивает каждый элемент в Left с соответствующим элементом в Right, используя обобщённый формальный оператор равенства. Если какое-либо такое сравнение возвращает False, функция возвращает False; в противном случае она возвращает True. Любое исключение, поднятое во время оценки равенства элементов, распространяется.

function To_Vector (Length : Count_Type) return Vector;

Возвращает вектор длины Length, заполненный пустыми элементами.

function To_Vector
(New_Item : Element_Type;
Length : Count_Type) return Vector;

Возвращает вектор длины Length, заполненный элементами, инициализированными значением New_Item.

function "&" (Left, Right : Vector) return Vector;

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

function "&" (Left : Vector;
Right : Element_Type) return Vector;

Возвращает вектор, состоящий из элементов Left, после которых следует элемент Right.

function "&" (Left : Element_Type;
Right : Vector) return Vector;

Возвращает вектор, состоящий из элемента Left, после которого следуют элементы Right.

function "&" (Left, Right : Element_Type) return Vector;

Возвращает вектор, состоящий из элемента Left, после которого следует элемент Right.

function Capacity (Container : Vector) return Count_Type;

Возвращает ёмкость Container.

procedure Reserve_Capacity (Container : in out Vector;
Capacity : in Count_Type);

Если ёмкость Container уже больше или равна Capacity, то Reserve_Capacity не оказывает влияния. В противном случае Reserve_Capacity выделяет дополнительное хранилище, чтобы гарантировать, что длина результирующего вектора может стать как минимум равной Capacity без дополнительных вызовов Reserve_Capacity и достаточно велика для хранения текущей длины Container. Reserve_Capacity затем, при необходимости, перемещает элементы в новое хранилище и освобождает любое больше не нужное хранилище. Любое исключение, поднятое во время выделения, распространяется, и Container не изменяется.

function Length (Container : Vector) return Count_Type;

Возвращает количество элементов в Container.

procedure Set_Length (Container : in out Vector;
Length : in Count_Type);

Если Length больше, чем ёмкость Container, Set_Length вызывает Reserve_Capacity (Container, Length), а затем устанавливает длину Container в Length. Если Length больше исходной длины Container, к Container добавляются пустые элементы; в противном случае элементы удаляются из Container.

function Is_Empty (Container : Vector) return Boolean;

Эквивалентно Length (Container) = 0.

procedure Clear (Container : in out Vector);

Удаляет все элементы из Container. Ёмкость Container не изменяется.

function To_Cursor (Container : Vector;
Index : Extended_Index) return Cursor;

Если Index не входит в диапазон First_Index (Container) .. Last_Index (Container), то возвращается No_Element. В противном случае возвращается курсор, указывающий на элемент в позиции Index в Container.

function To_Index (Position : Cursor) return Extended_Index;

Если Position равно No_Element, возвращается No_Index. В противном случае возвращается индекс (внутри содержащего вектора) элемента, обозначенного Position.

function Element (Container : Vector;
Index : Index_Type)
return Element_Type;

Если Index не находится в диапазоне First_Index (Container) .. Last_Index (Container), то генерируется Constraint_Error. В противном случае Element возвращает элемент по индексу Index.

function Element (Position : Cursor) return Element_Type;

Если Position равно No_Element, то генерируется Constraint_Error. В противном случае Element возвращает элемент, обозначенный Position.

procedure Replace_Element (Container : in out Vector;
Index : in Index_Type;
New_Item : in Element_Type);

Если Index не находится в диапазоне First_Index (Container) .. Last_Index (Container), то генерируется Constraint_Error. В противном случае Replace_Element присваивает значение New_Item элементу по индексу Index. Любые исключения, возникшие во время присваивания, передаются вверх. Элемент по индексу Index не является пустым после успешного вызова Replace_Element.

procedure Replace_Element (Container : in out Vector;
Position : in Cursor;
New_Item : in Element_Type);

Если Position равно No_Element, то генерируется Constraint_Error; если Position не обозначает элемент в Container, то генерируется Program_Error. В противном случае Replace_Element присваивает New_Item элементу, обозначенному Position. Любые исключения, возникшие во время присваивания, передаются вверх. Элемент по позиции Position не является пустым после успешного вызова Replace_Element.

procedure Query_Element
(Container : in Vector;
Index : in Index_Type;
Process : not null access procedure (Element : in Element_Type));

Если Index не находится в диапазоне First_Index (Container) .. Last_Index (Container), то генерируется Constraint_Error. В противном случае Query_Element вызывает Process.all с элементом по индексу Index в качестве аргумента. Изменение элементов Container запрещено во время выполнения вызова Process.all. Любые исключения, сгенерированные Process.all, передаются вверх.

procedure Query_Element
(Position : in Cursor;
Process : not null access procedure (Element : in Element_Type));

Если Position равно No_Element, то генерируется Constraint_Error. В противном случае Query_Element вызывает Process.all с элементом, обозначенным Position, в качестве аргумента. Изменение элементов вектора, содержащего элемент, обозначенный Position, запрещено во время выполнения вызова Process.all. Любые исключения, сгенерированные Process.all, передаются вверх.

procedure Update_Element
(Container : in out Vector;
Index : in Index_Type;
Process : not null access procedure (Element : in out Element_Type));

Если Index не находится в диапазоне First_Index (Container) .. Last_Index (Container), то генерируется Constraint_Error. В противном случае Update_Element вызывает Process.all с элементом по индексу Index в качестве аргумента. Изменение элементов Container запрещено во время выполнения вызова Process.all. Любые исключения, сгенерированные Process.all, передаются вверх.

Если Element_Type не ограничено и определено, то фактический параметр Element в Process.all должен быть не ограничен.

Элемент по индексу Index не является пустым элементом после успешного завершения данной операции.

procedure Update_Element
(Container : in out Vector;
Position : in Cursor;
Process : not null access procedure (Element : in out Element_Type));

Если Position равно No_Element, то генерируется Constraint_Error; если Position не обозначает элемент в Container, то генерируется Program_Error. В противном случае Update_Element вызывает Process.all с элементом, обозначенным Position, в качестве аргумента. Изменение элементов Container запрещено во время выполнения вызова Process.all. Любые исключения, сгенерированные Process.all, передаются вверх.

Если Element_Type не ограничено и определено, то фактический параметр Element в Process.all должен быть не ограничен.

Элемент, обозначенный Position, не является пустым после успешного завершения этой операции.

type Constant_Reference_Type
(Element : not null access constant Element_Type) is private
with Implicit_Dereference => Element;

type Reference_Type (Element : not null access Element_Type) is private
with Implicit_Dereference => Element;

Типы Constant_Reference_Type и Reference_Type требуют завершения.

Инициализация по умолчанию объекта типа Constant_Reference_Type или Reference_Type вызывает Program_Error.

function Constant_Reference (Container : aliased in Vector;
Index : in Index_Type)
return Constant_Reference_Type;

Эта функция (в сочетании с аспектами Constant_Indexing и Implicit_Dereference) предоставляет удобный способ получить доступ для чтения к отдельному элементу вектора, заданному индексом.

Если Index не находится в диапазоне First_Index (Container) .. Last_Index (Container), то генерируется Constraint_Error. В противном случае Constant_Reference возвращает объект, дискриминант которого является значением доступа, обозначающим элемент по индексу Index. Изменение элементов Container запрещено, пока существует возвращенный Constant_Reference объект и он не завершен.

function Reference (Container : aliased in out Vector;
Index : in Index_Type)
return Reference_Type;

Эта функция (в сочетании с аспектами Variable_Indexing и Implicit_Dereference) предоставляет удобный способ получения доступа для чтения и записи к отдельному элементу вектора, заданному индексом.

Если Index не находится в диапазоне First_Index (Container) .. Last_Index (Container), то генерируется Constraint_Error. В противном случае Reference возвращает объект, дискриминант которого является значением доступа, обозначающим элемент по индексу Index. Изменение элементов Container запрещено, пока существует возвращенный Reference объект и он не завершен.

Элемент по индексу Index не является пустым элементом после успешного выполнения операции.

function Constant_Reference (Container : aliased in Vector;
Position : in Cursor)
return Constant_Reference_Type;

Если Position равно No_Element, то генерируется Constraint_Error; если Position не обозначает элемент в Container, то генерируется Program_Error. В противном случае Constant_Reference возвращает объект, дискриминант которого является значением доступа, обозначающим элемент, обозначенный Position. Изменение элементов Container запрещено, пока существует возвращенный Constant_Reference объект и он не завершен.

function Reference (Container : aliased in out Vector;
Position : in Cursor)
return Reference_Type;

Если Position равно No_Element, то генерируется Constraint_Error; если Position не обозначает элемент в Container, то генерируется Program_Error. В противном случае Reference возвращает объект, дискриминант которого является значением доступа, обозначающим элемент, обозначенный Position. Изменение элементов Container запрещено, пока существует возвращенный Reference объект и он не завершен.

Элемент, обозначенный Position, не является пустым элементом после успешного выполнения операции.

procedure Assign (Target : in out Vector; Source : in Vector);

Если Target обозначает тот же объект, что и Source, операция не имеет эффекта. Если длина Source больше, чем емкость Target, вызывается Reserve_Capacity (Target, Length (Source)). Элементы Source затем копируются в Target так же, как при присваивании assignment_statement, присваивающей Source в Target (включая установление длины Target, равной длине Source).

function Copy (Source : Vector; Capacity : Count_Type := 0)
return Vector;

Возвращает вектор, элементы которого инициализированы из соответствующих элементов Source. Если Capacity равно 0, то емкость вектора равна длине Source; если Capacity равно или больше длины Source, то емкость вектора не меньше указанного значения. В противном случае генерируется Capacity_Error.

procedure Move (Target : in out Vector;
Source : in out Vector);

Если Target обозначает тот же объект, что и Source, операция не имеет эффекта. В противном случае Move сначала вызывает Reserve_Capacity (Target, Length (Source)), а затем Clear (Target); затем каждый элемент из Source удаляется из Source и вставляется в Target в исходном порядке. Длина Source равна 0 после успешного вызова Move.

procedure Insert (Container : in out Vector;
Before : in Extended_Index;
New_Item : in Vector);

Если Before не находится в диапазоне First_Index (Container) .. Last_Index (Container) + 1, то генерируется Constraint_Error. Если Length(New_Item) равно 0, то Insert ничего не делает. В противном случае вычисляет новую длину NL как сумму текущей длины и Length (New_Item); если значение Last, соответствующее длине NL, будет больше, чем Index_TypeLast, то генерируется Constraint_Error.

Если текущая емкость вектора меньше NL, вызывается Reserve_Capacity (Container, NL) для увеличения емкости вектора. Затем Insert сдвигает элементы в диапазоне Before .. Last_Index (Container) вверх на Length(New_Item) позиций, а затем копирует элементы New_Item в позиции, начиная с Before. Любое исключение, возникшее во время копирования, передаётся вверх.

процедура Insert (Container : ввод-вывод Vector;
Before : ввод Cursor;
New_Item : ввод Vector);

Если Before не равно No_Element и не указывает на элемент в Container, то генерируется Program_Error. В противном случае, если Length(New_Item) равно 0, то Insert ничего не делает. Если Before равно No_Element, то вызов эквивалентен Insert (Container, Last_Index (Container) + 1, New_Item); в противном случае вызов эквивалентен Insert (Container, To_Index (Before), New_Item);

процедура Insert (Container : ввод-вывод Vector;
Before : ввод Cursor;
New_Item : ввод Vector;
Position : вывод Cursor);

Если Before не равно No_Element и не указывает на элемент в Container, то генерируется Program_Error. Если Before равно No_Element, то пусть T будет Last_Index (Container) + 1; в противном случае пусть T будет To_Index (Before). Вызывается Insert (Container, T, New_Item), а затем Position устанавливается в To_Cursor (Container, T).

процедура Insert (Container : ввод-вывод Vector;
Before : ввод Extended_Index;
New_Item : ввод Element_Type;
Count : ввод Count_Type := 1);

Эквивалентно Insert (Container, Before, To_Vector (New_Item, Count));

процедура Insert (Container : ввод-вывод Vector;
Before : ввод Cursor;
New_Item : ввод Element_Type;
Count : ввод Count_Type := 1);

Эквивалентно Insert (Container, Before, To_Vector (New_Item, Count));

процедура Insert (Container : ввод-вывод Vector;
Before : ввод Cursor;
New_Item : ввод Element_Type;
Position : вывод Cursor;
Count : ввод Count_Type := 1);

Эквивалентно Insert (Container, Before, To_Vector (New_Item, Count), Position);

процедура Insert (Container : ввод-вывод Vector;
Before : ввод Extended_Index;
Count : ввод Count_Type := 1);

Если Before не находится в диапазоне First_Index (Container) .. Last_Index (Container) + 1, то генерируется Constraint_Error. Если Count равно 0, то Insert ничего не делает. В противном случае, вычисляется новая длина NL как сумма текущей длины и Count; если значение Last, соответствующее длине NL, будет больше, чем Index_Type'Last, то генерируется Constraint_Error.

Если текущая емкость вектора меньше NL, вызывается Reserve_Capacity (Container, NL) для увеличения емкости вектора. Затем Insert сдвигает элементы в диапазоне Before .. Last_Index (Container) вверх на Count позиций, а затем вставляет элементы, инициализированные по умолчанию (см. 3.3.1), начиная с позиции Before.

процедура Insert (Container : ввод-вывод Vector;
Before : ввод Cursor;
Position : вывод Cursor;
Count : ввод Count_Type := 1);

Если Before не равно No_Element и не указывает на элемент в Container, то генерируется Program_Error. Если Before равно No_Element, то пусть T будет Last_Index (Container) + 1; в противном случае пусть T будет To_Index (Before). Вызывается Insert (Container, T, Count), а затем Position устанавливается в To_Cursor (Container, T).

процедура Prepend (Container : ввод-вывод Vector;
New_Item : ввод Vector);

Эквивалентно Insert (Container, First_Index (Container), New_Item).

процедура Prepend (Container : ввод-вывод Vector;
New_Item : ввод Element_Type;
Count : ввод Count_Type := 1);

Эквивалентно Insert (Container, First_Index (Container), New_Item, Count).

процедура Append (Container : ввод-вывод Vector;
New_Item : ввод Vector);

Эквивалентно Insert (Container, Last_Index (Container) + 1, New_Item).

процедура Append (Container : ввод-вывод Vector;
New_Item : ввод Element_Type;
Count : ввод Count_Type := 1);

Эквивалентно Insert (Container, Last_Index (Container) + 1, New_Item, Count).

процедура Insert_Space (Container : ввод-вывод Vector;
Before : ввод Extended_Index;
Count : ввод Count_Type := 1);

Если Before не находится в диапазоне First_Index (Container) .. Last_Index (Container) + 1, то генерируется Constraint_Error. Если Count равно 0, то Insert_Space ничего не делает. В противном случае, вычисляется новая длина NL как сумма текущей длины и Count; если значение Last, соответствующее длине NL, будет больше, чем Index_Type'Last, то генерируется Constraint_Error.

Если текущая емкость вектора меньше NL, вызывается Reserve_Capacity (Container, NL) для увеличения емкости вектора. Затем Insert_Space сдвигает элементы в диапазоне Before .. Last_Index (Container) вверх на Count позиций, а затем вставляет пустые элементы, начиная с позиции Before.

процедура Insert_Space (Container : ввод-вывод Vector;
Before : ввод Cursor;
Position : вывод Cursor;
Count : ввод Count_Type := 1);

Если Before не равно No_Element и не указывает на элемент в Container, то генерируется Program_Error. Если Before равно No_Element, то пусть T будет Last_Index (Container) + 1; в противном случае пусть T будет To_Index (Before). Вызывается Insert_Space (Container, T, Count), а затем Position устанавливается в To_Cursor (Container, T).

процедура Delete (Container : ввод-вывод Vector;
Index : ввод Extended_Index;
Count : ввод Count_Type := 1);

Если Index не находится в диапазоне First_Index (Container) .. Last_Index (Container) + 1, то генерируется Constraint_Error. Если Count равно 0, то Delete не имеет эффекта. В противном случае, Delete сдвигает элементы, начиная с позиции Index + Count вниз до Index. Любое исключение, возникшее во время присваивания элемента, передаётся вверх.

процедура Delete (Container : ввод-вывод Vector;
Position : ввод-вывод Cursor;
Count : ввод Count_Type := 1);

Если Position равно No_Element, то генерируется Constraint_Error. Если Position не указывает на элемент в Container, то генерируется Program_Error. В противном случае, вызывается Delete (Container, To_Index (Position), Count), а затем Position устанавливается в No_Element.

процедура Delete_First (Container : ввод-вывод Vector;
Count : ввод Count_Type := 1);

Эквивалентно Delete (Container, First_Index (Container), Count).

процедура Delete_Last (Container : ввод-вывод Vector;
Count : ввод Count_Type := 1);

Если Length (Container) <= Count, то Delete_Last эквивалентно Clear (Container). В противном случае, это эквивалентно Delete (Container, Index_Type'Val(Index_Type'Pos(Last_Index (Container)) – Count + 1), Count).

процедура Reverse_Elements (Container : ввод-вывод Vector);

Переупорядочивает элементы Container в обратном порядке.

процедура Swap (Container : ввод-вывод Vector;
I, J : ввод Index_Type);

Если I или J не находятся в диапазоне First_Index (Container) .. Last_Index (Container), то генерируется Constraint_Error. В противном случае, Swap меняет значения элементов в позициях I и J.

процедура Swap (Container : ввод-вывод Vector;
I, J : ввод Cursor);

Если I или J равно No_Element, то генерируется Constraint_Error. Если I или J не указывают на элемент в Container, то генерируется Program_Error. В противном случае, Swap меняет значения элементов, указанных I и J.

функция First_Index (Container : Vector) возвращает Index_Type;

Возвращает значение Index_Type'First.

функция First (Container : Vector) возвращает Cursor;

Если Container пустой, First возвращает No_Element. В противном случае возвращает курсор, который указывает на первый элемент в Container.

функция First_Element (Container : Vector) возвращает Element_Type;

Эквивалентно Element (Container, First_Index (Container)).

функция Last_Index (Container : Vector) возвращает Extended_Index;

Если Container пустой, Last_Index возвращает No_Index. В противном случае возвращает позицию последнего элемента в Container.

функция Last (Container : Vector) возвращает Cursor;

Если Container пустой, Last возвращает No_Element. В противном случае возвращает курсор, который указывает на последний элемент в Container.

функция Last_Element (Container : Vector) возвращает Element_Type;

Эквивалентно Element (Container, Last_Index (Container)).

функция Next (Position : Cursor) возвращает Cursor;

Если Position равно No_Element или указывает на последний элемент контейнера, то Next возвращает No_Element. В противном случае, возвращает курсор, который указывает на элемент с индексом To_Index (Position) + 1 в том же векторе, что и Position.

процедура Next (Position : ввод-вывод Cursor);

Эквивалентно Position := Next (Position).

функция Previous (Position : Cursor) возвращает Cursor;

Если Position равно No_Element или обозначает первый элемент контейнера, то Previous возвращает значение No_Element. В противном случае, он возвращает курсор, обозначающий элемент с индексом To_Index (Position) – 1 в том же векторе, что и Position.

процедура Previous (Position : вход-выход Курсор);

Эквивалентно Position := Previous (Position).

функция Find_Index (Container : Vector;
Item : Element_Type;
Index : Index_Type := Index_Type'First)
возвращает Extended_Index;

Ищет элементы в Container, равные Item (используя общий формальный оператор равенства). Поиск начинается с позиции Index и продолжается до Last_Index (Container). Если элемент не найден, то Find_Index возвращает No_Index. В противном случае, он возвращает индекс первого найденного равного элемента.

функция Find (Container : Vector;
Item : Element_Type;
Position : Cursor := No_Element)
возвращает Cursor;

Если Position не равно No_Element и не обозначает элемент в Container, то генерируется Program_Error. В противном случае, Find ищет элементы в Container, равные Item (используя общий формальный оператор равенства). Поиск начинается с первого элемента, если Position равно No_Element, и с элемента, обозначенного Position, в противном случае. Он продолжается до последнего элемента Container. Если элемент не найден, то Find возвращает No_Element. В противном случае, он возвращает курсор, обозначающий первый найденный равный элемент.

функция Reverse_Find_Index (Container : Vector;
Item : Element_Type;
Index : Index_Type := Index_Type'Last)
возвращает Extended_Index;

Ищет элементы в Container, равные Item (используя общий формальный оператор равенства). Поиск начинается с позиции Index или, если Index больше Last_Index (Container), с позиции Last_Index (Container). Он продолжается в сторону First_Index (Container). Если элемент не найден, то Reverse_Find_Index возвращает No_Index. В противном случае, он возвращает индекс первого найденного равного элемента.

функция Reverse_Find (Container : Vector;
Item : Element_Type;
Position : Cursor := No_Element)
возвращает Cursor;

Если Position не равно No_Element и не обозначает элемент в Container, то генерируется Program_Error. В противном случае, Reverse_Find ищет элементы в Container, равные Item (используя общий формальный оператор равенства). Поиск начинается с последнего элемента, если Position равно No_Element, и с элемента, обозначенного Position, в противном случае. Он продолжается в сторону первого элемента Container. Если элемент не найден, то Reverse_Find возвращает No_Element. В противном случае, он возвращает курсор, обозначающий первый найденный равный элемент.

функция Contains (Container : Vector;
Item : Element_Type) возвращает Boolean;

Эквивалентно Has_Element (Find (Container, Item)).

Абзацы 225 и 226 были перемещены выше.

процедура Iterate
(Container : вход Vector;
Process : не null access процедура (Position : вход Курсор));

Вызывает Process.all с курсором, обозначающим каждый элемент в Container в порядке индексов. Изменение курсоров Container запрещено во время выполнения вызова Process.all. Любой исключительный ситуации, возбужденный Process.all, переходит по цепочке.

процедура Reverse_Iterate
(Container : вход Vector;
Process : не null access процедура (Position : вход Курсор));

Итерация по элементам в Container, как в процедуре Iterate, за исключением того, что элементы просматриваются в обратном порядке индексов.

функция Iterate (Container : вход Vector)
возвращает Vector_Iterator_Interfaces.Reversible_Iterator'Class;

Iterate возвращает объект обратимого итератора (см. 5.5.1), который сгенерирует значение для параметра цикла (см. 5.5.2), обозначающего каждый узел в Container, начиная с первого узла и перемещая курсор по функции Next при использовании в качестве прямого итератора, и начиная с последнего узла и перемещая курсор по функции Previous при использовании в качестве обратного итератора. Изменение курсоров Container запрещено, пока существует объект итератора (в частности, в sequence_of_statements оператора loop_statement, в iterator_specification которого обозначен этот объект). Объекту итератора необходимо завершение.

функция Iterate (Container : вход Vector; Start : вход Cursor)
возвращает Vector_Iterator_Interfaces.Reversible_Iterator'Class;

Если Start не равно No_Element и не обозначает элемент в Container, то генерируется Program_Error. Если Start равно No_Element, то генерируется Constraint_Error. В противном случае, Iterate возвращает объект обратимого итератора (см. 5.5.1), который будет генерировать значение для параметра цикла (см. 5.5.2), обозначающего каждый узел в Container, начиная с узла, обозначенного Start, и перемещая курсор по функции Next при использовании в качестве прямого итератора или по функции Previous при использовании в качестве обратного итератора. Изменение курсоров Container запрещено, пока существует объект итератора (в частности, в sequence_of_statements оператора loop_statement, в iterator_specification которого обозначен этот объект). Объекту итератора необходимо завершение.

Фактическая функция для общего формального оператора "<" в Generic_Sorting должна возвращать одно и то же значение каждый раз, когда она вызывается с конкретной парой значений элементов. Она должна определять отношение строгой слабой упорядоченности (см. A.18); она не должна изменять Container. Если фактическое поведение "<" отличается, то поведение подпрограмм Generic_Sorting не определено. Количество вызовов подпрограмм Generic_Sorting для "<" не определено.

функция Is_Sorted (Container : Vector) возвращает Boolean;

Возвращает True, если элементы упорядочены по возрастанию, как определено общим формальным оператором "<"; в противном случае, Is_Sorted возвращает False. Любое исключение, возбужденное во время вычисления "<", передается по цепочке.

процедура Sort (Container : вход-выход Vector);

Переупорядочивает элементы Container таким образом, чтобы они были упорядочены по возрастанию, как определено общим формальным оператором "<". Любое исключение, возбужденное во время вычисления "<", передается по цепочке.

процедура Merge (Target : вход-выход Vector;
Source : вход-выход Vector);

Если Source пуст, то Merge ничего не делает. Если Source и Target — один и тот же непустой объект контейнера, то генерируется Program_Error. В противном случае, Merge удаляет элементы из Source и вставляет их в Target; после этого Target содержит объединение элементов, которые изначально находились в Source и Target; Source остается пустым. Если Target и Source изначально были отсортированы по возрастанию, то Target отсортирован по возрастанию, как определено общим формальным оператором "<"; в противном случае порядок элементов в Target не определен. Любое исключение, возбужденное во время вычисления "<", передается по цепочке.

Ограниченные (временные) ошибки

Чтение значения пустого элемента с помощью вызова Element, Query_Element, Update_Element, Constant_Reference, Reference, Swap, Is_Sorted, Sort, Merge, "=", Find или Reverse_Find является ограниченной ошибкой. Реализация может рассматривать элемент как имеющий любое нормальное значение (см. 13.9.1) типа элемента или возбудить Constraint_Error или Program_Error до изменения вектора.

Вызов Merge в экземпляре Generic_Sorting, где либо Source, либо Target не упорядочены по возрастанию, используя предоставленный общий формальный оператор "<", является ограниченной ошибкой. Либо Program_Error генерируется после обновления Target, как описано для Merge, либо операция работает как определено.

Ограниченной ошибкой является изменение элементов любого параметра Vector операции в фактической функции, связанной с общим формальным подпрограммой, при вызове в качестве части операции этого пакета. Либо генерируется Program_Error, либо операция работает как определено на значении Vector, либо до, либо после некоторых или всех изменений в Vector.

Вызов любой подпрограммы, объявленной в видимой части Containers.Vectors, когда связанный контейнер завершен, является ограниченной ошибкой. Если операция принимает Container как параметр вход-выход, то она возбуждает Constraint_Error или Program_Error. В противном случае операция либо выполняется так же, как и для пустого контейнера, либо возбуждает Constraint_Error или Program_Error.

Значение Cursor является неопределенным, если после его создания произошло что-либо из следующего:

Для вектора, содержащего элемент, который обозначает курсор, были вызваны Insert, Insert_Space или Delete с индексом меньше или равным индексу элемента, обозначенного курсором; или

Вектор, содержащий элемент, который обозначает курсор, был передан в процедуры Sort или Merge экземпляра Generic_Sorting или в процедуру Reverse_Elements.

Вызов любой подпрограммы, кроме «=» или Has_Element, объявленной в Containers.Vectors, с неопределенным (но не недействительным, см. ниже) параметром курсора, является ограниченной ошибкой. Возможные результаты:

Курсор может обрабатываться так, как если бы он был No_Element;

Курсор может обозначать некоторый элемент в векторе (но не обязательно тот элемент, который он изначально обозначал);

Может быть возбужден Constraint_Error; или

Может быть возбужден Program_Error.

Ошибка выполнения

Значение курсора некорректно, если после его создания произошло любое из следующих событий:

Вектор, содержащий элемент, на который указывает курсор, был завершен;

Вектор, содержащий элемент, на который указывает курсор, был использован в качестве целевого объекта в вызове Assign или в качестве целевого объекта в операции присваивания;

Вектор, содержащий элемент, на который указывает курсор, был использован в качестве источника или целевого объекта в вызове Move; или

Элемент, на который указывает курсор, был удалён или удалён из вектора, который ранее содержал этот элемент.

Результат операции "=" или Has_Element не определён, если он вызван с некорректным параметром курсора. Выполнение является ошибочным, если любая другая подпрограмма, объявленная в Containers.Vectors, вызвана с некорректным параметром курсора.

Выполнение является ошибочным, если вектор, связанный с результатом вызова Reference или Constant_Reference, завершён до завершения объекта-результата, возвращённого вызовом Reference или Constant_Reference.

Требования к реализации

Память, связанная с объектом вектора, не должна быть потеряна при присваивании или выходе из области видимости.

Выполнение операции присваивания для вектора должно иметь эффект копирования элементов из исходного вектора в целевой вектор и изменения длины целевого объекта на длину исходного объекта.

A.18.2 Обобщенный пакет Containers.Vectors

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

Ограниченные (временные) ошибки

Ошибка выполнения

Требования к реализации

Рекомендации по реализации