Ada Conformity Assessment Authority      Home Conformity Assessment   Test Suite ARGAda Standard
Ada Reference Manual (Ada 2022 Draft 35)Legal Information
Contents   Index   References   Search   Previous   Next 

11.4.1 The Package Exceptions

Static Semantics

The following language-defined library package exists: 
with Ada.Streams;
package Ada.Exceptions 
    with Preelaborate, Nonblocking, Global => in out synchronized is
    type Exception_Id is private
        with Preelaborable_Initialization;
    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;
    type Exception_Occurrence is limited private
        with Preelaborable_Initialization;
    type Exception_Occurrence_Access is access all Exception_Occurrence;
    Null_Occurrence : constant Exception_Occurrence;
    procedure Raise_Exception(E : in Exception_Id;
                              Message : in String := "")
        with No_Return;
    function Exception_Message(X : Exception_Occurrence) return String;
    procedure Reraise_Occurrence(X : in Exception_Occurrence);
    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;
    procedure Save_Occurrence(Target : out Exception_Occurrence;
                              Source : in Exception_Occurrence);
    function Save_Occurrence(Source : Exception_Occurrence)
                             return Exception_Occurrence_Access;
    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);
    for Exception_Occurrence'Read use Read_Exception_Occurrence;
    for Exception_Occurrence'Write use Write_Exception_Occurrence;
   ... -- not specified by the language
end Ada.Exceptions;
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.
For a prefix E that denotes an exception, the following attribute is defined: 
E'Identity returns the unique identity of the exception. The type of this attribute is Exception_Id.
Raise_Exception raises a new occurrence of the identified exception.
  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 or raise_expression with an exception_name and a string_expression or string_simple_expression, the message is the string_expression or string_simple_expression. For the occurrence raised by a raise_statement or raise_expression with an exception_name but without a string_expression or string_simple_expression, the message is a string giving implementation-defined information about the exception occurrence. For an occurrence originally raised in some other manner (including by the failure of a language-defined check), the message is an unspecified string. In all cases, Exception_Message returns a string with lower bound 1. 
  Reraise_Occurrence reraises the specified exception occurrence.
Exception_Identity returns the identity of the exception of the occurrence.
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 is returned. The result is implementation defined if the exception is declared within an unnamed block_statement.
  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. 
  The string returned by the Exception_Name, Wide_Exception_Name, and Wide_Wide_Exception_Name functions has lower bound 1.
Exception_Information returns implementation-defined information about the exception occurrence. The returned string has lower bound 1. 
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.
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.
  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). 
Paragraph 16 was deleted. 

Implementation Permissions

An implementation of Exception_Name in a space-constrained environment may return the defining_identifier instead of the full expanded name.
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

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.
NOTE   UTF-8 encoding (see A.4.11) can be used to represent non-ASCII characters in exception messages.

Contents   Index   References   Search   Previous   Next 
Ada-Europe Ada 2005 and 2012 Editions sponsored in part by Ada-Europe