![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Constant Nil_Array_Component
Nil_Array_Component : constant Array_Component;Expanded Name Asis.Data_Decomposition.Nil_Array_Component
Defines a value that does not reference an array component.
Description
A newly created variable of the type Array_Component has the value Nil_Array_Component and tests as Is_Nil.
Cross-References
Constant Nil_Array_Component_Iterator
Nil_Array_Component_Iterator : constant Array_Component_Iterator;Expanded Name Asis.Data_Decomposition.Nil_Array_Component_Iterator
Defines an iterator that does not reference any array component.
Description
A newly created variable of the type Array_Component_Iterator has the value Nil_Array_Component_Iterator and tests as Done.
Cross-References
Constant Nil_Record_Component
Nil_Record_Component : constant Record_Component;Expanded Name Asis.Data_Decomposition.Nil_Record_Component
Defines a value that does not reference a record component.
Description
A newly created variable of the type Record_Component has the value Nil_Record_Component and tests as Is_Nil.
Cross-References
Generic Function Portable_Constrained_Subtype
generic type Constrained_Subtype is private;function Portable_Constrained_Subtype (Data_Stream : in Asis.Portable_Transfer.Portable_Data) return Constrained_Subtype;Expanded Name Asis.Data_Decomposition.Portable_Constrained_Subtype
Returns a value of the specified subtype from the specified data stream.
Description
The generic can be used only with a scalar or a fully constrained record subtype. If an unconstrained subtype is specified, a compilation error results. If a fully constrained array is specified, no compilation error results but function might not work as intended.
Instantiations with constrained array subtypes will not correctly convert array values created by the Portable_Array_Type_1, Portable_Array_Type_2, or Portable_Array_Type_3 interfaces.
Parameters
Data_Stream : in Asis. Portable_Transfer.Portable_Data;Specifies the data stream to be converted.
return Constrained_Subtype;Returns a value of the specified subtype from the specified data stream.
Errors
Constraint_Error can be raised if the subtype is scalar and the converted value is not in the subtype's range.
Examples
Cross-References
Related subprograms and packages:
- function Component_Data_Stream
- function Construct_Artificial_Data_Stream
- package Portable_Transfer.Portable_Array_Type_1
- package Portable_Transfer.Portable_Array_Type_2
- package Portable_Transfer.Portable_Array_Type_3
Function Position
function Position (Component : in Record_Component) return Asis.Asis_Natural;
function Position (Component : in Array_Component; Index : in Asis.Asis_Positive) return Asis.Asis_Natural;
function Position (Component : in Array_Component; Indexes : in Dimension_Indexes) return Asis.Asis_Natural;
function Position (Iterator : in Array_Component_Iterator) return Asis.Asis_Natural;Expanded Name Asis.Data_Decomposition.Position
For the first form, returns the offset, from the start of the first storage unit occupied by the enclosing composite type, of the first of the storage units occupied by the specified component.
For the last three forms, returns the offset, from the start of the first storage unit occupied by the enclosing composite type, of the first of the storage units occupied by the specified element.
Description
The offset is measured in storage units.
This function is meant to reflect the value of the 'Position predefined language attribute (LRM Annex A).
Parameters
Component : in Array_Component;Component : in Record_Component;Specifies the component to query. All non-nil component values are appropriate.
Index : in Asis.Asis_Positive;Specifies the linear index value for the array component that is being queried. The value must be in the range 1 .. Array_Length (Component).
Indexes : in Dimension_Indexes;Specifies the dimensional index values for the array component that is being queried. There must be one value for each dimension of the array type, and the value must be in the range 1 .. Array_Length (Component, N), where N represents the dimension of interest.
Iterator : in Array_Component_Iterator;Specifies the array component to query.
return Asis.Asis_Natural;Returns the offset, from the start of the first storage unit occupied by the enclosing composite type, of the first of the storage units occupied by the specified component.
Errors
Asis_Inappropriate_Element is raised and Environment.Status is set to Value_Error if a parameter references a library variable that is no longer open or a parameter is specified that is not appropriate for the query.
Asis_Inappropriate_Element is raised and Environment.Status is set to Data_Error if any index is not in the expected range or if Done (Iterator) is True.
Examples
Cross-References
- type Array_Component
- function Array_Indexes
- function Array_Iterator
- function Array_Length
- function First_Bit
- function Last_Bit
- function Size
Type Record_Component
type Record_Component is private;Expanded Name Asis.Data_Decomposition.Record_Component
Describes one discriminant or component of a record type.
Description
A record type definition contains 0 or more discriminants and components. In ASIS, such types are represented by an element with an Element_Kinds of A_Record_Type_Definition or A_Derived_Type_Definition whose parent type is a record type. For purposes of data decomposition, the Record_Component type (referred to as a record component) describes either one discriminant or one component of a record type definition.
Record-Component Properties
Discriminants must be scalar, but the other components can represent scalars, records, or arrays. You can determine what kind of data a particular record component represents with the Is_Array and Is_Record functions.
The equality operator (=) is not meaningful between record- component values and should not be used unless one component is equal to Nil_Record_Component. Uninitialized record- component variables are equal to Nil_Record_Component. The Is_Equal and Is_Identical functions should be used to compare component values.
Record components become invalid and must not be used after the library containing the type definition they were derived from is closed; an exception is raised if this occurs.
Obtaining a Record's Components
The Discriminant_Components function can be used to obtain a list containing all discriminants of a record; the Record_Com-ponents function can be used to obtain a list containing all discriminants and components of a record. The components can themselves be composite, representing records or arrays.
Two methods are available to decompose composite array components and obtain the constituent record components or array component:
- The type definition of the component, if known, can be used to obtain the constituent components.
- The record component itself can be used to obtain the constituent components.
Both methods return the same values. See "Obtaining Components and Nested Components" for more information.
Using Record Components to Obtain Data
Each record component contains the information necessary to:
- Extract the component's data stream from a stream that represents a value of a record or array containing the component. This process is briefly described below and more fully described in "Constructing Artificial Data Streams."
- Obtain the declaration of the component. See "Component Properties" for more information.
- Obtain attribute data about the component. See "Runtime Representation Functions" for more information.
Recall that a data stream represents the encoding of a variable. If the variable is a record, the encoding includes the discriminants and all component values. By specifying a data stream and a record component to the Component_Data_Stream function, you can extract the stream that represents the component.
If the component is a composite, the resulting data stream represents all values. Streams that represent composite values can be decomposed repeatedly, until a component is no longer a composite.
Cross-References
- function Array_Components
- function Component_Data_Stream
- function Is_Equal
- function Is_Identical
- function Is_Nil
- constant Nil_Record_Component
- type Record_Component_List
- function Record_Components
Type Record_Component_List
type Record_Component_List is array (Asis.List_Index range <>) of Record_Component;Expanded Name Asis.Data_Decomposition.Record_Component_List
Defines a list of record components.
Description
A record component list is nil if the value of its 'Length attribute
is 0.Cross-References
Function Record_Components
function Record_Components (Component : in Array_Component) return Record_Component_List;
function Record_Components (Component : in Record_Component) return Record_Component_List;
function Record_Components (Type_Definition : in Asis.Type_Definition) return Record_Component_List;
function Record_Components (Component : in Array_Component; Data_Stream : in Asis.Portable_Transfer.Portable_Data) return Record_Component_List;
function Record_Components (Component : in Record_Component; Data_Stream : in Asis.Portable_Transfer.Portable_Data) return Record_Component_List;
function Record_Components (Type_Definition : in Asis.Type_Definition; Data_Stream : in Asis.Portable_Transfer.Portable_Data) return Record_Component_List;Expanded Name Asis.Data_Decomposition.Record_Components
Returns a list containing the discriminants and components of the specified array component, record component, or record type definition.
Description
The returned list includes implementation-defined components (Ada83 LRM 13.4(8), Ada95 LRM 13.5.1). Refer to the Appendix F for your compilation system to determine whether your compiler generates implementation-defined components.
The returned components can be used with a data stream representing a value of the specified component or type.
All returned values are valid parameters for all functions.
If a simple static type is specified, it always returns the same component list (Is_Equal components) regardless of the data stream. The layout of a simple static type does not change with changes in discriminant values because there are no variant parts in the definition.
If a simple dynamic type is specified, it can return different component lists (non-Is_Equal components). The layout of a dynamic data type changes with changes in discriminant values because of the variant parts in the definition.
If a data stream is specified, it can represent an actual stream or an artificial stream as constructed with Construct_Artificial-_Data_Stream. Only the discriminant portion of the data stream is checked for validity, and only some discriminant fields might need to be checked, depending on the complexity of the record type. It is not necessary to provide values for nondiscriminant fields, but it is safer to do so.
If a data stream is specified, the returned list contains components that describe the locations of the record's discriminants and all components of the appropriate variant parts. The con-tents of the list are determined by the discriminant values in the data stream, and some components might not exist in the list (because they are not in an active variant part).
Parameters
Component : in Array_Component;Component : in Record_Component;Specifies the component to query. All components with a record subtype (Is_Record = True) are appropriate.
For the first three forms of the function, the component must be A_Simple_Static_Model. For the last three forms of the function, the component must be A_Simple_Static_Model or A_Simple-_Dynamic_Model.
Type_Definition : in Asis.Type_Definition;Specifies the record type definition to be queried. The type definition must be of the following kinds:
Element_Kinds Type_Definition_Kinds
A_Type_Definition A_Derived_Type_Definition1
A_Record_Type_Definition
1 Whose parent type is a record type.
For the first form of the function, the type definition must be A_Simple_Static_Model. For the second form of the function, it must be A_Simple_Static_Model or A_Simple_Dynamic_Model.
Data_Stream : in Asis. Portable_Transfer.Portable_Data;Specifies the data stream containing at least discriminant values.
return Record_Component_List;Returns a list containing the discriminants and components of the specified or referenced record type.
Errors
Asis_Inappropriate_Element is raised and Environment.Status is set to Value_Error if a parameter references a library variable that is no longer open or a parameter is specified that is not appropriate for the query.
Examples
Cross-References
Procedure Reset
procedure Reset (Iterator : in out Array_Component_Iterator);Expanded Name Asis.Data_Decomposition.Reset
Resets the iterator so that it references the first array component.
Description
Use the Next procedure to iterate to the next array component.
Parameters
Iterator : in out Array_Component_Iterator;Specifies the iterator to reset.
Errors
Asis_Inappropriate_Element is raised and Environment.Status is set to Value_Error if a parameter references a library variable that is no longer open or a parameter is specified that is not appropriate for the query.
Examples
Cross-References
Function Size
function Size (Component : in Array_Component) return Asis.Asis_Natural;
function Size (Component : in Record_Component) return Asis.Asis_Natural;
function Size (Type_Definition : in Asis.Type_Definition) return Asis.Asis_Natural;
function Size (Type_Definition : in Asis.Type_Definition; Data_Stream : in Asis.Portable_Transfer.Portable_Data) return Asis.Asis_Natural;Expanded Name Asis.Data_Decomposition.Size
For the first three forms, returns the 'Size attribute value for the specified component or type definition.
For the fourth form, returns the 'Size attribute value for the specified type definition with the discriminants as defined in the specified data stream.
Description
Returns the minimum number of bits required to hold a simple static type, the number of bits allocated to hold a record field, or the number of bits allocated to hold each array component.
If a component is specified, the returned value represents the actual number of bits allocated to the component. The size can be greater than the number of bits normally occupied by values of this type and is typically the result of a representation specification. If this is the case, the value can be preceded, followed, or surrounded by pad bits to fully occupy the space allotted.
If a data stream is specified, it can represent an actual stream or an artificial stream as constructed with Construct_Artificial-_Data_Stream. Only the discriminant portion of the data stream is checked for validity, and only some discriminant fields might need to be checked, depending on the complexity of the record type. It is not necessary to provide values for nondiscriminant fields, but it is safer to do so. The returned value is the minimum number of bits required to hold any possible value of the given fully constrained subtype.
Parameters
Component : in Array_Component;Component : in Record_Component;Specifies the component to query. All non-nil component values are appropriate and must be of the following type model kind:
Type_Model_Kinds
A_Simple_Static_Model
Type_Definition : in Asis.Type_Definition;Specifies the type definition to be queried. The type definition must be of the following kind:
Element_Kinds
A_Type_Definition
For the first form of the function, the type definition must be A_Simple_Static_Model. For the second form of the function, it must be A_Simple_Static_Model or A_Simple_Dynamic_Model.
Data_Stream : in Asis. Portable_Transfer.Portable_Data;Specifies the data stream containing at least discriminant values.
return Asis.Asis_Natural;Returns the value of the 'Size attribute for the specified
parameters.Errors
Asis_Inappropriate_Element is raised and Environment.Status is set to Value_Error if a parameter references a library variable that is no longer open or a parameter is specified that is not appropriate for the query.
Examples
Cross-References
Function Type_Model_Kind
function Type_Model_Kind (Component : in Array_Component) return Type_Model_Kinds;
function Type_Model_Kind (Component : in Record_Component) return Type_Model_Kinds;
function Type_Model_Kind (Type_Definition : in Asis.Type_Definition) return Type_Model_Kinds;Expanded Name Asis.Data_Decomposition.Type_Model_Kind
Returns the type model kind for the specified component or type definition.
Description
See the Type_Model_Kinds type for a summary of the models and "Type-Definition Model Kinds" for a detailed description of the type definitions that are represented by each model.
Parameters
Component : in Array_Component;Component : in Record_Component;Specifies the component to be queried. All component values are appropriate.
Type_Definition : in Asis.Type_Definition;Specifies the type definition to be queried. The type definition must be of the following kind:
Element_Kinds
A_Type_Definition
return Type_Model_Kinds;Returns the type model kind for all appropriate parameters, as described above, or Not_A_Type_Model for any unexpected parameters.
Errors
Asis_Inappropriate_Library is raised and Environment.Status is set to Value_Error if a parameter references a library that is no longer open.
Examples
Cross-References
Type Type_Model_Kinds
type Type_Model_Kinds is (...)Expanded Name Asis.Data_Decomposition.Type_Model_Kinds
Defines the kinds of type-definition models recognized by ASIS.
Description
The type-definition model kinds are not intrinsic to Ada. They are defined by ASIS to categorize and simplify reference to the kinds of type definitions that packages Data_Decomposition and Portable_Transfer can process.
The type-definition model kinds range from simple and static to complex and dynamic, based on whether the definition includes discriminants and variant parts or not and how the values for those discriminants are specified.
See "Type-Definition Model Kinds" for a detailed description of the type definitions that are represented by each model.
Parameters
A_Simple_Static_ModelIndicates that the component or type contains no variants and has a single fixed 'Size attribute value that and all components and attributes are themselves static and/or fully constrained.
A_Simple_Dynamic_ModelIndicates that the component or type contains one or more components or attributes whose size, position, or value depends on the value of one or more discriminants computed during execution.
The size, positions, or number of components cannot be determined without reference to actual discriminant values.
A_Complex_Dynamic_ModelIndicates that the component or type contains one or more components or attributes whose size, position, or value depends on one or more nonstatic values that are not stored within instances of the type.
The size, positions, or number of components cannot be determined without reference to these nonstatic values, whose runtime values are not known to the ASIS library and cannot be recorded automatically by the Portable_Transfer generics.
Not_A_Type_ModelIndicates that the specified array or record component is nil or that the specified element is not a type definition.
Cross-References
Rational Software Corporation
http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |