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

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

Пакет Interfaces.C.Strings объявляет типы и подпрограммы, позволяющие программе Ada выделять, ссылаться, обновлять и освобождать строки в стиле C. В частности, приватный тип chars_ptr соответствует обычному использованию ``char *'' в программах C, и объект этого типа может быть передан подпрограмме, к которой применено pragma Import(C,...), и для которой ``char *'' является типом аргумента функции C.

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

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

package Interfaces.C.Strings is pragma Preelaborate(Strings);

type char_array_access is access all char_array;

type chars_ptr is private;

type chars_ptr_array is array (size_t range <>) of 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 и соответствует использованию ``char *'' в C для указателя на первый символ в массиве 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 не содержит нуль, то функция распространяет 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 не содержит нуль, или

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, до и включая первый нуль. Нижний предел результата равен 0. Если Item не указывает на строку, завершающуюся нулём, то выполнение 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 в качестве данных для копирования в массив. Перезапись символа нуль и пропуск символа нуль с помощью 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), 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.

ПРИМЕЧАНИЯ

13 New_Char_Array и New_String могут быть реализованы либо через функцию выделения из среды C (``malloc''), либо через динамическое выделение памяти Ada (``new''). Ключевыми моментами являются

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

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