Справочник по Ada (Ada 2022)

B.3.1 Пакет интерфейсов Interfaces.C.Strings

Пакет Interfaces.C.Strings объявляет типы и подпрограммы, позволяющие Ada-программе выделять, ссылаться, обновлять и освобождать строки в стиле C. В частности, частный тип chars_ptr соответствует обычному использованию «char *» в C-программах, и объект этого типа может быть передан подпрограмме, для которой указано with Import => True, Convention => C, и для которой «char *» является типом аргумента C-функции.

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

Библиотечный пакет Interfaces.C.Strings имеет следующее объявление:

package Interfaces.C.Strings
with Preelaborate, Nonblocking, Global => in out synchronized is

type char_array_access is access all char_array;

type chars_ptr is private
with Preelaborable_Initialization;

type chars_ptr_array is array (size_t range <>) of aliased chars_ptr;

Null_Ptr : constant chars_ptr;

function To_Chars_Ptr (Item : in char_array_access;
Nul_Check : in Boolean := False)
return chars_ptr;

function New_Char_Array (Chars : in char_array) return chars_ptr;

function New_String (Str : in String) return chars_ptr;

procedure Free (Item : in out chars_ptr);

Dereference_Error : exception;

function Value (Item : in chars_ptr) return char_array;

function Value (Item : in chars_ptr; Length : in size_t)
return char_array;

function Value (Item : in chars_ptr) return String;

function Value (Item : in chars_ptr; Length : in size_t)
return String;

function Strlen (Item : in chars_ptr) return size_t;

procedure Update (Item : in chars_ptr;
Offset : in size_t;
Chars : in char_array;
Check : in Boolean := True);

procedure Update (Item : in chars_ptr;
Offset : in size_t;
Str : in String;
Check : in Boolean := True);

Update_Error : exception;

private
... -- не указано языком
end Interfaces.C.Strings;

Тип chars_ptr совместим с C и соответствует использованию C's «char *» для указателя на первый символ в массиве char, завершенном нулём. При объявлении объекта типа chars_ptr его значение по умолчанию устанавливается в Null_Ptr, если объект не импортируется (см. B.1).

function To_Chars_Ptr (Item : in char_array_access;
Nul_Check : in Boolean := False)
return chars_ptr;

Если Item равен null, то To_Chars_Ptr возвращает Null_Ptr. Если Item не равен null, Nul_Check равен True, и Item.all не содержит nul, то функция генерирует Terminator_Error; в противном случае To_Chars_Ptr выполняет преобразование указателя без выделения памяти.

function New_Char_Array (Chars : in char_array) return chars_ptr;

Эта функция возвращает указатель на выделенный объект, инициализированный Chars(Chars'First .. Index) & nul, где

Index = Chars'Last, если Chars не содержит nul, или

Index — наименьшее значение size_t I такое, что Chars(I+1) = nul.

Storage_Error генерируется, если выделение памяти не удаётся.

function New_String (Str : in String) return chars_ptr;

Эта функция эквивалентна New_Char_Array(To_C(Str)).

procedure Free (Item : in out chars_ptr);

Если Item равен Null_Ptr, то Free не имеет эффекта. В противном случае Free освобождает память, занимаемую Value(Item), и сбрасывает Item в Null_Ptr.

function Value (Item : in chars_ptr) return char_array;

Если Item = Null_Ptr, то Value генерирует Dereference_Error. В противном случае Value возвращает префикс массива символов, на который указывает Item, до и включая первый nul. Нижняя граница результата равна 0. Если Item не указывает на строку, завершенную nul, то выполнение Value является ошибочным.

function Value (Item : in chars_ptr; Length : in size_t)
return char_array;

Если Item = Null_Ptr, то Value генерирует Dereference_Error. В противном случае Value возвращает более короткий из двух массивов: первые Length символов, на которые указывает Item, или Value(Item). Нижняя граница результата равна 0. Если Length равно 0, то Value генерирует Constraint_Error.

function Value (Item : in chars_ptr) return String;

Эквивалентно To_Ada(Value(Item), Trim_Nul=>True).

function Value (Item : in chars_ptr; Length : in size_t)
return String;

Эквивалентно To_Ada(Value(Item, Length) & nul, Trim_Nul=>True).

function Strlen (Item : in chars_ptr) return size_t;

Возвращает Val'Length–1, где Val = Value(Item); генерирует Dereference_Error, если Item = Null_Ptr.

procedure Update (Item : in chars_ptr;
Offset : in size_t;
Chars : in char_array;
Check : Boolean := True);

Если Item = Null_Ptr, то Update генерирует Dereference_Error. В противном случае эта процедура обновляет значение, на которое указывает Item, начиная с позиции Offset, используя Chars как данные, которые нужно скопировать в массив. Перезапись символа nul и пропуск nul в результате Offset запрещены, если Check равен True, как показано ниже:

Пусть N = Strlen(Item). Если Check равен True, то:

Если Offset+Chars'Length>N, генерируется Update_Error.

В противном случае, перезаписываются данные в массиве, на который указывает Item, начиная с символа в позиции Offset, данными из Chars.

Если Check равен False, то обработка выполняется как выше, но без проверки Offset+Chars'Length>N.

procedure Update (Item : in chars_ptr;
Offset : in size_t;
Str : in String;
Check : in Boolean := True);

Эквивалентно Update(Item, Offset, To_C(Str, Append_Nul => False), Check).

Ошибочное выполнение

Выполнение любого из следующих действий является ошибочным, если параметр Item не равен null_ptr и Item не указывает на массив символов, завершённый нулём.

функции Value без параметра Length,

процедура Free,

функция Strlen.

Выполнение Free(X) также является ошибочным, если chars_ptr X не был возвращён New_Char_Array или New_String.

Чтение или обновление освобожденного char_array является ошибочным.

Выполнение Update является ошибочным, если Check равен False, и вызов с Check равным True сгенерировал бы Update_Error.

ПРИМЕЧАНИЕ New_Char_Array и New_String могут быть реализованы либо через функцию выделения памяти из C-среды («malloc»), либо через динамическое выделение памяти Ada («new»). Ключевые моменты:

возвращаемое значение (chars_ptr) представлено как C «char *», чтобы его можно было передавать C-функциям;

выделенный объект может быть освобождён программистом с помощью вызова Free, а не вызова C-функции.