Next: , Previous: 11.4, Up: 11.4


11.4.1 The Package Exceptions

Static Semantics

1
The following language−defined library package exists:

2/2

     with Ada.Streams;
     package Ada.Exceptions is
         pragma Preelaborate(Exceptions);
         type Exception_Id is private;
         pragma Preelaborable_Initialization(Exception_Id);
         Null_Id constant Exception_Id;
         function Exception_Name(Id Exception_Id) return String;
         function Wide_Exception_Name(Id Exception_Id) return Wide_String;
         function Wide_Wide_Exception_Name(Id Exception_Id)
             return Wide_Wide_String;

3/2

         type Exception_Occurrence is limited private;
         pragma Preelaborable_Initialization(Exception_Occurrence);
         type Exception_Occurrence_Access is access all Exception_Occurrence;
         Null_Occurrence constant Exception_Occurrence;

4/2

         procedure Raise_Exception(E in Exception_Id;
                                   Message in String := "");
             pragma No_Return(Raise_Exception);
         function Exception_Message(X Exception_Occurrence) return String;
         procedure Reraise_Occurrence(X in Exception_Occurrence);

5/2

         function Exception_Identity(X Exception_Occurrence)
                                     return Exception_Id;
         function Exception_Name(X Exception_Occurrence) return String;
             −− Same as Exception_Name(Exception_Identity(X)).
         function Wide_Exception_Name(X Exception_Occurrence)
             return Wide_String;
             −− Same as Wide_Exception_Name(Exception_Identity(X)).
         function Wide_Wide_Exception_Name(X Exception_Occurrence)
             return Wide_Wide_String;
             −− Same as Wide_Wide_Exception_Name(Exception_Identity(X)).
         function Exception_Information(X Exception_Occurrence) return String;

6/2

         procedure Save_Occurrence(Target out Exception_Occurrence;
                                   Source in Exception_Occurrence);
         function Save_Occurrence(Source Exception_Occurrence)
                                  return Exception_Occurrence_Access;

6.1/2

         procedure Read_Exception_Occurrence
            (Stream not null access Ada.Streams.Root_Stream_Type'Class;
             Item   out Exception_Occurrence);
         procedure Write_Exception_Occurrence
            (Stream not null access Ada.Streams.Root_Stream_Type'Class;
             Item   in Exception_Occurrence);

6.2/2

         for Exception_Occurrence'Read use Read_Exception_Occurrence;
         for Exception_Occurrence'Write use Write_Exception_Occurrence;

6.3/2

     private
        ... −− not specified by the language
     end Ada.Exceptions;

7
Each distinct exception is represented by a distinct value of type Exception_Id. Null_Id does not represent any exception, and is the default initial value of type Exception_Id. Each occurrence of an exception is represented by a value of type Exception_Occurrence. Null_Occurrence does not represent any exception occurrence, and is the default initial value of type Exception_Occurrence.

8/1
For a prefix E that denotes an exception, the following attribute is defined:

9
E'Identity

E'Identity returns the unique identity of the exception. The type of this attribute is Exception_Id.

10/2
Raise_Exception raises a new occurrence of the identified exception.

10.1/2
Exception_Message returns the message associated with the given Exception_Occurrence. For an occurrence raised by a call to Raise_Exception, the message is the Message parameter passed to Raise_Exception. For the occurrence raised by a raise_statement with an exception_name and a string_expression, the message is the string_expression. For the occurrence raised by a raise_statement with an exception_name but without a string_expression, the message is a string giving implementation−defined information about the exception occurrence. In all cases, Exception_Message returns a string with lower bound 1.

10.2/2
Reraise_Occurrence reraises the specified exception occurrence.

11
Exception_Identity returns the identity of the exception of the occurrence.

12/2
The Wide_Wide_Exception_Name functions return the full expanded name of the exception, in upper case, starting with a root library unit. For an exception declared immediately within package Standard, the defining_identifier (see 3.1) is returned. The result is implementation defined if the exception is declared within an unnamed block_statement.

12.1/2
The Exception_Name functions (respectively, Wide_Exception_Name) return the same sequence of graphic characters as that defined for Wide_Wide_Exception_Name, if all the graphic characters are defined in Character (respectively, Wide_Character); otherwise, the sequence of characters is implementation defined, but no shorter than that returned by Wide_Wide_Exception_Name for the same value of the argument.

12.2/2
The string returned by the Exception_Name, Wide_Exception_Name, and Wide_Wide_Exception_Name functions has lower bound 1.

13/2
Exception_Information returns implementation−defined information about the exception occurrence. The returned string has lower bound 1.

14/2
Reraise_Occurrence has no effect in the case of Null_Occurrence. Raise_Exception and Exception_Name raise Constraint_Error for a Null_Id. Exception_Message, Exception_Name, and Exception_Information raise Constraint_Error for a Null_Occurrence. Exception_Identity applied to Null_Occurrence returns Null_Id.

15
The Save_Occurrence procedure copies the Source to the Target. The Save_Occurrence function uses an allocator of type Exception_Occurrence_Access to create a new object, copies the Source to this new object, and returns an access value designating this new object; the result may be deallocated using an instance of Unchecked_Deallocation.

15.1/2
Write_Exception_Occurrence writes a representation of an exception occurrence to a stream; Read_Exception_Occurrence reconstructs an exception occurrence from a stream (including one written in a different partition).

Implementation Requirements

16/2
This paragraph was deleted.

Implementation Permissions

17
An implementation of Exception_Name in a space−constrained environment may return the defining_identifier (see 3.1) instead of the full expanded name.

18
The string returned by Exception_Message may be truncated (to no less than 200 characters) by the Save_Occurrence procedure (not the function), the Reraise_Occurrence procedure, and the re−raise statement.

Implementation Advice

19
Exception_Message (by default) and Exception_Information should produce information useful for debugging. Exception_Message should be short (about one line), whereas Exception_Information can be long. Exception_Message should not include the Exception_Name. Exception_Information should include both the Exception_Name and the Exception_Message.