CryptAda.Lists.Identifier_Item

Contents

• Overview
• Subprograms
  • Copy_Identifier
  • Text_2_Identifier
  • Identifier_2_Text
  • Is_Null
  • Make_Null
  • Is_Equal
  • Text_Length
  • Get_Value
  • Replace_Value
  • Insert_Value
  • Position_By_Value
  • Is_Enumerated
  • Enumeration_Pos

Overview

This package provides functionality for handling Identifiers either as items in lists or as item name in both, text form and as Identifier objects. Manipulation of Identifiers in the enumeration form is provided by the generic package CryptAda.Lists.Enumeration_Item.

Identifiers are character sequence that meet the syntax rules for Ada identifiers:

• First character must be a letter (Ada.Characters.Handling.Is_Letter shall return True for that character).
• Next characters must be either alphanumeric characters or the underscore '_' character.
• No two or more consecutive underscore characters are allowed and the underscore could not be the last character of the identifier.
• Ada reserved words are not allowed as identifiers.

Identifier comparison is case unsensitive, when converting from identifier text to Identifier, any whitespace (' ' | HT .. CR) before first identifier character or after the last identifier character is removed.

Case, when returning back the text from an Identifier object is preserved.

Maximum length for identifier is defined by the constant Identifier_Max_Length defined in CryptAda.Lists.

A null identifier represents an undefined identifier and is the value that an Identifier object acquires when its definition is elaborated.

Subprograms

Copy_Identifier

Specification

   procedure   Copy_Identifier(
                  From           : in     Identifier;
                  To             : in out Identifier);

Purpose

Returns in To a copy of From.

Arguments

• From. Source Identifier of the copy.
• To. Target Identifier of the copy.

Exceptions

• CryptAda_Identifier_Error if From is a null identifier.
• CryptAda_Storage_Error if an error is raised when allocating space for the copied items.

Text_2_Identifier

Specification

   procedure   Text_2_Identifier(
                  From           : in     Identifier_Text;
                  To             : in out Identifier);

Purpose

Converts an identifier text to its identifier representation.

Arguments

• From. Identifier text to convert.
• To. Identifier resulting from From conversion.

Exceptions

• CryptAda_Overflow_Error if From identifier characters exceeds the maximum defined length for identifiers.
• CryptAda_Storage_Error if an error is raised when allocating space for the identifier.
• CryptAda_Syntax_Error if From does not meet the syntax rules for identifiers.

Identifier_2_Text

Specification

   procedure   Identifier_2_Text(
                  From           : in     Identifier;
                  To             :    out Identifier_Text;
                  Length         :    out Positive);

   function    Identifier_2_Text(
                  From           : in     Identifier)
      return   Identifier_Text;

Purpose

Returns the text representation of an identifier value.

Two overloaded forms are provided: a procedure form and a function form.

The case of the identifier characters in the identifier text returned by these subprograms is preserved so:

declare
   Id_Text_1     : constant Identifier_Text := "Hello";
   Id            : Identifier;
begin
   Text_2_Identifier(Id_Text_1, Id);

   declare
      Id_Text_2 : constant Identifier_Text := Identifier_2_Text(Id);
      B         : Boolean := (Id_Text_1 = Id_Text_2);
   begin
      -- B is always True.
   end;
end;

Arguments

• From. Identifier from which the text form is to be returned.
• To. Procedure form, Identifier_Text object where the text form of From will be copied.
• Length. Procedure form, number of characters copied to To.

Returned value

Function form, Identifier_Text value containing the text representation of From.

Exceptions

• CryptAda_Identifier_Error if From is a null identifier.
• CryptAda_Overflow_Error (procedure form) if To length is not enough to hold the text representation of From.

Is_Null

Specification

   function    Is_Null(
                  What           : in     Identifier)
      return   Boolean;

Purpose

Checks whether or not an Identifier is null.

Arguments

• What. Identifier to check.

Returned value

Boolean value indicating whether the Identifier is null or not.

Exceptions

None.

Make_Null

Specification

   procedure   Make_Null(
                  What           : in out Identifier);

Purpose

Makes a given identifier null.

Arguments

• What. Identifier to make null.

Exceptions

None.

Is_Equal

Specification

   function    Is_Equal(
                  Left           : in     Identifier;
                  Right          : in     Identifier)
      return   Boolean;

Purpose

Equality test for Identifiers. Two identifiers are equal if:

• They are both null.
• They contain the same sequence of characters ignoring case for letters.

Note:

declare
   Id_T_1        : constant Identifier_Text := "Hello";
   Id_T_2        : constant Identifier_Text := "HELLO";
   Id_1          : Identifier;
   Id_2          : Identifier;
begin
   Text_2_Identifier(Id_T_1, Id_1);
   Text_2_Identifier(Id_T_2, Id_2);

   -- (Id_T_1 = Id_T_2) is always False.
   -- Is_Equal(Id_1, Id_2) is always True.
end;

Arguments

• Left. First identifier to compare.
• Right. Second identifier to compare.

Returned value

Boolean value indicating if the identifiers are equal or not.

Exceptions

None.

Text_Length

Specification

   function    Text_Length(
                  Of_Id          : in     Identifier)
      return   Natural;

Purpose

Returns the length of the text representation of an Identifier.

Arguments

• Of_Id. Identifier for which the text length is to be obtained.

Returned value

Natural value with Of_Id text length.

Exceptions

None.

Get_Value

Specification

   procedure   Get_Value(
                  From_List      : in     List;
                  At_Position    : in     Position_Count;
                  Value          : in out Identifier);

   procedure   Get_Value(
                  From_List      : in     List;
                  Item_Name      : in     Identifier;
                  Value          : in out Identifier);

   procedure   Get_Value(
                  From_List      : in     List;
                  Item_Name      : in     Identifier_Text;
                  Value          : in out Identifier);

Purpose

Returns the value of a specific Identifier item from the current list of a List object.

Three overloaded forms are provided:

• Returns the identifier item value provided its position (unnamed and named lists).
• Returns the identifier item value provided its item name as an Identifier (named lists).
• Returns the identifier item value provided its item name as an Identifier_Text (named lists).

Arguments

• From_List. List object from whose current list the identifier item value is to be retrieved.
• At_Position. First overloaded form, position of the identifier item in From_List current list.
• Item_Name. Second and third overloaded forms, either an Identifier or an Identifier_Text with the name of the identifier item.
• Value. Value of the identifier item.

Exceptions

• CryptAda_List_Kind_Error if From_List current list is Empty.
• CryptAda_Index_Error if At_Position is not a valid position in From_List current list.
• CryptAda_Identifier_Error (second form) if the Item_Name is a null identifier.
• CryptAda_Syntax_Error (third form) if the Identifier_Text does not conform the syntax for identifiers.
• CryptAda_Named_List_Error (second and third forms) if From_List current list is an unnamed list.
• CryptAda_Item_Not_Found_Error (second and third forms) there is no item with Item_Name in the current list of From_List.
• CryptAda_Item_Kind_Error if At_Position or Item_Name identify an item whose kind is not Identifier_Item_Kind.

Replace_Value

Specification

   procedure   Replace_Value(
                  In_List        : in out List;
                  At_Position    : in     Position_Count;
                  Value          : in     Identifier);

   procedure   Replace_Value(
                  In_List        : in out List;
                  Item_Name      : in     Identifier;
                  Value          : in     Identifier);

   procedure   Replace_Value(
                  In_List        : in out List;
                  Item_Name      : in     Identifier_Text;
                  Value          : in     Identifier);

Purpose

Replaces the value of a specific Identifier item from the current list of a List object with a replacement identifier provided.

Three overloaded forms are provided:

• Replaces the identifier item value provided its position (unnamed and named lists).
• Replaces the identifier item value provided its item name as an Identifier (named lists).
• Replaces the identifier item value provided its item name as an Identifier_Text (named lists).

Arguments

• In_List. List object from whose current list contains the identifier item whose value is to be replaced.
• At_Position. First overloaded form, position of the identifier item in In_List current list.
• Item_Name. Second and third overloaded forms, either an Identifier or an Identifier_Text with the name of the identifier item.
• Value. New value for the identifier item.

Exceptions

• CryptAda_List_Kind_Error if In_List current list is Empty.
• CryptAda_Index_Error if At_Position is not a valid position in In_List current list.
• CryptAda_Identifier_Error if the Item_Name in the second form is a null identifier or if Value is a null identifier.
• CryptAda_Syntax_Error (third form) if the Identifier_Text does not conform the syntax for identifiers.
• CryptAda_Named_List_Error (second and third forms) if In_List current list is an unnamed list.
• CryptAda_Item_Not_Found_Error (second and third forms) there is no item with Item_Name in the current list of In_List.
• CryptAda_Item_Kind_Error if At_Position or Item_Name identify an item whose kind is not Identifier_Item_Kind.

Insert_Value

Specification

   procedure   Insert_Value(
                  In_List        : in out List;
                  At_Position    : in     Insert_Count;
                  Value          : in     Identifier);

   procedure   Insert_Value(
                  In_List        : in out List;
                  At_Position    : in     Insert_Count;
                  Item_Name      : in     Identifier;
                  Value          : in     Identifier);

   procedure   Insert_Value(
                  In_List        : in out List;
                  At_Position    : in     Insert_Count;
                  Item_Name      : in     Identifier_Text;
                  Value          : in     Identifier);

Purpose

Inserts an Identifier value at a specific position into the current list of a List object.

Three overloaded forms are provided:

• Inserts an unnamed identifier value.
• Inserts a named identifier value given its name as Identifier.
• Inserts a named identifier value given its name as Identifier_Text.

Arguments

• In_List. List object in whose current list the identifier item is to be inserted.
• At_Position. Insert count value that specifies the position where insertion will take place (0 meaning at the beginning and any positive value means after the item which ocuppies At_Position position).
• Item_Name. Second and third overloaded forms, either an Identifier or an Identifier_Text with the name of the identifier item to insert.
• Value. Value of the identifier item to insert.

Exceptions

• CryptAda_List_Kind_Error if In_List is named and the first form is used or if In_List is unnamed and second and third forms are attempted.
• CryptAda_Index_Error if At_Position is not a valid insertion position in In_List current list.
• CryptAda_Identifier_Error if the Item_Name in the second form is a null identifier or if Value is a null identifier.
• CryptAda_Syntax_Error (third form) if the Identifier_Text does not conform the syntax for identifiers.
• CryptAda_Overflow_Error if the insertion operation will cause that In_List current list will exceed the maximum number of items for a List object.

Position_By_Value

Specification

   function    Position_By_Value(
                  In_List        : in     List;
                  Value          : in     Identifier;
                  Start_Position : in     Position_Count := Position_Count'First;
                  End_Position   : in     Position_Count := Position_Count'Last)
      return   Position_Count;

Purpose

Returns the position that an Identifier item with a specific value occupies into the current list of a List object.

Arguments

• In_List. List object to query for the item position.
• Value. Item value searched for.
• Start_Position. Position in the current list to start the search from.
• End_Position. Position in the current list beyond which the search will not proceed.

Exceptions

• CryptAda_List_Kind_Error if In_List is empty.
• CryptAda_Index_Error if Start_Position is greater than the number of items In_List or if it is greater than End_Position.
• CryptAda_Identifier_Error if Value is a null identifier.
• CryptAda_Item_Not_Found_Error if no item with value Value was found In_List.

Is_Enumerated

Specification

   function    Is_Enumerated(
                  In_List        : in     List;
                  At_Position    : in     Position_Count)
      return   Boolean;

   function    Is_Enumerated(
                  In_List        : in     List;
                  Item_Name      : in     Identifier)
      return   Boolean;

   function    Is_Enumerated(
                  In_List        : in     List;
                  Item_Name      : in     Identifier_Text)
      return   Boolean;

Purpose

Determines if a specified Identifier item in the current list of a list object is an enumerated item.

Three overloaded forms are provided:

• Item is specified by position (named and unnamed lists).
• Item is specified by name provided as an Identifier (named lists).
• Item is specified by name provided as an Identifier_Text (named lists).

Arguments

• In_List. List object to query.
• At_Position. (First form) position of the item to query.
• Item_Name. Second and third overloaded forms, either an Identifier or an Identifier_Text with the name of the identifier item to query.

Returned value

Boolean value that indicates if the identifier item specified is an enumerated value.

Exceptions

• CryptAda_List_Kind_Error if In_List is empty.
• CryptAda_Index_Error if At_Position is not a valid position in In_List current list.
• CryptAda_Identifier_Error (second form) if the Item_Name is a null identifier.
• CryptAda_Syntax_Error (third form) if the Identifier_Text does not conform the syntax for identifiers.
• CryptAda_Named_List_Error (second and third forms) if From_List current list is an unnamed list.
• CryptAda_Item_Not_Found_Error (second and third forms) there is no item with Item_Name in the current list of From_List.
• CryptAda_Item_Kind_Error if At_Position or Item_Name identify an item whose kind is not Identifier_Item_Kind.

Enumeration_Pos

Specification

   function    Enumeration_Pos(
                  In_List        : in     List;
                  At_Position    : in     Position_Count)
      return   Integer;

   function    Enumeration_Pos(
                  In_List        : in     List;
                  Item_Name      : in     Identifier)
      return   Integer;

   function    Enumeration_Pos(
                  In_List        : in     List;
                  Item_Name      : in     Identifier_Text)
      return   Integer;

Purpose

Returns the value of the attribute 'Pos of an Identifier item that is an enumerated item in the current list of a list object.

Three overloaded forms are provided:

• Item is specified by position (named and unnamed lists).
• Item is specified by name provided as an Identifier (named lists).
• Item is specified by name provided as an Identifier_Text (named lists).

Arguments

• In_List. List object to query.
• At_Position. (First form) position of the item to query.
• Item_Name. Second and third overloaded forms, either an Identifier or an Identifier_Text with the name of the identifier item to query.

Returned value

Integer with the value of 'Pos attribute of the enumeration value.

Exceptions

• CryptAda_List_Kind_Error if In_List is empty.
• CryptAda_Index_Error if At_Position is not a valid position in In_List current list.
• CryptAda_Identifier_Error (second form) if the Item_Name is a null identifier.
• CryptAda_Syntax_Error (third form) if the Identifier_Text does not conform the syntax for identifiers.
• CryptAda_Named_List_Error (second and third forms) if From_List current list is an unnamed list.
• CryptAda_Item_Not_Found_Error (second and third forms) there is no item with Item_Name in the current list of From_List.
• CryptAda_Item_Kind_Error if At_Position or Item_Name identify an item whose kind is not Identifier_Item_Kind or if being an Identifier is not an enumeration value.