Node:Top, Next:

Node:Foreword, Next:, Previous:Top, Up:Top

Foreword

  1. ISO (the International Organization for Standardization) and IEC (the International Electrotechnical Commission) form the specialized system for worldwide standardization. National bodies that are members of ISO or IEC participate in the development of International Standards through technical committees established by the respective organization to deal with particular fields of technical activity. ISO and IEC technical committees collaborate in fields of mutual interest. Other international organizations, governmental and non-governmental, in liaison with ISO and IEC, also take part in the work.
  2. In the field of information technology, ISO and IEC have established a joint technical committee, ISO/IEC JTC 1. Draft International Standards adopted by the joint technical committee are circulated to national bodies for voting. Publication as an International Standard requires approval by at least 75 % of the national bodies casting a vote.
  3. International Standard ISO/IEC 8652 was prepared by Joint Technical Committee ISO/IEC JTC 1, Information Technology.
  4. This second edition cancels and replaces the first edition (ISO 8652:1987), of which it constitutes a technical revision.
  5. Annexes A to J form an integral part of this International Standard. Annexes K to P are for information only.

Node:Introduction, Next:, Previous:Foreword, Up:Top

Introduction

  1. This is the Ada Reference Manual.
  2. Other available Ada documents include:
    1. Rationale for the Ada Programming Language - 1995 edition, which gives an introduction to the new features of Ada, and explains the rationale behind them. Programmers should read this first.
    2. Changes to Ada - 1987 to 1995. This document lists in detail the changes made to the 1987 edition of the standard.
    3. The Annotated Ada Reference Manual (AARM). The AARM contains all of the text in the RM95, plus various annotations. It is intended primarily for compiler writers, validation test writers, and others who wish to study the fine details. The annotations include detailed rationale for individual rules and explanations of some of the more arcane interactions among the rules.

Node:Design Goals, Next:, Previous:Introduction, Up:Introduction

Design Goals

  1. Ada was originally designed with three overriding concerns: program reliability and maintenance, programming as a human activity, and efficiency. This revision to the language was designed to provide greater flexibility and extensibility, additional control over storage management and synchronization, and standardized packages oriented toward supporting important application areas, while at the same time retaining the original emphasis on reliability, maintainability, and efficiency.
  2. The need for languages that promote reliability and simplify maintenance is well established. Hence emphasis was placed on program readability over ease of writing. For example, the rules of the language require that program variables be explicitly declared and that their type be specified. Since the type of a variable is invariant, compilers can ensure that operations on variables are compatible with the properties intended for objects of the type. Furthermore, error-prone notations have been avoided, and the syntax of the language avoids the use of encoded forms in favor of more English-like constructs. Finally, the language offers support for separate compilation of program units in a way that facilitates program development and maintenance, and which provides the same degree of checking between units as within a unit.
  3. Concern for the human programmer was also stressed during the design. Above all, an attempt was made to keep to a relatively small number of underlying concepts integrated in a consistent and systematic way while continuing to avoid the pitfalls of excessive involution. The design especially aims to provide language constructs that correspond intuitively to the normal expectations of users.
  4. Like many other human activities, the development of programs is becoming ever more decentralized and distributed. Consequently, the ability to assemble a program from independently produced software components continues to be a central idea in the design. The concepts of packages, of private types, and of generic units are directly related to this idea, which has ramifications in many other aspects of the language. An allied concern is the maintenance of programs to match changing requirements; type extension and the hierarchical library enable a program to be modified while minimizing disturbance to existing tested and trusted components.
  5. No language can avoid the problem of efficiency. Languages that require over-elaborate compilers, or that lead to the inefficient use of storage or execution time, force these inefficiencies on all machines and on all programs. Every construct of the language was examined in the light of present implementation techniques. Any proposed construct whose implementation was unclear or that required excessive machine resources was rejected.

Node:Language Summary, Next:, Previous:Design Goals, Up:Introduction

Language Summary

  1. An Ada program is composed of one or more program units. Program units may be subprograms (which define executable algorithms), packages (which define collections of entities), task units (which define concurrent computations), protected units (which define operations for the coordinated sharing of data between tasks), or generic units (which define parameterized forms of packages and subprograms). Each program unit normally consists of two parts: a specification, containing the information that must be visible to other units, and a body, containing the implementation details, which need not be visible to other units. Most program units can be compiled separately.
  2. This distinction of the specification and body, and the ability to compile units separately, allows a program to be designed, written, and tested as a set of largely independent software components.
  3. An Ada program will normally make use of a library of program units of general utility. The language provides means whereby individual organizations can construct their own libraries. All libraries are structured in a hierarchical manner; this enables the logical decomposition of a subsystem into individual components. The text of a separately compiled program unit must name the library units it requires.

Node:Program Units, Next:, Previous:Language Summary, Up:Introduction

Program Units

  1. A subprogram is the basic unit for expressing an algorithm. There are two kinds of subprograms: procedures and functions. A procedure is the means of invoking a series of actions. For example, it may read data, update variables, or produce some output. It may have parameters, to provide a controlled means of passing information between the procedure and the point of call. A function is the means of invoking the computation of a value. It is similar to a procedure, but in addition will return a result.
  2. A package is the basic unit for defining a collection of logically related entities. For example, a package can be used to define a set of type declarations and associated operations. Portions of a package can be hidden from the user, thus allowing access only to the logical properties expressed by the package specification.
  3. Subprogram and package units may be compiled separately and arranged in hierarchies of parent and child units giving fine control over visibility of the logical properties and their detailed implementation.
  4. A task unit is the basic unit for defining a task whose sequence of actions may be executed concurrently with those of other tasks. Such tasks may be implemented on multicomputers, multiprocessors, or with interleaved execution on a single processor. A task unit may define either a single executing task or a task type permitting the creation of any number of similar tasks.
  5. A protected unit is the basic unit for defining protected operations for the coordinated use of data shared between tasks. Simple mutual exclusion is provided automatically, and more elaborate sharing protocols can be defined. A protected operation can either be a subprogram or an entry. A protected entry specifies a Boolean expression (an entry barrier) that must be true before the body of the entry is executed. A protected unit may define a single protected object or a protected type permitting the creation of several similar objects.

Node:Declarations and Statements, Next:, Previous:Program Units, Up:Introduction

Declarations and Statements

  1. The body of a program unit generally contains two parts: a declarative part, which defines the logical entities to be used in the program unit, and a sequence of statements, which defines the execution of the program unit.
  2. The declarative part associates names with declared entities. For example, a name may denote a type, a constant, a variable, or an exception. A declarative part also introduces the names and parameters of other nested subprograms, packages, task units, protected units, and generic units to be used in the program unit.
  3. The sequence of statements describes a sequence of actions that are to be performed. The statements are executed in succession (unless a transfer of control causes execution to continue from another place).
  4. An assignment statement changes the value of a variable. A procedure call invokes execution of a procedure after associating any actual parameters provided at the call with the corresponding formal parameters.
  5. Case statements and if statements allow the selection of an enclosed sequence of statements based on the value of an expression or on the value of a condition.
  6. The loop statement provides the basic iterative mechanism in the language. A loop statement specifies that a sequence of statements is to be executed repeatedly as directed by an iteration scheme, or until an exit statement is encountered.
  7. A block statement comprises a sequence of statements preceded by the declaration of local entities used by the statements.
  8. Certain statements are associated with concurrent execution. A delay statement delays the execution of a task for a specified duration or until a specified time. An entry call statement is written as a procedure call statement; it requests an operation on a task or on a protected object, blocking the caller until the operation can be performed. A called task may accept an entry call by executing a corresponding accept statement, which specifies the actions then to be performed as part of the rendezvous with the calling task. An entry call on a protected object is processed when the corresponding entry barrier evaluates to true, whereupon the body of the entry is executed. The requeue statement permits the provision of a service as a number of related activities with preference control. One form of the select statement allows a selective wait for one of several alternative rendezvous. Other forms of the select statement allow conditional or timed entry calls and the asynchronous transfer of control in response to some triggering event.
  9. Execution of a program unit may encounter error situations in which normal program execution cannot continue. For example, an arithmetic computation may exceed the maximum allowed value of a number, or an attempt may be made to access an array component by using an incorrect index value. To deal with such error situations, the statements of a program unit can be textually followed by exception handlers that specify the actions to be taken when the error situation arises. Exceptions can be raised explicitly by a raise statement.

Node:Data Types, Next:, Previous:Declarations and Statements, Up:Introduction

Data Types

  1. Every object in the language has a type, which characterizes a set of values and a set of applicable operations. The main classes of types are elementary types (comprising enumeration, numeric, and access types) and composite types (including array and record types).
  2. An enumeration type defines an ordered set of distinct enumeration literals, for example a list of states or an alphabet of characters. The enumeration types Boolean, Character, and Wide_Character are predefined.
  3. Numeric types provide a means of performing exact or approximate numerical computations. Exact computations use integer types, which denote sets of consecutive integers. Approximate computations use either fixed point types, with absolute bounds on the error, or floating point types, with relative bounds on the error. The numeric types Integer, Float, and Duration are predefined.
  4. Composite types allow definitions of structured objects with related components. The composite types in the language include arrays and records. An array is an object with indexed components of the same type. A record is an object with named components of possibly different types. Task and protected types are also forms of composite types. The array types String and Wide_String are predefined.
  5. Record, task, and protected types may have special components called discriminants which parameterize the type. Variant record structures that depend on the values of discriminants can be defined within a record type.
  6. Access types allow the construction of linked data structures. A value of an access type represents a reference to an object declared as aliased or to an object created by the evaluation of an allocator. Several variables of an access type may designate the same object, and components of one object may designate the same or other objects. Both the elements in such linked data structures and their relation to other elements can be altered during program execution. Access types also permit references to subprograms to be stored, passed as parameters, and ultimately dereferenced as part of an indirect call.
  7. Private types permit restricted views of a type. A private type can be defined in a package so that only the logically necessary properties are made visible to the users of the type. The full structural details that are externally irrelevant are then only available within the package and any child units.
  8. From any type a new type may be defined by derivation. A type, together with its derivatives (both direct and indirect) form a derivation class. Class-wide operations may be defined that accept as a parameter an operand of any type in a derivation class. For record and private types, the derivatives may be extensions of the parent type. Types that support these object-oriented capabilities of class-wide operations and type extension must be tagged, so that the specific type of an operand within a derivation class can be identified at run time. When an operation of a tagged type is applied to an operand whose specific type is not known until run time, implicit dispatching is performed based on the tag of the operand.
  9. The concept of a type is further refined by the concept of a subtype, whereby a user can constrain the set of allowed values of a type. Subtypes can be used to define subranges of scalar types, arrays with a limited set of index values, and records and private types with particular discriminant values.

Node:Other Facilities, Next:, Previous:Data Types, Up:Introduction

Other Facilities

  1. Representation clauses can be used to specify the mapping between types and features of an underlying machine. For example, the user can specify that objects of a given type must be represented with a given number of bits, or that the components of a record are to be represented using a given storage layout. Other features allow the controlled use of low level, nonportable, or implementation-dependent aspects, including the direct insertion of machine code.
  2. The predefined environment of the language provides for input-output and other capabilities (such as string manipulation and random number generation) by means of standard library packages. Input-output is supported for values of user-defined as well as of predefined types. Standard means of representing values in display form are also provided. Other standard library packages are defined in annexes of the standard to support systems with specialized requirements.
  3. Finally, the language provides a powerful means of parameterization of program units, called generic program units. The generic parameters can be types and subprograms (as well as objects and packages) and so allow general algorithms and data structures to be defined that are applicable to all types of a given class.

Node:Language Changes, Next:, Previous:Other Facilities, Up:Introduction

Language Changes

  1. This International Standard replaces the first edition of 1987. In this edition, the following major language changes have been incorporated:
    1. Support for standard 8-bit and 16-bit character sets. See 2, 3.5.2, 3.6.3, A.1, A.3, and A.4.
    2. Object-oriented programming with run-time polymorphism. See the discussions of classes, derived types, tagged types, record extensions, and private extensions in clauses 3.4, 3.9, and 7.3. See also the new forms of generic formal parameters that are allowed by "Formal Private and Derived Types", and "Formal Packages".
    3. Access types have been extended to allow an access value to designate a subprogram or an object declared by an object declaration (as opposed to just a heap-allocated object) (see 3.10).
    4. Efficient data-oriented synchronization is provided via protected types. See 9.
    5. The library units of a library may be organized into a hierarchy of parent and child units (see 10).
    6. Additional support has been added for interfacing to other languages. See B.
    7. The Specialized Needs Annexes have been added to provide specific support for certain application areas:
      1. Annex C, "Systems Programming"
      2. Annex D, "Real-Time Systems"
      3. Annex E, "Distributed Systems"
      4. Annex F, "Information Systems"
      5. Annex G, "Numerics"
      6. Annex H, "Safety and Security"

Node:Instructions for Comment Submission, Next:, Previous:Language Changes, Up:Introduction

Instructions for Comment Submission

  1. Informal comments on this International Standard may be sent via e-mail to ada-comment@sw-eng.falls-church.va.us. If appropriate, the Project Editor will initiate the defect correction procedure.
  2. Comments should use the following format: 
  3. !topic Title summarizing comment
!reference RM95-ss.ss(pp)
!from Author Name yy-mm-dd
!keywords keywords related to topic
!discussion

text of discussion
  4. where ss.ss is the section, clause or subclause number, pp is the paragraph number where applicable, and yy-mm-dd is the date the comment was sent. The date is optional, as is the !keywords line.
  5. Multiple comments per e-mail message are acceptable. Please use a descriptive "Subject" in your e-mail message.
  6. When correcting typographical errors or making minor wording suggestions, please put the correction directly as the topic of the comment; use square brackets [ ] to indicate text to be omitted and curly braces { } to indicate text to be added, and provide enough context to make the nature of the suggestion self-evident or put additional information in the body of the comment, for example: 
  7. !topic [c]{C}haracter
!topic it[']s meaning is not defined
  8. Formal requests for interpretations and for reporting defects in this International Standard may be made in accordance with the ISO/IEC JTC1 Directives and the ISO/IEC JTC1/SC22 policy for interpretations. National Bodies may submit a Defect Report to ISO/IEC JTC1/SC22 for resolution under the JTC1 procedures. A response will be provided and, if appropriate, a Technical Corrigendum will be issued in accordance with the procedures.

Node:Acknowledgements, Next:, Previous:Instructions for Comment Submission, Up:Introduction

Acknowledgements

  1. This International Standard was prepared by the Ada 9X Mapping/Revision Team based at Intermetrics, Inc., which has included: W. Carlson, Program Manager; T. Taft, Technical Director; J. Barnes (consultant); B. Brosgol (consultant); R. Duff (Oak Tree Software); M. Edwards; C. Garrity; R. Hilliard; O. Pazy (consultant); D. Rosenfeld; L. Shafer; W. White; M. Woodger.
  2. The following consultants to the Ada 9X Project contributed to the Specialized Needs Annexes: T. Baker (Real-Time/Systems Programming - SEI, FSU); K. Dritz (Numerics - Argonne National Laboratory); A. Gargaro (Distributed Systems - Computer Sciences); J. Goodenough (Real-Time/Systems Programming - SEI); J. McHugh (Secure Systems - consultant); B. Wichmann (Safety-Critical Systems - NPL: UK).
  3. This work was regularly reviewed by the Ada 9X Distinguished Reviewers and the members of the Ada 9X Rapporteur Group (XRG): E. Ploedereder, Chairman of DRs and XRG (University of Stuttgart: Germany); B. Bardin (Hughes); J. Barnes (consultant: UK); B. Brett (DEC); B. Brosgol (consultant); R. Brukardt (RR Software); N. Cohen (IBM); R. Dewar (NYU); G. Dismukes (TeleSoft); A. Evans (consultant); A. Gargaro (Computer Sciences); M. Gerhardt (ESL); J. Goodenough (SEI); S. Heilbrunner (University of Salzburg: Austria); P. Hilfinger (UC/Berkeley); B. Kaellberg (CelsiusTech: Sweden); M. Kamrad II (Unisys); J. van Katwijk (Delft University of Technology: The Netherlands); V. Kaufman (Russia); P. Kruchten (Rational); R. Landwehr (CCI: Germany); C. Lester (Portsmouth Polytechnic: UK); L. Mansson (TELIA Research: Sweden); S. Michell (Multiprocessor Toolsmiths: Canada); M. Mills (US Air Force); D. Pogge (US Navy); K. Power (Boeing); O. Roubine (Verdix: France); A. Strohmeier (Swiss Fed Inst of Technology: Switzerland); W. Taylor (consultant: UK); J. Tokar (Tartan); E. Vasilescu (Grumman); J. Vladik (Prospeks s.r.o.: Czech Republic); S. Van Vlierberghe (OFFIS: Belgium).
  4. Other valuable feedback influencing the revision process was provided by the Ada 9X Language Precision Team (Odyssey Research Associates), the Ada 9X User/Implementer Teams (AETECH, Tartan, TeleSoft), the Ada 9X Implementation Analysis Team (New York University) and the Ada community-at-large.
  5. Special thanks go to R. Mathis, Convenor of ISO/IEC JTC1/SC22 Working Group 9.
  6. The Ada 9X Project was sponsored by the Ada Joint Program Office. Christine M. Anderson at the Air Force Phillips Laboratory (Kirtland AFB, NM) was the project manager. Changes
  7. The International Standard is the same as this version of the Reference Manual, except:
    1. This list of Changes is not included in the International Standard.
    2. The "Acknowledgements" page is not included in the International Standard.
    3. The text in the running headers and footers on each page is slightly different in the International Standard.
    4. The title page(s) are different in the International Standard.
    5. This document is formatted for 8.5-by-11-inch paper, whereas the International Standard is formatted for A4 paper (210-by-297mm); thus, the page breaks are in different places.

Node:1, Next:, Previous:Acknowledgements, Up:Top

General

  1. Ada is a programming language designed to support the construction of long-lived, highly reliable software systems. The language includes facilities to define packages of related types, objects, and operations. The packages may be parameterized and the types may be extended to support the construction of libraries of reusable, adaptable software components. The operations may be implemented as subprograms using conventional sequential control structures, or as entries that include synchronization of concurrent threads of control as part of their invocation. The language treats modularity in the physical sense as well, with a facility to support separate compilation.
  2. The language includes a complete facility for the support of real-time, concurrent programming. Errors can be signaled as exceptions and handled explicitly. The language also covers systems programming; this requires precise control over the representation of data and access to system-dependent properties. Finally, a predefined environment of standard packages is provided, including facilities for, among others, input-output, string manipulation, numeric elementary functions, and random number generation.

Node:1.1, Next:, Previous:1, Up:1

Scope

  1. This International Standard specifies the form and meaning of programs written in Ada. Its purpose is to promote the portability of Ada programs to a variety of data processing systems.

Node:1.1.1, Next:, Previous:1.1, Up:1.1

Extent

  1. This International Standard specifies:
    1. The form of a program written in Ada;
    2. The effect of translating and executing such a program;
    3. The manner in which program units may be combined to form Ada programs;
    4. The language-defined library units that a conforming implementation is required to supply;
    5. The permissible variations within the standard, and the manner in which they are to be documented;
    6. Those violations of the standard that a conforming implementation is required to detect, and the effect of attempting to translate or execute a program containing such violations;
    7. Those violations of the standard that a conforming implementation is not required to detect.
  1. This International Standard does not specify:
    1. The means whereby a program written in Ada is transformed into object code executable by a processor;
    2. The means whereby translation or execution of programs is invoked and the executing units are controlled;
    3. The size or speed of the object code, or the relative execution speed of different language constructs;

      The form or contents of any listings produced by implementations; in particular, the form or contents of error or warning messages;

    4. The effect of unspecified execution.
    5. The size of a program or program unit that will exceed the capacity of a particular conforming implementation.

Node:1.1.2, Next:, Previous:1.1.1, Up:1.1

Structure

  1. This International Standard contains thirteen sections, fourteen annexes, and an index.
  2. The core of the Ada language consists of:
    1. Sections 1 through 13
    2. Annex A, "Predefined Language Environment"
    3. Annex B, "Interface to Other Languages"
    4. Annex J, "Obsolescent Features"
  1. The following Specialized Needs Annexes define features that are needed by certain application areas:
    1. Annex C, "Systems Programming"
    2. Annex D, "Real-Time Systems"
    3. Annex E, "Distributed Systems"
    4. Annex F, "Information Systems"
    5. Annex G, "Numerics"
    6. Annex H, "Safety and Security"
  1. The core language and the Specialized Needs Annexes are normative, except that the material in each of the items listed below is informative:
    1. Text under a NOTES or Examples heading.
    2. Each clause or subclause whose title starts with the word "Example" or "Examples".
  1. All implementations shall conform to the core language. In addition, an implementation may conform separately to one or more Specialized Needs Annexes.
  2. The following Annexes are informative:
    1. Annex K, "Language-Defined Attributes"
    2. Annex L, "Language-Defined Pragmas"
    3. Annex M, "Implementation-Defined Characteristics"
    4. Annex N, "Glossary"
    5. Annex P, "Syntax Summary"
  1. Each section is divided into clauses and subclauses that have a common structure. Each section, clause, and subclause first introduces its subject. After the introductory text, text is labeled with the following headings:

    Syntax
  2. Syntax rules (indented).

    Name Resolution Rules
  3. Compile-time rules that are used in name resolution, including overload resolution.

    Legality Rules
  4. Rules that are enforced at compile time. A construct is legal if it obeys all of the Legality Rules.

    Static Semantics
  5. A definition of the compile-time effect of each construct.

    Post-Compilation Rules
  6. Rules that are enforced before running a partition. A partition is legal if its compilation units are legal and it obeys all of the Post-Compilation Rules.

    Dynamic Semantics
  7. A definition of the run-time effect of each construct.

    Bounded (Run-Time) Errors
  8. Situations that result in bounded (run-time) errors, see 1.1.5.

    Erroneous Execution
  9. Situations that result in erroneous execution, see 1.1.5.

    Implementation Requirements
  10. Additional requirements for conforming implementations.

    Documentation Requirements
  11. Documentation requirements for conforming implementations.

    Metrics
  12. Metrics that are specified for the time/space properties of the execution of certain language constructs.

    Implementation Permissions
  13. Additional permissions given to the implementer.

    Implementation Advice
  14. Optional advice given to the implementer. The word "should" is used to indicate that the advice is a recommendation, not a requirement. It is implementation defined whether or not a given recommendation is obeyed.

    NOTES

  15. (1) Notes emphasize consequences of the rules described in the (sub)clause or elsewhere. This material is informative.

    Examples
  16. Examples illustrate the possible forms of the constructs described. This material is informative.

Node:1.1.3, Next:, Previous:1.1.2, Up:1.1

Conformity of an Implementation with the Standard


Implementation Requirements
  1. A conforming implementation shall:
    1. Translate and correctly execute legal programs written in Ada, provided that they are not so large as to exceed the capacity of the implementation;
    2. Identify all programs or program units that are so large as to exceed the capacity of the implementation (or raise an appropriate exception at run time);
    3. Identify all programs or program units that contain errors whose detection is required by this International Standard;
    4. Supply all language-defined library units required by this International Standard;
    5. Contain no variations except those explicitly permitted by this International Standard, or those that are impossible or impractical to avoid given the implementation's execution environment;
    6. Specify all such variations in the manner prescribed by this International Standard.
  1. The external effect of the execution of an Ada program is defined in terms of its interactions with its external environment. The following are defined as external interactions:
    1. Any interaction with an external file, see A.7,
    2. The execution of certain code_statements, see 13.8, which code_statements cause external interactions is implementation defined.
    3. Any call on an imported subprogram, see B, including any parameters passed to it;
    4. Any result returned or exception propagated from a main subprogram (see 10.2) or an exported subprogram, see B, to an external caller;
    5. Any read or update of an atomic or volatile object, see C.6,
    6. The values of imported and exported objects, see B, at the time of any other interaction with the external environment.
  1. A conforming implementation of this International Standard shall produce for the execution of a given Ada program a set of interactions with the external environment whose order and timing are consistent with the definitions and requirements of this International Standard for the semantics of the given program.
  2. An implementation that conforms to this Standard shall support each capability required by the core language as specified. In addition, an implementation that conforms to this Standard may conform to one or more Specialized Needs Annexes (or to none). Conformance to a Specialized Needs Annex means that each capability required by the Annex is provided as specified.
  3. An implementation conforming to this International Standard may provide additional attributes, library units, and pragmas. However, it shall not provide any attribute, library unit, or pragma having the same name as an attribute, library unit, or pragma (respectively) specified in a Specialized Needs Annex unless the provided construct is either as specified in the Specialized Needs Annex or is more limited in capability than that required by the Annex. A program that attempts to use an unsupported capability of an Annex shall either be identified by the implementation before run time or shall raise an exception at run time.

    Documentation Requirements
  4. Certain aspects of the semantics are defined to be either implementation defined or unspecified. In such cases, the set of possible effects is specified, and the implementation may choose any effect in the set. Implementations shall document their behavior in implementation-defined situations, but documentation is not required for unspecified situations. The implementation-defined characteristics are summarized in Annex M.
  5. The implementation may choose to document implementation-defined behavior either by documenting what happens in general, or by providing some mechanism for the user to determine what happens in a particular case.

    Implementation Advice
  6. If an implementation detects the use of an unsupported Specialized Needs Annex feature at run time, it should raise Program_Error if feasible.
  7. If an implementation wishes to provide implementation-defined extensions to the functionality of a language-defined library unit, it should normally do so by adding children to the library unit.

    NOTES

  8. (2) The above requirements imply that an implementation conforming to this Standard may support some of the capabilities required by a Specialized Needs Annex without supporting all required capabilities.

Node:1.1.4, Next:, Previous:1.1.3, Up:1.1

Method of Description and Syntax Notation

  1. The form of an Ada program is described by means of a context-free syntax together with context-dependent requirements expressed by narrative rules.
  2. The meaning of Ada programs is described by means of narrative rules defining both the effects of each construct and the composition rules for constructs.
  3. The context-free syntax of the language is described using a simple variant of Backus-Naur Form. In particular:
    1. Lower case words in a sans-serif font, some containing embedded underlines, are used to denote syntactic categories, for example: 
    2. case_statement
    3. Boldface words are used to denote reserved words, for example: 
    4. array
    5. Square brackets enclose optional items. Thus the two following rules are equivalent. 
    6. return_statement ::= return [expression];
return_statement ::= return; | return expression;
    7. Curly brackets enclose a repeated item. The item may appear zero or more times; the repetitions occur from left to right as with an equivalent left-recursive rule. Thus the two following rules are equivalent. 
    8. term ::= factor {multiplying_operator factor}
term ::= factor | term multiplying_operator factor
    9. A vertical line separates alternative items unless it occurs immediately after an opening curly bracket, in which case it stands for itself: 
    10. constraint ::= scalar_constraint | composite_constraint
discrete_choice_list ::= discrete_choice {| discrete_choice}
    11. If the name of any syntactic category starts with an italicized part, it is equivalent to the category name without the italicized part. The italicized part is intended to convey some semantic information. For example subtype_name and task_name are both equivalent to name alone.
  1. A syntactic category is a nonterminal in the grammar defined in BNF under "Syntax." Names of syntactic categories are set in a different font, like_this.
  2. A construct is a piece of text (explicit or implicit) that is an instance of a syntactic category defined under "Syntax."
  3. A constituent of a construct is the construct itself, or any construct appearing within it.
  4. Whenever the run-time semantics defines certain actions to happen in an arbitrary order, this means that the implementation shall arrange for these actions to occur in a way that is equivalent to some sequential order, following the rules that result from that sequential order. When evaluations are defined to happen in an arbitrary order, with conversion of the results to some subtypes, or with some run-time checks, the evaluations, conversions, and checks may be arbitrarily interspersed, so long as each expression is evaluated before converting or checking its value. Note that the effect of a program can depend on the order chosen by the implementation. This can happen, for example, if two actual parameters of a given call have side effects.

    NOTES

  5. (3) The syntax rules describing structured constructs are presented in a form that corresponds to the recommended paragraphing. For example, an if_statement is defined as: 
  6. if_statement ::=
   if condition then
      sequence_of_statements
   {elsif condition then
      sequence_of_statements}
   [else
      sequence_of_statements]
   end if;
  7. (4) The line breaks and indentation in the syntax rules indicate the recommended line breaks and indentation in the corresponding constructs. The preferred places for other line breaks are after semicolons.

Node:1.1.5, Next:, Previous:1.1.4, Up:1.1

Classification of Errors


Implementation Requirements
  1. The language definition classifies errors into several different categories:
    1. Errors that are required to be detected prior to run time by every Ada implementation;
      1. These errors correspond to any violation of a rule given in this International Standard, other than those listed below. In particular, violation of any rule that uses the terms shall, allowed, permitted, legal, or illegal belongs to this category. Any program that contains such an error is not a legal Ada program; on the other hand, the fact that a program is legal does not mean, per se, that the program is free from other forms of error.
      2. The rules are further classified as either compile time rules, or post compilation rules, depending on whether a violation has to be detected at the time a compilation unit is submitted to the compiler, or may be postponed until the time a compilation unit is incorporated into a partition of a program.
    1. Errors that are required to be detected at run time by the execution of an Ada program;
      1. The corresponding error situations are associated with the names of the predefined exceptions. Every Ada compiler is required to generate code that raises the corresponding exception if such an error situation arises during program execution. If such an error situation is certain to arise in every execution of a construct, then an implementation is allowed (although not required) to report this fact at compilation time.
    1. Bounded errors;
      1. The language rules define certain kinds of errors that need not be detected either prior to or during run time, but if not detected, the range of possible effects shall be bounded. The errors of this category are called bounded errors. The possible effects of a given bounded error are specified for each such error, but in any case one possible effect of a bounded error is the raising of the exception Program_Error.
    1. Erroneous execution.
      1. In addition to bounded errors, the language rules define certain kinds of errors as leading to erroneous execution. Like bounded errors, the implementation need not detect such errors either prior to or during run time. Unlike bounded errors, there is no language-specified bound on the possible effect of erroneous execution; the effect is in general not predictable.

Implementation Permissions
  1. An implementation may provide nonstandard modes of operation. Typically these modes would be selected by a pragma or by a command line switch when the compiler is invoked. When operating in a nonstandard mode, the implementation may reject compilation_units that do not conform to additional requirements associated with the mode, such as an excessive number of warnings or violation of coding style guidelines. Similarly, in a nonstandard mode, the implementation may apply special optimizations or alternative algorithms that are only meaningful for programs that satisfy certain criteria specified by the implementation. In any case, an implementation shall support a standard mode that conforms to the requirements of this International Standard; in particular, in the standard mode, all legal compilation_units shall be accepted.

    Implementation Advice
  2. If an implementation detects a bounded error or erroneous execution, it should raise Program_Error.

Node:1.2, Next:, Previous:1.1.5, Up:1

Normative References

  1. The following standards contain provisions which, through reference in this text, constitute provisions of this International Standard. At the time of publication, the editions indicated were valid. All standards are subject to revision, and parties to agreements based on this International Standard are encouraged to investigate the possibility of applying the most recent editions of the standards indicated below. Members of IEC and ISO maintain registers of currently valid International Standards.
  2. ISO/IEC 646:1991, Information technology - ISO 7-bit coded character set for information interchange.
  3. ISO/IEC 1539:1991, Information technology - Programming languages - FORTRAN.
  4. ISO 1989:1985, Programming languages - COBOL.
  5. ISO/IEC 6429:1992, Information technology - Control functions for coded graphic character sets.
  6. ISO/IEC 8859-1:1987, Information processing - 8-bit single-byte coded character sets - Part 1: Latin alphabet No. 1.
  7. ISO/IEC 9899:1990, Programming languages - C.
  8. ISO/IEC 10646-1:1993, Information technology - Universal Multiple-Octet Coded Character Set (UCS) - Part 1: Architecture and Basic Multilingual Plane.

Node:1.3, Next:, Previous:1.2, Up:1

Definitions

  1. Terms are defined throughout this International Standard, indicated by italic type. Terms explicitly defined in this International Standard are not to be presumed to refer implicitly to similar terms defined elsewhere. Terms not defined in this International Standard are to be interpreted according to the Webster's Third New International Dictionary of the English Language. Informal descriptions of some terms are also given in Annex N, "Glossary".

Node:2, Next:, Previous:1.3, Up:Top

Lexical Elements

  1. The text of a program consists of the texts of one or more compilations. The text of a compilation is a sequence of lexical elements, each composed of characters; the rules of composition are given in this section. Pragmas, which provide certain information for the compiler, are also described in this section.

Node:2.1, Next:, Previous:2, Up:2

Character Set

  1. The only characters allowed outside of comments are the graphic_characters and format_effectors.

    Syntax
  2. character ::=
     graphic_character
   | format_effector
   | other_control_function

  3. graphic_character ::=
     identifier_letter
   | digit
   | space_character
   | special_character

    Static Semantics
  4. The character repertoire for the text of an Ada program consists of the collection of characters called the Basic Multilingual Plane (BMP) of the ISO 10646 Universal Multiple-Octet Coded Character Set, plus a set of format_ effectors and, in comments only, a set of other_control_functions; the coded representation for these characters is implementation defined (it need not be a representation defined within ISO-10646-1).
  5. The description of the language definition in this International Standard uses the graphic symbols defined for Row 00: Basic Latin and Row 00: Latin-1 Supplement of the ISO 10646 BMP; these correspond to the graphic symbols of ISO 8859-1 (Latin-1); no graphic symbols are used in this International Standard for characters outside of Row 00 of the BMP. The actual set of graphic symbols used by an implementation for the visual representation of the text of an Ada program is not specified.
  6. The categories of characters are defined as follows:
  7. identifier_letter 
    upper_case_identifier_letter | lower_case_identifier_letter
  8. upper_case_identifier_letter 
    Any character of Row 00 of ISO 10646 BMP whose name begins ``Latin
Capital Letter''.
  9. lower_case_identifier_letter 
    Any character of Row 00 of ISO 10646 BMP whose name begins
``Latin Small Letter''.
  10. digit 
    One of the characters 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9.
  11. space_character 
    The character of ISO 10646 BMP named ``Space''.
  12. special_character 
    Any character of the ISO 10646 BMP that is not reserved for a
control function, and is not the space_character, an
identifier_letter, or a digit.
  13. format_effector 
    The control functions of ISO 6429 called character tabulation
(HT), line tabulation (VT), carriage return (CR), line feed (LF),
and form feed (FF).
  14. other_control_function 
    Any control function, other than a format_effector, that is
allowed in a comment; the set of other_control_functions allowed
in comments is implementation defined.
  15. The following names are used when referring to certain special_characters: 
    symbol   name                   symbol   name

  "      quotation mark           :      colon
  #      number sign              ;      semicolon
  &      ampersand                <      less-than sign
  '      apostrophe, tick         =      equals sign
  (      left parenthesis         >      greater-than sign
  )      right parenthesis        _      low line, underline
  *      asterisk, multiply       |      vertical line
  +      plus sign                [      left square bracket
  ,      comma                    ]      right square bracket
  -      hyphen-minus, minus      {      left curly bracket
  .      full stop, dot, point    }      right curly bracket
  /      solidus, divide

    Implementation Permissions
  16. In a nonstandard mode, the implementation may support a different character repertoire; in particular, the set of characters that are considered identifier_letters can be extended or changed to conform to local conventions.

    NOTES

  17. (1) Every code position of ISO 10646 BMP that is not reserved for a control function is defined to be a graphic_character by this International Standard. This includes all code positions other than 0000 - 001F, 007F - 009F, and FFFE - FFFF.
  18. (2) The language does not specify the source representation of programs.

Node:2.2, Next:, Previous:2.1, Up:2

Lexical Elements, Separators, and Delimiters


Static Semantics
  1. The text of a program consists of the texts of one or more compilations. The text of each compilation is a sequence of separate lexical elements. Each lexical element is formed from a sequence of characters, and is either a delimiter, an identifier, a reserved word, a numeric_literal, a character_ literal, a string_literal, or a comment. The meaning of a program depends only on the particular sequences of lexical elements that form its compilations, excluding comments.
  2. The text of a compilation is divided into lines. In general, the representation for an end of line is implementation defined. However, a sequence of one or more format_effectors other than character tabulation (HT) signifies at least one end of line.
  3. In some cases an explicit separator is required to separate adjacent lexical elements. A separator is any of a space character, a format effector, or the end of a line, as follows:
    1. A space character is a separator except within a comment, a string_literal, or a character_literal.
    2. Character tabulation (HT) is a separator except within a comment.
    3. The end of a line is always a separator.
  1. One or more separators are allowed between any two adjacent lexical elements, before the first of each compilation, or after the last. At least one separator is required between an identifier, a reserved word, or a numeric_literal and an adjacent identifier, reserved word, or numeric_literal.
  2. A delimiter is either one of the following special characters 
  3. &    '    (    )    *    +    ,    -
.    /    :    ;    <    =    >    |
  4. or one of the following compound delimiters each composed of two adjacent special characters 
  5. =>    ..    **    :=    /=    >=    <=    <<    >>    <>
  6. Each of the special characters listed for single character delimiters is a single delimiter except if this character is used as a character of a compound delimiter, or as a character of a comment, string_literal, character_literal, or numeric_literal.
  7. The following names are used when referring to compound delimiters: 
  8. delimiter     name

   =>                       arrow
   ..                       double dot
   **                       double star, exponentiate
   :=                       assignment (pronounced: ``becomes'')
   /=                       inequality (pronounced: ``not equal'')
   >=                       greater than or equal
   <=                       less than or equal
   <<                       left label bracket
   >>                       right label bracket
   <>                       box

    Implementation Requirements
  9. An implementation shall support lines of at least 200 characters in length, not counting any characters used to signify the end of a line. An implementation shall support lexical elements of at least 200 characters in length. The maximum supported line length and lexical element length are implementation defined.

Node:2.3, Next:, Previous:2.2, Up:2

Identifiers

  1. Identifiers are used as names.

    Syntax
  2. identifier ::= identifier_letter {[underline] letter_or_digit}

  3. letter_or_digit ::= identifier_letter | digit
    1. An identifier shall not be a reserved word.

Static Semantics
  1. All characters of an identifier are significant, including any underline character. Identifiers differing only in the use of corresponding upper and lower case letters are considered the same.

    Implementation Permissions
  2. In a nonstandard mode, an implementation may support other upper/lower case equivalence rules for identifiers, to accommodate local conventions.

    Examples
  3. Examples of identifiers: 
  4. Count      X    Get_Symbol   Ethelyn   Marion

Snobol_4   X1   Page_Count    Store_Next_Item

Node:2.4, Next:, Previous:2.3, Up:2

Numeric Literals

  1. There are two kinds of numeric_literals, real literals and integer literals. A real literal is a numeric_literal that includes a point; an integer literal is a numeric_literal without a point.

    Syntax
  2. numeric_literal ::= decimal_literal | based_literal

    NOTES

  3. (3) The type of an integer literal is universal_integer. The type of a real literal is universal_real.

Node:2.4.1, Next:, Previous:2.4, Up:2.4

Decimal Literals

  1. A decimal_literal is a numeric_literal in the conventional decimal notation (that is, the base is ten).

    Syntax
  2. decimal_literal ::= numeral [.numeral] [exponent]

  3. numeral ::= digit {[underline] digit}

  4. exponent ::= E [+] numeral | E - numeral
    1. An exponent for an integer literal shall not have a minus sign.

Static Semantics
  1. An underline character in a numeric_literal does not affect its meaning. The letter E of an exponent can be written either in lower case or in upper case, with the same meaning.
  2. An exponent indicates the power of ten by which the value of the decimal_literal without the exponent is to be multiplied to obtain the value of the decimal_literal with the exponent.

    Examples
  3. Examples of decimal literals: 
  4. 12        0      1E6    123_456           --  integer literals

12.0      0.0    0.456  3.14159_26        --  real literals

Node:2.4.2, Next:, Previous:2.4.1, Up:2.4

Based Literals

  1. A based_literal is a numeric_literal expressed in a form that specifies the base explicitly.

    Syntax
  2. based_literal ::= base # based_numeral [.based_numeral] # [exponent]

  3. base ::= numeral

  4. based_numeral ::=
   extended_digit {[underline] extended_digit}

  5. extended_digit ::= digit | A | B | C | D | E | F

    Legality Rules
  6. The base (the numeric value of the decimal numeral preceding the first #) shall be at least two and at most sixteen. The extended_digits A through F represent the digits ten through fifteen, respectively. The value of each extended_digit of a based_literal shall be less than the base.

    Static Semantics
  7. The conventional meaning of based notation is assumed. An exponent indicates the power of the base by which the value of the based_literal without the exponent is to be multiplied to obtain the value of the based_literal with the exponent. The base and the exponent, if any, are in decimal notation.
  8. The extended_digits A through F can be written either in lower case or in upper case, with the same meaning.

    Examples
  9. Examples of based literals: 
  10. 2#1111_1111#   16#FF#       016#0ff#
--  integer literals of value 255

16#E#E1        2#1110_0000#
--  integer literals of value 224

16#F.FF#E+2    2#1.1111_1111_1110#E11
--  real literals of value 4095.0

Node:2.5, Next:, Previous:2.4.2, Up:2

Character Literals

  1. A character_literal is formed by enclosing a graphic character between two apostrophe characters.

    Syntax
  2. character_literal ::= 'graphic_character'

    NOTES

  3. (4) A character_literal is an enumeration literal of a character type. (see 3.5.2).

    Examples
  4. Examples of character literals: 
  5. 'A'     '*'     '''     ' '

Node:2.6, Next:, Previous:2.5, Up:2

String Literals

  1. A string_literal is formed by a sequence of graphic characters (possibly none) enclosed between two quotation marks used as string brackets. They are used to represent operator_symbols (see 6.1) values of a string type (see 4.2) and array subaggregates (see 4.3.3).

    Syntax
  2. string_literal ::= "{string_element}"

  3. string_element ::= "" | non_quotation_mark_graphic_character
    1. A string_element is either a pair of quotation marks (""), or a single graphic_character other than a quotation mark.

Static Semantics
  1. The sequence of characters of a string_literal is formed from the sequence of string_elements between the bracketing quotation marks, in the given order, with a string_element that is "" becoming a single quotation mark in the sequence of characters, and any other string_element being reproduced in the sequence.
  2. A null string literal is a string_literal with no string_elements between the quotation marks.

    NOTES

  3. (5) An end of line cannot appear in a string_literal.

    Examples
  4. Examples of string literals: 
  5. "Message of the day:"

""                           --  a null string literal
" "   "A"   """"             --  three string literals of length 1

"Characters such as $, %, and } are allowed in string literals"

Node:2.7, Next:, Previous:2.6, Up:2

Comments

  1. A comment starts with two adjacent hyphens and extends up to the end of the line.

    Syntax
  2. comment ::= --{non_end_of_line_character}
    1. A comment may appear on any line of a program.

Static Semantics
  1. The presence or absence of comments has no influence on whether a program is legal or illegal. Furthermore, comments do not influence the meaning of a program; their sole purpose is the enlightenment of the human reader.

    Examples
  2. Examples of comments: 
  3. --  the last sentence above echoes the Algol 68 report

end;  --  processing of Line is complete

--  a long comment may be split onto
--  two or more consecutive lines

----------------  the first two hyphens start the comment

Node:2.8, Next:, Previous:2.7, Up:2

Pragmas

  1. A pragma is a compiler directive. There are language-defined pragmas that give instructions for optimization, listing control, etc. An implementation may support additional (implementation-defined) pragmas.

    Syntax
  2. pragma ::=
   pragma identifier [(pragma_argument_association
      {, pragma_argument_association})];

  3. pragma_argument_association ::=
     [pragma_argument_identifier =>] name
   | [pragma_argument_identifier =>] expression
    1. In a pragma, any pragma_argument_associations without a pragma_argument_identifier shall precede any associations with a pragma_argument_identifier.
    2. Pragmas are only allowed at the following places in a program:
      1. After a semicolon delimiter, but not within a formal_part or discriminant_part.
      2. At any place where the syntax rules allow a construct defined by a syntactic category whose name ends with "declaration", "statement", "clause", or "alternative", or one of the syntactic categories variant or exception_handler; but not in place of such a construct. Also at any place where a compilation_unit would be allowed.
    1. Additional syntax rules and placement restrictions exist for specific pragmas.
  1. The name of a pragma is the identifier following the reserved word pragma. The name or expression of a pragma_argument_association is a pragma argument.
  2. An identifier specific to a pragma is an identifier that is used in a pragma argument with special meaning for that pragma.

    Static Semantics
  3. If an implementation does not recognize the name of a pragma, then it has no effect on the semantics of the program. Inside such a pragma, the only rules that apply are the Syntax Rules.

    Dynamic Semantics
  4. Any pragma that appears at the place of an executable construct is executed. Unless otherwise specified for a particular pragma, this execution consists of the evaluation of each evaluable pragma argument in an arbitrary order.

    Implementation Requirements
  5. The implementation shall give a warning message for an unrecognized pragma name.

    Implementation Permissions
  6. An implementation may provide implementation-defined pragmas; the name of an implementation-defined pragma shall differ from those of the language-defined pragmas.
  7. An implementation may ignore an unrecognized pragma even if it violates some of the Syntax Rules, if detecting the syntax error is too complex.

    Implementation Advice
  8. Normally, implementation-defined pragmas should have no semantic effect for error-free programs; that is, if the implementation-defined pragmas are removed from a working program, the program should still be legal, and should still have the same semantics.
  9. Normally, an implementation should not define pragmas that can make an illegal program legal, except as follows:
    1. A pragma used to complete a declaration, such as a pragma Import;
    2. A pragma used to configure the environment by adding, removing, or replacing library_items.

Syntax
  1. The forms of List, Page, and Optimize pragmas are as follows:
  2. pragma List(identifier);
  3. pragma Page;
  4. pragma Optimize(identifier);
    1. Other pragmas are defined throughout this International Standard, and are summarized in Annex L.

Static Semantics
  1. A pragma List takes one of the identifiers On or Off as the single argument. This pragma is allowed anywhere a pragma is allowed. It specifies that listing of the compilation is to be continued or suspended until a List pragma with the opposite argument is given within the same compilation. The pragma itself is always listed if the compiler is producing a listing.
  2. A pragma Page is allowed anywhere a pragma is allowed. It specifies that the program text which follows the pragma should start on a new page (if the compiler is currently producing a listing).
  3. A pragma Optimize takes one of the identifiers Time, Space, or Off as the single argument. This pragma is allowed anywhere a pragma is allowed, and it applies until the end of the immediately enclosing declarative region, or for a pragma at the place of a compilation_unit, to the end of the compilation. It gives advice to the implementation as to whether time or space is the primary optimization criterion, or that optional optimizations should be turned off. It is implementation defined how this advice is followed.

    Examples
  4. Examples of pragmas: 
  5. pragma List(Off);         -- turn off listing generation
pragma Optimize(Off);     -- turn off optional optimizations
pragma Inline(Set_Mask);  -- generate code for Set_Mask inline

pragma Suppress(Range_Check, On => Index);
-- turn off range checking on Index

Node:2.9, Next:, Previous:2.8, Up:2

Reserved Words


Syntax
    1. The following are the reserved words (ignoring upper/lower case distinctions): 
      abort          else           new            return
abs            elsif          not            reverse
abstract       end            null
accept         entry                         select
access         exception                     separate
aliased        exit           of             subtype
all                           or
and            for            others         tagged
array          function       out            task
at                                           terminate
               generic        package        then
begin          goto           pragma         type
body                          private
               if             procedure
case           in             protected      until
constant       is                            use
                              raise
declare                       range          when
delay          limited        record         while
delta          loop           rem            with
digits                        renames
do             mod            requeue        xor

    NOTES

  1. (6) The reserved words appear in lower case boldface in this International Standard, except when used in the designator of an attribute (see 4.1.4). Lower case boldface is also used for a reserved word in a string_literal used as an operator_symbol. This is merely a convention - programs may be written in whatever typeface is desired and available.

Node:3, Next:, Previous:2.9, Up:Top

Declarations and Types

  1. This section describes the types in the language and the rules for declaring constants, variables, and named numbers.

Node:3.1, Next:, Previous:3, Up:3

Declarations

  1. The language defines several kinds of named entities that are declared by declarations. The entity's name is defined by the declaration, usually by a defining_identifier, but sometimes by a defining_character_literal or defining_operator_symbol.
  2. There are several forms of declaration. A basic_declaration is a form of declaration defined as follows.

    Syntax
  3. basic_declaration ::=
     type_declaration         | subtype_declaration
   | object_declaration       | number_declaration
   | subprogram_declaration   | abstract_subprogram_declaration
   | package_declaration      | renaming_declaration
   | exception_declaration    | generic_declaration
   | generic_instantiation

  4. defining_identifier ::= identifier

    Static Semantics
  5. A declaration is a language construct that associates a name with (a view of) an entity. A declaration may appear explicitly in the program text (an explicit declaration), or may be supposed to occur at a given place in the text as a consequence of the semantics of another construct (an implicit declaration).
  6. Each of the following is defined to be a declaration: any basic_declaration; an enumeration_literal_specification; a discriminant_specification; a component_declaration; a loop_parameter_specification; a parameter_specification; a subprogram_body; an entry_declaration; an entry_index_specification; a choice_parameter_specification; a generic_formal_parameter_declaration.
  7. All declarations contain a definition for a view of an entity. A view consists of an identification of the entity (the entity of the view), plus view-specific characteristics that affect the use of the entity through that view (such as mode of access to an object, formal parameter names and defaults for a subprogram, or visibility to components of a type). In most cases, a declaration also contains the definition for the entity itself (a renaming_declaration is an example of a declaration that does not define a new entity, but instead defines a view of an existing entity, see 8.5.)
  8. For each declaration, the language rules define a certain region of text called the scope of the declaration (see 8.2). Most declarations associate an identifier with a declared entity. Within its scope, and only there, there are places where it is possible to use the identifier to refer to the declaration, the view it defines, and the associated entity; these places are defined by the visibility rules (see 8.3). At such places the identifier is said to be a name of the entity (the direct_name or selector_name); the name is said to denote the declaration, the view, and the associated entity (see 8.6). The declaration is said to declare the name, the view, and in most cases, the entity itself.
  9. As an alternative to an identifier, an enumeration literal can be declared with a character_literal as its name (see 3.5.1) and a function can be declared with an operator_symbol as its name (see 6.1).
  10. The syntax rules use the terms defining_identifier, defining_character_literal, and defining_operator_symbol for the defining occurrence of a name; these are collectively called defining names. The terms direct_name and selector_name are used for usage occurrences of identifiers, character_literals, and operator_symbols. These are collectively called usage names.

    Dynamic Semantics
  11. The process by which a construct achieves its run-time effect is called execution. This process is also called elaboration for declarations and evaluation for expressions. One of the terms execution, elaboration, or evaluation is defined by this International Standard for each construct that has a run-time effect.

    NOTES

  12. (1) At compile time, the declaration of an entity declares the entity. At run time, the elaboration of the declaration creates the entity.

Node:3.2, Next:, Previous:3.1, Up:3

Types and Subtypes


Static Semantics
  1. A type is characterized by a set of values, and a set of primitive operations which implement the fundamental aspects of its semantics. An object of a given type is a run-time entity that contains (has) a value of the type.
  2. Types are grouped into classes of types, reflecting the similarity of their values and primitive operations. There exist several language-defined classes of types (see NOTES below). Elementary types are those whose values are logically indivisible; composite types are those whose values are composed of component values.
  3. The elementary types are the scalar types (discrete and real) and the access types (whose values provide access to objects or subprograms). Discrete types are either integer types or are defined by enumeration of their values (enumeration types). Real types are either floating point types or fixed point types.
  4. The composite types are the record types, record extensions, array types, task types, and protected types. A private type or private extension represents a partial view, see 7.3, of a type, providing support for data abstraction. A partial view is a composite type.
  5. Certain composite types (and partial views thereof) have special components called discriminants whose values affect the presence, constraints, or initialization of other components. Discriminants can be thought of as parameters of the type.
  6. The term subcomponent is used in this International Standard in place of the term component to indicate either a component, or a component of another subcomponent. Where other subcomponents are excluded, the term component is used instead. Similarly, a part of an object or value is used to mean the whole object or value, or any set of its subcomponents.
  7. The set of possible values for an object of a given type can be subjected to a condition that is called a constraint (the case of a null constraint that specifies no restriction is also included); the rules for which values satisfy a given kind of constraint are given in 3.5 for range_constraints, 3.6.1, for index_constraints, and 3.7.1, for discriminant_constraints.
  8. A subtype of a given type is a combination of the type, a constraint on values of the type, and certain attributes specific to the subtype. The given type is called the type of the subtype. Similarly, the associated constraint is called the constraint of the subtype. The set of values of a subtype consists of the values of its type that satisfy its constraint. Such values belong to the subtype.
  9. A subtype is called an unconstrained subtype if its type has unknown discriminants, or if its type allows range, index, or discriminant constraints, but the subtype does not impose such a constraint; otherwise, the subtype is called a constrained subtype (since it has no unconstrained characteristics).

    NOTES

  10. (2) Any set of types that is closed under derivation (see 3.4) can be called a "class" of types. However, only certain classes are used in the description of the rules of the language - generally those that have their own particular set of primitive operations (see 3.2.3) or that correspond to a set of types that are matched by a given kind of generic formal type (see 12.5). The following are examples of "interesting" language-defined classes: elementary, scalar, discrete, enumeration, character, boolean, integer, signed integer, modular, real, floating point, fixed point, ordinary fixed point, decimal fixed point, numeric, access, access-to-object, access-to-subprogram, composite, array, string, (untagged) record, tagged, task, protected, nonlimited. Special syntax is provided to define types in each of these classes.
    1. These language-defined classes are organized like this: 
    2. all types
   elementary
      scalar
         discrete
            enumeration
               character
               boolean
               other enumeration
            integer
               signed integer
               modular integer
         real
            floating point
            fixed point
               ordinary fixed point
               decimal fixed point
      access
         access-to-object
         access-to-subprogram
   composite
      array
         string
         other array
      untagged record
      tagged
      task
      protected
    3. The classes "numeric" and "nonlimited" represent other classification dimensions and do not fit into the above strictly hierarchical picture.

Node:3.2.1, Next:, Previous:3.2, Up:3.2

Type Declarations

  1. A type_declaration declares a type and its first subtype.

    Syntax
  2. type_declaration ::=
     full_type_declaration
   | incomplete_type_declaration
   | private_type_declaration
   | private_extension_declaration

  3. full_type_declaration ::=
     type defining_identifier [known_discriminant_part]
       is type_definition;
   | task_type_declaration
   | protected_type_declaration

  4. type_definition ::=
     enumeration_type_definition | integer_type_definition
   | real_type_definition        | array_type_definition
   | record_type_definition      | access_type_definition
   | derived_type_definition

    Legality Rules
  5. A given type shall not have a subcomponent whose type is the given type itself.

    Static Semantics
  6. The defining_identifier of a type_declaration denotes the first subtype of the type. The known_discriminant_part, if any, defines the discriminants of the type (see "Discriminants"). The remainder of the type_ declaration defines the remaining characteristics of (the view of) the type.
  7. A type defined by a type_declaration is a named type; such a type has one or more nameable subtypes. Certain other forms of declaration also include type definitions as part of the declaration for an object (including a parameter or a discriminant). The type defined by such a declaration is anonymous - it has no nameable subtypes. For explanatory purposes, this International Standard sometimes refers to an anonymous type by a pseudo-name, written in italics, and uses such pseudo-names at places where the syntax normally requires an identifier. For a named type whose first subtype is T, this International Standard sometimes refers to the type of T as simply "the type T."
  8. A named type that is declared by a full_type_declaration, or an anonymous type that is defined as part of declaring an object of the type, is called a full type. The type_definition, task_definition, protected_definition, or access_definition that defines a full type is called a full type definition. Types declared by other forms of type_declaration are not separate types; they are partial or incomplete views of some full type.
  9. The definition of a type implicitly declares certain predefined operators that operate on the type, according to what classes the type belongs, as specified in "Operators and Expression Evaluation".
  10. The predefined types (for example the types Boolean, Wide_Character, Integer, root_integer, and universal_integer) are the types that are defined in a predefined library package called Standard; this package also includes the (implicit) declarations of their predefined operators. The package Standard is described in A.1.

    Dynamic Semantics
  11. The elaboration of a full_type_declaration consists of the elaboration of the full type definition. Each elaboration of a full type definition creates a distinct type and its first subtype.

    Examples
  12. Examples of type definitions: 
  13. (White, Red, Yellow, Green, Blue, Brown, Black)
range 1 .. 72
array(1 .. 10) of Integer
  14. Examples of type declarations: 
  15. type Color  is (White, Red, Yellow, Green, Blue, Brown, Black);
type Column is range 1 .. 72;
type Table  is array(1 .. 10) of Integer;

    NOTES

  16. (3) Each of the above examples declares a named type. The identifier given denotes the first subtype of the type. Other named subtypes of the type can be declared with subtype_declarations (see 3.2.2). Although names do not directly denote types, a phrase like "the type Column" is sometimes used in this International Standard to refer to the type of Column, where Column denotes the first subtype of the type. For an example of the definition of an anonymous type, see the declaration of the array Color_Table in 3.3.1, its type is anonymous - it has no nameable subtypes.

Node:3.2.2, Next:, Previous:3.2.1, Up:3.2

Subtype Declarations

  1. A subtype_declaration declares a subtype of some previously declared type, as defined by a subtype_indication.

    Syntax
  2. subtype_declaration ::=
   subtype defining_identifier is subtype_indication;

  3. subtype_indication ::=  subtype_mark [constraint]

  4. subtype_mark ::= subtype_name

  5. constraint ::= scalar_constraint | composite_constraint

  6. scalar_constraint ::=
   range_constraint | digits_constraint | delta_constraint

  7. composite_constraint ::=
   index_constraint | discriminant_constraint

    Name Resolution Rules
  8. A subtype_mark shall resolve to denote a subtype. The type determined by a subtype_mark is the type of the subtype denoted by the subtype_mark.

    Dynamic Semantics
  9. The elaboration of a subtype_declaration consists of the elaboration of the subtype_indication. The elaboration of a subtype_indication creates a new subtype. If the subtype_indication does not include a constraint, the new subtype has the same (possibly null) constraint as that denoted by the subtype_mark. The elaboration of a subtype_indication that includes a constraint proceeds as follows:
    1. The constraint is first elaborated.
    2. A check is then made that the constraint is compatible with the subtype denoted by the subtype_mark.
  1. The condition imposed by a constraint is the condition obtained after elaboration of the constraint. The rules defining compatibility are given for each form of constraint in the appropriate subclause. These rules are such that if a constraint is compatible with a subtype, then the condition imposed by the constraint cannot contradict any condition already imposed by the subtype on its values. The exception Constraint_Error is raised if any check of compatibility fails.

    NOTES

  2. (4) A scalar_constraint may be applied to a subtype of an appropriate scalar type, see 3.5, see 3.5.9, and J.3, even if the subtype is already constrained. On the other hand, a composite_constraint may be applied to a composite subtype (or an access-to-composite subtype) only if the composite subtype is unconstrained, see 3.6.1 and 3.7.1.

    Examples
  3. Examples of subtype declarations: 
  4. subtype Rainbow   is Color range Red .. Blue;  -- see 3.2.1
subtype Red_Blue  is Rainbow;
subtype Int       is Integer;
subtype Small_Int is Integer range -10 .. 10;
subtype Up_To_K   is Column range 1 .. K;      -- see 3.2.1
subtype Square    is Matrix(1 .. 10, 1 .. 10); -- see 3.6
subtype Male      is Person(Sex => M);         -- see 3.10.1

Node:3.2.3, Next:, Previous:3.2.2, Up:3.2

Classification of Operations


Static Semantics
  1. An operation operates on a type T if it yields a value of type T, if it has an operand whose expected type, see 8.6, is T, or if it has an access parameter, see 6.1 designating T. A predefined operator, or other language-defined operation such as assignment or a membership test, that operates on a type, is called a predefined operation of the type. The primitive operations of a type are the predefined operations of the type, plus any user-defined primitive subprograms.
  2. The primitive subprograms of a specific type are defined as follows:
    1. The predefined operators of the type, see 4.5,
    2. For a derived type, the inherited, see 3.4, user-defined subprograms;
    3. For an enumeration type, the enumeration literals (which are considered parameterless functions - see 3.5.1.);
    4. For a specific type declared immediately within a package_specification, any subprograms (in addition to the enumeration literals) that are explicitly declared immediately within the same package_specification and that operate on the type;
    5. Any subprograms not covered above that are explicitly declared immediately within the same declarative region as the type and that override, see 8.3, other implicitly declared primitive subprograms of the type.
  1. A primitive subprogram whose designator is an operator_symbol is called a primitive operator.

Node:3.3, Next:, Previous:3.2.3, Up:3

Objects and Named Numbers

  1. Objects are created at run time and contain a value of a given type. An object can be created and initialized as part of elaborating a declaration, evaluating an allocator, aggregate, or function_call, or passing a parameter by copy. Prior to reclaiming the storage for an object, it is finalized if necessary, see 7.6.1.

    Static Semantics
  2. All of the following are objects:
    1. the entity declared by an object_declaration;
    2. a formal parameter of a subprogram, entry, or generic subprogram;
    3. a generic formal object;
    4. a loop parameter;
    5. a choice parameter of an exception_handler;
    6. an entry index of an entry_body;
    7. the result of dereferencing an access-to-object value, see 4.1,
    8. the result of evaluating a function_call (or the equivalent operator invocation - see 6.6,
    9. the result of evaluating an aggregate;
    10. a component, slice, or view conversion of another object.
  1. An object is either a constant object or a variable object. The value of a constant object cannot be changed between its initialization and its finalization, whereas the value of a variable object can be changed. Similarly, a view of an object is either a constant or a variable. All views of a constant object are constant. A constant view of a variable object cannot be used to modify the value of the variable. The terms constant and variable by themselves refer to constant and variable views of objects.
  2. The value of an object is read when the value of any part of the object is evaluated, or when the value of an enclosing object is evaluated. The value of a variable is updated when an assignment is performed to any part of the variable, or when an assignment is performed to an enclosing object.
  3. Whether a view of an object is constant or variable is determined by the definition of the view. The following (and no others) represent constants:
    1. an object declared by an object_declaration with the reserved word constant;
    2. a formal parameter or generic formal object of mode in;
    3. a discriminant;
    4. a loop parameter, choice parameter, or entry index;
    5. the dereference of an access-to-constant value;
    6. he result of evaluating a function_call or an aggregate;
    7. a selected_component, indexed_component, slice, or view conversion of a constant.
  1. At the place where a view of an object is defined, a nominal subtype is associated with the view. The object's actual subtype (that is, its subtype) can be more restrictive than the nominal subtype of the view; it always is if the nominal subtype is an indefinite subtype. A subtype is an indefinite subtype if it is an unconstrained array subtype, or if it has unknown discriminants or unconstrained discriminants without defaults (see 3.7) otherwise the subtype is a definite subtype (all elementary subtypes are definite subtypes). A class-wide subtype is defined to have unknown discriminants, and is therefore an indefinite subtype. An indefinite subtype does not by itself provide enough information to create an object; an additional constraint or explicit initialization expression is necessary (see 3.3.1). A component cannot have an indefinite nominal subtype.
  2. A named number provides a name for a numeric value known at compile time. It is declared by a number_declaration.

    NOTES

  3. (5) A constant cannot be the target of an assignment operation, nor be passed as an in out or out parameter, between its initialization and finalization, if any.
  4. (6) The nominal and actual subtypes of an elementary object are always the same. For a discriminated or array object, if the nominal subtype is constrained then so is the actual subtype.

Node:3.3.1, Next:, Previous:3.3, Up:3.3

Object Declarations

  1. An object_declaration declares a stand-alone object with a given nominal subtype and, optionally, an explicit initial value given by an initialization expression. For an array, task, or protected object, the object_declaration may include the definition of the (anonymous) type of the object.

    Syntax
  2. object_declaration ::=
    defining_identifier_list : [aliased] [constant]
      subtype_indication [:= expression];
  | defining_identifier_list : [aliased] [constant]
      array_type_definition [:= expression];
  | single_task_declaration
  | single_protected_declaration

  3. defining_identifier_list ::=
   defining_identifier {, defining_identifier}

    Name Resolution Rules
  4. For an object_declaration with an expression following the compound delimiter :=, the type expected for the expression is that of the object. This expression is called the initialization expression.

    Legality Rules
  5. An object_declaration without the reserved word constant declares a variable object. If it has a subtype_indication or an array_type_definition that defines an indefinite subtype, then there shall be an initialization expression. An initialization expression shall not be given if the object is of a limited type.

    Static Semantics
  6. An object_declaration with the reserved word constant declares a constant object. If it has an initialization expression, then it is called a full constant declaration. Otherwise it is called a deferred constant declaration. The rules for deferred constant declarations are given in clause (see 7.4). The rules for full constant declarations are given in this subclause.
  7. Any declaration that includes a defining_identifier_list with more than one defining_identifier is equivalent to a series of declarations each containing one defining_identifier from the list, with the rest of the text of the declaration copied for each declaration in the series, in the same order as the list. The remainder of this International Standard relies on this equivalence; explanations are given for declarations with a single defining_identifier.
  8. The subtype_indication or full type definition of an object_declaration defines the nominal subtype of the object. The object_declaration declares an object of the type of the nominal subtype.

    Dynamic Semantics
  9. If a composite object declared by an object_declaration has an unconstrained nominal subtype, then if this subtype is indefinite or the object is constant or aliased, see 3.10, the actual subtype of this object is constrained. The constraint is determined by the bounds or discriminants (if any) of its initial value; the object is said to be constrained by its initial value. In the case of an aliased object, this initial value may be either explicit or implicit; in the other cases, an explicit initial value is required. When not constrained by its initial value, the actual and nominal subtypes of the object are the same. If its actual subtype is constrained, the object is called a constrained object.
  10. For an object_declaration without an initialization expression, any initial values for the object or its subcomponents are determined by the implicit initial values defined for its nominal subtype, as follows:
    1. The implicit initial value for an access subtype is the null value of the access type.
    2. The implicit initial (and only) value for each discriminant of a constrained discriminated subtype is defined by the subtype.
    3. For a (definite) composite subtype, the implicit initial value of each component with a default_expression is obtained by evaluation of this expression and conversion to the component's nominal subtype (which might raise Constraint_Error - see "Type Conversions".), unless the component is a discriminant of a constrained subtype (the previous case), or is in an excluded variant, see 3.8.1. For each component that does not have a default_expression, any implicit initial values are those determined by the component's nominal subtype.
    4. For a protected or task subtype, there is an implicit component (an entry queue) corresponding to each entry, with its implicit initial value being an empty queue.
  1. The elaboration of an object_declaration proceeds in the following sequence of steps:
    1. The subtype_indication, array_type_definition, single_task_declaration, or single_protected_declaration is first elaborated. This creates the nominal subtype (and the anonymous type in the latter three cases).
    2. If the object_declaration includes an initialization expression, the (explicit) initial value is obtained by evaluating the expression and converting it to the nominal subtype (which might raise Constraint_Error - see 4.6.).
    3. The object is created, and, if there is not an initialization expression, any per-object expressions, see 3.8 are evaluated and any implicit initial values for the object or for its subcomponents are obtained as determined by the nominal subtype.
    4. Any initial values (whether explicit or implicit) are assigned to the object or to the corresponding subcomponents. As described in 5.2, and 7.6, Initialize and Adjust procedures can be called.
  1. For the third step above, the object creation and any elaborations and evaluations are performed in an arbitrary order, except that if the default_expression for a discriminant is evaluated to obtain its initial value, then this evaluation is performed before that of the default_expression for any component that depends on the discriminant, and also before that of any default_expression that includes the name of the discriminant. The evaluations of the third step and the assignments of the fourth step are performed in an arbitrary order, except that each evaluation is performed before the resulting value is assigned.
  2. There is no implicit initial value defined for a scalar subtype. In the absence of an explicit initialization, a newly created scalar object might have a value that does not belong to its subtype (see 13.9.1 and H.1).

    NOTES

  3. (7) Implicit initial values are not defined for an indefinite subtype, because if an object's nominal subtype is indefinite, an explicit initial value is required.
  4. (8) As indicated above, a stand-alone object is an object declared by an object_declaration. Similar definitions apply to "stand-alone constant" and "stand-alone variable." A subcomponent of an object is not a stand-alone object, nor is an object that is created by an allocator. An object declared by a loop_parameter_specification, parameter_specification, entry_index_specification, choice_parameter_specification, or a formal_object_declaration is not called a stand-alone object.
  5. (9) The type of a stand-alone object cannot be abstract, see 3.9.3.

    Examples
  6. Example of a multiple object declaration: 
  7. --  the multiple object declaration

  8. John, Paul : Person_Name := new Person(Sex => M); --  see 3.10.1

  9. --  is equivalent to the two single object
--  declarations in the order given

  10. John : Person_Name := new Person(Sex => M);
Paul : Person_Name := new Person(Sex => M);
  11. Examples of variable declarations: 
  12. Count, Sum  : Integer;
Size        : Integer range 0 .. 10_000 := 0;
Sorted      : Boolean := False;
Color_Table : array(1 .. Max) of Color;
Option      : Bit_Vector(1 .. 10) := (others => True);
Hello       : constant String := "Hi, world.";
  13. Examples of constant declarations: 
  14. Limit     : constant Integer := 10_000;
Low_Limit : constant Integer := Limit/10;
Tolerance : constant Real := Dispersion(1.15);

Node:3.3.2, Next:, Previous:3.3.1, Up:3.3

Number Declarations

  1. A number_declaration declares a named number.

    Syntax
  2. number_declaration ::=
   defining_identifier_list : constant := static_expression;

    Name Resolution Rules
  3. The static_expression given for a number_declaration is expected to be of any numeric type.

    Legality Rules
  4. The static_expression given for a number declaration shall be a static expression, as defined by clause (see 4.9).

    Static Semantics
  5. The named number denotes a value of type universal_integer if the type of the static_expression is an integer type. The named number denotes a value of type universal_real if the type of the static_expression is a real type.
  6. The value denoted by the named number is the value of the static_expression, converted to the corresponding universal type.

    Dynamic Semantics
  7. The elaboration of a number_declaration has no effect.

    Examples
  8. Examples of number declarations: 
  9. Two_Pi        : constant := 2.0*Ada.Numerics.Pi;
-- a real number, see A.5

  10. Max           : constant := 500;     -- an integer number
Max_Line_Size : constant := Max/6;   -- the integer 83
Power_16      : constant := 2**16;   -- the integer 65_536
One, Un, Eins : constant := 1;       -- three different names for 1

Node:3.4, Next:, Previous:3.3.2, Up:3

Derived Types and Classes

  1. A derived_type_definition defines a new type (and its first subtype) whose characteristics are derived from those of a parent type.

    Syntax
  2. derived_type_definition ::= [abstract] new
  parent_subtype_indication [record_extension_part]

    Legality Rules
  3. The parent_subtype_indication defines the parent subtype; its type is the parent type.
  4. A type shall be completely defined, see 3.11.1, prior to being specified as the parent type in a derived_type_definition - the full_type_declarations for the parent type and any of its subcomponents have to precede the derived_type_definition.
  5. If there is a record_extension_part, the derived type is called a record extension of the parent type. A record_extension_part shall be provided if and only if the parent type is a tagged type.

    Static Semantics
  6. The first subtype of the derived type is unconstrained if a known_discriminant_part is provided in the declaration of the derived type, or if the parent subtype is unconstrained. Otherwise, the constraint of the first subtype corresponds to that of the parent subtype in the following sense: it is the same as that of the parent subtype except that for a range constraint (implicit or explicit), the value of each bound of its range is replaced by the corresponding value of the derived type.
  7. The characteristics of the derived type are defined as follows:
    1. Each class of types that includes the parent type also includes the derived type.
    2. If the parent type is an elementary type or an array type, then the set of possible values of the derived type is a copy of the set of possible values of the parent type. For a scalar type, the base range of the derived type is the same as that of the parent type.
    3. If the parent type is a composite type other than an array type, then the components, protected subprograms, and entries that are declared for the derived type are as follows:
      1. The discriminants specified by a new known_discriminant_part, if there is one; otherwise, each discriminant of the parent type (implicitly declared in the same order with the same specifications) - in the latter case, the discriminants are said to be inherited, or if unknown in the parent, are also unknown in the derived type;
      2. Each nondiscriminant component, entry, and protected subprogram of the parent type, implicitly declared in the same order with the same declarations; these components, entries, and protected subprograms are said to be inherited;
      3. Each component declared in a record_extension_part, if any.
    1. Declarations of components, protected subprograms, and entries, whether implicit or explicit, occur immediately within the declarative region of the type, in the order indicated above, following the parent subtype_indication.
    2. The derived type is limited if and only if the parent type is limited.
    3. For each predefined operator of the parent type, there is a corresponding predefined operator of the derived type.
    4. For each user-defined primitive subprogram (other than a user-defined equality operator - see below) of the parent type that already exists at the place of the derived_type_definition, there exists a corresponding inherited primitive subprogram of the derived type with the same defining name. Primitive user-defined equality operators of the parent type are also inherited by the derived type, except when the derived type is a nonlimited record extension, and the inherited operator would have a profile that is type conformant with the profile of the corresponding predefined equality operator; in this case, the user-defined equality operator is not inherited, but is rather incorporated into the implementation of the predefined equality operator of the record extension, see 4.5.2.
    5. The profile of an inherited subprogram (including an inherited enumeration literal) is obtained from the profile of the corresponding (user-defined) primitive subprogram of the parent type, after systematic replacement of each subtype of its profile, see 6.1, that is of the parent type with a corresponding subtype of the derived type. For a given subtype of the parent type, the corresponding subtype of the derived type is defined as follows:
      1. If the declaration of the derived type has neither a known_discriminant_part nor a record_extension_part, then the corresponding subtype has a constraint that corresponds (as defined above for the first subtype of the derived type) to that of the given subtype.
      2. If the derived type is a record extension, then the corresponding subtype is the first subtype of the derived type.
      3. If the derived type has a new known_discriminant_part but is not a record extension, then the corresponding subtype is constrained to those values that when converted to the parent type belong to the given subtype, see 4.6.
    1. The same formal parameters have default_expressions in the profile of the inherited subprogram. Any type mismatch due to the systematic replacement of the parent type by the derived type is handled as part of the normal type conversion associated with parameter passing - see 6.4.1.
  1. If a primitive subprogram of the parent type is visible at the place of the derived_type_definition, then the corresponding inherited subprogram is implicitly declared immediately after the derived_type_definition. Otherwise, the inherited subprogram is implicitly declared later or not at all, as explained in 7.3.1.
  2. A derived type can also be defined by a private_extension_declaration (see 7.3) or a formal_derived_type_definition, see 12.5.1. Such a derived type is a partial view of the corresponding full or actual type.
  3. All numeric types are derived types, in that they are implicitly derived from a corresponding root numeric type (see 3.5.4, and 3.5.6).

    Dynamic Semantics
  4. The elaboration of a derived_type_definition creates the derived type and its first subtype, and consists of the elaboration of the subtype_indication and the record_extension_part, if any. If the subtype_indication depends on a discriminant, then only those expressions that do not depend on a discriminant are evaluated.
  5. For the execution of a call on an inherited subprogram, a call on the corresponding primitive subprogram of the parent type is performed; the normal conversion of each actual parameter to the subtype of the corresponding formal parameter, see 6.4.1 performs any necessary type conversion as well. If the result type of the inherited subprogram is the derived type, the result of calling the parent's subprogram is converted to the derived type.

    NOTES

  6. (10) Classes are closed under derivation - any class that contains a type also contains its derivatives. Operations available for a given class of types are available for the derived types in that class.
  7. (11) Evaluating an inherited enumeration literal is equivalent to evaluating the corresponding enumeration literal of the parent type, and then converting the result to the derived type. This follows from their equivalence to parameterless functions.
  8. (12) A generic subprogram is not a subprogram, and hence cannot be a primitive subprogram and cannot be inherited by a derived type. On the other hand, an instance of a generic subprogram can be a primitive subprogram, and hence can be inherited.
  9. (13) If the parent type is an access type, then the parent and the derived type share the same storage pool; there is a null access value for the derived type and it is the implicit initial value for the type (see 3.10).
  10. (14) If the parent type is a boolean type, the predefined relational operators of the derived type deliver a result of the predefined type Boolean, see 4.5.2. If the parent type is an integer type, the right operand of the predefined exponentiation operator is of the predefined type Integer, see 4.5.6.
  11. (15) Any discriminants of the parent type are either all inherited, or completely replaced with a new set of discriminants.
  12. (16) For an inherited subprogram, the subtype of a formal parameter of the derived type need not have any value in common with the first subtype of the derived type.
  13. (17) If the reserved word abstract is given in the declaration of a type, the type is abstract, see 3.9.3.

    Examples
  14. Examples of derived type declarations: 
  15. type Local_Coordinate is new Coordinate;   --  two different types
type Midweek is new Day range Tue .. Thu;  --  see 3.5.1
type Counter is new Positive;              --  same range as Positive

  16. type Special_Key is new Key_Manager.Key;   --  see 7.3.1
  -- the inherited subprograms have the following specifications:
  --         procedure Get_Key(K : out Special_Key);
  --         function "<"(X,Y : Special_Key) return Boolean;

Node:3.4.1, Next:, Previous:3.4, Up:3.4

Derivation Classes

  1. In addition to the various language-defined classes of types, types can be grouped into derivation classes.

    Static Semantics
  2. A derived type is derived from its parent type directly; it is derived indirectly from any type from which its parent type is derived. The derivation class of types for a type T (also called the class rooted at T) is the set consisting of T (the root type of the class) and all types derived from T (directly or indirectly) plus any associated universal or class-wide types (defined below).
  3. Every type is either a specific type, a class-wide type, or a universal type. A specific type is one defined by a type_declaration, a formal_type_declaration, or a full type definition embedded in a declaration for an object. Class-wide and universal types are implicitly defined, to act as representatives for an entire class of types, as follows:
  4. Class-wide types
      Class-wide types are defined for (and belong to) each derivation class rooted at a tagged type, see 3.9. Given a subtype S of a tagged type T, S'Class is the subtype_mark for a corresponding subtype of the tagged class-wide type T'Class. Such types are called "class-wide" because when a formal parameter is defined to be of a class-wide type T'Class, an actual parameter of any type in the derivation class rooted at T is acceptable, see 8.6.
    1. The set of values for a class-wide type T'Class is the discriminated union of the set of values of each specific type in the derivation class rooted at T (the tag acts as the implicit discriminant - see 3.9.). Class-wide types have no primitive subprograms of their own. However, as explained in 3.9.2, operands of a class-wide type T'Class can be used as part of a dispatching call on a primitive subprogram of the type T. The only components (including discriminants) of T'Class that are visible are those of T. If S is a first subtype, then S'Class is a first subtype.
  1. Universal types
      Universal types are defined for (and belong to) the integer, real, and fixed point classes, and are referred to in this standard as respectively, universal_integer, universal_real, and universal_fixed. These are analogous to class-wide types for these language-defined numeric classes. As with class-wide types, if a formal parameter is of a universal type, then an actual parameter of any type in the corresponding class is acceptable. In addition, a value of a universal type (including an integer or real numeric_literal) is "universal" in that it is acceptable where some particular type in the class is expected, see 8.6.
    1. The set of values of a universal type is the undiscriminated union of the set of values possible for any definable type in the associated class. Like class-wide types, universal types have no primitive subprograms of their own. However, their "universality" allows them to be used as operands with the primitive subprograms of any type in the corresponding class.
  1. The integer and real numeric classes each have a specific root type in addition to their universal type, named respectively root_integer and root_real.
  2. A class-wide or universal type is said to cover all of the types in its class. A specific type covers only itself.
  3. A specific type T2 is defined to be a descendant of a type T1 if T2 is the same as T1, or if T2 is derived (directly or indirectly) from T1. A class-wide type T2'Class is defined to be a descendant of type T1 if T2 is a descendant of T1. Similarly, the universal types are defined to be descendants of the root types of their classes. If a type T2 is a descendant of a type T1, then T1 is called an ancestor of T2. The ultimate ancestor of a type is the ancestor of the type that is not a descendant of any other type.
  4. An inherited component (including an inherited discriminant) of a derived type is inherited from a given ancestor of the type if the corresponding component was inherited by each derived type in the chain of derivations going back to the given ancestor.

    NOTES

  5. (18) Because operands of a universal type are acceptable to the predefined operators of any type in their class, ambiguity can result. For universal_integer and universal_real, this potential ambiguity is resolved by giving a preference, see 8.6 to the predefined operators of the corresponding root types (root_integer and root_real, respectively). Hence, in an apparently ambiguous expression like 
  6. 1 + 4 < 7
  7. where each of the literals is of type universal_integer, the predefined operators of root_integer will be preferred over those of other specific integer types, thereby resolving the ambiguity.

Node:3.5, Next:, Previous:3.4.1, Up:3

Scalar Types

  1. Scalar types comprise enumeration types, integer types, and real types. Enumeration types and integer types are called discrete types; each value of a discrete type has a position number which is an integer value. Integer types and real types are called numeric types. All scalar types are ordered, that is, all relational operators are predefined for their values.

    Syntax
  2. range_constraint ::= range range

  3. range ::=
     range_attribute_reference
   | simple_expression .. simple_expression
  4. A range has a lower bound and an upper bound and specifies a subset of the values of some scalar type (the type of the range). A range with lower bound L and upper bound R is described by "L .. R". If R is less than L, then the range is a null range, and specifies an empty set of values. Otherwise, the range specifies the values of the type from the lower bound to the upper bound, inclusive. A value belongs to a range if it is of the type of the range, and is in the subset of values specified by the range. A value satisfies a range constraint if it belongs to the associated range. One range is included in another if all values that belong to the first range also belong to the second.

    Name Resolution Rules
  5. For a subtype_indication containing a range_constraint, either directly or as part of some other scalar_constraint, the type of the range shall resolve to that of the type determined by the subtype_mark of the subtype_indication. For a range of a given type, the simple_expressions of the range (likewise, the simple_expressions of the equivalent range for a range_attribute_reference) are expected to be of the type of the range.

    Static Semantics
  6. The base range of a scalar type is the range of finite values of the type that can be represented in every unconstrained object of the type; it is also the range supported at a minimum for intermediate values during the evaluation of expressions involving predefined operators of the type.
  7. A constrained scalar subtype is one to which a range constraint applies. The range of a constrained scalar subtype is the range associated with the range constraint of the subtype. The range of an unconstrained scalar subtype is the base range of its type.

    Dynamic Semantics
  8. A range is compatible with a scalar subtype if and only if it is either a null range or each bound of the range belongs to the range of the subtype. A range_constraint is compatible with a scalar subtype if and only if its range is compatible with the subtype.
  9. The elaboration of a range_constraint consists of the evaluation of the range. The evaluation of a range determines a lower bound and an upper bound. If simple_expressions are given to specify bounds, the evaluation of the range evaluates these simple_expressions in an arbitrary order, and converts them to the type of the range. If a range_attribute_reference is given, the evaluation of the range consists of the evaluation of the range_attribute_reference.
  10. Attributes
  11. For every scalar subtype S, the following attributes are defined:
  12. S'First 
    S'First denotes the lower bound of the range of S. The value
of this attribute is of the type of S.
  13. S'Last 
    S'Last denotes the upper bound of the range of S. The value
of this attribute is of the type of S.
  14. S'Range 
    S'Range is equivalent to the range S'First .. S'Last.
  15. S'Base 
    S'Base denotes an unconstrained subtype of the type of
S. This unconstrained subtype is called the base subtype of
the type.
  16. S'Min
      S'Min denotes a function with the following specification: 
    1. function S'Min(Left, Right : S'Base)
  return S'Base
    2. The function returns the lesser of the values of the two parameters.
  1. S'Max
      S'Max denotes a function with the following specification: 
    1. function S'Max(Left, Right : S'Base)
  return S'Base
    2. The function returns the greater of the values of the two parameters.
  1. S'Succ
      S'Succ denotes a function with the following specification: 
    1. function S'Succ(Arg : S'Base)
  return S'Base
    2. For an enumeration type, the function returns the value whose position number is one more than that of the value of Arg; Constraint_Error is raised if there is no such value of the type. For an integer type, the function returns the result of adding one to the value of Arg. For a fixed point type, the function returns the result of adding small to the value of Arg. For a floating point type, the function returns the machine number (as defined in 3.5.7.) immediately above the value of Arg; Constraint_Error is raised if there is no such machine number.
  1. S'Pred
      S'Pred denotes a function with the following specification: 
    1. function S'Pred(Arg : S'Base)
  return S'Base
    2. For an enumeration type, the function returns the value whose position number is one less than that of the value of Arg; Constraint_Error is raised if there is no such value of the type. For an integer type, the function returns the result of subtracting one from the value of Arg. For a fixed point type, the function returns the result of subtracting small from the value of Arg. For a floating point type, the function returns the machine number (as defined in 3.5.7.) immediately below the value of Arg; Constraint_Error is raised if there is no such machine number.
  1. S'Wide_Image
      S'Wide_Image denotes a function with the following specification: 
    1. function S'Wide_Image(Arg : S'Base)
  return Wide_String
    2. The function returns an image of the value of Arg, that is, a sequence of characters representing the value in display form. The lower bound of the result is one.
    3. The image of an integer value is the corresponding decimal literal, without underlines, leading zeros, exponent, or trailing spaces, but with a single leading character that is either a minus sign or a space.
    4. The image of an enumeration value is either the corresponding identifier in upper case or the corresponding character literal (including the two apostrophes); neither leading nor trailing spaces are included. For a nongraphic character (a value of a character type that has no enumeration literal associated with it), the result is a corresponding language-defined or implementation-defined name in upper case (for example, the image of the nongraphic character identified as nul is "NUL" - the quotes are not part of the image).
    5. The image of a floating point value is a decimal real literal best approximating the value (rounded away from zero if halfway between) with a single leading character that is either a minus sign or a space, a single digit (that is nonzero unless the value is zero), a decimal point, S'Digits-1, see 3.5.8, digits after the decimal point (but one if S'Digits is one), an upper case E, the sign of the exponent (either + or -), and two or more digits (with leading zeros if necessary) representing the exponent. If S'Signed_Zeros is True, then the leading character is a minus sign for a negatively signed zero.
    6. The image of a fixed point value is a decimal real literal best approximating the value (rounded away from zero if halfway between) with a single leading character that is either a minus sign or a space, one or more digits before the decimal point (with no redundant leading zeros), a decimal point, and S'Aft, see 3.5.10, digits after the decimal point.
  1. S'Image
      S'Image denotes a function with the following specification: 
    1. function S'Image(Arg : S'Base)
  return String
    2. The function returns an image of the value of Arg as a String. The lower bound of the result is one. The image has the same sequence of graphic characters as that defined for S'Wide_Image if all the graphic characters are defined in Character; otherwise the sequence of characters is implementation defined (but no shorter than that of S'Wide_Image for the same value of Arg).
  1. S'Wide_Width 
    S'Wide_Width denotes the maximum length of a Wide_String
returned by S'Wide_Image over all values of the subtype S. It
denotes zero for a subtype that has a null range. Its type
is universal_integer.
  2. S'Width 
    S'Width denotes the maximum length of a String returned by
S'Image over all values of the subtype S. It denotes
zero for a subtype that has a null range. Its type is
universal_integer.
  3. S'Wide_Value
      S'Wide_Value denotes a function with the following specification: 
    1. function S'Wide_Value(Arg : Wide_String)
  return S'Base
    2. This function returns a value given an image of the value as a Wide_String, ignoring any leading or trailing spaces.
    3. For the evaluation of a call on S'Wide_Value for an enumeration subtype S, if the sequence of characters of the parameter (ignoring leading and trailing spaces) has the syntax of an enumeration literal and if it corresponds to a literal of the type of S (or corresponds to the result of S'Wide_Image for a nongraphic character of the type), the result is the corresponding enumeration value; otherwise Constraint_Error is raised.
    4. For the evaluation of a call on S'Wide_Value (or S'Value) for an integer subtype S, if the sequence of characters of the parameter (ignoring leading and trailing spaces) has the syntax of an integer literal, with an optional leading sign character (plus or minus for a signed type; only plus for a modular type), and the corresponding numeric value belongs to the base range of the type of S, then that value is the result; otherwise Constraint_Error is raised.
    5. For the evaluation of a call on S'Wide_Value (or S'Value) for a real subtype S, if the sequence of characters of the parameter (ignoring leading and trailing spaces) has the syntax of one of the following:
      1. numeric_literal
      2. numeral.[exponent]
      3. .numeral[exponent]
      4. base#based_numeral.#[exponent]
      5. base#.based_numeral#[exponent]
    1. with an optional leading sign character (plus or minus), and if the corresponding numeric value belongs to the base range of the type of S, then that value is the result; otherwise Constraint_Error is raised. The sign of a zero value is preserved (positive if none has been specified) if S'Signed_Zeros is True.
  1. S'Value
      S'Value denotes a function with the following specification: 
    1. function S'Value(Arg : String)
  return S'Base
    2. This function returns a value given an image of the value as a String, ignoring any leading or trailing spaces.
    3. For the evaluation of a call on S'Value for an enumeration subtype S, if the sequence of characters of the parameter (ignoring leading and trailing spaces) has the syntax of an enumeration literal and if it corresponds to a literal of the type of S (or corresponds to the result of S'Image for a value of the type), the result is the corresponding enumeration value; otherwise Constraint_Error is raised. For a numeric subtype S, the evaluation of a call on S'Value with Arg of type String is equivalent to a call on S'Wide_Value for a corresponding Arg of type Wide_String.

Implementation Permissions
  1. An implementation may extend the Wide_Value, Value, Wide_Image, and Image attributes of a floating point type to support special values such as infinities and NaNs.

    NOTES

  2. (19) The evaluation of S'First or S'Last never raises an exception. If a scalar subtype S has a nonnull range, S'First and S'Last belong to this range. These values can, for example, always be assigned to a variable of subtype S.
  3. (20) For a subtype of a scalar type, the result delivered by the attributes Succ, Pred, and Value might not belong to the subtype; similarly, the actual parameters of the attributes Succ, Pred, and Image need not belong to the subtype.
  4. (21) For any value V (including any nongraphic character) of an enumeration subtype S, S'Value(S'Image(V)) equals V, as does S'Wide_Value(S'Wide_Image(V)). Neither expression ever raises Constraint_Error.

    Examples
  5. Examples of ranges: 
  6. -10 .. 10
X .. X + 1
0.0 .. 2.0*Pi
Red .. Green     --  see 3.5.1
1 .. 0           -- a null range
Table'Range      -- a range attribute reference, see 3.6
  7. Examples of range constraints: 
  8. range -999.0 .. +999.0
range S'First+1 .. S'Last-1

Node:3.5.1, Next:, Previous:3.5, Up:3.5

Enumeration Types

  1. An enumeration_type_definition defines an enumeration type.

    Syntax
  2. enumeration_type_definition ::=
   (enumeration_literal_specification
     {, enumeration_literal_specification})

  3. enumeration_literal_specification ::=
   defining_identifier | defining_character_literal

  4. defining_character_literal ::= character_literal

    Legality Rules
  5. The defining_identifiers and defining_character_literals listed in an enumeration_type_definition shall be distinct.

    Static Semantics
  6. Each enumeration_literal_specification is the explicit declaration of the corresponding enumeration literal: it declares a parameterless function, whose defining name is the defining_identifier or defining_character_literal, and whose result type is the enumeration type.
  7. Each enumeration literal corresponds to a distinct value of the enumeration type, and to a distinct position number. The position number of the value of the first listed enumeration literal is zero; the position number of the value of each subsequent enumeration literal is one more than that of its predecessor in the list.
  8. The predefined order relations between values of the enumeration type follow the order of corresponding position numbers.
  9. If the same defining_identifier or defining_character_literal is specified in more than one enumeration_type_definition, the corresponding enumeration literals are said to be overloaded. At any place where an overloaded enumeration literal occurs in the text of a program, the type of the enumeration literal has to be determinable from the context, see 8.6.

    Dynamic Semantics
  10. The elaboration of an enumeration_type_definition creates the enumeration type and its first subtype, which is constrained to the base range of the type.
  11. When called, the parameterless function associated with an enumeration literal returns the corresponding value of the enumeration type.

    NOTES

  12. (22) If an enumeration literal occurs in a context that does not otherwise suffice to determine the type of the literal, then qualification by the name of the enumeration type is one way to resolve the ambiguity, see 4.7.

    Examples
  13. Examples of enumeration types and subtypes: 
  14. type Day    is (Mon, Tue, Wed, Thu, Fri, Sat, Sun);
type Suit   is (Clubs, Diamonds, Hearts, Spades);
type Gender is (M, F);
type Level  is (Low, Medium, Urgent);
type Color  is (White, Red, Yellow, Green, Blue, Brown, Black);
type Light  is (Red, Amber, Green); -- Red and Green are overloaded

  15. type Hexa   is ('A', 'B', 'C', 'D', 'E', 'F');
type Mixed  is ('A', 'B', '*', B, None, '?', '%');

  16. subtype Weekday is Day   range Mon .. Fri;
subtype Major   is Suit  range Hearts .. Spades;
subtype Rainbow is Color range Red .. Blue;
--  the Color Red, not the Light

Node:3.5.2, Next:, Previous:3.5.1, Up:3.5

Character Types


Static Semantics
  1. An enumeration type is said to be a character type if at least one of its enumeration literals is a character_literal.
  2. The predefined type Character is a character type whose values correspond to the 256 code positions of Row 00 (also known as Latin-1) of the ISO 10646 Basic Multilingual Plane (BMP). Each of the graphic characters of Row 00 of the BMP has a corresponding character_literal in Character. Each of the nongraphic positions of Row 00 (0000-001F and 007F-009F) has a corresponding language-defined name, which is not usable as an enumeration literal, but which is usable with the attributes (Wide_)Image and (Wide_)Value; these names are given in the definition of type Character in "The Package Standard", but are set in italics.
  3. The predefined type Wide_Character is a character type whose values correspond to the 65536 code positions of the ISO 10646 Basic Multilingual Plane (BMP). Each of the graphic characters of the BMP has a corresponding character_literal in Wide_Character. The first 256 values of Wide_Character have the same character_literal or language-defined name as defined for Character. The last 2 values of Wide_Character correspond to the nongraphic positions FFFE and FFFF of the BMP, and are assigned the language-defined names FFFE and FFFF. As with the other language-defined names for nongraphic characters, the names FFFE and FFFF are usable only with the attributes (Wide_)Image and (Wide_)Value; they are not usable as enumeration literals. All other values of Wide_Character are considered graphic characters, and have a corresponding character_literal.

    Implementation Permissions
  4. In a nonstandard mode, an implementation may provide other interpretations for the predefined types Character and Wide_Character, to conform to local conventions.

    Implementation Advice
  5. If an implementation supports a mode with alternative interpretations for Character and Wide_Character, the set of graphic characters of Character should nevertheless remain a proper subset of the set of graphic characters of Wide_Character. Any character set "localizations" should be reflected in the results of the subprograms defined in the language-defined package Characters.Handling, see A.3, available in such a mode. In a mode with an alternative interpretation of Character, the implementation should also support a corresponding change in what is a legal identifier_letter.

    NOTES

  6. (23) The language-defined library package Characters.Latin_1 (A.3.3) includes the declaration of constants denoting control characters, lower case characters, and special characters of the predefined type Character.
  7. (24) A conventional character set such as EBCDIC can be declared as a character type; the internal codes of the characters can be specified by an enumeration_representation_clause as explained in clause (see 13.4).

    Examples
  8. Example of a character type: 
  9. type Roman_Digit is ('I', 'V', 'X', 'L', 'C', 'D', 'M');

Node:3.5.3, Next:, Previous:3.5.2, Up:3.5

Boolean Types


Static Semantics
  1. There is a predefined enumeration type named Boolean, declared in the visible part of package Standard. It has the two enumeration literals False and True ordered with the relation False < True. Any descendant of the predefined type Boolean is called a boolean type.

Node:3.5.4, Next:, Previous:3.5.3, Up:3.5

Integer Types

  1. An integer_type_definition defines an integer type; it defines either a signed integer type, or a modular integer type. The base range of a signed integer type includes at least the values of the specified range. A modular type is an integer type with all arithmetic modulo a specified positive modulus; such a type corresponds to an unsigned type with wrap-around semantics.

    Syntax
  2. integer_type_definition ::=
   signed_integer_type_definition | modular_type_definition

  3. signed_integer_type_definition ::=
   range static_simple_expression .. static_simple_expression

  4. modular_type_definition ::= mod static_expression

    Name Resolution Rules
  5. Each simple_expression in a signed_integer_type_definition is expected to be of any integer type; they need not be of the same type. The expression in a modular_type_definition is likewise expected to be of any integer type.

    Legality Rules
  6. The simple_expressions of a signed_integer_type_definition shall be static, and their values shall be in the range System.Min_Int .. System.Max_Int.
  7. The expression of a modular_type_definition shall be static, and its value (the modulus) shall be positive, and shall be no greater than System.Max_Binary_Modulus if a power of 2, or no greater than System.Max_Nonbinary_Modulus if not.

    Static Semantics
  8. The set of values for a signed integer type is the (infinite) set of mathematical integers, though only values of the base range of the type are fully supported for run-time operations. The set of values for a modular integer type are the values from 0 to one less than the modulus, inclusive.
  9. A signed_integer_type_definition defines an integer type whose base range includes at least the values of the simple_expressions and is symmetric about zero, excepting possibly an extra negative value. A signed_integer_type_definition also defines a constrained first subtype of the type, with a range whose bounds are given by the values of the simple_expressions, converted to the type being defined.
  10. A modular_type_definition defines a modular type whose base range is from zero to one less than the given modulus. A modular_type_definition also defines a constrained first subtype of the type with a range that is the same as the base range of the type.
  11. There is a predefined signed integer subtype named Integer, declared in the visible part of package Standard. It is constrained to the base range of its type.
  12. Integer has two predefined subtypes, declared in the visible part of package Standard: 
  13. subtype Natural  is Integer range 0 .. Integer'Last;
subtype Positive is Integer range 1 .. Integer'Last;
  14. A type defined by an integer_type_definition is implicitly derived from root_integer, an anonymous predefined (specific) integer type, whose base range is System.Min_Int .. System.Max_Int. However, the base range of the new type is not inherited from root_integer, but is instead determined by the range or modulus specified by the integer_type_definition. Integer literals are all of the type universal_integer, the universal type, see 3.4.1, for the class rooted at root_integer, allowing their use with the operations of any integer type.
  15. The position number of an integer value is equal to the value.
  16. For every modular subtype S, the following attribute is defined:
  17. S'Modulus 
    S'Modulus yields the modulus of the type of S, as a value of
the type universal_integer.

    Dynamic Semantics
  18. The elaboration of an integer_type_definition creates the integer type and its first subtype.
  19. For a modular type, if the result of the execution of a predefined operator, see 4.5 is outside the base range of the type, the result is reduced modulo the modulus of the type to a value that is within the base range of the type.
  20. For a signed integer type, the exception Constraint_Error is raised by the execution of an operation that cannot deliver the correct result because it is outside the base range of the type. For any integer type, Constraint_Error is raised by the operators "/", "rem", and "mod" if the right operand is zero.

    Implementation Requirements
  21. In an implementation, the range of Integer shall include the range -2**15+1 .. +2**15-1.
  22. If Long_Integer is predefined for an implementation, then its range shall include the range -2**31+1 .. +2**31-1.
  23. System.Max_Binary_Modulus shall be at least 2**16.

    Implementation Permissions
  24. For the execution of a predefined operation of a signed integer type, the implementation need not raise Constraint_Error if the result is outside the base range of the type, so long as the correct result is produced.
  25. An implementation may provide additional predefined signed integer types, declared in the visible part of Standard, whose first subtypes have names of the form Short_Integer, Long_Integer, Short_Short_Integer, Long_Long_Integer, etc. Different predefined integer types are allowed to have the same base range. However, the range of Integer should be no wider than that of Long_Integer. Similarly, the range of Short_Integer (if provided) should be no wider than Integer. Corresponding recommendations apply to any other predefined integer types. There need not be a named integer type corresponding to each distinct base range supported by an implementation. The range of each first subtype should be the base range of its type.
  26. An implementation may provide nonstandard integer types, descendants of root_integer that are declared outside of the specification of package Standard, which need not have all the standard characteristics of a type defined by an integer_type_definition. For example, a nonstandard integer type might have an asymmetric base range or it might not be allowed as an array or loop index (a very long integer). Any type descended from a nonstandard integer type is also nonstandard. An implementation may place arbitrary restrictions on the use of such types; it is implementation defined whether operators that are predefined for "any integer type" are defined for a particular nonstandard integer type. In any case, such types are not permitted as explicit_generic_actual_parameters for formal scalar types - see 12.5.2.
  27. For a one's complement machine, the high bound of the base range of a modular type whose modulus is one less than a power of 2 may be equal to the modulus, rather than one less than the modulus. It is implementation defined for which powers of 2, if any, this permission is exercised.

    Implementation Advice
  28. An implementation should support Long_Integer in addition to Integer if the target machine supports 32-bit (or longer) arithmetic. No other named integer subtypes are recommended for package Standard. Instead, appropriate named integer subtypes should be provided in the library package Interfaces, see B.2.
  29. An implementation for a two's complement machine should support modular types with a binary modulus up to System.Max_Int*2+2. An implementation should support a nonbinary modulus up to Integer'Last.

    NOTES

  30. (25) Integer literals are of the anonymous predefined integer type universal_integer. Other integer types have no literals. However, the overload resolution rules, see "The Context of Overload Resolution", allow expressions of the type universal_integer whenever an integer type is expected.
  31. (26) The same arithmetic operators are predefined for all signed integer types defined by a signed_integer_type_definition, see "Operators and Expression Evaluation". For modular types, these same operators are predefined, plus bit-wise logical operators (and, or, xor, and not). In addition, for the unsigned types declared in the language-defined package Interfaces, see B.2, functions are defined that provide bit-wise shifting and rotating.
  32. (27) Modular types match a generic_formal_parameter_declaration of the form "type T is mod <>;"; signed integer types match "type T is range <>;", see 12.5.2.

    Examples
  33. Examples of integer types and subtypes: 
  34. type Page_Num  is range 1 .. 2_000;
type Line_Size is range 1 .. Max_Line_Size;

  35. subtype Small_Int   is Integer   range -10 .. 10;
subtype Column_Ptr  is Line_Size range 1 .. 10;
subtype Buffer_Size is Integer   range 0 .. Max;

  36. type Byte        is mod 256; -- an unsigned byte
type Hash_Index  is mod 97;  -- modulus is prime

Node:3.5.5, Next:, Previous:3.5.4, Up:3.5

Operations of Discrete Types


Static Semantics
  1. For every discrete subtype S, the following attributes are defined:
  2. S'Pos
      S'Pos denotes a function with the following specification: 
    1. function S'Pos(Arg : S'Base)
  return universal_integer
    2. This function returns the position number of the value of Arg, as a value of type universal_integer.
  1. S'Val
      S'Val denotes a function with the following specification: 
    1. function S'Val(Arg : universal_integer)
  return S'Base
    2. This function returns a value of the type of S whose position number equals the value of Arg. For the evaluation of a call on S'Val, if there is no value in the base range of its type with the given position number, Constraint_Error is raised.

Implementation Advice
  1. For the evaluation of a call on S'Pos for an enumeration subtype, if the value of the operand does not correspond to the internal code for any enumeration literal of its type (perhaps due to an uninitialized variable), then the implementation should raise Program_Error. This is particularly important for enumeration types with noncontiguous internal codes specified by an enumeration_representation_clause.

    NOTES

  2. (28) Indexing and loop iteration use values of discrete types.
  3. (29) The predefined operations of a discrete type include the assignment operation, qualification, the membership tests, and the relational operators; for a boolean type they include the short-circuit control forms and the logical operators; for an integer type they include type conversion to and from other numeric types, as well as the binary and unary adding operators - and +, the multiplying operators, the unary operator abs, and the exponentiation operator. The assignment operation is described in 5.2. The other predefined operations are described in Section 4.
  4. (30) As for all types, objects of a discrete type have Size and Address attributes, see 13.3.
  5. (31) For a subtype of a discrete type, the result delivered by the attribute Val might not belong to the subtype; similarly, the actual parameter of the attribute Pos need not belong to the subtype. The following relations are satisfied (in the absence of an exception) by these attributes: 
  6. S'Val(S'Pos(X)) = X
S'Pos(S'Val(N)) = N

    Examples
  7. Examples of attributes of discrete subtypes: 
  8. --  For the types and subtypes declared in subclause
--  see 3.5.1, the following hold:

  9. --  Color'First   = White,   Color'Last   = Black
--  Rainbow'First = Red,     Rainbow'Last = Blue

  10. --  Color'Succ(Blue) = Rainbow'Succ(Blue) = Brown
--  Color'Pos(Blue)  = Rainbow'Pos(Blue)  = 4
--  Color'Val(0)     = Rainbow'Val(0)     = White

Node:3.5.6, Next:, Previous:3.5.5, Up:3.5

Real Types

  1. Real types provide approximations to the real numbers, with relative bounds on errors for floating point types, and with absolute bounds for fixed point types.

    Syntax
  2. real_type_definition ::=
   floating_point_definition | fixed_point_definition

    Static Semantics
  3. A type defined by a real_type_definition is implicitly derived from root_real, an anonymous predefined (specific) real type. Hence, all real types, whether floating point or fixed point, are in the derivation class rooted at root_real.
  4. Real literals are all of the type universal_real, the universal type (see 3.4.1) for the class rooted at root_real, allowing their use with the operations of any real type. Certain multiplying operators have a result type of universal_fixed, see 4.5.5, the universal type for the class of fixed point types, allowing the result of the multiplication or division to be used where any specific fixed point type is expected.

    Dynamic Semantics
  5. The elaboration of a real_type_definition consists of the elaboration of the floating_point_definition or the fixed_point_definition.

    Implementation Requirements
  6. An implementation shall perform the run-time evaluation of a use of a predefined operator of root_real with an accuracy at least as great as that of any floating point type definable by a floating_point_definition.

    Implementation Permissions
  7. For the execution of a predefined operation of a real type, the implementation need not raise Constraint_Error if the result is outside the base range of the type, so long as the correct result is produced, or the Machine_Overflows attribute of the type is false, see G.2.
  8. An implementation may provide nonstandard real types, descendants of root_real that are declared outside of the specification of package Standard, which need not have all the standard characteristics of a type defined by a real_type_definition. For example, a nonstandard real type might have an asymmetric or unsigned base range, or its predefined operations might wrap around or "saturate" rather than overflow (modular or saturating arithmetic), or it might not conform to the accuracy model, see G.2. Any type descended from a nonstandard real type is also nonstandard. An implementation may place arbitrary restrictions on the use of such types; it is implementation defined whether operators that are predefined for "any real type" are defined for a particular nonstandard real type. In any case, such types are not permitted as explicit_generic_actual_parameters for formal scalar types - see 12.5.2.

    NOTES

  9. (32) As stated, real literals are of the anonymous predefined real type universal_real. Other real types have no literals. However, the overload resolution rules, see 8.6, allow expressions of the type universal_real whenever a real type is expected.

Node:3.5.7, Next:, Previous:3.5.6, Up:3.5

Floating Point Types

  1. For floating point types, the error bound is specified as a relative precision by giving the required minimum number of significant decimal digits.

    Syntax
  2. floating_point_definition ::=
   digits static_expression [real_range_specification]

  3. real_range_specification ::=
   range static_simple_expression .. static_simple_expression

    Name Resolution Rules
  4. The requested decimal precision, which is the minimum number of significant decimal digits required for the floating point type, is specified by the value of the expression given after the reserved word digits. This expression is expected to be of any integer type.
  5. Each simple_expression of a real_range_specification is expected to be of any real type; the types need not be the same.

    Legality Rules
  6. The requested decimal precision shall be specified by a static expression whose value is positive and no greater than System.Max_Base_Digits. Each simple_expression of a real_range_specification shall also be static. If the real_range_specification is omitted, the requested decimal precision shall be no greater than System.Max_Digits.
  7. A floating_point_definition is illegal if the implementation does not support a floating point type that satisfies the requested decimal precision and range.

    Static Semantics
  8. The set of values for a floating point type is the (infinite) set of rational numbers. The machine numbers of a floating point type are the values of the type that can be represented exactly in every unconstrained variable of the type. The base range, see 3.5, of a floating point type is symmetric around zero, except that it can include some extra negative values in some implementations.
  9. The base decimal precision of a floating point type is the number of decimal digits of precision representable in objects of the type. The safe range of a floating point type is that part of its base range for which the accuracy corresponding to the base decimal precision is preserved by all predefined operations.
  10. A floating_point_definition defines a floating point type whose base decimal precision is no less than the requested decimal precision. If a real_range_specification is given, the safe range of the floating point type (and hence, also its base range) includes at least the values of the simple expressions given in the real_range_specification. If a real_range_specification is not given, the safe (and base) range of the type includes at least the values of the range -10.0**(4*D) .. +10.0**(4*D) where D is the requested decimal precision. The safe range might include other values as well. The attributes Safe_First and Safe_Last give the actual bounds of the safe range.
  11. A floating_point_definition also defines a first subtype of the type. If a real_range_specification is given, then the subtype is constrained to a range whose bounds are given by a conversion of the values of the simple_expressions of the real_range_specification to the type being defined. Otherwise, the subtype is unconstrained.
  12. There is a predefined, unconstrained, floating point subtype named Float, declared in the visible part of package Standard.

    Dynamic Semantics
  13. The elaboration of a floating_point_definition creates the floating point type and its first subtype.

    Implementation Requirements
  14. In an implementation that supports floating point types with 6 or more digits of precision, the requested decimal precision for Float shall be at least 6.
  15. If Long_Float is predefined for an implementation, then its requested decimal precision shall be at least 11.

    Implementation Permissions
  16. An implementation is allowed to provide additional predefined floating point types, declared in the visible part of Standard, whose (unconstrained) first subtypes have names of the form Short_Float, Long_Float, Short_Short_Float, Long_Long_Float, etc. Different predefined floating point types are allowed to have the same base decimal precision. However, the precision of Float should be no greater than that of Long_Float. Similarly, the precision of Short_Float (if provided) should be no greater than Float. Corresponding recommendations apply to any other predefined floating point types. There need not be a named floating point type corresponding to each distinct base decimal precision supported by an implementation.

    Implementation Advice
  17. An implementation should support Long_Float in addition to Float if the target machine supports 11 or more digits of precision. No other named floating point subtypes are recommended for package Standard. Instead, appropriate named floating point subtypes should be provided in the library package Interfaces, see B.2.

    NOTES

  18. (33) If a floating point subtype is unconstrained, then assignments to variables of the subtype involve only Overflow_Checks, never Range_Checks.

    Examples
  19. Examples of floating point types and subtypes: 
  20. type Coefficient is digits 10 range -1.0 .. 1.0;

  21. type Real is digits 8;
type Mass is digits 7 range 0.0 .. 1.0E35;

  22. subtype Probability is Real range 0.0 .. 1.0;
--  a subtype with a smaller range

Node:3.5.8, Next:, Previous:3.5.7, Up:3.5

Operations of Floating Point Types


Static Semantics
  1. The following attribute is defined for every floating point subtype S:
  2. S'Digits 
    S'Digits denotes the requested decimal precision for the
subtype S. The value of this attribute is of the type
universal_integer. The requested decimal precision of the
base subtype of a floating point type T is defined to be the
largest value of d for which ceiling(d * log(10) /
log(T'Machine_Radix)) + 1 <= T'Model_Mantissa.

    NOTES

  3. (34) The predefined operations of a floating point type include the assignment operation, qualification, the membership tests, and explicit conversion to and from other numeric types. They also include the relational operators and the following predefined arithmetic operators: the binary and unary adding operators - and +, certain multiplying operators, the unary operator abs, and the exponentiation operator.
  4. (35) As for all types, objects of a floating point type have Size and Address attributes, see 13.3. Other attributes of floating point types are defined in A.5.3.

Node:3.5.9, Next:, Previous:3.5.8, Up:3.5

Fixed Point Types

  1. A fixed point type is either an ordinary fixed point type, or a decimal fixed point type. The error bound of a fixed point type is specified as an absolute value, called the delta of the fixed point type.

    Syntax
  2. fixed_point_definition ::=
   ordinary_fixed_point_definition | decimal_fixed_point_definition

  3. ordinary_fixed_point_definition ::=
   delta static_expression real_range_specification

  4. decimal_fixed_point_definition ::=
   delta static_expression digits static_expression
     [real_range_specification]

  5. digits_constraint ::=
   digits static_expression [range_constraint]

    Name Resolution Rules
  6. For a type defined by a fixed_point_definition, the delta of the type is specified by the value of the expression given after the reserved word delta; this expression is expected to be of any real type. For a type defined by a decimal_fixed_point_definition (a decimal fixed point type), the number of significant decimal digits for its first subtype (the digits of the first subtype) is specified by the expression given after the reserved word digits; this expression is expected to be of any integer type.

    Legality Rules
  7. In a fixed_point_definition or digits_constraint, the expressions given after the reserved words delta and digits shall be static; their values shall be positive.
  8. The set of values of a fixed point type comprise the integral multiples of a number called the small of the type. For a type defined by an ordinary_fixed_point_definition (an ordinary fixed point type), the small may be specified by an attribute_definition_clause, see 13.3, if so specified, it shall be no greater than the delta of the type. If not specified, the small of an ordinary fixed point type is an implementation-defined power of two less than or equal to the delta.
  9. For a decimal fixed point type, the small equals the delta; the delta shall be a power of 10. If a real_range_specification is given, both bounds of the range shall be in the range -(10**digits-1)*delta .. +(10**digits-1)*delta.
  10. A fixed_point_definition is illegal if the implementation does not support a fixed point type with the given small and specified range or digits.
  11. For a subtype_indication with a digits_constraint, the subtype_mark shall denote a decimal fixed point subtype.

    Static Semantics
  12. The base range, see 3.5 of a fixed point type is symmetric around zero, except possibly for an extra negative value in some implementations.
  13. An ordinary_fixed_point_definition defines an ordinary fixed point type whose base range includes at least all multiples of small that are between the bounds specified in the real_range_specification. The base range of the type does not necessarily include the specified bounds themselves. An ordinary_fixed_point_definition also defines a constrained first subtype of the type, with each bound of its range given by the closer to zero of:
    1. the value of the conversion to the fixed point type of the corresponding expression of the real_range_specification;
    2. the corresponding bound of the base range.
  1. A decimal_fixed_point_definition defines a decimal fixed point type whose base range includes at least the range -(10**digits-1)*delta .. +(10**digits-1)*delta. A decimal_fixed_point_definition also defines a constrained first subtype of the type. If a real_range_specification is given, the bounds of the first subtype are given by a conversion of the values of the expressions of the real_range_specification. Otherwise, the range of the first subtype is -(10**digits-1)*delta .. +(10**digits-1)*delta.

    Dynamic Semantics
  2. The elaboration of a fixed_point_definition creates the fixed point type and its first subtype.
  3. For a digits_constraint on a decimal fixed point subtype with a given delta, if it does not have a range_constraint, then it specifies an implicit range -(10**D-1)*delta .. +(10**D-1)*delta, where D is the value of the expression. A digits_constraint is compatible with a decimal fixed point subtype if the value of the expression is no greater than the digits of the subtype, and if it specifies (explicitly or implicitly) a range that is compatible with the subtype.
  4. The elaboration of a digits_constraint consists of the elaboration of the range_constraint, if any. If a range_constraint is given, a check is made that the bounds of the range are both in the range -(10**D-1)*delta .. +(10**D-1)*delta, where D is the value of the (static) expression given after the reserved word digits. If this check fails, Constraint_Error is raised.

    Implementation Requirements
  5. The implementation shall support at least 24 bits of precision (including the sign bit) for fixed point types.

    Implementation Permissions
  6. Implementations are permitted to support only smalls that are a power of two. In particular, all decimal fixed point type declarations can be disallowed. Note however that conformance with the Information Systems Annex requires support for decimal smalls, and decimal fixed point type declarations with digits up to at least 18.

    NOTES

  7. (36) The base range of an ordinary fixed point type need not include the specified bounds themselves so that the range specification can be given in a natural way, such as: 
  8. type Fraction is delta 2.0**(-15) range -1.0 .. 1.0;
  9. With 2's complement hardware, such a type could have a signed 16-bit representation, using 1 bit for the sign and 15 bits for fraction, resulting in a base range of -1.0 .. 1.0-2.0**(-15).

    Examples
  10. Examples of fixed point types and subtypes: 
  11. type Volt is delta 0.125 range 0.0 .. 255.0;

  12. --  A pure fraction which requires all the available
--  space in a word can be declared as the type Fraction:

type Fraction is delta System.Fine_Delta range -1.0 .. 1.0;
--  Fraction'Last = 1.0 - System.Fine_Delta

  13. type Money is delta 0.01 digits 15;  -- decimal fixed point
subtype Salary is Money digits 10;
  -- Money'Last = 10.0**13 - 0.01, Salary'Last = 10.0**8 - 0.01

Node:3.5.10, Next:, Previous:3.5.9, Up:3.5

Operations of Fixed Point Types


Static Semantics
  1. The following attributes are defined for every fixed point subtype S:
  2. S'Small 
    S'Small denotes the small of the type of S. The value of
this attribute is of the type universal_real. Small may
be specified for nonderived fixed point types via an
attribute_definition_clause, see 13.3; the expression
of such a clause shall be static.
  3. S'Delta 
    S'Delta denotes the delta of the fixed point subtype S. The
value of this attribute is of the type universal_real.
  4. S'Fore 
    S'Fore yields the minimum number of characters needed
before the decimal point for the decimal representation
of any value of the subtype S, assuming that the
representation does not include an exponent, but
includes a one-character prefix that is either a minus
sign or a space. (This minimum number does not include
superfluous zeros or underlines, and is at least 2.) The
value of this attribute is of the type
universal_integer.
  5. S'Aft 
    S'Aft yields the number of decimal digits needed after the
decimal point to accommodate the delta of the subtype S,
unless the delta of the subtype S is greater than 0.1, in
which case the attribute yields the value one. (S'Aft is the
smallest positive integer N for which (10**N)*S'Delta is
greater than or equal to one.) The value of this attribute
is of the type universal_integer.
  6. The following additional attributes are defined for every decimal fixed point subtype S:
  7. S'Digits 
    S'Digits denotes the digits of the decimal fixed point
subtype S, which corresponds to the number of decimal digits
that are representable in objects of the subtype. The value
of this attribute is of the type universal_integer. Its
value is determined as follows:
    1. For a first subtype or a subtype defined by a subtype_indication with a digits_constraint, the digits is the value of the expression given after the reserved word digits;
    2. For a subtype defined by a subtype_indication without a digits_constraint, the digits of the subtype is the same as that of the subtype denoted by the subtype_mark in the subtype_indication.
    3. The digits of a base subtype is the largest integer D such that the range -(10**D-1)*delta .. +(10**D-1)*delta is included in the base range of the type.
  1. S'Scale 
    S'Scale denotes the scale of the subtype S, defined as the
value N such that S'Delta = 10.0**(-N). The scale indicates
the position of the point relative to the rightmost
significant digits of values of subtype S. The value of this
attribute is of the type universal_integer.
  2. S'Round
      S'Round denotes a function with the following specification: 
    1. function S'Round(X : universal_real)
  return S'Base
    2. The function returns the value obtained by rounding X (away from 0, if X is midway between two values of the type of S).

    NOTES

  1. (37) All subtypes of a fixed point type will have the same value for the Delta attribute, in the absence of delta_constraints, see J.3.
  2. (38) S'Scale is not always the same as S'Aft for a decimal subtype; for example, if S'Delta = 1.0 then S'Aft is 1 while S'Scale is 0.
  3. (39) The predefined operations of a fixed point type include the assignment operation, qualification, the membership tests, and explicit conversion to and from other numeric types. They also include the relational operators and the following predefined arithmetic operators: the binary and unary adding operators - and +, multiplying operators, and the unary operator abs.
  4. (40) As for all types, objects of a fixed point type have Size and Address attributes, see 13.3. Other attributes of fixed point types are defined in A.5.4.

Node:3.6, Next:, Previous:3.5.10, Up:3

Array Types

  1. An array object is a composite object consisting of components which all have the same subtype. The name for a component of an array uses one or more index values belonging to specified discrete types. The value of an array object is a composite value consisting of the values of the components.

    Syntax
  2. array_type_definition ::=
   unconstrained_array_definition | constrained_array_definition

  3. unconstrained_array_definition ::=
   array(index_subtype_definition {, index_subtype_definition})
     of component_definition

  4. index_subtype_definition ::= subtype_mark range <>

  5. constrained_array_definition ::=
   array (discrete_subtype_definition
     {, discrete_subtype_definition}) of component_definition

  6. discrete_subtype_definition ::= discrete_subtype_indication | range

  7. component_definition ::= [aliased] subtype_indication

    Name Resolution Rules
  8. For a discrete_subtype_definition that is a range, the range shall resolve to be of some specific discrete type; which discrete type shall be determined without using any context other than the bounds of the range itself (plus the preference for root_integer - see 8.6.).

    Legality Rules
  9. Each index_subtype_definition or discrete_subtype_definition in an array_type_definition defines an index subtype; its type (the index type) shall be discrete.
  10. The subtype defined by the subtype_indication of a component_definition (the component subtype) shall be a definite subtype.
  11. Within the definition of a nonlimited composite type (or a limited composite type that later in its immediate scope becomes nonlimited - 7.3.1, and 7.5.), if a component_definition contains the reserved word aliased and the type of the component is discriminated, then the nominal subtype of the component shall be constrained.

    Static Semantics
  12. An array is characterized by the number of indices (the dimensionality of the array), the type and position of each index, the lower and upper bounds for each index, and the subtype of the components. The order of the indices is significant.
  13. A one-dimensional array has a distinct component for each possible index value. A multidimensional array has a distinct component for each possible sequence of index values that can be formed by selecting one value for each index position (in the given order). The possible values for a given index are all the values between the lower and upper bounds, inclusive; this range of values is called the index range. The bounds of an array are the bounds of its index ranges. The length of a dimension of an array is the number of values of the index range of the dimension (zero for a null range). The length of a one-dimensional array is the length of its only dimension.
  14. An array_type_definition defines an array type and its first subtype. For each object of this array type, the number of indices, the type and position of each index, and the subtype of the components are as in the type definition; the values of the lower and upper bounds for each index belong to the corresponding index subtype of its type, except for null arrays, see 3.6.1.
  15. An unconstrained_array_definition defines an array type with an unconstrained first subtype. Each index_subtype_definition defines the corresponding index subtype to be the subtype denoted by the subtype_mark. The compound delimiter <> (called a box) of an index_subtype_definition stands for an undefined range (different objects of the type need not have the same bounds).
  16. A constrained_array_definition defines an array type with a constrained first subtype. Each discrete_subtype_definition defines the corresponding index subtype, as well as the corresponding index range for the constrained first subtype. The constraint of the first subtype consists of the bounds of the index ranges.
  17. The discrete subtype defined by a discrete_subtype_definition is either that defined by the subtype_indication, or a subtype determined by the range as follows:
    1. If the type of the range resolves to root_integer, then the discrete_subtype_definition defines a subtype of the predefined type Integer with bounds given by a conversion to Integer of the bounds of the range;
    2. Otherwise, the discrete_subtype_definition defines a subtype of the type of the range, with the bounds given by the range.
  1. The component_definition of an array_type_definition defines the nominal subtype of the components. If the reserved word aliased appears in the component_definition, then each component of the array is aliased, see 3.10.

    Dynamic Semantics
  2. The elaboration of an array_type_definition creates the array type and its first subtype, and consists of the elaboration of any discrete_subtype_definitions and the component_definition.
  3. The elaboration of a discrete_subtype_definition creates the discrete subtype, and consists of the elaboration of the subtype_indication or the evaluation of the range. The elaboration of a component_definition in an array_type_definition consists of the elaboration of the subtype_indication. The elaboration of any discrete_subtype_definitions and the elaboration of the component_definition are performed in an arbitrary order.

    NOTES

  4. (41) All components of an array have the same subtype. In particular, for an array of components that are one-dimensional arrays, this means that all components have the same bounds and hence the same length.
  5. (42) Each elaboration of an array_type_definition creates a distinct array type. A consequence of this is that each object whose object_declaration contains an array_type_definition is of its own unique type.

    Examples
  6. Examples of type declarations with unconstrained array definitions: 
  7. type Vector     is array(Integer  range <>) of Real;

type Matrix     is array(Integer  range <>, Integer range <>)
  of Real;

type Bit_Vector is array(Integer  range <>) of Boolean;

type Roman      is array(Positive range <>) of
  Roman_Digit;  --  see 3.5.2
  8. Examples of type declarations with constrained array definitions: 
  9. type Table    is array(1 .. 10) of Integer;
type Schedule is array(Day) of Boolean;
type Line     is array(1 .. Max_Line_Size) of Character;
  10. Examples of object declarations with array type definitions: 
  11. Grid : array(1 .. 80, 1 .. 100) of Boolean;
Mix  : array(Color range Red .. Green) of Boolean;
Page : array(Positive range <>) of Line :=  --  an array of arrays
  (1 | 50  => Line'(1 | Line'Last => '+', others => '-'),
  --  see 4.3.3
   2 .. 49 => Line'(1 | Line'Last => '|', others => ' '));
    -- Page is constrained by its initial value to (1..50)

Node:3.6.1, Next:, Previous:3.6, Up:3.6

Index Constraints and Discrete Ranges

  1. An index_constraint determines the range of possible values for every index of an array subtype, and thereby the corresponding array bounds.

    Syntax
  2. index_constraint ::= (discrete_range {, discrete_range})

  3. discrete_range ::= discrete_subtype_indication | range

    Name Resolution Rules
  4. The type of a discrete_range is the type of the subtype defined by the subtype_indication, or the type of the range. For an index_constraint, each discrete_range shall resolve to be of the type of the corresponding index.

    Legality Rules
  5. An index_constraint shall appear only in a subtype_indication whose subtype_mark denotes either an unconstrained array subtype, or an unconstrained access subtype whose designated subtype is an unconstrained array subtype; in either case, the index_constraint shall provide a discrete_range for each index of the array type.

    Static Semantics
  6. A discrete_range defines a range whose bounds are given by the range, or by the range of the subtype defined by the subtype_indication.

    Dynamic Semantics
  7. An index_constraint is compatible with an unconstrained array subtype if and only if the index range defined by each discrete_range is compatible, see 3.5, with the corresponding index subtype. If any of the discrete_ranges defines a null range, any array thus constrained is a null array, having no components. An array value satisfies an index_constraint if at each index position the array value and the index_constraint have the same index bounds.
  8. The elaboration of an index_constraint consists of the evaluation of the discrete_range(s), in an arbitrary order. The evaluation of a discrete_range consists of the elaboration of the subtype_indication or the evaluation of the range.

    NOTES

  9. (43) The elaboration of a subtype_indication consisting of a subtype_mark followed by an index_constraint checks the compatibility of the index_constraint with the subtype_mark, see 3.2.2.
  10. (44) Even if an array value does not satisfy the index constraint of an array subtype, Constraint_Error is not raised on conversion to the array subtype, so long as the length of each dimension of the array value and the array subtype match (see 4.6).

    Examples
  11. Examples of array declarations including an index constraint: 
  12. Board     : Matrix(1 .. 8,  1 .. 8);  --  see 3.6
Rectangle : Matrix(1 .. 20, 1 .. 30);
Inverse   : Matrix(1 .. N,  1 .. N);  --  N need not be static

  13. Filter    : Bit_Vector(0 .. 31);
  14. Example of array declaration with a constrained array subtype: 
  15. My_Schedule : Schedule;
--  all arrays of type Schedule have the same bounds
  16. Example of record type with a component that is an array: 
  17. type Var_Line(Length : Natural) is
   record
      Image : String(1 .. Length);
   end record;

  18. Null_Line : Var_Line(0);  --  Null_Line.Image is a null array

Node:3.6.2, Next:, Previous:3.6.1, Up:3.6

Operations of Array Types


Legality Rules
  1. The argument N used in the attribute_designators for the N-th dimension of an array shall be a static expression of some integer type. The value of N shall be positive (nonzero) and no greater than the dimensionality of the array.

    Static Semantics
  2. The following attributes are defined for a prefix A that is of an array type (after any implicit dereference), or denotes a constrained array subtype:
  3. A'First 
    A'First denotes the lower bound of the first index range; its
type is the corresponding index type.
  4. A'First(N) 
    A'First(N) denotes the lower bound of the N-th index range;
its type is the corresponding index type.
  5. A'Last 
    A'Last denotes the upper bound of the first index range; its
type is the corresponding index type.
  6. A'Last(N) 
    A'Last(N) denotes the upper bound of the N-th index range;
its type is the corresponding index type.
  7. A'Range 
    A'Range is equivalent to the range A'First .. A'Last, except
that the prefix A is only evaluated once.
  8. A'Range(N) 
    A'Range(N) is equivalent to the range A'First(N) ..
A'Last(N), except that the prefix A is only evaluated once.
  9. A'Length 
    A'Length denotes the number of values of the first index
range (zero for a null range); its type is universal_integer.
  10. A'Length(N) 
    A'Length(N) denotes the number of values of the N-th index
range (zero for a null range); its type is universal_integer.

    Implementation Advice
  11. An implementation should normally represent multidimensional arrays in row-major order, consistent with the notation used for multidimensional array aggregates, see 4.3.3. However, if a pragma Convention(Fortran, ...) applies to a multidimensional array type, then column-major order should be used instead, see "Interfacing with Fortran".

    NOTES

  12. (45) The attribute_references A'First and A'First(1) denote the same value. A similar relation exists for the attribute_references A'Last, A'Range, and A'Length. The following relation is satisfied (except for a null array) by the above attributes if the index type is an integer type: 
  13. A'Length(N) = A'Last(N) - A'First(N) + 1
  14. (46) An array type is limited if its component type is limited, see 7.5.
  15. (47) The predefined operations of an array type include the membership tests, qualification, and explicit conversion. If the array type is not limited, they also include assignment and the predefined equality operators. For a one-dimensional array type, they include the predefined concatenation operators (if nonlimited) and, if the component type is discrete, the predefined relational operators; if the component type is boolean, the predefined logical operators are also included.
  16. (48) A component of an array can be named with an indexed_component. A value of an array type can be specified with an array_aggregate, unless the array type is limited. For a one-dimensional array type, a slice of the array can be named; also, string literals are defined if the component type is a character type.

    Examples
  17. Examples (using arrays declared in the examples of subclause 3.6.1): 
  18. --  Filter'First       =   0
--  Filter'Last        =  31
--  Filter'Length      =  32
--  Rectangle'Last(1)  =  20
--  Rectangle'Last(2)  =  30

Node:3.6.3, Next:, Previous:3.6.2, Up:3.6

String Types


Static Semantics
  1. A one-dimensional array type whose component type is a character type is called a string type.
  2. There are two predefined string types, String and Wide_String, each indexed by values of the predefined subtype Positive; these are declared in the visible part of package Standard: 
  3. subtype Positive is Integer range 1 .. Integer'Last;

  4. type String is array(Positive range <>) of Character;
type Wide_String is array(Positive range <>) of Wide_Character;

    NOTES

  5. (49) String literals, see 2.6, and 4.2, are defined for all string types. The concatenation operator & is predefined for string types, as for all nonlimited one-dimensional array types. The ordering operators <, <=, >, and >= are predefined for string types, as for all one-dimensional discrete array types; these ordering operators correspond to lexicographic order, see 4.5.2.

    Examples
  6. Examples of string objects: 
  7. Stars      : String(1 .. 120) := (1 .. 120 => '*' );
Question   : constant String  := "How many characters?";
--  Question'First = 1, Question'Last = 20
--  Question'Length = 20 (the number of characters)

  8. Ask_Twice  : String  := Question & Question;
--  constrained to (1..40)

Ninety_Six : constant Roman   := "XCVI";
--  see 3.5.2, and 3.6

Node:3.7, Next:, Previous:3.6.3, Up:3

Discriminants

  1. A composite type (other than an array type) can have discriminants, which parameterize the type. A known_discriminant_part specifies the discriminants of a composite type. A discriminant of an object is a component of the object, and is either of a discrete type or an access type. An unknown_discriminant_part in the declaration of a partial view of a type specifies that the discriminants of the type are unknown for the given view; all subtypes of such a partial view are indefinite subtypes.

    Syntax
  2. discriminant_part ::=
   unknown_discriminant_part | known_discriminant_part

  3. unknown_discriminant_part ::= (<>)

  4. known_discriminant_part ::=
   (discriminant_specification {; discriminant_specification})

  5. discriminant_specification ::=
     defining_identifier_list : subtype_mark
       [:= default_expression]
   | defining_identifier_list : access_definition
       [:= default_expression]

  6. default_expression ::= expression

    Name Resolution Rules
  7. The expected type for the default_expression of a discriminant_specification is that of the corresponding discriminant.

    Legality Rules
  8. A known_discriminant_part is only permitted in a declaration for a composite type that is not an array type (this includes generic formal types); a type declared with a known_discriminant_part is called a discriminated type, as is a type that inherits (known) discriminants.
  9. The subtype of a discriminant may be defined by a subtype_mark, in which case the subtype_mark shall denote a discrete or access subtype, or it may be defined by an access_definition (in which case the subtype_mark of the access_definition may denote any kind of subtype). A discriminant that is defined by an access_definition is called an access discriminant and is of an anonymous general access-to-variable type whose designated subtype is denoted by the subtype_mark of the access_definition.
  10. A discriminant_specification for an access discriminant shall appear only in the declaration for a task or protected type, or for a type with the reserved word limited in its (full) definition or in that of one of its ancestors. In addition to the places where Legality Rules normally apply, see 12.3, this rule applies also in the private part of an instance of a generic unit.
  11. Default_expressions shall be provided either for all or for none of the discriminants of a known_discriminant_part. No default_expressions are permitted in a known_discriminant_part in a declaration of a tagged type or a generic formal type.
  12. For a type defined by a derived_type_definition, if a known_discriminant_part is provided in its declaration, then:
    1. The parent subtype shall be constrained;
    2. If the parent type is not a tagged type, then each discriminant of the derived type shall be used in the constraint defining the parent subtype;
    3. If a discriminant is used in the constraint defining the parent subtype, the subtype of the discriminant shall be statically compatible (see 4.9.1) with the subtype of the corresponding parent discriminant.
  1. The type of the default_expression, if any, for an access discriminant shall be convertible to the anonymous access type of the discriminant (see 4.6).

    Static Semantics
  2. A discriminant_specification declares a discriminant; the subtype_mark denotes its subtype unless it is an access discriminant, in which case the discriminant's subtype is the anonymous access-to-variable subtype defined by the access_definition.
  3. For a type defined by a derived_type_definition, each discriminant of the parent type is either inherited, constrained to equal some new discriminant of the derived type, or constrained to the value of an expression. When inherited or constrained to equal some new discriminant, the parent discriminant and the discriminant of the derived type are said to correspond. Two discriminants also correspond if there is some common discriminant to which they both correspond. A discriminant corresponds to itself as well. If a discriminant of a parent type is constrained to a specific value by a derived_type_definition, then that discriminant is said to be specified by that derived_type_definition.
  4. A constraint that appears within the definition of a discriminated type depends on a discriminant of the type if it names the discriminant as a bound or discriminant value. A component_definition depends on a discriminant if its constraint depends on the discriminant, or on a discriminant that corresponds to it.
  5. A component depends on a discriminant if:
    1. Its component_definition depends on the discriminant; or
    2. It is declared in a variant_part that is governed by the discriminant; or
    3. It is a component inherited as part of a derived_type_definition, and the constraint of the parent_subtype_indication depends on the discriminant; or
    4. It is a subcomponent of a component that depends on the discriminant.
  1. Each value of a discriminated type includes a value for each component of the type that does not depend on a discriminant; this includes the discriminants themselves. The values of discriminants determine which other component values are present in the value of the discriminated type.
  2. A type declared with a known_discriminant_part is said to have known discriminants; its first subtype is unconstrained. A type declared with an unknown_discriminant_part is said to have unknown discriminants. A type declared without a discriminant_part has no discriminants, unless it is a derived type; if derived, such a type has the same sort of discriminants (known, unknown, or none) as its parent (or ancestor) type. A tagged class-wide type also has unknown discriminants. Any subtype of a type with unknown discriminants is an unconstrained and indefinite subtype, see 3.2, and 3.3.

    Dynamic Semantics
  3. An access_definition is elaborated when the value of a corresponding access discriminant is defined, either by evaluation of its default_expression or by elaboration of a discriminant_constraint. The elaboration of an access_definition creates the anonymous access type. When the expression defining the access discriminant is evaluated, it is converted to this anonymous access type, see 4.6.

    NOTES

  4. (50) If a discriminated type has default_expressions for its discriminants, then unconstrained variables of the type are permitted, and the values of the discriminants can be changed by an assignment to such a variable. If defaults are not provided for the discriminants, then all variables of the type are constrained, either by explicit constraint or by their initial value; the values of the discriminants of such a variable cannot be changed after initialization.
  5. (51) The default_expression for a discriminant of a type is evaluated when an object of an unconstrained subtype of the type is created.
  6. (52) Assignment to a discriminant of an object (after its initialization) is not allowed, since the name of a discriminant is a constant; neither assignment_statements nor assignments inherent in passing as an in out or out parameter are allowed. Note however that the value of a discriminant can be changed by assigning to the enclosing object, presuming it is an unconstrained variable.
  7. (53) A discriminant that is of a named access type is not called an access discriminant; that term is used only for discriminants defined by an access_definition.

    Examples
  8. Examples of discriminated types: 
  9. type Buffer(Size : Buffer_Size := 100) is  --  see 3.5.4
   record
      Pos   : Buffer_Size := 0;
      Value : String(1 .. Size);
   end record;

  10. type Matrix_Rec(Rows, Columns : Integer) is
   record
      Mat : Matrix(1 .. Rows, 1 .. Columns);  --  see 3.6
   end record;

  11. type Square(Side : Integer) is new
  Matrix_Rec(Rows => Side, Columns => Side);

  12. type Double_Square(Number : Integer) is
   record
      Left  : Square(Number);
      Right : Square(Number);
   end record;

    type Item(Number : Positive) is
   record
      Content : Integer;
      --  no component depends on the discriminant
   end record;

Node:3.7.1, Next:, Previous:3.7, Up:3.7

Discriminant Constraints

  1. A discriminant_constraint specifies the values of the discriminants for a given discriminated type.

    Syntax
  2. discriminant_constraint ::=
   (discriminant_association {, discriminant_association})

  3. discriminant_association ::=
   [discriminant_selector_name
     {| discriminant_selector_name} =>] expression
    1. A discriminant_association is said to be named if it has one or more discriminant_selector_names; it is otherwise said to be positional. In a discriminant_constraint, any positional associations shall precede any named associations.

Name Resolution Rules
  1. Each selector_name of a named discriminant_association shall resolve to denote a discriminant of the subtype being constrained; the discriminants so named are the associated discriminants of the named association. For a positional association, the associated discriminant is the one whose discriminant_specification occurred in the corresponding position in the known_discriminant_part that defined the discriminants of the subtype being constrained.
  2. The expected type for the expression in a discriminant_association is that of the associated discriminant(s).

    Legality Rules
  3. A discriminant_constraint is only allowed in a subtype_indication whose subtype_mark denotes either an unconstrained discriminated subtype, or an unconstrained access subtype whose designated subtype is an unconstrained discriminated subtype.
  4. A named discriminant_association with more than one selector_name is allowed only if the named discriminants are all of the same type. A discriminant_constraint shall provide exactly one value for each discriminant of the subtype being constrained.
  5. The expression associated with an access discriminant shall be of a type convertible to the anonymous access type.

    Dynamic Semantics
  6. A discriminant_constraint is compatible with an unconstrained discriminated subtype if each discriminant value belongs to the subtype of the corresponding discriminant.
  7. A composite value satisfies a discriminant constraint if and only if each discriminant of the composite value has the value imposed by the discriminant constraint.
  8. For the elaboration of a discriminant_constraint, the expressions in the discriminant_associations are evaluated in an arbitrary order and converted to the type of the associated discriminant (which might raise Constraint_Error - see 4.6.); the expression of a named association is evaluated (and converted) once for each associated discriminant. The result of each evaluation and conversion is the value imposed by the constraint for the associated discriminant.

    NOTES

  9. (54) The rules of the language ensure that a discriminant of an object always has a value, either from explicit or implicit initialization.

    Examples
  10. Examples (using types declared above in clause 3.7): 
  11. Large   : Buffer(200);  --  constrained, always 200 characters
                        --   (explicit discriminant value)
Message : Buffer;       --  unconstrained, initially 100 characters
                        --   (default discriminant value)
Basis   : Square(5);    --  constrained, always 5 by 5
Illegal : Square;       --  illegal, a Square has to be constrained

Node:3.7.2, Next:, Previous:3.7.1, Up:3.7

Operations of Discriminated Types

  1. If a discriminated type has default_expressions for its discriminants, then unconstrained variables of the type are permitted, and the discriminants of such a variable can be changed by assignment to the variable. For a formal parameter of such a type, an attribute is provided to determine whether the corresponding actual parameter is constrained or unconstrained.

    Static Semantics
  2. For a prefix A that is of a discriminated type (after any implicit dereference), the following attribute is defined:
  3. A'Constrained 
    Yields the value True if A denotes a constant, a value, or a
constrained variable, and False otherwise.

    Erroneous Execution
  4. The execution of a construct is erroneous if the construct has a constituent that is a name denoting a subcomponent that depends on discriminants, and the value of any of these discriminants is changed by this execution between evaluating the name and the last use (within this execution) of the subcomponent denoted by the name.

Node:3.8, Next:, Previous:3.7.2, Up:3

Record Types

  1. A record object is a composite object consisting of named components. The value of a record object is a composite value consisting of the values of the components.

    Syntax
  2. record_type_definition ::=
   [[abstract] tagged] [limited] record_definition

  3. record_definition ::=
     record
        component_list
     end record
   | null record

  4. component_list ::=
     component_item {component_item}
   | {component_item} variant_part
   |  null;

  5. component_item ::= component_declaration | representation_clause

  6. component_declaration ::=
   defining_identifier_list : component_definition
     [:= default_expression];

    Name Resolution Rules
  7. The expected type for the default_expression, if any, in a component_declaration is the type of the component.

    Legality Rules
  8. A default_expression is not permitted if the component is of a limited type.
  9. Each component_declaration declares a component of the record type. Besides components declared by component_declarations, the components of a record type include any components declared by discriminant_specifications of the record type declaration. The identifiers of all components of a record type shall be distinct.
  10. Within a type_declaration, a name that denotes a component, protected subprogram, or entry of the type is allowed only in the following cases:
    1. A name that denotes any component, protected subprogram, or entry is allowed within a representation item that occurs within the declaration of the composite type.
    2. A name that denotes a noninherited discriminant is allowed within the declaration of the type, but not within the discriminant_part. If the discriminant is used to define the constraint of a component, the bounds of an entry family, or the constraint of the parent subtype in a derived_type_definition then its name shall appear alone as a direct_name (not as part of a larger expression or expanded name). A discriminant shall not be used to define the constraint of a scalar component.
  1. If the name of the current instance of a type, see 8.6, is used to define the constraint of a component, then it shall appear as a direct_name that is the prefix of an attribute_reference whose result is of an access type, and the attribute_reference shall appear alone.

    Static Semantics
  2. The component_definition of a component_declaration defines the (nominal) subtype of the component. If the reserved word aliased appears in the component_definition, then the component is aliased, see 3.10.
  3. If the component_list of a record type is defined by the reserved word null and there are no discriminants, then the record type has no components and all records of the type are null records. A record_definition of null record is equivalent to record null; end record.

    Dynamic Semantics
  4. The elaboration of a record_type_definition creates the record type and its first subtype, and consists of the elaboration of the record_definition. The elaboration of a record_definition consists of the elaboration of its component_list, if any.
  5. The elaboration of a component_list consists of the elaboration of the component_items and variant_part, if any, in the order in which they appear. The elaboration of a component_declaration consists of the elaboration of the component_definition.
  6. Within the definition of a composite type, if a component_definition or discrete_subtype_definition, see 9.5.2, includes a name that denotes a discriminant of the type, or that is an attribute_reference whose prefix denotes the current instance of the type, the expression containing the name is called a per-object expression, and the constraint being defined is called a per-object constraint. For the elaboration of a component_definition of a component_declaration, if the constraint of the subtype_indication is not a per-object constraint, then the subtype_indication is elaborated. On the other hand, if the constraint is a per-object constraint, then the elaboration consists of the evaluation of any included expression that is not part of a per-object expression.

    NOTES

  7. (55) A component_declaration with several identifiers is equivalent to a sequence of single component_declarations, as explained in 3.3.1.
  8. (56) The default_expression of a record component is only evaluated upon the creation of a default-initialized object of the record type (presuming the object has the component, if it is in a variant_part - see 3.3.1).
  9. (57) The subtype defined by a component_definition, see 3.6, has to be a definite subtype.
  10. (58) If a record type does not have a variant_part, then the same components are present in all values of the type.
  11. (59) A record type is limited if it has the reserved word limited in its definition, or if any of its components are limited, see 7.5.
  12. (60) The predefined operations of a record type include membership tests, qualification, and explicit conversion. If the record type is nonlimited, they also include assignment and the predefined equality operators.
  13. (61) A component of a record can be named with a selected_component. A value of a record can be specified with a record_aggregate, unless the record type is limited.

    Examples
  14. Examples of record type declarations: 
  15. type Date is
   record
      Day   : Integer range 1 .. 31;
      Month : Month_Name;
      Year  : Integer range 0 .. 4000;
   end record;

  16. type Complex is
   record
      Re : Real := 0.0;
      Im : Real := 0.0;
   end record;
  17. Examples of record variables: 
  18. Tomorrow, Yesterday : Date;
A, B, C : Complex;

  19. -- both components of A, B, and C are implicitly initialized to zero

Node:3.8.1, Next:, Previous:3.8, Up:3.8

Variant Parts and Discrete Choices

  1. A record type with a variant_part specifies alternative lists of components. Each variant defines the components for the value or values of the discriminant covered by its discrete_choice_list.

    Syntax
  2. variant_part ::=
   case discriminant_direct_name is
      variant
      {variant}
   end case;

  3. variant ::=
   when discrete_choice_list =>
      component_list

  4. discrete_choice_list ::= discrete_choice {| discrete_choice}

  5. discrete_choice ::= expression | discrete_range | others

    Name Resolution Rules
  6. The discriminant_direct_name shall resolve to denote a discriminant (called the discriminant of the variant_part) specified in the known_discriminant_part of the full_type_declaration that contains the variant_part. The expected type for each discrete_choice in a variant is the type of the discriminant of the variant_part.

    Legality Rules
  7. The discriminant of the variant_part shall be of a discrete type.
  8. The expressions and discrete_ranges given as discrete_choices in a variant_part shall be static. The discrete_choice others shall appear alone in a discrete_choice_list, and such a discrete_choice_list, if it appears, shall be the last one in the enclosing construct.
  9. A discrete_choice is defined to cover a value in the following cases:
    1. A discrete_choice that is an expression covers a value if the value equals the value of the expression converted to the expected type.
    2. A discrete_choice that is a discrete_range covers all values (possibly none) that belong to the range.
    3. The discrete_choice others covers all values of its expected type that are not covered by previous discrete_choice_lists of the same construct.
  1. A discrete_choice_list covers a value if one of its discrete_choices covers the value.
  2. The possible values of the discriminant of a variant_part shall be covered as follows:
    1. If the discriminant is of a static constrained scalar subtype, then each non-others discrete_choice shall cover only values in that subtype, and each value of that subtype shall be covered by some discrete_choice (either explicitly or by others);
    2. If the type of the discriminant is a descendant of a generic formal scalar type then the variant_part shall have an others discrete_choice;
    3. Otherwise, each value of the base range of the type of the discriminant shall be covered (either explicitly or by others).
  1. Two distinct discrete_choices of a variant_part shall not cover the same value.

    Static Semantics
  2. If the component_list of a variant is specified by null, the variant has no components.
  3. The discriminant of a variant_part is said to govern the variant_part and its variants. In addition, the discriminant of a derived type governs a variant_part and its variants if it corresponds, see 3.7, to the discriminant of the variant_part.

    Dynamic Semantics
  4. A record value contains the values of the components of a particular variant only if the value of the discriminant governing the variant is covered by the discrete_choice_list of the variant. This rule applies in turn to any further variant that is, itself, included in the component_list of the given variant.
  5. The elaboration of a variant_part consists of the elaboration of the component_list of each variant in the order in which they appear.

    Examples
  6. Example of record type with a variant part: 
  7. type Device is (Printer, Disk, Drum);
type State  is (Open, Closed);

  8. type Peripheral(Unit : Device := Disk) is
   record
      Status : State;
      case Unit is
         when Printer =>
            Line_Count : Integer range 1 .. Page_Size;
         when others =>
            Cylinder   : Cylinder_Index;
            Track      : Track_Number;
         end case;
      end record;
  9. Examples of record subtypes: 
  10. subtype Drum_Unit is Peripheral(Drum);
subtype Disk_Unit is Peripheral(Disk);
  11. Examples of constrained record variables: 
  12. Writer   : Peripheral(Unit  => Printer);
Archive  : Disk_Unit;

Node:3.9, Next:, Previous:3.8.1, Up:3

Tagged Types and Type Extensions

  1. Tagged types and type extensions support object-oriented programming, based on inheritance with extension and run-time polymorphism via dispatching operations.

    Static Semantics
  2. A record type or private type that has the reserved word tagged in its declaration is called a tagged type. When deriving from a tagged type, additional components may be defined. As for any derived type, additional primitive subprograms may be defined, and inherited primitive subprograms may be overridden. The derived type is called an extension of the ancestor type, or simply a type extension. Every type extension is also a tagged type, and is either a record extension or a private extension of some other tagged type. A record extension is defined by a derived_type_definition with a record_extension_part. A private extension, which is a partial view of a record extension, can be declared in the visible part of a package, see 7.3, or in a generic formal part, see 12.5.1.
  3. An object of a tagged type has an associated (run-time) tag that identifies the specific tagged type used to create the object originally. The tag of an operand of a class-wide tagged type T'Class controls which subprogram body is to be executed when a primitive subprogram of type T is applied to the operand, see 3.9.2, using a tag to control which body to execute is called dispatching.
  4. The tag of a specific tagged type identifies the full_type_declaration of the type. If a declaration for a tagged type occurs within a generic_package_declaration, then the corresponding type declarations in distinct instances of the generic package are associated with distinct tags. For a tagged type that is local to a generic package body, the language does not specify whether repeated instantiations of the generic body result in distinct tags.
  5. The following language-defined library package exists: 
  6. package Ada.Tags is
    type Tag is private;

  7.     function Expanded_Name(T : Tag) return String;
    function External_Tag(T : Tag) return String;
    function Internal_Tag(External : String) return Tag;

  8.     Tag_Error : exception;

  9. private
   ... -- not specified by the language
end Ada.Tags;
  10. The function Expanded_Name returns the full expanded name of the first subtype of the specific type identified by the tag, in upper case, starting with a root library unit. The result is implementation defined if the type is declared within an unnamed block_statement.
  11. The function External_Tag returns a string to be used in an external representation for the given tag. The call External_Tag(S'Tag) is equivalent to the attribute_reference S'External_Tag, see 13.3.
  12. The function Internal_Tag returns the tag that corresponds to the given external tag, or raises Tag_Error if the given string is not the external tag for any specific type of the partition.
  13. For every subtype S of a tagged type T (specific or class-wide), the following attributes are defined:
  14. S'Class 
    S'Class denotes a subtype of the class-wide type (called
T'Class in this International Standard) for the class rooted
at T (or if S already denotes a class-wide subtype, then
S'Class is the same as S).
    1. S'Class is unconstrained. However, if S is constrained, then the values of S'Class are only those that when converted to the type T belong to S.
  1. S'Tag 
    S'Tag denotes the tag of the type T (or if T is class-wide,
the tag of the root type of the corresponding class). The
value of this attribute is of type Tag.
  2. Given a prefix X that is of a class-wide tagged type (after any implicit dereference), the following attribute is defined:
  3. X'Tag 
    X'Tag denotes the tag of X. The value of this attribute is of
type Tag.

    Dynamic Semantics
  4. The tag associated with an object of a tagged type is determined as follows:
    1. The tag of a stand-alone object, a component, or an aggregate of a specific tagged type T identifies T.
    2. The tag of an object created by an allocator for an access type with a specific designated tagged type T, identifies T.
    3. The tag of an object of a class-wide tagged type is that of its initialization expression.
    4. The tag of the result returned by a function whose result type is a specific tagged type T identifies T.
    5. The tag of the result returned by a function with a class-wide result type is that of the return expression.
  1. The tag is preserved by type conversion and by parameter passing. The tag of a value is the tag of the associated object, see 6.2.

    Implementation Permissions
  2. The implementation of the functions in Ada.Tags may raise Tag_Error if no specific type corresponding to the tag passed as a parameter exists in the partition at the time the function is called.

    NOTES

  3. (62) A type declared with the reserved word tagged should normally be declared in a package_specification, so that new primitive subprograms can be declared for it.
  4. (63) Once an object has been created, its tag never changes.
  5. (64) Class-wide types are defined to have unknown discriminants (see 3.7). This means that objects of a class-wide type have to be explicitly initialized (whether created by an object_declaration or an allocator), and that aggregates have to be explicitly qualified with a specific type when their expected type is class-wide.
  6. (65) If S denotes an untagged private type whose full type is tagged, then S'Class is also allowed before the full type definition, but only in the private part of the package in which the type is declared (see 7.3.1). Similarly, the Class attribute is defined for incomplete types whose full type is tagged, but only within the library unit in which the incomplete type is declared, see 3.10.1.

    Examples
  7. Examples of tagged record types: 
  8. type Point is tagged
  record
    X, Y : Real := 0.0;
  end record;

  9. type Expression is tagged null record;
  -- Components will be added by each extension

Node:3.9.1, Next:, Previous:3.9, Up:3.9

Type Extensions

  1. Every type extension is a tagged type, and is either a record extension or a private extension of some other tagged type.

    Syntax
  2. record_extension_part ::= with record_definition

    Legality Rules
  3. The parent type of a record extension shall not be a class-wide type. If the parent type is nonlimited, then each of the components of the record_extension_part shall be nonlimited. The accessibility level (see 3.10.2) of a record extension shall not be statically deeper than that of its parent type. In addition to the places where Legality Rules normally apply, see 12.3, these rules apply also in the private part of an instance of a generic unit.
  4. A type extension shall not be declared in a generic body if the parent type is declared outside that body.

    Dynamic Semantics
  5. The elaboration of a record_extension_part consists of the elaboration of the record_definition.

    NOTES

  6. (66) The term "type extension" refers to a type as a whole. The term "extension part" refers to the piece of text that defines the additional components (if any) the type extension has relative to its specified ancestor type.
  7. (67) The accessibility rules imply that a tagged type declared in a library package_specification can be extended only at library level or as a generic formal. When the extension is declared immediately within a package_body, primitive subprograms are inherited and are overridable, but new primitive subprograms cannot be added.
  8. (68) A name that denotes a component (including a discriminant) of the parent type is not allowed within the record_extension_part. Similarly, a name that denotes a component defined within the record_extension_part is not allowed within the record_extension_part. It is permissible to use a name that denotes a discriminant of the record extension, providing there is a new known_discriminant_part in the enclosing type declaration. (The full rule is given in 3.8.)
  9. (69) Each visible component of a record extension has to have a unique name, whether the component is (visibly) inherited from the parent type or declared in the record_extension_part, see 8.3.

    Examples
  10. Examples of record extensions (of types defined above in 3.9.): 
  11. type Painted_Point is new Point with
  record
    Paint : Color := White;
  end record;
    -- Components X and Y are inherited

  12. Origin : constant Painted_Point := (X | Y => 0.0, Paint => Black);

  13. type Literal is new Expression with
  record                 -- a leaf in an Expression tree
    Value : Real;
  end record;

  14. type Expr_Ptr is access all Expression'Class;
--  see 3.10

  15. type Binary_Operation is new Expression with
  record       -- an internal node in an Expression tree
    Left, Right : Expr_Ptr;
  end record;

  16. type Addition is new Binary_Operation with null record;
type Subtraction is new Binary_Operation with null record;
-- No additional components needed for these extensions

  17. Tree : Expr_Ptr :=  -- A tree representation of ``5.0 + (13.0-7.0)''
   new Addition'(
      Left  => new Literal'(Value => 5.0),
      Right => new Subtraction'(
         Left  => new Literal'(Value => 13.0),
         Right => new Literal'(Value => 7.0)));

Node:3.9.2, Next:, Previous:3.9.1, Up:3.9

Dispatching Operations of Tagged Types

  1. The primitive subprograms of a tagged type are called dispatching operations. A dispatching operation can be called using a statically determined controlling tag, in which case the body to be executed is determined at compile time. Alternatively, the controlling tag can be dynamically determined, in which case the call dispatches to a body that is determined at run time; such a call is termed a dispatching call. As explained below, the properties of the operands and the context of a particular call on a dispatching operation determine how the controlling tag is determined, and hence whether or not the call is a dispatching call. Run-time polymorphism is achieved when a dispatching operation is called by a dispatching call.

    Static Semantics
  2. A call on a dispatching operation is a call whose name or prefix denotes the declaration of a primitive subprogram of a tagged type, that is, a dispatching operation. A controlling operand in a call on a dispatching operation of a tagged type T is one whose corresponding formal parameter is of type T or is of an anonymous access type with designated type T; the corresponding formal parameter is called a controlling formal parameter. If the controlling formal parameter is an access parameter, the controlling operand is the object designated by the actual parameter, rather than the actual parameter itself. If the call is to a (primitive) function with result type T, then the call has a controlling result - the context of the call can control the dispatching.
  3. A name or expression of a tagged type is either statically tagged, dynamically tagged, or tag indeterminate, according to whether, when used as a controlling operand, the tag that controls dispatching is determined statically by the operand's (specific) type, dynamically by its tag at run time, or from context. A qualified_expression or parenthesized expression is statically, dynamically, or indeterminately tagged according to its operand. For other kinds of names and expressions, this is determined as follows:
    1. The name or expression is statically tagged if it is of a specific tagged type and, if it is a call with a controlling result, it has at least one statically tagged controlling operand;
    2. The name or expression is dynamically tagged if it is of a class-wide type, or it is a call with a controlling result and at least one dynamically tagged controlling operand;
    3. The name or expression is tag indeterminate if it is a call with a controlling result, all of whose controlling operands (if any) are tag indeterminate.
  1. A type_conversion is statically or dynamically tagged according to whether the type determined by the subtype_mark is specific or class-wide, respectively. For a controlling operand that is designated by an actual parameter, the controlling operand is statically or dynamically tagged according to whether the designated type of the actual parameter is specific or class-wide, respectively.

    Legality Rules
  2. A call on a dispatching operation shall not have both dynamically tagged and statically tagged controlling operands.
  3. If the expected type for an expression or name is some specific tagged type, then the expression or name shall not be dynamically tagged unless it is a controlling operand in a call on a dispatching operation. Similarly, if the expected type for an expression is an anonymous access-to-specific tagged type, then the expression shall not be of an access-to-class-wide type unless it designates a controlling operand in a call on a dispatching operation.
  4. In the declaration of a dispatching operation of a tagged type, everywhere a subtype of the tagged type appears as a subtype of the profile, see 6.1, it shall statically match the first subtype of the tagged type. If the dispatching operation overrides an inherited subprogram, it shall be subtype conformant with the inherited subprogram. A dispatching operation shall not be of convention Intrinsic. If a dispatching operation overrides the predefined equals operator, then it shall be of convention Ada (either explicitly or by default - see 6.3.1.).
  5. The default_expression for a controlling formal parameter of a dispatching operation shall be tag indeterminate. A controlling formal parameter that is an access parameter shall not have a default_expression.
  6. A given subprogram shall not be a dispatching operation of two or more distinct tagged types.
  7. The explicit declaration of a primitive subprogram of a tagged type shall occur before the type is frozen, see 13.14. For example, new dispatching operations cannot be added after objects or values of the type exist, nor after deriving a record extension from it, nor after a body.

    Dynamic Semantics
  8. For the execution of a call on a dispatching operation of a type T, the controlling tag value determines which subprogram body is executed. The controlling tag value is defined as follows:
    1. If one or more controlling operands are statically tagged, then the controlling tag value is statically determined to be the tag of T.
    2. If one or more controlling operands are dynamically tagged, then the controlling tag value is not statically determined, but is rather determined by the tags of the controlling operands. If there is more than one dynamically tagged controlling operand, a check is made that they all have the same tag. If this check fails, Constraint_Error is raised unless the call is a function_call whose name denotes the declaration of an equality operator (predefined or user defined) that returns Boolean, in which case the result of the call is defined to indicate inequality, and no subprogram_body is executed. This check is performed prior to evaluating any tag-indeterminate controlling operands.
    3. If all of the controlling operands are tag-indeterminate, then:
      1. If the call has a controlling result and is itself a (possibly parenthesized or qualified) controlling operand of an enclosing call on a dispatching operation of type T, then its controlling tag value is determined by the controlling tag value of this enclosing call;
      2. Otherwise, the controlling tag value is statically determined to be the tag of type T.
  1. For the execution of a call on a dispatching operation, the body executed is the one for the corresponding primitive subprogram of the specific type identified by the controlling tag value. The body for an explicitly declared dispatching operation is the corresponding explicit body for the subprogram. The body for an implicitly declared dispatching operation that is overridden is the body for the overriding subprogram, even if the overriding occurs in a private part. The body for an inherited dispatching operation that is not overridden is the body of the corresponding subprogram of the parent or ancestor type.

    NOTES

  2. (70) The body to be executed for a call on a dispatching operation is determined by the tag; it does not matter whether that tag is determined statically or dynamically, and it does not matter whether the subprogram's declaration is visible at the place of the call.
  3. (71) This subclause covers calls on primitive subprograms of a tagged type. Rules for tagged type membership tests are described in 4.5.2. Controlling tag determination for an assignment_statement is described in 5.2.
  4. (72) A dispatching call can dispatch to a body whose declaration is not visible at the place of the call.
  5. (73) A call through an access-to-subprogram value is never a dispatching call, even if the access value designates a dispatching operation. Similarly a call whose prefix denotes a subprogram_renaming_declaration cannot be a dispatching call unless the renaming itself is the declaration of a primitive subprogram.

Node:3.9.3, Next:, Previous:3.9.2, Up:3.9

Abstract Types and Subprograms

  1. An abstract type is a tagged type intended for use as a parent type for type extensions, but which is not allowed to have objects of its own. An abstract subprogram is a subprogram that has no body, but is intended to be overridden at some point when inherited. Because objects of an abstract type cannot be created, a dispatching call to an abstract subprogram always dispatches to some overriding body.

    Legality Rules
  2. An abstract type is a specific type that has the reserved word abstract in its declaration. Only a tagged type is allowed to be declared abstract.
  3. A subprogram declared by an abstract_subprogram_declaration, see 6.1, is an abstract subprogram. If it is a primitive subprogram of a tagged type, then the tagged type shall be abstract.
  4. For a derived type, if the parent or ancestor type has an abstract primitive subprogram, or a primitive function with a controlling result, then:
    1. If the derived type is abstract or untagged, the inherited subprogram is abstract.
    2. Otherwise, the subprogram shall be overridden with a nonabstract subprogram; for a type declared in the visible part of a package, the overriding may be either in the visible or the private part. However, if the type is a generic formal type, the subprogram need not be overridden for the formal type itself; a nonabstract version will necessarily be provided by the actual type.
  1. A call on an abstract subprogram shall be a dispatching call; nondispatching calls to an abstract subprogram are not allowed.
  2. The type of an aggregate, or of an object created by an object_declaration or an allocator, or a generic formal object of mode in, shall not be abstract. The type of the target of an assignment operation, see 5.2, shall not be abstract. The type of a component shall not be abstract. If the result type of a function is abstract, then the function shall be abstract.
  3. If a partial view is not abstract, the corresponding full view shall not be abstract. If a generic formal type is abstract, then for each primitive subprogram of the formal that is not abstract, the corresponding primitive subprogram of the actual shall not be abstract.
  4. For an abstract type declared in a visible part, an abstract primitive subprogram shall not be declared in the private part, unless it is overriding an abstract subprogram implicitly declared in the visible part. For a tagged type declared in a visible part, a primitive function with a controlling result shall not be declared in the private part, unless it is overriding a function implicitly declared in the visible part.
  5. A generic actual subprogram shall not be an abstract subprogram. The prefix of an attribute_reference for the Access, Unchecked_Access, or Address attributes shall not denote an abstract subprogram.

    NOTES

  6. (74) Abstractness is not inherited; to declare an abstract type, the reserved word abstract has to be used in the declaration of the type extension.
  7. (75) A class-wide type is never abstract. Even if a class is rooted at an abstract type, the class-wide type for the class is not abstract, and an object of the class-wide type can be created; the tag of such an object will identify some nonabstract type in the class.

    Examples
  8. Example of an abstract type representing a set of natural numbers: 
  9. package Sets is
    subtype Element_Type is Natural;
    type Set is abstract tagged null record;
    function Empty return Set is abstract;
    function Union(Left, Right : Set) return Set is abstract;
    function Intersection(Left, Right : Set) return Set is abstract;
    function Unit_Set(Element : Element_Type) return Set is abstract;
    procedure Take
      (Element : out Element_Type;
       From : in out Set) is abstract;
end Sets;

    NOTES

  10. (76) Notes on the example: Given the above abstract type, one could then derive various (nonabstract) extensions of the type, representing alternative implementations of a set. One might use a bit vector, but impose an upper bound on the largest element representable, while another might use a hash table, trading off space for flexibility.

Node:3.10, Next:, Previous:3.9.3, Up:3

Access Types

  1. A value of an access type (an access value) provides indirect access to the object or subprogram it designates. Depending on its type, an access value can designate either subprograms, objects created by allocators (see 4.8) or more generally aliased objects of an appropriate type.

    Syntax
  2. access_type_definition ::=
     access_to_object_definition
   | access_to_subprogram_definition

  3. access_to_object_definition ::=
    access [general_access_modifier] subtype_indication

  4. general_access_modifier ::= all | constant

  5. access_to_subprogram_definition ::=
     access [protected] procedure parameter_profile
   | access [protected] function  parameter_and_result_profile

  6. access_definition ::= access subtype_mark

    Static Semantics
  7. There are two kinds of access types, access-to-object types, whose values designate objects, and access-to-subprogram types, whose values designate subprograms. Associated with an access-to-object type is a storage pool; several access types may share the same storage pool. A storage pool is an area of storage used to hold dynamically allocated objects (called pool elements) created by allocators; storage pools are described further in "Storage Management".
  8. Access-to-object types are further subdivided into pool-specific access types, whose values can designate only the elements of their associated storage pool, and general access types, whose values can designate the elements of any storage pool, as well as aliased objects created by declarations rather than allocators, and aliased subcomponents of other objects.
  9. A view of an object is defined to be aliased if it is defined by an object_declaration or component_definition with the reserved word aliased, or by a renaming of an aliased view. In addition, the dereference of an access-to-object value denotes an aliased view, as does a view conversion, see 4.6 of an aliased view. Finally, the current instance of a limited type, and a formal parameter or generic formal object of a tagged type are defined to be aliased. Aliased views are the ones that can be designated by an access value. If the view defined by an object_declaration is aliased, and the type of the object has discriminants, then the object is constrained; if its nominal subtype is unconstrained, then the object is constrained by its initial value. Similarly, if the object created by an allocator has discriminants, the object is constrained, either by the designated subtype, or by its initial value.
  10. An access_to_object_definition defines an access-to-object type and its first subtype; the subtype_indication defines the designated subtype of the access type. If a general_access_modifier appears, then the access type is a general access type. If the modifier is the reserved word constant, then the type is an access-to-constant type; a designated object cannot be updated through a value of such a type. If the modifier is the reserved word all, then the type is an access-to-variable type; a designated object can be both read and updated through a value of such a type. If no general_access_modifier appears in the access_to_object_definition, the access type is a pool-specific access-to-variable type.
  11. An access_to_subprogram_definition defines an access-to-subprogram type and its first subtype; the parameter_profile or parameter_and_result_profile defines the designated profile of the access type. There is a calling convention associated with the designated profile; only subprograms with this calling convention can be designated by values of the access type. By default, the calling convention is "protected" if the reserved word protected appears, and "Ada" otherwise. See Annex B for how to override this default.
  12. An access_definition defines an anonymous general access-to-variable type; the subtype_mark denotes its designated subtype. An access_definition is used in the specification of an access discriminant, see 3.7, or an access parameter, see 6.1.
  13. For each (named) access type, there is a literal null which has a null access value designating no entity at all. The null value of a named access type is the default initial value of the type. Other values of an access type are obtained by evaluating an attribute_reference for the Access or Unchecked_Access attribute of an aliased view of an object or non-intrinsic subprogram, or, in the case of a named access-to-object type, an allocator, which returns an access value designating a newly created object, see 3.10.2.
  14. All subtypes of an access-to-subprogram type are constrained. The first subtype of a type defined by an access_type_definition or an access_to_object_definition is unconstrained if the designated subtype is an unconstrained array or discriminated type; otherwise it is constrained.

    Dynamic Semantics
  15. A composite_constraint is compatible with an unconstrained access subtype if it is compatible with the designated subtype. An access value satisfies a composite_constraint of an access subtype if it equals the null value of its type or if it designates an object whose value satisfies the constraint.
  16. The elaboration of an access_type_definition creates the access type and its first subtype. For an access-to-object type, this elaboration includes the elaboration of the subtype_indication, which creates the designated subtype.
  17. The elaboration of an access_definition creates an anonymous general access-to-variable type (this happens as part of the initialization of an access parameter or access discriminant).

    NOTES

  18. (77) Access values are called "pointers" or "references" in some other languages.
  19. (78) Each access-to-object type has an associated storage pool; several access types can share the same pool. An object can be created in the storage pool of an access type by an allocator, see 4.8, for the access type. A storage pool (roughly) corresponds to what some other languages call a "heap.". See 13.11, for a discussion of pools.
  20. (79) Only index_constraints and discriminant_constraints can be applied to access types, see 3.6.1, and 3.7.1.

    Examples
  21. Examples of access-to-object types: 
  22. type Peripheral_Ref is access Peripheral;  --  see 3.8.1
type Binop_Ptr is access all Binary_Operation'Class;
-- general access-to-class-wide, see 3.9.1
  23. Example of an access subtype: 
  24. subtype Drum_Ref is Peripheral_Ref(Drum);  --  see 3.8.1
  25. Example of an access-to-subprogram type: 
  26. type Message_Procedure is access
  procedure (M : in String := "Error!");
procedure Default_Message_Procedure(M : in String);
Give_Message : Message_Procedure := Default_Message_Procedure'Access;
...
procedure Other_Procedure(M : in String);
...
Give_Message := Other_Procedure'Access;
...
Give_Message("File not found.");
-- call with parameter (.all is optional)
Give_Message.all;
-- call with no parameters

Node:3.10.1, Next:, Previous:3.10, Up:3.10

Incomplete Type Declarations

  1. There are no particular limitations on the designated type of an access type. In particular, the type of a component of the designated type can be another access type, or even the same access type. This permits mutually dependent and recursive access types. An incomplete_type_declaration can be used to introduce a type to be used as a designated type, while deferring its full definition to a subsequent full_type_declaration.

    Syntax
  2. incomplete_type_declaration ::=
   type defining_identifier [discriminant_part];

    Legality Rules
  3. An incomplete_type_declaration requires a completion, which shall be a full_type_declaration. If the incomplete_type_declaration occurs immediately within either the visible part of a package_specification or a declarative_part, then the full_type_declaration shall occur later and immediately within this visible part or declarative_part. If the incomplete_type_declaration occurs immediately within the private part of a given package_specification, then the full_type_declaration shall occur later and immediately within either the private part itself, or the declarative_part of the corresponding package_body.
  4. If an incomplete_type_declaration has a known_discriminant_part, then a full_type_declaration that completes it shall have a fully conforming (explicit) known_discriminant_part, see 6.3.1. If an incomplete_type_declaration has no discriminant_part (or an unknown_discriminant_part), then a corresponding full_type_declaration is nevertheless allowed to have discriminants, either explicitly, or inherited via derivation.
  5. The only allowed uses of a name that denotes an incomplete_type_declaration are as follows:
    1. as the subtype_mark in the subtype_indication of an access_to_object_definition; the only form of constraint allowed in this subtype_indication is a discriminant_constraint;
    2. as the subtype_mark defining the subtype of a parameter or result of an access_to_subprogram_definition;
    3. as the subtype_mark in an access_definition;
    4. as the prefix of an attribute_reference whose attribute_designator is Class; such an attribute_reference is similarly restricted to the uses allowed here; when used in this way, the corresponding full_type_declaration shall declare a tagged type, and the attribute_reference shall occur in the same library unit as the incomplete_type_declaration.
  1. A dereference (whether implicit or explicit - see 4.1.) shall not be of an incomplete type.

    Static Semantics
  2. An incomplete_type_declaration declares an incomplete type and its first subtype; the first subtype is unconstrained if a known_discriminant_part appears.

    Dynamic Semantics
  3. The elaboration of an incomplete_type_declaration has no effect.

    NOTES

  4. (80) Within a declarative_part, an incomplete_type_declaration and a corresponding full_type_declaration cannot be separated by an intervening body. This is because a type has to be completely defined before it is frozen, and a body freezes all types declared prior to it in the same declarative_part, see 13.14.

    Examples
  5. Example of a recursive type: 
  6. type Cell;  --  incomplete type declaration
type Link is access Cell;

  7. type Cell is
   record
      Value  : Integer;
      Succ   : Link;
      Pred   : Link;
   end record;

  8. Head   : Link  := new Cell'(0, null, null);
Next   : Link  := Head.Succ;
  9. Examples of mutually dependent access types: 
  10. type Person(<>);    -- incomplete type declaration
type Car;           -- incomplete type declaration

  11. type Person_Name is access Person;
type Car_Name    is access all Car;

  12. type Car is
   record
      Number  : Integer;
      Owner   : Person_Name;
   end record;

  13. type Person(Sex : Gender) is
   record
      Name     : String(1 .. 20);
      Birth    : Date;
      Age      : Integer range 0 .. 130;
      Vehicle  : Car_Name;
      case Sex is
         when M => Wife    : Person_Name(Sex => F);
         when F => Husband : Person_Name(Sex => M);
      end case;
   end record;

  14. My_Car, Your_Car, Next_Car : Car_Name := new Car;
--  see 4.8
George : Person_Name := new Person(M);
   ...
George.Vehicle := Your_Car;

Node:3.10.2, Next:, Previous:3.10.1, Up:3.10

Operations of Access Types

  1. The attribute Access is used to create access values designating aliased objects and non-intrinsic subprograms. The "accessibility" rules prevent dangling references (in the absence of uses of certain unchecked features - see 13.).

    Name Resolution Rules
  2. For an attribute_reference with attribute_designator Access (or Unchecked_Access - see 13.10.), the expected type shall be a single access type; the prefix of such an attribute_reference is never interpreted as an implicit_dereference. If the expected type is an access-to-subprogram type, then the expected profile of the prefix is the designated profile of the access type.

    Static Semantics
  3. The accessibility rules, which prevent dangling references, are written in terms of accessibility levels, which reflect the run-time nesting of masters. As explained in 7.6.1, a master is the execution of a task_body, a block_statement, a subprogram_body, an entry_body, or an accept_statement. An accessibility level is deeper than another if it is more deeply nested at run time. For example, an object declared local to a called subprogram has a deeper accessibility level than an object declared local to the calling subprogram. The accessibility rules for access types require that the accessibility level of an object designated by an access value be no deeper than that of the access type. This ensures that the object will live at least as long as the access type, which in turn ensures that the access value cannot later designate an object that no longer exists. The Unchecked_Access attribute may be used to circumvent the accessibility rules.
  4. A given accessibility level is said to be statically deeper than another if the given level is known at compile time (as defined below) to be deeper than the other for all possible executions. In most cases, accessibility is enforced at compile time by Legality Rules. Run-time accessibility checks are also used, since the Legality Rules do not cover certain cases involving access parameters and generic packages.
  5. Each master, and each entity and view created by it, has an accessibility level:
    1. The accessibility level of a given master is deeper than that of each dynamically enclosing master, and deeper than that of each master upon which the task executing the given master directly depends, see 9.3.
    2. An entity or view created by a declaration has the same accessibility level as the innermost enclosing master, except in the cases of renaming and derived access types described below. A parameter of a master has the same accessibility level as the master.
    3. The accessibility level of a view of an object or subprogram defined by a renaming_declaration is the same as that of the renamed view.
    4. The accessibility level of a view conversion is the same as that of the operand.
    5. For a function whose result type is a return-by-reference type, the accessibility level of the result object is the same as that of the master that elaborated the function body. For any other function, the accessibility level of the result object is that of the execution of the called function.
    6. The accessibility level of a derived access type is the same as that of its ultimate ancestor.
    7. The accessibility level of the anonymous access type of an access discriminant is the same as that of the containing object or associated constrained subtype.
    8. The accessibility level of the anonymous access type of an access parameter is the same as that of the view designated by the actual. If the actual is an allocator, this is the accessibility level of the execution of the called subprogram.
    9. The accessibility level of an object created by an allocator is the same as that of the access type.
    10. The accessibility level of a view of an object or subprogram denoted by a dereference of an access value is the same as that of the access type.
    11. The accessibility level of a component, protected subprogram, or entry of (a view of) a composite object is the same as that of (the view of) the composite object.
  1. One accessibility level is defined to be statically deeper than another in the following cases:
    1. For a master that is statically nested within another master, the accessibility level of the inner master is statically deeper than that of the outer master.
    2. The statically deeper relationship does not apply to the accessibility level of the anonymous type of an access parameter; that is, such an accessibility level is not considered to be statically deeper, nor statically shallower, than any other.
    3. For determining whether one level is statically deeper than another when within a generic package body, the generic package is presumed to be instantiated at the same level as where it was declared; run-time checks are needed in the case of more deeply nested instantiations.
    4. For determining whether one level is statically deeper than another when within the declarative region of a type_declaration, the current instance of the type is presumed to be an object created at a deeper level than that of the type.
  1. The accessibility level of all library units is called the library level; a library-level declaration or entity is one whose accessibility level is the library level.
  2. The following attribute is defined for a prefix X that denotes an aliased view of an object:
  3. X'Access 
    X'Access yields an access value that designates the object
denoted by X. The type of X'Access is an access-to-object
type, as determined by the expected type. The expected type
shall be a general access type. X shall denote an aliased
view of an object, including possibly the current instance
(see 8.6) of a limited type within its definition, or a
formal parameter or generic formal object of a tagged type.
The view denoted by the prefix X shall satisfy the following
additional requirements, presuming the expected type for
X'Access is the general access type A:
      1. If A is an access-to-variable type, then the view shall be a variable; on the other hand, if A is an access-to-constant type, the view may be either a constant or a variable.
      2. The view shall not be a subcomponent that depends on discriminants of a variable whose nominal subtype is unconstrained, unless this subtype is indefinite, or the variable is aliased.
      3. If the designated type of A is tagged, then the type of the view shall be covered by the designated type; if A's designated type is not tagged, then the type of the view shall be the same, and either A's designated subtype shall statically match the nominal subtype of the view, or the designated subtype shall be discriminated and unconstrained;
      4. The accessibility level of the view shall not be statically deeper than that of the access type A. In addition to the places where Legality Rules normally apply, see 12.3, this rule applies also in the private part of an instance of a generic unit.
    1. A check is made that the accessibility level of X is not deeper than that of the access type A. If this check fails, Program_Error is raised.
    2. If the nominal subtype of X does not statically match the designated subtype of A, a view conversion of X to the designated subtype is evaluated (which might raise Constraint_Error - see 4.6.) and the value of X'Access designates that view.
  1. The following attribute is defined for a prefix P that denotes a subprogram:
  2. P'Access 
    P'Access yields an access value that designates the
subprogram denoted by P. The type of P'Access is an
access-to-subprogram type (S), as determined by the expected
type. The accessibility level of P shall not be statically
deeper than that of S. In addition to the places where
Legality Rules normally apply, see 12.3, this rule applies
also in the private part of an instance of a generic unit.
The profile of P shall be subtype-conformant with the
designated profile of S, and shall not be Intrinsic. If
the subprogram denoted by P is declared within a generic
body, S shall be declared within the generic body.

    NOTES

  3. (81) The Unchecked_Access attribute yields the same result as the Access attribute for objects, but has fewer restrictions, see 13.10. There are other predefined operations that yield access values: an allocator can be used to create an object, and return an access value that designates it, see 4.8, evaluating the literal null yields a null access value that designates no entity at all, see 4.2.
  4. (82) The predefined operations of an access type also include the assignment operation, qualification, and membership tests. Explicit conversion is allowed between general access types with matching designated subtypes; explicit conversion is allowed between access-to-subprogram types with subtype conformant profiles, see 4.6. Named access types have predefined equality operators; anonymous access types do not, see 4.5.2.
  5. (83) The object or subprogram designated by an access value can be named with a dereference, either an explicit_dereference or an implicit_dereference (see 4.1).
  6. (84) A call through the dereference of an access-to-subprogram value is never a dispatching call.
  7. (85) The accessibility rules imply that it is not possible to use the Access attribute to implement "downward closures" - that is, to pass a more-nested subprogram as a parameter to a less-nested subprogram, as might be desired for example for an iterator abstraction. Instead, downward closures can be implemented using generic formal subprograms (see 12.6). Note that Unchecked_Access is not allowed for subprograms.
  8. (86) Note that using an access-to-class-wide tagged type with a dispatching operation is a potentially more structured alternative to using an access-to-subprogram type.
  9. (87) An implementation may consider two access-to-subprogram values to be unequal, even though they designate the same subprogram. This might be because one points directly to the subprogram, while the other points to a special prologue that performs an Elaboration_Check and then jumps to the subprogram (see 4.5.2).

    Examples
  10. Example of use of the Access attribute: 
  11. Martha : Person_Name := new Person(F);  --  see 3.10.1
Cars   : array (1..2) of aliased Car;
   ...
Martha.Vehicle := Cars(1)'Access;
George.Vehicle := Cars(2)'Access;

Node:3.11, Next:, Previous:3.10.2, Up:3

Declarative Parts

  1. A declarative_part contains declarative_items (possibly none).

    Syntax
  2. declarative_part ::= {declarative_item}

  3. declarative_item ::= basic_declarative_item | body

  4. basic_declarative_item ::=
   basic_declaration | representation_clause | use_clause

  5. body ::= proper_body | body_stub

  6. proper_body ::=
   subprogram_body | package_body | task_body | protected_body

    Dynamic Semantics
  7. The elaboration of a declarative_part consists of the elaboration of the declarative_items, if any, in the order in which they are given in the declarative_part.
  8. An elaborable construct is in the elaborated state after the normal completion of its elaboration. Prior to that, it is not yet elaborated.
  9. For a construct that attempts to use a body, a check (Elaboration_Check) is performed, as follows:
    1. For a call to a (non-protected) subprogram that has an explicit body, a check is made that the subprogram_body is already elaborated. This check and the evaluations of any actual parameters of the call are done in an arbitrary order.
    2. For a call to a protected operation of a protected type (that has a body - no check is performed if a pragma Import applies to the protected type), a check is made that the protected_body is already elaborated. This check and the evaluations of any actual parameters of the call are done in an arbitrary order.
    3. For the activation of a task, a check is made by the activator that the task_body is already elaborated. If two or more tasks are being activated together, see 9.2, as the result of the elaboration of a declarative_part or the initialization for the object created by an allocator, this check is done for all of them before activating any of them.
    4. For the instantiation of a generic unit that has a body, a check is made that this body is already elaborated. This check and the evaluation of any explicit_generic_actual_parameters of the instantiation are done in an arbitrary order.
  1. The exception Program_Error is raised if any of these checks fails.

Node:3.11.1, Next:, Previous:3.11, Up:3.11

Completions of Declarations

  1. Declarations sometimes come in two parts. A declaration that requires a second part is said to require completion. The second part is called the completion of the declaration (and of the entity declared), and is either another declaration, a body, or a pragma.

    Name Resolution Rules
  2. A construct that can be a completion is interpreted as the completion of a prior declaration only if:
    1. The declaration and the completion occur immediately within the same declarative region;
    2. The defining name or defining_program_unit_name in the completion is the same as in the declaration, or in the case of a pragma, the pragma applies to the declaration;
    3. If the declaration is overloadable, then the completion either has a type-conformant profile, or is a pragma.

Legality Rules
  1. An implicit declaration shall not have a completion. For any explicit declaration that is specified to require completion, there shall be a corresponding explicit completion.
  2. At most one completion is allowed for a given declaration. Additional requirements on completions appear where each kind of completion is defined.
  3. A type is completely defined at a place that is after its full type definition (if it has one) and after all of its subcomponent types are completely defined. A type shall be completely defined before it is frozen, see 13.14, and 7.3.

    NOTES

  4. (88) Completions are in principle allowed for any kind of explicit declaration. However, for some kinds of declaration, the only allowed completion is a pragma Import, and implementations are not required to support pragma Import for every kind of entity.
  5. (89) There are rules that prevent premature uses of declarations that have a corresponding completion. The Elaboration_Checks (see 3.11) prevent such uses at run time for subprograms, protected operations, tasks, and generic units. The "Freezing Rules" (see 13.14) prevent, at compile time, premature uses of other entities such as private types and deferred constants.

Node:4, Next:, Previous:3.11.1, Up:Top

Names and Expressions

  1. The rules applicable to the different forms of name and expression, and to their evaluation, are given in this section.

Node:4.1, Next:, Previous:4, Up:4

Names

  1. Names can denote declared entities, whether declared explicitly or implicitly, see 3.1. Names can also denote objects or subprograms designated by access values; the results of type_conversions or function_calls; subcomponents and slices of objects and values; protected subprograms, single entries, entry families, and entries in families of entries. Finally, names can denote attributes of any of the foregoing.

    Syntax
  2. name ::=
     direct_name          | explicit_dereference
   | indexed_component    | slice
   | selected_component   | attribute_reference
   | type_conversion      | function_call
   | character_literal

  3. direct_name ::= identifier | operator_symbol

  4. prefix ::= name | implicit_dereference

  5. explicit_dereference ::= name.all

  6. implicit_dereference ::= name
  7. Certain forms of name (indexed_components, selected_components, slices, and attributes) include a prefix that is either itself a name that denotes some related entity, or an implicit_dereference of an access value that designates some related entity.

    Name Resolution Rules
  8. The name in a dereference (either an implicit_dereference or an explicit_dereference) is expected to be of any access type.

    Static Semantics
  9. If the type of the name in a dereference is some access-to-object type T, then the dereference denotes a view of an object, the nominal subtype of the view being the designated subtype of T.
  10. If the type of the name in a dereference is some access-to-subprogram type S, then the dereference denotes a view of a subprogram, the profile of the view being the designated profile of S.

    Dynamic Semantics
  11. The evaluation of a name determines the entity denoted by the name. This evaluation has no other effect for a name that is a direct_name or a character_literal.
  12. The evaluation of a name that has a prefix includes the evaluation of the prefix. The evaluation of a prefix consists of the evaluation of the name or the implicit_dereference. The prefix denotes the entity denoted by the name or the implicit_dereference.
  13. The evaluation of a dereference consists of the evaluation of the name and the determination of the object or subprogram that is designated by the value of the name. A check is made that the value of the name is not the null access value. Constraint_Error is raised if this check fails. The dereference denotes the object or subprogram designated by the value of the name.

    Examples
  14. Examples of direct names: 
  15. Pi      -- the direct name of a number            (see 3.3.2)
Limit   -- the direct name of a constant          (see 3.3.1)
Count   -- the direct name of a scalar variable   (see 3.3.1)
Board   -- the direct name of an array variable   (see 3.6.1)
Matrix  -- the direct name of a type              (see 3.6)
Random  -- the direct name of a function          (see 6.1)
Error   -- the direct name of an exception        (see 11.1)
  16. Examples of dereferences: 
  17. Next_Car.all    --  explicit dereference denoting the object
                --  designated by the access variable Next_Car,
                --  see 3.10.1
Next_Car.Owner  --  selected component with implicit dereference;
                --  same as Next_Car.all.Owner

Node:4.1.1, Next:, Previous:4.1, Up:4.1

Indexed Components

  1. An indexed_component denotes either a component of an array or an entry in a family of entries.

    Syntax
  2. indexed_component ::= prefix(expression {, expression})

    Name Resolution Rules
  3. The prefix of an indexed_component with a given number of expressions shall resolve to denote an array (after any implicit dereference) with the corresponding number of index positions, or shall resolve to denote an entry family of a task or protected object (in which case there shall be only one expression).
  4. The expected type for each expression is the corresponding index type.

    Static Semantics
  5. When the prefix denotes an array, the indexed_component denotes the component of the array with the specified index value(s). The nominal subtype of the indexed_component is the component subtype of the array type.
  6. When the prefix denotes an entry family, the indexed_component denotes the individual entry of the entry family with the specified index value.

    Dynamic Semantics
  7. For the evaluation of an indexed_component, the prefix and the expressions are evaluated in an arbitrary order. The value of each expression is converted to the corresponding index type. A check is made that each index value belongs to the corresponding index range of the array or entry family denoted by the prefix. Constraint_Error is raised if this check fails.

    Examples
  8. Examples of indexed components: 
  9. My_Schedule(Sat)
--  a component of a one-dimensional array   (see see 3.6.1)

Page(10)
--  a component of a one-dimensional array   (see see 3.6)

Board(M, J + 1)
--  a component of a two-dimensional array   (see see 3.6.1)

Page(10)(20)
--  a component of a component               (see see 3.6)

Request(Medium)
--  an entry in a family of entries          (see see 9.1)

Next_Frame(L)(M, N)
--  a component of a function call           (see see 6.1)

    NOTES

  10. (1) Notes on the examples: Distinct notations are used for components of multidimensional arrays (such as Board) and arrays of arrays (such as Page). The components of an array of arrays are arrays and can therefore be indexed. Thus Page(10)(20) denotes the 20th component of Page(10). In the last example Next_Frame(L) is a function call returning an access value that designates a two-dimensional array.

Node:4.1.2, Next:, Previous:4.1.1, Up:4.1

Slices

  1. A slice denotes a one-dimensional array formed by a sequence of consecutive components of a one-dimensional array. A slice of a variable is a variable; a slice of a constant is a constant; a slice of a value is a value.

    Syntax
  2. slice ::= prefix(discrete_range)

    Name Resolution Rules
  3. The prefix of a slice shall resolve to denote a one-dimensional array (after any implicit dereference).
  4. The expected type for the discrete_range of a slice is the index type of the array type.

    Static Semantics
  5. A slice denotes a one-dimensional array formed by the sequence of consecutive components of the array denoted by the prefix, corresponding to the range of values of the index given by the discrete_range.
  6. The type of the slice is that of the prefix. Its bounds are those defined by the discrete_range.

    Dynamic Semantics
  7. For the evaluation of a slice, the prefix and the discrete_range are evaluated in an arbitrary order. If the slice is not a null slice (a slice where the discrete_range is a null range), then a check is made that the bounds of the discrete_range belong to the index range of the array denoted by the prefix. Constraint_Error is raised if this check fails.

    NOTES

  8. (2) A slice is not permitted as the prefix of an Access attribute_reference, even if the components or the array as a whole are aliased (see 3.10.2).
  9. (3) For a one-dimensional array A, the slice A(N .. N) denotes an array that has only one component; its type is the type of A. On the other hand, A(N) denotes a component of the array A and has the corresponding component type.

    Examples
  10. Examples of slices: 
  11. Stars(1 .. 15)
--  a slice of 15 characters         (see 3.6.3)

Page(10 .. 10 + Size)
--  a slice of 1 + Size components   (see 3.6)

Page(L)(A .. B)
--  a slice of the array Page(L)     (see 3.6)

Stars(1 .. 0)
--  a null slice                     (see 3.6.3)

My_Schedule(Weekday)
--  bounds given by subtype          (see 3.6.1, and 3.5.1)

Stars(5 .. 15)(K)
--  same as Stars(K)                 (see 3.6.3)
--  provided that K is in 5 .. 15

Node:4.1.3, Next:, Previous:4.1.2, Up:4.1

Selected Components

  1. Selected_components are used to denote components (including discriminants), entries, entry families, and protected subprograms; they are also used as expanded names as described below.

    Syntax
  2. selected_component ::= prefix . selector_name

  3. selector_name ::= identifier | character_literal | operator_symbol

    Name Resolution Rules
  4. A selected_component is called an expanded name if, according to the visibility rules, at least one possible interpretation of its prefix denotes a package or an enclosing named construct (directly, not through a subprogram_renaming_declaration or generic_renaming_declaration).
  5. A selected_component that is not an expanded name shall resolve to denote one of the following:
    1. A component (including a discriminant):
      1. The prefix shall resolve to denote an object or value of some non-array composite type (after any implicit dereference). The selector_name shall resolve to denote a discriminant_specification of the type, or, unless the type is a protected type, a component_declaration of the type. The selected_component denotes the corresponding component of the object or value.
    1. A single entry, an entry family, or a protected subprogram:
      1. The prefix shall resolve to denote an object or value of some task or protected type (after any implicit dereference). The selector_name shall resolve to denote an entry_declaration or subprogram_declaration occurring (implicitly or explicitly) within the visible part of that type. The selected_component denotes the corresponding entry, entry family, or protected subprogram.
  1. An expanded name shall resolve to denote a declaration that occurs immediately within a named declarative region, as follows:
    1. The prefix shall resolve to denote either a package (including the current instance of a generic package, or a rename of a package), or an enclosing named construct.
    2. The selector_name shall resolve to denote a declaration that occurs immediately within the declarative region of the package or enclosing construct (the declaration shall be visible at the place of the expanded name - see 8.3.). The expanded name denotes that declaration.
    3. If the prefix does not denote a package, then it shall be a direct_name or an expanded name, and it shall resolve to denote a program unit (other than a package), the current instance of a type, a block_statement, a loop_statement, or an accept_statement (in the case of an accept_statement or entry_body, no family index is allowed); the expanded name shall occur within the declarative region of this construct. Further, if this construct is a callable construct and the prefix denotes more than one such enclosing callable construct, then the expanded name is ambiguous, independently of the selector_name.

Dynamic Semantics
  1. The evaluation of a selected_component includes the evaluation of the prefix.
  2. For a selected_component that denotes a component of a variant, a check is made that the values of the discriminants are such that the value or object denoted by the prefix has this component. The exception Constraint_Error is raised if this check fails.

    Examples
  3. Examples of selected components: 
  4. Tomorrow.Month
--  a record component                    (see 3.8)

Next_Car.Owner
--  a record component                    (see 3.10.1)

Next_Car.Owner.Age
--  a record component                    (see 3.10.1)
--  the previous two lines involve implicit dereferences

Writer.Unit
--  a record component (a discriminant)   (see 3.8.1)

Min_Cell(H).Value
--  a record component of the result      (see 6.1)
--  of the function call Min_Cell(H)

Control.Seize
--  an entry of a protected object        (see 9.4)

Pool(K).Write
--  an entry of the task Pool(K)          (see 9.4)
  5. Examples of expanded names: 
  6. Key_Manager."<"
--  an operator of the visible part of a package   (see 7.3.1)

Dot_Product.Sum
--  a variable declared in a function body         (see 6.1)

Buffer.Pool
--  a variable declared in a protected unit        (see 9.11)

Buffer.Read
--  an entry of a protected unit                   (see 9.11)

Swap.Temp
--  a variable declared in a block statement       (see 5.6)

Standard.Boolean
--  the name of a predefined type                  (see A.1)

Node:4.1.4, Next:, Previous:4.1.3, Up:4.1

Attributes

  1. An attribute is a characteristic of an entity that can be queried via an attribute_reference or a range_attribute_reference.

    Syntax
  2. attribute_reference ::= prefix'attribute_designator

  3. attribute_designator ::=
     identifier[(static_expression)]
   | Access | Delta | Digits

  4. range_attribute_reference ::= prefix'range_attribute_designator

  5. range_attribute_designator ::= Range[(static_expression)]

    Name Resolution Rules
  6. In an attribute_reference, if the attribute_designator is for an attribute defined for (at least some) objects of an access type, then the prefix is never interpreted as an implicit_dereference; otherwise (and for all range_attribute_references), if the type of the name within the prefix is of an access type, the prefix is interpreted as an implicit_dereference. Similarly, if the attribute_designator is for an attribute defined for (at least some) functions, then the prefix is never interpreted as a parameterless function_call; otherwise (and for all range_attribute_references), if the prefix consists of a name that denotes a function, it is interpreted as a parameterless function_call.
  7. The expression, if any, in an attribute_designator or range_attribute_designator is expected to be of any integer type.

    Legality Rules
  8. The expression, if any, in an attribute_designator or range_attribute_designator shall be static.

    Static Semantics
  9. An attribute_reference denotes a value, an object, a subprogram, or some other kind of program entity.
  10. A range_attribute_reference X'Range(N) is equivalent to the range X'First(N) .. X'Last(N), except that the prefix is only evaluated once. Similarly, X'Range is equivalent to X'First .. X'Last, except that the prefix is only evaluated once.

    Dynamic Semantics
  11. The evaluation of an attribute_reference (or range_attribute_reference) consists of the evaluation of the prefix.

    Implementation Permissions
  12. An implementation may provide implementation-defined attributes; the identifier for an implementation-defined attribute shall differ from those of the language-defined attributes.

    NOTES

  13. (4) Attributes are defined throughout this International Standard, and are summarized in "Annex K.".
  14. (5) In general, the name in a prefix of an attribute_reference (or a range_attribute_reference) has to be resolved without using any context. However, in the case of the Access attribute, the expected type for the prefix has to be a single access type, and if it is an access-to-subprogram type, see 3.10.2, then the resolution of the name can use the fact that the profile of the callable entity denoted by the prefix has to be type conformant with the designated profile of the access type.

    Examples
  15. Examples of attributes: 
  16. Color'First
-- minimum value of the enumeration type Color    (see 3.5.1)

Rainbow'Base'First
-- same as Color'First                            (see 3.5.1)

Real'Digits
-- precision of the type Real                     (see 3.5.7)

Board'Last(2)
-- upper bound of the second dimension of Board   (see 3.6.1)

Board'Range(1)
-- index range of the first dimension of Board    (see 3.6.1)

Pool(K)'Terminated
-- True if task Pool(K) is terminated             (see 9.1)

Date'Size
-- number of bits for records of type Date        (see 3.8)

Message'Address
-- address of the record variable Message         (see 3.7.1)

Node:4.2, Next:, Previous:4.1.4, Up:4

Literals

  1. A literal represents a value literally, that is, by means of notation suited to its kind. A literal is either a numeric_literal, a character_literal, the literal null, or a string_literal.

    Name Resolution Rules
  2. The expected type for a literal null shall be a single access type.
  3. For a name that consists of a character_literal, either its expected type shall be a single character type, in which case it is interpreted as a parameterless function_call that yields the corresponding value of the character type, or its expected profile shall correspond to a parameterless function with a character result type, in which case it is interpreted as the name of the corresponding parameterless function declared as part of the character type's definition, see 3.5.1. In either case, the character_literal denotes the enumeration_literal_specification.
  4. The expected type for a primary that is a string_literal shall be a single string type.

    Legality Rules
  5. A character_literal that is a name shall correspond to a defining_character_literal of the expected type, or of the result type of the expected profile.
  6. For each character of a string_literal with a given expected string type, there shall be a corresponding defining_character_literal of the component type of the expected string type.
  7. A literal null shall not be of an anonymous access type, since such types do not have a null value, see 3.10.

    Static Semantics
  8. An integer literal is of type universal_integer. A real literal is of type universal_real.

    Dynamic Semantics
  9. The evaluation of a numeric literal, or the literal null, yields the represented value.
  10. The evaluation of a string_literal that is a primary yields an array value containing the value of each character of the sequence of characters of the string_literal, as defined in 2.6. The bounds of this array value are determined according to the rules for positional_array_aggregates (see 4.3.3), except that for a null string literal the upper bound is the predecessor of the lower bound.
  11. For the evaluation of a string_literal of type T, a check is made that the value of each character of the string_literal belongs to the component subtype of T. For the evaluation of a null string literal, a check is made that its lower bound is greater than the lower bound of the base range of the index type. The exception Constraint_Error is raised if either of these checks fails.

    NOTES

  12. (6) Enumeration literals that are identifiers rather than character_literals follow the normal rules for identifiers when used in a name, see 4.1, and 4.1.3. Character_literals used as selector_names follow the normal rules for expanded names, see 4.1.3.

    Examples
  13. Examples of literals: 
  14. 3.14159_26536    --  a real literal
1_345            --  an integer literal
'A'              --  a character literal
"Some Text"      --  a string literal

Node:4.3, Next:, Previous:4.2, Up:4

Aggregates

  1. An aggregate combines component values into a composite value of an array type, record type, or record extension.

    Syntax
  2. aggregate ::=
   record_aggregate | extension_aggregate | array_aggregate

    Name Resolution Rules
  3. The expected type for an aggregate shall be a single nonlimited array type, record type, or record extension.

    Legality Rules
  4. An aggregate shall not be of a class-wide type.

    Dynamic Semantics
  5. For the evaluation of an aggregate, an anonymous object is created and values for the components or ancestor part are obtained (as described in the subsequent subclause for each kind of the aggregate) and assigned into the corresponding components or ancestor part of the anonymous object. Obtaining the values and the assignments occur in an arbitrary order. The value of the aggregate is the value of this object.
  6. If an aggregate is of a tagged type, a check is made that its value belongs to the first subtype of the type. Constraint_Error is raised if this check fails.

Node:4.3.1, Next:, Previous:4.3, Up:4.3

Record Aggregates

  1. In a record_aggregate, a value is specified for each component of the record or record extension value, using either a named or a positional association.

    Syntax
  2. record_aggregate ::= (record_component_association_list)

  3. record_component_association_list ::=
     record_component_association {, record_component_association}
   | null record

  4. record_component_association ::=
   [ component_choice_list => ] expression

  5. component_choice_list ::=
     component_selector_name {| component_selector_name}
   | others
    1. A record_component_association is a named component association if it has a component_choice_list; otherwise, it is a positional component association. Any positional component associations shall precede any named component associations. If there is a named association with a component_choice_list of others, it shall come last.
    2. In the record_component_association_list for a record_aggregate, if there is only one association, it shall be a named association.

Name Resolution Rules
  1. The expected type for a record_aggregate shall be a single nonlimited record type or record extension.
  2. For the record_component_association_list of a record_aggregate, all components of the composite value defined by the aggregate are needed; for the association list of an extension_aggregate, only those components not determined by the ancestor expression or subtype are needed, see 4.3.2. Each selector_name in a record_component_association shall denote a needed component (including possibly a discriminant).
  3. The expected type for the expression of a record_component_association is the type of the associated component(s); the associated component(s) are as follows:
    1. For a positional association, the component (including possibly a discriminant) in the corresponding relative position (in the declarative region of the type), counting only the needed components;
    2. For a named association with one or more component_selector_names, the named component(s);
    3. For a named association with the reserved word others, all needed components that are not associated with some previous association.

Legality Rules
  1. If the type of a record_aggregate is a record extension, then it shall be a descendant of a record type, through one or more record extensions (and no private extensions).
  2. If there are no components needed in a given record_component_association_list, then the reserved words null record shall appear rather than a list of record_component_associations.
  3. Each record_component_association shall have at least one associated component, and each needed component shall be associated with exactly one record_component_association. If a record_component_association has two or more associated components, all of them shall be of the same type.
  4. If the components of a variant_part are needed, then the value of a discriminant that governs the variant_part shall be given by a static expression.

    Dynamic Semantics
  5. The evaluation of a record_aggregate consists of the evaluation of the record_component_association_list.
  6. For the evaluation of a record_component_association_list, any per-object constraints, see 3.8, for components specified in the association list are elaborated and any expressions are evaluated and converted to the subtype of the associated component. Any constraint elaborations and expression evaluations (and conversions) occur in an arbitrary order, except that the expression for a discriminant is evaluated (and converted) prior to the elaboration of any per-object constraint that depends on it, which in turn occurs prior to the evaluation and conversion of the expression for the component with the per-object constraint.
  7. The expression of a record_component_association is evaluated (and converted) once for each associated component.

    NOTES

  8. (7) For a record_aggregate with positional associations, expressions specifying discriminant values appear first since the known_discriminant_part is given first in the declaration of the type; they have to be in the same order as in the known_discriminant_part.

    Examples
  9. Example of a record aggregate with positional associations: 
  10. (4, July, 1776)  --  see 3.8
  11. Examples of record aggregates with named associations: 
  12. (Day => 4, Month => July, Year => 1776)
(Month => July, Day => 4, Year => 1776)

  13. (Disk, Closed, Track => 5, Cylinder => 12)  --  see 3.8.1
(Unit => Disk, Status => Closed, Cylinder => 9, Track => 1)
  14. Example of component association with several choices: 
  15. (Value => 0, Succ|Pred => new Cell'(0, null, null))
--  see 3.10.1

  16. --  The allocator is evaluated twice:
--  Succ and Pred designate different cells
  17. Examples of record aggregates for tagged types, see 3.9, and 3.9.1 
  18. Expression'(null record)
Literal'(Value => 0.0)
Painted_Point'(0.0, Pi/2.0, Paint => Red)

Node:4.3.2, Next:, Previous:4.3.1, Up:4.3

Extension Aggregates

  1. An extension_aggregate specifies a value for a type that is a record extension by specifying a value or subtype for an ancestor of the type, followed by associations for any components not determined by the ancestor_part.

    Syntax
  2. extension_aggregate ::=
   (ancestor_part with record_component_association_list)

  3. ancestor_part ::= expression | subtype_mark

    Name Resolution Rules
  4. The expected type for an extension_aggregate shall be a single nonlimited type that is a record extension. If the ancestor_part is an expression, it is expected to be of any nonlimited tagged type.

    Legality Rules
  5. If the ancestor_part is a subtype_mark, it shall denote a specific tagged subtype. The type of the extension_aggregate shall be derived from the type of the ancestor_part, through one or more record extensions (and no private extensions).

    Static Semantics
  6. For the record_component_association_list of an extension_aggregate, the only components needed are those of the composite value defined by the aggregate that are not inherited from the type of the ancestor_part, plus any inherited discriminants if the ancestor_part is a subtype_mark that denotes an unconstrained subtype.

    Dynamic Semantics
  7. For the evaluation of an extension_aggregate, the record_component_association_list is evaluated. If the ancestor_part is an expression, it is also evaluated; if the ancestor_part is a subtype_mark, the components of the value of the aggregate not given by the record_component_association_list are initialized by default as for an object of the ancestor type. Any implicit initializations or evaluations are performed in an arbitrary order, except that the expression for a discriminant is evaluated prior to any other evaluation or initialization that depends on it.
  8. If the type of the ancestor_part has discriminants that are not inherited by the type of the extension_aggregate, then, unless the ancestor_part is a subtype_mark that denotes an unconstrained subtype, a check is made that each discriminant of the ancestor has the value specified for a corresponding discriminant, either in the record_component_association_list, or in the derived_type_definition for some ancestor of the type of the extension_aggregate. Constraint_Error is raised if this check fails.

    NOTES

  9. (8) If all components of the value of the extension_aggregate are determined by the ancestor_part, then the record_component_association_list is required to be simply null record.
  10. (9) If the ancestor_part is a subtype_mark, then its type can be abstract. If its type is controlled, then as the last step of evaluating the aggregate, the Initialize procedure of the ancestor type is called, unless the Initialize procedure is abstract, see 7.6.

    Examples
  11. Examples of extension aggregates (for types defined in 3.9.1.): 
  12. Painted_Point'(Point with Red)
(Point'(P) with Paint => Black)

  13. (Expression with Left => 1.2, Right => 3.4)
Addition'(Binop with null record)
-- presuming Binop is of type Binary_Operation

Node:4.3.3, Next:, Previous:4.3.2, Up:4.3

Array Aggregates

  1. In an array_aggregate, a value is specified for each component of an array, either positionally or by its index. For a positional_array_aggregate, the components are given in increasing-index order, with a final others, if any, representing any remaining components. For a named_array_aggregate, the components are identified by the values covered by the discrete_choices.

    Syntax
  2. array_aggregate ::=
   positional_array_aggregate | named_array_aggregate

  3. positional_array_aggregate ::=
     (expression, expression {, expression})
   | (expression {, expression}, others => expression)

  4. named_array_aggregate ::=
   (array_component_association {, array_component_association})

  5. array_component_association ::=
   discrete_choice_list => expression
  6. An n-dimensional array_aggregate is one that is written as n levels of nested array_aggregates (or at the bottom level, equivalent string_literals). For the multidimensional case (n >= 2) the array_aggregates (or equivalent string_literals) at the n-1 lower levels are called subaggregates of the enclosing n-dimensional array_aggregate. The expressions of the bottom level subaggregates (or of the array_aggregate itself if one-dimensional) are called the array component expressions of the enclosing n-dimensional array_aggregate.

    Name Resolution Rules
  7. The expected type for an array_aggregate (that is not a subaggregate) shall be a single nonlimited array type. The component type of this array type is the expected type for each array component expression of the array_aggregate.
  8. The expected type for each discrete_choice in any discrete_choice_list of a named_array_aggregate is the type of the corresponding index; the corresponding index for an array_aggregate that is not a subaggregate is the first index of its type; for an (n-m)-dimensional subaggregate within an array_aggregate of an n-dimensional type, the corresponding index is the index in position m+1.

    Legality Rules
  9. An array_aggregate of an n-dimensional array type shall be written as an n-dimensional array_aggregate.
  10. An others choice is allowed for an array_aggregate only if an applicable index constraint applies to the array_aggregate. An applicable index constraint is a constraint provided by certain contexts where an array_aggregate is permitted that can be used to determine the bounds of the array value specified by the aggregate. Each of the following contexts (and none other) defines an applicable index constraint:
    1. For an explicit_actual_parameter, an explicit_generic_actual_parameter, the expression of a return_statement, the initialization expression in an object_declaration, or a default_expression (for a parameter or a component), when the nominal subtype of the corresponding formal parameter, generic formal parameter, function result, object, or component is a constrained array subtype, the applicable index constraint is the constraint of the subtype;
    2. For the expression of an assignment_statement where the name denotes an array variable, the applicable index constraint is the constraint of the array variable;
    3. For the operand of a qualified_expression whose subtype_mark denotes a constrained array subtype, the applicable index constraint is the constraint of the subtype;
    4. For a component expression in an aggregate, if the component's nominal subtype is a constrained array subtype, the applicable index constraint is the constraint of the subtype;
    5. For a parenthesized expression, the applicable index constraint is that, if any, defined for the expression.
  1. The applicable index constraint applies to an array_aggregate that appears in such a context, as well as to any subaggregates thereof. In the case of an explicit_actual_parameter (or default_expression) for a call on a generic formal subprogram, no applicable index constraint is defined.
  2. The discrete_choice_list of an array_component_association is allowed to have a discrete_choice that is a nonstatic expression or that is a discrete_range that defines a nonstatic or null range, only if it is the single discrete_choice of its discrete_choice_list, and there is only one array_component_association in the array_aggregate.
  3. In a named_array_aggregate with more than one discrete_choice, no two discrete_choices are allowed to cover the same value, see 3.8.1, if there is no others choice, the discrete_choices taken together shall exactly cover a contiguous sequence of values of the corresponding index type.
  4. A bottom level subaggregate of a multidimensional array_aggregate of a given array type is allowed to be a string_literal only if the component type of the array type is a character type; each character of such a string_literal shall correspond to a defining_character_literal of the component type.

    Static Semantics
  5. A subaggregate that is a string_literal is equivalent to one that is a positional_array_aggregate of the same length, with each expression being the character_literal for the corresponding character of the string_literal.

    Dynamic Semantics
  6. The evaluation of an array_aggregate of a given array type proceeds in two steps:
    1. Any discrete_choices of this aggregate and of its subaggregates are evaluated in an arbitrary order, and converted to the corresponding index type;
    2. The array component expressions of the aggregate are evaluated in an arbitrary order and their values are converted to the component subtype of the array type; an array component expression is evaluated once for each associated component.
  1. The bounds of the index range of an array_aggregate (including a subaggregate) are determined as follows:
    1. For an array_aggregate with an others choice, the bounds are those of the corresponding index range from the applicable index constraint;
    2. For a positional_array_aggregate (or equivalent string_literal) without an others choice, the lower bound is that of the corresponding index range in the applicable index constraint, if defined, or that of the corresponding index subtype, if not; in either case, the upper bound is determined from the lower bound and the number of expressions (or the length of the string_literal);
    3. For a named_array_aggregate without an others choice, the bounds are determined by the smallest and largest index values covered by any discrete_choice_list.
  1. For an array_aggregate, a check is made that the index range defined by its bounds is compatible with the corresponding index subtype.
  2. For an array_aggregate with an others choice, a check is made that no expression is specified for an index value outside the bounds determined by the applicable index constraint.
  3. For a multidimensional array_aggregate, a check is made that all subaggregates that correspond to the same index have the same bounds.
  4. The exception Constraint_Error is raised if any of the above checks fail.

    NOTES

  5. (10) In an array_aggregate, positional notation may only be used with two or more expressions; a single expression in parentheses is interpreted as a parenthesized_expression. A named_array_aggregate, such as (1 => X), may be used to specify an array with a single component.

    Examples
  6. Examples of array aggregates with positional associations: 
  7. (7, 9, 5, 1, 3, 2, 4, 8, 6, 0)
Table'(5, 8, 4, 1, others => 0)  --  see 3.6
  8. Examples of array aggregates with named associations: 
  9. (1 .. 5 => (1 .. 8 => 0.0))  --  two-dimensional
(1 .. N => new Cell)         --  N new cells, in particular for N = 0

  10. Table'(2 | 4 | 10 => 1, others => 0)

Schedule'(Mon .. Fri => True,  others => False)
Schedule'(Wed | Sun  => False, others => True)
--  see 3.6

Vector'(1 => 2.5)
--  single-component vector
  11. Examples of two-dimensional array aggregates: 
  12. -- Three aggregates for the same value of subtype
--  Matrix(1..2,1..3), see 3.6

  13. ((1.1, 1.2, 1.3), (2.1, 2.2, 2.3))
(1 => (1.1, 1.2, 1.3), 2 => (2.1, 2.2, 2.3))
(1 => (1 => 1.1, 2 => 1.2, 3 => 1.3),
  2 => (1 => 2.1, 2 => 2.2, 3 => 2.3))
  14. Examples of aggregates as initial values: 
  15. A : Table := (7, 9, 5, 1, 3, 2, 4, 8, 6, 0);
-- A(1)=7, A(10)=0

B : Table := (2 | 4 | 10 => 1, others => 0);
-- B(1)=0, B(10)=1

C : constant Matrix := (1 .. 5 => (1 .. 8 => 0.0));
-- C'Last(1)=5, C'Last(2)=8

  16. D : Bit_Vector(M .. N) := (M .. N => True);  --  see 3.6
E : Bit_Vector(M .. N) := (others => True);
F : String(1 .. 1) := (1 => 'F');
-- a one component aggregate: same as "F"

Node:4.4, Next:, Previous:4.3.3, Up:4

Expressions

  1. An expression is a formula that defines the computation or retrieval of a value. In this International Standard, the term "expression" refers to a construct of the syntactic category expression or of any of the other five syntactic categories defined below.

    Syntax
  2. expression ::=
     relation {and relation} | relation {and then relation}
   | relation {or relation}  | relation {or else relation}
   | relation {xor relation}

  3. relation ::=
     simple_expression [relational_operator simple_expression]
   | simple_expression [not] in range
   | simple_expression [not] in subtype_mark

  4. simple_expression ::=
   [unary_adding_operator] term {binary_adding_operator term}

  5. term ::= factor {multiplying_operator factor}

  6. factor ::= primary [** primary] | abs primary | not primary

  7. primary ::=
     numeric_literal   | null
   | string_literal    | aggregate
   | name              | qualified_expression
   | allocator         | (expression)

    Name Resolution Rules
  8. A name used as a primary shall resolve to denote an object or a value.

    Static Semantics
  9. Each expression has a type; it specifies the computation or retrieval of a value of that type.

    Dynamic Semantics
  10. The value of a primary that is a name denoting an object is the value of the object.

    Implementation Permissions
  11. For the evaluation of a primary that is a name denoting an object of an unconstrained numeric subtype, if the value of the object is outside the base range of its type, the implementation may either raise Constraint_Error or return the value of the object.

    Examples
  12. Examples of primaries: 
  13. 4.0                --  real literal
Pi                 --  named number
(1 .. 10 => 0)     --  array aggregate
Sum                --  variable
Integer'Last       --  attribute
Sine(X)            --  function call
Color'(Blue)       --  qualified expression
Real(M*N)          --  conversion
(Line_Count + 10)  --  parenthesized expression
  14. Examples of expressions: 
  15. Volume                      -- primary
not Destroyed               -- factor
2*Line_Count                -- term
-4.0                        -- simple expression
-4.0 + A                    -- simple expression
B**2 - 4.0*A*C              -- simple expression
Password(1 .. 3) = "Bwv"    -- relation
Count in Small_Int          -- relation
Count not in Small_Int      -- relation
Index = 0 or Item_Hit       -- expression
(Cold and Sunny) or Warm    -- expression (parentheses are required)
A**(B**C)                   -- expression (parentheses are required)

Node:4.5, Next:, Previous:4.4, Up:4

Operators and Expression Evaluation

  1. The language defines the following six categories of operators (given in order of increasing precedence). The corresponding operator_symbols, and only those, can be used as designators in declarations of functions for user-defined operators (see "Overloading of Operators").

    Syntax
  2. logical_operator            ::=  and | or  | xor

  3. relational_operator         ::=  =   | /=  | <   | <= | > | >=

  4. binary_adding_operator      ::=  +   | -   | &

  5. unary_adding_operator       ::=  +   | -

  6. multiplying_operator        ::=  *   | /   | mod | rem

  7. highest_precedence_operator ::=  **  | abs | not

    Static Semantics
  8. For a sequence of operators of the same precedence level, the operators are associated with their operands in textual order from left to right. Parentheses can be used to impose specific associations.
  9. For each form of type definition, certain of the above operators are predefined; that is, they are implicitly declared immediately after the type definition. For each such implicit operator declaration, the parameters are called Left and Right for binary operators; the single parameter is called Right for unary operators. An expression of the form X op Y, where op is a binary operator, is equivalent to a function_call of the form "op"(X, Y). An expression of the form op Y, where op is a unary operator, is equivalent to a function_call of the form "op"(Y). The predefined operators and their effects are described in subclauses 4.5.1 through 4.5.6.

    Dynamic Semantics
  10. The predefined operations on integer types either yield the mathematically correct result or raise the exception Constraint_Error. For implementations that support the Numerics Annex, the predefined operations on real types yield results whose accuracy is defined in "Annex G", or raise the exception Constraint_Error.

    Implementation Requirements
  11. The implementation of a predefined operator that delivers a result of an integer or fixed point type may raise Constraint_Error only if the result is outside the base range of the result type.
  12. The implementation of a predefined operator that delivers a result of a floating point type may raise Constraint_Error only if the result is outside the safe range of the result type.

    Implementation Permissions
  13. For a sequence of predefined operators of the same precedence level (and in the absence of parentheses imposing a specific association), an implementation may impose any association of the operators with operands so long as the result produced is an allowed result for the left-to-right association, but ignoring the potential for failure of language-defined checks in either the left-to-right or chosen order of association.

    NOTES

  14. (11) The two operands of an expression of the form X op Y, where op is a binary operator, are evaluated in an arbitrary order, as for any function_call, see 6.4.

    Examples
  15. Examples of precedence: 
  16. not Sunny or Warm    --  same as (not Sunny) or Warm
X > 4.0 and Y > 0.0  --  same as (X > 4.0) and (Y > 0.0)

  17. -4.0*A**2            --  same as -(4.0 * (A**2))
abs(1 + A) + B       --  same as (abs (1 + A)) + B
Y**(-3)              --  parentheses are necessary
A / B * C            --  same as (A/B)*C
A + (B + C)          --  evaluate B + C before adding it to A

Node:4.5.1, Next:, Previous:4.5, Up:4.5

Logical Operators and Short-circuit Control Forms


Name Resolution Rules
  1. An expression consisting of two relations connected by and then or or else (a short-circuit control form) shall resolve to be of some boolean type; the expected type for both relations is that same boolean type.

    Static Semantics
  2. The following logical operators are predefined for every boolean type T, for every modular type T, and for every one-dimensional array type T whose component type is a boolean type: 
  3. function "and"(Left, Right : T) return T
function "or" (Left, Right : T) return T
function "xor"(Left, Right : T) return T
  4. For boolean types, the predefined logical operators and, or, and xor perform the conventional operations of conjunction, inclusive disjunction, and exclusive disjunction, respectively.
  5. For modular types, the predefined logical operators are defined on a bit-by-bit basis, using the binary representation of the value of the operands to yield a binary representation for the result, where zero represents False and one represents True. If this result is outside the base range of the type, a final subtraction by the modulus is performed to bring the result into the base range of the type.
  6. The logical operators on arrays are performed on a component-by-component basis on matching components (as for equality - see 4.5.2.), using the predefined logical operator for the component type. The bounds of the resulting array are those of the left operand.

    Dynamic Semantics
  7. The short-circuit control forms and then and or else deliver the same result as the corresponding predefined and and or operators for boolean types, except that the left operand is always evaluated first, and the right operand is not evaluated if the value of the left operand determines the result.
  8. For the logical operators on arrays, a check is made that for each component of the left operand there is a matching component of the right operand, and vice versa. Also, a check is made that each component of the result belongs to the component subtype. The exception Constraint_Error is raised if either of the above checks fails.

    NOTES

  9. (12) The conventional meaning of the logical operators is given by the following truth table: 
  10. A      B      (A and B)  (A or B)  (A xor B)

True   True     True       True      False
True   False    False      True      True
False  True     False      True      True
False  False    False      False     False

    Examples
  11. Examples of logical operators: 
  12. Sunny or Warm
Filter(1 .. 10) and Filter(15 .. 24)   --  see 3.6.1
  13. Examples of short-circuit control forms: 
  14. Next_Car.Owner /= null and then Next_Car.Owner.Age > 25
--  see 3.10.1

N = 0 or else A(N) = Hit_Value

Node:4.5.2, Next:, Previous:4.5.1, Up:4.5

Relational Operators and Membership Tests

  1. The equality operators = (equals) and /= (not equals) are predefined for nonlimited types. The other relational_operators are the ordering operators < (less than), <= (less than or equal), > (greater than), and >= (greater than or equal). The ordering operators are predefined for scalar types, and for discrete array types, that is, one-dimensional array types whose components are of a discrete type.
  2. A membership test, using in or not in, determines whether or not a value belongs to a given subtype or range, or has a tag that identifies a type that is covered by a given type. Membership tests are allowed for all types.

    Name Resolution Rules
  3. The tested type of a membership test is the type of the range or the type determined by the subtype_mark. If the tested type is tagged, then the simple_expression shall resolve to be of a type that covers or is covered by the tested type; if untagged, the expected type for the simple_expression is the tested type.

    Legality Rules
  4. For a membership test, if the simple_expression is of a tagged class-wide type, then the tested type shall be (visibly) tagged.

    Static Semantics
  5. The result type of a membership test is the predefined type Boolean.
  6. The equality operators are predefined for every specific type T that is not limited, and not an anonymous access type, with the following specifications: 
  7. function "=" (Left, Right : T) return Boolean
function "/="(Left, Right : T) return Boolean
  8. The ordering operators are predefined for every specific scalar type T, and for every discrete array type T, with the following specifications: 
  9. function "<" (Left, Right : T) return Boolean
function "<="(Left, Right : T) return Boolean
function ">" (Left, Right : T) return Boolean
function ">="(Left, Right : T) return Boolean

    Dynamic Semantics
  10. For discrete types, the predefined relational operators are defined in terms of corresponding mathematical operations on the position numbers of the values of the operands.
  11. For real types, the predefined relational operators are defined in terms of the corresponding mathematical operations on the values of the operands, subject to the accuracy of the type.
  12. Two access-to-object values are equal if they designate the same object, or if both are equal to the null value of the access type.
  13. Two access-to-subprogram values are equal if they are the result of the same evaluation of an Access attribute_reference, or if both are equal to the null value of the access type. Two access-to-subprogram values are unequal if they designate different subprograms. It is unspecified whether two access values that designate the same subprogram but are the result of distinct evaluations of Access attribute_references are equal or unequal.
  14. For a type extension, predefined equality is defined in terms of the primitive (possibly user-defined) equals operator of the parent type and of any tagged components of the extension part, and predefined equality for any other components not inherited from the parent type.
  15. For a private type, if its full type is tagged, predefined equality is defined in terms of the primitive equals operator of the full type; if the full type is untagged, predefined equality for the private type is that of its full type.
  16. For other composite types, the predefined equality operators (and certain other predefined operations on composite types - see 4.5.1, and 4.6.) are defined in terms of the corresponding operation on matching components, defined as follows:
    1. For two composite objects or values of the same non-array type, matching components are those that correspond to the same component_declaration or discriminant_specification;
    2. For two one-dimensional arrays of the same type, matching components are those (if any) whose index values match in the following sense: the lower bounds of the index ranges are defined to match, and the successors of matching indices are defined to match;
    3. For two multidimensional arrays of the same type, matching components are those whose index values match in successive index positions.
  1. The analogous definitions apply if the types of the two objects or values are convertible, rather than being the same.
  2. Given the above definition of matching components, the result of the predefined equals operator for composite types (other than for those composite types covered earlier) is defined as follows:
    1. If there are no components, the result is defined to be True;
    2. If there are unmatched components, the result is defined to be False;
    3. Otherwise, the result is defined in terms of the primitive equals operator for any matching tagged components, and the predefined equals for any matching untagged components.
  1. The predefined "/=" operator gives the complementary result to the predefined "=" operator.
  2. For a discrete array type, the predefined ordering operators correspond to lexicographic order using the predefined order relation of the component type: A null array is lexicographically less than any array having at least one component. In the case of nonnull arrays, the left operand is lexicographically less than the right operand if the first component of the left operand is less than that of the right; otherwise the left operand is lexicographically less than the right operand only if their first components are equal and the tail of the left operand is lexicographically less than that of the right (the tail consists of the remaining components beyond the first and can be null).
  3. For the evaluation of a membership test, the simple_expression and the range (if any) are evaluated in an arbitrary order.
  4. A membership test using in yields the result True if:
    1. The tested type is scalar, and the value of the simple_expression belongs to the given range, or the range of the named subtype; or
    2. The tested type is not scalar, and the value of the simple_ expression satisfies any constraints of the named subtype, and, if the type of the simple_expression is class-wide, the value has a tag that identifies a type covered by the tested type.
  1. Otherwise the test yields the result False.
  2. A membership test using not in gives the complementary result to the corresponding membership test using in.

    NOTES

  3. (13) No exception is ever raised by a membership test, by a predefined ordering operator, or by a predefined equality operator for an elementary type, but an exception can be raised by the evaluation of the operands. A predefined equality operator for a composite type can only raise an exception if the type has a tagged part whose primitive equals operator propagates an exception.
  4. (14) If a composite type has components that depend on discriminants, two values of this type have matching components if and only if their discriminants are equal. Two nonnull arrays have matching components if and only if the length of each dimension is the same for both.

    Examples
  5. Examples of expressions involving relational operators and membership tests: 
  6. X /= Y

  7. "" < "A" and "A" < "Aa"     --  True
"Aa" < "B" and "A" < "A  "  --  True

  8. My_Car = null
-- true if My_Car has been set to null  (see 3.10.1)

My_Car = Your_Car
-- true if we both share the same car

My_Car.all = Your_Car.all
-- true if the two cars are identical

  9. N not in 1 .. 10
-- range membership test

Today in Mon .. Fri
-- range membership test

Today in Weekday
-- subtype membership test  (see 3.5.1)

Archive in Disk_Unit
-- subtype membership test, see 3.8.1

Tree.all in Addition'Class
-- class membership test  (see 3.9.1)

Node:4.5.3, Next:, Previous:4.5.2, Up:4.5

Binary Adding Operators


Static Semantics
  1. The binary adding operators + (addition) and - (subtraction) are predefined for every specific numeric type T with their conventional meaning. They have the following specifications: 
  2. function "+"(Left, Right : T) return T
function "-"(Left, Right : T) return T
  3. The concatenation operators & are predefined for every nonlimited, one-dimensional array type T with component type C. They have the following specifications: 
  4. function "&"(Left : T; Right : T) return T
function "&"(Left : T; Right : C) return T
function "&"(Left : C; Right : T) return T
function "&"(Left : C; Right : C) return T

    Dynamic Semantics
  5. For the evaluation of a concatenation with result type T, if both operands are of type T, the result of the concatenation is a one-dimensional array whose length is the sum of the lengths of its operands, and whose components comprise the components of the left operand followed by the components of the right operand. If the left operand is a null array, the result of the concatenation is the right operand. Otherwise, the lower bound of the result is determined as follows:
    1. If the ultimate ancestor of the array type was defined by a constrained_array_definition, then the lower bound of the result is that of the index subtype;
    2. If the ultimate ancestor of the array type was defined by an unconstrained_array_definition, then the lower bound of the result is that of the left operand.
  1. The upper bound is determined by the lower bound and the length. A check is made that the upper bound of the result of the concatenation belongs to the range of the index subtype, unless the result is a null array. Constraint_Error is raised if this check fails.
  2. If either operand is of the component type C, the result of the concatenation is given by the above rules, using in place of such an operand an array having this operand as its only component (converted to the component subtype) and having the lower bound of the index subtype of the array type as its lower bound.
  3. The result of a concatenation is defined in terms of an assignment to an anonymous object, as for any function call, see 6.5.

    NOTES

  4. (15) As for all predefined operators on modular types, the binary adding operators + and - on modular types include a final reduction modulo the modulus if the result is outside the base range of the type.

    Examples
  5. Examples of expressions involving binary adding operators: 
  6. Z + 0.1
--  Z has to be of a real type

  7. "A" & "BCD"
--  concatenation of two string literals

'A' & "BCD"
--  concatenation of a character literal and a string literal

'A' & 'A'
--  concatenation of two character literals

Node:4.5.4, Next:, Previous:4.5.3, Up:4.5

Unary Adding Operators


Static Semantics
  1. The unary adding operators + (identity) and - (negation) are predefined for every specific numeric type T with their conventional meaning. They have the following specifications: 
  2. function "+"(Right : T) return T
function "-"(Right : T) return T

    NOTES

  3. (16) For modular integer types, the unary adding operator -, when given a nonzero operand, returns the result of subtracting the value of the operand from the modulus; for a zero operand, the result is zero.

Node:4.5.5, Next:, Previous:4.5.4, Up:4.5

Multiplying Operators


Static Semantics
  1. The multiplying operators * (multiplication), / (division), mod (modulus), and rem (remainder) are predefined for every specific integer type T: 
  2. function "*"  (Left, Right : T) return T
function "/"  (Left, Right : T) return T
function "mod"(Left, Right : T) return T
function "rem"(Left, Right : T) return T
  3. Signed integer multiplication has its conventional meaning.
  4. Signed integer division and remainder are defined by the relation: 
  5. A = (A/B)*B + (A rem B)
  6. where (A rem B) has the sign of A and an absolute value less than the absolute value of B. Signed integer division satisfies the identity: 
  7. (-A)/B = -(A/B) = A/(-B)
  8. The signed integer modulus operator is defined such that the result of A mod B has the sign of B and an absolute value less than the absolute value of B; in addition, for some signed integer value N, this result satisfies the relation: 
  9. A = B*N + (A mod B)
  10. The multiplying operators on modular types are defined in terms of the corresponding signed integer operators, followed by a reduction modulo the modulus if the result is outside the base range of the type (which is only possible for the "*" operator).
  11. Multiplication and division operators are predefined for every specific floating point type T: 
  12. function "*"(Left, Right : T) return T
function "/"(Left, Right : T) return T
  13. The following multiplication and division operators, with an operand of the predefined type Integer, are predefined for every specific fixed point type T: 
  14. function "*"(Left : T; Right : Integer) return T
function "*"(Left : Integer; Right : T) return T
function "/"(Left : T; Right : Integer) return T
  15. All of the above multiplying operators are usable with an operand of an appropriate universal numeric type. The following additional multiplying operators for root_real are predefined, and are usable when both operands are of an appropriate universal or root numeric type, and the result is allowed to be of type root_real, as in a number_declaration: 
  16. function "*"(Left, Right : root_real) return root_real
function "/"(Left, Right : root_real) return root_real

  17. function "*"(Left : root_real; Right : root_integer) return root_real
function "*"(Left : root_integer; Right : root_real) return root_real
function "/"(Left : root_real; Right : root_integer) return root_real
  18. Multiplication and division between any two fixed point types are provided by the following two predefined operators: 
  19. function "*"(Left, Right : universal_fixed) return universal_fixed
function "/"(Left, Right : universal_fixed) return universal_fixed

    Legality Rules
  20. The above two fixed-fixed multiplying operators shall not be used in a context where the expected type for the result is itself universal_fixed - the context has to identify some other numeric type to which the result is to be converted, either explicitly or implicitly.

    Dynamic Semantics
  21. The multiplication and division operators for real types have their conventional meaning. For floating point types, the accuracy of the result is determined by the precision of the result type. For decimal fixed point types, the result is truncated toward zero if the mathematical result is between two multiples of the small of the specific result type (possibly determined by context); for ordinary fixed point types, if the mathematical result is between two multiples of the small, it is unspecified which of the two is the result.
  22. The exception Constraint_Error is raised by integer division, rem, and mod if the right operand is zero. Similarly, for a real type T with T'Machine_Overflows True, division by zero raises Constraint_Error.

    NOTES

  23. (17) For positive A and B, A/B is the quotient and A rem B is the remainder when A is divided by B. The following relations are satisfied by the rem operator: 
  24.   A  rem (-B) =   A rem B
(-A) rem   B  = -(A rem B)
  25. (18) For any signed integer K, the following identity holds: 
  26.   A mod B   =   (A + K*B) mod B
  27. The relations between signed integer division, remainder, and modulus are illustrated by the following table: 
  28.   A    B  A/B  A rem B  A mod B    A   B  A/B  A rem B  A mod B

  29.   10   5   2      0        0      -10  5   -2     0        0
  11   5   2      1        1      -11  5   -2    -1        4
  12   5   2      2        2      -12  5   -2    -2        3
  13   5   2      3        3      -13  5   -2    -3        2
  14   5   2      4        4      -14  5   -2    -4        1

  30.   A    B  A/B  A rem B  A mod B    A   B  A/B  A rem B  A mod B
  10  -5   -2     0        0      -10 -5    2     0        0
  11  -5   -2     1       -4      -11 -5    2    -1       -1
  12  -5   -2     2       -3      -12 -5    2    -2       -2
  13  -5   -2     3       -2      -13 -5    2    -3       -3
  14  -5   -2     4       -1      -14 -5    2    -4       -4

    Examples
  31. Examples of expressions involving multiplying operators: 
  32. I : Integer := 1;
J : Integer := 2;
K : Integer := 3;

  33. X : Real := 1.0;       --  see 3.5.7
Y : Real := 2.0;

  34. F : Fraction := 0.25;  --  see 3.5.9
G : Fraction := 0.5;

  35. Expression     Value  Result Type

I*J            2      same as I and J, that is, Integer
K/J            1      same as K and J, that is, Integer
K mod J        1      same as K and J, that is, Integer

X/Y            0.5    same as X and Y, that is, Real
F/2            0.125  same as F, that is, Fraction

3*F            0.75   same as F, that is, Fraction
0.75*G         0.375  universal_fixed, implicitly convertible
                      to any fixed point type
Fraction(F*G)  0.125  Fraction, as stated by the conversion
Real(J)*Y      4.0    Real, the type of both operands after
                      conversion of J

Node:4.5.6, Next:, Previous:4.5.5, Up:4.5

Highest Precedence Operators


Static Semantics
  1. The highest precedence unary operator abs (absolute value) is predefined for every specific numeric type T, with the following specification: 
  2. function "abs"(Right : T) return T
  3. The highest precedence unary operator not (logical negation) is predefined for every boolean type T, every modular type T, and for every one-dimensional array type T whose components are of a boolean type, with the following specification: 
  4. function "not"(Right : T) return T
  5. The result of the operator not for a modular type is defined as the difference between the high bound of the base range of the type and the value of the operand. For a binary modulus, this corresponds to a bit-wise complement of the binary representation of the value of the operand.
  6. The operator not that applies to a one-dimensional array of boolean components yields a one-dimensional boolean array with the same bounds; each component of the result is obtained by logical negation of the corresponding component of the operand (that is, the component that has the same index value). A check is made that each component of the result belongs to the component subtype; the exception Constraint_Error is raised if this check fails.
  7. The highest precedence exponentiation operator ** is predefined for every specific integer type T with the following specification: 
  8. function "**"(Left : T; Right : Natural) return T
  9. Exponentiation is also predefined for every specific floating point type as well as root_real, with the following specification (where T is root_real or the floating point type): 
  10. function "**"(Left : T; Right : Integer'Base) return T
  11. The right operand of an exponentiation is the exponent. The expression X**N with the value of the exponent N positive is equivalent to the expression X*X*...X (with N-1 multiplications) except that the multiplications are associated in an arbitrary order. With N equal to zero, the result is one. With the value of N negative (only defined for a floating point operand), the result is the reciprocal of the result using the absolute value of N as the exponent.

    Implementation Permissions
  12. The implementation of exponentiation for the case of a negative exponent is allowed to raise Constraint_Error if the intermediate result of the repeated multiplications is outside the safe range of the type, even though the final result (after taking the reciprocal) would not be. (The best machine approximation to the final result in this case would generally be 0.0.)

    NOTES

  13. (19) As implied by the specification given above for exponentiation of an integer type, a check is made that the exponent is not negative. Constraint_Error is raised if this check fails.

Node:4.6, Next:, Previous:4.5.6, Up:4

Type Conversions

  1. Explicit type conversions, both value conversions and view conversions, are allowed between closely related types as defined below. This clause also defines rules for value and view conversions to a particular subtype of a type, both explicit ones and those implicit in other constructs.

    Syntax
  2. type_conversion ::=
     subtype_mark(expression)
   | subtype_mark(name)
  3. The target subtype of a type_conversion is the subtype denoted by the subtype_mark. The operand of a type_conversion is the expression or name within the parentheses; its type is the operand type.
  4. One type is convertible to a second type if a type_conversion with the first type as operand type and the second type as target type is legal according to the rules of this clause. Two types are convertible if each is convertible to the other.
  5. A type_conversion whose operand is the name of an object is called a view conversion if its target type is tagged, or if it appears as an actual parameter of mode out or in out; other type_conversions are called value conversions.

    Name Resolution Rules
  6. The operand of a type_conversion is expected to be of any type.
  7. The operand of a view conversion is interpreted only as a name; the operand of a value conversion is interpreted as an expression.

    Legality Rules
  8. If the target type is a numeric type, then the operand type shall be a numeric type.
  9. If the target type is an array type, then the operand type shall be an array type. Further:
    1. The types shall have the same dimensionality;
    2. Corresponding index types shall be convertible; and
    3. The component subtypes shall statically match.
  1. If the target type is a general access type, then the operand type shall be an access-to-object type. Further:
    1. If the target type is an access-to-variable type, then the operand type shall be an access-to-variable type;
    2. If the target designated type is tagged, then the operand designated type shall be convertible to the target designated type;
    3. If the target designated type is not tagged, then the designated types shall be the same, and either the designated subtypes shall statically match or the target designated subtype shall be discriminated and unconstrained; and
    4. The accessibility level of the operand type shall not be statically deeper than that of the target type. In addition to the places where Legality Rules normally apply, see 12.3, this rule applies also in the private part of an instance of a generic unit.
  1. If the target type is an access-to-subprogram type, then the operand type shall be an access-to-subprogram type. Further:
    1. The designated profiles shall be subtype-conformant.
    2. The accessibility level of the operand type shall not be statically deeper than that of the target type. In addition to the places where Legality Rules normally apply, see 12.3, this rule applies also in the private part of an instance of a generic unit. If the operand type is declared within a generic body, the target type shall be declared within the generic body.
  1. If the target type is not included in any of the above four cases, there shall be a type that is an ancestor of both the target type and the operand type. Further, if the target type is tagged, then either:
    1. The operand type shall be covered by or descended from the target type; or
    2. The operand type shall be a class-wide type that covers the target type.
  1. In a view conversion for an untagged type, the target type shall be convertible (back) to the operand type.

    Static Semantics
  2. A type_conversion that is a value conversion denotes the value that is the result of converting the value of the operand to the target subtype.
  3. A type_conversion that is a view conversion denotes a view of the object denoted by the operand. This view is a variable of the target type if the operand denotes a variable; otherwise it is a constant of the target type.
  4. The nominal subtype of a type_conversion is its target subtype.

    Dynamic Semantics
  5. For the evaluation of a type_conversion that is a value conversion, the operand is evaluated, and then the value of the operand is converted to a corresponding value of the target type, if any. If there is no value of the target type that corresponds to the operand value, Constraint_Error is raised; this can only happen on conversion to a modular type, and only when the operand value is outside the base range of the modular type. Additional rules follow:
    1. Numeric Type Conversion
      1. If the target and the operand types are both integer types, then the result is the value of the target type that corresponds to the same mathematical integer as the operand.
      2. If the target type is a decimal fixed point type, then the result is truncated (toward 0) if the value of the operand is not a multiple of the small of the target type.
      3. If the target type is some other real type, then the result is within the accuracy of the target type (see "Numeric Performance Requirements", for implementations that support the Numerics Annex).
      4. If the target type is an integer type and the operand type is real, the result is rounded to the nearest integer (away from zero if exactly halfway between two integers).
    1. Enumeration Type Conversion
      1. The result is the value of the target type with the same position number as that of the operand value.
    1. Array Type Conversion
      1. If the target subtype is a constrained array subtype, then a check is made that the length of each dimension of the value of the operand equals the length of the corresponding dimension of the target subtype. The bounds of the result are those of the target subtype.
      2. If the target subtype is an unconstrained array subtype, then the bounds of the result are obtained by converting each bound of the value of the operand to the corresponding index type of the target type. For each nonnull index range, a check is made that the bounds of the range belong to the corresponding index subtype.
      3. In either array case, the value of each component of the result is that of the matching component of the operand value, see 4.5.2.
    1. Composite (Non-Array) Type Conversion
      1. The value of each nondiscriminant component of the result is that of the matching component of the operand value.
      2. The tag of the result is that of the operand. If the operand type is class-wide, a check is made that the tag of the operand identifies a (specific) type that is covered by or descended from the target type.
      3. For each discriminant of the target type that corresponds to a discriminant of the operand type, its value is that of the corresponding discriminant of the operand value; if it corresponds to more than one discriminant of the operand type, a check is made that all these discriminants are equal in the operand value.
      4. For each discriminant of the target type that corresponds to a discriminant that is specified by the derived_type_definition for some ancestor of the operand type (or if class-wide, some ancestor of the specific type identified by the tag of the operand), its value in the result is that specified by the derived_type_definition.
      5. For each discriminant of the operand type that corresponds to a discriminant that is specified by the derived_type_definition for some ancestor of the target type, a check is made that in the operand value it equals the value specified for it.
      6. For each discriminant of the result, a check is made that its value belongs to its subtype.
    1. Access Type Conversion
      1. For an access-to-object type, a check is made that the accessibility level of the operand type is not deeper than that of the target type.
      2. If the target type is an anonymous access type, a check is made that the value of the operand is not null; if the target is not an anonymous access type, then the result is null if the operand value is null.
      3. If the operand value is not null, then the result designates the same object (or subprogram) as is designated by the operand value, but viewed as being of the target designated subtype (or profile); any checks associated with evaluating a conversion to the target designated subtype are performed.
  1. After conversion of the value to the target type, if the target subtype is constrained, a check is performed that the value satisfies this constraint.
  2. For the evaluation of a view conversion, the operand name is evaluated, and a new view of the object denoted by the operand is created, whose type is the target type; if the target type is composite, checks are performed as above for a value conversion.
  3. The properties of this new view are as follows:
    1. If the target type is composite, the bounds or discriminants (if any) of the view are as defined above for a value conversion; each nondiscriminant component of the view denotes the matching component of the operand object; the subtype of the view is constrained if either the target subtype or the operand object is constrained, or if the operand type is a descendant of the target type, and has discriminants that were not inherited from the target type;
    2. If the target type is tagged, then an assignment to the view assigns to the corresponding part of the object denoted by the operand; otherwise, an assignment to the view assigns to the object, after converting the assigned value to the subtype of the object (which might raise Constraint_Error);
    3. Reading the value of the view yields the result of converting the value of the operand object to the target subtype (which might raise Constraint_Error), except if the object is of an access type and the view conversion is passed as an out parameter; in this latter case, the value of the operand object is used to initialize the formal parameter without checking against any constraint of the target subtype (see 6.4.1).
  1. If an Accessibility_Check fails, Program_Error is raised. Any other check associated with a conversion raises Constraint_Error if it fails.
  2. Conversion to a type is the same as conversion to an unconstrained subtype of the type.

    NOTES

  3. (20) In addition to explicit type_conversions, type conversions are performed implicitly in situations where the expected type and the actual type of a construct differ, as is permitted by the type resolution rules, see 8.6. For example, an integer literal is of the type universal_integer, and is implicitly converted when assigned to a target of some specific integer type. Similarly, an actual parameter of a specific tagged type is implicitly converted when the corresponding formal parameter is of a class-wide type.
  4. Even when the expected and actual types are the same, implicit subtype conversions are performed to adjust the array bounds (if any) of an operand to match the desired target subtype, or to raise Constraint_Error if the (possibly adjusted) value does not satisfy the constraints of the target subtype.
  5. (21) A ramification of the overload resolution rules is that the operand of an (explicit) type_conversion cannot be the literal null, an allocator, an aggregate, a string_literal, a character_literal, or an attribute_reference for an Access or Unchecked_Access attribute. Similarly, such an expression enclosed by parentheses is not allowed. A qualified_expression, see 4.7, can be used instead of such a type_conversion.
  6. (22) The constraint of the target subtype has no effect for a type_conversion of an elementary type passed as an out parameter. Hence, it is recommended that the first subtype be specified as the target to minimize confusion (a similar recommendation applies to renaming and generic formal in out objects).

    Examples
  7. Examples of numeric type conversion: 
  8. Real(2*J)      --  value is converted to floating point
Integer(1.6)   --  value is 2
Integer(-0.4)  --  value is 0
  9. Example of conversion between derived types: 
  10. type A_Form is new B_Form;

  11. X : A_Form;
Y : B_Form;

  12. X := A_Form(Y);
Y := B_Form(X);  --  the reverse conversion
  13. Examples of conversions between array types: 
  14. type Sequence is array (Integer range <>) of Integer;
subtype Dozen is Sequence(1 .. 12);
Ledger : array(1 .. 100) of Integer;

  15. Sequence(Ledger)            --  bounds are those of Ledger
Sequence(Ledger(31 .. 42))  --  bounds are 31 and 42
Dozen(Ledger(31 .. 42))     --  bounds are those of Dozen

Node:4.7, Next:, Previous:4.6, Up:4

Qualified Expressions

  1. A qualified_expression is used to state explicitly the type, and to verify the subtype, of an operand that is either an expression or an aggregate.

    Syntax
  2. qualified_expression ::=
   subtype_mark'(expression) | subtype_mark'aggregate

    Name Resolution Rules
  3. The operand (the expression or aggregate) shall resolve to be of the type determined by the subtype_mark, or a universal type that covers it.

    Dynamic Semantics
  4. The evaluation of a qualified_expression evaluates the operand (and if of a universal type, converts it to the type determined by the subtype_mark) and checks that its value belongs to the subtype denoted by the subtype_mark. The exception Constraint_Error is raised if this check fails.

    NOTES

  5. (23) When a given context does not uniquely identify an expected type, a qualified_expression can be used to do so. In particular, if an overloaded name or aggregate is passed to an overloaded subprogram, it might be necessary to qualify the operand to resolve its type.

    Examples
  6. Examples of disambiguating expressions using qualification: 
  7. type Mask is (Fix, Dec, Exp, Signif);
type Code is (Fix, Cla, Dec, Tnz, Sub);

  8. Print (Mask'(Dec));  --  Dec is of type Mask
Print (Code'(Dec));  --  Dec is of type Code

  9. for J in Code'(Fix) .. Code'(Dec) loop ...
-- qualification needed for either Fix or Dec

for J in Code range Fix .. Dec loop ...
-- qualification unnecessary

for J in Code'(Fix) .. Dec loop ...
-- qualification unnecessary for Dec

  10. Dozen'(1 | 3 | 5 | 7 => 2, others => 0) --  see 4.6

Node:4.8, Next:, Previous:4.7, Up:4

Allocators

  1. The evaluation of an allocator creates an object and yields an access value that designates the object.

    Syntax
  2. allocator ::=
   new subtype_indication | new qualified_expression

    Name Resolution Rules
  3. The expected type for an allocator shall be a single access-to-object type whose designated type covers the type determined by the subtype_mark of the subtype_indication or qualified_expression.

    Legality Rules
  4. An initialized allocator is an allocator with a qualified_expression. An uninitialized allocator is one with a subtype_indication. In the subtype_indication of an uninitialized allocator, a constraint is permitted only if the subtype_mark denotes an unconstrained composite subtype; if there is no constraint, then the subtype_mark shall denote a definite subtype.
  5. If the type of the allocator is an access-to-constant type, the allocator shall be an initialized allocator. If the designated type is limited, the allocator shall be an uninitialized allocator.

    Static Semantics
  6. If the designated type of the type of the allocator is elementary, then the subtype of the created object is the designated subtype. If the designated type is composite, then the created object is always constrained; if the designated subtype is constrained, then it provides the constraint of the created object; otherwise, the object is constrained by its initial value (even if the designated subtype is unconstrained with defaults).

    Dynamic Semantics
  7. For the evaluation of an allocator, the elaboration of the subtype_indication or the evaluation of the qualified_expression is performed first. For the evaluation of an initialized allocator, an object of the designated type is created and the value of the qualified_expression is converted to the designated subtype and assigned to the object.
  8. For the evaluation of an uninitialized allocator:
    1. If the designated type is elementary, an object of the designated subtype is created and any implicit initial value is assigned;
    2. If the designated type is composite, an object of the designated type is created with tag, if any, determined by the subtype_mark of the subtype_indication; any per-object constraints on subcomponents are elaborated and any implicit initial values for the subcomponents of the object are obtained as determined by the subtype_indication and assigned to the corresponding subcomponents. A check is made that the value of the object belongs to the designated subtype. Constraint_Error is raised if this check fails. This check and the initialization of the object are performed in an arbitrary order.
  1. If the created object contains any tasks, they are activated (see 9.2). Finally, an access value that designates the created object is returned.

    NOTES

  2. (24) Allocators cannot create objects of an abstract type (see 3.9.3).
  3. (25) If any part of the created object is controlled, the initialization includes calls on corresponding Initialize or Adjust procedures (see 7.6).
  4. (26) As explained in "Storage Management", the storage for an object allocated by an allocator comes from a storage pool (possibly user defined). The exception Storage_Error is raised by an allocator if there is not enough storage. Instances of Unchecked_Deallocation may be used to explicitly reclaim storage.
  5. (27) Implementations are permitted, but not required, to provide garbage collection, see 13.11.3.

    Examples
  6. Examples of allocators: 
  7. new Cell'(0, null, null)
-- initialized explicitly, see 3.10.1

new Cell'(Value => 0, Succ => null, Pred => null)
-- initialized explicitly

new Cell
-- not initialized

  8. new Matrix(1 .. 10, 1 .. 20)
-- the bounds only are given

new Matrix'(1 .. 10 => (1 .. 20 => 0.0))
-- initialized explicitly

  9. new Buffer(100)
-- the discriminant only is given

new Buffer'(Size => 80, Pos => 0, Value => (1 .. 80 => 'A'))
-- initialized explicitly

  10. Expr_Ptr'(new Literal)
-- allocator for access-to-class-wide type, see 3.9.1

Expr_Ptr'(new Literal'(Expression with 3.5))
-- initialized explicitly

Node:4.9, Next:, Previous:4.8, Up:4

Static Expressions and Static Subtypes

  1. Certain expressions of a scalar or string type are defined to be static. Similarly, certain discrete ranges are defined to be static, and certain scalar and string subtypes are defined to be static subtypes. Static means determinable at compile time, using the declared properties or values of the program entities.
  2. A static expression is a scalar or string expression that is one of the following:
    1. a numeric_literal;
    2. a string_literal of a static string subtype;
    3. a name that denotes the declaration of a named number or a static constant;
    4. a function_call whose function_name or function_prefix statically denotes a static function, and whose actual parameters, if any (whether given explicitly or by default), are all static expressions;
    5. an attribute_reference that denotes a scalar value, and whose prefix denotes a static scalar subtype;
    6. an attribute_reference whose prefix statically denotes a statically constrained array object or array subtype, and whose attribute_designator is First, Last, or Length, with an optional dimension;
    7. a type_conversion whose subtype_mark denotes a static scalar subtype, and whose operand is a static expression;
    8. a qualified_expression whose subtype_mark denotes a static (scalar or string) subtype, and whose operand is a static expression;
    9. a membership test whose simple_expression is a static expression, and whose range is a static range or whose subtype_mark denotes a static (scalar or string) subtype;
    10. a short-circuit control form both of whose relations are static expressions;
    11. a static expression enclosed in parentheses.
  1. A name statically denotes an entity if it denotes the entity and:
    1. It is a direct_name, expanded name, or character_literal, and it denotes a declaration other than a renaming_declaration; or
    2. It is an attribute_reference whose prefix statically denotes some entity; or
    3. It denotes a renaming_declaration with a name that statically denotes the renamed entity.
  1. A static function is one of the following:
    1. a predefined operator whose parameter and result types are all scalar types none of which are descendants of formal scalar types;
    2. a predefined concatenation operator whose result type is a string type;
    3. an enumeration literal;
    4. a language-defined attribute that is a function, if the prefix denotes a static scalar subtype, and if the parameter and result types are scalar.
  1. In any case, a generic formal subprogram is not a static function.
  2. A static constant is a constant view declared by a full constant declaration or an object_renaming_declaration with a static nominal subtype, having a value defined by a static scalar expression or by a static string expression whose value has a length not exceeding the maximum length of a string_literal in the implementation.
  3. A static range is a range whose bounds are static expressions, or a range_attribute_reference that is equivalent to such a range. A static discrete_range is one that is a static range or is a subtype_indication that defines a static scalar subtype. The base range of a scalar type is a static range, unless the type is a descendant of a formal scalar type.
  4. A static subtype is either a static scalar subtype or a static string subtype. A static scalar subtype is an unconstrained scalar subtype whose type is not a descendant of a formal scalar type, or a constrained scalar subtype formed by imposing a compatible static constraint on a static scalar subtype. A static string subtype is an unconstrained string subtype whose index subtype and component subtype are static (and whose type is not a descendant of a formal array type), or a constrained string subtype formed by imposing a compatible static constraint on a static string subtype. In any case, the subtype of a generic formal object of mode in out, and the result subtype of a generic formal function, are not static.
  5. The different kinds of static constraint are defined as follows:
    1. A null constraint is always static;
    2. A scalar constraint is static if it has no range_constraint, or one with a static range;
    3. An index constraint is static if each discrete_range is static, and each index subtype of the corresponding array type is static;
    4. A discriminant constraint is static if each expression of the constraint is static, and the subtype of each discriminant is static.
  1. A subtype is statically constrained if it is constrained, and its constraint is static. An object is statically constrained if its nominal subtype is statically constrained, or if it is a static string constant.

    Legality Rules
  2. A static expression is evaluated at compile time except when it is part of the right operand of a static short-circuit control form whose value is determined by its left operand. This evaluation is performed exactly, without performing Overflow_Checks. For a static expression that is evaluated:
    1. The expression is illegal if its evaluation fails a language-defined check other than Overflow_Check.
    2. If the expression is not part of a larger static expression, then its value shall be within the base range of its expected type. Otherwise, the value may be arbitrarily large or small.
    3. If the expression is of type universal_real and its expected type is a decimal fixed point type, then its value shall be a multiple of the small of the decimal type.
  1. The last two restrictions above do not apply if the expected type is a descendant of a formal scalar type (or a corresponding actual type in an instance).

    Implementation Requirements
  2. For a real static expression that is not part of a larger static expression, and whose expected type is not a descendant of a formal scalar type, the implementation shall round or truncate the value (according to the Machine_Rounds attribute of the expected type) to the nearest machine number of the expected type; if the value is exactly half-way between two machine numbers, any rounding shall be performed away from zero. If the expected type is a descendant of a formal scalar type, no special rounding or truncating is required - normal accuracy rules apply, see G.

    NOTES

  3. (28) An expression can be static even if it occurs in a context where staticness is not required.
  4. (29) A static (or run-time) type_conversion from a real type to an integer type performs rounding. If the operand value is exactly half-way between two integers, the rounding is performed away from zero.

    Examples
  5. Examples of static expressions: 
  6. 1 + 1       -- 2
abs(-10)*3  -- 30

  7. Kilo : constant := 1000;
Mega : constant := Kilo*Kilo;   -- 1_000_000
Long : constant := Float'Digits*2;

  8. Half_Pi    : constant := Pi/2;
--  see 3.3.2.

Deg_To_Rad : constant := Half_Pi/90;

Rad_To_Deg : constant := 1.0/Deg_To_Rad;
-- equivalent to 1.0/((3.14159_26536/2)/90)

Node:4.9.1, Next:, Previous:4.9, Up:4.9

Statically Matching Constraints and Subtypes


Static Semantics
  1. A constraint statically matches another constraint if both are null constraints, both are static and have equal corresponding bounds or discriminant values, or both are nonstatic and result from the same elaboration of a constraint of a subtype_indication or the same evaluation of a range of a discrete_subtype_definition.
  2. A subtype statically matches another subtype of the same type if they have statically matching constraints. Two anonymous access subtypes statically match if their designated subtypes statically match.
  3. Two ranges of the same type statically match if both result from the same evaluation of a range, or if both are static and have equal corresponding bounds.
  4. A constraint is statically compatible with a scalar subtype if it statically matches the constraint of the subtype, or if both are static and the constraint is compatible with the subtype. A constraint is statically compatible with an access or composite subtype if it statically matches the constraint of the subtype, or if the subtype is unconstrained. One subtype is statically compatible with a second subtype if the constraint of the first is statically compatible with the second subtype.

Node:5, Next:, Previous:4.9.1, Up:Top

Statements

  1. A statement defines an action to be performed upon its execution.
  2. This section describes the general rules applicable to all statements. Some statements are discussed in later sections: Procedure_call_statements and return_statements are described in "Subprograms". Entry_call_statements, requeue_statements, delay_statements, accept_statements, select_statements, and abort_statements are described in "Tasks and Synchronization". Raise_statements are described in "Exceptions", and code_statements in 13. The remaining forms of statements are presented in this section.

Node:5.1, Next:, Previous:5, Up:5

Simple and Compound Statements - Sequences of Statements

  1. A statement is either simple or compound. A simple_statement encloses no other statement. A compound_statement can enclose simple_statements and other compound_statements.

    Syntax
  2. sequence_of_statements ::= statement {statement}

  3. statement ::=
   {label} simple_statement | {label} compound_statement

  4. simple_statement ::= null_statement
   | assignment_statement   | exit_statement
   | goto_statement         | procedure_call_statement
   | return_statement       | entry_call_statement
   | requeue_statement      | delay_statement
   | abort_statement        | raise_statement
   | code_statement

  5. compound_statement ::=
     if_statement           | case_statement
   | loop_statement         | block_statement
   | accept_statement       | select_statement

  6. null_statement ::= null;

  7. label ::= <<label_statement_identifier>>

  8. statement_identifier ::= direct_name
    1. The direct_name of a statement_identifier shall be an identifier (not an operator_symbol).

Name Resolution Rules
  1. The direct_name of a statement_identifier shall resolve to denote its corresponding implicit declaration (see below).

    Legality Rules
  2. Distinct identifiers shall be used for all statement_identifiers that appear in the same body, including inner block_statements but excluding inner program units.

    Static Semantics
  3. For each statement_identifier, there is an implicit declaration (with the specified identifier) at the end of the declarative_part of the innermost block_statement or body that encloses the statement_identifier. The implicit declarations occur in the same order as the statement_identifiers occur in the source text. If a usage name denotes such an implicit declaration, the entity it denotes is the label, loop_statement, or block_statement with the given statement_identifier.

    Dynamic Semantics
  4. The execution of a null_statement has no effect.
  5. A transfer of control is the run-time action of an exit_statement, return_statement, goto_statement, or requeue_statement, selection of a terminate_alternative, raising of an exception, or an abort, which causes the next action performed to be one other than what would normally be expected from the other rules of the language. As explained in 7.6.1, a transfer of control can cause the execution of constructs to be completed and then left, which may trigger finalization.
  6. The execution of a sequence_of_statements consists of the execution of the individual statements in succession until the sequence_ is completed.

    NOTES

  7. (1) A statement_identifier that appears immediately within the declarative region of a named loop_statement or an accept_statement is nevertheless implicitly declared immediately within the declarative region of the innermost enclosing body or block_statement; in other words, the expanded name for a named statement is not affected by whether the statement occurs inside or outside a named loop or an accept_statement - only nesting within block_statements is relevant to the form of its expanded name.

    Examples
  8. Examples of labeled statements: 
  9. <<Here>> <<Ici>> <<Aqui>> <<Hier>> null;

  10. <<After>> X := 1;

Node:5.2, Next:, Previous:5.1, Up:5

Assignment Statements

  1. An assignment_statement replaces the current value of a variable with the result of evaluating an expression.

    Syntax
  2. assignment_statement ::= variable_name := expression;
  3. The execution of an assignment_statement includes the evaluation of the expression and the assignment of the value of the expression into the target. An assignment operation (as opposed to an assignment_statement) is performed in other contexts as well, including object initialization and by-copy parameter passing. The target of an assignment operation is the view of the object to which a value is being assigned; the target of an assignment_statement is the variable denoted by the variable_name.

    Name Resolution Rules
  4. The variable_name of an assignment_statement is expected to be of any nonlimited type. The expected type for the expression is the type of the target.

    Legality Rules
  5. The target denoted by the variable_name shall be a variable.
  6. If the target is of a tagged class-wide type T'Class, then the expression shall either be dynamically tagged, or of type T and tag-indeterminate, see 3.9.2.

    Dynamic Semantics
  7. For the execution of an assignment_statement, the variable_name and the expression are first evaluated in an arbitrary order.
  8. When the type of the target is class-wide:
    1. If the expression is tag-indeterminate, see 3.9.2, then the controlling tag value for the expression is the tag of the target;
    2. Otherwise (the expression is dynamically tagged), a check is made that the tag of the value of the expression is the same as that of the target; if this check fails, Constraint_Error is raised.
  1. The value of the expression is converted to the subtype of the target. The conversion might raise an exception, see 4.6.
  2. In cases involving controlled types, the target is finalized, and an anonymous object might be used as an intermediate in the assignment, as described in "Completion and Finalization". In any case, the converted value of the expression is then assigned to the target, which consists of the following two steps:
    1. The value of the target becomes the converted value.
    2. If any part of the target is controlled, its value is adjusted as explained in 7.6.

    NOTES

  1. (2) The tag of an object never changes; in particular, an assignment_statement does not change the tag of the target.
  2. (3) The values of the discriminants of an object designated by an access value cannot be changed (not even by assigning a complete value to the object itself) since such objects are always constrained; however, subcomponents of such objects may be unconstrained.

    Examples
  3. Examples of assignment statements: 
  4. Value := Max_Value - 1;
Shade := Blue;

  5. Next_Frame(F)(M, N) := 2.5;  --  see 4.1.1
U := Dot_Product(V, W);      --  see 6.3

  6. Writer := (Status => Open, Unit => Printer, Line_Count => 60);
--  see 3.8.1

Next_Car.all := (72074, null);
--  see 3.10.1
  7. Examples involving scalar subtype conversions: 
  8. I, J : Integer range 1 .. 10 := 5;
K    : Integer range 1 .. 20 := 15;
 ...

  9. I := J;  --  identical ranges
K := J;  --  compatible ranges
J := K;  --  will raise Constraint_Error if K > 10
  10. Examples involving array subtype conversions: 
  11. A : String(1 .. 31);
B : String(3 .. 33);
 ...

  12. A := B;  --  same number of components

  13. A(1 .. 9)  := "tar sauce";
A(4 .. 12) := A(1 .. 9);  --  A(1 .. 12) = "tartar sauce"

    NOTES

  14. (4) Notes on the examples: Assignment_statements are allowed even in the case of overlapping slices of the same array, because the variable_name and expression are both evaluated before copying the value into the variable. In the above example, an implementation yielding A(1 .. 12) = "tartartartar" would be incorrect.

Node:5.3, Next:, Previous:5.2, Up:5

If Statements

  1. An if_statement selects for execution at most one of the enclosed sequences_of_statements, depending on the (truth) value of one or more corresponding conditions.

    Syntax
  2. if_statement ::=
    if condition then
       sequence_of_statements
    {elsif condition then
       sequence_of_statements}
    [else
       sequence_of_statements]
    end if;

  3. condition ::= boolean_expression

    Name Resolution Rules
  4. A condition is expected to be of any boolean type.

    Dynamic Semantics
  5. For the execution of an if_statement, the condition specified after if, and any conditions specified after elsif, are evaluated in succession (treating a final else as elsif True then), until one evaluates to True or all conditions are evaluated and yield False. If a condition evaluates to True, then the corresponding sequence_of_statements is executed; otherwise none of them is executed.

    Examples
  6. Examples of if statements: 
  7. if Month = December and Day = 31 then
   Month := January;
   Day   := 1;
   Year  := Year + 1;
end if;

  8. if Line_Too_Short then
   raise Layout_Error;
elsif Line_Full then
   New_Line;
   Put(Item);
else
   Put(Item);
end if;

  9. if My_Car.Owner.Vehicle /= My_Car then  --  see 3.10.1
   Report ("Incorrect data");
end if;

Node:5.4, Next:, Previous:5.3, Up:5

Case Statements

  1. A case_statement selects for execution one of a number of alternative sequences_of_statements; the chosen alternative is defined by the value of an expression.

    Syntax
  2. case_statement ::=
   case expression is
      case_statement_alternative
      {case_statement_alternative}
   end case;

  3. case_statement_alternative ::=
   when discrete_choice_list =>
      sequence_of_statements

    Name Resolution Rules
  4. The expression is expected to be of any discrete type. The expected type for each discrete_choice is the type of the expression.

    Legality Rules
  5. The expressions and discrete_ranges given as discrete_choices of a case_statement shall be static. A discrete_choice others, if present, shall appear alone and in the last discrete_choice_list.
  6. The possible values of the expression shall be covered as follows:
    1. If the expression is a name (including a type_conversion or a function_call) having a static and constrained nominal subtype, or is a qualified_expression whose subtype_mark denotes a static and constrained scalar subtype, then each non-others discrete_choice shall cover only values in that subtype, and each value of that subtype shall be covered by some discrete_choice (either explicitly or by others).
    2. If the type of the expression is root_integer, universal_integer, or a descendant of a formal scalar type, then the case_statement shall have an others discrete_choice.
    3. Otherwise, each value of the base range of the type of the expression shall be covered (either explicitly or by others).
  1. Two distinct discrete_choices of a case_statement shall not cover the same value.

    Dynamic Semantics
  2. For the execution of a case_statement the expression is first evaluated.
  3. If the value of the expression is covered by the discrete_choice_list of some case_statement_alternative, then the sequence_of_statements of the _alternative is executed.
  4. Otherwise (the value is not covered by any discrete_choice_list, perhaps due to being outside the base range), Constraint_Error is raised.

    NOTES

  5. (5) The execution of a case_statement chooses one and only one alternative. Qualification of the expression of a case_statement by a static subtype can often be used to limit the number of choices that need be given explicitly.

    Examples
  6. Examples of case statements: 
  7. case Sensor is
   when Elevation  => Record_Elevation(Sensor_Value);
   when Azimuth    => Record_Azimuth  (Sensor_Value);
   when Distance   => Record_Distance (Sensor_Value);
   when others     => null;
end case;

  8. case Today is
   when Mon        => Compute_Initial_Balance;
   when Fri        => Compute_Closing_Balance;
   when Tue .. Thu => Generate_Report(Today);
   when Sat .. Sun => null;
end case;

  9. case Bin_Number(Count) is
   when 1      => Update_Bin(1);
   when 2      => Update_Bin(2);
   when 3 | 4  =>
      Empty_Bin(1);
      Empty_Bin(2);
   when others => raise Error;
end case;

Node:5.5, Next:, Previous:5.4, Up:5

Loop Statements

  1. A loop_statement includes a sequence_of_statements that is to be executed repeatedly, zero or more times.

    Syntax
  2. loop_statement ::=
   [loop_statement_identifier:]
      [iteration_scheme] loop
         sequence_of_statements
      end loop [loop_identifier];

  3. iteration_scheme ::= while condition
   | for loop_parameter_specification

  4. loop_parameter_specification ::=
   defining_identifier in [reverse] discrete_subtype_definition
    1. If a loop_statement has a loop_statement_identifier, then the identifier shall be repeated after the end loop; otherwise, there shall not be an identifier after the end loop.

Static Semantics
  1. A loop_parameter_specification declares a loop parameter, which is an object whose subtype is that defined by the discrete_subtype_definition.

    Dynamic Semantics
  2. For the execution of a loop_statement, the sequence_of_statements is executed repeatedly, zero or more times, until the loop_statement is complete. The loop_statement is complete when a transfer of control occurs that transfers control out of the loop, or, in the case of an iteration_scheme, as specified below.
  3. For the execution of a loop_statement with a while iteration_scheme, the condition is evaluated before each execution of the sequence_of_statements; if the value of the condition is True, the sequence_of_statements is executed; if False, the execution of the loop_statement is complete.
  4. For the execution of a loop_statement with a for iteration_scheme, the loop_parameter_specification is first elaborated. This elaboration creates the loop parameter and elaborates the discrete_subtype_definition. If the discrete_subtype_definition defines a subtype with a null range, the execution of the loop_statement is complete. Otherwise, the sequence_of_statements is executed once for each value of the discrete subtype defined by the discrete_subtype_definition (or until the loop is left as a consequence of a transfer of control). Prior to each such iteration, the corresponding value of the discrete subtype is assigned to the loop parameter. These values are assigned in increasing order unless the reserved word reverse is present, in which case the values are assigned in decreasing order.

    NOTES

  5. (6) A loop parameter is a constant; it cannot be updated within the sequence_of_statements of the loop, see 3.3.
  6. (7) An object_declaration should not be given for a loop parameter, since the loop parameter is automatically declared by the loop_parameter_specification. The scope of a loop parameter extends from the loop_parameter_specification to the end of the loop_statement, and the visibility rules are such that a loop parameter is only visible within the sequence_of_statements of the loop.
  7. (8) The discrete_subtype_definition of a for loop is elaborated just once. Use of the reserved word reverse does not alter the discrete subtype defined, so that the following iteration_schemes are not equivalent; the first has a null range. 
  8. for J in reverse 1 ..  0
for J in 0 .. 1

    Examples
  9. Example of a loop statement without an iteration scheme: 
  10. loop
   Get(Current_Character);
   exit when Current_Character = '*';
end loop;
  11. Example of a loop statement with a while iteration scheme: 
  12. while Bid(N).Price < Cut_Off.Price loop
   Record_Bid(Bid(N).Price);
   N := N + 1;
end loop;
  13. Example of a loop statement with a for iteration scheme: 
  14. for J in Buffer'Range loop  --  works even with a null range
   if Buffer(J) /= Space then
      Put(Buffer(J));
   end if;
end loop;
  15. Example of a loop statement with a name: 
  16. Summation:
   while Next /= Head loop  --  see 3.10.1
      Sum  := Sum + Next.Value;
      Next := Next.Succ;
   end loop Summation;

Node:5.6, Next:, Previous:5.5, Up:5

Block Statements

  1. A block_statement encloses a handled_sequence_of_statements optionally preceded by a declarative_part.

    Syntax
  2. block_statement ::=
   [block_statement_identifier:]
      [declare
         declarative_part]
      begin
         handled_sequence_of_statements
      end [block_identifier];
    1. If a block_statement has a block_statement_identifier, then the identifier shall be repeated after the end; otherwise, there shall not be an identifier after the end.

Static Semantics
  1. A block_statement that has no explicit declarative_part has an implicit empty declarative_part.

    Dynamic Semantics
  2. The execution of a block_statement consists of the elaboration of its declarative_part followed by the execution of its handled_sequence_of_statements.

    Examples
  3. Example of a block statement with a local variable: 
  4. Swap:
   declare
      Temp : Integer;
   begin
      Temp := V; V := U; U := Temp;
   end Swap;

Node:5.7, Next:, Previous:5.6, Up:5

Exit Statements

  1. An exit_statement is used to complete the execution of an enclosing loop_statement; the completion is conditional if the exit_statement includes a condition.

    Syntax
  2. exit_statement ::= exit [loop_name] [when condition];

    Name Resolution Rules
  3. The loop_name, if any, in an exit_statement shall resolve to denote a loop_statement.

    Legality Rules
  4. Each exit_statement applies to a loop_statement; this is the loop_statement being exited. An exit_statement with a name is only allowed within the loop_statement denoted by the name, and applies to that loop_statement. An exit_statement without a name is only allowed within a loop_statement, and applies to the innermost enclosing one. An exit_statement that applies to a given loop_statement shall not appear within a body or accept_statement, if this construct is itself enclosed by the given loop_statement.

    Dynamic Semantics
  5. For the execution of an exit_statement, the condition, if present, is first evaluated. If the value of the condition is True, or if there is no condition, a transfer of control is done to complete the loop_statement. If the value of the condition is False, no transfer of control takes place.

    NOTES

  6. (9) Several nested loops can be exited by an exit_statement that names the outer loop.

    Examples
  7. Examples of loops with exit statements: 
  8. for N in 1 .. Max_Num_Items loop
   Get_New_Item(New_Item);
   Merge_Item(New_Item, Storage_File);
   exit when New_Item = Terminal_Item;
end loop;

  9. Main_Cycle:
   loop
      --  initial statements
      exit Main_Cycle when Found;
      --  final statements
   end loop Main_Cycle;

Node:5.8, Next:, Previous:5.7, Up:5

Goto Statements

  1. A goto_statement specifies an explicit transfer of control from this statement to a target statement with a given label.

    Syntax
  2. goto_statement ::= goto label_name;

    Name Resolution Rules
  3. The label_name shall resolve to denote a label; the statement with that label is the target statement.

    Legality Rules
  4. The innermost sequence_of_statements that encloses the target statement shall also enclose the goto_statement. Furthermore, if a goto_statement is enclosed by an accept_statement or a body, then the target statement shall not be outside this enclosing construct.

    Dynamic Semantics
  5. The execution of a goto_statement transfers control to the target statement, completing the execution of any compound_statement that encloses the goto_statement but does not enclose the target.

    NOTES

  6. (10) The above rules allow transfer of control to a statement of an enclosing sequence_of_statements but not the reverse. Similarly, they prohibit transfers of control such as between alternatives of a case_statement, if_statement, or select_statement; between exception_handlers; or from an exception_handler of a handled_sequence_of_statements back to its sequence_of_statements.

    Examples
  7. Example of a loop containing a goto statement: 
  8. <<Sort>>
for I in 1 .. N-1 loop
   if A(I) > A(I+1) then
      Exchange(A(I), A(I+1));
      goto Sort;
   end if;
end loop;

Node:6, Next:, Previous:5.8, Up:Top

Subprograms

  1. A subprogram is a program unit or intrinsic operation whose execution is invoked by a subprogram call. There are two forms of subprogram: procedures and functions. A procedure call is a statement; a function call is an expression and returns a value. The definition of a subprogram can be given in two parts: a subprogram declaration defining its interface, and a subprogram_body defining its execution. Operators and enumeration literals are functions.
  2. A callable entity is a subprogram or entry, see 9. A callable entity is invoked by a call; that is, a subprogram call or entry call. A callable construct is a construct that defines the action of a call upon a callable entity: a subprogram_body, entry_body, or accept_statement.

Node:6.1, Next:, Previous:6, Up:6

Subprogram Declarations

  1. A subprogram_declaration declares a procedure or function.

    Syntax
  2. subprogram_declaration ::= subprogram_specification;

  3. abstract_subprogram_declaration ::=
   subprogram_specification is abstract;

  4. subprogram_specification ::=
     procedure defining_program_unit_name parameter_profile
   | function defining_designator parameter_and_result_profile

  5. designator ::= [parent_unit_name . ]identifier | operator_symbol

  6. defining_designator ::=
   defining_program_unit_name | defining_operator_symbol

  7. defining_program_unit_name ::=
   [parent_unit_name . ]defining_identifier
    1. The optional parent_unit_name is only allowed for library units (see 10.1.1). 
  1. operator_symbol ::= string_literal
    1. The sequence of characters in an operator_symbol shall correspond to an operator belonging to one of the six classes of operators defined in clause 4.5 (spaces are not allowed and the case of letters is not significant). 
  1. defining_operator_symbol ::= operator_symbol

  2. parameter_profile ::= [formal_part]

  3. parameter_and_result_profile ::= [formal_part] return subtype_mark

  4. formal_part ::=
   (parameter_specification {; parameter_specification{)

  5. parameter_specification ::=
    defining_identifier_list : mode subtype_mark
      [:= default_expression]
  | defining_identifier_list : access_definition
      [:= default_expression]

  6. mode ::= [in] | in out | out

    Name Resolution Rules
  7. A formal parameter is an object directly visible within a subprogram_body that represents the actual parameter passed to the subprogram in a call; it is declared by a parameter_specification. For a formal parameter, the expected type for its default_expression, if any, is that of the formal parameter.

    Legality Rules
  8. The parameter mode of a formal parameter conveys the direction of information transfer with the actual parameter: in, in out, or out. Mode in is the default, and is the mode of a parameter defined by an access_definition. The formal parameters of a function, if any, shall have the mode in.
  9. A default_expression is only allowed in a parameter_specification for a formal parameter of mode in.
  10. A subprogram_declaration or a generic_subprogram_declaration requires a completion: a body, a renaming_declaration, see 8.5, or a pragma Import, see B.1. A completion is not allowed for an abstract_subprogram_declaration.
  11. A name that denotes a formal parameter is not allowed within the formal_part in which it is declared, nor within the formal_part of a corresponding body or accept_statement.

    Static Semantics
  12. The profile of (a view of) a callable entity is either a parameter_profile or parameter_and_result_profile; it embodies information about the interface to that entity - for example, the profile includes information about parameters passed to the callable entity. All callable entities have a profile - enumeration literals, other subprograms, and entries. An access-to-subprogram type has a designated profile. Associated with a profile is a calling convention. A subprogram_declaration declares a procedure or a function, as indicated by the initial reserved word, with name and profile as given by its specification.
  13. The nominal subtype of a formal parameter is the subtype denoted by the subtype_mark, or defined by the access_definition, in the parameter_specification.
  14. An access parameter is a formal in parameter specified by an access_definition. An access parameter is of an anonymous general access-to-variable type, see 3.10. Access parameters allow dispatching calls to be controlled by access values.
  15. The subtypes of a profile are:
    1. For any non-access parameters, the nominal subtype of the parameter.
    2. For any access parameters, the designated subtype of the parameter type.
    3. For any result, the result subtype.
  1. The types of a profile are the types of those subtypes.
  2. A subprogram declared by an abstract_subprogram_declaration is abstract; a subprogram declared by a subprogram_declaration is not (see "Abstract Types and Subprograms").

    Dynamic Semantics
  3. The elaboration of a subprogram_declaration or an abstract_subprogram_declaration has no effect.

    NOTES

  4. (1) A parameter_specification with several identifiers is equivalent to a sequence of single parameter_specifications, as explained in 3.3.
  5. (2) Abstract subprograms do not have bodies, and cannot be used in a nondispatching call, see "Abstract Types and Subprograms".
  6. (3) The evaluation of default_expressions is caused by certain calls, as described in 6.4.1. They are not evaluated during the elaboration of the subprogram declaration.
  7. (4) Subprograms can be called recursively and can be called concurrently from multiple tasks.

    Examples
  8. Examples of subprogram declarations: 
  9. procedure Traverse_Tree;
procedure Increment(X : in out Integer);
procedure Right_Indent(Margin : out Line_Size); --  see 3.5.4
procedure Switch(From, To : in out Link);       --  see 3.10.1

  10. function Random return Probability;             --  see 3.5.7

  11. function Min_Cell(X : Link) return Cell;        --  see 3.10.1
function Next_Frame(K : Positive) return Frame; --  see 3.10
function Dot_Product(Left, Right : Vector) return Real;
--  see 3.6

  12. function "*"(Left, Right : Matrix) return Matrix;
--  see 3.6
  13. Examples of in parameters with default expressions: 
  14. procedure Print_Header
  (Pages  : in Natural;
   Header : in Line    :=  (1 .. Line'Last => ' '); --  see 3.6
   Center : in Boolean := True);

Node:6.2, Next:, Previous:6.1, Up:6

Formal Parameter Modes

  1. A parameter_specification declares a formal parameter of mode in, in out, or out.

    Static Semantics
  2. A parameter is passed either by copy or by reference. When a parameter is passed by copy, the formal parameter denotes a separate object from the actual parameter, and any information transfer between the two occurs only before and after executing the subprogram. When a parameter is passed by reference, the formal parameter denotes (a view of) the object denoted by the actual parameter; reads and updates of the formal parameter directly reference the actual parameter object.
  3. A type is a by-copy type if it is an elementary type, or if it is a descendant of a private type whose full type is a by-copy type. A parameter of a by-copy type is passed by copy.
  4. A type is a by-reference type if it is a descendant of one of the following:
    1. a tagged type;
    2. a task or protected type;
    3. a nonprivate type with the reserved word limited in its declaration;
    4. a composite type with a subcomponent of a by-reference type;
    5. a private type whose full type is a by-reference type.
  1. A parameter of a by-reference type is passed by reference. Each value of a by-reference type has an associated object. For a parenthesized expression, qualified_expression, or type_conversion, this object is the one associated with the operand.
  2. For parameters of other types, it is unspecified whether the parameter is passed by copy or by reference.

    Bounded (Run-Time) Errors
  3. If one name denotes a part of a formal parameter, and a second name denotes a part of a distinct formal parameter or an object that is not part of a formal parameter, then the two names are considered distinct access paths. If an object is of a type for which the parameter passing mechanism is not specified, then it is a bounded error to assign to the object via one access path, and then read the value of the object via a distinct access path, unless the first access path denotes a part of a formal parameter that no longer exists at the point of the second access (due to leaving the corresponding callable construct). The possible consequences are that Program_Error is raised, or the newly assigned value is read, or some old value of the object is read.

    NOTES

  4. (5) A formal parameter of mode in is a constant view, see 3.3, it cannot be updated within the subprogram_body.

Node:6.3, Next:, Previous:6.2, Up:6

Subprogram Bodies

  1. A subprogram_body specifies the execution of a subprogram.

    Syntax
  2. subprogram_body ::=
   subprogram_specification is
      declarative_part
   begin
      handled_sequence_of_statements
   end [designator];
    1. If a designator appears at the end of a subprogram_body, it shall repeat the defining_designator of the subprogram_specification.

Legality Rules
  1. In contrast to other bodies, a subprogram_body need not be the completion of a previous declaration, in which case the body declares the subprogram. If the body is a completion, it shall be the completion of a subprogram_declaration or generic_subprogram_declaration. The profile of a subprogram_body that completes a declaration shall conform fully to that of the declaration.

    Static Semantics
  2. A subprogram_body is considered a declaration. It can either complete a previous declaration, or itself be the initial declaration of the subprogram.

    Dynamic Semantics
  3. The elaboration of a non-generic subprogram_body has no other effect than to establish that the subprogram can from then on be called without failing the Elaboration_Check.
  4. The execution of a subprogram_body is invoked by a subprogram call. For this execution the declarative_part is elaborated, and the handled_sequence_of_statements is then executed.

    Examples
  5. Example of procedure body: 
  6. procedure Push(E : in Element_Type; S : in out Stack) is
begin
   if S.Index = S.Size then
      raise Stack_Overflow;
   else
      S.Index := S.Index + 1;
      S.Space(S.Index) := E;
   end if;
end Push;
  7. Example of a function body: 
  8. function Dot_Product(Left, Right : Vector) return Real is
   Sum : Real := 0.0;
begin
   Check(Left'First = Right'First and Left'Last = Right'Last);
   for J in Left'Range loop
      Sum := Sum + Left(J)*Right(J);
   end loop;
   return Sum;
end Dot_Product;

Node:6.3.1, Next:, Previous:6.3, Up:6.3

Conformance Rules

  1. When subprogram profiles are given in more than one place, they are required to conform in one of four ways: type conformance, mode conformance, subtype conformance, or full conformance.

    Static Semantics
  2. As explained in "Interfacing Pragmas", a convention can be specified for an entity. For a callable entity or access-to-subprogram type, the convention is called the calling convention. The following conventions are defined by the language:
    1. The default calling convention for any subprogram not listed below is Ada. A pragma Convention, Import, or Export may be used to override the default calling convention, see B.1.
    2. The Intrinsic calling convention represents subprograms that are "built in" to the compiler. The default calling convention is Intrinsic for the following:
        1. an enumeration literal;
        2. a "/=" operator declared implicitly due to the declaration of "=" (see 6.6);
        3. any other implicitly declared subprogram unless it is a dispatching operation of a tagged type;
        4. an inherited subprogram of a generic formal tagged type with unknown discriminants;
        5. an attribute that is a subprogram;
        6. a subprogram declared immediately within a protected_body.
      1. The Access attribute is not allowed for Intrinsic subprograms.
    1. The default calling convention is protected for a protected subprogram, and for an access-to-subprogram type with the reserved word protected in its definition.
    2. The default calling convention is entry for an entry.
  1. Of these four conventions, only Ada and Intrinsic are allowed as a convention_identifier in a pragma Convention, Import, or Export.
  2. Two profiles are type conformant if they have the same number of parameters, and both have a result if either does, and corresponding parameter and result types are the same, or, for access parameters, corresponding designated types are the same.
  3. Two profiles are mode conformant if they are type-conformant, and corresponding parameters have identical modes, and, for access parameters, the designated subtypes statically match.
  4. Two profiles are subtype conformant if they are mode-conformant, corresponding subtypes of the profile statically match, and the associated calling conventions are the same. The profile of a generic formal subprogram is not subtype-conformant with any other profile.
  5. Two profiles are fully conformant if they are subtype-conformant, and corresponding parameters have the same names and have default_expressions that are fully conformant with one another.
  6. Two expressions are fully conformant if, after replacing each use of an operator with the equivalent function_call:
    1. each constituent construct of one corresponds to an instance of the same syntactic category in the other, except that an expanded name may correspond to a direct_name (or character_literal) or to a different expanded name in the other; and
    2. each direct_name, character_literal, and selector_name that is not part of the prefix of an expanded name in one denotes the same declaration as the corresponding direct_name, character_literal, or selector_name in the other; and
    3. each primary that is a literal in one has the same value as the corresponding literal in the other.
  1. Two known_discriminant_parts are fully conformant if they have the same number of discriminants, and discriminants in the same positions have the same names, statically matching subtypes, and default_expressions that are fully conformant with one another.
  2. Two discrete_subtype_definitions are fully conformant if they are both subtype_indications or are both ranges, the subtype_marks (if any) denote the same subtype, and the corresponding simple_expressions of the ranges (if any) fully conform.

    Implementation Permissions
  3. An implementation may declare an operator declared in a language-defined library unit to be intrinsic.

Node:6.3.2, Next:, Previous:6.3.1, Up:6.3

Inline Expansion of Subprograms

  1. Subprograms may be expanded in line at the call site.

    Syntax
  2. The form of a pragma Inline, which is a program unit pragma (see 10.1.5) is as follows: 
  3. pragma Inline(name {, name{);

    Legality Rules
  4. The pragma shall apply to one or more callable entities or generic subprograms.

    Static Semantics
  5. If a pragma Inline applies to a callable entity, this indicates that inline expansion is desired for all calls to that entity. If a pragma Inline applies to a generic subprogram, this indicates that inline expansion is desired for all calls to all instances of that generic subprogram.

    Implementation Permissions
  6. For each call, an implementation is free to follow or to ignore the recommendation expressed by the pragma.

    NOTES

  7. (6) The name in a pragma Inline can denote more than one entity in the case of overloading. Such a pragma applies to all of the denoted entities.

Node:6.4, Next:, Previous:6.3.2, Up:6

Subprogram Calls

  1. A subprogram call is either a procedure_call_statement or a function_call; it invokes the execution of the subprogram_body. The call specifies the association of the actual parameters, if any, with formal parameters of the subprogram.

    Syntax
  2. procedure_call_statement ::=
     procedure_name;
   | procedure_prefix actual_parameter_part;

  3. function_call ::=
     function_name
   | function_prefix actual_parameter_part

  4. actual_parameter_part ::=
   (parameter_association {, parameter_association{)

  5. parameter_association ::=
   [formal_parameter_selector_name =>] explicit_actual_parameter

  6. explicit_actual_parameter ::= expression | variable_name
    1. A parameter_association is named or positional according to whether or not the formal_parameter_selector_name is specified. Any positional associations shall precede any named associations. Named associations are not allowed if the prefix in a subprogram call is an attribute_reference.

Name Resolution Rules
  1. The name or prefix given in a procedure_call_statement shall resolve to denote a callable entity that is a procedure, or an entry renamed as (viewed as) a procedure. The name or prefix given in a function_call shall resolve to denote a callable entity that is a function. When there is an actual_parameter_part, the prefix can be an implicit_dereference of an access-to-subprogram value.
  2. A subprogram call shall contain at most one association for each formal parameter. Each formal parameter without an association shall have a default_expression (in the profile of the view denoted by the name or prefix). This rule is an overloading rule, see 8.6.

    Dynamic Semantics
  3. For the execution of a subprogram call, the name or prefix of the call is evaluated, and each parameter_association is evaluated, see 6.4.1. If a default_expression is used, an implicit parameter_association is assumed for this rule. These evaluations are done in an arbitrary order. The subprogram_body is then executed. Finally, if the subprogram completes normally, then after it is left, any necessary assigning back of formal to actual parameters occurs, see 6.4.1.
  4. The exception Program_Error is raised at the point of a function_call if the function completes normally without executing a return_statement.
  5. A function_call denotes a constant, as defined in 6.5, the nominal subtype of the constant is given by the result subtype of the function.

    Examples
  6. Examples of procedure calls: 
  7. Traverse_Tree;                   --  see 6.1
Print_Header(128, Title, True);  --  see 6.1

  8. Switch(From => X, To => Next);
--  see 6.1.

Print_Header(128, Header => Title, Center => True);
--  see 6.1.

Print_Header(Header => Title, Center => True, Pages => 128);
--  see 6.1.
  9. Examples of function calls: 
  10. Dot_Product(U, V)   --  see 6.1, and 6.3.
Clock               --  see 9.6.
F.all
--  presuming F is of an access-to-subprogram type
--  see 3.10.
  11. Examples of procedures with default expressions: 
  12. procedure Activate(Process : in Process_Name;
                   After   : in Process_Name := No_Process;
                   Wait    : in Duration := 0.0;
                   Prior   : in Boolean := False);

  13. procedure Pair(Left, Right : in Person_Name := new Person);
--  see 3.10.1.
  14. Examples of their calls: 
  15. Activate(X);
Activate(X, After => Y);
Activate(X, Wait => 60.0, Prior => True);
Activate(X, Y, 10.0, False);

  16. Pair;
Pair(Left => new Person, Right => new Person);

    NOTES

  17. (7) If a default_expression is used for two or more parameters in a multiple parameter_specification, the default_expression is evaluated once for each omitted parameter. Hence in the above examples, the two calls of Pair are equivalent.

    Examples
  18. Examples of overloaded subprograms: 
  19. procedure Put(X : in Integer);
procedure Put(X : in String);

  20. procedure Set(Tint   : in Color);
procedure Set(Signal : in Light);
  21. Examples of their calls: 
  22. Put(28);
Put("no possible ambiguity here");

  23. Set(Tint   => Red);
Set(Signal => Red);
Set(Color'(Red));

  24. --  Set(Red) would be ambiguous since Red may
--  denote a value either of type Color or of type Light

Node:6.4.1, Next:, Previous:6.4, Up:6.4

Parameter Associations

  1. A parameter association defines the association between an actual parameter and a formal parameter.

    Name Resolution Rules
  2. The formal_parameter_selector_name of a parameter_association shall resolve to denote a parameter_specification of the view being called.
  3. The actual parameter is either the explicit_actual_parameter given in a parameter_association for a given formal parameter, or the corresponding default_expression if no parameter_association is given for the formal parameter. The expected type for an actual parameter is the type of the corresponding formal parameter.
  4. If the mode is in, the actual is interpreted as an expression; otherwise, the actual is interpreted only as a name, if possible.

    Legality Rules
  5. If the mode is in out or out, the actual shall be a name that denotes a variable.
  6. The type of the actual parameter associated with an access parameter shall be convertible, see 4.6, to its anonymous access type.

    Dynamic Semantics
  7. For the evaluation of a parameter_association:
    1. The actual parameter is first evaluated.
    2. For an access parameter, the access_definition is elaborated, which creates the anonymous access type.
    3. For a parameter (of any mode) that is passed by reference, see 6.2, a view conversion of the actual parameter to the nominal subtype of the formal parameter is evaluated, and the formal parameter denotes that conversion.
    4. For an in or in out parameter that is passed by copy, see 6.2, the formal parameter object is created, and the value of the actual parameter is converted to the nominal subtype of the formal parameter and assigned to the formal.
    5. For an out parameter that is passed by copy, the formal parameter object is created, and:
      1. For an access type, the formal parameter is initialized from the value of the actual, without a constraint check;
      2. For a composite type with discriminants or that has implicit initial values for any subcomponents, see 3.3.1, the behavior is as for an in out parameter passed by copy.
      3. For any other type, the formal parameter is uninitialized. If composite, a view conversion of the actual parameter to the nominal subtype of the formal is evaluated (which might raise Constraint_Error), and the actual subtype of the formal is that of the view conversion. If elementary, the actual subtype of the formal is given by its nominal subtype.
  1. A formal parameter of mode in out or out with discriminants is constrained if either its nominal subtype or the actual parameter is constrained.
  2. After normal completion and leaving of a subprogram, for each in out or out parameter that is passed by copy, the value of the formal parameter is converted to the subtype of the variable given as the actual parameter and assigned to it. These conversions and assignments occur in an arbitrary order.

Node:6.5, Next:, Previous:6.4.1, Up:6

Return Statements

  1. A return_statement is used to complete the execution of the innermost enclosing subprogram_body, entry_body, or accept_statement.

    Syntax
  2. return_statement ::= return [expression];

    Name Resolution Rules
  3. The expression, if any, of a return_statement is called the return expression. The result subtype of a function is the subtype denoted by the subtype_mark after the reserved word return in the profile of the function. The expected type for a return expression is the result type of the corresponding function.

    Legality Rules
  4. A return_statement shall be within a callable construct, and it applies to the innermost one. A return_statement shall not be within a body that is within the construct to which the return_statement applies.
  5. A function body shall contain at least one return_statement that applies to the function body, unless the function contains code_statements. A return_statement shall include a return expression if and only if it applies to a function body.

    Dynamic Semantics
  6. For the execution of a return_statement, the expression (if any) is first evaluated and converted to the result subtype.
  7. If the result type is class-wide, then the tag of the result is the tag of the value of the expression.
  8. If the result type is a specific tagged type:
    1. If it is limited, then a check is made that the tag of the value of the return expression identifies the result type. Constraint_Error is raised if this check fails.
    2. If it is nonlimited, then the tag of the result is that of the result type.
  1. A type is a return-by-reference type if it is a descendant of one of the following:
    1. a tagged limited type;
    2. a task or protected type;
    3. a nonprivate type with the reserved word limited in its declaration;
    4. a composite type with a subcomponent of a return-by-reference type;
    5. a private type whose full type is a return-by-reference type.
  1. If the result type is a return-by-reference type, then a check is made that the return expression is one of the following:
    1. a name that denotes an object view whose accessibility level is not deeper than that of the master that elaborated the function body; or
    2. a parenthesized expression or qualified_expression whose operand is one of these kinds of expressions.
  1. The exception Program_Error is raised if this check fails.
  2. For a function with a return-by-reference result type the result is returned by reference; that is, the function call denotes a constant view of the object associated with the value of the return expression. For any other function, the result is returned by copy; that is, the converted value is assigned into an anonymous constant created at the point of the return_statement, and the function call denotes that object.
  3. Finally, a transfer of control is performed which completes the execution of the callable construct to which the return_statement applies, and returns to the caller.

    Examples
  4. Examples of return statements: 
  5. return;
-- in a procedure body, entry_body, or accept_statement

return Key_Value(Last_Index);
-- in a function body

Node:6.6, Next:, Previous:6.5, Up:6

Overloading of Operators

  1. An operator is a function whose designator is an operator_symbol. Operators, like other functions, may be overloaded.

    Name Resolution Rules
  2. Each use of a unary or binary operator is equivalent to a function_call with function_prefix being the corresponding operator_symbol, and with (respectively) one or two positional actual parameters being the operand(s) of the operator (in order).

    Legality Rules
  3. The subprogram_specification of a unary or binary operator shall have one or two parameters, respectively. A generic function instantiation whose designator is an operator_symbol is only allowed if the specification of the generic function has the corresponding number of parameters.
  4. Default_expressions are not allowed for the parameters of an operator (whether the operator is declared with an explicit subprogram_specification or by a generic_instantiation).
  5. An explicit declaration of "/=" shall not have a result type of the predefined type Boolean.

    Static Semantics
  6. A declaration of "=" whose result type is Boolean implicitly declares a declaration of "/=" that gives the complementary result.

    NOTES

  7. (8) The operators "+" and "-" are both unary and binary operators, and hence may be overloaded with both one- and two-parameter functions.

    Examples
  8. Examples of user-defined operators: 
  9. function "+" (Left, Right : Matrix) return Matrix;
function "+" (Left, Right : Vector) return Vector;

--  assuming that A, B, and C are of the type Vector
--  the following two statements are equivalent:

A := B + C;
A := "+"(B, C);

Node:7, Next:, Previous:6.6, Up:Top

Packages

  1. Packages are program units that allow the specification of groups of logically related entities. Typically, a package contains the declaration of a type (often a private type or private extension) along with the declarations of primitive subprograms of the type, which can be called from outside the package, while their inner workings remain hidden from outside users.

Node:7.1, Next:, Previous:7, Up:7

Package Specifications and Declarations

  1. A package is generally provided in two parts: a package_specification and a package_body. Every package has a package_specification, but not all packages have a package_body.

    Syntax
  2. package_declaration ::= package_specification;

  3. package_specification ::=
   package defining_program_unit_name is
      {basic_declarative_item}
   [private
      {basic_declarative_item}]
   end [[parent_unit_name.]identifier]
    1. If an identifier or parent_unit_name.identifier appears at the end of a package_specification, then this sequence of lexical elements shall repeat the defining_program_unit_name.

Legality Rules
  1. A package_declaration or generic_package_declaration requires a completion (a body) if it contains any declarative_item that requires a completion, but whose completion is not in its package_specification.

    Static Semantics
  2. The first list of declarative_items of a package_specification of a package other than a generic formal package is called the visible part of the package. The optional list of declarative_items after the reserved word private (of any package_specification) is called the private part of the package. If the reserved word private does not appear, the package has an implicit empty private part.
  3. An entity declared in the private part of a package is visible only within the declarative region of the package itself (including any child units - see 10.1.1. In contrast, expanded names denoting entities declared in the visible part can be used even outside the package; furthermore, direct visibility of such entities can be achieved by means of use_clauses, see 4.1.3, and 8.4.

    Dynamic Semantics
  4. The elaboration of a package_declaration consists of the elaboration of its basic_declarative_items in the given order.

    NOTES

  5. (1) The visible part of a package contains all the information that another program unit is able to know about the package.
  6. (2) If a declaration occurs immediately within the specification of a package, and the declaration has a corresponding completion that is a body, then that body has to occur immediately within the body of the package.

    Examples
  7. Example of a package declaration: 
  8. package Rational_Numbers is

  9. type Rational is
   record
      Numerator   : Integer;
      Denominator : Positive;
   end record;

  10.    function "="(X,Y : Rational) return Boolean;

  11.    function "/"  (X,Y : Integer)  return Rational;
   --  to construct a rational number

  12.    function "+"  (X,Y : Rational) return Rational;
   function "-"  (X,Y : Rational) return Rational;
   function "*"  (X,Y : Rational) return Rational;
   function "/"  (X,Y : Rational) return Rational;
end Rational_Numbers;
  13. There are also many examples of package declarations in the predefined language environment, see "Annex A".

Node:7.2, Next:, Previous:7.1, Up:7

Package Bodies

  1. In contrast to the entities declared in the visible part of a package, the entities declared in the package_body are visible only within the package_body itself. As a consequence, a package with a package_body can be used for the construction of a group of related subprograms in which the logical operations available to clients are clearly isolated from the internal entities.

    Syntax
  2. package_body ::=
   package body defining_program_unit_name is
      declarative_part
   [begin
      handled_sequence_of_statements]
   end [[parent_unit_name.]identifier];
    1. If an identifier or parent_unit_name.identifier appears at the end of a package_body, then this sequence of lexical elements shall repeat the defining_program_unit_name.

Legality Rules
  1. A package_body shall be the completion of a previous package_declaration or generic_package_declaration. A library package_declaration or library generic_package_declaration shall not have a body unless it requires a body; pragma Elaborate_Body can be used to require a library_unit_declaration to have a body, see 10.2.1, if it would not otherwise require one.

    Static Semantics
  2. In any package_body without statements there is an implicit null_statement. For any package_declaration without an explicit completion, there is an implicit package_body containing a single null_statement. For a noninstance, nonlibrary package, this body occurs at the end of the declarative_part of the innermost enclosing program unit or block_statement; if there are several such packages, the order of the implicit package_bodies is unspecified. (For an instance, the implicit package_body occurs at the place of the instantiation (see 12.3). For a library package, the place is partially determined by the elaboration dependences, see "Section 10".

    Dynamic Semantics
  3. For the elaboration of a nongeneric package_body, its declarative_part is first elaborated, and its handled_sequence_of_statements is then executed.

    NOTES

  4. (3) A variable declared in the body of a package is only visible within this body and, consequently, its value can only be changed within the package_body. In the absence of local tasks, the value of such a variable remains unchanged between calls issued from outside the package to subprograms declared in the visible part. The properties of such a variable are similar to those of a "static" variable of C.
  5. (4) The elaboration of the body of a subprogram explicitly declared in the visible part of a package is caused by the elaboration of the body of the package. Hence a call of such a subprogram by an outside program unit raises the exception Program_Error if the call takes place before the elaboration of the package_body, see 3.11.

    Examples
  6. Example of a package body, see 7.1 
  7. package body Rational_Numbers is

  8.    procedure Same_Denominator (X,Y : in out Rational) is
   begin
      --  reduces X and Y to the same denominator:
      ...
   end Same_Denominator;

  9.    function "="(X,Y : Rational) return Boolean is
      U : Rational := X;
      V : Rational := Y;
   begin
      Same_Denominator (U,V);
      return U.Numerator = V.Numerator;
   end "=";

  10.    function "/" (X,Y : Integer) return Rational is
   begin
      if Y > 0 then
         return (Numerator => X,  Denominator => Y);
      else
         return (Numerator => -X, Denominator => -Y);
      end if;
   end "/";

  11.    function "+" (X,Y : Rational) return Rational is ...  end "+";
   function "-" (X,Y : Rational) return Rational is ...  end "-";
   function "*" (X,Y : Rational) return Rational is ...  end "*";
   function "/" (X,Y : Rational) return Rational is ...  end "/";

  12. end Rational_Numbers;

Node:7.3, Next:, Previous:7.2, Up:7

Private Types and Private Extensions

  1. The declaration (in the visible part of a package) of a type as a private type or private extension serves to separate the characteristics that can be used directly by outside program units (that is, the logical properties) from other characteristics whose direct use is confined to the package (the details of the definition of the type itself). See 3.9.1, for an overview of type extensions.

    Syntax
  2. private_type_declaration ::=
   type defining_identifier [discriminant_part] is
     [[abstract] tagged] [limited] private;

  3. private_extension_declaration ::=
   type defining_identifier [discriminant_part] is
     [abstract] new ancestor_subtype_indication with private;

    Legality Rules
  4. A private_type_declaration or private_extension_declaration declares a partial view of the type; such a declaration is allowed only as a declarative_item of the visible part of a package, and it requires a completion, which shall be a full_type_declaration that occurs as a declarative_item of the private part of the package. The view of the type declared by the full_type_declaration is called the full view. A generic formal private type or a generic formal private extension is also a partial view.
  5. A type shall be completely defined before it is frozen, see 3.11.1, and 13.14. Thus, neither the declaration of a variable of a partial view of a type, nor the creation by an allocator of an object of the partial view are allowed before the full declaration of the type. Similarly, before the full declaration, the name of the partial view cannot be used in a generic_instantiation or in a representation item.
  6. A private type is limited if its declaration includes the reserved word limited; a private extension is limited if its ancestor type is limited. If the partial view is nonlimited, then the full view shall be nonlimited. If a tagged partial view is limited, then the full view shall be limited. On the other hand, if an untagged partial view is limited, the full view may be limited or nonlimited.
  7. If the partial view is tagged, then the full view shall be tagged. On the other hand, if the partial view is untagged, then the full view may be tagged or untagged. In the case where the partial view is untagged and the full view is tagged, no derivatives of the partial view are allowed within the immediate scope of the partial view; derivatives of the full view are allowed.
  8. The ancestor subtype of a private_extension_declaration is the subtype defined by the ancestor_subtype_indication; the ancestor type shall be a specific tagged type. The full view of a private extension shall be derived (directly or indirectly) from the ancestor type. In addition to the places where Legality Rules normally apply, see 12.3, the requirement that the ancestor be specific applies also in the private part of an instance of a generic unit.
  9. If the declaration of a partial view includes a known_discriminant_part, then the full_type_declaration shall have a fully conforming (explicit) known_discriminant_part, see "Conformance Rules". The ancestor subtype may be unconstrained; the parent subtype of the full view is required to be constrained, see 3.7.
  10. If a private extension inherits known discriminants from the ancestor subtype, then the full view shall also inherit its discriminants from the ancestor subtype, and the parent subtype of the full view shall be constrained if and only if the ancestor subtype is constrained.
  11. If a partial view has unknown discriminants, then the full_type_declaration may define a definite or an indefinite subtype, with or without discriminants.
  12. If a partial view has neither known nor unknown discriminants, then the full_type_declaration shall define a definite subtype.
  13. If the ancestor subtype of a private extension has constrained discriminants, then the parent subtype of the full view shall impose a statically matching constraint on those discriminants.

    Static Semantics
  14. A private_type_declaration declares a private type and its first subtype. Similarly, a private_extension_declaration declares a private extension and its first subtype.
  15. A declaration of a partial view and the corresponding full_type_declaration define two views of a single type. The declaration of a partial view together with the visible part define the operations that are available to outside program units; the declaration of the full view together with the private part define other operations whose direct use is possible only within the declarative region of the package itself. Moreover, within the scope of the declaration of the full view, the characteristics of the type are determined by the full view; in particular, within its scope, the full view determines the classes that include the type, which components, entries, and protected subprograms are visible, what attributes and other predefined operations are allowed, and whether the first subtype is static (see 7.3.1).
  16. A private extension inherits components (including discriminants unless there is a new discriminant_part specified) and user-defined primitive subprograms from its ancestor type, in the same way that a record extension inherits components and user-defined primitive subprograms from its parent type, see 3.4.

    Dynamic Semantics
  17. The elaboration of a private_type_declaration creates a partial view of a type. The elaboration of a private_extension_declaration elaborates the ancestor_subtype_indication, and creates a partial view of a type.

    NOTES

  18. (5) The partial view of a type as declared by a private_type_declaration is defined to be a composite view (in 3.2). The full view of the type might or might not be composite. A private extension is also composite, as is its full view.
  19. (6) Declaring a private type with an unknown_discriminant_part is a way of preventing clients from creating uninitialized objects of the type; they are then forced to initialize each object by calling some operation declared in the visible part of the package. If such a type is also limited, then no objects of the type can be declared outside the scope of the full_type_declaration, restricting all object creation to the package defining the type. This allows complete control over all storage allocation for the type. Objects of such a type can still be passed as parameters, however.
  20. (7) The ancestor type specified in a private_extension_declaration and the parent type specified in the corresponding declaration of a record extension given in the private part need not be the same - the parent type of the full view can be any descendant of the ancestor type. In this case, for a primitive subprogram that is inherited from the ancestor type and not overridden, the formal parameter names and default expressions (if any) come from the corresponding primitive subprogram of the specified ancestor type, while the body comes from the corresponding primitive subprogram of the parent type of the full view (see 3.9.2).

    Examples
  21. Examples of private type declarations: 
  22. type Key is private;
type File_Name is limited private;
  23. Example of a private extension declaration: 
  24. type List is new Ada.Finalization.Controlled with private;

Node:7.3.1, Next:, Previous:7.3, Up:7.3

Private Operations

  1. For a type declared in the visible part of a package or generic package, certain operations on the type do not become visible until later in the package - either in the private part or the body. Such private operations are available only inside the declarative region of the package or generic package.

    Static Semantics
  2. The predefined operators that exist for a given type are determined by the classes to which the type belongs. For example, an integer type has a predefined "+" operator. In most cases, the predefined operators of a type are declared immediately after the definition of the type; the exceptions are explained below. Inherited subprograms are also implicitly declared immediately after the definition of the type, except as stated below.
  3. For a composite type, the characteristics, see 7.3 of the type are determined in part by the characteristics of its component types. At the place where the composite type is declared, the only characteristics of component types used are those characteristics visible at that place. If later within the immediate scope of the composite type additional characteristics become visible for a component type, then any corresponding characteristics become visible for the composite type. Any additional predefined operators are implicitly declared at that place.
  4. The corresponding rule applies to a type defined by a derived_type_definition, if there is a place within its immediate scope where additional characteristics of its parent type become visible.
  5. For example, an array type whose component type is limited private becomes nonlimited if the full view of the component type is nonlimited and visible at some later place within the immediate scope of the array type. In such a case, the predefined "=" operator is implicitly declared at that place, and assignment is allowed after that place.
  6. Inherited primitive subprograms follow a different rule. For a derived_type_definition, each inherited primitive subprogram is implicitly declared at the earliest place, if any, within the immediate scope of the type_declaration, but after the type_declaration, where the corresponding declaration from the parent is visible. If there is no such place, then the inherited subprogram is not declared at all. An inherited subprogram that is not declared at all cannot be named in a call and cannot be overridden, but for a tagged type, it is possible to dispatch to it.
  7. For a private_extension_declaration, each inherited subprogram is declared immediately after the private_extension_declaration if the corresponding declaration from the ancestor is visible at that place. Otherwise, the inherited subprogram is not declared for the private extension, though it might be for the full type.
  8. The Class attribute is defined for tagged subtypes in 3.9. In addition, for every subtype S of an untagged private type whose full view is tagged, the following attribute is defined:
  9. S'Class 
    Denotes the class-wide subtype corresponding to the full view
of S. This attribute is allowed only from the beginning of
the private part in which the full view is declared, until
the declaration of the full view. After the full view, the
Class attribute of the full view can be used.

    NOTES

  10. (8) Because a partial view and a full view are two different views of one and the same type, outside of the defining package the characteristics of the type are those defined by the visible part. Within these outside program units the type is just a private type or private extension, and any language rule that applies only to another class of types does not apply. The fact that the full declaration might implement a private type with a type of a particular class (for example, as an array type) is relevant only within the declarative region of the package itself including any child units.
  11. The consequences of this actual implementation are, however, valid everywhere. For example: any default initialization of components takes place; the attribute Size provides the size of the full view; finalization is still done for controlled components of the full view; task dependence rules still apply to components that are task objects.
  12. (9) Partial views provide assignment (unless the view is limited), membership tests, selected components for the selection of discriminants and inherited components, qualification, and explicit conversion.
  13. (10) For a subtype S of a partial view, S'Size is defined, see 13.3. For an object A of a partial view, the attributes A'Size and A'Address are defined, see 13.3. The Position, First_Bit, and Last_Bit attributes are also defined for discriminants and inherited components.

    Examples
  14. Example of a type with private operations: 
  15. package Key_Manager is
   type Key is private;
   Null_Key : constant Key;
   -- a deferred constant declaration, see 7.4
   procedure Get_Key(K : out Key);
   function "<" (X, Y : Key) return Boolean;
private
   type Key is new Natural;
   Null_Key : constant Key := Key'First;
end Key_Manager;

  16. package body Key_Manager is
   Last_Key : Key := Null_Key;
   procedure Get_Key(K : out Key) is
   begin
      Last_Key := Last_Key + 1;
      K := Last_Key;
   end Get_Key;

  17.    function "<" (X, Y : Key) return Boolean is
   begin
      return Natural(X) < Natural(Y);
   end "<";
end Key_Manager;

    NOTES

  18. (11) Notes on the example: Outside of the package Key_Manager, the operations available for objects of type Key include assignment, the comparison for equality or inequality, the procedure Get_Key and the operator "<"; they do not include other relational operators such as ">=", or arithmetic operators.
  19. The explicitly declared operator "<" hides the predefined operator "<" implicitly declared by the full_type_declaration. Within the body of the function, an explicit conversion of X and Y to the subtype Natural is necessary to invoke the "<" operator of the parent type. Alternatively, the result of the function could be written as not (X >= Y), since the operator ">=" is not redefined.
  20. The value of the variable Last_Key, declared in the package body, remains unchanged between calls of the procedure Get_Key (See also the NOTES of 7.2)

Node:7.4, Next:, Previous:7.3.1, Up:7

Deferred Constants

  1. Deferred constant declarations may be used to declare constants in the visible part of a package, but with the value of the constant given in the private part. They may also be used to declare constants imported from other languages, see "Annex B".

    Legality Rules
  2. A deferred constant declaration is an object_declaration with the reserved word constant but no initialization expression. The constant declared by a deferred constant declaration is called a deferred constant. A deferred constant declaration requires a completion, which shall be a full constant declaration (called the full declaration of the deferred constant), or a pragma Import (see "Annex B").
  3. A deferred constant declaration that is completed by a full constant declaration shall occur immediately within the visible part of a package_ specification. For this case, the following additional rules apply to the corresponding full declaration:
    1. The full declaration shall occur immediately within the private part of the same package;
    2. The deferred and full constants shall have the same type;
    3. If the subtype defined by the subtype_indication in the deferred declaration is constrained, then the subtype defined by the subtype_indication in the full declaration shall match it statically. On the other hand, if the subtype of the deferred constant is unconstrained, then the full declaration is still allowed to impose a constraint. The constant itself will be constrained, like all constants;
    4. If the deferred constant declaration includes the reserved word aliased, then the full declaration shall also.
  1. A deferred constant declaration that is completed by a pragma Import need not appear in the visible part of a package_specification, and has no full constant declaration.
  2. The completion of a deferred constant declaration shall occur before the constant is frozen, see 7.4.

    Dynamic Semantics
  3. The elaboration of a deferred constant declaration elaborates the subtype_indication or (only allowed in the case of an imported constant) the array_type_definition.

    NOTES

  4. (12) The full constant declaration for a deferred constant that is of a given private type or private extension is not allowed before the corresponding full_type_declaration. This is a consequence of the freezing rules for types, see 13.14.

    Examples
  5. Examples of deferred constant declarations: 
  6. Null_Key : constant Key;      --  see 7.3.1

  7. CPU_Identifier : constant String(1..8);
pragma Import(Assembler, CPU_Identifier, Link_Name => "CPU_ID");
--  see B.1

Node:7.5, Next:, Previous:7.4, Up:7

Limited Types

  1. A limited type is (a view of) a type for which the assignment operation is not allowed. A nonlimited type is a (view of a) type for which the assignment operation is allowed.

    Legality Rules
  2. If a tagged record type has any limited components, then the reserved word limited shall appear in its record_type_definition.

    Static Semantics
  3. A type is limited if it is a descendant of one of the following:
    1. a type with the reserved word limited in its definition;
    2. a task or protected type;
    3. a composite type with a limited component.
  1. Otherwise, the type is nonlimited.
  2. There are no predefined equality operators for a limited type.

    NOTES

  3. (13) The following are consequences of the rules for limited types:
    1. An initialization expression is not allowed in an object_declaration if the type of the object is limited.
    2. A default expression is not allowed in a component_declaration if the type of the record component is limited.
    3. An initialized allocator is not allowed if the designated type is limited.
    4. A generic formal parameter of mode in must not be of a limited type.
  1. (14) Aggregates are not available for a limited composite type. Concatenation is not available for a limited array type.
  2. (15) The rules do not exclude a default_expression for a formal parameter of a limited type; they do not exclude a deferred constant of a limited type if the full declaration of the constant is of a nonlimited type.
  3. (16) As illustrated in 7.3.1, an untagged limited type can become nonlimited under certain circumstances.

    Examples
  4. Example of a package with a limited type: 
  5. package IO_Package is
   type File_Name is limited private;

  6.    procedure Open (F : in out File_Name);
   procedure Close(F : in out File_Name);
   procedure Read (F : in File_Name; Item : out Integer);
   procedure Write(F : in File_Name; Item : in  Integer);
private
   type File_Name is
      limited record
         Internal_Name : Integer := 0;
      end record;
end IO_Package;

  7. package body IO_Package is
   Limit : constant := 200;
   type File_Descriptor is record  ...  end record;
   Directory : array (1 .. Limit) of File_Descriptor;
   ...
   procedure Open (F : in out File_Name) is  ...  end;
   procedure Close(F : in out File_Name) is  ...  end;
   procedure Read (F : in File_Name; Item : out Integer) is ... end;
   procedure Write(F : in File_Name; Item : in  Integer) is ... end;
begin
   ...
end IO_Package;

    NOTES

  8. (17) Notes on the example: In the example above, an outside subprogram making use of IO_Package may obtain a file name by calling Open and later use it in calls to Read and Write. Thus, outside the package, a file name obtained from Open acts as a kind of password; its internal properties (such as containing a numeric value) are not known and no other operations (such as addition or comparison of internal names) can be performed on a file name. Most importantly, clients of the package cannot make copies of objects of type File_Name.
  9. This example is characteristic of any case where complete control over the operations of a type is desired. Such packages serve a dual purpose. They prevent a user from making use of the internal structure of the type. They also implement the notion of an encapsulated data type where the only operations on the type are those given in the package specification.
  10. The fact that the full view of File_Name is explicitly declared limited means that parameter passing and function return will always be by reference, see 6.2, and 6.5.

Node:7.6, Next:, Previous:7.5, Up:7

User-Defined Assignment and Finalization

  1. Three kinds of actions are fundamental to the manipulation of objects: initialization, finalization, and assignment. Every object is initialized, either explicitly or by default, after being created (for example, by an object_declaration or allocator). Every object is finalized before being destroyed (for example, by leaving a subprogram_body containing an object_declaration, or by a call to an instance of Unchecked_Deallocation). An assignment operation is used as part of assignment_statements, explicit initialization, parameter passing, and other operations.
  2. Default definitions for these three fundamental operations are provided by the language, but a controlled type gives the user additional control over parts of these operations. In particular, the user can define, for a controlled type, an Initialize procedure which is invoked immediately after the normal default initialization of a controlled object, a Finalize procedure which is invoked immediately before finalization of any of the components of a controlled object, and an Adjust procedure which is invoked as the last step of an assignment to a (nonlimited) controlled object.

    Static Semantics
  3. The following language-defined library package exists: 
  4. package Ada.Finalization is
    pragma Preelaborate(Finalization);

  5.     type Controlled is abstract tagged private;

  6.     procedure Initialize(Object : in out Controlled);
    procedure Adjust                 (Object : in out Controlled);
    procedure Finalize               (Object : in out Controlled);

  7.     type Limited_Controlled is abstract tagged limited private;

  8.     procedure Initialize(Object : in out Limited_Controlled);
    procedure Finalize  (Object : in out Limited_Controlled);
private
    ... -- not specified by the language
end Ada.Finalization;
  9. A controlled type is a descendant of Controlled or Limited_Controlled. The (default) implementations of Initialize, Adjust, and Finalize have no effect. The predefined "=" operator of type Controlled always returns True, since this operator is incorporated into the implementation of the predefined equality operator of types derived from Controlled, as explained in 4.5.2. The type Limited_Controlled is like Controlled, except that it is limited and it lacks the primitive subprogram Adjust.

    Dynamic Semantics
  10. During the elaboration of an object_declaration, for every controlled subcomponent of the object that is not assigned an initial value (as defined in 3.3.1), Initialize is called on that subcomponent. Similarly, if the object as a whole is controlled and is not assigned an initial value, Initialize is called on the object. The same applies to the evaluation of an allocator, as explained in 4.8.
  11. For an extension_aggregate whose ancestor_part is a subtype_mark, Initialize is called on all controlled subcomponents of the ancestor part; if the type of the ancestor part is itself controlled, the Initialize procedure of the ancestor type is called, unless that Initialize procedure is abstract.
  12. Initialize and other initialization operations are done in an arbitrary order, except as follows. Initialize is applied to an object after initialization of its subcomponents, if any (including both implicit initialization and Initialize calls). If an object has a component with an access discriminant constrained by a per-object expression, Initialize is applied to this component after any components that do not have such discriminants. For an object with several components with such a discriminant, Initialize is applied to them in order of their component_declarations. For an allocator, any task activations follow all calls on Initialize.
  13. When a target object with any controlled parts is assigned a value, either when created or in a subsequent assignment_statement, the assignment operation proceeds as follows:
    1. The value of the target becomes the assigned value.
    2. The value of the target is adjusted.
  1. To adjust the value of a (nonlimited) composite object, the values of the components of the object are first adjusted in an arbitrary order, and then, if the object is controlled, Adjust is called. Adjusting the value of an elementary object has no effect, nor does adjusting the value of a composite object with no controlled parts.
  2. For an assignment_statement, after the name and expression have been evaluated, and any conversion (including constraint checking) has been done, an anonymous object is created, and the value is assigned into it; that is, the assignment operation is applied. (Assignment includes value adjustment.) The target of the assignment_statement is then finalized. The value of the anonymous object is then assigned into the target of the assignment_statement. Finally, the anonymous object is finalized. As explained below, the implementation may eliminate the intermediate anonymous object, so this description subsumes the one given in "Assignment Statements".

    Implementation Permissions
  3. An implementation is allowed to relax the above rules (for nonlimited controlled types) in the following ways:
    1. For an assignment_statement that assigns to an object the value of that same object, the implementation need not do anything.
    2. For an assignment_statement for a noncontrolled type, the implementation may finalize and assign each component of the variable separately (rather than finalizing the entire variable and assigning the entire new value) unless a discriminant of the variable is changed by the assignment.
    3. For an aggregate or function call whose value is assigned into a target object, the implementation need not create a separate anonymous object if it can safely create the value of the aggregate or function call directly in the target object. Similarly, for an assignment_statement, the implementation need not create an anonymous object if the value being assigned is the result of evaluating a name denoting an object (the source object) whose storage cannot overlap with the target. If the source object might overlap with the target object, then the implementation can avoid the need for an intermediary anonymous object by exercising one of the above permissions and perform the assignment one component at a time (for an overlapping array assignment), or not at all (for an assignment where the target and the source of the assignment are the same object). Even if an anonymous object is created, the implementation may move its value to the target object as part of the assignment without re-adjusting so long as the anonymous object has no aliased subcomponents.

Node:7.6.1, Next:, Previous:7.6, Up:7.6

Completion and Finalization

  1. This subclause defines completion and leaving of the execution of constructs and entities. A master is the execution of a construct that includes finalization of local objects after it is complete (and after waiting for any local tasks - see 9.3.), but before leaving. Other constructs and entities are left immediately upon completion.

    Dynamic Semantics
  2. The execution of a construct or entity is complete when the end of that execution has been reached, or when a transfer of control, see 5.1, causes it to be abandoned. Completion due to reaching the end of execution, or due to the transfer of control of an exit_, return_, goto_, or requeue_statement or of the selection of a terminate_alternative is normal completion. Completion is abnormal otherwise - when control is transferred out of a construct due to abort or the raising of an exception.
  3. After execution of a construct or entity is complete, it is left, meaning that execution continues with the next action, as defined for the execution that is taking place. Leaving an execution happens immediately after its completion, except in the case of a master: the execution of a task_body, a block_statement, a subprogram_body, an entry_body, or an accept_statement. A master is finalized after it is complete, and before it is left.
  4. For the finalization of a master, dependent tasks are first awaited, as explained in 9.3. Then each object whose accessibility level is the same as that of the master is finalized if the object was successfully initialized and still exists. These actions are performed whether the master is left by reaching the last statement or via a transfer of control. When a transfer of control causes completion of an execution, each included master is finalized in order, from innermost outward.
  5. For the finalization of an object:
    1. If the object is of an elementary type, finalization has no effect;
    2. If the object is of a controlled type, the Finalize procedure is called;
    3. If the object is of a protected type, the actions defined in 9.4 are performed;
    4. If the object is of a composite type, then after performing the above actions, if any, every component of the object is finalized in an arbitrary order, except as follows: if the object has a component with an access discriminant constrained by a per-object expression, this component is finalized before any components that do not have such discriminants; for an object with several components with such a discriminant, they are finalized in the reverse of the order of their component_declarations.
  1. Immediately before an instance of Unchecked_Deallocation reclaims the storage of an object, the object is finalized. If an instance of Unchecked_Deallocation is never applied to an object created by an allocator, the object will still exist when the corresponding master completes, and it will be finalized then.
  2. The order in which the finalization of a master performs finalization of objects is as follows: Objects created by declarations in the master are finalized in the reverse order of their creation. For objects that were created by allocators for an access type whose ultimate ancestor is declared in the master, this rule is applied as though each such object that still exists had been created in an arbitrary order at the first freezing point, see 13.14, of the ultimate ancestor type.
  3. The target of an assignment statement is finalized before copying in the new value, as explained in 7.6.
  4. The anonymous objects created by function calls and by aggregates are finalized no later than the end of the innermost enclosing declarative_item or statement; if that is a compound_statement, they are finalized before starting the execution of any statement within the compound_statement.

    Bounded (Run-Time) Errors
  5. It is a bounded error for a call on Finalize or Adjust to propagate an exception. The possible consequences depend on what action invoked the Finalize or Adjust operation:
    1. For a Finalize invoked as part of an assignment_statement, Program_Error is raised at that point.
    2. For an Adjust invoked as part of an assignment operation, any other adjustments due to be performed are performed, and then Program_Error is raised.
    3. For a Finalize invoked as part of a call on an instance of Unchecked_Deallocation, any other finalizations due to be performed are performed, and then Program_Error is raised.
    4. For a Finalize invoked by the transfer of control of an exit_, return_, goto_, or requeue_statement, Program_Error is raised no earlier than after the finalization of the master being finalized when the exception occurred, and no later than the point where normal execution would have continued. Any other finalizations due to be performed up to that point are performed before raising Program_Error.
    5. For a Finalize invoked by a transfer of control that is due to raising an exception, any other finalizations due to be performed for the same master are performed; Program_Error is raised immediately after leaving the master.
    6. For a Finalize invoked by a transfer of control due to an abort or selection of a terminate alternative, the exception is ignored; any other finalizations due to be performed are performed.

    NOTES

  1. (18) The rules in "Section 10", imply that immediately prior to partition termination, Finalize operations are applied to library-level controlled objects (including those created by allocators of library-level access types, except those already finalized). This occurs after waiting for library-level tasks to terminate.
  2. (19) A constant is only constant between its initialization and finalization. Both initialization and finalization are allowed to change the value of a constant.
  3. (20) Abort is deferred during certain operations related to controlled types, as explained in 9.8. Those rules prevent an abort from causing a controlled object to be left in an ill-defined state.
  4. (21) The Finalize procedure is called upon finalization of a controlled object, even if Finalize was called earlier, either explicitly or as part of an assignment; hence, if a controlled type is visibly controlled (implying that its Finalize primitive is directly callable), or is nonlimited (implying that assignment is allowed), its Finalize procedure should be designed to have no ill effect if it is applied a second time to the same object.

Node:8, Next:, Previous:7.6.1, Up:Top

Visibility Rules

  1. The rules defining the scope of declarations and the rules defining which identifiers, character_literals, and operator_symbols are visible at (or from) various places in the text of the program are described in this section. The formulation of these rules uses the notion of a declarative region.
  2. As explained in Section 3, a declaration declares a view of an entity and associates a defining name with that view. The view comprises an identification of the viewed entity, and possibly additional properties. A usage name denotes a declaration. It also denotes the view declared by that declaration, and denotes the entity of that view. Thus, two different usage names might denote two different views of the same entity; in this case they denote the same entity.

Node:8.1, Next:, Previous:8, Up:8

Declarative Region


Static Semantics
  1. For each of the following constructs, there is a portion of the program text called its declarative region, within which nested declarations can occur:
    1. any declaration, other than that of an enumeration type, that is not a completion of a previous declaration;
    2. a block_statement;
    3. a loop_statement;
    4. an accept_statement;
    5. an exception_handler.
  1. The declarative region includes the text of the construct together with additional text determined (recursively), as follows:
    1. If a declaration is included, so is its completion, if any.
    2. If the declaration of a library unit (including Standard - see 10.1.1, is included, so are the declarations of any child units (and their completions, by the previous rule). The child declarations occur after the declaration.
    3. If a body_stub is included, so is the corresponding subunit.
    4. If a type_declaration is included, then so is a corresponding record_representation_clause, if any.
  1. The declarative region of a declaration is also called the declarative region of any view or entity declared by the declaration.
  2. A declaration occurs immediately within a declarative region if this region is the innermost declarative region that encloses the declaration (the immediately enclosing declarative region), not counting the declarative region (if any) associated with the declaration itself.
  3. A declaration is local to a declarative region if the declaration occurs immediately within the declarative region. An entity is local to a declarative region if the entity is declared by a declaration that is local to the declarative region.
  4. A declaration is global to a declarative region if the declaration occurs immediately within another declarative region that encloses the declarative region. An entity is global to a declarative region if the entity is declared by a declaration that is global to the declarative region.

    NOTES

  5. (1) The children of a parent library unit are inside the parent's declarative region, even though they do not occur inside the parent's declaration or body. This implies that one can use (for example) "P.Q" to refer to a child of P whose defining name is Q, and that after "use P;" Q can refer (directly) to that child.
  6. (2) As explained above and in "Compilation Units - Library Units", all library units are descendants of Standard, and so are contained in the declarative region of Standard. They are not inside the declaration or body of Standard, but they are inside its declarative region.
  7. (3) For a declarative region that comes in multiple parts, the text of the declarative region does not contain any text that might appear between the parts. Thus, when a portion of a declarative region is said to extend from one place to another in the declarative region, the portion does not contain any text that might appear between the parts of the declarative region.

Node:8.2, Next:, Previous:8.1, Up:8

Scope of Declarations

  1. For each declaration, the language rules define a certain portion of the program text called the scope of the declaration. The scope of a declaration is also called the scope of any view or entity declared by the declaration. Within the scope of an entity, and only there, there are places where it is legal to refer to the declared entity. These places are defined by the rules of visibility and overloading.

    Static Semantics
  2. The immediate scope of a declaration is a portion of the declarative region immediately enclosing the declaration. The immediate scope starts at the beginning of the declaration, except in the case of an overloadable declaration, in which case the immediate scope starts just after the place where the profile of the callable entity is determined (which is at the end of the _specification for the callable entity, or at the end of the generic_instantiation if an instance). The immediate scope extends to the end of the declarative region, with the following exceptions:
    1. The immediate scope of a library_item includes only its semantic dependents.
    2. The immediate scope of a declaration in the private part of a library unit does not include the visible part of any public descendant of that library unit.
  1. The visible part of (a view of) an entity is a portion of the text of its declaration containing declarations that are visible from outside. The private part of (a view of) an entity that has a visible part contains all declarations within the declaration of (the view of) the entity, except those in the visible part; these are not visible from outside. Visible and private parts are defined only for these kinds of entities: callable entities, other program units, and composite types.
    1. The visible part of a view of a callable entity is its profile.
    2. The visible part of a composite type other than a task or protected type consists of the declarations of all components declared (explicitly or implicitly) within the type_declaration.
    3. The visible part of a generic unit includes the generic_formal_part. For a generic package, it also includes the first list of basic_declarative_items of the package_specification. For a generic subprogram, it also includes the profile.
    4. The visible part of a package, task unit, or protected unit consists of declarations in the program unit's declaration other than those following the reserved word private, if any; see 7.1, and 12.7, for packages, see 9.1, for task units, and 9.4, for protected units.
  1. The scope of a declaration always contains the immediate scope of the declaration. In addition, for a given declaration that occurs immediately within the visible part of an outer declaration, or is a public child of an outer declaration, the scope of the given declaration extends to the end of the scope of the outer declaration, except that the scope of a library_item includes only its semantic dependents.
  2. The immediate scope of a declaration is also the immediate scope of the entity or view declared by the declaration. Similarly, the scope of a declaration is also the scope of the entity or view declared by the declaration.

    NOTES

  3. (4) There are notations for denoting visible declarations that are not directly visible. For example, parameter_specifications are in the visible part of a subprogram_declaration so that they can be used in named-notation calls appearing outside the called subprogram. For another example, declarations of the visible part of a package can be denoted by expanded names appearing outside the package, and can be made directly visible by a use_clause.

Node:8.3, Next:, Previous:8.2, Up:8

Visibility

  1. The visibility rules, given below, determine which declarations are visible and directly visible at each place within a program. The visibility rules apply to both explicit and implicit declarations.

    Static Semantics
  2. A declaration is defined to be directly visible at places where a name consisting of only an identifier or operator_symbol is sufficient to denote the declaration; that is, no selected_component notation or special context (such as preceding => in a named association) is necessary to denote the declaration. A declaration is defined to be visible wherever it is directly visible, as well as at other places where some name (such as a selected_component) can denote the declaration.
  3. The syntactic category direct_name is used to indicate contexts where direct visibility is required. The syntactic category selector_name is used to indicate contexts where visibility, but not direct visibility, is required.
  4. There are two kinds of direct visibility: immediate visibility and use-visibility. A declaration is immediately visible at a place if it is directly visible because the place is within its immediate scope. A declaration is use-visible if it is directly visible because of a use_clause, see 8.4. Both conditions can apply.
  5. A declaration can be hidden, either from direct visibility, or from all visibility, within certain parts of its scope. Where hidden from all visibility, it is not visible at all (neither using a direct_name nor a selector_name). Where hidden from direct visibility, only direct visibility is lost; visibility using a selector_name is still possible.
  6. Two or more declarations are overloaded if they all have the same defining name and there is a place where they are all directly visible.
  7. The declarations of callable entities (including enumeration literals) are overloadable, meaning that overloading is allowed for them.
  8. Two declarations are homographs if they have the same defining name, and, if both are overloadable, their profiles are type conformant. An inner declaration hides any outer homograph from direct visibility.
  9. Two homographs are not generally allowed immediately within the same declarative region unless one overrides the other (see Legality Rules below). A declaration overrides another homograph that occurs immediately within the same declarative region in the following cases:
    1. An explicit declaration overrides an implicit declaration of a primitive subprogram, regardless of which declaration occurs first;
    2. The implicit declaration of an inherited operator overrides that of a predefined operator;
    3. An implicit declaration of an inherited subprogram overrides a previous implicit declaration of an inherited subprogram.
    4. For an implicit declaration of a primitive subprogram in a generic unit, there is a copy of this declaration in an instance. However, a whole new set of primitive subprograms is implicitly declared for each type declared within the visible part of the instance. These new declarations occur immediately after the type declaration, and override the copied ones. The copied ones can be called only from within the instance; the new ones can be called only from outside the instance, although for tagged types, the body of a new one can be executed by a call to an old one.
  1. A declaration is visible within its scope, except where hidden from all visibility, as follows:
    1. An overridden declaration is hidden from all visibility within the scope of the overriding declaration.
    2. A declaration is hidden from all visibility until the end of the declaration, except:
      1. For a record type or record extension, the declaration is hidden from all visibility only until the reserved word record;
      2. For a package_declaration, task declaration, protected declaration, generic_package_declaration, or subprogram_body, the declaration is hidden from all visibility only until the reserved word is of the declaration.
    1. If the completion of a declaration is a declaration, then within the scope of the completion, the first declaration is hidden from all visibility. Similarly, a discriminant_specification or parameter_specification is hidden within the scope of a corresponding discriminant_specification or parameter_specification of a corresponding completion, or of a corresponding accept_statement.
    2. The declaration of a library unit (including a library_unit_renaming_declaration) is hidden from all visibility except at places that are within its declarative region or within the scope of a with_clause that mentions it. For each declaration or renaming of a generic unit as a child of some parent generic package, there is a corresponding declaration nested immediately within each instance of the parent. Such a nested declaration is hidden from all visibility except at places that are within the scope of a with_clause that mentions the child.
  1. A declaration with a defining_identifier or defining_operator_symbol is immediately visible (and hence directly visible) within its immediate scope except where hidden from direct visibility, as follows:
    1. A declaration is hidden from direct visibility within the immediate scope of a homograph of the declaration, if the homograph occurs within an inner declarative region;
    2. A declaration is also hidden from direct visibility where hidden from all visibility.

Name Resolution Rules
  1. A direct_name shall resolve to denote a directly visible declaration whose defining name is the same as the direct_name. A selector_name shall resolve to denote a visible declaration whose defining name is the same as the selector_name.
  2. These rules on visibility and direct visibility do not apply in a context_clause, a parent_unit_name, or a pragma that appears at the place of a compilation_unit. For those contexts, see the rules in "Environment-Level Visibility Rules".

    Legality Rules
  3. An explicit declaration is illegal if there is a homograph occurring immediately within the same declarative region that is visible at the place of the declaration, and is not hidden from all visibility by the explicit declaration. Similarly, the context_clause for a subunit is illegal if it mentions (in a with_clause) some library unit, and there is a homograph of the library unit that is visible at the place of the corresponding stub, and the homograph and the mentioned library unit are both declared immediately within the same declarative region. These rules also apply to dispatching operations declared in the visible part of an instance of a generic unit. However, they do not apply to other overloadable declarations in an instance; such declarations may have type conformant profiles in the instance, so long as the corresponding declarations in the generic were not type conformant.

    NOTES

  4. (5) Visibility for compilation units follows from the definition of the environment in 10.1.4, except that it is necessary to apply a with_clause to obtain visibility to a library_unit_declaration or library_unit_renaming_declaration.
  5. (6) In addition to the visibility rules given above, the meaning of the occurrence of a direct_name or selector_name at a given place in the text can depend on the overloading rules, see 8.6.
  6. (7) Not all contexts where an identifier, character_literal, or operator_symbol are allowed require visibility of a corresponding declaration. Contexts where visibility is not required are identified by using one of these three syntactic categories directly in a syntax rule, rather than using direct_name or selector_name.

Node:8.4, Next:, Previous:8.3, Up:8

Use Clauses

  1. A use_package_clause achieves direct visibility of declarations that appear in the visible part of a package; a use_type_clause achieves direct visibility of the primitive operators of a type.

    Syntax
  2. use_clause ::= use_package_clause | use_type_clause

  3. use_package_clause ::= use package_name {, package_name};

  4. use_type_clause ::= use type subtype_mark {, subtype_mark};

    Legality Rules
  5. A package_name of a use_package_clause shall denote a package.

    Static Semantics
  6. For each use_clause, there is a certain region of text called the scope of the use_clause. For a use_clause within a context_clause of a library_unit_declaration or library_unit_renaming_declaration, the scope is the entire declarative region of the declaration. For a use_clause within a context_clause of a body, the scope is the entire body and any subunits (including multiply nested subunits). The scope does not include context_clauses themselves.
  7. For a use_clause immediately within a declarative region, the scope is the portion of the declarative region starting just after the use_clause and extending to the end of the declarative region. However, the scope of a use_clause in the private part of a library unit does not include the visible part of any public descendant of that library unit.
  8. For each package denoted by a package_name of a use_package_clause whose scope encloses a place, each declaration that occurs immediately within the declarative region of the package is potentially use-visible at this place if the declaration is visible at this place. For each type T or T'Class determined by a subtype_mark of a use_type_clause whose scope encloses a place, the declaration of each primitive operator of type T is potentially use-visible at this place if its declaration is visible at this place.
  9. A declaration is use-visible if it is potentially use-visible, except in these naming-conflict cases:
    1. A potentially use-visible declaration is not use-visible if the place considered is within the immediate scope of a homograph of the declaration.
    2. Potentially use-visible declarations that have the same identifier are not use-visible unless each of them is an overloadable declaration.

Dynamic Semantics
  1. The elaboration of a use_clause has no effect.

    Examples
  2. Example of a use clause in a context clause: 
  3. with Ada.Calendar; use Ada;

  4. Example of a use type clause:

  5. use type Rational_Numbers.Rational;  --  see 7.1
Two_Thirds: Rational_Numbers.Rational := 2/3;

Node:8.5, Next:, Previous:8.4, Up:8

Renaming Declarations

  1. A renaming_declaration declares another name for an entity, such as an object, exception, package, subprogram, entry, or generic unit. Alternatively, a subprogram_renaming_declaration can be the completion of a previous subprogram_declaration.

    Syntax
  2. renaming_declaration ::=
      object_renaming_declaration
    | exception_renaming_declaration
    | package_renaming_declaration
    | subprogram_renaming_declaration
    | generic_renaming_declaration

    Dynamic Semantics
  3. The elaboration of a renaming_declaration evaluates the name that follows the reserved word renames and thereby determines the view and entity denoted by this name (the renamed view and renamed entity). A name that denotes the renaming_declaration denotes (a new view of) the renamed entity.

    NOTES

  4. (8) Renaming may be used to resolve name conflicts and to act as a shorthand. Renaming with a different identifier or operator_symbol does not hide the old name; the new name and the old name need not be visible at the same places.
  5. (9) A task or protected object that is declared by an explicit object_declaration can be renamed as an object. However, a single task or protected object cannot be renamed since the corresponding type is anonymous (meaning it has no nameable subtypes). For similar reasons, an object of an anonymous array or access type cannot be renamed.
  6. (10) A subtype defined without any additional constraint can be used to achieve the effect of renaming another subtype (including a task or protected subtype) as in 
  7. subtype Mode is Ada.Text_IO.File_Mode;

Node:8.5.1, Next:, Previous:8.5, Up:8.5

Object Renaming Declarations

  1. An object_renaming_declaration is used to rename an object.

    Syntax
  2. object_renaming_declaration ::=
   defining_identifier : subtype_mark renames object_name;

    Name Resolution Rules
  3. The type of the object_name shall resolve to the type determined by the subtype_mark.

    Legality Rules
  4. The renamed entity shall be an object.
  5. The renamed entity shall not be a subcomponent that depends on discriminants of a variable whose nominal subtype is unconstrained, unless this subtype is indefinite, or the variable is aliased. A slice of an array shall not be renamed if this restriction disallows renaming of the array.

    Static Semantics
  6. An object_renaming_declaration declares a new view of the renamed object whose properties are identical to those of the renamed view. Thus, the properties of the renamed object are not affected by the renaming_declaration. In particular, its value and whether or not it is a constant are unaffected; similarly, the constraints that apply to an object are not affected by renaming (any constraint implied by the subtype_mark of the object_renaming_declaration is ignored).

    Examples
  7. Example of renaming an object: 
  8. declare
   L : Person renames Leftmost_Person;  --  see 3.10.1
begin
   L.Age := L.Age + 1;
end;

Node:8.5.2, Next:, Previous:8.5.1, Up:8.5

Exception Renaming Declarations

  1. An exception_renaming_declaration is used to rename an exception.

    Syntax
  2. exception_renaming_declaration ::=
   defining_identifier : exception renames exception_name;

    Legality Rules
  3. The renamed entity shall be an exception.

    Static Semantics
  4. An exception_renaming_declaration declares a new view of the renamed exception.

    Examples
  5. Example of renaming an exception: 
  6. EOF : exception renames Ada.IO_Exceptions.End_Error;
--  see A.13

Node:8.5.3, Next:, Previous:8.5.2, Up:8.5

Package Renaming Declarations

  1. A package_renaming_declaration is used to rename a package.

    Syntax
  2. package_renaming_declaration ::=
   package defining_program_unit_name renames package_name;

    Legality Rules
  3. The renamed entity shall be a package.

    Static Semantics
  4. A package_renaming_declaration declares a new view of the renamed package.

    Examples
  5. Example of renaming a package: 
  6. package TM renames Table_Manager;

Node:8.5.4, Next:, Previous:8.5.3, Up:8.5

Subprogram Renaming Declarations

  1. A subprogram_renaming_declaration can serve as the completion of a subprogram_declaration; such a renaming_declaration is called a renaming-as-body. A subprogram_renaming_declaration that is not a completion is called a renaming-as-declaration, and is used to rename a subprogram (possibly an enumeration literal) or an entry.

    Syntax
  2. subprogram_renaming_declaration ::=
   subprogram_specification renames callable_entity_name;

    Name Resolution Rules
  3. The expected profile for the callable_entity_name is the profile given in the subprogram_specification.

    Legality Rules
  4. The profile of a renaming-as-declaration shall be mode-conformant with that of the renamed callable entity.
  5. The profile of a renaming-as-body shall be subtype-conformant with that of the renamed callable entity, and shall conform fully to that of the declaration it completes. If the renaming-as-body completes that declaration before the subprogram it declares is frozen, the subprogram it declares takes its convention from the renamed subprogram; otherwise the convention of the renamed subprogram shall not be Intrinsic.
  6. A name that denotes a formal parameter of the subprogram_specification is not allowed within the callable_entity_name.

    Static Semantics
  7. A renaming-as-declaration declares a new view of the renamed entity. The profile of this new view takes its subtypes, parameter modes, and calling convention from the original profile of the callable entity, while taking the formal parameter names and default_expressions from the profile given in the subprogram_renaming_declaration. The new view is a function or procedure, never an entry.

    Dynamic Semantics
  8. For a call on a renaming of a dispatching subprogram that is overridden, if the overriding occurred before the renaming, then the body executed is that of the overriding declaration, even if the overriding declaration is not visible at the place of the renaming; otherwise, the inherited or predefined subprogram is called.

    NOTES

  9. (11) A procedure can only be renamed as a procedure. A function whose defining_designator is either an identifier or an operator_symbol can be renamed with either an identifier or an operator_symbol; for renaming as an operator, the subprogram specification given in the renaming_declaration is subject to the rules given in 6.6, for operator declarations. Enumeration literals can be renamed as functions; similarly, attribute_references that denote functions (such as references to Succ and Pred) can be renamed as functions. An entry can only be renamed as a procedure; the new name is only allowed to appear in contexts that allow a procedure name. An entry of a family can be renamed, but an entry family cannot be renamed as a whole.
  10. (12) The operators of the root numeric types cannot be renamed because the types in the profile are anonymous, so the corresponding specifications cannot be written; the same holds for certain attributes, such as Pos.
  11. (13) Calls with the new name of a renamed entry are procedure_call_statements and are not allowed at places where the syntax requires an entry_call_statement in conditional_ and timed_entry_calls, nor in an asynchronous_select; similarly, the Count attribute is not available for the new name.
  12. (14) The primitiveness of a renaming-as-declaration is determined by its profile, and by where it occurs, as for any declaration of (a view of) a subprogram; primitiveness is not determined by the renamed view. In order to perform a dispatching call, the subprogram name has to denote a primitive subprogram, not a non-primitive renaming of a primitive subprogram.

    Examples
  13. Examples of subprogram renaming declarations: 
  14. procedure My_Write(C : in Character) renames Pool(K).Write;
--  see 4.1.3

  15. function Real_Plus(Left, Right : Real   ) return Real    renames "+";
function Int_Plus (Left, Right : Integer) return Integer renames "+";

  16. function Rouge return Color renames Red;  --  see 3.5.1
function Rot   return Color renames Red;
function Rosso return Color renames Rouge;

  17. function Next(X : Color) return Color renames Color'Succ;
--  see 3.5.1
  18. Example of a subprogram renaming declaration with new parameter names: 
  19. function "*" (X,Y : Vector) return Real renames Dot_Product;
--  see 6.1
  20. Example of a subprogram renaming declaration with a new default expression: 
  21. function Minimum(L : Link := Head) return Cell renames Min_Cell;
--  see 6.1

Node:8.5.5, Next:, Previous:8.5.4, Up:8.5

Generic Renaming Declarations

    A generic_renaming_declaration is used to rename a generic unit.

    Syntax
  1. generic_renaming_declaration ::=
    generic package defining_program_unit_name renames
      generic_package_name;
  | generic procedure defining_program_unit_name renames
      generic_procedure_name;
  | generic function defining_program_unit_name renames
      generic_function_name;

    Legality Rules
  2. The renamed entity shall be a generic unit of the corresponding kind.

    Static Semantics
  3. A generic_renaming_declaration declares a new view of the renamed generic unit.

    NOTES

  4. (15) Although the properties of the new view are the same as those of the renamed view, the place where the generic_renaming_declaration occurs may affect the legality of subsequent renamings and instantiations that denote the generic_renaming_declaration, in particular if the renamed generic unit is a library unit, see 10.1.1.

    Examples
  5. Example of renaming a generic unit: 
  6. generic package Enum_IO renames Ada.Text_IO.Enumeration_IO;
--  see A.10.10

Node:8.6, Next:, Previous:8.5.5, Up:8

The Context of Overload Resolution

  1. Because declarations can be overloaded, it is possible for an occurrence of a usage name to have more than one possible interpretation; in most cases, ambiguity is disallowed. This clause describes how the possible interpretations resolve to the actual interpretation.
  2. Certain rules of the language (the Name Resolution Rules) are considered "overloading rules". If a possible interpretation violates an overloading rule, it is assumed not to be the intended interpretation; some other possible interpretation is assumed to be the actual interpretation. On the other hand, violations of non-overloading rules do not affect which interpretation is chosen; instead, they cause the construct to be illegal. To be legal, there usually has to be exactly one acceptable interpretation of a construct that is a "complete context", not counting any nested complete contexts.
  3. The syntax rules of the language and the visibility rules given in 8.3, determine the possible interpretations. Most type checking rules (rules that require a particular type, or a particular class of types, for example) are overloading rules. Various rules for the matching of formal and actual parameters are overloading rules.

    Name Resolution Rules
  4. Overload resolution is applied separately to each complete context, not counting inner complete contexts. Each of the following constructs is a complete context:
    1. A context_item.
    2. declarative_item or declaration.
    3. A statement.
    4. A pragma_argument_association.
    5. The expression of a case_statement.
  1. An (overall) interpretation of a complete context embodies its meaning, and includes the following information about the constituents of the complete context, not including constituents of inner complete contexts:
    1. for each constituent of the complete context, to which syntactic categories it belongs, and by which syntax rules; and
    2. for each usage name, which declaration it denotes (and, therefore, which view and which entity it denotes); and
    3. for a complete context that is a declarative_item, whether or not it is a completion of a declaration, and (if so) which declaration it completes.
  1. A possible interpretation is one that obeys the syntax rules and the visibility rules. An acceptable interpretation is a possible interpretation that obeys the overloading rules, that is, those rules that specify an expected type or expected profile, or specify how a construct shall resolve or be interpreted.
  2. The interpretation of a constituent of a complete context is determined from the overall interpretation of the complete context as a whole. Thus, for example, "interpreted as a function_call," means that the construct's interpretation says that it belongs to the syntactic category function_call.
  3. Each occurrence of a usage name denotes the declaration determined by its interpretation. It also denotes the view declared by its denoted declaration, except in the following cases:
    1. If a usage name appears within the declarative region of a type_declaration and denotes that same type_declaration, then it denotes the current instance of the type (rather than the type itself). The current instance of a type is the object or value of the type that is associated with the execution that evaluates the usage name.
    2. If a usage name appears within the declarative region of a generic_declaration (but not within its generic_formal_part) and it denotes that same generic_declaration, then it denotes the current instance of the generic unit (rather than the generic unit itself). See also 12.3.
  1. A usage name that denotes a view also denotes the entity of that view.
  2. The expected type for a given expression, name, or other construct determines, according to the type resolution rules given below, the types considered for the construct during overload resolution. The type resolution rules provide support for class-wide programming, universal numeric literals, dispatching operations, and anonymous access types:
    1. If a construct is expected to be of any type in a class of types, or of the universal or class-wide type for a class, then the type of the construct shall resolve to a type in that class or to a universal type that covers the class.
    2. If the expected type for a construct is a specific type T, then the type of the construct shall resolve either to T, or:
      1. to T'Class; or
      2. to a universal type that covers T; or
      3. when T is an anonymous access type, see 3.10, with designated type D, to an access-to-variable type whose designated type is D'Class or is covered by D.
  1. In certain contexts, such as in a subprogram_renaming_declaration, the Name Resolution Rules define an expected profile for a given name; in such cases, the name shall resolve to the name of a callable entity whose profile is type conformant with the expected profile.

    Legality Rules
  2. When the expected type for a construct is required to be a single type in a given class, the type expected for the construct shall be determinable solely from the context in which the construct appears, excluding the construct itself, but using the requirement that it be in the given class; the type of the construct is then this single expected type. Furthermore, the context shall not be one that expects any type in some class that contains types of the given class; in particular, the construct shall not be the operand of a type_conversion.
  3. A complete context shall have at least one acceptable interpretation; if there is exactly one, then that one is chosen.
  4. There is a preference for the primitive operators (and ranges) of the root numeric types root_integer and root_real. In particular, if two acceptable interpretations of a constituent of a complete context differ only in that one is for a primitive operator (or range) of the type root_integer or root_real, and the other is not, the interpretation using the primitive operator (or range) of the root numeric type is preferred.
  5. For a complete context, if there is exactly one overall acceptable interpretation where each constituent's interpretation is the same as or preferred (in the above sense) over those in all other overall acceptable interpretations, then that one overall acceptable interpretation is chosen. Otherwise, the complete context is ambiguous.
  6. A complete context other than a pragma_argument_association shall not be ambiguous.
  7. A complete context that is a pragma_argument_association is allowed to be ambiguous (unless otherwise specified for the particular pragma), but only if every acceptable interpretation of the pragma argument is as a name that statically denotes a callable entity. Such a name denotes all of the declarations determined by its interpretations, and all of the views declared by these declarations.

    NOTES

  8. (16) If a usage name has only one acceptable interpretation, then it denotes the corresponding entity. However, this does not mean that the usage name is necessarily legal since other requirements exist which are not considered for overload resolution; for example, the fact that an expression is static, whether an object is constant, mode and subtype conformance rules, freezing rules, order of elaboration, and so on.
  9. Similarly, subtypes are not considered for overload resolution (the violation of a constraint does not make a program illegal but raises an exception during program execution).

Node:9, Next:, Previous:8.6, Up:Top

Tasks and Synchronization

  1. The execution of an Ada program consists of the execution of one or more tasks. Each task represents a separate thread of control that proceeds independently and concurrently between the points where it interacts with other tasks. The various forms of task interaction are described in this section, and include:
    1. the activation and termination of a task;
    2. a call on a protected subprogram of a protected object, providing exclusive read-write access, or concurrent read-only access to shared data;
    3. a call on an entry, either of another task, allowing for synchronous communication with that task, or of a protected object, allowing for asynchronous communication with one or more other tasks using that same protected object;
    4. a timed operation, including a simple delay statement, a timed entry call or accept, or a timed asynchronous select statement (see next item);
    5. an asynchronous transfer of control as part of an asynchronous select statement, where a task stops what it is doing and begins execution at a different point in response to the completion of an entry call or the expiration of a delay;
    6. an abort statement, allowing one task to cause the termination of another task.
  1. In addition, tasks can communicate indirectly by reading and updating (unprotected) shared variables, presuming the access is properly synchronized through some other kind of task interaction.

    Static Semantics
  2. The properties of a task are defined by a corresponding task declaration and task_body, which together define a program unit called a task unit.

    Dynamic Semantics
  3. Over time, tasks proceed through various states. A task is initially inactive; upon activation, and prior to its termination it is either blocked (as part of some task interaction) or ready to run. While ready, a task competes for the available execution resources that it requires to run.

    NOTES

  4. (1) Concurrent task execution may be implemented on multicomputers, multiprocessors, or with interleaved execution on a single physical processor. On the other hand, whenever an implementation can determine that the required semantic effects can be achieved when parts of the execution of a given task are performed by different physical processors acting in parallel, it may choose to perform them in this way.

Node:9.1, Next:, Previous:9, Up:9

Task Units and Task Objects

  1. A task unit is declared by a task declaration, which has a corresponding task_body. A task declaration may be a task_type_declaration, in which case it declares a named task type; alternatively, it may be a single_task_declaration, in which case it defines an anonymous task type, as well as declaring a named task object of that type.

    Syntax
  2. task_type_declaration ::=
   task type defining_identifier [known_discriminant_part]
     [is task_definition];

  3. single_task_declaration ::=
   task defining_identifier [is task_definition];

  4. task_definition ::=
      {task_item}
   [ private
      {task_item}]
   end [task_identifier]

  5. task_item ::= entry_declaration | representation_clause

  6. task_body ::=
   task body defining_identifier is
      declarative_part
   begin
      handled_sequence_of_statements
   end [task_identifier];
    1. If a task_identifier appears at the end of a task_definition or task_body, it shall repeat the defining_identifier.

Legality Rules
  1. A task declaration requires a completion, which shall be a task_body, and every task_body shall be the completion of some task declaration.

    Static Semantics
  2. A task_definition defines a task type and its first subtype. The first list of task_items of a task_definition, together with the known_discriminant_part, if any, is called the visible part of the task unit. The optional list of task_items after the reserved word private is called the private part of the task unit.

    Dynamic Semantics
  3. The elaboration of a task declaration elaborates the task_definition. The elaboration of a single_task_declaration also creates an object of an (anonymous) task type.
  4. The elaboration of a task_definition creates the task type and its first subtype; it also includes the elaboration of the entry_declarations in the given order.
  5. As part of the initialization of a task object, any representation_clauses and any per-object constraints associated with entry_declarations of the corresponding task_definition are elaborated in the given order.
  6. The elaboration of a task_body has no effect other than to establish that tasks of the type can from then on be activated without failing the Elaboration_Check.
  7. The execution of a task_body is invoked by the activation of a task of the corresponding type, see 9.2.
  8. The content of a task object of a given task type includes:
    1. The values of the discriminants of the task object, if any;
    2. An entry queue for each entry of the task object;
    3. A representation of the state of the associated task.

    NOTES

  1. (2) Within the declaration or body of a task unit, the name of the task unit denotes the current instance of the unit, see 8.6, rather than the first subtype of the corresponding task type (and thus the name cannot be used as a subtype_mark).
  2. (3) The notation of a selected_component can be used to denote a discriminant of a task, see 4.1.3. Within a task unit, the name of a discriminant of the task type denotes the corresponding discriminant of the current instance of the unit.
  3. (4) A task type is a limited type, see 7.5, and hence has neither an assignment operation nor predefined equality operators. If an application needs to store and exchange task identities, it can do so by defining an access type designating the corresponding task objects and by using access values for identification purposes. Assignment is available for such an access type as for any access type. Alternatively, if the implementation supports the Systems Programming Annex, the Identity attribute can be used for task identification, see C.7.

    Examples
  4. Examples of declarations of task types: 
  5. task type Server is
   entry Next_Work_Item(WI : in Work_Item);
   entry Shut_Down;
end Server;

  6. task type Keyboard_Driver(ID : Keyboard_ID := New_ID) is
   entry Read (C : out Character);
   entry Write(C : in  Character);
end Keyboard_Driver;
  7. Examples of declarations of single tasks: 
  8. task Controller is
   entry Request(Level)(D : Item);  --  a family of entries
end Controller;

  9. task Parser is
   entry Next_Lexeme(L : in  Lexical_Element);
   entry Next_Action(A : out Parser_Action);
end;

  10. task User;  --  has no entries
  11. Examples of task objects: 
  12. Agent    : Server;
Teletype : Keyboard_Driver(TTY_ID);
Pool     : array(1 .. 10) of Keyboard_Driver;
  13. Example of access type designating task objects: 
  14. type Keyboard is access Keyboard_Driver;
Terminal : Keyboard := new Keyboard_Driver(Term_ID);

Node:9.2, Next:, Previous:9.1, Up:9

Task Execution - Task Activation


Dynamic Semantics
  1. The execution of a task of a given task type consists of the execution of the corresponding task_body. The initial part of this execution is called the activation of the task; it consists of the elaboration of the declarative_part of the task_body. Should an exception be propagated by the elaboration of its declarative_part, the activation of the task is defined to have failed, and it becomes a completed task.
  2. A task object (which represents one task) can be created either as part of the elaboration of an object_declaration occurring immediately within some declarative region, or as part of the evaluation of an allocator. All tasks created by the elaboration of object_declarations of a single declarative region (including subcomponents of the declared objects) are activated together. Similarly, all tasks created by the evaluation of a single allocator are activated together. The activation of a task is associated with the innermost allocator or object_declaration that is responsible for its creation.
  3. For tasks created by the elaboration of object_declarations of a given declarative region, the activations are initiated within the context of the handled_sequence_of_statements (and its associated exception_handlers if any - see 11.2, just prior to executing the statements of the _sequence. For a package without an explicit body or an explicit handled_sequence_of_statements, an implicit body or an implicit null_statement is assumed, as defined in 7.2.
  4. For tasks created by the evaluation of an allocator, the activations are initiated as the last step of evaluating the allocator, after completing any initialization for the object created by the allocator, and prior to returning the new access value.
  5. The task that created the new tasks and initiated their activations (the activator) is blocked until all of these activations complete (successfully or not). Once all of these activations are complete, if the activation of any of the tasks has failed (due to the propagation of an exception), Tasking_Error is raised in the activator, at the place at which it initiated the activations. Otherwise, the activator proceeds with its execution normally. Any tasks that are aborted prior to completing their activation are ignored when determining whether to raise Tasking_Error.
  6. Should the task that created the new tasks never reach the point where it would initiate the activations (due to an abort or the raising of an exception), the newly created tasks become terminated and are never activated.

    NOTES

  7. (5) An entry of a task can be called before the task has been activated.
  8. (6) If several tasks are activated together, the execution of any of these tasks need not await the end of the activation of the other tasks.
  9. (7) A task can become completed during its activation either because of an exception or because it is aborted, see 9.8.

    Examples
  10. Example of task activation: 
  11. procedure P is
   A, B : Server;    --  elaborate the task objects A, B
   C    : Server;    --  elaborate the task object C
begin
   --  the tasks A, B, C are activated together
   --  before the first statement
   ...
end;

Node:9.3, Next:, Previous:9.2, Up:9

Task Dependence - Termination of Tasks


Dynamic Semantics
  1. Each task (other than an environment task - see 10.2, depends on one or more masters, see 7.6.1, as follows:
    1. If the task is created by the evaluation of an allocator for a given access type, it depends on each master that includes the elaboration of the declaration of the ultimate ancestor of the given access type.
    2. If the task is created by the elaboration of an object_declaration, it depends on each master that includes this elaboration.
  1. Furthermore, if a task depends on a given master, it is defined to depend on the task that executes the master, and (recursively) on any master of that task.
  2. A task is said to be completed when the execution of its corresponding task_body is completed. A task is said to be terminated when any finalization of the task_body has been performed, see 7.6.1. The first step of finalizing a master (including a task_body) is to wait for the termination of any tasks dependent on the master. The task executing the master is blocked until all the dependents have terminated. Any remaining finalization is then performed and the master is left.
  3. Completion of a task (and the corresponding task_body) can occur when the task is blocked at a select_statement with an an open terminate_alternative, see 9.7.1, the open terminate_alternative is selected if and only if the following conditions are satisfied:
    1. The task depends on some completed master;
    2. Each task that depends on the master considered is either already terminated or similarly blocked at a select_statement with an open terminate_alternative.
  1. When both conditions are satisfied, the task considered becomes completed, together with all tasks that depend on the master considered that are not yet completed.

    NOTES

  2. (8) The full view of a limited private type can be a task type, or can have subcomponents of a task type. Creation of an object of such a type creates dependences according to the full type.
  3. (9) An object_renaming_declaration defines a new view of an existing entity and hence creates no further dependence.
  4. (10) The rules given for the collective completion of a group of tasks all blocked on select_statements with open terminate_alternatives ensure that the collective completion can occur only when there are no remaining active tasks that could call one of the tasks being collectively completed.
  5. (11) If two or more tasks are blocked on select_statements with open terminate_alternatives, and become completed collectively, their finalization actions proceed concurrently.
  6. (12) The completion of a task can occur due to any of the following:
    1. the raising of an exception during the elaboration of the declarative_part of the corresponding task_body;
    2. the completion of the handled_sequence_of_statements of the corresponding task_body;
    3. the selection of an open terminate_alternative of a select_statement in the corresponding task_body;
    4. the abort of the task.

Examples
  1. Example of task dependence: 
  2. declare
   type Global is access Server; --  see 9.1
   A, B : Server;
   G    : Global;
begin
   --  activation of A and B
   declare
      type Local is access Server;
      X : Global := new Server;  --  activation of X.all
      L : Local  := new Server;  --  activation of L.all
      C : Server;
   begin
      --  activation of C
      G := X;  --  both G and X designate the same task object
      ...
   end;  --  await termination of C and L.all (but not X.all)
   ...
end;  --  await termination of A, B, and G.all

Node:9.4, Next:, Previous:9.3, Up:9

Protected Units and Protected Objects

  1. A protected object provides coordinated access to shared data, through calls on its visible protected operations, which can be protected subprograms or protected entries. A protected unit is declared by a protected declaration, which has a corresponding protected_body. A protected declaration may be a protected_type_declaration, in which case it declares a named protected type; alternatively, it may be a single_protected_declaration, in which case it defines an anonymous protected type, as well as declaring a named protected object of that type.

    Syntax
  2. protected_type_declaration ::=
   protected type defining_identifier [known_discriminant_part] is
     protected_definition;

  3. single_protected_declaration ::=
   protected defining_identifier is protected_definition;

  4. protected_definition ::=
      { protected_operation_declaration }
   [ private
      { protected_element_declaration } ]
   end [protected_identifier]

  5. protected_operation_declaration ::=
     subprogram_declaration
   | entry_declaration
   | representation_clause

  6. protected_element_declaration ::=
   protected_operation_declaration | component_declaration

  7. protected_body ::=
   protected body defining_identifier is
      { protected_operation_item }
   end [protected_identifier];

  8. protected_operation_item ::=
     subprogram_declaration
   | subprogram_body
   | entry_body
   | representation_clause
    1. If a protected_identifier appears at the end of a protected_definition or protected_body, it shall repeat the defining_identifier.

Legality Rules
  1. A protected declaration requires a completion, which shall be a protected_body, and every protected_body shall be the completion of some protected declaration.

    Static Semantics
  2. A protected_definition defines a protected type and its first subtype. The list of protected_operation_declarations of a protected_definition, together with the known_discriminant_part, if any, is called the visible part of the protected unit. The optional list of protected_element_declarations after the reserved word private is called the private part of the protected unit.

    Dynamic Semantics
  3. The elaboration of a protected declaration elaborates the protected_definition. The elaboration of a single_protected_declaration also creates an object of an (anonymous) protected type.
  4. The elaboration of a protected_definition creates the protected type and its first subtype; it also includes the elaboration of the component_declarations and protected_operation_declarations in the given order.
  5. As part of the initialization of a protected object, any per-object constraints, see 3.8, are elaborated.
  6. The elaboration of a protected_body has no other effect than to establish that protected operations of the type can from then on be called without failing the Elaboration_Check.
  7. The content of an object of a given protected type includes:
    1. The values of the components of the protected object, including (implicitly) an entry queue for each entry declared for the protected object;
    2. A representation of the state of the execution resource associated with the protected object (one such resource is associated with each protected object).
  1. The execution resource associated with a protected object has to be acquired to read or update any components of the protected object; it can be acquired (as part of a protected action - see 9.5.1, either for concurrent read-only access, or for exclusive read-write access.
  2. As the first step of the finalization of a protected object, each call remaining on any entry queue of the object is removed from its queue and Program_Error is raised at the place of the corresponding entry_call_statement.

    NOTES

  3. (13) Within the declaration or body of a protected unit, the name of the protected unit denotes the current instance of the unit, see 8.6, rather than the first subtype of the corresponding protected type (and thus the name cannot be used as a subtype_mark).
  4. (14) A selected_component can be used to denote a discriminant of a protected object, see 4.1.3. Within a protected unit, the name of a discriminant of the protected type denotes the corresponding discriminant of the current instance of the unit.
  5. (15) A protected type is a limited type, see 7.5, and hence has neither an assignment operation nor predefined equality operators.
  6. (16) The bodies of the protected operations given in the protected_body define the actions that take place upon calls to the protected operations.
  7. (17) The declarations in the private part are only visible within the private part and the body of the protected unit.

    Examples
  8. Example of declaration of protected type and corresponding body: 
  9. protected type Resource is
   entry Seize;
   procedure Release;
private
   Busy : Boolean := False;
end Resource;

  10. protected body Resource is
   entry Seize when not Busy is
   begin
      Busy := True;
   end Seize;

  11.    procedure Release is
   begin
      Busy := False;
   end Release;
end Resource;
  12. Example of a single protected declaration and corresponding body: 
  13. protected Shared_Array is
   --  Index, Item, and Item_Array are global types
   function  Component    (N : in Index) return Item;
   procedure Set_Component(N : in Index; E : in  Item);
private
   Table : Item_Array(Index) := (others => Null_Item);
end Shared_Array;

  14. protected body Shared_Array is
   function Component(N : in Index) return Item is
   begin
      return Table(N);
   end Component;

  15.    procedure Set_Component(N : in Index; E : in Item) is
   begin
      Table(N) := E;
   end Set_Component;
end Shared_Array;
  16. Examples of protected objects: 
  17. Control  : Resource;
Flags    : array(1 .. 100) of Resource;

Node:9.5, Next:, Previous:9.4, Up:9

Intertask Communication

  1. The primary means for intertask communication is provided by calls on entries and protected subprograms. Calls on protected subprograms allow coordinated access to shared data objects. Entry calls allow for blocking the caller until a given condition is satisfied (namely, that the corresponding entry is open - see 9.5.3.), and then communicating data or control information directly with another task or indirectly via a shared protected object.

    Static Semantics
  2. Any call on an entry or on a protected subprogram identifies a target object for the operation, which is either a task (for an entry call) or a protected object (for an entry call or a protected subprogram call). The target object is considered an implicit parameter to the operation, and is determined by the operation name (or prefix) used in the call on the operation, as follows:
    1. If it is a direct_name or expanded name that denotes the declaration (or body) of the operation, then the target object is implicitly specified to be the current instance of the task or protected unit immediately enclosing the operation; such a call is defined to be an internal call;
    2. If it is a selected_component that is not an expanded name, then the target object is explicitly specified to be the task or protected object denoted by the prefix of the name; such a call is defined to be an external call;
    3. If the name or prefix is a dereference (implicit or explicit) of an access-to-protected-subprogram value, then the target object is determined by the prefix of the Access attribute_reference that produced the access value originally, and the call is defined to be an external call;
    4. If the name or prefix denotes a subprogram_renaming_declaration, then the target object is as determined by the name of the renamed entity.
  1. A corresponding definition of target object applies to a requeue_statement, see 9.5.4, with a corresponding distinction between an internal requeue and an external requeue.

    Dynamic Semantics
  2. Within the body of a protected operation, the current instance (see 8.6) of the immediately enclosing protected unit is determined by the target object specified (implicitly or explicitly) in the call (or requeue) on the protected operation.
  3. Any call on a protected procedure or entry of a target protected object is defined to be an update to the object, as is a requeue on such an entry.

Node:9.5.1, Next:, Previous:9.5, Up:9.5

Protected Subprograms and Protected Actions

  1. A protected subprogram is a subprogram declared immediately within a protected_definition. Protected procedures provide exclusive read-write access to the data of a protected object; protected functions provide concurrent read-only access to the data.

    Static Semantics
  2. Within the body of a protected function (or a function declared immediately within a protected_body), the current instance of the enclosing protected unit is defined to be a constant (that is, its subcomponents may be read but not updated). Within the body of a protected procedure (or a procedure declared immediately within a protected_body), and within an entry_body, the current instance is defined to be a variable (updating is permitted).

    Dynamic Semantics
  3. For the execution of a call on a protected subprogram, the evaluation of the name or prefix and of the parameter associations, and any assigning back of in out or out parameters, proceeds as for a normal subprogram call, see 6.4. If the call is an internal call, see 9.5, the body of the subprogram is executed as for a normal subprogram call. If the call is an external call, then the body of the subprogram is executed as part of a new protected action on the target protected object; the protected action completes after the body of the subprogram is executed. A protected action can also be started by an entry call, see 9.5.3.
  4. A new protected action is not started on a protected object while another protected action on the same protected object is underway, unless both actions are the result of a call on a protected function. This rule is expressible in terms of the execution resource associated with the protected object:
    1. Starting a protected action on a protected object corresponds to acquiring the execution resource associated with the protected object, either for concurrent read-only access if the protected action is for a call on a protected function, or for exclusive read-write access otherwise;
    2. Completing the protected action corresponds to releasing the associated execution resource.
  1. After performing an operation on a protected object other than a call on a protected function, but prior to completing the associated protected action, the entry queues (if any) of the protected object are serviced (see 9.5.3).

    Bounded (Run-Time) Errors
  2. During a protected action, it is a bounded error to invoke an operation that is potentially blocking. The following are defined to be potentially blocking operations:
    1. a select_statement;
    2. an accept_statement;
    3. an entry_call_statement;
    4. a delay_statement;
    5. an abort_statement;
    6. task creation or activation;
    7. an external call on a protected subprogram (or an external requeue) with the same target object as that of the protected action;
    8. a call on a subprogram whose body contains a potentially blocking operation.
  1. If the bounded error is detected, Program_Error is raised. If not detected, the bounded error might result in deadlock or a (nested) protected action on the same target object.
  2. Certain language-defined subprograms are potentially blocking. In particular, the subprograms of the language-defined input-output packages that manipulate files (implicitly or explicitly) are potentially blocking. Other potentially blocking subprograms are identified where they are defined. When not specified as potentially blocking, a language-defined subprogram is nonblocking.

    NOTES

  3. (18) If two tasks both try to start a protected action on a protected object, and at most one is calling a protected function, then only one of the tasks can proceed. Although the other task cannot proceed, it is not considered blocked, and it might be consuming processing resources while it awaits its turn. There is no language-defined ordering or queuing presumed for tasks competing to start a protected action - on a multiprocessor such tasks might use busy-waiting; for monoprocessor considerations, see "Priority Ceiling Locking".
  4. (19) The body of a protected unit may contain declarations and bodies for local subprograms. These are not visible outside the protected unit.
  5. (20) The body of a protected function can contain internal calls on other protected functions, but not protected procedures, because the current instance is a constant. On the other hand, the body of a protected procedure can contain internal calls on both protected functions and procedures.
  6. (21) From within a protected action, an internal call on a protected subprogram, or an external call on a protected subprogram with a different target object is not considered a potentially blocking operation.

    Examples
  7. Examples of protected subprogram calls, see 9.4 
  8. Shared_Array.Set_Component(N, E);
E := Shared_Array.Component(M);
Control.Release;

Node:9.5.2, Next:, Previous:9.5.1, Up:9.5

Entries and Accept Statements

  1. Entry_declarations, with the corresponding entry_bodies or accept_statements, are used to define potentially queued operations on tasks and protected objects.

    Syntax
  2. entry_declaration ::=
   entry defining_identifier [(discrete_subtype_definition)]
     parameter_profile;

  3. accept_statement ::=
   accept entry_direct_name [(entry_index)] parameter_profile
      [do handled_sequence_of_statements
   end [entry_identifier]];

  4. entry_index ::= expression

  5. entry_body ::=
   entry defining_identifier entry_body_formal_part entry_barrier is
      declarative_part
   begin
      handled_sequence_of_statements
   end [entry_identifier];

  6. entry_body_formal_part ::=
   [(entry_index_specification)] parameter_profile

  7. entry_barrier ::= when condition

  8. entry_index_specification ::=
   for defining_identifier in discrete_subtype_definition
    1. If an entry_identifier appears at the end of an accept_statement, it shall repeat the entry_direct_name. If an entry_identifier appears at the end of an entry_body, it shall repeat the defining_identifier.
    2. An entry_declaration is allowed only in a protected or task declaration.

Name Resolution Rules
  1. In an accept_statement, the expected profile for the entry_direct_name is that of the entry_declaration; the expected type for an entry_index is that of the subtype defined by the discrete_subtype_definition of the corresponding entry_declaration.
  2. Within the handled_sequence_of_statements of an accept_statement, if a selected_component has a prefix that denotes the corresponding entry_declaration, then the entity denoted by the prefix is the accept_statement, and the selected_component is interpreted as an expanded name, see 4.1.3, the selector_name of the selected_component has to be the identifier for some formal parameter of the accept_statement.

    Legality Rules
  3. An entry_declaration in a task declaration shall not contain a specification for an access parameter, see 3.10.
  4. For an accept_statement, the innermost enclosing body shall be a task_body, and the entry_direct_name shall denote an entry_declaration in the corresponding task declaration; the profile of the accept_statement shall conform fully to that of the corresponding entry_declaration. An accept_statement shall have a parenthesized entry_index if and only if the corresponding entry_declaration has a discrete_subtype_definition.
  5. An accept_statement shall not be within another accept_statement that corresponds to the same entry_declaration, nor within an asynchronous_select inner to the enclosing task_body.
  6. An entry_declaration of a protected unit requires a completion, which shall be an entry_body, and every entry_body shall be the completion of an entry_declaration of a protected unit. The profile of the entry_body shall conform fully to that of the corresponding declaration.
  7. An entry_body_formal_part shall have an entry_index_specification if and only if the corresponding entry_declaration has a discrete_subtype_definition. In this case, the discrete_subtype_definitions of the entry_declaration and the entry_index_specification shall fully conform to one another (see 6.3.1).
  8. A name that denotes a formal parameter of an entry_body is not allowed within the entry_barrier of the entry_body.

    Static Semantics
  9. The parameter modes defined for parameters in the parameter_profile of an entry_declaration are the same as for a subprogram_declaration and have the same meaning, see 6.2.
  10. An entry_declaration with a discrete_subtype_definition, see 3.6, declares a family of distinct entries having the same profile, with one such entry for each value of the entry index subtype defined by the discrete_subtype_definition. A name for an entry of a family takes the form of an indexed_component, where the prefix denotes the entry_declaration for the family, and the index value identifies the entry within the family. The term single entry is used to refer to any entry other than an entry of an entry family.
  11. In the entry_body for an entry family, the entry_index_specification declares a named constant whose subtype is the entry index subtype defined by the corresponding entry_declaration; the value of the named entry index identifies which entry of the family was called.

    Dynamic Semantics
  12. For the elaboration of an entry_declaration for an entry family, if the discrete_subtype_definition contains no per-object expressions (see 3.8) then the discrete_subtype_definition is elaborated. Otherwise, the elaboration of the entry_declaration consists of the evaluation of any expression of the discrete_subtype_definition that is not a per-object expression (or part of one). The elaboration of an entry_declaration for a single entry has no effect.
  13. The actions to be performed when an entry is called are specified by the corresponding accept_statements (if any) for an entry of a task unit, and by the corresponding entry_body for an entry of a protected unit.
  14. For the execution of an accept_statement, the entry_index, if any, is first evaluated and converted to the entry index subtype; this index value identifies which entry of the family is to be accepted. Further execution of the accept_statement is then blocked until a caller of the corresponding entry is selected, see 9.5.3, whereupon the handled_sequence_of_statements, if any, of the accept_statement is executed, with the formal parameters associated with the corresponding actual parameters of the selected entry call. Upon completion of the handled_sequence_of_statements, the accept_statement completes and is left. When an exception is propagated from the handled_sequence_of_statements of an accept_statement, the same exception is also raised by the execution of the corresponding entry_call_statement.
  15. The above interaction between a calling task and an accepting task is called a rendezvous. After a rendezvous, the two tasks continue their execution independently.
  16. An entry_body is executed when the condition of the entry_barrier evaluates to True and a caller of the corresponding single entry, or entry of the corresponding entry family, has been selected (see 9.5.3). For the execution of the entry_body, the declarative_part of the entry_body is elaborated, and the handled_sequence_of_statements of the body is executed, as for the execution of a subprogram_body. The value of the named entry index, if any, is determined by the value of the entry index specified in the entry_name of the selected entry call (or intermediate requeue_statement - see 9.5.4.

    NOTES

  17. (22) A task entry has corresponding accept_statements (zero or more), whereas a protected entry has a corresponding entry_body (exactly one).
  18. (23) A consequence of the rule regarding the allowed placements of accept_statements is that a task can execute accept_statements only for its own entries.
  19. (24) A return_statement, see 6.5, or a requeue_statement (see 9.5.4) may be used to complete the execution of an accept_statement or an entry_body.
  20. (25) The condition in the entry_barrier may reference anything visible except the formal parameters of the entry. This includes the entry index (if any), the components (including discriminants) of the protected object, the Count attribute of an entry of that protected object, and data global to the protected unit.
  21. The restriction against referencing the formal parameters within an entry_barrier ensures that all calls of the same entry see the same barrier value. If it is necessary to look at the parameters of an entry call before deciding whether to handle it, the entry_barrier can be "when True" and the caller can be requeued (on some private entry) when its parameters indicate that it cannot be handled immediately.

    Examples
  22. Examples of entry declarations: 
  23. entry Read(V : out Item);
entry Seize;
entry Request(Level)(D : Item);  --  a family of entries
  24. Examples of accept statements: 
  25. accept Shut_Down;

  26. accept Read(V : out Item) do
   V := Local_Item;
end Read;

  27. accept Request(Low)(D : Item) do
   ...
end Request;

Node:9.5.3, Next:, Previous:9.5.2, Up:9.5

Entry Calls

  1. An entry_call_statement (an entry call) can appear in various contexts. A simple entry call is a stand-alone statement that represents an unconditional call on an entry of a target task or a protected object. Entry calls can also appear as part of select_statements, see 9.7.

    Syntax
  2. entry_call_statement ::= entry_name [actual_parameter_part];

    Name Resolution Rules
  3. The entry_name given in an entry_call_statement shall resolve to denote an entry. The rules for parameter associations are the same as for subprogram calls, see 6.4, and 6.4.1.

    Static Semantics
  4. The entry_name of an entry_call_statement specifies (explicitly or implicitly) the target object of the call, the entry or entry family, and the entry index, if any, see 9.5.

    Dynamic Semantics
  5. Under certain circumstances (detailed below), an entry of a task or protected object is checked to see whether it is open or closed:
    1. An entry of a task is open if the task is blocked on an accept_statement that corresponds to the entry, see 9.5.2, or on a selective_accept, (see 9.7.1) with an open accept_alternative that corresponds to the entry; otherwise it is closed.
    2. An entry of a protected object is open if the condition of the entry_barrier of the corresponding entry_body evaluates to True; otherwise it is closed. If the evaluation of the condition propagates an exception, the exception Program_Error is propagated to all current callers of all entries of the protected object.
  1. For the execution of an entry_call_statement, evaluation of the name and of the parameter associations is as for a subprogram call, see 6.4. The entry call is then issued: For a call on an entry of a protected object, a new protected action is started on the object, see 9.5.1. The named entry is checked to see if it is open; if open, the entry call is said to be selected immediately, and the execution of the call proceeds as follows:
    1. For a call on an open entry of a task, the accepting task becomes ready and continues the execution of the corresponding accept_statement (see 9.5.2).
    2. For a call on an open entry of a protected object, the corresponding entry_body is executed, see 9.5.2, as part of the protected action.
  1. If the accept_statement or entry_body completes other than by a requeue (see 9.5.4) return is made to the caller (after servicing the entry queues - see below); any necessary assigning back of formal to actual parameters occurs, as for a subprogram call, see 6.4.1, such assignments take place outside of any protected action.
  2. If the named entry is closed, the entry call is added to an entry queue (as part of the protected action, for a call on a protected entry), and the call remains queued until it is selected or cancelled; there is a separate (logical) entry queue for each entry of a given task or protected object (including each entry of an entry family).
  3. When a queued call is selected, it is removed from its entry queue. Selecting a queued call from a particular entry queue is called servicing the entry queue. An entry with queued calls can be serviced under the following circumstances:
    1. When the associated task reaches a corresponding accept_statement, or a selective_accept with a corresponding open accept_alternative;
    2. If after performing, as part of a protected action on the associated protected object, an operation on the object other than a call on a protected function, the entry is checked and found to be open.
  1. If there is at least one call on a queue corresponding to an open entry, then one such call is selected according to the entry queuing policy in effect (see below), and the corresponding accept_statement or entry_body is executed as above for an entry call that is selected immediately.
  2. The entry queuing policy controls selection among queued calls both for task and protected entry queues. The default entry queuing policy is to select calls on a given entry queue in order of arrival. If calls from two or more queues are simultaneously eligible for selection, the default entry queuing policy does not specify which queue is serviced first. Other entry queuing policies can be specified by pragmas (see D.4).
  3. For a protected object, the above servicing of entry queues continues until there are no open entries with queued calls, at which point the protected action completes.
  4. For an entry call that is added to a queue, and that is not the triggering_statement of an asynchronous_select, see 9.7.4, the calling task is blocked until the call is cancelled, or the call is selected and a corresponding accept_statement or entry_body completes without requeuing. In addition, the calling task is blocked during a rendezvous.
  5. An attempt can be made to cancel an entry call upon an abort (see 9.8) and as part of certain forms of select_statement, see 9.7.2, 9.7.3, and 9.7.4. The cancellation does not take place until a point (if any) when the call is on some entry queue, and not protected from cancellation as part of a requeue, see 9.5.4, at such a point, the call is removed from the entry queue and the call completes due to the cancellation. The cancellation of a call on an entry of a protected object is a protected action, and as such cannot take place while any other protected action is occurring on the protected object. Like any protected action, it includes servicing of the entry queues (in case some entry barrier depends on a Count attribute).
  6. A call on an entry of a task that has already completed its execution raises the exception Tasking_Error at the point of the call; similarly, this exception is raised at the point of the call if the called task completes its execution or becomes abnormal before accepting the call or completing the rendezvous, see 9.8. This applies equally to a simple entry call and to an entry call as part of a select_statement.

    Implementation Permissions
  7. An implementation may perform the sequence of steps of a protected action using any thread of control; it need not be that of the task that started the protected action. If an entry_body completes without requeuing, then the corresponding calling task may be made ready without waiting for the entire protected action to complete.
  8. When the entry of a protected object is checked to see whether it is open, the implementation need not reevaluate the condition of the corresponding entry_barrier if no variable or attribute referenced by the condition (directly or indirectly) has been altered by the execution (or cancellation) of a protected procedure or entry call on the object since the condition was last evaluated.
  9. An implementation may evaluate the conditions of all entry_barriers of a given protected object any time any entry of the object is checked to see if it is open.
  10. When an attempt is made to cancel an entry call, the implementation need not make the attempt using the thread of control of the task (or interrupt) that initiated the cancellation; in particular, it may use the thread of control of the caller itself to attempt the cancellation, even if this might allow the entry call to be selected in the interim.

    NOTES

  11. (26) If an exception is raised during the execution of an entry_body, it is propagated to the corresponding caller, see 11.4.
  12. (27) For a call on a protected entry, the entry is checked to see if it is open prior to queuing the call, and again thereafter if its Count attribute, see 9.9, is referenced in some entry barrier.
  13. (28) In addition to simple entry calls, the language permits timed, conditional, and asynchronous entry calls, see 9.7.2, see 9.7.3, and 9.7.4.
  14. (29) The condition of an entry_barrier is allowed to be evaluated by an implementation more often than strictly necessary, even if the evaluation might have side effects. On the other hand, an implementation need not reevaluate the condition if nothing it references was updated by an intervening protected action on the protected object, even if the condition references some global variable that might have been updated by an action performed from outside of a protected action.

    Examples
  15. Examples of entry calls: 
  16. Agent.Shut_Down;                     --  see 9.1
Parser.Next_Lexeme(E);               --  see 9.1
Pool(5).Read(Next_Char);             --  see 9.1
Controller.Request(Low)(Some_Item);  --  see 9.1
Flags(3).Seize;                      --  see 9.4

Node:9.5.4, Next:, Previous:9.5.3, Up:9.5

Requeue Statements

  1. A requeue_statement can be used to complete an accept_statement or entry_body, while redirecting the corresponding entry call to a new (or the same) entry queue. Such a requeue can be performed with or without allowing an intermediate cancellation of the call, due to an abort or the expiration of a delay.

    Syntax
  2. requeue_statement ::= requeue entry_name [with abort];

    Name Resolution Rules
  3. The entry_name of a requeue_statement shall resolve to denote an entry (the target entry) that either has no parameters, or that has a profile that is type conformant, see 6.3.1, with the profile of the innermost enclosing entry_body or accept_statement.

    Legality Rules
  4. A requeue_statement shall be within a callable construct that is either an entry_body or an accept_statement, and this construct shall be the innermost enclosing body or callable construct.
  5. If the target entry has parameters, then its profile shall be subtype conformant with the profile of the innermost enclosing callable construct.
  6. In a requeue_statement of an accept_statement of some task unit, either the target object shall be a part of a formal parameter of the accept_statement, or the accessibility level of the target object shall not be equal to or statically deeper than any enclosing accept_statement of the task unit. In a requeue_statement of an entry_body of some protected unit, either the target object shall be a part of a formal parameter of the entry_body, or the accessibility level of the target object shall not be statically deeper than that of the entry_declaration. Dynamic Semantics
  7. The execution of a requeue_statement proceeds by first evaluating the entry_name, including the prefix identifying the target task or protected object and the expression identifying the entry within an entry family, if any. The entry_body or accept_statement enclosing the requeue_statement is then completed, finalized, and left, see 7.6.1.
  8. For the execution of a requeue on an entry of a target task, after leaving the enclosing callable construct, the named entry is checked to see if it is open and the requeued call is either selected immediately or queued, as for a normal entry call, see 9.5.3.
  9. For the execution of a requeue on an entry of a target protected object, after leaving the enclosing callable construct:
    1. if the requeue is an internal requeue (that is, the requeue is back on an entry of the same protected object - see 9.5.), the call is added to the queue of the named entry and the ongoing protected action continues, see 9.5.1;
    2. if the requeue is an external requeue (that is, the target protected object is not implicitly the same as the current object - see 9.5.), a protected action is started on the target object and proceeds as for a normal entry call, see 9.5.3.
  1. If the new entry named in the requeue_statement has formal parameters, then during the execution of the accept_statement or entry_body corresponding to the new entry, the formal parameters denote the same objects as did the corresponding formal parameters of the callable construct completed by the requeue. In any case, no parameters are specified in a requeue_statement; any parameter passing is implicit.
  2. If the requeue_statement includes the reserved words with abort (it is a requeue-with-abort), then:
    1. if the original entry call has been aborted, see 9.8, then the requeue acts as an abort completion point for the call, and the call is cancelled and no requeue is performed;
    2. if the original entry call was timed (or conditional), then the original expiration time is the expiration time for the requeued call.
  1. If the reserved words with abort do not appear, then the call remains protected against cancellation while queued as the result of the requeue_statement.

    NOTES

  2. (30) A requeue is permitted from a single entry to an entry of an entry family, or vice-versa. The entry index, if any, plays no part in the subtype conformance check between the profiles of the two entries; an entry index is part of the entry_name for an entry of a family.

    Examples
  3. Examples of requeue statements: 
  4. requeue Request(Medium) with abort;
--  requeue on a member of an entry family
--  of the current task, see 9.1

  5. requeue Flags(I).Seize;
--  requeue on an entry of an array
--  component, see 9.4

Node:9.6, Next:, Previous:9.5.4, Up:9

Delay Statements, Duration, and Time

  1. A delay_statement is used to block further execution until a specified expiration time is reached. The expiration time can be specified either as a particular point in time (in a delay_until_statement), or in seconds from the current time (in a delay_relative_statement). The language-defined package Calendar provides definitions for a type Time and associated operations, including a function Clock that returns the current time.

    Syntax
  2. delay_statement ::= delay_until_statement | delay_relative_statement

  3. delay_until_statement ::= delay until delay_expression;

  4. delay_relative_statement ::= delay delay_expression;

    Name Resolution Rules
  5. The expected type for the delay_expression in a delay_relative_statement is the predefined type Duration. The delay_expression in a delay_until_statement is expected to be of any nonlimited type.

    Legality Rules
  6. There can be multiple time bases, each with a corresponding clock, and a corresponding time type. The type of the delay_expression in a delay_until_statement shall be a time type - either the type Time defined in the language-defined package Calendar (see below), or some other implementation-defined time type, see D.8.

    Static Semantics
  7. There is a predefined fixed point type named Duration, declared in the visible part of package Standard; a value of type Duration is used to represent the length of an interval of time, expressed in seconds. The type Duration is not specific to a particular time base, but can be used with any time base.
  8. A value of the type Time in package Calendar, or of some other implementation-defined time type, represents a time as reported by a corresponding clock.
  9. The following language-defined library package exists: 
  10. package Ada.Calendar is
  type Time is private;

  11.   subtype Year_Number  is Integer range 1901 ..  2099;
  subtype Month_Number is Integer range 1 ..  12;
  subtype Day_Number   is Integer range 1 ..  31;
  subtype Day_Duration is Duration range 0.0 ..  86_400.0;

  12.   function Clock return Time;

  13.   function Year   (Date : Time) return Year_Number;
  function Month  (Date : Time) return Month_Number;
  function Day    (Date : Time) return Day_Number;
  function Seconds(Date : Time) return Day_Duration;

  14.   procedure Split (Date  : in Time;
                   Year    : out Year_Number;
                   Month   : out Month_Number;
                   Day     : out Day_Number;
                   Seconds : out Day_Duration);

  15.   function Time_Of(Year  : Year_Number;
                   Month   : Month_Number;
                   Day     : Day_Number;
                   Seconds : Day_Duration := 0.0)
   return Time;

  16.   function "+" (Left : Time;   Right : Duration) return Time;
  function "+" (Left : Duration; Right : Time) return Time;
  function "-" (Left : Time;   Right : Duration) return Time;
  function "-" (Left : Time;   Right : Time) return Duration;

  17.   function "<" (Left, Right : Time) return Boolean;
  function "<="(Left, Right : Time) return Boolean;
  function ">" (Left, Right : Time) return Boolean;
  function ">="(Left, Right : Time) return Boolean;

  18.   Time_Error : exception;

  19. private
   ... -- not specified by the language
end Ada.Calendar;

    Dynamic Semantics
  20. For the execution of a delay_statement, the delay_expression is first evaluated. For a delay_until_statement, the expiration time for the delay is the value of the delay_expression, in the time base associated with the type of the expression. For a delay_relative_statement, the expiration time is defined as the current time, in the time base associated with relative delays, plus the value of the delay_expression converted to the type Duration, and then rounded up to the next clock tick. The time base associated with relative delays is as defined in "Delay Accuracy", or is implementation defined.
  21. The task executing a delay_statement is blocked until the expiration time is reached, at which point it becomes ready again. If the expiration time has already passed, the task is not blocked.
  22. If an attempt is made to cancel the delay_statement (as part of an asynchronous_select or abort - see 9.7.4, and 9.8, the _statement is cancelled if the expiration time has not yet passed, thereby completing the delay_statement.
  23. The time base associated with the type Time of package Calendar is implementation defined. The function Clock of package Calendar returns a value representing the current time for this time base. The implementation-defined value of the named number System.Tick (see 13.7) is an approximation of the length of the real-time interval during which the value of Calendar.Clock remains constant.
  24. The functions Year, Month, Day, and Seconds return the corresponding values for a given value of the type Time, as appropriate to an implementation-defined timezone; the procedure Split returns all four corresponding values. Conversely, the function Time_Of combines a year number, a month number, a day number, and a duration, into a value of type Time. The operators "+" and "-" for addition and subtraction of times and durations, and the relational operators for times, have the conventional meaning.
  25. If Time_Of is called with a seconds value of 86_400.0, the value returned is equal to the value of Time_Of for the next day with a seconds value of 0.0. The value returned by the function Seconds or through the Seconds parameter of the procedure Split is always less than 86_400.0.
  26. The exception Time_Error is raised by the function Time_Of if the actual parameters do not form a proper date. This exception is also raised by the operators "+" and "-" if the result is not representable in the type Time or Duration, as appropriate. This exception is also raised by the function Year or the procedure Split if the year number of the given date is outside of the range of the subtype Year_Number.

    Implementation Requirements
  27. The implementation of the type Duration shall allow representation of time intervals (both positive and negative) up to at least 86400 seconds (one day); Duration'Small shall not be greater than twenty milliseconds. The implementation of the type Time shall allow representation of all dates with year numbers in the range of Year_Number; it may allow representation of other dates as well (both earlier and later).

    Implementation Permissions
  28. An implementation may define additional time types, see D.8.
  29. An implementation may raise Time_Error if the value of a delay_expression in a delay_until_statement of a select_statement represents a time more than 90 days past the current time. The actual limit, if any, is implementation-defined.

    Implementation Advice
  30. Whenever possible in an implementation, the value of Duration'Small should be no greater than 100 microseconds.
  31. The time base for delay_relative_statements should be monotonic; it need not be the same time base as used for Calendar.Clock.

    NOTES

  32. (31) A delay_relative_statement with a negative value of the delay_expression is equivalent to one with a zero value.
  33. (32) A delay_statement may be executed by the environment task; consequently delay_statements may be executed as part of the elaboration of a library_item or the execution of the main subprogram. Such statements delay the environment task, see 10.2.
  34. (33) A delay_statement is an abort completion point and a potentially blocking operation, even if the task is not actually blocked.
  35. (34) There is no necessary relationship between System.Tick (the resolution of the clock of package Calendar) and Duration'Small (the small of type Duration).
  36. (35) Additional requirements associated with delay_statements are given in "Delay Accuracy".

    Examples
  37. Example of a relative delay statement: 
  38. delay 3.0;  -- delay 3.0 seconds
  39. Example of a periodic task: 
  40. declare
   use Ada.Calendar;
   Next_Time : Time := Clock + Period;
                      -- Period is a global constant of type Duration
begin
   loop               -- repeated every Period seconds
      delay until Next_Time;
      ... -- perform some actions
      Next_Time := Next_Time + Period;
   end loop;
end;

Node:9.7, Next:, Previous:9.6, Up:9

Select Statements

  1. There are four forms of the select_statement. One form provides a selective wait for one or more select_alternatives. Two provide timed and conditional entry calls. The fourth provides asynchronous transfer of control.

    Syntax
  2. select_statement ::=
     selective_accept
   | timed_entry_call
   | conditional_entry_call
   | asynchronous_select

    Examples
  3. Example of a select statement: 
  4. select
   accept Driver_Awake_Signal;
or
   delay 30.0*Seconds;
   Stop_The_Train;
end select;

Node:9.7.1, Next:, Previous:9.7, Up:9.7

Selective Accept

  1. This form of the select_statement allows a combination of waiting for, and selecting from, one or more alternatives. The selection may depend on conditions associated with each alternative of the selective_accept.

    Syntax
  2. selective_accept ::=
   select
      [guard]
      select_alternative
 { or
      [guard]
      select_alternative }
    [ else
      sequence_of_statements ]
    end select;

  3. guard ::= when condition =>

  4. select_alternative ::=
     accept_alternative
   | delay_alternative
   | terminate_alternative

  5. accept_alternative ::=
   accept_statement [sequence_of_statements]

  6. delay_alternative ::=
   delay_statement [sequence_of_statements]

  7. terminate_alternative ::= terminate;
    1. A selective_accept shall contain at least one accept_alternative. In addition, it can contain:
      1. a terminate_alternative (only one); or
      2. one or more delay_alternatives; or
      3. an else part (the reserved word else followed by a sequence_of_statements).
    1. These three possibilities are mutually exclusive.

Legality Rules
  1. If a selective_accept contains more than one delay_alternative, then all shall be delay_relative_statements, or all shall be delay_until_statements for the same time type.

    Dynamic Semantics
  2. A select_alternative is said to be open if it is not immediately preceded by a guard, or if the condition of its guard evaluates to True. It is said to be closed otherwise.
  3. For the execution of a selective_accept, any guard conditions are evaluated; open alternatives are thus determined. For an open delay_alternative, the delay_expression is also evaluated. Similarly, for an open accept_alternative for an entry of a family, the entry_index is also evaluated. These evaluations are performed in an arbitrary order, except that a delay_expression or entry_index is not evaluated until after evaluating the corresponding condition, if any. Selection and execution of one open alternative, or of the else part, then completes the execution of the selective_accept; the rules for this selection are described below.
  4. Open accept_alternatives are first considered. Selection of one such alternative takes place immediately if the corresponding entry already has queued calls. If several alternatives can thus be selected, one of them is selected according to the entry queuing policy in effect (see 9.5.3 and D.4). When such an alternative is selected, the selected call is removed from its entry queue and the handled_sequence_of_statements (if any) of the corresponding accept_statement is executed; after the rendezvous completes any subsequent sequence_of_statements of the alternative is executed. If no selection is immediately possible (in the above sense) and there is no else part, the task blocks until an open alternative can be selected.
  5. Selection of the other forms of alternative or of an else part is performed as follows:
    1. An open delay_alternative is selected when its expiration time is reached if no accept_alternative or other delay_alternative can be selected prior to the expiration time. If several delay_alternatives have this same expiration time, one of them is selected according to the queuing policy in effect, see D.4, the default queuing policy chooses arbitrarily among the delay_alternatives whose expiration time has passed.
    2. The else part is selected and its sequence_of_statements is executed if no accept_alternative can immediately be selected; in particular, if all alternatives are closed.
    3. An open terminate_alternative is selected if the conditions stated at the end of clause (see 9.3) are satisfied.
  1. The exception Program_Error is raised if all alternatives are closed and there is no else part.

    NOTES

  2. (36) A selective_accept is allowed to have several open delay_alternatives. A selective_accept is allowed to have several open accept_alternatives for the same entry.

    Examples
  3. Example of a task body with a selective accept: 
  4. task body Server is
   Current_Work_Item : Work_Item;
begin
   loop
      select
         accept Next_Work_Item(WI : in Work_Item) do
            Current_Work_Item := WI;
          end;
          Process_Work_Item(Current_Work_Item);
      or
         accept Shut_Down;
         exit;       -- Premature shut down requested
      or
         terminate;  -- Normal shutdown at end of scope
      end select;
   end loop;
end Server;

Node:9.7.2, Next:, Previous:9.7.1, Up:9.7

Timed Entry Calls

  1. A timed_entry_call issues an entry call that is cancelled if the call (or a requeue-with-abort of the call) is not selected before the expiration time is reached.

    Syntax
  2. timed_entry_call ::=
   select
      entry_call_alternative
   or
      delay_alternative
   end select;

  3. entry_call_alternative ::=
   entry_call_statement [sequence_of_statements]

    Dynamic Semantics
  4. For the execution of a timed_entry_call, the entry_name and the actual parameters are evaluated, as for a simple entry call, see 9.5.3. The expiration time, see 9.6 for the call is determined by evaluating the delay_expression of the delay_alternative; the entry call is then issued.
  5. If the call is queued (including due to a requeue-with-abort), and not selected before the expiration time is reached, an attempt to cancel the call is made. If the call completes due to the cancellation, the optional sequence_of_statements of the delay_alternative is executed; if the entry call completes normally, the optional sequence_of_statements of the entry_call_alternative is executed.

    Examples
  6. Example of a timed entry call: 
  7. select
   Controller.Request(Medium)(Some_Item);
or
   delay 45.0;
   --  controller too busy, try something else
end select;

Node:9.7.3, Next:, Previous:9.7.2, Up:9.7

Conditional Entry Calls

  1. A conditional_entry_call issues an entry call that is then cancelled if it is not selected immediately (or if a requeue-with-abort of the call is not selected immediately).

    Syntax
  2. conditional_entry_call ::=
   select
      entry_call_alternative
   else
      sequence_of_statements
   end select;

    Dynamic Semantics
  3. The execution of a conditional_entry_call is defined to be equivalent to the execution of a timed_entry_call with a delay_alternative specifying an immediate expiration time and the same sequence_of_statements as given after the reserved word else.

    NOTES

  4. (37) A conditional_entry_call may briefly increase the Count attribute of the entry, even if the conditional call is not selected.

    Examples
  5. Example of a conditional entry call: 
  6. procedure Spin(R : in Resource) is
begin
   loop
      select
         R.Seize;
         return;
      else
         null;  --  busy waiting
      end select;
   end loop;
end;

Node:9.7.4, Next:, Previous:9.7.3, Up:9.7

Asynchronous Transfer of Control

  1. An asynchronous select_statement provides asynchronous transfer of control upon completion of an entry call or the expiration of a delay.

    Syntax
  2. asynchronous_select ::=
   select
      triggering_alternative
   then abort
      abortable_part
   end select;

  3. triggering_alternative ::=
   triggering_statement [sequence_of_statements]

  4. triggering_statement ::= entry_call_statement | delay_statement

  5. abortable_part ::= sequence_of_statements

    Dynamic Semantics
  6. For the execution of an asynchronous_select whose triggering_statement is an entry_call_statement, the entry_name and actual parameters are evaluated as for a simple entry call, see 9.5.3, and the entry call is issued. If the entry call is queued (or requeued-with-abort), then the abortable_part is executed. If the entry call is selected immediately, and never requeued-with-abort, then the abortable_part is never started.
  7. For the execution of an asynchronous_select whose triggering_statement is a delay_statement, the delay_expression is evaluated and the expiration time is determined, as for a normal delay_statement. If the expiration time has not already passed, the abortable_part is executed.
  8. If the abortable_part completes and is left prior to completion of the triggering_statement, an attempt to cancel the triggering_statement is made. If the attempt to cancel succeeds, see 9.5.3, and 9.6, the asynchronous_select is complete.
  9. If the triggering_statement completes other than due to cancellation, the abortable_part is aborted (if started but not yet completed - see 9.8). If the triggering_statement completes normally, the optional sequence_of_statements of the triggering_alternative is executed after the abortable_part is left.

    Examples
  10. Example of a main command loop for a command interpreter: 
  11. loop
    select
        Terminal.Wait_For_Interrupt;
        Put_Line("Interrupted");
    then abort
        -- This will be abandoned upon terminal interrupt
        Put_Line("-> ");
        Get_Line(Command, Last);
        Process_Command(Command(1..Last));
    end select;
end loop;
  12. Example of a time-limited calculation: 
  13. select
   delay 5.0;
   Put_Line("Calculation does not converge");
then abort
   -- This calculation should finish in 5.0 seconds;
   --  if not, it is assumed to diverge.
   Horribly_Complicated_Recursive_Function(X, Y);
end select;

Node:9.8, Next:, Previous:9.7.4, Up:9

Abort of a Task - Abort of a Sequence of Statements

  1. An abort_statement causes one or more tasks to become abnormal, thus preventing any further interaction with such tasks. The completion of the triggering_statement of an asynchronous_select causes a sequence_of_statements to be aborted.

    Syntax
  2. abort_statement ::= abort task_name {, task_name};

    Name Resolution Rules
  3. Each task_name is expected to be of any task type; they need not all be of the same task type.

    Dynamic Semantics
  4. For the execution of an abort_statement, the given task_names are evaluated in an arbitrary order. Each named task is then aborted, which consists of making the task abnormal and aborting the execution of the corresponding task_body, unless it is already completed.
  5. When the execution of a construct is aborted (including that of a task_body or of a sequence_of_statements), the execution of every construct included within the aborted execution is also aborted, except for executions included within the execution of an abort-deferred operation; the execution of an abort-deferred operation continues to completion without being affected by the abort; the following are the abort-deferred operations:
    1. a protected action;
    2. waiting for an entry call to complete (after having initiated the attempt to cancel it - see below);
    3. waiting for the termination of dependent tasks;
    4. the execution of an Initialize procedure as the last step of the default initialization of a controlled object;
    5. the execution of a Finalize procedure as part of the finalization of a controlled object;
    6. an assignment operation to an object with a controlled part.
  1. The last three of these are discussed further in 7.6.
  2. When a master is aborted, all tasks that depend on that master are aborted.
  3. The order in which tasks become abnormal as the result of an abort_statement or the abort of a sequence_of_statements is not specified by the language.
  4. If the execution of an entry call is aborted, an immediate attempt is made to cancel the entry call, see 9.5.3. If the execution of a construct is aborted at a time when the execution is blocked, other than for an entry call, at a point that is outside the execution of an abort-deferred operation, then the execution of the construct completes immediately. For an abort due to an abort_statement, these immediate effects occur before the execution of the abort_statement completes. Other than for these immediate cases, the execution of a construct that is aborted does not necessarily complete before the abort_statement completes. However, the execution of the aborted construct completes no later than its next abort completion point (if any) that occurs outside of an abort-deferred operation; the following are abort completion points for an execution:
    1. the point where the execution initiates the activation of another task;
    2. the end of the activation of a task;
    3. the start or end of the execution of an entry call, accept_statement, delay_statement, or abort_statement;
    4. the start of the execution of a select_statement, or of the sequence_of_statements of an exception_handler.

Bounded (Run-Time) Errors
  1. An attempt to execute an asynchronous_select as part of the execution of an abort-deferred operation is a bounded error. Similarly, an attempt to create a task that depends on a master that is included entirely within the execution of an abort-deferred operation is a bounded error. In both cases, Program_Error is raised if the error is detected by the implementation; otherwise the operations proceed as they would outside an abort-deferred operation, except that an abort of the abortable_part or the created task might or might not have an effect.

    Erroneous Execution
  2. If an assignment operation completes prematurely due to an abort, the assignment is said to be disrupted; the target of the assignment or its parts can become abnormal, and certain subsequent uses of the object can be erroneous, as explained in 13.9.1.

    NOTES

  3. (38) An abort_statement should be used only in situations requiring unconditional termination.
  4. (39) A task is allowed to abort any task it can name, including itself.
  5. (40) Additional requirements associated with abort are given in "Preemptive Abort".

Node:9.9, Next:, Previous:9.8, Up:9

Task and Entry Attributes


Dynamic Semantics
  1. For a prefix T that is of a task type (after any implicit dereference), the following attributes are defined:
  2. T'Callable 
    Yields the value True when the task denoted by T is callable,
and False otherwise; a task is callable unless it is
completed or abnormal. The value of this attribute is of the
predefined type Boolean.
  3. T'Terminated 
    Yields the value True if the task denoted by T is terminated,
and False otherwise. The value of this attribute is of the
predefined type Boolean.
  4. For a prefix E that denotes an entry of a task or protected unit, the following attribute is defined. This attribute is only allowed within the body of the task or protected unit, but excluding, in the case of an entry of a task unit, within any program unit that is, itself, inner to the body of the task unit.
  5. E'Count 
    Yields the number of calls presently queued on the entry E of
the current instance of the unit. The value of this
attribute is of the type universal_integer.

    NOTES

  6. (41) For the Count attribute, the entry can be either a single entry or an entry of a family. The name of the entry or entry family can be either a direct_name or an expanded name.
  7. (42) Within task units, algorithms interrogating the attribute E'Count should take precautions to allow for the increase of the value of this attribute for incoming entry calls, and its decrease, for example with timed_entry_calls. Also, a conditional_entry_call may briefly increase this value, even if the conditional call is not accepted.
  8. (43) Within protected units, algorithms interrogating the attribute E'Count in the entry_barrier for the entry E should take precautions to allow for the evaluation of the condition of the barrier both before and after queuing a given caller.

Node:9.10, Next:, Previous:9.9, Up:9

Shared Variables


Static Semantics
  1. If two different objects, including nonoverlapping parts of the same object, are independently addressable, they can be manipulated concurrently by two different tasks without synchronization. Normally, any two nonoverlapping objects are independently addressable. However, if packing, record layout, or Component_Size is specified for a given composite object, then it is implementation defined whether or not two nonoverlapping parts of that composite object are independently addressable.

    Dynamic Semantics
  2. Separate tasks normally proceed independently and concurrently with one another. However, task interactions can be used to synchronize the actions of two or more tasks to allow, for example, meaningful communication by the direct updating and reading of variables shared between the tasks. The actions of two different tasks are synchronized in this sense when an action of one task signals an action of the other task; an action A1 is defined to signal an action A2 under the following circumstances:
    1. If A1 and A2 are part of the execution of the same task, and the language rules require A1 to be performed before A2;
    2. If A1 is the action of an activator that initiates the activation of a task, and A2 is part of the execution of the task that is activated;
    3. If A1 is part of the activation of a task, and A2 is the action of waiting for completion of the activation;
    4. If A1 is part of the execution of a task, and A2 is the action of waiting for the termination of the task;
    5. If A1 is the action of issuing an entry call, and A2 is part of the corresponding execution of the appropriate entry_body or accept_statement.
    6. If A1 is part of the execution of an accept_statement or entry_body, and A2 is the action of returning from the corresponding entry call;
    7. If A1 is part of the execution of a protected procedure body or entry_body for a given protected object, and A2 is part of a later execution of an entry_body for the same protected object;
    8. If A1 signals some action that in turn signals A2.

Erroneous Execution
  1. Given an action of assigning to an object, and an action of reading or updating a part of the same object (or of a neighboring object if the two are not independently addressable), then the execution of the actions is erroneous unless the actions are sequential. Two actions are sequential if one of the following is true:
    1. One action signals the other;
    2. Both actions occur as part of the execution of the same task;
    3. Both actions occur as part of protected actions on the same protected object, and at most one of the actions is part of a call on a protected function of the protected object.
  1. A pragma Atomic or Atomic_Components may also be used to ensure that certain reads and updates are sequential - see C.6.

Node:9.11, Next:, Previous:9.10, Up:9

Example of Tasking and Synchronization


Examples
  1. The following example defines a buffer protected object to smooth variations between the speed of output of a producing task and the speed of input of some consuming task. For instance, the producing task might have the following structure: 
  2. task Producer;

  3. task body Producer is
   Char : Character;
begin
   loop
      ... --  produce the next character Char
      Buffer.Write(Char);
      exit when Char = ASCII.EOT;
   end loop;
end Producer;
  4. and the consuming task might have the following structure: 
  5. task Consumer;

  6. task body Consumer is
   Char : Character;
begin
   loop
      Buffer.Read(Char);
      exit when Char = ASCII.EOT;
      ... --  consume the character Char
   end loop;
end Consumer;
  7. The buffer object contains an internal pool of characters managed in a round-robin fashion. The pool has two indices, an In_Index denoting the space for the next input character and an Out_Index denoting the space for the next output character. 
  8. protected Buffer is
   entry Read (C : out Character);
   entry Write(C : in  Character);
private
   Pool      : String(1 .. 100);
   Count     : Natural := 0;
   In_Index, Out_Index : Positive := 1;
end Buffer;

  9. protected body Buffer is
   entry Write(C : in Character)
      when Count < Pool'Length is
   begin
      Pool(In_Index) := C;
      In_Index := (In_Index mod Pool'Length) + 1;
      Count    := Count + 1;
   end Write;

  10.    entry Read(C : out Character)
      when Count > 0 is
   begin
      C := Pool(Out_Index);
      Out_Index := (Out_Index mod Pool'Length) + 1;
      Count     := Count - 1;
   end Read;
end Buffer;

Node:10, Next:, Previous:9.11, Up:Top

Program Structure and Compilation Issues

  1. The overall structure of programs and the facilities for separate compilation are described in this section. A program is a set of partitions, each of which may execute in a separate address space, possibly on a separate computer.
  2. As explained below, a partition is constructed from library units. Syntactically, the declaration of a library unit is a library_item, as is the body of a library unit. An implementation may support a concept of a program library (or simply, a "library"), which contains library_items and their subunits. Library units may be organized into a hierarchy of children, grandchildren, and so on.
  3. This section has two clauses: (see "Separate Compilation") discusses compile-time issues related to separate compilation. (see "Program Execution") discusses issues related to what is traditionally known as "link time" and "run time" - building and executing partitions.

Node:10.1, Next:, Previous:10, Up:10

Separate Compilation

  1. A program unit is either a package, a task unit, a protected unit, a protected entry, a generic unit, or an explicitly declared subprogram other than an enumeration literal. Certain kinds of program units can be separately compiled. Alternatively, they can appear physically nested within other program units.
  2. The text of a program can be submitted to the compiler in one or more compilations. Each compilation is a succession of compilation_units. A compilation_unit contains either the declaration, the body, or a renaming of a program unit. The representation for a compilation is implementation-defined.
  3. A library unit is a separately compiled program unit, and is always a package, subprogram, or generic unit. Library units may have other (logically nested) library units as children, and may have other program units physically nested within them. A root library unit, together with its children and grandchildren and so on, form a subsystem.

    Implementation Permissions
  4. An implementation may impose implementation-defined restrictions on compilations that contain multiple compilation_units.

Node:10.1.1, Next:, Previous:10.1, Up:10.1

Compilation Units - Library Units

  1. A library_item is a compilation unit that is the declaration, body, or renaming of a library unit. Each library unit (except Standard) has a parent unit, which is a library package or generic library package. A library unit is a child of its parent unit. The root library units are the children of the predefined library package Standard.

    Syntax
  2. compilation ::= {compilation_unit}

  3. compilation_unit ::=
     context_clause library_item
   | context_clause subunit

  4. library_item ::= [private] library_unit_declaration
   | library_unit_body
   | [private] library_unit_renaming_declaration

  5. library_unit_declaration ::=
     subprogram_declaration | package_declaration
   | generic_declaration    | generic_instantiation

  6. library_unit_renaming_declaration ::=
     package_renaming_declaration
   | generic_renaming_declaration
   | subprogram_renaming_declaration

  7. library_unit_body ::= subprogram_body | package_body

  8. parent_unit_name ::= name
  9. A library unit is a program unit that is declared by a library_item. When a program unit is a library unit, the prefix "library" is used to refer to it (or "generic library" if generic), as well as to its declaration and body, as in "library procedure", "library package_body", or "generic library package". The term compilation unit is used to refer to a compilation_unit. When the meaning is clear from context, the term is also used to refer to the library_item of a compilation_unit or to the proper_body of a subunit (that is, the compilation_unit without the context_clause and the separate (parent_unit_name)).
  10. The parent declaration of a library_item (and of the library unit) is the declaration denoted by the parent_unit_name, if any, of the defining_program_unit_name of the library_item. If there is no parent_unit_name, the parent declaration is the declaration of Standard, the library_item is a root library_item, and the library unit (renaming) is a root library unit (renaming). The declaration and body of Standard itself have no parent declaration. The parent unit of a library_item or library unit is the library unit declared by its parent declaration.
  11. The children of a library unit occur immediately within the declarative region of the declaration of the library unit. The ancestors of a library unit are itself, its parent, its parent's parent, and so on. (Standard is an ancestor of every library unit.) The descendant relation is the inverse of the ancestor relation.
  12. A library_unit_declaration or a library_unit_renaming_declaration is private if the declaration is immediately preceded by the reserved word private; it is otherwise public. A library unit is private or public according to its declaration. The public descendants of a library unit are the library unit itself, and the public descendants of its public children. Its other descendants are private descendants.

    Legality Rules
  13. The parent unit of a library_item shall be a library package or generic library package.
  14. If a defining_program_unit_name of a given declaration or body has a parent_unit_name, then the given declaration or body shall be a library_item. The body of a program unit shall be a library_item if and only if the declaration of the program unit is a library_item. In a library_unit_renaming_declaration, the (old) name shall denote a library_item.
  15. A parent_unit_name (which can be used within a defining_program_unit_name of a library_item and in the separate clause of a subunit), and each of its prefixes, shall not denote a renaming_declaration. On the other hand, a name that denotes a library_unit_renaming_declaration is allowed in a with_clause and other places where the name of a library unit is allowed.
  16. If a library package is an instance of a generic package, then every child of the library package shall either be itself an instance or be a renaming of a library unit.
  17. A child of a generic library package shall either be itself a generic unit or be a renaming of some other child of the same generic unit. The renaming of a child of a generic package shall occur only within the declarative region of the generic package.
  18. A child of a parent generic package shall be instantiated or renamed only within the declarative region of the parent generic.
  19. For each declaration or renaming of a generic unit as a child of some parent generic package, there is a corresponding declaration nested immediately within each instance of the parent. This declaration is visible only within the scope of a with_clause that mentions the child generic unit.
  20. A library subprogram shall not override a primitive subprogram.
  21. The defining name of a function that is a compilation unit shall not be an operator_symbol.

    Static Semantics
  22. A subprogram_renaming_declaration that is a library_unit_renaming_declaration is a renaming-as-declaration, not a renaming-as-body.
  23. There are two kinds of dependences among compilation units:
    1. The semantic dependences (see below) are the ones needed to check the compile-time rules across compilation unit boundaries; a compilation unit depends semantically on the other compilation units needed to determine its legality. The visibility rules are based on the semantic dependences.
    2. The elaboration dependences, see 10.2, determine the order of elaboration of library_items.
  1. A library_item depends semantically upon its parent declaration. A subunit depends semantically upon its parent body. A library_unit_body depends semantically upon the corresponding library_unit_declaration, if any. A compilation unit depends semantically upon each library_item mentioned in a with_clause of the compilation unit. In addition, if a given compilation unit contains an attribute_reference of a type defined in another compilation unit, then the given compilation unit depends semantically upon the other compilation unit. The semantic dependence relationship is transitive.

    NOTES

  2. (1) A simple program may consist of a single compilation unit. A compilation need not have any compilation units; for example, its text can consist of pragmas.
  3. (2) The designator of a library function cannot be an operator_symbol, but a nonlibrary renaming_declaration is allowed to rename a library function as an operator. Within a partition, two library subprograms are required to have distinct names and hence cannot overload each other. However, renaming_declarations are allowed to define overloaded names for such subprograms, and a locally declared subprogram is allowed to overload a library subprogram. The expanded name Standard.L can be used to denote a root library unit L (unless the declaration of Standard is hidden) since root library unit declarations occur immediately within the declarative region of package Standard.

    Examples
  4. Examples of library units: 
  5. package Rational_Numbers.IO is
   -- public child of Rational_Numbers, see 7.1
   procedure Put(R : in  Rational);
   procedure Get(R : out Rational);
end Rational_Numbers.IO;

  6. private procedure Rational_Numbers.Reduce(R : in out Rational);
-- private child of Rational_Numbers

  7. with Rational_Numbers.Reduce;   -- refer to a private child
package body Rational_Numbers is
   ...
end Rational_Numbers;

  8. with Rational_Numbers.IO; use Rational_Numbers;
with Ada.Text_io;  --  see A.10
procedure Main is  -- a root library procedure
   R : Rational;
begin
   R := 5/3;       -- construct a rational number, see 7.1
   Ada.Text_IO.Put("The answer is: ");
   IO.Put(R);
   Ada.Text_IO.New_Line;
end Main;

  9. with Rational_Numbers.IO;
package Rational_IO renames Rational_Numbers.IO;
-- a library unit renaming declaration
  10. Each of the above library_items can be submitted to the compiler separately.

Node:10.1.2, Next:, Previous:10.1.1, Up:10.1

Context Clauses - With Clauses

  1. A context_clause is used to specify the library_items whose names are needed within a compilation unit.

    Syntax
  2. context_clause ::= {context_item}

  3. context_item ::= with_clause | use_clause

  4. with_clause ::= with library_unit_name {, library_unit_name};

    Name Resolution Rules
  5. The scope of a with_clause that appears on a library_unit_declaration or library_unit_renaming_declaration consists of the entire declarative region of the declaration, which includes all children and subunits. The scope of a with_clause that appears on a body consists of the body, which includes all subunits.
  6. A library_item is mentioned in a with_clause if it is denoted by a library_unit_name or a prefix in the with_clause.
  7. Outside its own declarative region, the declaration or renaming of a library unit can be visible only within the scope of a with_clause that mentions it. The visibility of the declaration or renaming of a library unit otherwise follows from its placement in the environment.

    Legality Rules
  8. If a with_clause of a given compilation_unit mentions a private child of some library unit, then the given compilation_unit shall be either the declaration of a private descendant of that library unit or the body or subunit of a (public or private) descendant of that library unit.

    NOTES

  9. (3) A library_item mentioned in a with_clause of a compilation unit is visible within the compilation unit and hence acts just like an ordinary declaration. Thus, within a compilation unit that mentions its declaration, the name of a library package can be given in use_clauses and can be used to form expanded names, a library subprogram can be called, and instances of a generic library unit can be declared. If a child of a parent generic package is mentioned in a with_clause, then the corresponding declaration nested within each visible instance is visible within the compilation unit.

Node:10.1.3, Next:, Previous:10.1.2, Up:10.1

Subunits of Compilation Units

  1. Subunits are like child units, with these (important) differences: subunits support the separate compilation of bodies only (not declarations); the parent contains a body_stub to indicate the existence and place of each of its subunits; declarations appearing in the parent's body can be visible within the subunits.

    Syntax
  2. body_stub ::=
     subprogram_body_stub
   | package_body_stub
   | task_body_stub
   | protected_body_stub

  3. subprogram_body_stub ::= subprogram_specification is separate;

  4. package_body_stub ::= package body defining_identifier is separate;

  5. task_body_stub ::= task body defining_identifier is separate;

  6. protected_body_stub ::=
   protected body defining_identifier is separate;

  7. subunit ::= separate (parent_unit_name) proper_body

    Legality Rules
  8. The parent body of a subunit is the body of the program unit denoted by its parent_unit_name. The term subunit is used to refer to a subunit and also to the proper_body of a subunit.
  9. The parent body of a subunit shall be present in the current environment, and shall contain a corresponding body_stub with the same defining_identifier as the subunit.
  10. A package_body_stub shall be the completion of a package_declaration or generic_package_declaration; a task_body_stub shall be the completion of a task_declaration; a protected_body_stub shall be the completion of a protected_declaration.
  11. In contrast, a subprogram_body_stub need not be the completion of a previous declaration, in which case the _stub declares the subprogram. If the _stub is a completion, it shall be the completion of a subprogram_declaration or generic_subprogram_declaration. The profile of a subprogram_body_stub that completes a declaration shall conform fully to that of the declaration.
  12. A subunit that corresponds to a body_stub shall be of the same kind (package_, subprogram_, task_, or protected_) as the body_stub. The profile of a subprogram_body subunit shall be fully conformant to that of the corresponding body_stub.
  13. A body_stub shall appear immediately within the declarative_part of a compilation unit body. This rule does not apply within an instance of a generic unit.
  14. The defining_identifiers of all body_stubs that appear immediately within a particular declarative_part shall be distinct.

    Post-Compilation Rules
  15. For each body_stub, there shall be a subunit containing the corresponding proper_body.

    NOTES

  16. (4) The rules in "The Compilation Process", say that a body_stub is equivalent to the corresponding proper_body. This implies:
    1. Visibility within a subunit is the visibility that would be obtained at the place of the corresponding body_stub (within the parent body) if the context_clause of the subunit were appended to that of the parent body.
    2. The effect of the elaboration of a body_stub is to elaborate the subunit.

Examples
  1. The package Parent is first written without subunits: 
  2. package Parent is
    procedure Inner;
end Parent;

  3. with Ada.Text_IO;
package body Parent is
    Variable : String := "Hello, there.";
    procedure Inner is
    begin
        Ada.Text_IO.Put_Line(Variable);
    end Inner;
end Parent;
  4. The body of procedure Inner may be turned into a subunit by rewriting the package body as follows (with the declaration of Parent remaining the same): 
  5. package body Parent is
    Variable : String := "Hello, there.";
    procedure Inner is separate;
end Parent;

  6. with Ada.Text_IO;
separate(Parent)
procedure Inner is
begin
    Ada.Text_IO.Put_Line(Variable);
end Inner;

Node:10.1.4, Next:, Previous:10.1.3, Up:10.1

The Compilation Process

  1. Each compilation unit submitted to the compiler is compiled in the context of an environment declarative_part (or simply, an environment), which is a conceptual declarative_part that forms the outermost declarative region of the context of any compilation. At run time, an environment forms the declarative_part of the body of the environment task of a partition, see "Program Execution".
  2. The declarative_items of the environment are library_items appearing in an order such that there are no forward semantic dependences. Each included subunit occurs in place of the corresponding stub. The visibility rules apply as if the environment were the outermost declarative region, except that with_clauses are needed to make declarations of library units visible, see 10.1.2.
  3. The mechanisms for creating an environment and for adding and replacing compilation units within an environment are implementation defined.

    Name Resolution Rules
  4. If a library_unit_body that is a subprogram_body is submitted to the compiler, it is interpreted only as a completion if a library_unit_declaration for a subprogram or a generic subprogram with the same defining_program_unit_name already exists in the environment (even if the profile of the body is not type conformant with that of the declaration); otherwise the subprogram_body is interpreted as both the declaration and body of a library subprogram.

    Legality Rules
  5. When a compilation unit is compiled, all compilation units upon which it depends semantically shall already exist in the environment; the set of these compilation units shall be consistent in the sense that the new compilation unit shall not semantically depend (directly or indirectly) on two different versions of the same compilation unit, nor on an earlier version of itself.

    Implementation Permissions
  6. The implementation may require that a compilation unit be legal before inserting it into the environment.
  7. When a compilation unit that declares or renames a library unit is added to the environment, the implementation may remove from the environment any preexisting library_item with the same defining_program_unit_name. When a compilation unit that is a subunit or the body of a library unit is added to the environment, the implementation may remove from the environment any preexisting version of the same compilation unit. When a given compilation unit is removed from the environment, the implementation may also remove any compilation unit that depends semantically upon the given one. If the given compilation unit contains the body of a subprogram to which a pragma Inline applies, the implementation may also remove any compilation unit containing a call to that subprogram.

    NOTES

  8. (5) The rules of the language are enforced across compilation and compilation unit boundaries, just as they are enforced within a single compilation unit.
  9. (6) An implementation may support a concept of a library, which contains library_items. If multiple libraries are supported, the implementation has to define how a single environment is constructed when a compilation unit is submitted to the compiler. Naming conflicts between different libraries might be resolved by treating each library as the root of a hierarchy of child library units.
  10. (7) A compilation unit containing an instantiation of a separately compiled generic unit does not semantically depend on the body of the generic unit. Therefore, replacing the generic body in the environment does not result in the removal of the compilation unit containing the instantiation.

Node:10.1.5, Next:, Previous:10.1.4, Up:10.1

Pragmas and Program Units

  1. This subclause discusses pragmas related to program units, library units, and compilations.

    Name Resolution Rules
  2. Certain pragmas are defined to be program unit pragmas. A name given as the argument of a program unit pragma shall resolve to denote the declarations or renamings of one or more program units that occur immediately within the declarative region or compilation in which the pragma immediately occurs, or it shall resolve to denote the declaration of the immediately enclosing program unit (if any); the pragma applies to the denoted program unit(s). If there are no names given as arguments, the pragma applies to the immediately enclosing program unit.

    Legality Rules
  3. A program unit pragma shall appear in one of these places:
    1. At the place of a compilation_unit, in which case the pragma shall immediately follow in the same compilation (except for other pragmas) a library_unit_declaration that is a subprogram_declaration, generic_subprogram_declaration, or generic_instantiation, and the pragma shall have an argument that is a name denoting that declaration.
    2. Immediately within the declaration of a program unit and before any nested declaration, in which case the argument, if any, shall be a direct_name that denotes the immediately enclosing program unit declaration.
    3. At the place of a declaration other than the first, of a declarative_part or program unit declaration, in which case the pragma shall have an argument, which shall be a direct_name that denotes one or more of the following (and nothing else): a subprogram_declaration, a generic_subprogram_declaration, or a generic_instantiation, of the same declarative_part or program unit declaration.
  1. Certain program unit pragmas are defined to be library unit pragmas. The name, if any, in a library unit pragma shall denote the declaration of a library unit.

    Post-Compilation Rules
  2. Certain pragmas are defined to be configuration pragmas; they shall appear before the first compilation_unit of a compilation. They are generally used to select a partition-wide or system-wide option. The pragma applies to all compilation_units appearing in the compilation, unless there are none, in which case it applies to all future compilation_units compiled into the same environment.

    Implementation Permissions
  3. An implementation may place restrictions on configuration pragmas, so long as it allows them when the environment contains no library_items other than those of the predefined environment.

Node:10.1.6, Next:, Previous:10.1.5, Up:10.1

Environment-Level Visibility Rules

  1. The normal visibility rules do not apply within a parent_unit_name or a context_clause, nor within a pragma that appears at the place of a compilation unit. The special visibility rules for those contexts are given here.

    Static Semantics
  2. Within the parent_unit_name at the beginning of a library_item, and within a with_clause, the only declarations that are visible are those that are library_items of the environment, and the only declarations that are directly visible are those that are root library_items of the environment. Notwithstanding the rules of 4.1.3, an expanded name in a with_clause may consist of a prefix that denotes a generic package and a selector_name that denotes a child of that generic package (The child is necessarily a generic unit, see See 10.1.1).
  3. Within a use_clause or pragma that is within a context_clause, each library_item mentioned in a previous with_clause of the same context_clause is visible, and each root library_item so mentioned is directly visible. In addition, within such a use_clause, if a given declaration is visible or directly visible, each declaration that occurs immediately within the given declaration's visible part is also visible. No other declarations are visible or directly visible.
  4. Within the parent_unit_name of a subunit, library_items are visible as they are in the parent_unit_name of a library_item; in addition, the declaration corresponding to each body_stub in the environment is also visible.
  5. Within a pragma that appears at the place of a compilation unit, the immediately preceding library_item and each of its ancestors is visible. The ancestor root library_item is directly visible.

Node:10.2, Next:, Previous:10.1.6, Up:10

Program Execution

  1. An Ada program consists of a set of partitions, which can execute in parallel with one another, possibly in a separate address space, and possibly on a separate computer.

    Post-Compilation Rules
  2. A partition is a program or part of a program that can be invoked from outside the Ada implementation. For example, on many systems, a partition might be an executable file generated by the system linker. The user can explicitly assign library units to a partition. The assignment is done in an implementation-defined manner. The compilation units included in a partition are those of the explicitly assigned library units, as well as other compilation units needed by those library units. The compilation units needed by a given compilation unit are determined as follows (unless specified otherwise via an implementation-defined pragma, or by some other implementation-defined means):
    1. A compilation unit needs itself;
    2. If a compilation unit is needed, then so are any compilation units upon which it depends semantically;
    3. If a library_unit_declaration is needed, then so is any corresponding library_unit_body;
    4. If a compilation unit with stubs is needed, then so are any corresponding subunits.
  1. The user can optionally designate (in an implementation-defined manner) one subprogram as the main subprogram for the partition. A main subprogram, if specified, shall be a subprogram.
  2. Each partition has an anonymous environment task, which is an implicit outermost task whose execution elaborates the library_items of the environment declarative_part, and then calls the main subprogram, if there is one. A partition's execution is that of its tasks.
  3. The order of elaboration of library units is determined primarily by the elaboration dependences. There is an elaboration dependence of a given library_item upon another if the given library_item or any of its subunits depends semantically on the other library_item. In addition, if a given library_item or any of its subunits has a pragma Elaborate or Elaborate_All that mentions another library unit, then there is an elaboration dependence of the given library_item upon the body of the other library unit, and, for Elaborate_All only, upon each library_item needed by the declaration of the other library unit.
  4. The environment task for a partition has the following structure: 
  5. task Environment_Task;

  6. task body Environment_Task is
    ... (1) -- The environment declarative_part
            -- (that is, the sequence of library_items) goes here.
begin
    ... (2) -- Call the main subprogram, if there is one.
end Environment_Task;
  7. The environment declarative_part at (1) is a sequence of declarative_items consisting of copies of the library_items included in the partition. The order of elaboration of library_items is the order in which they appear in the environment declarative_part:
    1. The order of all included library_items is such that there are no forward elaboration dependences.
    2. Any included library_unit_declaration to which a pragma Elaborate_Body applies is immediately followed by its library_unit_body, if included.
    3. All library_items declared pure occur before any that are not declared pure.
    4. All preelaborated library_items occur before any that are not preelaborated.
  1. There shall be a total order of the library_items that obeys the above rules. The order is otherwise implementation defined.
  2. The full expanded names of the library units and subunits included in a given partition shall be distinct.
  3. The sequence_of_statements of the environment task (see (2) above) consists of either:
      1. A call to the main subprogram, if the partition has one. If the main subprogram has parameters, they are passed; where the actuals come from is implementation defined. What happens to the result of a main function is also implementation defined.
    1. or:
      1. A null_statement, if there is no main subprogram.
  1. The mechanisms for building and running partitions are implementation defined. These might be combined into one operation, as, for example, in dynamic linking, or "load-and-go" systems.

    Dynamic Semantics
  2. The execution of a program consists of the execution of a set of partitions. Further details are implementation defined. The execution of a partition starts with the execution of its environment task, ends when the environment task terminates, and includes the executions of all tasks of the partition. The execution of the (implicit) task_body of the environment task acts as a master for all other tasks created as part of the execution of the partition. When the environment task completes (normally or abnormally), it waits for the termination of all such tasks, and then finalizes any remaining objects of the partition.

    Bounded (Run-Time) Errors
  3. Once the environment task has awaited the termination of all other tasks of the partition, any further attempt to create a task (during finalization) is a bounded error, and may result in the raising of Program_Error either upon creation or activation of the task. If such a task is activated, it is not specified whether the task is awaited prior to termination of the environment task.

    Implementation Requirements
  4. The implementation shall ensure that all compilation units included in a partition are consistent with one another, and are legal according to the rules of the language.

    Implementation Permissions
  5. The kind of partition described in this clause is known as an active partition. An implementation is allowed to support other kinds of partitions, with implementation-defined semantics.
  6. An implementation may restrict the kinds of subprograms it supports as main subprograms. However, an implementation is required to support all main subprograms that are public parameterless library procedures.
  7. If the environment task completes abnormally, the implementation may abort any dependent tasks.

    NOTES

  8. (8) An implementation may provide inter-partition communication mechanism(s) via special packages and pragmas. Standard pragmas for distribution and methods for specifying inter-partition communication are defined in "Distributed Systems". If no such mechanisms are provided, then each partition is isolated from all others, and behaves as a program in and of itself.
  9. (9) Partitions are not required to run in separate address spaces. For example, an implementation might support dynamic linking via the partition concept.
  10. (10) An order of elaboration of library_items that is consistent with the partial ordering defined above does not always ensure that each library_unit_body is elaborated before any other compilation unit whose elaboration necessitates that the library_unit_body be already elaborated (In particular, there is no requirement that the body of a library unit be elaborated as soon as possible after the library_unit_declaration is elaborated, unless the pragmas in subclause, see 10.2.1, are used).
  11. (11) A partition (active or otherwise) need not have a main subprogram. In such a case, all the work done by the partition would be done by elaboration of various library_items, and by tasks created by that elaboration. Passive partitions, which cannot have main subprograms, are defined in "Distributed Systems".

Node:10.2.1, Next:, Previous:10.2, Up:10.2

Elaboration Control

  1. This subclause defines pragmas that help control the elaboration order of library_items.

    Syntax
  2. The form of a pragma Preelaborate is as follows: 
  3. pragma Preelaborate[(library_unit_name)];
    1. A pragma Preelaborate is a library unit pragma.

Legality Rules
  1. An elaborable construct is preelaborable unless its elaboration performs any of the following actions:
    1. The execution of a statement other than a null_statement.
    2. A call to a subprogram other than a static function.
    3. The evaluation of a primary that is a name of an object, unless the name is a static expression, or statically denotes a discriminant of an enclosing type.
    4. The creation of a default-initialized object (including a component) of a descendant of a private type, private extension, controlled type, task type, or protected type with entry_declarations; similarly the evaluation of an extension_aggregate with an ancestor subtype_mark denoting a subtype of such a type.
  1. A generic body is preelaborable only if elaboration of a corresponding instance body would not perform any such actions, presuming that the actual for each formal private type (or extension) is a private type (or extension), and the actual for each formal subprogram is a user-defined subprogram.
  2. If a pragma Preelaborate (or pragma Pure - see below) applies to a library unit, then it is preelaborated. If a library unit is preelaborated, then its declaration, if any, and body, if any, are elaborated prior to all non-preelaborated library_items of the partition. All compilation units of a preelaborated library unit shall be preelaborable. In addition to the places where Legality Rules normally apply, see 12.3, this rule applies also in the private part of an instance of a generic unit. In addition, all compilation units of a preelaborated library unit shall depend semantically only on compilation units of other preelaborated library units.

    Implementation Advice
  3. In an implementation, a type declared in a preelaborated package should have the same representation in every elaboration of a given version of the package, whether the elaborations occur in distinct executions of the same program, or in executions of distinct programs or partitions that include the given version.

    Syntax
  4. The form of a pragma Pure is as follows: 
  5. pragma Pure[(library_unit_name)];
    1. A pragma Pure is a library unit pragma.

      Legality Rules
  1. A pure library_item is a preelaborable library_item that does not contain the declaration of any variable or named access type, except within a subprogram, generic subprogram, task unit, or protected unit.
  2. A pragma Pure is used to declare that a library unit is pure. If a pragma Pure applies to a library unit, then its compilation units shall be pure, and they shall depend semantically only on compilation units of other library units that are declared pure.

    Implementation Permissions
  3. If a library unit is declared pure, then the implementation is permitted to omit a call on a library-level subprogram of the library unit if the results are not needed after the call. Similarly, it may omit such a call and simply reuse the results produced by an earlier call on the same subprogram, provided that none of the parameters are of a limited type, and the addresses and values of all by-reference actual parameters, and the values of all by-copy-in actual parameters, are the same as they were at the earlier call. This permission applies even if the subprogram produces other side effects when called.

    Syntax
  4. The form of a pragma Elaborate, Elaborate_All, or Elaborate_Body is as follows: 
  5. pragma Elaborate(library_unit_name{, library_unit_name});

  6. pragma Elaborate_All(library_unit_name{, library_unit_name});

  7. pragma Elaborate_Body[(library_unit_name)];
    1. A pragma Elaborate or Elaborate_All is only allowed within a context_clause.
    2. A pragma Elaborate_Body is a library unit pragma.

Legality Rules
  1. If a pragma Elaborate_Body applies to a declaration, then the declaration requires a completion (a body).

    Static Semantics
  2. A pragma Elaborate specifies that the body of the named library unit is elaborated before the current library_item. A pragma Elaborate_All specifies that each library_item that is needed by the named library unit declaration is elaborated before the current library_item. A pragma Elaborate_Body specifies that the body of the library unit is elaborated immediately after its declaration.

    NOTES

  3. (12) A preelaborated library unit is allowed to have non-preelaborable children.
  4. (13) A library unit that is declared pure is allowed to have impure children.

Node:11, Next:, Previous:10.2.1, Up:Top

Exceptions

  1. This section defines the facilities for dealing with errors or other exceptional situations that arise during program execution. An exception represents a kind of exceptional situation; an occurrence of such a situation (at run time) is called an exception occurrence. To raise an exception is to abandon normal program execution so as to draw attention to the fact that the corresponding situation has arisen. Performing some actions in response to the arising of an exception is called handling the exception.
  2. An exception_declaration declares a name for an exception. An exception is raised initially either by a raise_statement or by the failure of a language-defined check. When an exception arises, control can be transferred to a user-provided exception_handler at the end of a handled_sequence_of_statements, or it can be propagated to a dynamically enclosing execution.

Node:11.1, Next:, Previous:11, Up:11

Exception Declarations

  1. An exception_declaration declares a name for an exception.

    Syntax
  2. exception_declaration ::= defining_identifier_list : exception;

    Static Semantics
  3. Each single exception_declaration declares a name for a different exception. If a generic unit includes an exception_declaration, the exception_declarations implicitly generated by different instantiations of the generic unit refer to distinct exceptions (but all have the same defining_identifier). The particular exception denoted by an exception name is determined at compilation time and is the same regardless of how many times the exception_declaration is elaborated.
  4. The predefined exceptions are the ones declared in the declaration of package Standard: Constraint_Error, Program_Error, Storage_Error, and Tasking_Error; one of them is raised when a language-defined check fails.

    Dynamic Semantics
  5. The elaboration of an exception_declaration has no effect.
  6. The execution of any construct raises Storage_Error if there is insufficient storage for that execution. The amount of storage needed for the execution of constructs is unspecified.

    Examples
  7. Examples of user-defined exception declarations: 
  8. Singular            : exception;
Error               : exception;
Overflow, Underflow : exception;

Node:11.2, Next:, Previous:11.1, Up:11

Exception Handlers

  1. The response to one or more exceptions is specified by an exception_handler.

    Syntax
  2. handled_sequence_of_statements ::=
      sequence_of_statements
   [exception
      exception_handler
      {exception_handler}]

  3. exception_handler ::=
  when [choice_parameter_specification:]
    exception_choice {| exception_choice} =>
     sequence_of_statements

  4. choice_parameter_specification ::= defining_identifier

  5. exception_choice ::= exception_name | others

    Legality Rules
  6. A choice with an exception_name covers the named exception. A choice with others covers all exceptions not named by previous choices of the same handled_sequence_of_statements. Two choices in different exception_handlers of the same handled_sequence_of_statements shall not cover the same exception.
  7. A choice with others is allowed only for the last handler of a handled_sequence_of_statements and as the only choice of that handler.
  8. An exception_name of a choice shall not denote an exception declared in a generic formal package.

    Static Semantics
  9. A choice_parameter_specification declares a choice parameter, which is a constant object of type Exception_Occurrence, see 11.4.1. During the handling of an exception occurrence, the choice parameter, if any, of the handler represents the exception occurrence that is being handled.

    Dynamic Semantics
  10. The execution of a handled_sequence_of_statements consists of the execution of the sequence_of_statements. The optional handlers are used to handle any exceptions that are propagated by the sequence_of_statements.

    Examples
  11. Example of an exception handler: 
  12. begin
   Open(File, In_File, "input.txt");   --  see A.8.2
exception
   when E : Name_Error =>
      Put("Cannot open input file : ");
      Put_Line(Exception_Message(E));  --  see 11.4.1
      raise;
end;

Node:11.3, Next:, Previous:11.2, Up:11

Raise Statements

  1. A raise_statement raises an exception.

    Syntax
  2. raise_statement ::= raise [exception_name];

    Legality Rules
  3. The name, if any, in a raise_statement shall denote an exception. A raise_statement with no exception_name (that is, a re-raise statement) shall be within a handler, but not within a body enclosed by that handler.

    Dynamic Semantics
  4. To raise an exception is to raise a new occurrence of that exception, as explained in 11.4. For the execution of a raise_statement with an exception_name, the named exception is raised. For the execution of a re-raise statement, the exception occurrence that caused transfer of control to the innermost enclosing handler is raised again.

    Examples
  5. Examples of raise statements: 
  6. raise Ada.IO_Exceptions.Name_Error;  --  see A.13

  7. raise;
--  re-raise the current exception

Node:11.4, Next:, Previous:11.3, Up:11

Exception Handling

  1. When an exception occurrence is raised, normal program execution is abandoned and control is transferred to an applicable exception_handler, if any. To handle an exception occurrence is to respond to the exceptional event. To propagate an exception occurrence is to raise it again in another context; that is, to fail to respond to the exceptional event in the present context.

    Dynamic Semantics
  2. Within a given task, if the execution of construct a is defined by this International Standard to consist (in part) of the execution of construct b, then while b is executing, the execution of a is said to dynamically enclose the execution of b. The innermost dynamically enclosing execution of a given execution is the dynamically enclosing execution that started most recently.
  3. When an exception occurrence is raised by the execution of a given construct, the rest of the execution of that construct is abandoned; that is, any portions of the execution that have not yet taken place are not performed. The construct is first completed, and then left, as explained in 7.6.1. Then:
    1. If the construct is a task_body, the exception does not propagate further;
    2. If the construct is the sequence_of_statements of a handled_sequence_of_statements that has a handler with a choice covering the exception, the occurrence is handled by that handler;
    3. Otherwise, the occurrence is propagated to the innermost dynamically enclosing execution, which means that the occurrence is raised again in that context.
  1. When an occurrence is handled by a given handler, the choice_parameter_specification, if any, is first elaborated, which creates the choice parameter and initializes it to the occurrence. Then, the sequence_of_statements of the handler is executed; this execution replaces the abandoned portion of the execution of the sequence_of_statements.

    NOTES

  2. (1) Note that exceptions raised in a declarative_part of a body are not handled by the handlers of the handled_sequence_of_statements of that body.

Node:11.4.1, Next:, Previous:11.4, Up:11.4

The Package Exceptions


Static Semantics
  1. The following language-defined library package exists: 
  2. package Ada.Exceptions is
    type Exception_Id is private;
    Null_Id : constant Exception_Id;
    function Exception_Name(Id : Exception_Id) return String;

  3.     type Exception_Occurrence is limited private;
    type Exception_Occurrence_Access is
      access all Exception_Occurrence;
    Null_Occurrence : constant Exception_Occurrence;

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

  5.     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 Exception_Information(X : Exception_Occurrence)
      return String;

  6.     procedure Save_Occurrence(Target : out Exception_Occurrence;
                              Source : in Exception_Occurrence);
    function Save_Occurrence(Source : Exception_Occurrence)
                             return Exception_Occurrence_Access;
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. 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. Raise_Exception raises a new occurrence of the identified exception. In this case, Exception_Message returns the Message parameter of Raise_Exception. For a raise_statement with an exception_name, Exception_Message returns implementation-defined information about the exception occurrence. Reraise_Occurrence reraises the specified exception occurrence.
  11. Exception_Identity returns the identity of the exception of the occurrence.
  12. The 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.
  13. Exception_Information returns implementation-defined information about the exception occurrence.
  14. Raise_Exception and Reraise_Occurrence have no effect in the case of Null_Id or Null_Occurrence. Exception_Message, Exception_Identity, Exception_Name, and Exception_Information raise Constraint_Error for a Null_Id or Null_Occurrence.
  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.

    Implementation Requirements
  16. The implementation of the Write attribute, see 13.13.2, of Exception_Occurrence shall support writing a representation of an exception occurrence to a stream; the implementation of the Read attribute of Exception_Occurrence shall support reconstructing an exception occurrence from a stream (including one written in a different partition).

    Implementation Permissions
  17. An implementation of Exception_Name in a space-constrained environment may return the defining_identifier 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.

Node:11.4.2, Next:, Previous:11.4.1, Up:11.4

Example of Exception Handling


Examples
  1. Exception handling may be used to separate the detection of an error from the response to that error: 
  2. with Ada.Exceptions;
use Ada;
package File_System is
    type File_Handle is limited private;

  3.     File_Not_Found : exception;
    procedure Open(F : in out File_Handle; Name : String);
    --  raises File_Not_Found if named file does not exist

  4.     End_Of_File : exception;
    procedure Read(F : in out File_Handle; Data : out Data_Type);
    --  raises End_Of_File if the file is not open

  5.     ...
end File_System;

  6. package body File_System is
    procedure Open(F : in out File_Handle; Name : String) is
    begin
        if File_Exists(Name) then
            ...
        else
            Exceptions.Raise_Exception
              (File_Not_Found'Identity,
               "File not found: " & Name & ".");
        end if;
    end Open;

  7.     procedure Read(F : in out File_Handle; Data : out Data_Type) is
    begin
        if F.Current_Position <= F.Last_Position then
            ...
        else
            raise End_Of_File;
        end if;
    end Read;

  8.     ...

  9. end File_System;

  10. with Ada.Text_IO;
with Ada.Exceptions;
with File_System; use File_System;
use Ada;
procedure Main is
begin
    ... -- call operations in File_System
exception
    when End_Of_File =>
        Close(Some_File);
    when Not_Found_Error : File_Not_Found =>
        Text_IO.Put_Line
          (Exceptions.Exception_Message(Not_Found_Error));
    when The_Error : others =>
        Text_IO.Put_Line("Unknown error:");
        if Verbosity_Desired then
            Text_IO.Put_Line(Exceptions.Exception_Information
              (The_Error));
        else
            Text_IO.Put_Line(Exceptions.Exception_Name
              (The_Error));
            Text_IO.Put_Line(Exceptions.Exception_Message
              (The_Error));
        end if;
        raise;
end Main;
  11. In the above example, the File_System package contains information about detecting certain exceptional situations, but it does not specify how to handle those situations. Procedure Main specifies how to handle them; other clients of File_System might have different handlers, even though the exceptional situations arise from the same basic causes.

Node:11.5, Next:, Previous:11.4.2, Up:11

Suppressing Checks

  1. A pragma Suppress gives permission to an implementation to omit certain language-defined checks.
  2. A language-defined check (or simply, a "check") is one of the situations defined by this International Standard that requires a check to be made at run time to determine whether some condition is true. A check fails when the condition being checked is false, causing an exception to be raised.

    Syntax
  3. The form of a pragma Suppress is as follows: 
  4. pragma Suppress(identifier [, [On =>] name]);
    1. A pragma Suppress is allowed only immediately within a declarative_part, immediately within a package_specification, or as a configuration pragma.

Legality Rules
  1. The identifier shall be the name of a check. The name (if present) shall statically denote some entity.
  2. For a pragma Suppress that is immediately within a package_specification and includes a name, the name shall denote an entity (or several overloaded subprograms) declared immediately within the package_specification.

    Static Semantics
  3. A pragma Suppress gives permission to an implementation to omit the named check from the place of the pragma to the end of the innermost enclosing declarative region, or, if the pragma is given in a package_specification and includes a name, to the end of the scope of the named entity. If the pragma includes a name, the permission applies only to checks performed on the named entity, or, for a subtype, on objects and values of its type. Otherwise, the permission applies to all entities. If permission has been given to suppress a given check, the check is said to be suppressed.
  4. The following are the language-defined checks:
    1. The following checks correspond to situations in which the exception Constraint_Error is raised upon failure.
      1. Access_Check 
        When evaluating a dereference (explicit or
implicit), check that the value of the name is
not null. When passing an actual parameter to a
formal access parameter, check that the value of
the actual parameter is not null.
      2. Discriminant_Check 
        Check that the discriminants of a composite value
have the values imposed by a discriminant
constraint. Also, when accessing a record
component, check that it exists for the current
discriminant values.
      3. Division_Check 
        Check that the second operand is not zero for the
operations /, rem and mod.
      4. Index_Check 
        Check that the bounds of an array value are equal
to the corresponding bounds of an index
constraint. Also, when accessing a component of
an array object, check for each dimension that
the given index value belongs to the range
defined by the bounds of the array object. Also,
when accessing a slice of an array object, check
that the given discrete range is compatible with
the range defined by the bounds of the array
object.
      5. Length_Check 
        Check that two arrays have matching components,
in the case of array subtype conversions, and
logical operators for arrays of boolean
components.
      6. Overflow_Check 
        Check that a scalar value is within the base
range of its type, in cases where the
implementation chooses to raise an exception
instead of returning the correct mathematical
result.
      7. Range_Check 
        Check that a scalar value satisfies a range
constraint. Also, for the elaboration of a
subtype_indication, check that the constraint (if
present) is compatible with the subtype denoted
by the subtype_mark. Also, for an aggregate,
check that an index or discriminant value belongs
to the corresponding subtype. Also, check that
when the result of an operation yields an array,
the value of each component belongs to the
component subtype.
      8. Tag_Check 
        Check that operand tags in a dispatching call are
all equal. Check for the correct tag on tagged
type conversions, for an assignment_statement,
and when returning a tagged limited object from a
function.
    1. The following checks correspond to situations in which the exception Program_Error is raised upon failure.
      1. Elaboration_Check 
        When a subprogram or protected entry is called, a
task activation is accomplished, or a generic
instantiation is elaborated, check that the body
of the corresponding unit has already been
elaborated.
      2. Accessibility_Check 
        Check the accessibility level of an entity or
view.
    1. The following check corresponds to situations in which the exception Storage_Error is raised upon failure.
      1. Storage_Check 
        Check that evaluation of an allocator does not
require more space than is available for a
storage pool. Check that the space available for
a task or subprogram has not been exceeded.
    1. The following check corresponds to all situations in which any predefined exception is raised.
      1. All_Checks 
        Represents the union of all checks; suppressing
All_Checks suppresses all checks.

Erroneous Execution
  1. If a given check has been suppressed, and the corresponding error situation occurs, the execution of the program is erroneous.

    Implementation Permissions
  2. An implementation is allowed to place restrictions on Suppress pragmas. An implementation is allowed to add additional check names, with implementation-defined semantics. When Overflow_Check has been suppressed, an implementation may also suppress an unspecified subset of the Range_Checks.

    Implementation Advice
  3. The implementation should minimize the code executed for checks that have been suppressed.

    NOTES

  4. (2) There is no guarantee that a suppressed check is actually removed; hence a pragma Suppress should be used only for efficiency reasons.

    Examples
  5. Examples of suppressing checks: 
  6. pragma Suppress(Range_Check);
pragma Suppress(Index_Check, On => Table);

Node:11.6, Next:, Previous:11.5, Up:11

Exceptions and Optimization

  1. This clause gives permission to the implementation to perform certain "optimizations" that do not necessarily preserve the canonical semantics.

    Dynamic Semantics
  2. The rest of this International Standard (outside this clause) defines the canonical semantics of the language. The canonical semantics of a given (legal) program determines a set of possible external effects that can result from the execution of the program with given inputs.
  3. As explained in "Conformity of an Implementation With the Standard", the external effect of a program is defined in terms of its interactions with its external environment. Hence, the implementation can perform any internal actions whatsoever, in any order or in parallel, so long as the external effect of the execution of the program is one that is allowed by the canonical semantics, or by the rules of this clause.

    Implementation Permissions
  4. The following additional permissions are granted to the implementation:
    1. An implementation need not always raise an exception when a language-defined check fails. Instead, the operation that failed the check can simply yield an undefined result. The exception need be raised by the implementation only if, in the absence of raising it, the value of this undefined result would have some effect on the external interactions of the program. In determining this, the implementation shall not presume that an undefined result has a value that belongs to its subtype, nor even to the base range of its type, if scalar. Having removed the raise of the exception, the canonical semantics will in general allow the implementation to omit the code for the check, and some or all of the operation itself.
    2. If an exception is raised due to the failure of a language-defined check, then upon reaching the corresponding exception_handler (or the termination of the task, if none), the external interactions that have occurred need reflect only that the exception was raised somewhere within the execution of the sequence_of_statements with the handler (or the task_body), possibly earlier (or later if the interactions are independent of the result of the checked operation) than that defined by the canonical semantics, but not within the execution of some abort-deferred operation or independent subprogram that does not dynamically enclose the execution of the construct whose check failed. An independent subprogram is one that is defined outside the library unit containing the construct whose check failed, and has no Inline pragma applied to it. Any assignment that occurred outside of such abort-deferred operations or independent subprograms can be disrupted by the raising of the exception, causing the object or its parts to become abnormal, and certain subsequent uses of the object to be erroneous, as explained in 13.9.1.

    NOTES

  1. (3) The permissions granted by this clause can have an effect on the semantics of a program only if the program fails a language-defined check.

Node:12, Next:, Previous:11.6, Up:Top

Generic Units

  1. A generic unit is a program unit that is either a generic subprogram or a generic package. A generic unit is a template, which can be parameterized, and from which corresponding (nongeneric) subprograms or packages can be obtained. The resulting program units are said to be instances of the original generic unit.
  2. A generic unit is declared by a generic_declaration. This form of declaration has a generic_formal_part declaring any generic formal parameters. An instance of a generic unit is obtained as the result of a generic_instantiation with appropriate generic actual parameters for the generic formal parameters. An instance of a generic subprogram is a subprogram. An instance of a generic package is a package.
  3. Generic units are templates. As templates they do not have the properties that are specific to their nongeneric counterparts. For example, a generic subprogram can be instantiated but it cannot be called. In contrast, an instance of a generic subprogram is a (nongeneric) subprogram; hence, this instance can be called but it cannot be used to produce further instances.

Node:12.1, Next:, Previous:12, Up:12

Generic Declarations

  1. A generic_declaration declares a generic unit, which is either a generic subprogram or a generic package. A generic_declaration includes a generic_formal_part declaring any generic formal parameters. A generic formal parameter can be an object; alternatively (unlike a parameter of a subprogram), it can be a type, a subprogram, or a package.

    Syntax
  2. generic_declaration ::=
   generic_subprogram_declaration | generic_package_declaration

  3. generic_subprogram_declaration ::=
   generic_formal_part subprogram_specification;

  4. generic_package_declaration ::=
   generic_formal_part package_specification;

  5. generic_formal_part ::=
   generic {generic_formal_parameter_declaration | use_clause}

  6. generic_formal_parameter_declaration ::=
      formal_object_declaration
    | formal_type_declaration
    | formal_subprogram_declaration
    | formal_package_declaration
    1. The only form of subtype_indication allowed within a generic_formal_part is a subtype_mark (that is, the subtype_indication shall not include an explicit constraint). The defining name of a generic subprogram shall be an identifier (not an operator_symbol).

Static Semantics
  1. A generic_declaration declares a generic unit - a generic package, generic procedure or generic function, as appropriate.
  2. An entity is a generic formal entity if it is declared by a generic_formal_parameter_declaration. "Generic formal," or simply "formal," is used as a prefix in referring to objects, subtypes (and types), functions, procedures and packages, that are generic formal entities, as well as to their respective declarations. Examples: "generic formal procedure" or a "formal integer type declaration."

    Dynamic Semantics
  3. The elaboration of a generic_declaration has no effect.

    NOTES

  4. (1) Outside a generic unit a name that denotes the generic_declaration denotes the generic unit. In contrast, within the declarative region of the generic unit, a name that denotes the generic_declaration denotes the current instance.
  5. (2) Within a generic subprogram_body, the name of this program unit acts as the name of a subprogram. Hence this name can be overloaded, and it can appear in a recursive call of the current instance. For the same reason, this name cannot appear after the reserved word new in a (recursive) generic_instantiation.
  6. (3) A default_expression or default_name appearing in a generic_formal_part is not evaluated during elaboration of the generic_formal_part; instead, it is evaluated when used. (The usual visibility rules apply to any name used in a default: the denoted declaration therefore has to be visible at the place of the expression.)

    Examples
  7. Examples of generic formal parts: 
  8. generic     --  parameterless

  9. generic
    Size : Natural;  --  formal object

  10. generic
   Length : Integer := 200;
   --  formal object with a default expression

  11.    Area : Integer := Length*Length;
   --  formal object with a default expression

  12. generic
   type Item  is private;                        -- formal type
   type Index is (<>);                           -- formal type
   type Row   is array(Index range <>) of Item;  -- formal type
   with function "<"(X, Y : Item) return Boolean;
   --  formal subprogram
  13. Examples of generic declarations declaring generic subprograms Exchange and Squaring: 
  14. generic
   type Elem is private;
procedure Exchange(U, V : in out Elem);

  15. generic
   type Item is private;
   with function "*"(U, V : Item) return Item is <>;
function Squaring(X : Item) return Item;
  16. Example of a generic declaration declaring a generic package: 
  17. generic
   type Item   is private;
   type Vector is array (Positive range <>) of Item;
   with function Sum(X, Y : Item) return Item;
package On_Vectors is
   function Sum  (A, B : Vector) return Vector;
   function Sigma(A    : Vector) return Item;
   Length_Error : exception;
end On_Vectors;

Node:12.2, Next:, Previous:12.1, Up:12

Generic Bodies

  1. The body of a generic unit (a generic body) is a template for the instance bodies. The syntax of a generic body is identical to that of a nongeneric body.

    Dynamic Semantics
  2. The elaboration of a generic body has no other effect than to establish that the generic unit can from then on be instantiated without failing the Elaboration_Check. If the generic body is a child of a generic package, then its elaboration establishes that each corresponding declaration nested in an instance of the parent, see 10.1.1, can from then on be instantiated without failing the Elaboration_Check.

    NOTES

  3. (4) The syntax of generic subprograms implies that a generic subprogram body is always the completion of a declaration.

    Examples
  4. Example of a generic procedure body: 
  5. procedure Exchange(U, V : in out Elem) is  --  see 12.1
   T : Elem;  --  the generic formal type
begin
   T := U;
   U := V;
   V := T;
end Exchange;
  6. Example of a generic function body: 
  7. function Squaring(X : Item) return Item is  --  see 12.1
begin
   return X*X;  --  the formal operator "*"
end Squaring;
  8. Example of a generic package body: 
  9. package body On_Vectors is  --  see 12.1

  10.    function Sum(A, B : Vector) return Vector is
      Result : Vector(A'Range); --  the formal type Vector
      Bias   : constant Integer := B'First - A'First;
   begin
      if A'Length /= B'Length then
         raise Length_Error;
      end if;

  11.       for N in A'Range loop
         Result(N) := Sum(A(N), B(N + Bias));
         --  the formal function Sum
      end loop;
      return Result;
   end Sum;

  12.    function Sigma(A : Vector) return Item is
      Total : Item := A(A'First); --  the formal type Item
   begin
      for N in A'First + 1 .. A'Last loop
         Total := Sum(Total, A(N)); --  the formal function Sum
      end loop;
      return Total;
   end Sigma;
end On_Vectors;

Node:12.3, Next:, Previous:12.2, Up:12

Generic Instantiation

  1. An instance of a generic unit is declared by a generic_instantiation.

    Syntax
  2. generic_instantiation ::=
     package defining_program_unit_name is
       new generic_package_name [generic_actual_part];
   | procedure defining_program_unit_name is
       new generic_procedure_name [generic_actual_part];
   | function defining_designator is
       new generic_function_name [generic_actual_part];

  3. generic_actual_part ::=
   (generic_association {, generic_association})

  4. generic_association ::=
   [generic_formal_parameter_selector_name =>]
      explicit_generic_actual_parameter

  5. explicit_generic_actual_parameter ::= expression | variable_name
   | subprogram_name | entry_name | subtype_mark
   | package_instance_name
    1. A generic_association is named or positional according to whether or not the generic_formal_parameter_selector_name is specified. Any positional associations shall precede any named associations.
  1. The generic actual parameter is either the explicit_generic_actual_parameter given in a generic_parameter_association for each formal, or the corresponding default_expression or default_name if no generic_parameter_association is given for the formal. When the meaning is clear from context, the term "generic actual," or simply "actual," is used as a synonym for "generic actual parameter" and also for the view denoted by one, or the value of one.

    Legality Rules
  2. In a generic_instantiation for a particular kind of program unit (package, procedure, or function), the name shall denote a generic unit of the corresponding kind (generic package, generic procedure, or generic function, respectively).
  3. The generic_formal_parameter_selector_name of a generic_association shall denote a generic_formal_parameter_declaration of the generic unit being instantiated. If two or more formal subprograms have the same defining name, then named associations are not allowed for the corresponding actuals.
  4. A generic_instantiation shall contain at most one generic_association for each formal. Each formal without an association shall have a default_expression or subprogram_default.
  5. In a generic unit Legality Rules are enforced at compile time of the generic_declaration and generic body, given the properties of the formals. In the visible part and formal part of an instance, Legality Rules are enforced at compile time of the generic_instantiation, given the properties of the actuals. In other parts of an instance, Legality Rules are not enforced; this rule does not apply when a given rule explicitly specifies otherwise.

    Static Semantics
  6. A generic_instantiation declares an instance; it is equivalent to the instance declaration (a package_declaration or subprogram_declaration) immediately followed by the instance body, both at the place of the instantiation.
  7. The instance is a copy of the text of the template. Each use of a formal parameter becomes (in the copy) a use of the actual, as explained below. An instance of a generic package is a package, that of a generic procedure is a procedure, and that of a generic function is a function.
  8. The interpretation of each construct within a generic declaration or body is determined using the overloading rules when that generic declaration or body is compiled. In an instance, the interpretation of each (copied) construct is the same, except in the case of a name that denotes the generic_declaration or some declaration within the generic unit; the corresponding name in the instance then denotes the corresponding copy of the denoted declaration. The overloading rules do not apply in the instance.
  9. In an instance, a generic_formal_parameter_declaration declares a view whose properties are identical to those of the actual, except as specified in "Formal Objects", and "Formal Subprograms". Similarly, for a declaration within a generic_formal_parameter_declaration, the corresponding declaration in an instance declares a view whose properties are identical to the corresponding declaration within the declaration of the actual.
  10. Implicit declarations are also copied, and a name that denotes an implicit declaration in the generic denotes the corresponding copy in the instance. However, for a type declared within the visible part of the generic, a whole new set of primitive subprograms is implicitly declared for use outside the instance, and may differ from the copied set if the properties of the type in some way depend on the properties of some actual type specified in the instantiation. For example, if the type in the generic is derived from a formal private type, then in the instance the type will inherit subprograms from the corresponding actual type.
  11. These new implicit declarations occur immediately after the type declaration in the instance, and override the copied ones. The copied ones can be called only from within the instance; the new ones can be called only from outside the instance, although for tagged types, the body of a new one can be executed by a call to an old one.
  12. In the visible part of an instance, an explicit declaration overrides an implicit declaration if they are homographs, as described in 8.3. On the other hand, an explicit declaration in the private part of an instance overrides an implicit declaration in the instance, only if the corresponding explicit declaration in the generic overrides a corresponding implicit declaration in the generic. Corresponding rules apply to the other kinds of overriding described in 8.3.

    Post-Compilation Rules
  13. Recursive generic instantiation is not allowed in the following sense: if a given generic unit includes an instantiation of a second generic unit, then the instance generated by this instantiation shall not include an instance of the first generic unit (whether this instance is generated directly, or indirectly by intermediate instantiations).

    Dynamic Semantics
  14. For the elaboration of a generic_instantiation, each generic_association is first evaluated. If a default is used, an implicit generic_association is assumed for this rule. These evaluations are done in an arbitrary order, except that the evaluation for a default actual takes place after the evaluation for another actual if the default includes a name that denotes the other one. Finally, the instance declaration and body are elaborated.
  15. For the evaluation of a generic_association the generic actual parameter is evaluated. Additional actions are performed in the case of a formal object of mode in, see 12.4.

    NOTES

  16. (5) If a formal type is not tagged, then the type is treated as an untagged type within the generic body. Deriving from such a type in a generic body is permitted; the new type does not get a new tag value, even if the actual is tagged. Overriding operations for such a derived type cannot be dispatched to from outside the instance.

    Examples
  17. Examples of generic instantiations, see 12.1 
  18. procedure Swap is new Exchange(Elem => Integer);
procedure Swap is new Exchange(Character);
--  Swap is overloaded
function Square is new Squaring(Integer);
--  "*" of Integer used by default
function Square is new Squaring
  (Item => Matrix, "*" => Matrix_Product);
function Square is new Squaring
  (Matrix, Matrix_Product); -- same as previous

  19. package Int_Vectors is new On_Vectors(Integer, Table, "+");
  20. Examples of uses of instantiated units: 
  21. Swap(A, B);
A := Square(A);

  22. T : Table(1 .. 5) := (10, 20, 30, 40, 50);
N : Integer := Int_Vectors.Sigma(T);
--  150 (see ``Generic Bodies'', for the body of Sigma)

  23. use Int_Vectors;
M : Integer := Sigma(T);  --  150

Node:12.4, Next:, Previous:12.3, Up:12

Formal Objects

  1. A generic formal object can be used to pass a value or variable to a generic unit.

    Syntax
  2. formal_object_declaration ::=
   defining_identifier_list : mode subtype_mark
     [:= default_expression];

    Name Resolution Rules
  3. The expected type for the default_expression, if any, of a formal object is the type of the formal object.
  4. For a generic formal object of mode in, the expected type for the actual is the type of the formal.
  5. For a generic formal object of mode in out, the type of the actual shall resolve to the type of the formal.

    Legality Rules
  6. If a generic formal object has a default_expression, then the mode shall be in (either explicitly or by default); otherwise, its mode shall be either in or in out.
  7. For a generic formal object of mode in, the actual shall be an expression. For a generic formal object of mode in out, the actual shall be a name that denotes a variable for which renaming is allowed (see 8.5.1).
  8. The type of a generic formal object of mode in shall be nonlimited.

    Static Semantics
  9. A formal_object_declaration declares a generic formal object. The default mode is in. For a formal object of mode in, the nominal subtype is the one denoted by the subtype_mark in the declaration of the formal. For a formal object of mode in out, its type is determined by the subtype_mark in the declaration; its nominal subtype is nonstatic, even if the subtype_mark denotes a static subtype.
  10. In an instance, a formal_object_declaration of mode in declares a new stand-alone constant object whose initialization expression is the actual, whereas a formal_object_declaration of mode in out declares a view whose properties are identical to those of the actual.

    Dynamic Semantics
  11. For the evaluation of a generic_association for a formal object of mode in, a constant object is created, the value of the actual parameter is converted to the nominal subtype of the formal object, and assigned to the object, including any value adjustment - see 7.6.

    NOTES

  12. (6) The constraints that apply to a generic formal object of mode in out are those of the corresponding generic actual parameter (not those implied by the subtype_mark that appears in the formal_object_declaration). Therefore, to avoid confusion, it is recommended that the name of a first subtype be used for the declaration of such a formal object.

Node:12.5, Next:, Previous:12.4, Up:12

Formal Types

  1. A generic formal subtype can be used to pass to a generic unit a subtype whose type is in a certain class of types.

    Syntax
  2. formal_type_declaration ::=
   type defining_identifier[discriminant_part] is
     formal_type_definition;

  3. formal_type_definition ::=
     formal_private_type_definition
   | formal_derived_type_definition
   | formal_discrete_type_definition
   | formal_signed_integer_type_definition
   | formal_modular_type_definition
   | formal_floating_point_definition
   | formal_ordinary_fixed_point_definition
   | formal_decimal_fixed_point_definition
   | formal_array_type_definition
   | formal_access_type_definition

    Legality Rules
  4. For a generic formal subtype, the actual shall be a subtype_mark; it denotes the (generic) actual subtype.

    Static Semantics
  5. A formal_type_declaration declares a (generic) formal type, and its first subtype, the (generic) formal subtype.
  6. The form of a formal_type_definition determines a class to which the formal type belongs. For a formal_private_type_definition the reserved words tagged and limited indicate the class, see 12.5.1. For a formal_derived_type_definition the class is the derivation class rooted at the ancestor type. For other formal types, the name of the syntactic category indicates the class; a formal_discrete_type_definition defines a discrete type, and so on.

    Legality Rules
  7. The actual type shall be in the class determined for the formal.

    Static Semantics
  8. The formal type also belongs to each class that contains the determined class. The primitive subprograms of the type are as for any type in the determined class. For a formal type other than a formal derived type, these are the predefined operators of the type; they are implicitly declared immediately after the declaration of the formal type. In an instance, the copy of such an implicit declaration declares a view of the predefined operator of the actual type, even if this operator has been overridden for the actual type. The rules specific to formal derived types are given in 12.5.1.

    NOTES

  9. (7) Generic formal types, like all types, are not named. Instead, a name can denote a generic formal subtype. Within a generic unit, a generic formal type is considered as being distinct from all other (formal or nonformal) types.
  10. (8) A discriminant_part is allowed only for certain kinds of types, and therefore only for certain kinds of generic formal types (see 3.7).

    Examples
  11. Examples of generic formal types: 
  12. type Item is private;
type Buffer(Length : Natural) is limited private;

  13. type Enum  is (<>);
type Int   is range <>;
type Angle is delta <>;
type Mass  is digits <>;

  14. type Table is array (Enum) of Item;
  15. Example of a generic formal part declaring a formal integer type: 
  16. generic
   type Rank is range <>;
   First  : Rank := Rank'First;
   Second : Rank := First + 1;
   --  the operator "+" of the type Rank

Node:12.5.1, Next:, Previous:12.5, Up:12.5

Formal Private and Derived Types

  1. The class determined for a formal private type can be either limited or nonlimited, and either tagged or untagged; no more specific class is known for such a type. The class determined for a formal derived type is the derivation class rooted at the ancestor type.

    Syntax
  2. formal_private_type_definition ::=
   [[abstract] tagged] [limited] private

  3. formal_derived_type_definition ::=
   [abstract] new subtype_mark [with private]

    Legality Rules
  4. If a generic formal type declaration has a known_discriminant_part, then it shall not include a default_expression for a discriminant.
  5. The ancestor subtype of a formal derived type is the subtype denoted by the subtype_mark of the formal_derived_type_definition. For a formal derived type declaration, the reserved words with private shall appear if and only if the ancestor type is a tagged type; in this case the formal derived type is a private extension of the ancestor type and the ancestor shall not be a class-wide type. Similarly, the optional reserved word abstract shall appear only if the ancestor type is a tagged type.
  6. If the formal subtype is definite, then the actual subtype shall also be definite.
  7. For a generic formal derived type with no discriminant_part:
    1. If the ancestor subtype is constrained, the actual subtype shall be constrained, and shall be statically compatible with the ancestor;
    2. If the ancestor subtype is an unconstrained access or composite subtype, the actual subtype shall be unconstrained.
    3. If the ancestor subtype is an unconstrained discriminated subtype, then the actual shall have the same number of discriminants, and each discriminant of the actual shall correspond to a discriminant of the ancestor, in the sense of 3.7.
  1. The declaration of a formal derived type shall not have a known_discriminant_part. For a generic formal private type with a known_discriminant_part:
    1. The actual type shall be a type with the same number of discriminants.
    2. The actual subtype shall be unconstrained.
    3. The subtype of each discriminant of the actual type shall statically match the subtype of the corresponding discriminant of the formal type.
  1. For a generic formal type with an unknown_discriminant_part, the actual may, but need not, have discriminants, and may be definite or indefinite.

    Static Semantics
  2. The class determined for a formal private type is as follows: 
  3. Type Definition         Determined Class

limited private         the class of all types
private                 the class of all nonlimited types
tagged limited private  the class of all tagged types
tagged private          the class of all nonlimited tagged types
  4. The presence of the reserved word abstract determines whether the actual type may be abstract.
  5. A formal private or derived type is a private or derived type, respectively. A formal derived tagged type is a private extension. A formal private or derived type is abstract if the reserved word abstract appears in its declaration.
  6. If the ancestor type is a composite type that is not an array type, the formal type inherits components from the ancestor type (including discriminants if a new discriminant_part is not specified), as for a derived type defined by a derived_type_definition, see 3.4.
  7. For a formal derived type, the predefined operators and inherited user-defined subprograms are determined by the ancestor type, and are implicitly declared at the earliest place, if any, within the immediate scope of the formal type, where the corresponding primitive subprogram of the ancestor is visible, see 7.3.1. In an instance, the copy of such an implicit declaration declares a view of the corresponding primitive subprogram of the ancestor, even if this primitive has been overridden for the actual type. In the case of a formal private extension, however, the tag of the formal type is that of the actual type, so if the tag in a call is statically determined to be that of the formal type, the body executed will be that corresponding to the actual type.
  8. For a prefix S that denotes a formal indefinite subtype, the following attribute is defined:
  9. S'Definite 
    S'Definite yields True if the actual subtype corresponding to
S is definite; otherwise it yields False. The value of this
attribute is of the predefined type Boolean.

    NOTES

  10. (9) In accordance with the general rule that the actual type shall belong to the class determined for the formal, see "Formal Types".:
    1. If the formal type is nonlimited, then so shall be the actual;
    2. For a formal derived type, the actual shall be in the class rooted at the ancestor subtype.
  1. (10) The actual type can be abstract only if the formal type is abstract (see 3.9.3).
  2. (11) If the formal has a discriminant_part, the actual can be either definite or indefinite. Otherwise, the actual has to be definite.

Node:12.5.2, Next:, Previous:12.5.1, Up:12.5

Formal Scalar Types

  1. A formal scalar type is one defined by any of the formal_type_definitions in this subclause. The class determined for a formal scalar type is discrete, signed integer, modular, floating point, ordinary fixed point, or decimal.

    Syntax
  2. formal_discrete_type_definition ::= (<>)

  3. formal_signed_integer_type_definition ::= range <>

  4. formal_modular_type_definition ::= mod <>

  5. formal_floating_point_definition ::= digits <>

  6. formal_ordinary_fixed_point_definition ::= delta <>

  7. formal_decimal_fixed_point_definition ::= delta <> digits <>

    Legality Rules
  8. The actual type for a formal scalar type shall not be a nonstandard numeric type.

    NOTES

  9. (12) The actual type shall be in the class of types implied by the syntactic category of the formal type definition, see "Formal Types". For example, the actual for a formal_modular_type_definition shall be a modular type.

Node:12.5.3, Next:, Previous:12.5.2, Up:12.5

Formal Array Types

  1. The class determined for a formal array type is the class of all array types.

    Syntax
  2. formal_array_type_definition ::= array_type_definition

    Legality Rules
  3. The only form of discrete_subtype_definition that is allowed within the declaration of a generic formal (constrained) array subtype is a subtype_mark.
  4. For a formal array subtype, the actual subtype shall satisfy the following conditions:
    1. The formal array type and the actual array type shall have the same dimensionality; the formal subtype and the actual subtype shall be either both constrained or both unconstrained.
    2. For each index position, the index types shall be the same, and the index subtypes (if unconstrained), or the index ranges (if constrained), shall statically match, see 4.9.1.
    3. The component subtypes of the formal and actual array types shall statically match.
    4. If the formal type has aliased components, then so shall the actual.

Examples
  1. Example of formal array types: 
  2. --  given the generic package

  3. generic
   type Item   is private;
   type Index  is (<>);
   type Vector is array (Index range <>) of Item;
   type Table  is array (Index) of Item;
package P is
   ...
end P;

  4. --  and the types

  5. type Mix    is array (Color range <>) of Boolean;
type Option is array (Color) of Boolean;

  6. --  then Mix can match Vector and Option can match Table

  7. package R is new P(Item   => Boolean, Index => Color,
                   Vector => Mix,     Table => Option);

  8. --  Note that Mix cannot match Table and Option cannot match Vector

Node:12.5.4, Next:, Previous:12.5.3, Up:12.5

Formal Access Types

  1. The class determined for a formal access type is the class of all access types.

    Syntax
  2. formal_access_type_definition ::= access_type_definition

    Legality Rules
  3. For a formal access-to-object type, the designated subtypes of the formal and actual types shall statically match.
  4. If and only if the general_access_modifier constant applies to the formal, the actual shall be an access-to-constant type. If the general_access_modifier all applies to the formal, then the actual shall be a general access-to-variable type, see 3.10.
  5. For a formal access-to-subprogram subtype, the designated profiles of the formal and the actual shall be mode-conformant, and the calling convention of the actual shall be protected if and only if that of the formal is protected.

    Examples
  6. Example of formal access types: 
  7. --  the formal types of the generic package

  8. generic
   type Node is private;
   type Link is access Node;
package P is
   ...
end P;

  9. --  can be matched by the actual types

  10. type Car;
type Car_Name is access Car;

  11. type Car is
   record
      Pred, Succ : Car_Name;
      Number     : License_Number;
      Owner      : Person;
   end record;

  12. --  in the following generic instantiation

  13. package R is new P(Node => Car, Link => Car_Name);

Node:12.6, Next:, Previous:12.5.4, Up:12

Formal Subprograms

  1. Formal subprograms can be used to pass callable entities to a generic unit.

    Syntax
  2. formal_subprogram_declaration ::=
   with subprogram_specification [is subprogram_default];

  3. subprogram_default ::= default_name | <>

  4. default_name ::= name

    Name Resolution Rules
  5. The expected profile for the default_name, if any, is that of the formal subprogram.
  6. For a generic formal subprogram, the expected profile for the actual is that of the formal subprogram.

    Legality Rules
  7. The profiles of the formal and any named default shall be mode-conformant.
  8. The profiles of the formal and actual shall be mode-conformant.

    Static Semantics
  9. A formal_subprogram_declaration declares a generic formal subprogram. The types of the formal parameters and result, if any, of the formal subprogram are those determined by the subtype_marks given in the formal_subprogram_declaration; however, independent of the particular subtypes that are denoted by the subtype_marks, the nominal subtypes of the formal parameters and result, if any, are defined to be nonstatic, and unconstrained if of an array type (no applicable index constraint is provided in a call on a formal subprogram). In an instance, a formal_subprogram_declaration declares a view of the actual. The profile of this view takes its subtypes and calling convention from the original profile of the actual entity, while taking the formal parameter names and default_expressions from the profile given in the formal_subprogram_declaration. The view is a function or procedure, never an entry.
  10. If a generic unit has a subprogram_default specified by a box, and the corresponding actual parameter is omitted, then it is equivalent to an explicit actual parameter that is a usage name identical to the defining name of the formal.

    NOTES

  11. (13) The matching rules for formal subprograms state requirements that are similar to those applying to subprogram_renaming_declarations (see 8.5.4). In particular, the name of a parameter of the formal subprogram need not be the same as that of the corresponding parameter of the actual subprogram; similarly, for these parameters, default_expressions need not correspond.
  12. (14) The constraints that apply to a parameter of a formal subprogram are those of the corresponding formal parameter of the matching actual subprogram (not those implied by the corresponding subtype_mark in the _specification of the formal subprogram). A similar remark applies to the result of a function. Therefore, to avoid confusion, it is recommended that the name of a first subtype be used in any declaration of a formal subprogram.
  13. (15) The subtype specified for a formal parameter of a generic formal subprogram can be any visible subtype, including a generic formal subtype of the same generic_formal_part.
  14. (16) A formal subprogram is matched by an attribute of a type if the attribute is a function with a matching specification. An enumeration literal of a given type matches a parameterless formal function whose result type is the given type.
  15. (17) A default_name denotes an entity that is visible or directly visible at the place of the generic_declaration; a box used as a default is equivalent to a name that denotes an entity that is directly visible at the place of the _instantiation.
  16. (18) The actual subprogram cannot be abstract, see 3.9.3.

    Examples
  17. Examples of generic formal subprograms: 
  18. with function "+"(X, Y : Item) return Item is <>;
with function Image(X : Enum) return String is Enum'Image;
with procedure Update is Default_Update;

  19. --  given the generic procedure declaration

  20. generic
   with procedure Action (X : in Item);
procedure Iterate(Seq : in Item_Sequence);

  21. --  and the procedure

  22. procedure Put_Item(X : in Item);

  23. --  the following instantiation is possible

  24. procedure Put_List is new Iterate(Action => Put_Item);

Node:12.7, Next:, Previous:12.6, Up:12

Formal Packages

  1. Formal packages can be used to pass packages to a generic unit. The formal_package_declaration declares that the formal package is an instance of a given generic package. Upon instantiation, the actual package has to be an instance of that generic package.

    Syntax
  2. formal_package_declaration ::=
   with package defining_identifier is new
     generic_package_name formal_package_actual_part;

  3. formal_package_actual_part ::= (<>) | [generic_actual_part]

    Legality Rules
  4. The generic_package_name shall denote a generic package (the template for the formal package); the formal package is an instance of the template.
  5. The actual shall be an instance of the template. If the formal_package_actual_part is (<>), then the actual may be any instance of the template; otherwise, each actual parameter of the actual instance shall match the corresponding actual parameter of the formal package (whether the actual parameter is given explicitly or by default), as follows:
    1. For a formal object of mode in the actuals match if they are static expressions with the same value, or if they statically denote the same constant, or if they are both the literal null.
    2. For a formal subtype, the actuals match if they denote statically matching subtypes.
    3. For other kinds of formals, the actuals match if they statically denote the same entity.

Static Semantics
  1. A formal_package_declaration declares a generic formal package.
  2. The visible part of a formal package includes the first list of basic_declarative_items of the package_specification. In addition, if the formal_package_actual_part is (<>), it also includes the generic_formal_part of the template for the formal package.

Node:12.8, Next:, Previous:12.7, Up:12

Example of a Generic Package

  1. The following example provides a possible formulation of stacks by means of a generic package. The size of each stack and the type of the stack elements are provided as generic formal parameters.

    Examples
  1. generic
   Size : Positive;
   type Item is private;
package Stack is
   procedure Push(E : in  Item);
   procedure Pop (E : out Item);
   Overflow, Underflow : exception;
end Stack;

  2. package body Stack is

  3.    type Table is array (Positive range <>) of Item;
   Space : Table(1 .. Size);
   Index : Natural := 0;

  4.    procedure Push(E : in Item) is
   begin
      if Index >= Size then
         raise Overflow;
      end if;
      Index := Index + 1;
      Space(Index) := E;
   end Push;

  5.    procedure Pop(E : out Item) is
   begin
      if Index = 0 then
         raise Underflow;
      end if;
      E := Space(Index);
      Index := Index - 1;
   end Pop;

  6. end Stack;
  7. Instances of this generic package can be obtained as follows: 
  8. package Stack_Int  is new Stack(Size => 200, Item => Integer);
package Stack_Bool is new Stack(100, Boolean);
  9. Thereafter, the procedures of the instantiated packages can be called as follows: 
  10. Stack_Int.Push(N);
Stack_Bool.Push(True);
  11. Alternatively, a generic formulation of the type Stack can be given as follows (package body omitted): 
  12. generic
   type Item is private;
package On_Stacks is
   type Stack(Size : Positive) is limited private;
   procedure Push(S : in out Stack; E : in  Item);
   procedure Pop (S : in out Stack; E : out Item);
   Overflow, Underflow : exception;
private
   type Table is array (Positive range <>) of Item;
   type Stack(Size : Positive) is
      record
         Space : Table(1 .. Size);
         Index : Natural := 0;
      end record;
end On_Stacks;
  13. In order to use such a package, an instance has to be created and thereafter stacks of the corresponding type can be declared: 
  14. declare
   package Stack_Real is new On_Stacks(Real); use Stack_Real;
   S : Stack(100);
begin
   ...
   Push(S, 2.54);
   ...
end;

Node:13, Next:, Previous:12.8, Up:Top

Representation Issues

  1. This section describes features for querying and controlling aspects of representation and for interfacing to hardware.

Node:13.1, Next:, Previous:13, Up:13

Representation Items

  1. There are three kinds of representation items: representation_clauses, component_clauses, and representation pragmas. Representation items specify how the types and other entities of the language are to be mapped onto the underlying machine. They can be provided to give more efficient representation or to interface with features that are outside the domain of the language (for example, peripheral hardware). Representation items also specify other specifiable properties of entities. A representation item applies to an entity identified by a local_name, which denotes an entity declared local to the current declarative region, or a library unit declared immediately preceding a representation pragma in a compilation.

    Syntax
  2. representation_clause ::=
     attribute_definition_clause
   | enumeration_representation_clause
   | record_representation_clause
   | at_clause

  3. local_name ::=
     direct_name
   | direct_name'attribute_designator
   | library_unit_name
    1. A representation pragma is allowed only at places where a representation_clause or compilation_unit is allowed.

Name Resolution Rules
  1. In a representation item, if the local_name is a direct_name, then it shall resolve to denote a declaration (or, in the case of a pragma, one or more declarations) that occurs immediately within the same declarative_region as the representation item. If the local_name has an attribute_designator, then it shall resolve to denote an implementation-defined component, see 13.5.1, or a class-wide type implicitly declared immediately within the same declarative_region as the representation item. A local_name that is a library_unit_name (only permitted in a representation pragma) shall resolve to denote the library_item that immediately precedes (except for other pragmas) the representation pragma.

    Legality Rules
  2. The local_name of a representation_clause or representation pragma shall statically denote an entity (or, in the case of a pragma, one or more entities) declared immediately preceding it in a compilation, or within the same declarative_part, package_specification, task_definition, protected_definition, or record_definition as the representation item. If a local_name denotes a local callable entity, it may do so through a local subprogram_renaming_declaration (as a way to resolve ambiguity in the presence of overloading); otherwise, the local_name shall not denote a renaming_declaration.
  3. The representation of an object consists of a certain number of bits (the size of the object). These are the bits that are normally read or updated by the machine code when loading, storing, or operating-on the value of the object. This includes some padding bits, when the size of the object is greater than the size of its subtype. Such padding bits are considered to be part of the representation of the object, rather than being gaps between objects, if these bits are normally read and updated.
  4. A representation item directly specifies an aspect of representation of the entity denoted by the local_name, except in the case of a type-related representation item, whose local_name shall denote a first subtype, and which directly specifies an aspect of the subtype's type. A representation item that names a subtype is either subtype-specific (Size and Alignment clauses) or type-related (all others). Subtype-specific aspects may differ for different subtypes of the same type.
  5. A representation item that directly specifies an aspect of a subtype or type shall appear after the type is completely defined, see 3.11.1, and before the subtype or type is frozen, see 13.14. If a representation item is given that directly specifies an aspect of an entity, then it is illegal to give another representation item that directly specifies the same aspect of the entity.
  6. For an untagged derived type, no type-related representation items are allowed if the parent type is a by-reference type, or has any user-defined primitive subprograms.
  7. Representation aspects of a generic formal parameter are the same as those of the actual. A type-related representation item is not allowed for a descendant of a generic formal untagged type.
  8. A representation item that specifies the Size for a given subtype, or the size or storage place for an object (including a component) of a given subtype, shall allow for enough storage space to accommodate any value of the subtype.
  9. A representation item that is not supported by the implementation is illegal, or raises an exception at run time.

    Static Semantics
  10. If two subtypes statically match, then their subtype-specific aspects (Size and Alignment) are the same.
  11. A derived type inherits each type-related aspect of its parent type that was directly specified before the declaration of the derived type, or (in the case where the parent is derived) that was inherited by the parent type from the grandparent type. A derived subtype inherits each subtype-specific aspect of its parent subtype that was directly specified before the declaration of the derived type, or (in the case where the parent is derived) that was inherited by the parent subtype from the grandparent subtype, but only if the parent subtype statically matches the first subtype of the parent type. An inherited aspect of representation is overridden by a subsequent representation item that specifies the same aspect of the type or subtype.
  12. Each aspect of representation of an entity is as follows:
    1. If the aspect is specified for the entity, meaning that it is either directly specified or inherited, then that aspect of the entity is as specified, except in the case of Storage_Size, which specifies a minimum.
    2. If an aspect of representation of an entity is not specified, it is chosen by default in an unspecified manner.

Dynamic Semantics
  1. For the elaboration of a representation_clause, any evaluable constructs within it are evaluated.

    Implementation Permissions
  2. An implementation may interpret aspects of representation in an implementation-defined manner. An implementation may place implementation-defined restrictions on representation items. A recommended level of support is specified for representation items and related features in each subclause. These recommendations are changed to requirements for implementations that support the Systems Programming Annex, see "Required Representation Support".

    Implementation Advice
  3. The recommended level of support for all representation items is qualified as follows:
    1. An implementation need not support representation items containing nonstatic expressions, except that an implementation should support a representation item for a given entity if each nonstatic expression in the representation item is a name that statically denotes a constant declared before the entity.
    2. An implementation need not support a specification for the Size for a given composite subtype, nor the size or storage place for an object (including a component) of a given composite subtype, unless the constraints on the subtype and its composite subcomponents (if any) are all static constraints.
    3. An aliased component, or a component whose type is by-reference, should always be allocated at an addressable location.

Node:13.2, Next:, Previous:13.1, Up:13

Pragma Pack

  1. A pragma Pack specifies that storage minimization should be the main criterion when selecting the representation of a composite type.

    Syntax
  2. The form of a pragma Pack is as follows: 
  3. pragma Pack(first_subtype_local_name);

    Legality Rules
  4. The first_subtype_local_name of a pragma Pack shall denote a composite subtype.

    Static Semantics
  5. A pragma Pack specifies the packing aspect of representation; the type (or the extension part) is said to be packed. For a type extension, the parent part is packed as for the parent type, and a pragma Pack causes packing only of the extension part.

    Implementation Advice
  6. If a type is packed, then the implementation should try to minimize storage allocated to objects of the type, possibly at the expense of speed of accessing components, subject to reasonable complexity in addressing calculations.
  7. The recommended level of support for pragma Pack is:
    1. For a packed record type, the components should be packed as tightly as possible subject to the Sizes of the component subtypes, and subject to any record_representation_clause that applies to the type; the implementation may, but need not, reorder components or cross aligned word boundaries to improve the packing. A component whose Size is greater than the word size may be allocated an integral number of words.
    2. For a packed array type, if the component subtype's Size is less than or equal to the word size, and Component_Size is not specified for the type, Component_Size should be less than or equal to the Size of the component subtype, rounded up to the nearest factor of the word size.

Node:13.3, Next:, Previous:13.2, Up:13

Representation Attributes

  1. The values of certain implementation-dependent characteristics can be obtained by interrogating appropriate representation attributes. Some of these attributes are specifiable via an attribute_definition_clause.

    Syntax
  2. attribute_definition_clause ::=
     for local_name'attribute_designator use expression;
   | for local_name'attribute_designator use name;

    Name Resolution Rules
  3. For an attribute_definition_clause that specifies an attribute that denotes a value, the form with an expression shall be used. Otherwise, the form with a name shall be used.
  4. For an attribute_definition_clause that specifies an attribute that denotes a value or an object, the expected type for the expression or name is that of the attribute. For an attribute_definition_clause that specifies an attribute that denotes a subprogram, the expected profile for the name is the profile required for the attribute. For an attribute_definition_clause that specifies an attribute that denotes some other kind of entity, the name shall resolve to denote an entity of the appropriate kind.

    Legality Rules
  5. An attribute_designator is allowed in an attribute_definition_clause only if this International Standard explicitly allows it, or for an implementation-defined attribute if the implementation allows it. Each specifiable attribute constitutes an aspect of representation.
  6. For an attribute_definition_clause that specifies an attribute that denotes a subprogram, the profile shall be mode conformant with the one required for the attribute, and the convention shall be Ada. Additional requirements are defined for particular attributes.

    Static Semantics
  7. A Size clause is an attribute_definition_clause whose attribute_designator is Size. Similar definitions apply to the other specifiable attributes.
  8. A storage element is an addressable element of storage in the machine. A word is the largest amount of storage that can be conveniently and efficiently manipulated by the hardware, given the implementation's run-time model. A word consists of an integral number of storage elements.
  9. The following attributes are defined:
  10. For a prefix X that denotes an object, program unit, or label:
  11. X'Address 
    Denotes the address of the first of the storage elements
allocated to X. For a program unit or label, this value
refers to the machine code associated with the corresponding
body or statement. The value of this attribute is of type
System.Address.

  12. Address may be specified for stand-alone objects and for
program units via an attribute_definition_clause.

    Erroneous Execution
  13. If an Address is specified, it is the programmer's responsibility to ensure that the address is valid; otherwise, program execution is erroneous.

    Implementation Advice
  14. For an array X, X'Address should point at the first component of the array, and not at the array bounds.
  15. The recommended level of support for the Address attribute is:
    1. X'Address should produce a useful result if X is an object that is aliased or of a by-reference type, or is an entity whose Address has been specified.
    2. An implementation should support Address clauses for imported subprograms.
    3. Objects (including subcomponents) that are aliased or of a by-reference type should be allocated on storage element boundaries.
    4. If the Address of an object is specified, or it is imported or exported, then the implementation should not perform optimizations based on assumptions of no aliases.

    NOTES

  1. (1) The specification of a link name in a pragma Export, see B.1 for a subprogram or object is an alternative to explicit specification of its link-time address, allowing a link-time directive to place the subprogram or object within memory.
  2. (2) The rules for the Size attribute imply, for an aliased object X, that if X'Size = Storage_Unit, then X'Address points at a storage element containing all of the bits of X, and only the bits of X.

    Static Semantics
  3. For a prefix X that denotes a subtype or object:
  4. X'Alignment 
    The Address of an object that is allocated under control of
the implementation is an integral multiple of the Alignment
of the object (that is, the Address modulo the Alignment is
zero). The offset of a record component is a multiple of the
Alignment of the component. For an object that is not
allocated under control of the implementation (that is, one
that is imported, that is allocated by a user-defined
allocator, whose Address has been specified, or is designated
by an access value returned by an instance of
Unchecked_Conversion), the implementation may assume that the
Address is an integral multiple of its Alignment. The
implementation shall not assume a stricter alignment.

  5. The value of this attribute is of type
universal_integer, and nonnegative; zero means that the
object is not necessarily aligned on a storage element
boundary.

  6. Alignment may be specified for first subtypes and
stand-alone objects via an attribute_definition_clause; the
expression of such a clause shall be static, and its value
nonnegative. If the Alignment of a subtype is specified,
then the Alignment of an object of the subtype is at least as
strict, unless the object's Alignment is also specified. The
Alignment of an object created by an allocator is that of the
designated subtype.

  7. If an Alignment is specified for a composite subtype or
object, this Alignment shall be equal to the least common
multiple of any specified Alignments of the subcomponent
subtypes, or an integer multiple thereof.

    Erroneous Execution
  8. Program execution is erroneous if an Address clause is given that conflicts with the Alignment.
  9. If the Alignment is specified for an object that is not allocated under control of the implementation, execution is erroneous if the object is not aligned according to the Alignment.

    Implementation Advice
  10. The recommended level of support for the Alignment attribute for subtypes is:
    1. An implementation should support specified Alignments that are factors and multiples of the number of storage elements per word, subject to the following:
    2. An implementation need not support specified Alignments for combinations of Sizes and Alignments that cannot be easily loaded and stored by available machine instructions.
    3. An implementation need not support specified Alignments that are greater than the maximum Alignment the implementation ever returns by default.
  1. The recommended level of support for the Alignment attribute for objects is:
    1. Same as above, for subtypes, but in addition:
    2. For stand-alone library-level objects of statically constrained subtypes, the implementation should support all Alignments supported by the target linker. For example, page alignment is likely to be supported for such objects, but not for subtypes.

    NOTES

  1. (3) Alignment is a subtype-specific attribute.
  2. (4) The Alignment of a composite object is always equal to the least common multiple of the Alignments of its components, or a multiple thereof.
  3. (5) A component_clause, Component_Size clause, or a pragma Pack can override a specified Alignment.

    Static Semantics
  4. For a prefix X that denotes an object:
  5. X'Size 
    Denotes the size in bits of the representation of the object.
The value of this attribute is of the type universal_integer.
    1. Size may be specified for stand-alone objects via an attribute_definition_clause; the expression of such a clause shall be static and its value nonnegative.

Implementation Advice
  1. The recommended level of support for the Size attribute of objects is:
    1. A Size clause should be supported for an object if the specified Size is at least as large as its subtype's Size, and corresponds to a size in storage elements that is a multiple of the object's Alignment (if the Alignment is nonzero).

Static Semantics
  1. For every subtype S:
  2. S'Size 
    If S is definite, denotes the size (in bits) that the
implementation would choose for the following objects of
subtype S:
    1. A record component of subtype S when the record type is packed.
    2. The formal parameter of an instance of Unchecked_Conversion that converts from subtype S to some other subtype.
    3. If S is indefinite, the meaning is implementation defined. The value of this attribute is of the type universal_integer. The Size of an object is at least as large as that of its subtype, unless the object's Size is determined by a Size clause, a component_clause, or a Component_Size clause. Size may be specified for first subtypes via an attribute_definition_clause; the expression of such a clause shall be static and its value nonnegative.

Implementation Requirements
  1. In an implementation, Boolean'Size shall be 1.

    Implementation Advice
  2. If the Size of a subtype is specified, and allows for efficient independent addressability, see 9.10, on the target architecture, then the Size of the following objects of the subtype should equal the Size of the subtype:
    1. Aliased objects (including components).
    2. Unaliased components, unless the Size of the component is determined by a component_clause or Component_Size clause.
  1. A Size clause on a composite subtype should not affect the internal layout of components.
  2. The recommended level of support for the Size attribute of subtypes is:
    1. The Size (if not specified) of a static discrete or fixed point subtype should be the number of bits needed to represent each value belonging to the subtype using an unbiased representation, leaving space for a sign bit only if the subtype contains negative values. If such a subtype is a first subtype, then an implementation should support a specified Size for it that reflects this representation.
    2. For a subtype implemented with levels of indirection, the Size should include the size of the pointers, but not the size of what they point at.

    NOTES

  1. (6) Size is a subtype-specific attribute.
  2. (7) A component_clause or Component_Size clause can override a specified Size. A pragma Pack cannot.

    Static Semantics
  3. For a prefix T that denotes a task object (after any implicit dereference):
  4. T'Storage_Size 
    Denotes the number of storage elements reserved for the task.
The value of this attribute is of the type universal_integer.
The Storage_Size includes the size of the task's stack, if
any. The language does not specify whether or not it
includes other storage associated with the task (such as the
``task control block'' used by some implementations.)  If a
pragma Storage_Size is given, the value of the Storage_Size
attribute is at least the value specified in the pragma.
  5. A pragma Storage_Size specifies the amount of storage to be reserved for the execution of a task.

    Syntax
  6. The form of a pragma Storage_Size is as follows: 
  7. pragma Storage_Size(expression);
    1. A pragma Storage_Size is allowed only immediately within a task_definition.

Name Resolution Rules
  1. The expression of a pragma Storage_Size is expected to be of any integer type.

    Dynamic Semantics
  2. A pragma Storage_Size is elaborated when an object of the type defined by the immediately enclosing task_definition is created. For the elaboration of a pragma Storage_Size, the expression is evaluated; the Storage_Size attribute of the newly created task object is at least the value of the expression.
  3. At the point of task object creation, or upon task activation, Storage_Error is raised if there is insufficient free storage to accommodate the requested Storage_Size. Static Semantics
  4. For a prefix X that denotes an array subtype or array object (after any implicit dereference):
  5. X'Component_Size 
    Denotes the size in bits of components of the type of X. The
value of this attribute is of type universal_integer.
    1. Component_Size may be specified for array types via an attribute_definition_clause; the expression of such a clause shall be static, and its value nonnegative.

Implementation Advice
  1. The recommended level of support for the Component_Size attribute is:
    1. An implementation need not support specified Component_Sizes that are less than the Size of the component subtype.
    2. An implementation should support specified Component_Sizes that are factors and multiples of the word size. For such Component_Sizes, the array should contain no gaps between components. For other Component_Sizes (if supported), the array should contain no gaps between components when packing is also specified; the implementation should forbid this combination in cases where it cannot support a no-gaps representation.

Static Semantics
  1. For every subtype S of a tagged type T (specific or class-wide), the following attribute is defined:
  2. S'External_Tag 
    S'External_Tag denotes an external string representation for
S'Tag; it is of the predefined type String. External_Tag may
be specified for a specific tagged type via an
attribute_definition_clause; the expression of such a
clause shall be static. The default external tag
representation is implementation defined. See 3.9.2, and
13.13.2.

    Implementation Requirements
  3. In an implementation, the default external tag for each specific tagged type declared in a partition shall be distinct, so long as the type is declared outside an instance of a generic body. If the compilation unit in which a given tagged type is declared, and all compilation units on which it semantically depends, are the same in two different partitions, then the external tag for the type shall be the same in the two partitions. What it means for a compilation unit to be the same in two different partitions is implementation defined. At a minimum, if the compilation unit is not recompiled between building the two different partitions that include it, the compilation unit is considered the same in the two partitions.

    NOTES

  4. (8) The following language-defined attributes are specifiable, at least for some of the kinds of entities to which they apply: Address, Size, Component_Size, Alignment, External_Tag, Small, Bit_Order, Storage_Pool, Storage_Size, Write, Output, Read, Input, and Machine_Radix.
  5. (9) It follows from the general rules in 13.1, that if one writes "for X'Size use Y;" then the X'Size attribute_reference will return Y (assuming the implementation allows the Size clause). The same is true for all of the specifiable attributes except Storage_Size.

    Examples
  6. Examples of attribute definition clauses: 
  7. Byte : constant := 8;
Page : constant := 2**12;

  8. type Medium is range 0 .. 65_000;
for Medium'Size use 2*Byte;
for Medium'Alignment use 2;
Device_Register : Medium;
for Device_Register'Size use Medium'Size;
for Device_Register'Address use
  System.Storage_Elements.To_Address(16#FFFF_0020#);

  9. type Short is delta 0.01 range -100.0 .. 100.0;
for Short'Size use 15;

  10. for Car_Name'Storage_Size use
-- specify access type's storage pool size
  2000*((Car'Size/System.Storage_Unit) +1);
  -- approximately 2000 cars

  11. function My_Read(Stream : access Ada.Streams.Root_Stream_Type'Class)
  return T;
for T'Read use My_Read;  --  see 13.13.2

    NOTES

  12. (10) Notes on the examples: In the Size clause for Short, fifteen bits is the minimum necessary, since the type definition requires Short'Small <= 2**(-7).

Node:13.4, Next:, Previous:13.3, Up:13

Enumeration Representation Clauses

  1. An enumeration_representation_clause specifies the internal codes for enumeration literals.

    Syntax
  2. enumeration_representation_clause ::=
   for first_subtype_local_name use enumeration_aggregate;

  3. enumeration_aggregate ::= array_aggregate

    Name Resolution Rules
  4. The enumeration_aggregate shall be written as a one-dimensional array_aggregate, for which the index subtype is the unconstrained subtype of the enumeration type, and each component expression is expected to be of any integer type.

    Legality Rules
  5. The first_subtype_local_name of an enumeration_representation_clause shall denote an enumeration subtype.
  6. The expressions given in the array_aggregate shall be static, and shall specify distinct integer codes for each value of the enumeration type; the associated integer codes shall satisfy the predefined ordering relation of the type.

    Static Semantics
  7. An enumeration_representation_clause specifies the coding aspect of representation. The coding consists of the internal code for each enumeration literal, that is, the integral value used internally to represent each literal.

    Implementation Requirements
  8. For nonboolean enumeration types, if the coding is not specified for the type, then for each value of the type, the internal code shall be equal to its position number.

    Implementation Advice
  9. The recommended level of support for enumeration_representation_clauses is:
    1. An implementation should support at least the internal codes in the range System.Min_Int..System.Max_Int. An implementation need not support enumeration_representation_clauses for boolean types.

    NOTES

  1. (11) Unchecked_Conversion may be used to query the internal codes used for an enumeration type. The attributes of the type, such as Succ, Pred, and Pos, are unaffected by the representation_clause. For example, Pos always returns the position number, not the internal integer code that might have been specified in a representation_clause.

    Examples
  2. Example of an enumeration representation clause: 
  3. type Mix_Code is (ADD, SUB, MUL, LDA, STA, STZ);

  4. for Mix_Code use
   (ADD => 1, SUB => 2, MUL => 3, LDA => 8, STA => 24, STZ =>33);

Node:13.5, Next:, Previous:13.4, Up:13

Record Layout

  1. The (record) layout aspect of representation consists of the storage places for some or all components, that is, storage place attributes of the components. The layout can be specified with a record_representation_clause.

Node:13.5.1, Next:, Previous:13.5, Up:13.5

Record Representation Clauses

  1. A record_representation_clause specifies the storage representation of records and record extensions, that is, the order, position, and size of components (including discriminants, if any).

    Syntax
  2. record_representation_clause ::=
   for first_subtype_local_name use
      record [mod_clause]
         {component_clause}
      end record;

  3. component_clause ::=
   component_local_name at position range first_bit .. last_bit;

  4. position ::= static_expression

  5. first_bit ::= static_simple_expression

  6. last_bit ::= static_simple_expression

    Name Resolution Rules
  7. Each position, first_bit, and last_bit is expected to be of any integer type.

    Legality Rules
  8. The first_subtype_local_name of a record_representation_clause shall denote a specific nonlimited record or record extension subtype.
  9. If the component_local_name is a direct_name, the local_name shall denote a component of the type. For a record extension, the component shall not be inherited, and shall not be a discriminant that corresponds to a discriminant of the parent type. If the component_local_name has an attribute_designator, the direct_name of the local_name shall denote either the declaration of the type or a component of the type, and the attribute_designator shall denote an implementation-defined implicit component of the type.
  10. The position, first_bit, and last_bit shall be static expressions. The value of position and first_bit shall be nonnegative. The value of last_bit shall be no less than first_bit - 1.
  11. At most one component_clause is allowed for each component of the type, including for each discriminant (component_clauses may be given for some, all, or none of the components). Storage places within a component_list shall not overlap, unless they are for components in distinct variants of the same variant_part.
  12. A name that denotes a component of a type is not allowed within a record_representation_clause for the type, except as the component_local_name of a component_clause.

    Static Semantics
  13. A record_representation_clause (without the mod_clause) specifies the layout. The storage place attributes, see 13.5.2, are taken from the values of the position, first_bit, and last_bit expressions after normalizing those values so that first_bit is less than Storage_Unit.
  14. A record_representation_clause for a record extension does not override the layout of the parent part; if the layout was specified for the parent type, it is inherited by the record extension.

    Implementation Permissions
  15. An implementation may generate implementation-defined components (for example, one containing the offset of another component). An implementation may generate names that denote such implementation-defined components; such names shall be implementation-defined attribute_references. An implementation may allow such implementation-defined names to be used in record_ representation_clauses. An implementation can restrict such component_clauses in any manner it sees fit.
  16. If a record_representation_clause is given for an untagged derived type, the storage place attributes for all of the components of the derived type may differ from those of the corresponding components of the parent type, even for components whose storage place is not specified explicitly in the record_representation_clause.

    Implementation Advice
  17. The recommended level of support for record_representation_clauses is:
    1. An implementation should support storage places that can be extracted with a load, mask, shift sequence of machine code, and set with a load, shift, mask, store sequence, given the available machine instructions and run-time model.
    2. A storage place should be supported if its size is equal to the Size of the component subtype, and it starts and ends on a boundary that obeys the Alignment of the component subtype.
    3. If the default bit ordering applies to the declaration of a given type, then for a component whose subtype's Size is less than the word size, any storage place that does not cross an aligned word boundary should be supported.
    4. An implementation may reserve a storage place for the tag field of a tagged type, and disallow other components from overlapping that place.
    5. An implementation need not support a component_clause for a component of an extension part if the storage place is not after the storage places of all components of the parent type, whether or not those storage places had been specified.

    NOTES

  1. (12) If no component_clause is given for a component, then the choice of the storage place for the component is left to the implementation. If component_clauses are given for all components, the record_representation_clause completely specifies the representation of the type and will be obeyed exactly by the implementation.

    Examples
  2. Example of specifying the layout of a record type: 
  3. Word : constant := 4;  --  storage element is byte, 4 bytes per word

  4. type State      is (A,M,W,P);
type Mode       is (Fix, Dec, Exp, Signif);

  5. type Byte_Mask  is array (0..7)  of Boolean;
type State_Mask is array (State) of Boolean;
type Mode_Mask  is array (Mode)  of Boolean;

  6. type Program_Status_Word is
  record
      System_Mask     : Byte_Mask;
      Protection_Key  : Integer range 0 .. 3;
      Machine_State   : State_Mask;
      Interrupt_Cause : Interruption_Code;
      Ilc             : Integer range 0 .. 3;
      Cc              : Integer range 0 .. 3;
      Program_Mask    : Mode_Mask;
      Inst_Address    : Address;
end record;

  7. for Program_Status_Word use
  record
      System_Mask     at 0*Word range 0  .. 7;
      Protection_Key  at 0*Word range 10 .. 11; -- bits 8,9 unused
      Machine_State   at 0*Word range 12 .. 15;
      Interrupt_Cause at 0*Word range 16 .. 31;
      Ilc             at 1*Word range 0  .. 1;  -- second word
      Cc              at 1*Word range 2  .. 3;
      Program_Mask    at 1*Word range 4  .. 7;
      Inst_Address    at 1*Word range 8  .. 31;
  end record;

  8. for Program_Status_Word'Size use 8*System.Storage_Unit;
for Program_Status_Word'Alignment use 8;

    NOTES

  9. (13) Note on the example: The record_representation_clause defines the record layout. The Size clause guarantees that (at least) eight storage elements are used for objects of the type. The Alignment clause guarantees that aliased, imported, or exported objects of the type will have addresses divisible by eight.

Node:13.5.2, Next:, Previous:13.5.1, Up:13.5

Storage Place Attributes


Static Semantics
  1. For a component C of a composite, non-array object R, the storage place attributes are defined:
  2. R.C'Position 
    Denotes the same value as R.C'Address - R'Address. The value
of this attribute is of the type universal_integer.
  3. R.C'First_Bit 
    Denotes the offset, from the start of the first of the
storage elements occupied by C, of the first bit occupied by
C. This offset is measured in bits. The first bit of a
storage element is numbered zero. The value of this
attribute is of the type universal_integer.
  4. R.C'Last_Bit 
    Denotes the offset, from the start of the first of the
storage elements occupied by C, of the last bit occupied by
C. This offset is measured in bits. The value of this
attribute is of the type universal_integer.

    Implementation Advice
  5. If a component is represented using some form of pointer (such as an offset) to the actual data of the component, and this data is contiguous with the rest of the object, then the storage place attributes should reflect the place of the actual data, not the pointer. If a component is allocated discontiguously from the rest of the object, then a warning should be generated upon reference to one of its storage place attributes.

Node:13.5.3, Next:, Previous:13.5.2, Up:13.5

Bit Ordering

  1. The Bit_Order attribute specifies the interpretation of the storage place attributes.

    Static Semantics
  2. A bit ordering is a method of interpreting the meaning of the storage place attributes. High_Order_First (known in the vernacular as "big endian") means that the first bit of a storage element (bit 0) is the most significant bit (interpreting the sequence of bits that represent a component as an unsigned integer value). Low_Order_First (known in the vernacular as "little endian") means the opposite: the first bit is the least significant.
  3. For every specific record subtype S, the following attribute is defined:
  4. S'Bit_Order 
    Denotes the bit ordering for the type of S. The value of this
attribute is of type System.Bit_Order. Bit_Order may be
specified for specific record types via an
attribute_definition_clause; the expression of such a
clause shall be static.
  5. If Word_Size = Storage_Unit, the default bit ordering is implementation defined. If Word_Size > Storage_Unit, the default bit ordering is the same as the ordering of storage elements in a word, when interpreted as an integer.
  6. The storage place attributes of a component of a type are interpreted according to the bit ordering of the type.

    Implementation Advice
  7. The recommended level of support for the nondefault bit ordering is:
    1. If Word_Size = Storage_Unit, then the implementation should support the nondefault bit ordering in addition to the default bit ordering.

Node:13.6, Next:, Previous:13.5.3, Up:13

Change of Representation

  1. A type_conversion, see 4.6 can be used to convert between two different representations of the same array or record. To convert an array from one representation to another, two array types need to be declared with matching component subtypes, and convertible index types. If one type has packing specified and the other does not, then explicit conversion can be used to pack or unpack an array.
  2. To convert a record from one representation to another, two record types with a common ancestor type need to be declared, with no inherited subprograms. Distinct representations can then be specified for the record types, and explicit conversion between the types can be used to effect a change in representation.

    Examples
  3. Example of change of representation: 
  4. -- Packed_Descriptor and Descriptor are two different types
-- with identical characteristics, apart from their
-- representation

  5. type Descriptor is
    record
      -- components of a descriptor
    end record;

  6. type Packed_Descriptor is new Descriptor;

  7. for Packed_Descriptor use
    record
      -- component clauses for some or for all components
    end record;

  8. --  Change of representation can now be accomplished
--  by explicit type conversions:

  9. D : Descriptor;
P : Packed_Descriptor;

  10. P := Packed_Descriptor(D);  -- pack D
D := Descriptor(P);         -- unpack P

Node:13.7, Next:, Previous:13.6, Up:13

The Package System

  1. For each implementation there is a library package called System which includes the definitions of certain configuration-dependent characteristics.

    Static Semantics
  2. The following language-defined library package exists: 
  3. package System is
   pragma Preelaborate(System);

  4.    type Name is implementation-defined-enumeration-type;
   System_Name : constant Name := implementation-defined;

  5.    -- System-Dependent Named Numbers:

  6.    Min_Int               : constant := root_integer'First;
   Max_Int               : constant := root_integer'Last;

  7.    Max_Binary_Modulus    : constant := implementation-defined;
   Max_Nonbinary_Modulus : constant := implementation-defined;

  8.    Max_Base_Digits       : constant := root_real'Digits;
   Max_Digits            : constant := implementation-defined;

  9.    Max_Mantissa          : constant := implementation-defined;
   Fine_Delta            : constant := implementation-defined;

  10.    Tick                  : constant := implementation-defined;

  11.    -- Storage-related Declarations:

  12.    type Address is implementation-defined;
   Null_Address : constant Address;

  13.    Storage_Unit : constant := implementation-defined;
   Word_Size    : constant := implementation-defined * Storage_Unit;
   Memory_Size  : constant := implementation-defined;

  14.    -- Address Comparison:
   function "<" (Left, Right : Address) return Boolean;
   function "<="(Left, Right : Address) return Boolean;
   function ">" (Left, Right : Address) return Boolean;
   function ">="(Left, Right : Address) return Boolean;
   function "=" (Left, Right : Address) return Boolean;
-- function "/=" (Left, Right : Address) return Boolean;
   -- "/=" is implicitly defined
   pragma Convention(Intrinsic, "<");
   ...
   -- and so on for all language-defined subprograms in this package

  15.    -- Other System-Dependent Declarations:
   type Bit_Order is (High_Order_First, Low_Order_First);
   Default_Bit_Order : constant Bit_Order;

  16.    -- Priority-related declarations, see D.1.:
   subtype Any_Priority is Integer
     range implementation-defined;
   subtype Priority is Any_Priority
     range Any_Priority'First .. implementation-defined;
   subtype Interrupt_Priority is Any_Priority
     range Priority'Last+1 .. Any_Priority'Last;

  17.    Default_Priority : constant Priority
     := (Priority'First + Priority'Last)/2;

  18. private
   ... -- not specified by the language
end System;
  19. Name is an enumeration subtype. Values of type Name are the names of alternative machine configurations handled by the implementation. System_Name represents the current machine configuration.
  20. The named numbers Fine_Delta and Tick are of the type universal_real; the others are of the type universal_integer.
  21. The meanings of the named numbers are:
  22. Min_Int 
    The smallest (most negative) value allowed for the
expressions of a signed_integer_type_definition.
  23. Max_Int 
    The largest (most positive) value allowed for the expressions
of a signed_integer_type_definition.
  24. Max_Binary_Modulus 
    A power of two such that it, and all lesser positive powers
of two, are allowed as the modulus of a
modular_type_definition.
  25. Max_Nonbinary_Modulus 
    A value such that it, and all lesser positive integers, are
allowed as the modulus of a modular_type_definition.
  26. Max_Base_Digits 
    The largest value allowed for the requested decimal precision
in a floating_point_definition.
  27. Max_Digits 
    The largest value allowed for the requested decimal precision
in a floating_point_definition that has no
real_range_specification. Max_Digits is less than or equal
to Max_Base_Digits.
  28. Max_Mantissa 
    The largest possible number of binary digits in the mantissa
of machine numbers of a user-defined ordinary fixed point
type. (The mantissa is defined in G.)
  29. Fine_Delta 
    The smallest delta allowed in an
ordinary_fixed_point_definition that has the
real_range_specification range -1.0 .. 1.0.
  30. Tick 
    A period in seconds approximating the real time interval
during which the value of Calendar.Clock remains constant.
  31. Storage_Unit 
    The number of bits per storage element.
  32. Word_Size 
    The number of bits per word.
  33. Memory_Size 
    An implementation-defined value that is intended to reflect
the memory size of the configuration in storage elements.
  34. Address is of a definite, nonlimited type. Address represents machine addresses capable of addressing individual storage elements. Null_Address is an address that is distinct from the address of any object or program unit.
  35. See 13.5.3, for an explanation of Bit_Order and Default_Bit_Order.

    Implementation Permissions
  36. An implementation may add additional implementation-defined declarations to package System and its children. However, it is usually better for the implementation to provide additional functionality via implementation-defined children of System. Package System may be declared pure.

    Implementation Advice
  37. Address should be of a private type.

    NOTES

  38. (14) There are also some language-defined child packages of System defined elsewhere.

Node:13.7.1, Next:, Previous:13.7, Up:13.7

The Package System.Storage_Elements


Static Semantics
  1. The following language-defined library package exists: 
  2. package System.Storage_Elements is
   pragma Preelaborate(System.Storage_Elements);

  3.    type Storage_Offset is range implementation-defined;

  4.    subtype Storage_Count is Storage_Offset
     range 0..Storage_Offset'Last;

  5.    type Storage_Element is mod implementation-defined;
   for Storage_Element'Size use Storage_Unit;
   type Storage_Array is array
     (Storage_Offset range <>) of aliased Storage_Element;
   for Storage_Array'Component_Size use Storage_Unit;

  6.    -- Address Arithmetic:

  7.    function "+"(Left : Address; Right : Storage_Offset)
     return Address;
   function "+"(Left : Storage_Offset; Right : Address)
     return Address;
   function "-"(Left : Address; Right : Storage_Offset)
     return Address;
   function "-"(Left, Right : Address)
     return Storage_Offset;

  8.    function "mod"(Left : Address; Right : Storage_Offset)
     return Storage_Offset;

  9.    -- Conversion to/from integers:

  10.    type Integer_Address is implementation-defined;
   function To_Address(Value : Integer_Address) return Address;
   function To_Integer(Value : Address) return Integer_Address;

  11.    pragma Convention(Intrinsic, "+");
      -- ...and so on for all language-defined subprograms
      -- declared in this package.
end System.Storage_Elements;
  12. Storage_Element represents a storage element. Storage_Offset represents an offset in storage elements. Storage_Count represents a number of storage elements. Storage_Array represents a contiguous sequence of storage elements.
  13. Integer_Address is a (signed or modular) integer subtype. To_Address and To_Integer convert back and forth between this type and Address.

    Implementation Requirements
  14. Storage_Offset'Last shall be greater than or equal to Integer'Last or the largest possible storage offset, whichever is smaller. Storage_Offset'First shall be <= (-Storage_Offset'Last).

    Implementation Permissions
  15. Package System.Storage_Elements may be declared pure.

    Implementation Advice
  16. Operations in System and its children should reflect the target environment semantics as closely as is reasonable. For example, on most machines, it makes sense for address arithmetic to "wrap around." Operations that do not make sense should raise Program_Error.

Node:13.7.2, Next:, Previous:13.7.1, Up:13.7

The Package System.Address_To_Access_Conversions


Static Semantics
  1. The following language-defined generic library package exists: 
  2. generic
    type Object(<>) is limited private;
package System.Address_To_Access_Conversions is
   pragma Preelaborate(Address_To_Access_Conversions);

  3.    type Object_Pointer is access all Object;
   function To_Pointer(Value : Address) return Object_Pointer;
   function To_Address(Value : Object_Pointer) return Address;

  4.    pragma Convention(Intrinsic, To_Pointer);
   pragma Convention(Intrinsic, To_Address);
end System.Address_To_Access_Conversions;
  5. The To_Pointer and To_Address subprograms convert back and forth between values of types Object_Pointer and Address. To_Pointer(X'Address) is equal to X'Unchecked_Access for any X that allows Unchecked_Access. To_Pointer(Null_Address) returns null. For other addresses, the behavior is unspecified. To_Address(null) returns Null_Address (for null of the appropriate type). To_Address(Y), where Y /= null, returns Y.all'Address.

    Implementation Permissions
  6. An implementation may place restrictions on instantiations of Address_To_Access_Conversions.

Node:13.8, Next:, Previous:13.7.2, Up:13

Machine Code Insertions

  1. A machine code insertion can be achieved by a call to a subprogram whose sequence_of_statements contains code_statements.

    Syntax
  2. code_statement ::= qualified_expression;
    1. A code_statement is only allowed in the handled_sequence_of_statements of a subprogram_body. If a subprogram_body contains any code_statements, then within this subprogram_body the only allowed form of statement is a code_statement (labeled or not), the only allowed declarative_items are use_clauses, and no exception_handler is allowed (comments and pragmas are allowed as usual).

Name Resolution Rules
  1. The qualified_expression is expected to be of any type.

    Legality Rules
  2. The qualified_expression shall be of a type declared in package System.Machine_Code.
  3. A code_statement shall appear only within the scope of a with_clause that mentions package System.Machine_Code.

    Static Semantics
  4. The contents of the library package System.Machine_Code (if provided) are implementation defined. The meaning of code_statements is implementation defined. Typically, each qualified_expression represents a machine instruction or assembly directive.

    Implementation Permissions
  5. An implementation may place restrictions on code_statements. An implementation is not required to provide package System.Machine_Code.

    NOTES

  6. (15) An implementation may provide implementation-defined pragmas specifying register conventions and calling conventions.
  7. (16) Machine code functions are exempt from the rule that a return_statement is required. In fact, return_statements are forbidden, since only code_statements are allowed.
  8. (17) Intrinsic subprograms, see "Conformance Rules", can also be used to achieve machine code insertions. Interface to assembly language can be achieved using the features in Annex B, see "Interface to Other Languages".

    Examples
  9. Example of a code statement: 
  10. M : Mask;
procedure Set_Mask; pragma Inline(Set_Mask);

  11. procedure Set_Mask is
  use System.Machine_Code;
  -- assume ``with System.Machine_Code;'' appears somewhere above
begin
  SI_Format'(Code => SSM, B => M'Base_Reg, D => M'Disp);
  --  Base_Reg and Disp are implementation-defined attributes
end Set_Mask;

Node:13.9, Next:, Previous:13.8, Up:13

Unchecked Type Conversions

  1. An unchecked type conversion can be achieved by a call to an instance of the generic function Unchecked_Conversion.

    Static Semantics
  2. The following language-defined generic library function exists: 
  3. generic
   type Source(<>) is limited private;
   type Target(<>) is limited private;
function Ada.Unchecked_Conversion(S : Source) return Target;
pragma Convention(Intrinsic, Ada.Unchecked_Conversion);
pragma Pure(Ada.Unchecked_Conversion);

    Dynamic Semantics
  4. The size of the formal parameter S in an instance of Unchecked_Conversion is that of its subtype. This is the actual subtype passed to Source, except when the actual is an unconstrained composite subtype, in which case the subtype is constrained by the bounds or discriminants of the value of the actual expression passed to S.
  5. If all of the following are true, the effect of an unchecked conversion is to return the value of an object of the target subtype whose representation is the same as that of the source object S:
    1. S'Size = Target'Size.
    2. S'Alignment = Target'Alignment.
    3. The target subtype is not an unconstrained composite subtype.
    4. S and the target subtype both have a contiguous representation.
    5. The representation of S is a representation of an object of the target subtype.
  1. Otherwise, the effect is implementation defined; in particular, the result can be abnormal, see 13.9.1.

    Implementation Permissions
  2. An implementation may return the result of an unchecked conversion by reference, if the Source type is not a by-copy type. In this case, the result of the unchecked conversion represents simply a different (read-only) view of the operand of the conversion.
  3. An implementation may place restrictions on Unchecked_Conversion.

    Implementation Advice
  4. The Size of an array object should not include its bounds; hence, the bounds should not be part of the converted data.
  5. The implementation should not generate unnecessary run-time checks to ensure that the representation of S is a representation of the target type. It should take advantage of the permission to return by reference when possible. Restrictions on unchecked conversions should be avoided unless required by the target environment.
  6. The recommended level of support for unchecked conversions is:
      Unchecked conversions should be supported and should be reversible in the cases where this clause defines the result. To enable meaningful use of unchecked conversion, a contiguous representation should be used for elementary subtypes, for statically constrained array subtypes whose component subtype is one of the subtypes described in this paragraph, and for record subtypes without discriminants whose component subtypes are described in this paragraph.

Node:13.9.1, Next:, Previous:13.9, Up:13.9

Data Validity

  1. Certain actions that can potentially lead to erroneous execution are not directly erroneous, but instead can cause objects to become abnormal. Subsequent uses of abnormal objects can be erroneous.
  2. A scalar object can have an invalid representation, which means that the object's representation does not represent any value of the object's subtype. The primary cause of invalid representations is uninitialized variables.
  3. Abnormal objects and invalid representations are explained in this subclause.

    Dynamic Semantics
  4. When an object is first created, and any explicit or default initializations have been performed, the object and all of its parts are in the normal state. Subsequent operations generally leave them normal. However, an object or part of an object can become abnormal in the following ways:
    1. An assignment to the object is disrupted due to an abort, see 9.8, or due to the failure of a language-defined check, see 11.6.
    2. The object is not scalar, and is passed to an in out or out parameter of an imported procedure or language-defined input procedure, if after return from the procedure the representation of the parameter does not represent a value of the parameter's subtype.
  1. Whether or not an object actually becomes abnormal in these cases is not specified. An abnormal object becomes normal again upon successful completion of an assignment to the object as a whole.

    Erroneous Execution
  2. It is erroneous to evaluate a primary that is a name denoting an abnormal object, or to evaluate a prefix that denotes an abnormal object.

    Bounded (Run-Time) Errors
  3. If the representation of a scalar object does not represent a value of the object's subtype (perhaps because the object was not initialized), the object is said to have an invalid representation. It is a bounded error to evaluate the value of such an object. If the error is detected, either Constraint_Error or Program_Error is raised. Otherwise, execution continues using the invalid representation. The rules of the language outside this subclause assume that all objects have valid representations. The semantics of operations on invalid representations are as follows:
    1. If the representation of the object represents a value of the object's type, the value of the type is used.
    2. If the representation of the object does not represent a value of the object's type, the semantics of operations on such representations is implementation-defined, but does not by itself lead to erroneous or unpredictable execution, or to other objects becoming abnormal.

Erroneous Execution
  1. A call to an imported function or an instance of Unchecked_Conversion is erroneous if the result is scalar, and the result object has an invalid representation.
  2. The dereference of an access value is erroneous if it does not designate an object of an appropriate type or a subprogram with an appropriate profile, if it designates a nonexistent object, or if it is an access-to-variable value that designates a constant object. Such an access value can exist, for example, because of Unchecked_Deallocation, Unchecked_Access, or Unchecked_Conversion.

    NOTES

  3. (18) Objects can become abnormal due to other kinds of actions that directly update the object's representation; such actions are generally considered directly erroneous, however.

Node:13.9.2, Next:, Previous:13.9.1, Up:13.9

The Valid Attribute

  1. The Valid attribute can be used to check the validity of data produced by unchecked conversion, input, interface to foreign languages, and the like.

    Static Semantics
  2. For a prefix X that denotes a scalar object (after any implicit dereference), the following attribute is defined:
  3. X'Valid 
    Yields True if and only if the object denoted by X is normal
and has a valid representation. The value of this attribute
is of the predefined type Boolean.

    NOTES

  4. (19) Invalid data can be created in the following cases (not counting erroneous or unpredictable execution):
    1. an uninitialized scalar object,
    2. the result of an unchecked conversion,
    3. input,
    4. interface to another language (including machine code),
    5. aborting an assignment,
    6. disrupting an assignment due to the failure of a language-defined check (see 11.6) and
    7. use of an object whose Address has been specified.
  1. (20) X'Valid is not considered to be a read of X; hence, it is not an error to check the validity of invalid data.

Node:13.10, Next:, Previous:13.9.2, Up:13

Unchecked Access Value Creation

  1. The attribute Unchecked_Access is used to create access values in an unsafe manner - the programmer is responsible for preventing "dangling references."

    Static Semantics
  2. The following attribute is defined for a prefix X that denotes an aliased view of an object:
  3. X'Unchecked_Access 
    All rules and semantics that apply to X'Access, see 3.10.2,
apply also to X'Unchecked_Access, except that, for the
purposes of accessibility rules and checks, it is as if X
were declared immediately within a library package.

    NOTES

  4. (21) This attribute is provided to support the situation where a local object is to be inserted into a global linked data structure, when the programmer knows that it will always be removed from the data structure prior to exiting the object's scope. The Access attribute would be illegal in this case, see "Operations of Access Types".
  5. (22) There is no Unchecked_Access attribute for subprograms.

Node:13.11, Next:, Previous:13.10, Up:13

Storage Management

  1. Each access-to-object type has an associated storage pool. The storage allocated by an allocator comes from the pool; instances of Unchecked_Deallocation return storage to the pool. Several access types can share the same pool.
  2. A storage pool is a variable of a type in the class rooted at Root_Storage_Pool, which is an abstract limited controlled type. By default, the implementation chooses a standard storage pool for each access type. The user may define new pool types, and may override the choice of pool for an access type by specifying Storage_Pool for the type.

    Legality Rules
  3. If Storage_Pool is specified for a given access type, Storage_Size shall not be specified for it.

    Static Semantics
  4. The following language-defined library package exists: 
  5. with Ada.Finalization;
with System.Storage_Elements;
package System.Storage_Pools is
    pragma Preelaborate(System.Storage_Pools);

  6.     type Root_Storage_Pool is
        abstract new
          Ada.Finalization.Limited_Controlled with private;

  7.     procedure Allocate(
      Pool : in out Root_Storage_Pool;
      Storage_Address : out Address;
      Size_In_Storage_Elements : in Storage_Elements.Storage_Count;
      Alignment : in Storage_Elements.Storage_Count) is abstract;

  8.     procedure Deallocate(
      Pool : in out Root_Storage_Pool;
      Storage_Address : in Address;
      Size_In_Storage_Elements : in Storage_Elements.Storage_Count;
      Alignment : in Storage_Elements.Storage_Count) is abstract;

  9.     function Storage_Size(Pool : Root_Storage_Pool)
        return Storage_Elements.Storage_Count is abstract;

  10. private
   ... -- not specified by the language
end System.Storage_Pools;
  11. A storage pool type (or pool type) is a descendant of Root_Storage_Pool. The elements of a storage pool are the objects allocated in the pool by allocators.
  12. For every access subtype S, the following attributes are defined:
  13. S'Storage_Pool 
    Denotes the storage pool of the type of S. The type of this
attribute is Root_Storage_Pool'Class.
  14. S'Storage_Size 
    Yields the result of calling Storage_Size(S'Storage_Pool),
which is intended to be a measure of the number of storage
elements reserved for the pool. The type of this attribute
is universal_integer.
  15. Storage_Size or Storage_Pool may be specified for a non-derived access-to-object type via an attribute_definition_clause; the name in a Storage_Pool clause shall denote a variable.
  16. An allocator of type T allocates storage from T's storage pool. If the storage pool is a user-defined object, then the storage is allocated by calling Allocate, passing T'Storage_Pool as the Pool parameter. The Size_In_Storage_Elements parameter indicates the number of storage elements to be allocated, and is no more than D'Max_Size_In_Storage_Elements, where D is the designated subtype. The Alignment parameter is D'Alignment. The result returned in the Storage_Address parameter is used by the allocator as the address of the allocated storage, which is a contiguous block of memory of Size_In_Storage_Elements storage elements. Any exception propagated by Allocate is propagated by the allocator.
  17. If Storage_Pool is not specified for a type defined by an access_to_object_definition, then the implementation chooses a standard storage pool for it in an implementation-defined manner. In this case, the exception Storage_Error is raised by an allocator if there is not enough storage. It is implementation defined whether or not the implementation provides user-accessible names for the standard pool type(s).
  18. If Storage_Size is specified for an access type, then the Storage_Size of this pool is at least that requested, and the storage for the pool is reclaimed when the master containing the declaration of the access type is left. If the implementation cannot satisfy the request, Storage_Error is raised at the point of the attribute_definition_clause. If neither Storage_Pool nor Storage_Size are specified, then the meaning of Storage_Size is implementation defined.
  19. If Storage_Pool is specified for an access type, then the specified pool is used.
  20. The effect of calling Allocate and Deallocate for a standard storage pool directly (rather than implicitly via an allocator or an instance of Unchecked_Deallocation) is unspecified.

    Erroneous Execution
  21. If Storage_Pool is specified for an access type, then if Allocate can satisfy the request, it should allocate a contiguous block of memory, and return the address of the first storage element in Storage_Address. The block should contain Size_In_Storage_Elements storage elements, and should be aligned according to Alignment. The allocated storage should not be used for any other purpose while the pool element remains in existence. If the request cannot be satisfied, then Allocate should propagate an exception (such as Storage_Error). If Allocate behaves in any other manner, then the program execution is erroneous.

    Documentation Requirements
  22. An implementation shall document the set of values that a user-defined Allocate procedure needs to accept for the Alignment parameter. An implementation shall document how the standard storage pool is chosen, and how storage is allocated by standard storage pools.

    Implementation Advice
  23. An implementation should document any cases in which it dynamically allocates heap storage for a purpose other than the evaluation of an allocator.
  24. A default (implementation-provided) storage pool for an access-to-constant type should not have overhead to support deallocation of individual objects.
  25. A storage pool for an anonymous access type should be created at the point of an allocator for the type, and be reclaimed when the designated object becomes inaccessible.

    NOTES

  26. (23) A user-defined storage pool type can be obtained by extending the Root_Storage_Pool type, and overriding the primitive subprograms Allocate, Deallocate, and Storage_Size. A user-defined storage pool can then be obtained by declaring an object of the type extension. The user can override Initialize and Finalize if there is any need for non-trivial initialization and finalization for a user-defined pool type. For example, Finalize might reclaim blocks of storage that are allocated separately from the pool object itself.
  27. (24) The writer of the user-defined allocation and deallocation procedures, and users of allocators for the associated access type, are responsible for dealing with any interactions with tasking. In particular:
    1. If the allocators are used in different tasks, they require mutual exclusion.
    2. If they are used inside protected objects, they cannot block.
    3. If they are used by interrupt handlers, see "Interrupt Support", the mutual exclusion mechanism has to work properly in that context.
  1. (25) The primitives Allocate, Deallocate, and Storage_Size are declared as abstract, see 3.9.3, and therefore they have to be overridden when a new (non-abstract) storage pool type is declared.

    Examples
  2. To associate an access type with a storage pool object, the user first declares a pool object of some type derived from Root_Storage_Pool. Then, the user defines its Storage_Pool attribute, as follows: 
  3. Pool_Object : Some_Storage_Pool_Type;

  4. type T is access Designated;
for T'Storage_Pool use Pool_Object;
  5. Another access type may be added to an existing storage pool, via: 
  6. for T2'Storage_Pool use T'Storage_Pool;
  7. The semantics of this is implementation defined for a standard storage pool.
  8. As usual, a derivative of Root_Storage_Pool may define additional operations. For example, presuming that Mark_Release_Pool_Type has two additional operations, Mark and Release, the following is a possible use: 
  9. type Mark_Release_Pool_Type
   (Pool_Size : Storage_Elements.Storage_Count;
    Block_Size : Storage_Elements.Storage_Count)
        is new Root_Storage_Pool with limited private;

  10. ...

  11. MR_Pool : Mark_Release_Pool_Type (Pool_Size => 2000,
                                  Block_Size => 100);

  12. type Acc is access ...;
for Acc'Storage_Pool use MR_Pool;
...

  13. Mark(MR_Pool);
... -- Allocate objects using ``new Designated(...)''.
Release(MR_Pool); -- Reclaim the storage.

Node:13.11.1, Next:, Previous:13.11, Up:13

The Max_Size_In_Storage_Elements Attribute

  1. The Max_Size_In_Storage_Elements attribute is useful in writing user-defined pool types.

    Static Semantics
  2. For every subtype S, the following attribute is defined:
  3. S'Max_Size_In_Storage_Elements 
  4. Denotes the maximum value for Size_In_Storage_Elements that
will be requested via Allocate for an access type whose
designated subtype is S. The value of this attribute is of
type universal_integer.

Node:13.11.2, Next:, Previous:13.11.1, Up:13.11

Unchecked Storage Deallocation

  1. Unchecked storage deallocation of an object designated by a value of an access type is achieved by a call to an instance of the generic procedure Unchecked_Deallocation.

    Static Semantics
  2. The following language-defined generic library procedure exists: 
  3. generic
   type Object(<>) is limited private;
   type Name   is access  Object;
procedure Ada.Unchecked_Deallocation(X : in out Name);
pragma Convention(Intrinsic, Ada.Unchecked_Deallocation);
pragma Preelaborate(Ada.Unchecked_Deallocation);

    Dynamic Semantics
  4. Given an instance of Unchecked_Deallocation declared as follows: 
  5. procedure Free is
    new Ada.Unchecked_Deallocation
      (object_subtype_name, access_to_variable_subtype_name);
  6. Procedure Free has the following effect:
    1. After executing Free(X), the value of X is null.
    2. Free(X), when X is already equal to null, has no effect.
    3. Free(X), when X is not equal to null first performs finalization, as described in 7.6. It then deallocates the storage occupied by the object designated by X. If the storage pool is a user-defined object, then the storage is deallocated by calling Deallocate, passing access_to_variable_subtype_name'Storage_Pool as the Pool parameter. Storage_Address is the value returned in the Storage_Address parameter of the corresponding Allocate call. Size_In_Storage_Elements and Alignment are the same values passed to the corresponding Allocate call. There is one exception: if the object being freed contains tasks, the object might not be deallocated.
  1. After Free(X), the object designated by X, and any subcomponents thereof, no longer exist; their storage can be reused for other purposes.

    Bounded (Run-Time) Errors
  2. It is a bounded error to free a discriminated, unterminated task object. The possible consequences are:
    1. No exception is raised.
    2. Program_Error or Tasking_Error is raised at the point of the deallocation.
    3. Program_Error or Tasking_Error is raised in the task the next time it references any of the discriminants.
  1. In the first two cases, the storage for the discriminants (and for any enclosing object if it is designated by an access discriminant of the task) is not reclaimed prior to task termination.

    Erroneous Execution
  2. Evaluating a name that denotes a nonexistent object is erroneous. The execution of a call to an instance of Unchecked_Deallocation is erroneous if the object was created other than by an allocator for an access type whose pool is Name'Storage_Pool.

    Implementation Advice
  3. For a standard storage pool, Free should actually reclaim the storage.

    NOTES

  4. (26) The rules here that refer to Free apply to any instance of Unchecked_Deallocation.
  5. (27) Unchecked_Deallocation cannot be instantiated for an access-to-constant type. This is implied by the rules of 12.5.4.

Node:13.11.3, Next:, Previous:13.11.2, Up:13.11

Pragma Controlled

  1. Pragma Controlled is used to prevent any automatic reclamation of storage (garbage collection) for the objects created by allocators of a given access type.

    Syntax
  2. The form of a pragma Controlled is as follows: 
  3. pragma Controlled(first_subtype_local_name);

    Legality Rules
  4. The first_subtype_local_name of a pragma Controlled shall denote a non-derived access subtype.

    Static Semantics
  5. A pragma Controlled is a representation pragma that specifies the controlled aspect of representation.
  6. Garbage collection is a process that automatically reclaims storage, or moves objects to a different address, while the objects still exist.
  7. If a pragma Controlled is specified for an access type with a standard storage pool, then garbage collection is not performed for objects in that pool.

    Implementation Permissions
  8. An implementation need not support garbage collection, in which case, a pragma Controlled has no effect.

Node:13.12, Next:, Previous:13.11.3, Up:13

Pragma Restrictions

  1. A pragma Restrictions expresses the user's intent to abide by certain restrictions. This may facilitate the construction of simpler run-time environments.

    Syntax
  2. The form of a pragma Restrictions is as follows: 
  3. pragma Restrictions(restriction{, restriction});

  4. restriction ::= restriction_identifier
   | restriction_parameter_identifier => expression

    Name Resolution Rules
  5. Unless otherwise specified for a particular restriction, the expression is expected to be of any integer type.

    Legality Rules
  6. Unless otherwise specified for a particular restriction, the expression shall be static, and its value shall be nonnegative.

    Static Semantics
  7. The set of restrictions is implementation defined.

    Post-Compilation Rules
  8. A pragma Restrictions is a configuration pragma; unless otherwise specified for a particular restriction, a partition shall obey the restriction if a pragma Restrictions applies to any compilation unit included in the partition.

    Implementation Permissions
  9. An implementation may place limitations on the values of the expression that are supported, and limitations on the supported combinations of restrictions. The consequences of violating such limitations are implementation defined.

    NOTES

  10. (28) Restrictions intended to facilitate the construction of efficient tasking run-time systems are defined in D.7. Safety- and security-related restrictions are defined in H.4.
  11. (29) An implementation has to enforce the restrictions in cases where enforcement is required, even if it chooses not to take advantage of the restrictions in terms of efficiency.

Node:13.13, Next:, Previous:13.12, Up:13

Streams

  1. A stream is a sequence of elements comprising values from possibly different types and allowing sequential access to these values. A stream type is a type in the class whose root type is Streams.Root_Stream_Type. A stream type may be implemented in various ways, such as an external sequential file, an internal buffer, or a network channel.

Node:13.13.1, Next:, Previous:13.13, Up:13.13

The Package Streams


Static Semantics
  1. The abstract type Root_Stream_Type is the root type of the class of stream types. The types in this class represent different kinds of streams. A new stream type is defined by extending the root type (or some other stream type), overriding the Read and Write operations, and optionally defining additional primitive subprograms, according to the requirements of the particular kind of stream. The predefined stream-oriented attributes like T'Read and T'Write make dispatching calls on the Read and Write procedures of the Root_Stream_Type. (User-defined T'Read and T'Write attributes can also make such calls, or can call the Read and Write attributes of other types.) 
  2. package Ada.Streams is
    pragma Pure(Streams);

  3.     type Root_Stream_Type is abstract tagged limited private;

  4.     type Stream_Element is mod implementation-defined;
    type Stream_Element_Offset is range implementation-defined;
    subtype Stream_Element_Count is
        Stream_Element_Offset range 0..Stream_Element_Offset'Last;
    type Stream_Element_Array is
        array(Stream_Element_Offset range <>) of Stream_Element;

  5.     procedure Read(
      Stream : in out Root_Stream_Type;
      Item   : out Stream_Element_Array;
      Last   : out Stream_Element_Offset) is abstract;

  6.     procedure Write(
      Stream : in out Root_Stream_Type;
      Item   : in Stream_Element_Array) is abstract;

  7. private
   ... -- not specified by the language
end Ada.Streams;
  8. The Read operation transfers Item'Length stream elements from the specified stream to fill the array Item. The index of the last stream element transferred is returned in Last. Last is less than Item'Last only if the end of the stream is reached.
  9. The Write operation appends Item to the specified stream.

    NOTES

  10. (30) See "The Package Streams.Stream_IO", for an example of extending type Root_Stream_Type.

Node:13.13.2, Next:, Previous:13.13.1, Up:13.13

Stream-Oriented Attributes

  1. The Write, Read, Output, and Input attributes convert values to a stream of elements and reconstruct values from a stream.

    Static Semantics
  2. For every subtype S of a specific type T, the following attributes are defined.
  3. S'Write 
    S'Write denotes a procedure with the following specification:

    1. procedure S'Write(
   Stream : access Ada.Streams.Root_Stream_Type'Class;
   Item : in T)
    2. S'Write writes the value of Item to Stream.
  1. S'Read 
    S'Read denotes a procedure with the following specification:

    1. procedure S'Read(
   Stream : access Ada.Streams.Root_Stream_Type'Class;
   Item : out T)
    2. S'Read reads the value of Item from Stream.
  1. For elementary types, the representation in terms of stream elements is implementation defined. For composite types, the Write or Read attribute for each component is called in a canonical order. The canonical order of components is last dimension varying fastest for an array, and positional aggregate order for a record. Bounds are not included in the stream if T is an array type. If T is a discriminated type, discriminants are included only if they have defaults. If T is a tagged type, the tag is not included.
  2. For every subtype S'Class of a class-wide type T'Class:
  3. S'Class'Write 
    S'Class'Write denotes a procedure with the following
specification:

    1. procedure S'Class'Write(
   Stream : access Ada.Streams.Root_Stream_Type'Class;
   Item   : in T'Class)
    2. Dispatches to the subprogram denoted by the Write attribute of the specific type identified by the tag of Item.
  1. S'Class'Read 
    S'Class'Read denotes a procedure with the following
specification:

    1. procedure S'Class'Read(
   Stream : access Ada.Streams.Root_Stream_Type'Class;
   Item : out T'Class)
    2. Dispatches to the subprogram denoted by the Read attribute of the specific type identified by the tag of Item.

Implementation Advice
  1. If a stream element is the same size as a storage element, then the normal in-memory representation should be used by Read and Write for scalar objects. Otherwise, Read and Write should use the smallest number of stream elements needed to represent all values in the base range of the scalar type.

    Static Semantics
  2. For every subtype S of a specific type T, the following attributes are defined.
  3. S'Output 
    S'Output denotes a procedure with the following specification:

    1. procedure S'Output(
   Stream : access Ada.Streams.Root_Stream_Type'Class;
   Item : in T)
    2. S'Output writes the value of Item to Stream, including any bounds or discriminants.
  1. S'Input 
    S'Input denotes a function with the following specification:

    1. function S'Input(
   Stream : access Ada.Streams.Root_Stream_Type'Class)
   return T
    2. S'Input reads and returns one value from Stream, using any bounds or discriminants written by a corresponding S'Output to determine how much to read.
  1. Unless overridden by an attribute_definition_clause, these subprograms execute as follows:
    1. If T is an array type, S'Output first writes the bounds, and S'Input first reads the bounds. If T has discriminants without defaults, S'Output first writes the discriminants (using S'Write for each), and S'Input first reads the discriminants (using S'Read for each).
    2. S'Output then calls S'Write to write the value of Item to the stream. S'Input then creates an object (with the bounds or discriminants, if any, taken from the stream), initializes it with S'Read, and returns the value of the object.
  1. For every subtype S'Class of a class-wide type T'Class:
  2. S'Class'Output 
    S'Class'Output denotes a procedure with the following
specification:

    1. procedure S'Class'Output(
   Stream : access Ada.Streams.Root_Stream_Type'Class;
   Item   : in T'Class)
    2. First writes the external tag of Item to Stream (by calling String'Output(Tags.External_Tag(Item'Tag) - see 3.9.) and then dispatches to the subprogram denoted by the Output attribute of the specific type identified by the tag.
  1. S'Class'Input 
    S'Class'Input denotes a function with the following
specification:

    1. function S'Class'Input(
   Stream : access Ada.Streams.Root_Stream_Type'Class)
   return T'Class
    2. First reads the external tag from Stream and determines the corresponding internal tag (by calling Tags.Internal_Tag(String'Input(Stream)) - see 3.9.) and then dispatches to the subprogram denoted by the Input attribute of the specific type identified by the internal tag; returns that result.
  1. In the default implementation of Read and Input for a composite type, for each scalar component that is a discriminant or whose component_declaration includes a default_expression, a check is made that the value returned by Read for the component belongs to its subtype. Constraint_Error is raised if this check fails. For other scalar components, no check is made. For each component that is of an access type, if the implementation can detect that the value returned by Read for the component is not a value of its subtype, Constraint_Error is raised. If the value is not a value of its subtype and this error is not detected, the component has an abnormal value, and erroneous execution can result, see 13.9.1.
  2. The stream-oriented attributes may be specified for any type via an attribute_definition_clause. All nonlimited types have default implementations for these operations. An attribute_reference for one of these attributes is illegal if the type is limited, unless the attribute has been specified by an attribute_definition_clause. For an attribute_definition_clause specifying one of these attributes, the subtype of the Item parameter shall be the base subtype if scalar, and the first subtype otherwise. The same rule applies to the result of the Input function.

    NOTES

  3. (31) For a definite subtype S of a type T, only T'Write and T'Read are needed to pass an arbitrary value of the subtype through a stream. For an indefinite subtype S of a type T, T'Output and T'Input will normally be needed, since T'Write and T'Read do not pass bounds, discriminants, or tags.
  4. (32) User-specified attributes of S'Class are not inherited by other class-wide types descended from S.

    Examples
  5. Example of user-defined Write attribute: 
  6. procedure My_Write
  (Stream : access Ada.Streams.Root_Stream_Type'Class;
   Item   : My_Integer'Base);
for My_Integer'Write use My_Write;

Node:13.14, Next:, Previous:13.13.2, Up:13

Freezing Rules

  1. This clause defines a place in the program text where each declared entity becomes "frozen." A use of an entity, such as a reference to it by name, or (for a type) an expression of the type, causes freezing of the entity in some contexts, as described below. The Legality Rules forbid certain kinds of uses of an entity in the region of text where it is frozen.
  2. The freezing of an entity occurs at one or more places (freezing points) in the program text where the representation for the entity has to be fully determined. Each entity is frozen from its first freezing point to the end of the program text (given the ordering of compilation units defined in 10.1.4.
  3. The end of a declarative_part, protected_body, or a declaration of a library package or generic library package, causes freezing of each entity declared within it, except for incomplete types. A noninstance body causes freezing of each entity declared before it within the same declarative_part.
  4. A construct that (explicitly or implicitly) references an entity can cause the freezing of the entity, as defined by subsequent paragraphs. At the place where a construct causes freezing, each name, expression, or range within the construct causes freezing:
    1. The occurrence of a generic_instantiation causes freezing; also, if a parameter of the instantiation is defaulted, the default_expression or default_name for that parameter causes freezing.
    2. The occurrence of an object_declaration that has no corresponding completion causes freezing.
    3. The declaration of a record extension causes freezing of the parent subtype.
  1. A static expression causes freezing where it occurs. A nonstatic expression causes freezing where it occurs, unless the expression is part of a default_expression, a default_name, or a per-object expression of a component's constraint, in which case, the freezing occurs later as part of another construct.
  2. The following rules define which entities are frozen at the place where a construct causes freezing:
    1. At the place where an expression causes freezing, the type of the expression is frozen, unless the expression is an enumeration literal used as a discrete_choice of the array_aggregate of an enumeration_representation_clause.
    2. At the place where a name causes freezing, the entity denoted by the name is frozen, unless the name is a prefix of an expanded name; at the place where an object name causes freezing, the nominal subtype associated with the name is frozen.
    3. At the place where a range causes freezing, the type of the range is frozen.
    4. At the place where an allocator causes freezing, the designated subtype of its type is frozen. If the type of the allocator is a derived type, then all ancestor types are also frozen.
    5. At the place where a callable entity is frozen, each subtype of its profile is frozen. If the callable entity is a member of an entry family, the index subtype of the family is frozen. At the place where a function call causes freezing, if a parameter of the call is defaulted, the default_expression for that parameter causes freezing.
    6. At the place where a subtype is frozen, its type is frozen. At the place where a type is frozen, any expressions or names within the full type definition cause freezing; the first subtype, and any component subtypes, index subtypes, and parent subtype of the type are frozen as well. For a specific tagged type, the corresponding class-wide type is frozen as well. For a class-wide type, the corresponding specific type is frozen as well.

Legality Rules
  1. The explicit declaration of a primitive subprogram of a tagged type shall occur before the type is frozen, see 3.9.2.
  2. A type shall be completely defined before it is frozen (see 3.11.1, and 7.3.).
  3. The completion of a deferred constant declaration shall occur before the constant is frozen, see 7.4.
  4. A representation item that directly specifies an aspect of an entity shall appear before the entity is frozen, see 13.1.

Node:A, Next:, Previous:13.14, Up:Top

Predefined Language Environment (normative)

  1. This Annex contains the specifications of library units that shall be provided by every implementation. There are three root library units: Ada, Interfaces, and System; other library units are children of these: 
  2. Standard --  see A.1.
  Ada --  see A.2.
     Asynchronous_Task_Control --  see D.11.
     Calendar --  see 9.6.
     Characters --  see A.3.1.
        Handling --  see A.3.2.
        Latin_1 --  see A.3.3.
     Command_Line --  see A.15.
     Decimal --  see F.2.
     Direct_IO --  see A.8.4.
     Dynamic_Priorities --  see D.5.
     Exceptions --  see 11.4.1.
     Finalization --  see 7.6.
     Interrupts --  see C.3.2.
        Names --  see C.3.2.
     IO_Exceptions --  see A.13.
     Numerics --  see A.5.
        Complex_Elementary_Functions --  see G.1.2.
        Complex_Types --  see G.1.1.
        Discrete_Random --  see A.5.2.
        Elementary_Functions --  see A.5.1.
        Float_Random --  see A.5.2.
        Generic_Complex_Elementary_Functions --  see G.1.2.
        Generic_Complex_Types --  see G.1.1.
        Generic_Elementary_Functions --  see A.5.1.
     Real_Time --  see D.8.
     Sequential_IO --  see A.8.1.
     Storage_IO --  see A.9.
     Streams --  see 13.13.1.
        Stream_IO --  see A.12.1.
     Strings --  see A.4.1.
        Bounded --  see A.4.4.
        Fixed --  see A.4.3.
        Maps --  see A.4.2.
           Constants --  see A.4.6.
        Unbounded --  see A.4.5.
        Wide_Bounded --  see A.4.7.
        Wide_Fixed --  see A.4.7.
        Wide_Maps --  see A.4.7.
           Wide_Constants --  see A.4.7.
        Wide_Unbounded --  see A.4.7.
Standard (...continued)
  Ada (...continued)
     Synchronous_Task_Control --  see D.10.
     Tags --  see 3.9.
     Task_Attributes --  see C.7.2.
     Task_Identification --  see C.7.1.
     Text_IO --  see A.10.1.
        Complex_IO --  see G.1.3.
        Editing --  see F.3.3.
        Text_Streams --  see A.12.2.
     Unchecked_Conversion --  see 13.9.
     Unchecked_Deallocation --  see 13.11.2.
     Wide_Text_IO --  see A.11.
        Complex_IO --  see G.1.3.
        Editing --  see F.3.4.
        Text_Streams --  see A.12.3.

  Interfaces --  see B.2.
     C --  see B.3.
        Pointers --  see B.3.2.
        Strings --  see B.3.1.
     COBOL --  see B.4.
     Fortran --  see B.5.

  System --  see 13.7.
     Address_To_Access_Conversions --  see 13.7.2.
     Machine_Code --  see 13.8.
     RPC --  see E.5.
     Storage_Elements --  see 13.7.1.
     Storage_Pools --  see 13.11.

    Implementation Requirements
  3. The implementation shall ensure that each language defined subprogram is reentrant in the sense that concurrent calls on the same subprogram perform as specified, so long as all parameters that could be passed by reference denote nonoverlapping objects.

    Implementation Permissions
  4. The implementation may restrict the replacement of language-defined compilation units. The implementation may restrict children of language-defined library units (other than Standard).

Node:A.1, Next:, Previous:A, Up:A

The Package Standard

  1. This clause outlines the specification of the package Standard containing all predefined identifiers in the language. The corresponding package body is not specified by the language.
  2. The operators that are predefined for the types declared in the package Standard are given in comments since they are implicitly declared. Italics are used for pseudo-names of anonymous types (such as root_real) and for undefined information (such as implementation-defined).

    Static Semantics
  3. The library package Standard has the following declaration: 
  4. package Standard is
   pragma Pure(Standard);

  5.    type Boolean is (False, True);

  6.    --  The predefined relational operators
   --  for this type are as follows:

  7.    -- function "="   (Left, Right : Boolean) return Boolean;
   -- function "/="  (Left, Right : Boolean) return Boolean;
   -- function "<"   (Left, Right : Boolean) return Boolean;
   -- function "<="  (Left, Right : Boolean) return Boolean;
   -- function ">"   (Left, Right : Boolean) return Boolean;
   -- function ">="  (Left, Right : Boolean) return Boolean;

  8.    --  The predefined logical operators and the predefined
   --  logical negation operator are as follows:

  9.    --  function "and" (Left, Right : Boolean) return Boolean;
   --  function "or"  (Left, Right : Boolean) return Boolean;
   --  function "xor" (Left, Right : Boolean) return Boolean;

  10.    --  function "not" (Right : Boolean) return Boolean;

  11.    --  The integer type root_integer is predefined.
   --  The corresponding universal type is universal_integer.

  12.    type Integer is range implementation-defined;

  13.    subtype Natural  is Integer range 0 .. Integer'Last;
   subtype Positive is Integer range 1 .. Integer'Last;

  14.    --  The predefined operators for type Integer are as follows:

  15.    --  function "="  (Left, Right : Integer'Base) return Boolean;
   --  function "/=" (Left, Right : Integer'Base) return Boolean;
   --  function "<"  (Left, Right : Integer'Base) return Boolean;
   --  function "<=" (Left, Right : Integer'Base) return Boolean;
   --  function ">"  (Left, Right : Integer'Base) return Boolean;
   --  function ">=" (Left, Right : Integer'Base) return Boolean;

  16.    --  function "+"   (Right : Integer'Base) return Integer'Base;
   --  function "-"   (Right : Integer'Base) return Integer'Base;
   --  function "abs" (Right : Integer'Base) return Integer'Base;

  17.    --  function "+"   (Left, Right : Integer'Base)
   --    return Integer'Base;
   --  function "-"   (Left, Right : Integer'Base)
   --    return Integer'Base;
   --  function "*"   (Left, Right : Integer'Base)
   --    return Integer'Base;
   --  function "/"   (Left, Right : Integer'Base)
   --    return Integer'Base;
   --  function "rem" (Left, Right : Integer'Base)
   --    return Integer'Base;
   --  function "mod" (Left, Right : Integer'Base)
   --    return Integer'Base;

  18.    --  function "**"
     (Left  : Integer'Base;
      Right : Natural) return Integer'Base;

  19.    --  The specification of each operator for the type
   --  root_integer, or for any additional predefined integer
   --  type, is obtained by replacing Integer by the name of the type
   --  in the specification of the corresponding operator of the type
   --  Integer. The right operand of the exponentiation operator
   --  remains as subtype Natural.

  20.    --  The floating point type root_real is predefined.
   --  The corresponding universal type is universal_real.

  21.    type Float is digits implementation-defined;

  22.    --  The predefined operators for this type are as follows:

  23.    --  function "="   (Left, Right : Float) return Boolean;
   --  function "/="  (Left, Right : Float) return Boolean;
   --  function "<"   (Left, Right : Float) return Boolean;
   --  function "<="  (Left, Right : Float) return Boolean;
   --  function ">"   (Left, Right : Float) return Boolean;
   --  function ">="  (Left, Right : Float) return Boolean;

  24.    --  function "+"   (Right : Float) return Float;
   --  function "-"   (Right : Float) return Float;
   --  function "abs" (Right : Float) return Float;

  25.    --  function "+"   (Left, Right : Float) return Float;
   --  function "-"   (Left, Right : Float) return Float;
   --  function "*"   (Left, Right : Float) return Float;
   --  function "/"   (Left, Right : Float) return Float;

  26.    --  function "**"
     (Left  : Float;
      Right : Integer'Base) return Float;

  27.    --  The specification of each operator for the type root_real,
   --  or  for any additional predefined floating point type, is
   --  obtained by replacing Float by the name of the type in the
   --  specification of the corresponding operator of the type Float.

  28.    --  In addition, the following operators are predefined for
   --  the root numeric types:

  29.    function "*" (Left : root_integer; Right : root_real)
     return root_real;

  30.    function "*" (Left : root_real; Right : root_integer)
     return root_real;

  31.    function "/" (Left : root_real; Right : root_integer)
     return root_real;

  32.    --  The type universal_fixed is predefined.
   --  The only multiplying operators defined between
   --  fixed point types are

  33.    function "*" (Left : universal_fixed; Right : universal_fixed)
     return universal_fixed;

  34.    function "/" (Left : universal_fixed; Right : universal_fixed)
     return universal_fixed;

   --  The declaration of type Character is based on the standard
   --  ISO 8859-1 character set.

  35.    --  There are no character literals corresponding to the
   --  positions for control characters. They are indicated in
   --  italics in this definition (see 3.5.2).

   type Character is

     (nul,  soh,  stx,  etx, eot,  enq,  ack,  bel,
      bs,   ht,   lf,   vt,  ff,   cr,   so,   si,

      dle,  dc1,  dc2,  dc3, dc4,  nak,  syn,  etb,
      can,  em,   sub,  esc, fs,   gs,   rs,   us,

      ' ',  '!',  '"',  '#', '$',  '%',  '&',  ''',
      '(',  ')',  '*',  '+', ',',  '-',  '.',  '/',

      '0',  '1',  '2',  '3', '4',  '5',  '6',  '7',
      '8',  '9',  ':',  ';', '<',  '=',  '>',  '?',

      '´,  'A',  'B',  'C', 'D',  'E',  'F',  'G',
      'H',  'I',  'J',  'K', 'L',  'M',  'N',  'O',

      'P',  'Q',  'R',  'S', 'T',  'U',  'V',  'W',
      'X',  'Y',  'Z',  '[', '\',  ']',  '^',  '_',

      '`',  'a',  'b',  'c', 'd',  'e',  'f',  'g',
      'h',  'i',  'j',  'k', 'l',  'm',  'n',  'o',

      'p',  'q',  'r',  's', 't',  'u',  'v',  'w',
      'x',  'y',  'z',  '{', '|',  '}',  '~',  del,

      reserved_128, reserved_129,  bph,  nbh,
      reserved_132, nel,     ssa,  esa,

      hts, htj, vts, pld, plu, ri, ss2, ss3,

      dcs, pu1, pu2, sts, cch, mw, spa, epa,

      sos, reserved_153, sci, csi,
      st,  osc,          pm,  apc,

   ... );

  36.    --  The predefined operators for the type Character are the
   --  same as for any enumeration type.

   --  The declaration of type Wide_Character is based on the
   --  standard ISO 10646 BMP character set. The first 256 positions
   --  have the same contents as type Character (see 3.5.2).

   type Wide_Character is (nul, soh ... FFFE, FFFF);

   package ASCII is ... end ASCII;  --Obsolescent;  (see J.5).

   -- Predefined string types:

  37.    type String is array(Positive range <>) of Character;
   pragma Pack(String);

  38.    -- The predefined operators for this type are as follows:

  39.    --  function "="  (Left, Right: String) return Boolean;
   --  function "/=" (Left, Right: String) return Boolean;
   --  function "<"  (Left, Right: String) return Boolean;
   --  function "<=" (Left, Right: String) return Boolean;
   --  function ">"  (Left, Right: String) return Boolean;
   --  function ">=" (Left, Right: String) return Boolean;

  40.    --  function "&" (Left: String;    Right: String)
   --    return String;
   --  function "&" (Left: Character; Right: String)
   --    return String;
   --  function "&" (Left: String;    Right: Character)
   --    return String;
   --  function "&" (Left: Character; Right: Character)
   --    return String;

  41.    type Wide_String is array(Positive range <>) of Wide_Character;
   pragma Pack(Wide_String);

  42.    --  The predefined operators for this type correspond to those
   --  for String

  43.    type Duration is delta
     implementation-defined range implementation-defined;

  44.    --  The predefined operators for the type Duration are the
   --  same as for any fixed point type.

  45.    -- The predefined exceptions:

  46.    Constraint_Error: exception;
   Program_Error   : exception;
   Storage_Error   : exception;
   Tasking_Error   : exception;

  47. end Standard;
  48. Standard has no private part.
  49. In each of the types Character and Wide_Character, the character literals for the space character (position 32) and the non-breaking space character (position 160) correspond to different values. Unless indicated otherwise, each occurrence of the character literal ' ' in this International Standard refers to the space character. Similarly, the character literals for hyphen (position 45) and soft hyphen (position 173) correspond to different values. Unless indicated otherwise, each occurrence of the character literal '-' in this International Standard refers to the hyphen character.

    Dynamic Semantics
  50. Elaboration of the body of Standard has no effect.

    Implementation Permissions
  51. An implementation may provide additional predefined integer types and additional predefined floating point types. Not all of these types need have names.

    Implementation Advice
  52. If an implementation provides additional named predefined integer types, then the names should end with "Integer" as in "Long_Integer". If an implementation provides additional named predefined floating point types, then the names should end with "Float" as in "Long_Float".

    NOTES

  53. (1) Certain aspects of the predefined entities cannot be completely described in the language itself. For example, although the enumeration type Boolean can be written showing the two enumeration literals False and True, the short-circuit control forms cannot be expressed in the language.
  54. (2) As explained in "Declarative Region", and "The Compilation Process", the declarative region of the package Standard encloses every library unit and consequently the main subprogram; the declaration of every library unit is assumed to occur within this declarative region. Library_items are assumed to be ordered in such a way that there are no forward semantic dependences. However, as explained in "Visibility", the only library units that are visible within a given compilation unit are the library units named by all with_clauses that apply to the given unit, and moreover, within the declarative region of a given library unit, that library unit itself.
  55. (3) If all block_statements of a program are named, then the name of each program unit can always be written as an expanded name starting with Standard (unless Standard is itself hidden). The name of a library unit cannot be a homograph of a name (such as Integer) that is already declared in Standard.
  56. (4) The exception Standard.Numeric_Error is defined in J.6.

Node:A.2, Next:, Previous:A.1, Up:A

The Package Ada


Static Semantics
  1. The following language-defined library package exists: 
  2. package Ada is
    pragma Pure(Ada);
end Ada;
  3. Ada serves as the parent of most of the other language-defined library units; its declaration is empty (except for the pragma Pure).

    Legality Rules
  4. In the standard mode, it is illegal to compile a child of package Ada.

Node:A.3, Next:, Previous:A.2, Up:A

Character Handling

  1. This clause presents the packages related to character processing: an empty pure package Characters and child packages Characters.Handling and Characters.Latin_1. The package Characters.Handling provides classification and conversion functions for Character data, and some simple functions for dealing with Wide_Character data. The child package Characters.Latin_1 declares a set of constants initialized to values of type Character.

Node:A.3.1, Next:, Previous:A.3, Up:A.3

The Package Characters


Static Semantics
  1. The library package Characters has the following declaration: 
  2. package Ada.Characters is
  pragma Pure(Characters);
end Ada.Characters;

Node:A.3.2, Next:, Previous:A.3.1, Up:A.3

The Package Characters.Handling


Static Semantics
  1. The library package Characters.Handling has the following declaration: 
  2. package Ada.Characters.Handling is
  pragma Preelaborate(Handling);

  3.   --  Character classification functions

  4.   function Is_Control           (Item : in Character) return Boolean;
  function Is_Graphic           (Item : in Character) return Boolean;
  function Is_Letter            (Item : in Character) return Boolean;
  function Is_Lower             (Item : in Character) return Boolean;
  function Is_Upper             (Item : in Character) return Boolean;
  function Is_Basic             (Item : in Character) return Boolean;
  function Is_Digit             (Item : in Character) return Boolean;
  function Is_Decimal_Digit     (Item : in Character) return Boolean
    renames Is_Digit;
  function Is_Hexadecimal_Digit (Item : in Character) return Boolean;
  function Is_Alphanumeric      (Item : in Character) return Boolean;
  function Is_Special           (Item : in Character) return Boolean;

  5.   --  Conversion functions for Character and String

  6.   function To_Lower (Item : in Character) return Character;
  function To_Upper (Item : in Character) return Character;
  function To_Basic (Item : in Character) return Character;

  7.   function To_Lower (Item : in String) return String;
  function To_Upper (Item : in String) return String;
  function To_Basic (Item : in String) return String;

  8.   --  Classifications of and conversions
  --  between Character and ISO 646

  9.   subtype ISO_646 is
    Character range Character'Val(0) .. Character'Val(127);

  10.   function Is_ISO_646 (Item : in Character) return Boolean;
  function Is_ISO_646 (Item : in String)    return Boolean;

  11.   function To_ISO_646 (Item       : in Character;
                       Substitute : in ISO_646 := ' ')
    return ISO_646;

  12.   function To_ISO_646 (Item       : in String;
                       Substitute : in ISO_646 := ' ')
    return String;

  13.   --  Classifications of and conversions
  --  between Wide_Character and Character.

  14.  function Is_Character (Item : in Wide_Character) return Boolean;
 function Is_String    (Item : in Wide_String)    return Boolean;

  15.   function To_Character (Item       : in Wide_Character;
                         Substitute : in Character := ' ')
    return Character;

  16.   function To_String (Item       : in Wide_String;
                      Substitute : in Character := ' ')
    return String;

  17.   function To_Wide_Character (Item : in Character)
    return Wide_Character;

  18.   function To_Wide_String (Item : in String) return Wide_String;

  19. end Ada.Characters.Handling;
  20. In the description below for each function that returns a Boolean result, the effect is described in terms of the conditions under which the value True is returned. If these conditions are not met, then the function returns False.
  21. Each of the following classification functions has a formal Character parameter, Item, and returns a Boolean result.
  22. Is_Control 
    True if Item is a control character. A control character is
a character whose position is in one of the ranges 0..31 or
127..159.
  23. Is_Graphic 
    True if Item is a graphic character. A graphic character is
a character whose position is in one of the ranges 32..126 or
160..255.
  24. Is_Letter 
    True if Item is a letter. A letter is a character that is in
one of the ranges 'A'..'Z' or 'a'..'z', or whose position is
in one of the ranges 192..214, 216..246, or 248..255.
  25. Is_Lower 
    True if Item is a lower-case letter. A lower-case letter is
a character that is in the range 'a'..'z', or whose position
is in one of the ranges 223..246 or 248..255.
  26. Is_Upper 
    True if Item is an upper-case letter. An upper-case letter
is a character that is in the range 'A'..'Z' or whose
position is in one of the ranges 192..214 or 216.. 222.
  27. Is_Basic 
    True if Item is a basic letter. A basic letter is a
character that is in one of the ranges 'A'..'Z' and 'a'..'z',
or that is one of the following: an upper- or lower-case AE
diphthong, an upper- or lower-case Icelandic eth, an upper-
or lower-case Icelandic thorn, or a sharp-s.
  28. Is_Digit 
    True if Item is a decimal digit. A decimal digit is a
character in the range '0'..'9'.
  29. Is_Decimal_Digit 
    A renaming of Is_Digit.
  30. Is_Hexadecimal_Digit 
    True if Item is a hexadecimal digit. A hexadecimal digit is
a character that is either a decimal digit or that is in one
of the ranges 'A' .. 'F' or 'a' .. 'f'.
  31. Is_Alphanumeric 
    True if Item is an alphanumeric character. An alphanumeric
character is a character that is either a letter or a decimal
digit.
  32. Is_Special 
    True if Item is a special graphic character. A special
graphic character is a graphic character that is not
alphanumeric.
  33. Each of the names To_Lower, To_Upper, and To_Basic refers to two functions: one that converts from Character to Character, and the other that converts from String to String. The result of each Character-to-Character function is described below, in terms of the conversion applied to Item, its formal Character parameter. The result of each String-to-String conversion is obtained by applying to each element of the function's String parameter the corresponding Character-to-Character conversion; the result is the null String if the value of the formal parameter is the null String. The lower bound of the result String is 1.
  34. To_Lower 
    Returns the corresponding lower-case value for Item if
Is_Upper(Item), and returns Item otherwise.
  35. To_Upper 
    Returns the corresponding upper-case value for Item if
Is_Lower(Item) and Item has an upper-case form, and returns Item
otherwise. The lower case letters sharp-s and y-diaeresis do
not have upper case forms.
  36. To_Basic 
    Returns the letter corresponding to Item but with no
diacritical mark, if Item is a letter but not a basic letter;
returns Item otherwise.
  37. The following set of functions test for membership in the ISO 646 character range, or convert between ISO 646 and Character.
  38. Is_ISO_646 
    The function whose formal parameter, Item, is of type
Character returns True if Item is in the subtype ISO_646.
  39. Is_ISO_646 
    The function whose formal parameter, Item, is of type String
returns True if Is_ISO_646(Item(I)) is True for each I in
Item'Range.
  40. To_ISO_646 
    The function whose first formal parameter, Item, is of type
Character returns Item if Is_ISO_646(Item), and returns the
Substitute ISO_646 character otherwise.
  41. To_ISO_646 
    The function whose first formal parameter, Item, is of type
String returns the String whose Range is 1..Item'Length and
each of whose elements is given by To_ISO_646 of the
corresponding element in Item.
  42. The following set of functions test Wide_Character values for membership in Character, or convert between corresponding characters of Wide_Character and Character.
  43. Is_Character 
    Returns True if Wide_Character'Pos(Item) <=
Character'Pos(Character'Last).
  44. Is_String 
    Returns True if Is_Character(Item(I)) is True for each I in
Item'Range.
  45. To_Character 
    Returns the Character corresponding to Item if
Is_Character(Item), and returns the Substitute Character
otherwise.
  46. To_String 
    Returns the String whose range is 1..Item'Length and each of
whose elements is given by To_Character of the corresponding
element in Item.
  47. To_Wide_Character 
    Returns the Wide_Character X such that Character'Pos(Item) =
Wide_Character'Pos(X).
  48. To_Wide_String 
    Returns the Wide_String whose range is 1..Item'Length and
each of whose elements is given by To_Wide_Character of the
corresponding element in Item.

    Implementation Advice
  49. If an implementation provides a localized definition of Character or Wide_Character, then the effects of the subprograms in Characters.Handling should reflect the localizations. See also 3.5.2.

    NOTES

  50. (5) A basic letter is a letter without a diacritical mark.
  51. (6) Except for the hexadecimal digits, basic letters, and ISO_646 characters, the categories identified in the classification functions form a strict hierarchy:
    1. Control characters
    2. Graphic characters
      1. Alphanumeric characters
        1. Letters
          1. Upper-case letters
          2. Lower-case letters
        1. Decimal digits
      1. Special graphic characters

Node:A.3.3, Next:, Previous:A.3.2, Up:A.3

The Package Characters.Latin_1

  1. The package Characters.Latin_1 declares constants for characters in ISO 8859-1.

    Static Semantics
  2. The library package Characters.Latin_1 has the following declaration: 
  3. package Ada.Characters.Latin_1 is
    pragma Pure(Latin_1);

  4.   -- Control characters:

  5.   NUL                  : constant Character := Character'Val(0);
  SOH                  : constant Character := Character'Val(1);
  STX                  : constant Character := Character'Val(2);
  ETX                  : constant Character := Character'Val(3);
  EOT                  : constant Character := Character'Val(4);
  ENQ                  : constant Character := Character'Val(5);
  ACK                  : constant Character := Character'Val(6);
  BEL                  : constant Character := Character'Val(7);
  BS                   : constant Character := Character'Val(8);
  HT                   : constant Character := Character'Val(9);
  LF                   : constant Character := Character'Val(10);
  VT                   : constant Character := Character'Val(11);
  FF                   : constant Character := Character'Val(12);
  CR                   : constant Character := Character'Val(13);
  SO                   : constant Character := Character'Val(14);
  SI                   : constant Character := Character'Val(15);

  6.   DLE                  : constant Character := Character'Val(16);
  DC1                  : constant Character := Character'Val(17);
  DC2                  : constant Character := Character'Val(18);
  DC3                  : constant Character := Character'Val(19);
  DC4                  : constant Character := Character'Val(20);
  NAK                  : constant Character := Character'Val(21);
  SYN                  : constant Character := Character'Val(22);
  ETB                  : constant Character := Character'Val(23);
  CAN                  : constant Character := Character'Val(24);
  EM                   : constant Character := Character'Val(25);
  SUB                  : constant Character := Character'Val(26);
  ESC                  : constant Character := Character'Val(27);
  FS                   : constant Character := Character'Val(28);
  GS                   : constant Character := Character'Val(29);
  RS                   : constant Character := Character'Val(30);
  US                   : constant Character := Character'Val(31);

  7.   -- ISO 646 graphic characters:

  8.   Space                : constant Character := ' ';
                         -- Character'Val(32)
  Exclamation          : constant Character := '!';
                         -- Character'Val(33)
  Quotation            : constant Character := '"';
                         -- Character'Val(34)
  Number_Sign          : constant Character := '#';
                         -- Character'Val(35)
  Dollar_Sign          : constant Character := '$';
                         -- Character'Val(36)
  Percent_Sign         : constant Character := '%';
                         -- Character'Val(37)
  Ampersand            : constant Character := '&';
                         -- Character'Val(38)
  Apostrophe           : constant Character := ''';
                         -- Character'Val(39)
  Left_Parenthesis     : constant Character := '(';
                         -- Character'Val(40)
  Right_Parenthesis    : constant Character := ')';
                         -- Character'Val(41)
  Asterisk             : constant Character := '*';
                         -- Character'Val(42)
  Plus_Sign            : constant Character := '+';
                         -- Character'Val(43)
  Comma                : constant Character := ',';
                         -- Character'Val(44)
  Hyphen               : constant Character := '-';
                         -- Character'Val(45)
  Minus_Sign           : Character renames Hyphen;
  Full_Stop            : constant Character := '.';
                         -- Character'Val(46)
  Solidus              : constant Character := '/';
                         -- Character'Val(47)

  9.   -- Decimal digits '0' though '9' are at positions 48 through 57

  10.   Colon                : constant Character := ':';
                         -- Character'Val(58)
  Semicolon            : constant Character := ';';
                         -- Character'Val(59)
  Less_Than_Sign       : constant Character := '<';
                         -- Character'Val(60)
  Equals_Sign          : constant Character := '=';
                         -- Character'Val(61)
  Greater_Than_Sign    : constant Character := '>';
                         -- Character'Val(62)
  Question             : constant Character := '?';
                         -- Character'Val(63)
  Commercial_At        : constant Character := '´;
                         -- Character'Val(64)

  11.   -- Letters 'A' through 'Z' are at positions 65 through 90

  12.   Left_Square_Bracket  : constant Character := '[';
                         -- Character'Val(91)
  Reverse_Solidus      : constant Character := '\';
                         -- Character'Val(92)
  Right_Square_Bracket : constant Character := ']';
                         -- Character'Val(93)
  Circumflex           : constant Character := '^';
                         -- Character'Val(94)
  Low_Line             : constant Character := '_';
                         -- Character'Val(95)

  13.   Grave                : constant Character := '`';
                         -- Character'Val(96)
  LC_A                 : constant Character := 'a';
                         -- Character'Val(97)
  LC_B                 : constant Character := 'b';
                         -- Character'Val(98)
  LC_C                 : constant Character := 'c';
                         -- Character'Val(99)
  LC_D                 : constant Character := 'd';
                         -- Character'Val(100)
  LC_E                 : constant Character := 'e';
                         -- Character'Val(101)
  LC_F                 : constant Character := 'f';
                         -- Character'Val(102)
  LC_G                 : constant Character := 'g';
                         -- Character'Val(103)
  LC_H                 : constant Character := 'h';
                         -- Character'Val(104)
  LC_I                 : constant Character := 'i';
                         -- Character'Val(105)
  LC_J                 : constant Character := 'j';
                         -- Character'Val(106)
  LC_K                 : constant Character := 'k';
                         -- Character'Val(107)
  LC_L                 : constant Character := 'l';
                         -- Character'Val(108)
  LC_M                 : constant Character := 'm';
                         -- Character'Val(109)
  LC_N                 : constant Character := 'n';
                         -- Character'Val(110)
  LC_O                 : constant Character := 'o';
                         -- Character'Val(111)

  14.   LC_P                 : constant Character := 'p';
                         -- Character'Val(112)
  LC_Q                 : constant Character := 'q';
                         -- Character'Val(113)
  LC_R                 : constant Character := 'r';
                         -- Character'Val(114)
  LC_S                 : constant Character := 's';
                         -- Character'Val(115)
  LC_T                 : constant Character := 't';
                         -- Character'Val(116)
  LC_U                 : constant Character := 'u';
                         -- Character'Val(117)
  LC_V                 : constant Character := 'v';
                         -- Character'Val(118)
  LC_W                 : constant Character := 'w';
                         -- Character'Val(119)
  LC_X                 : constant Character := 'x';
                         -- Character'Val(120)
  LC_Y                 : constant Character := 'y';
                         -- Character'Val(121)
  LC_Z                 : constant Character := 'z';
                         -- Character'Val(122)
  Left_Curly_Bracket   : constant Character := '{';
                         -- Character'Val(123)
  Vertical_Line        : constant Character := '|';
                         -- Character'Val(124)
  Right_Curly_Bracket  : constant Character := '}';
                         -- Character'Val(125)
  Tilde                : constant Character := '~';
                         -- Character'Val(126)
  DEL                  : constant Character := Character'Val(127);

  15.   -- ISO 6429 control characters:

  16.   IS4                  : Character renames FS;
  IS3                  : Character renames GS;
  IS2                  : Character renames RS;
  IS1                  : Character renames US;

  17.   Reserved_128         : constant Character := Character'Val(128);
  Reserved_129         : constant Character := Character'Val(129);
  BPH                  : constant Character := Character'Val(130);
  NBH                  : constant Character := Character'Val(131);
  Reserved_132         : constant Character := Character'Val(132);
  NEL                  : constant Character := Character'Val(133);
  SSA                  : constant Character := Character'Val(134);
  ESA                  : constant Character := Character'Val(135);
  HTS                  : constant Character := Character'Val(136);
  HTJ                  : constant Character := Character'Val(137);
  VTS                  : constant Character := Character'Val(138);
  PLD                  : constant Character := Character'Val(139);
  PLU                  : constant Character := Character'Val(140);
  RI                   : constant Character := Character'Val(141);
  SS2                  : constant Character := Character'Val(142);
  SS3                  : constant Character := Character'Val(143);

  18.   DCS                  : constant Character := Character'Val(144);
  PU1                  : constant Character := Character'Val(145);
  PU2                  : constant Character := Character'Val(146);
  STS                  : constant Character := Character'Val(147);
  CCH                  : constant Character := Character'Val(148);
  MW                   : constant Character := Character'Val(149);
  SPA                  : constant Character := Character'Val(150);
  EPA                  : constant Character := Character'Val(151);

  19.   SOS                  : constant Character := Character'Val(152);
  Reserved_153         : constant Character := Character'Val(153);
  SCI                  : constant Character := Character'Val(154);
  CSI                  : constant Character := Character'Val(155);
  ST                   : constant Character := Character'Val(156);
  OSC                  : constant Character := Character'Val(157);
  PM                   : constant Character := Character'Val(158);
  APC                  : constant Character := Character'Val(159);

  20.   -- Other graphic characters:

  21.   -- Character positions 160 (16#A0#) .. 175 (16#AF#):
  No_Break_Space              : constant Character := ' ';
                                -- Character'Val(160)
  NBSP                        : Character renames No_Break_Space;
  Inverted_Exclamation        : constant Character :=
    Character'Val(161);
  Cent_Sign                   : constant Character :=
    Character'Val(162);
  Pound_Sign                  : constant Character :=
    Character'Val(163);
  Currency_Sign               : constant Character :=
    Character'Val(164);
  Yen_Sign                    : constant Character :=
    Character'Val(165);
  Broken_Bar                  : constant Character :=
    Character'Val(166);
  Section_Sign                : constant Character :=
    Character'Val(167);
  Diaeresis                   : constant Character :=
    Character'Val(168);
  Copyright_Sign              : constant Character :=
    Character'Val(169);
  Feminine_Ordinal_Indicator  : constant Character :=
    Character'Val(170);
  Left_Angle_Quotation        : constant Character :=
    Character'Val(171);
  Not_Sign                    : constant Character :=
    Character'Val(172);
  Soft_Hyphen                 : constant Character :=
    Character'Val(173);
  Registered_Trade_Mark_Sign  : constant Character :=
    Character'Val(174);
  Macron                      : constant Character :=
    Character'Val(175);

  22.   -- Character positions 176 (16#B0#) .. 191 (16#BF#):
  Degree_Sign                 : constant Character :=
    Character'Val(176);
  Ring_Above                  : Character renames Degree_Sign;
  Plus_Minus_Sign             : constant Character :=
    Character'Val(177);
  Superscript_Two             : constant Character :=
    Character'Val(178);
  Superscript_Three           : constant Character :=
    Character'Val(179);
  Acute                       : constant Character :=
    Character'Val(180);
  Micro_Sign                  : constant Character :=
    Character'Val(181);
  Pilcrow_Sign                : constant Character :=
    Character'Val(182);
  Paragraph_Sign              : Character renames Pilcrow_Sign;
  Middle_Dot                  : constant Character :=
    Character'Val(183);
  Cedilla                     : constant Character :=
    Character'Val(184);
  Superscript_One             : constant Character :=
    Character'Val(185);
  Masculine_Ordinal_Indicator : constant Character :=
    Character'Val(186);
  Right_Angle_Quotation       : constant Character :=
    Character'Val(187);
  Fraction_One_Quarter        : constant Character :=
    Character'Val(188);
  Fraction_One_Half           : constant Character :=
    Character'Val(189);
  Fraction_Three_Quarters     : constant Character :=
    Character'Val(190);
  Inverted_Question           : constant Character :=
    Character'Val(191);

  23.   -- Character positions 192 (16#C0#) .. 207 (16#CF#):
  UC_A_Grave                  : constant Character :=
    Character'Val(192);
  UC_A_Acute                  : constant Character :=
    Character'Val(193);
  UC_A_Circumflex             : constant Character :=
    Character'Val(194);
  UC_A_Tilde                  : constant Character :=
    Character'Val(195);
  UC_A_Diaeresis              : constant Character :=
    Character'Val(196);
  UC_A_Ring                   : constant Character :=
    Character'Val(197);
  UC_AE_Diphthong             : constant Character :=
    Character'Val(198);
  UC_C_Cedilla                : constant Character :=
    Character'Val(199);
  UC_E_Grave                  : constant Character :=
    Character'Val(200);
  UC_E_Acute                  : constant Character :=
    Character'Val(201);
  UC_E_Circumflex             : constant Character :=
    Character'Val(202);
  UC_E_Diaeresis              : constant Character :=
    Character'Val(203);
  UC_I_Grave                  : constant Character :=
    Character'Val(204);
  UC_I_Acute                  : constant Character :=
    Character'Val(205);
  UC_I_Circumflex             : constant Character :=
    Character'Val(206);
  UC_I_Diaeresis              : constant Character :=
    Character'Val(207);

  24.   -- Character positions 208 (16#D0#) .. 223 (16#DF#):
  UC_Icelandic_Eth            : constant Character :=
    Character'Val(208);
  UC_N_Tilde                  : constant Character :=
    Character'Val(209);
  UC_O_Grave                  : constant Character :=
    Character'Val(210);
  UC_O_Acute                  : constant Character :=
    Character'Val(211);
  UC_O_Circumflex             : constant Character :=
    Character'Val(212);
  UC_O_Tilde                  : constant Character :=
    Character'Val(213);
  UC_O_Diaeresis              : constant Character :=
    Character'Val(214);
  Multiplication_Sign         : constant Character :=
    Character'Val(215);
  UC_O_Oblique_Stroke         : constant Character :=
    Character'Val(216);
  UC_U_Grave                  : constant Character :=
    Character'Val(217);
  UC_U_Acute                  : constant Character :=
    Character'Val(218);
  UC_U_Circumflex             : constant Character :=
    Character'Val(219);
  UC_U_Diaeresis              : constant Character :=
    Character'Val(220);
  UC_Y_Acute                  : constant Character :=
    Character'Val(221);
  UC_Icelandic_Thorn          : constant Character :=
    Character'Val(222);
  LC_German_Sharp_S           : constant Character :=
    Character'Val(223);

  25.   -- Character positions 224 (16#E0#) .. 239 (16#EF#):
  LC_A_Grave                  : constant Character :=
    Character'Val(224);
  LC_A_Acute                  : constant Character :=
    Character'Val(225);
  LC_A_Circumflex             : constant Character :=
    Character'Val(226);
  LC_A_Tilde                  : constant Character :=
    Character'Val(227);
  LC_A_Diaeresis              : constant Character :=
    Character'Val(228);
  LC_A_Ring                   : constant Character :=
    Character'Val(229);
  LC_AE_Diphthong             : constant Character :=
    Character'Val(230);
  LC_C_Cedilla                : constant Character :=
    Character'Val(231);
  LC_E_Grave                  : constant Character :=
    Character'Val(232);
  LC_E_Acute                  : constant Character :=
    Character'Val(233);
  LC_E_Circumflex             : constant Character :=
    Character'Val(234);
  LC_E_Diaeresis              : constant Character :=
    Character'Val(235);
  LC_I_Grave                  : constant Character :=
    Character'Val(236);
  LC_I_Acute                  : constant Character :=
    Character'Val(237);
  LC_I_Circumflex             : constant Character :=
    Character'Val(238);
  LC_I_Diaeresis              : constant Character :=
    Character'Val(239);

  26.   -- Character positions 240 (16#F0#) .. 255 (16#FF#):
  LC_Icelandic_Eth            : constant Character :=
    Character'Val(240);
  LC_N_Tilde                  : constant Character :=
    Character'Val(241);
  LC_O_Grave                  : constant Character :=
    Character'Val(242);
  LC_O_Acute                  : constant Character :=
    Character'Val(243);
  LC_O_Circumflex             : constant Character :=
    Character'Val(244);
  LC_O_Tilde                  : constant Character :=
    Character'Val(245);
  LC_O_Diaeresis              : constant Character :=
    Character'Val(246);
  Division_Sign               : constant Character :=
    Character'Val(247);
  LC_O_Oblique_Stroke         : constant Character :=
    Character'Val(248);
  LC_U_Grave                  : constant Character :=
    Character'Val(249);
  LC_U_Acute                  : constant Character :=
    Character'Val(250);
  LC_U_Circumflex             : constant Character :=
    Character'Val(251);
  LC_U_Diaeresis              : constant Character :=
    Character'Val(252);
  LC_Y_Acute                  : constant Character :=
    Character'Val(253);
  LC_Icelandic_Thorn          : constant Character :=
    Character'Val(254);
  LC_Y_Diaeresis              : constant Character :=
    Character'Val(255);
end Ada.Characters.Latin_1;

    Implementation Permissions
  27. An implementation may provide additional packages as children of Ada.Characters, to declare names for the symbols of the local character set or other character sets.

Node:A.4, Next:, Previous:A.3.3, Up:A

String Handling

  1. This clause presents the specifications of the package Strings and several child packages, which provide facilities for dealing with string data. Fixed-length, bounded-length, and unbounded-length strings are supported, for both String and Wide_String. The string-handling subprograms include searches for pattern strings and for characters in program-specified sets, translation (via a character-to-character mapping), and transformation (replacing, inserting, overwriting, and deleting of substrings).

Node:A.4.1, Next:, Previous:A.4, Up:A.4

The Package Strings

  1. The package Strings provides declarations common to the string handling packages.

    Static Semantics
  2. The library package Strings has the following declaration: 
  3. package Ada.Strings is
   pragma Pure(Strings);

  4.    Space      : constant Character      := ' ';
   Wide_Space : constant Wide_Character := ' ';

  5.    Length_Error, Pattern_Error, Index_Error, Translation_Error
     : exception;

  6.    type Alignment  is (Left, Right, Center);
   type Truncation is (Left, Right, Error);
   type Membership is (Inside, Outside);
   type Direction  is (Forward, Backward);
   type Trim_End   is (Left, Right, Both);
end Ada.Strings;

Node:A.4.2, Next:, Previous:A.4.1, Up:A.4

The Package Strings.Maps

  1. The package Strings.Maps defines the types, operations, and other entities needed for character sets and character-to-character mappings.

    Static Semantics
  2. The library package Strings.Maps has the following declaration: 
  3. package Ada.Strings.Maps is
   pragma Preelaborate(Maps);

  4.    -- Representation for a set of character values:
   type Character_Set is private;

  5.    Null_Set : constant Character_Set;

  6.    type Character_Range is
     record
        Low  : Character;
        High : Character;
     end record;
   -- Represents Character range Low..High

  7.    type Character_Ranges is
     array (Positive range <>) of Character_Range;

  8.    function To_Set (Ranges : in Character_Ranges)
     return Character_Set;

  9.    function To_Set (Span : in Character_Range)
     return Character_Set;

  10.    function To_Ranges (Set : in Character_Set)
     return Character_Ranges;

  11.    function "=" (Left, Right : in Character_Set) return Boolean;

  12.    function "not" (Right : in Character_Set)
     return Character_Set;
   function "and" (Left, Right : in Character_Set)
     return Character_Set;
   function "or"  (Left, Right : in Character_Set)
     return Character_Set;
   function "xor" (Left, Right : in Character_Set)
     return Character_Set;
   function "-"   (Left, Right : in Character_Set)
     return Character_Set;

  13.    function Is_In (Element : in Character;
                   Set     : in Character_Set)
      return Boolean;

  14.    function Is_Subset (Elements : in Character_Set;
                       Set      : in Character_Set)
      return Boolean;

  15.    function "<=" (Left  : in Character_Set;
                  Right : in Character_Set)
      return Boolean renames Is_Subset;

  16.    -- Alternative representation for a set of character values:
   subtype Character_Sequence is String;

  17.    function To_Set (Sequence : in Character_Sequence)
     return Character_Set;

  18.    function To_Set (Singleton : in Character) return Character_Set;

  19.    function To_Sequence (Set : in Character_Set)
     return Character_Sequence;

  20.    -- Representation for a character to character mapping:
   type Character_Mapping is private;

  21.    function Value (Map     : in Character_Mapping;
                   Element : in Character)
      return Character;

  22.    Identity : constant Character_Mapping;

  23.    function To_Mapping (From, To : in Character_Sequence)
     return Character_Mapping;

  24.    function To_Domain (Map : in Character_Mapping)
     return Character_Sequence;
   function To_Range  (Map : in Character_Mapping)
     return Character_Sequence;

  25.    type Character_Mapping_Function is
      access function (From : in Character) return Character;

  26. private
   ... -- not specified by the language
end Ada.Strings.Maps;
  27. An object of type Character_Set represents a set of characters.
  28. Null_Set represents the set containing no characters.
  29. An object Obj of type Character_Range represents the set of characters in the range Obj.Low .. Obj.High.
  30. An object Obj of type Character_Ranges represents the union of the sets corresponding to Obj(I) for I in Obj'Range. 
  31. function To_Set (Ranges : in Character_Ranges) return Character_Set;
    1. If Ranges'Length=0 then Null_Set is returned; otherwise the returned value represents the set corresponding to Ranges. 
  1. function To_Set (Span : in Character_Range) return Character_Set;
    1. The returned value represents the set containing each character in Span. 
  1. function To_Ranges (Set : in Character_Set) return Character_Ranges;
    1. If Set = Null_Set then an empty Character_Ranges array is returned; otherwise the shortest array of contiguous ranges of Character values in Set, in increasing order of Low, is returned. 
  1. function "=" (Left, Right : in Character_Set) return Boolean;
    1. The function "=" returns True if Left and Right represent identical sets, and False otherwise.
  1. Each of the logical operators "not", "and", "or", and "xor" returns a Character_Set value that represents the set obtained by applying the corresponding operation to the set(s) represented by the parameter(s) of the operator. "-"(Left, Right) is equivalent to "and"(Left, "not"(Right)). 
  2. function Is_In (Element : in Character;
                Set     : in Character_Set);
   return Boolean;
    1. Is_In returns True if Element is in Set, and False otherwise. 
  1. function Is_Subset (Elements : in Character_Set;
                    Set      : in Character_Set)
   return Boolean;
    1. Is_Subset returns True if Elements is a subset of Set, and False otherwise. 
  1. subtype Character_Sequence is String;
    1. The Character_Sequence subtype is used to portray a set of character values and also to identify the domain and range of a character mapping. 
  1. function To_Set (Sequence  : in Character_Sequence)
  return Character_Set;

function To_Set (Singleton : in Character)
  return Character_Set;
    1. Sequence portrays the set of character values that it explicitly contains (ignoring duplicates). Singleton portrays the set comprising a single Character. Each of the To_Set functions returns a Character_Set value that represents the set portrayed by Sequence or Singleton. 
  1. function To_Sequence (Set : in Character_Set)
  return Character_Sequence;
    1. The function To_Sequence returns a Character_Sequence value containing each of the characters in the set represented by Set, in ascending order with no duplicates. 
  1. type Character_Mapping is private;
    1. An object of type Character_Mapping represents a Character-to-Character mapping. 
  1. function Value (Map     : in Character_Mapping;
                Element : in Character)
   return Character;
    1. The function Value returns the Character value to which Element maps with respect to the mapping represented by Map.
  1. A character C matches a pattern character P with respect to a given Character_Mapping value Map if Value(Map, C) = P. A string S matches a pattern string P with respect to a given Character_Mapping if their lengths are the same and if each character in S matches its corresponding character in the pattern string P.
  2. String handling subprograms that deal with character mappings have parameters whose type is Character_Mapping. 
  3. Identity : constant Character_Mapping;
    1. Identity maps each Character to itself. 
  1. function To_Mapping (From, To : in Character_Sequence)
  return Character_Mapping;
    1. To_Mapping produces a Character_Mapping such that each element of From maps to the corresponding element of To, and each other character maps to itself. If From'Length /= To'Length, or if some character is repeated in From, then Translation_Error is propagated. 
  1. function To_Domain (Map : in Character_Mapping)
  return Character_Sequence;
    1. To_Domain returns the shortest Character_Sequence value D such that each character not in D maps to itself, and such that the characters in D are in ascending order. The lower bound of D is 1. 
  1. function To_Range (Map : in Character_Mapping)
  return Character_Sequence;
    1. To_Range returns the Character_Sequence value R, with lower bound 1 and upper bound Map'Length, such that if D = To_Domain(Map) then D(I) maps to R(I) for each I in D'Range.
  1. An object F of type Character_Mapping_Function maps a Character value C to the Character value F.all(C), which is said to match C with respect to mapping function F.

    NOTES

  2. (7) Character_Mapping and Character_Mapping_Function are used both for character equivalence mappings in the search subprograms (such as for case insensitivity) and as transformational mappings in the Translate subprograms.
  3. (8) To_Domain(Identity) and To_Range(Identity) each returns the null string.

    Examples
  4. To_Mapping("ABCD", "ZZAB") returns a Character_Mapping that maps 'A' and 'B' to 'Z', 'C' to 'A', 'D' to 'B', and each other Character to itself.

Node:A.4.3, Next:, Previous:A.4.2, Up:A.4

Fixed-Length String Handling

  1. The language-defined package Strings.Fixed provides string-handling subprograms for fixed-length strings; that is, for values of type Standard.String. Several of these subprograms are procedures that modify the contents of a String that is passed as an out or an in out parameter; each has additional parameters to control the effect when the logical length of the result differs from the parameter's length.
  2. For each function that returns a String, the lower bound of the returned value is 1.
  3. The basic model embodied in the package is that a fixed-length string comprises significant characters and possibly padding (with space characters) on either or both ends. When a shorter string is copied to a longer string, padding is inserted, and when a longer string is copied to a shorter one, padding is stripped. The Move procedure in Strings.Fixed, which takes a String as an out parameter, allows the programmer to control these effects. Similar control is provided by the string transformation procedures.

    Static Semantics
  4. The library package Strings.Fixed has the following declaration: 
  5. with Ada.Strings.Maps;
package Ada.Strings.Fixed is
   pragma Preelaborate(Fixed);

  6.    -- "Copy" procedure for strings of possibly different lengths

  7.    procedure Move (Source  : in  String;
                   Target  : out String;
                   Drop    : in  Truncation := Error;
                   Justify : in  Alignment  := Left;
                   Pad     : in  Character  := Space);

  8.    -- Search subprograms

  9.    function Index (Source   : in String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

  10.    function Index (Source   : in String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

  11.    function Index (Source : in String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward)
      return Natural;

  12.    function Index_Non_Blank (Source : in String;
                             Going  : in Direction := Forward)
      return Natural;

  13.    function Count (Source   : in String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                 := Maps.Identity)
      return Natural;

  14.    function Count (Source   : in String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

  15.    function Count (Source   : in String;
                   Set      : in Maps.Character_Set)
      return Natural;

  16.    procedure Find_Token (Source : in String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

  17.    -- String translation subprograms

  18.    function Translate (Source  : in String;
                       Mapping : in Maps.Character_Mapping)
      return String;

  19.    procedure Translate (Source  : in out String;
                            Mapping : in Maps.Character_Mapping);

  20.    function Translate (Source  : in String;
                       Mapping : in Maps.Character_Mapping_Function)
      return String;

  21.    procedure Translate
     (Source  : in out String;
      Mapping : in Maps.Character_Mapping_Function);

  22.    -- String transformation subprograms

  23.    function Replace_Slice (Source   : in String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return String;

  24.    procedure Replace_Slice (Source   : in out String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String;
                            Drop     : in Truncation := Error;
                            Justify  : in Alignment  := Left;
                            Pad      : in Character  := Space);

  25.    function Insert (Source   : in String;
                    Before   : in Positive;
                    New_Item : in String)
      return String;

  26.    procedure Insert (Source   : in out String;
                     Before   : in Positive;
                     New_Item : in String;
                     Drop     : in Truncation := Error);

  27.    function Overwrite (Source   : in String;
                       Position : in Positive;
                       New_Item : in String)
      return String;

  28.    procedure Overwrite (Source   : in out String;
                        Position : in Positive;
                        New_Item : in String;
                        Drop     : in Truncation := Right);

  29.    function Delete (Source  : in String;
                    From    : in Positive;
                    Through : in Natural)
      return String;

  30.    procedure Delete (Source  : in out String;
                     From    : in Positive;
                     Through : in Natural;
                     Justify : in Alignment := Left;
                     Pad     : in Character := Space);

  31.    -- String selector subprograms

   function Trim (Source : in String;
                  Side   : in Trim_End)
      return String;

  32.    procedure Trim (Source  : in out String;
                   Side    : in Trim_End;
                   Justify : in Alignment := Left;
                   Pad     : in Character := Space);

  33.    function Trim (Source : in String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return String;

  34.    procedure Trim (Source  : in out String;
                   Left    : in Maps.Character_Set;
                   Right   : in Maps.Character_Set;
                   Justify : in Alignment := Strings.Left;
                   Pad     : in Character := Space);

  35.    function Head (Source : in String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return String;

  36.    procedure Head (Source  : in out String;
                   Count   : in Natural;
                   Justify : in Alignment := Left;
                   Pad     : in Character := Space);

  37.    function Tail (Source : in String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return String;

  38.    procedure Tail (Source  : in out String;
                   Count   : in Natural;
                   Justify : in Alignment := Left;
                   Pad     : in Character := Space);

  39.    --String constructor functions

  40.    function "*" (Left  : in Natural;
                 Right : in Character) return String;

  41.    function "*" (Left  : in Natural;
                 Right : in String) return String;

  42. end Ada.Strings.Fixed;
  43. The effects of the above subprograms are as follows. 
  44. procedure Move (Source  : in  String;
                Target  : out String;
                Drop    : in  Truncation := Error;
                Justify : in  Alignment  := Left;
                Pad     : in  Character  := Space);
    1. The Move procedure copies characters from Source to Target. If Source has the same length as Target, then the effect is to assign Source to Target. If Source is shorter than Target then:
      1. If Justify=Left, then Source is copied into the first Source'Length characters of Target.
      2. If Justify=Right, then Source is copied into the last Source'Length characters of Target.
      3. If Justify=Center, then Source is copied into the middle Source'Length characters of Target. In this case, if the difference in length between Target and Source is odd, then the extra Pad character is on the right.
      4. Pad is copied to each Target character not otherwise assigned.
    1. If Source is longer than Target, then the effect is based on Drop.
      1. If Drop=Left, then the rightmost Target'Length characters of Source are copied into Target.
      2. If Drop=Right, then the leftmost Target'Length characters of Source are copied into Target.
      3. If Drop=Error, then the effect depends on the value of the Justify parameter and also on whether any characters in Source other than Pad would fail to be copied:
        1. If Justify=Left, and if each of the rightmost Source'Length-Target'Length characters in Source is Pad, then the leftmost Target'Length characters of Source are copied to Target.
        2. If Justify=Right, and if each of the leftmost Source'Length-Target'Length characters in Source is Pad, then the rightmost Target'Length characters of Source are copied to Target.
        3. Otherwise, Length_Error is propagated. 
  1. function Index (Source   : in String;
                Pattern  : in String;
                Going    : in Direction := Forward;
                Mapping  : in Maps.Character_Mapping
                              := Maps.Identity)
   return Natural;

function Index (Source   : in String;
                Pattern  : in String;
                Going    : in Direction := Forward;
                Mapping  : in Maps.Character_Mapping_Function)
   return Natural;
    1. Each Index function searches for a slice of Source, with length Pattern'Length, that matches Pattern with respect to Mapping; the parameter Going indicates the direction of the lookup. If Going = Forward, then Index returns the smallest index I such that the slice of Source starting at I matches Pattern. If Going = Backward, then Index returns the largest index I such that the slice of Source starting at I matches Pattern. If there is no such slice, then 0 is returned. If Pattern is the null string then Pattern_Error is 
  1. function Index (Source : in String;
                Set    : in Maps.Character_Set;
                Test   : in Membership := Inside;
                Going  : in Direction  := Forward)
   return Natural;
    1. Index searches for the first or last occurrence of any of a set of characters (when Test=Inside), or any of the complement of a set of characters (when Test=Outside). It returns the smallest index I (if Going=Forward) or the largest index I (if Going=Backward) such that Source(I) satisfies the Test condition with respect to Set; it returns 0 if there is no such Character in Source. 
  1. function Index_Non_Blank (Source : in String;
                          Going  : in Direction := Forward)
   return Natural;
    1. Returns Index(Source, Maps.To_Set(Space), Outside, Going) 
  1. function Count (Source   : in String;
                Pattern  : in String;
                Mapping  : in Maps.Character_Mapping
                             := Maps.Identity)
   return Natural;

function Count (Source   : in String;
                Pattern  : in String;
                Mapping  : in Maps.Character_Mapping_Function)
   return Natural;
    1. Returns the maximum number of nonoverlapping slices of Source that match Pattern with respect to Mapping. If Pattern is the null string then Pattern_Error is propagated. 
  1. function Count (Source   : in String;
                Set      : in Maps.Character_Set)
   return Natural;
    1. Returns the number of occurrences in Source of characters that are in Set. 
  1. procedure Find_Token (Source : in String;
                      Set    : in Maps.Character_Set;
                      Test   : in Membership;
                      First  : out Positive;
                      Last   : out Natural);
    1. Find_Token returns in First and Last the indices of the beginning and end of the first slice of Source all of whose elements satisfy the Test condition, and such that the elements (if any) immediately before and after the slice do not satisfy the Test condition. If no such slice exists, then the value returned for Last is zero, and the value returned for First is Source'First. 
  1. function Translate (Source  : in String;
                    Mapping : in Maps.Character_Mapping)
   return String;

function Translate (Source  : in String;
                    Mapping : in Maps.Character_Mapping_Function)
   return String;
    1. Returns the string S whose length is Source'Length and such that S(I) is the character to which Mapping maps the corresponding element of Source, for I in 1..Source'Length. 
  1. procedure Translate (Source  : in out String;
                     Mapping : in Maps.Character_Mapping);

procedure Translate (Source  : in out String;
                     Mapping : in Maps.Character_Mapping_Function);
    1. Equivalent to Source := Translate(Source, Mapping). 
  1. function Replace_Slice (Source   : in String;
                        Low      : in Positive;
                        High     : in Natural;
                        By       : in String)
   return String;
    1. If Low > Source'Last+1, or High < Source'First-1, then Index_Error is propagated. Otherwise, if High >= Low then the returned string comprises Source(Source'First..Low-1) & By & Source(High+1..Source'Last), and if High < Low then the returned string is Insert(Source, Before=>Low, New_Item=>By). 
  1. procedure Replace_Slice (Source   : in out String;
                         Low      : in Positive;
                         High     : in Natural;
                         By       : in String;
                         Drop     : in Truncation := Error;
                         Justify  : in Alignment  := Left;
                         Pad      : in Character  := Space);
    1. Equivalent to Move(Replace_Slice(Source, Low, High, By), Source, Drop, Justify, Pad). 
  1. function Insert (Source   : in String;
                 Before   : in Positive;
                 New_Item : in String)
   return String;
      Propagates Index_Error if Before is not in Source'First .. Source'Last+1; otherwise returns Source(Source'First..Before-1) & New_Item & Source(Before..Source'Last), but with lower bound 1. 
  1. procedure Insert (Source   : in out String;
                  Before   : in Positive;
                  New_Item : in String;
                  Drop     : in Truncation := Error);
    1. Equivalent to Move(Insert(Source, Before, New_Item), Source, Drop). 
  1. function Overwrite (Source   : in String;
                    Position : in Positive;
                    New_Item : in String)
   return String;
    1. Propagates Index_Error if Position is not in Source'First .. Source'Last+1; otherwise returns the string obtained from Source by consecutively replacing characters starting at Position with corresponding characters from New_Item. If the end of Source is reached before the characters in New_Item are exhausted, the remaining characters from New_Item are appended to the string. 
  1. procedure Overwrite (Source   : in out String;
                     Position : in Positive;
                     New_Item : in String;
                     Drop     : in Truncation := Right);
    1. Equivalent to Move(Overwrite(Source, Position, New_Item), Source, Drop). 
  1. function Delete (Source  : in String;
                 From    : in Positive;
                 Through : in Natural)
   return String;
    1. If From <= Through, the returned string is Replace_Slice(Source, From, Through, ""), otherwise it is Source. 
  1. procedure Delete (Source  : in out String;
                  From    : in Positive;
                  Through : in Natural;
                  Justify : in Alignment := Left;
                  Pad     : in Character := Space);
    1. Equivalent to Move(Delete(Source, From, Through), Source, Justify => Justify, Pad => Pad). 
  1. function Trim (Source : in String;
               Side   : in Trim_End)
  return String;
    1. Returns the string obtained by removing from Source all leading Space characters (if Side = Left), all trailing Space characters (if Side = Right), or all leading and trailing Space characters (if Side = Both). 
  1. procedure Trim (Source  : in out String;
                Side    : in Trim_End;
                Justify : in Alignment := Left;
                Pad     : in Character := Space);
    1. Equivalent to Move(Trim(Source, Side), Source, Justify=>Justify, Pad=>Pad). 
  1. function Trim (Source : in String;
               Left   : in Maps.Character_Set;
               Right  : in Maps.Character_Set)
   return String;
    1. Returns the string obtained by removing from Source all leading characters in Left and all trailing characters in Right. 
  1. procedure Trim (Source  : in out String;
                Left    : in Maps.Character_Set;
                Right   : in Maps.Character_Set;
                Justify : in Alignment := Strings.Left;
                Pad     : in Character := Space);
    1. Equivalent to Move(Trim(Source, Left, Right), Source, Justify => Justify, Pad=>Pad). 
  1. function Head (Source : in String;
               Count  : in Natural;
               Pad    : in Character := Space)
   return String;
    1. Returns a string of length Count. If Count <= Source'Length, the string comprises the first Count characters of Source. Otherwise its contents are Source concatenated with Count-Source'Length Pad characters. 
  1. procedure Head (Source  : in out String;
                Count   : in Natural;
                Justify : in Alignment := Left;
                Pad     : in Character := Space);
    1. Equivalent to Move(Head(Source, Count, Pad), Source, Drop=>Error, Justify=>Justify, Pad=>Pad). 
  1. function Tail (Source : in String;
               Count  : in Natural;
               Pad    : in Character := Space)
   return String;
    1. Returns a string of length Count. If Count <= Source'Length, the string comprises the last Count characters of Source. Otherwise its contents are Count-Source'Length Pad characters concatenated with Source. 
  1. procedure Tail (Source  : in out String;
                Count   : in Natural;
                Justify : in Alignment := Left;
                Pad     : in Character := Space);
    1. Equivalent to Move(Tail(Source, Count, Pad), Source, Drop=>Error, Justify=>Justify, Pad=>Pad). 
  1. function "*" (Left  : in Natural;
              Right : in Character) return String;

function "*" (Left  : in Natural;
              Right : in String) return String;
    1. These functions replicate a character or string a specified number of times. The first function returns a string whose length is Left and each of whose elements is Right. The second function returns a string whose length is Left*Right'Length and whose value is the null string if Left = 0 and is (Left-1)*Right & Right otherwise.

    NOTES

  1. (9) In the Index and Count functions taking Pattern and Mapping parameters, the actual String parameter passed to Pattern should comprise characters occurring as target characters of the mapping. Otherwise the pattern will not match.
  2. (10) In the Insert subprograms, inserting at the end of a string is obtained by passing Source'Last+1 as the Before parameter.
  3. (11) If a null Character_Mapping_Function is passed to any of the string handling subprograms, Constraint_Error is propagated.

Node:A.4.4, Next:, Previous:A.4.3, Up:A.4

Bounded-Length String Handling

  1. The language-defined package Strings.Bounded provides a generic package each of whose instances yields a private type Bounded_String and a set of operations. An object of a particular Bounded_String type represents a String whose low bound is 1 and whose length can vary conceptually between 0 and a maximum size established at the generic instantiation. The subprograms for fixed-length string handling are either overloaded directly for Bounded_String, or are modified as needed to reflect the variability in length. Additionally, since the Bounded_String type is private, appropriate constructor and selector operations are provided.

    Static Semantics
  2. The library package Strings.Bounded has the following declaration: 
  3. with Ada.Strings.Maps;
package Ada.Strings.Bounded is
   pragma Preelaborate(Bounded);

  4.    generic
      Max   : Positive;    -- Maximum length of a Bounded_String
   package Generic_Bounded_Length is

  5.       Max_Length : constant Positive := Max;

  6.       type Bounded_String is private;

  7.       Null_Bounded_String : constant Bounded_String;

  8.       subtype Length_Range is Natural range 0 .. Max_Length;

  9.       function Length (Source : in Bounded_String)
        return Length_Range;

  10.       -- Conversion, Concatenation, and Selection functions

  11.       function To_Bounded_String (Source : in String;
                                  Drop   : in Truncation := Error)
         return Bounded_String;

  12.       function To_String (Source : in Bounded_String) return String;

  13.       function Append (Left, Right : in Bounded_String;
                       Drop        : in Truncation  := Error)
         return Bounded_String;

  14.       function Append (Left  : in Bounded_String;
                       Right : in String;
                       Drop  : in Truncation := Error)
         return Bounded_String;

  15.       function Append (Left  : in String;
                       Right : in Bounded_String;
                       Drop  : in Truncation := Error)
         return Bounded_String;

  16.       function Append (Left  : in Bounded_String;
                       Right : in Character;
                       Drop  : in Truncation := Error)
         return Bounded_String;

  17.       function Append (Left  : in Character;
                       Right : in Bounded_String;
                       Drop  : in Truncation := Error)
         return Bounded_String;

  18.       procedure Append (Source   : in out Bounded_String;
                        New_Item : in Bounded_String;
                        Drop     : in Truncation  := Error);

  19.       procedure Append (Source   : in out Bounded_String;
                        New_Item : in String;
                        Drop     : in Truncation  := Error);

  20.       procedure Append (Source   : in out Bounded_String;
                        New_Item : in Character;
                        Drop     : in Truncation  := Error);

  21.       function "&" (Left, Right : in Bounded_String)
         return Bounded_String;

  22.       function "&" (Left : in Bounded_String; Right : in String)
         return Bounded_String;

  23.       function "&" (Left : in String; Right : in Bounded_String)
         return Bounded_String;

  24.       function "&" (Left : in Bounded_String; Right : in Character)
         return Bounded_String;

  25.       function "&" (Left : in Character; Right : in Bounded_String)
         return Bounded_String;

  26.       function Element (Source : in Bounded_String;
                        Index  : in Positive)
         return Character;

  27.       procedure Replace_Element (Source : in out Bounded_String;
                                 Index  : in Positive;
                                 By     : in Character);

  28.       function Slice (Source : in Bounded_String;
                      Low    : in Positive;
                      High   : in Natural)
         return String;

  29.       function "="  (Left, Right : in Bounded_String) return Boolean;
      function "="  (Left : in Bounded_String; Right : in String)
        return Boolean;

  30.       function "="  (Left : in String; Right : in Bounded_String)
        return Boolean;

  31.       function "<"  (Left, Right : in Bounded_String) return Boolean;

  32.       function "<"  (Left : in Bounded_String; Right : in String)
        return Boolean;

  33.       function "<"  (Left : in String; Right : in Bounded_String)
        return Boolean;

  34.       function "<=" (Left, Right : in Bounded_String) return Boolean;

  35.       function "<="  (Left : in Bounded_String; Right : in String)
        return Boolean;

  36.       function "<="  (Left : in String; Right : in Bounded_String)
        return Boolean;

  37.       function ">"  (Left, Right : in Bounded_String) return Boolean;

  38.       function ">"  (Left : in Bounded_String; Right : in String)
        return Boolean;

  39.       function ">"  (Left : in String; Right : in Bounded_String)
        return Boolean;

  40.       function ">=" (Left, Right : in Bounded_String) return Boolean;

  41.       function ">="  (Left : in Bounded_String; Right : in String)
        return Boolean;

  42.       function ">="  (Left : in String; Right : in Bounded_String)
        return Boolean;

  43.       -- Search functions

  44.       function Index (Source   : in Bounded_String;
                      Pattern  : in String;
                      Going    : in Direction := Forward;
                      Mapping  : in Maps.Character_Mapping
                                 := Maps.Identity)
         return Natural;

  45.       function Index (Source   : in Bounded_String;
                      Pattern  : in String;
                      Going    : in Direction := Forward;
                      Mapping  : in Maps.Character_Mapping_Function)
         return Natural;

  46.       function Index (Source : in Bounded_String;
                      Set    : in Maps.Character_Set;
                      Test   : in Membership := Inside;
                      Going  : in Direction  := Forward)
         return Natural;

  47.       function Index_Non_Blank (Source : in Bounded_String;
                                Going  : in Direction := Forward)
         return Natural;

  48.       function Count (Source   : in Bounded_String;
                      Pattern  : in String;
                      Mapping  : in Maps.Character_Mapping
                                   := Maps.Identity)
         return Natural;

  49.       function Count (Source   : in Bounded_String;
                      Pattern  : in String;
                      Mapping  : in Maps.Character_Mapping_Function)
         return Natural;

  50.       function Count (Source   : in Bounded_String;
                      Set      : in Maps.Character_Set)
         return Natural;

  51.       procedure Find_Token (Source : in Bounded_String;
                            Set    : in Maps.Character_Set;
                            Test   : in Membership;
                            First  : out Positive;
                            Last   : out Natural);

  52.       -- String translation subprograms

  53.       function Translate (Source  : in Bounded_String;
                          Mapping : in Maps.Character_Mapping)
         return Bounded_String;

  54.       procedure Translate (Source  : in out Bounded_String;
                           Mapping : in Maps.Character_Mapping);

  55.       function Translate
        (Source  : in Bounded_String;
         Mapping : in Maps.Character_Mapping_Function)
         return Bounded_String;

  56.       procedure Translate
        (Source  : in out Bounded_String;
         Mapping : in Maps.Character_Mapping_Function);

  57.       -- String transformation subprograms

  58.       function Replace_Slice (Source   : in Bounded_String;
                              Low      : in Positive;
                              High     : in Natural;
                              By       : in String;
                              Drop     : in Truncation := Error)
         return Bounded_String;

  59.       procedure Replace_Slice (Source   : in out Bounded_String;
                               Low      : in Positive;
                               High     : in Natural;
                               By       : in String;
                               Drop     : in Truncation := Error);

  60.       function Insert (Source   : in Bounded_String;
                       Before   : in Positive;
                       New_Item : in String;
                       Drop     : in Truncation := Error)
         return Bounded_String;

  61.       procedure Insert (Source   : in out Bounded_String;
                        Before   : in Positive;
                        New_Item : in String;
                        Drop     : in Truncation := Error);

  62.       function Overwrite (Source    : in Bounded_String;
                          Position  : in Positive;
                          New_Item  : in String;
                          Drop      : in Truncation := Error)
         return Bounded_String;

  63.       procedure Overwrite (Source    : in out Bounded_String;
                           Position  : in Positive;
                           New_Item  : in String;
                           Drop      : in Truncation := Error);

  64.       function Delete (Source  : in Bounded_String;
                       From    : in Positive;
                       Through : in Natural)
         return Bounded_String;

  65.       procedure Delete (Source  : in out Bounded_String;
                        From    : in Positive;
                        Through : in Natural);

  66.       -- String selector subprograms

  67.       function Trim (Source : in Bounded_String;
                     Side   : in Trim_End)
         return Bounded_String;

      procedure Trim (Source : in out Bounded_String;
                      Side   : in Trim_End);

  68.       function Trim (Source : in Bounded_String;
                     Left   : in Maps.Character_Set;
                     Right  : in Maps.Character_Set)
         return Bounded_String;

  69.       procedure Trim (Source : in out Bounded_String;
                      Left   : in Maps.Character_Set;
                      Right  : in Maps.Character_Set);

  70.       function Head (Source : in Bounded_String;
                     Count  : in Natural;
                     Pad    : in Character  := Space;
                     Drop   : in Truncation := Error)
         return Bounded_String;

  71.       procedure Head (Source : in out Bounded_String;
                      Count  : in Natural;
                      Pad    : in Character  := Space;
                      Drop   : in Truncation := Error);

  72.       function Tail (Source : in Bounded_String;
                     Count  : in Natural;
                     Pad    : in Character  := Space;
                     Drop   : in Truncation := Error)
         return Bounded_String;

  73.       procedure Tail (Source : in out Bounded_String;
                      Count  : in Natural;
                      Pad    : in Character  := Space;
                      Drop   : in Truncation := Error);

  74.       -- String constructor subprograms

  75.       function "*" (Left  : in Natural;
                    Right : in Character)
         return Bounded_String;

  76.       function "*" (Left  : in Natural;
                    Right : in String)
         return Bounded_String;

  77.       function "*" (Left  : in Natural;
                    Right : in Bounded_String)
         return Bounded_String;

  78.       function Replicate (Count : in Natural;
                          Item  : in Character;
                          Drop  : in Truncation := Error)
         return Bounded_String;

  79.       function Replicate (Count : in Natural;
                          Item  : in String;
                          Drop  : in Truncation := Error)
         return Bounded_String;

  80.       function Replicate (Count : in Natural;
                          Item  : in Bounded_String;
                          Drop  : in Truncation := Error)
         return Bounded_String;

  81.    private
       ... -- not specified by the language
   end Generic_Bounded_Length;

  82. end Ada.Strings.Bounded;
  83. Null_Bounded_String represents the null string. If an object of type Bounded_String is not otherwise initialized, it will be initialized to the same value as Null_Bounded_String. 
  84. function Length (Source : in Bounded_String) return Length_Range;
    1. The Length function returns the length of the string represented by Source. 
  1. function To_Bounded_String (Source : in String;
                            Drop   : in Truncation := Error)
   return Bounded_String;
    1. If Source'Length <= Max_Length then this function returns a Bounded_String that represents Source. Otherwise the effect depends on the value of Drop:
      1. If Drop=Left, then the result is a Bounded_String that represents the string comprising the rightmost Max_Length characters of Source.
      2. If Drop=Right, then the result is a Bounded_String that represents the string comprising the leftmost Max_Length characters of Source.
      3. If Drop=Error, then Strings.Length_Error is propagated. 
  1. function To_String (Source : in Bounded_String) return String;
    1. To_String returns the String value with lower bound 1 represented by Source. If B is a Bounded_String, then B = To_Bounded_String(To_String(B)).
  1. Each of the Append functions returns a Bounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Bounded_String to the concatenation result string, with Drop as provided to the Append function.
  2. Each of the procedures Append(Source, New_Item, Drop) has the same effect as the corresponding assignment Source := Append(Source, New_Item, Drop).
  3. Each of the "&" functions has the same effect as the corresponding Append function, with Error as the Drop parameter. 
  4. function Element (Source : in Bounded_String;
                  Index  : in Positive)
   return Character;
    1. Returns the character at position Index in the string represented by Source; propagates Index_Error if Index > Length(Source). 
  1. procedure Replace_Element (Source : in out Bounded_String;
                           Index  : in Positive;
                           By     : in Character);
    1. Updates Source such that the character at position Index in the string represented by Source is By; propagates Index_Error if Index > Length(Source). 
  1. function Slice (Source : in Bounded_String;
                Low    : in Positive;
                High   : in Natural)
   return String;
    1. Returns the slice at positions Low through High in the string represented by Source; propagates Index_Error if Low > Length(Source)+1.
  1. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by the two parameters.
  2. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Bounded_String parameter.
  3. Each of the Translate subprograms, when applied to a Bounded_String, has an analogous effect to the corresponding subprogram in Strings.Fixed. For the Translate function, the translation is applied to the string represented by the Bounded_String parameter, and the result is converted (via To_Bounded_String) to a Bounded_String. For the Translate procedure, the string represented by the Bounded_String parameter after the translation is given by the Translate function for fixed-length strings applied to the string represented by the original value of the parameter.
  4. Each of the transformation subprograms (Replace_Slice, Insert, Overwrite, Delete), selector subprograms (Trim, Head, Tail), and constructor functions ("*") has an effect based on its corresponding subprogram in Strings.Fixed, and Replicate is based on Fixed."*". For each of these subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Bounded_String parameter. To_Bounded_String is applied the result string, with Drop (or Error in the case of Generic_Bounded_Length."*") determining the effect when the string length exceeds Max_Length.

    Implementation Advice
  5. Bounded string objects should not be implemented by implicit pointers and dynamic allocation.

Node:A.4.5, Next:, Previous:A.4.4, Up:A.4

Unbounded-Length String Handling

  1. The language-defined package Strings.Unbounded provides a private type Unbounded_String and a set of operations. An object of type Unbounded_String represents a String whose low bound is 1 and whose length can vary conceptually between 0 and Natural'Last. The subprograms for fixed-length string handling are either overloaded directly for Unbounded_String, or are modified as needed to reflect the flexibility in length. Since the Unbounded_String type is private, relevant constructor and selector operations are provided.

    Static Semantics
  2. The library package Strings.Unbounded has the following declaration: 
  3. with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

  4.    type Unbounded_String is private;

  5.    Null_Unbounded_String : constant Unbounded_String;

  6.    function Length (Source : in Unbounded_String) return Natural;

  7.    type String_Access is access all String;
   procedure Free (X : in out String_Access);

  8.    -- Conversion, Concatenation, and Selection functions

  9.    function To_Unbounded_String (Source : in String)
      return Unbounded_String;

  10.    function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

  11.    function To_String (Source : in Unbounded_String) return String;

  12.    procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

  13.    procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

  14.    procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

  15.    function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

  16.    function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

  17.    function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

  18.    function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

  19.    function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

  20.    function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

  21.    procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

  22.    function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

  23.    function "="  (Left, Right : in Unbounded_String) return Boolean;

  24.    function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

  25.    function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

  26.    function "<"  (Left, Right : in Unbounded_String) return Boolean;

  27.    function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

  28.    function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

  29.    function "<=" (Left, Right : in Unbounded_String) return Boolean;

  30.    function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

  31.    function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

  32.    function ">"  (Left, Right : in Unbounded_String) return Boolean;

  33.    function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

  34.    function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

  35.    function ">=" (Left, Right : in Unbounded_String) return Boolean;

  36.    function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

  37.    function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

  38.    -- Search subprograms

  39.    function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

  40.    function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

  41.    function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

  42.    function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

  43.    function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

  44.    function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

  45.    function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

  46.    procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

  47.    -- String translation subprograms

  48.    function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

  49.    procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

  50.    function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

  51.    procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

  52.    -- String transformation subprograms

  53.    function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

  54.    procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

  55.    function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

  56.    procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

  57.    function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

  58.    procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

  59.    function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

  60.    procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

  61.    function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

  62.    procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

  63.    function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

  64.    procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

  65.    function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

  66.    procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

  67.    function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

  68.    procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

  69.    function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

  70.    function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

  71.    function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

  72. private
   ... -- not specified by the language
end Ada.Strings.Unbounded;
  73. Null_Unbounded_String represents the null String. If an object of type Unbounded_String is not otherwise initialized, it will be initialized to the same value as Null_Unbounded_String.
  74. The function Length returns the length of the String represented by Source.
  75. The type String_Access provides a (non-private) access type for explicit processing of unbounded-length strings. The procedure Free performs an unchecked deallocation of an object of type String_Access.
  76. The function To_Unbounded_String(Source : in String) returns an Unbounded_String that represents Source. The function To_Unbounded_String(Length : in Natural) returns an Unbounded_String that represents an uninitialized String whose length is Length.
  77. The function To_String returns the String with lower bound 1 represented by Source. To_String and To_Unbounded_String are related as follows:
    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.
    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  36. 

       function "<"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  37. 

       function "<=" (Left, Right : in Unbounded_String) return Boolean;

    


  38. 

       function "<="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  39. 

       function "<="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  40. 

       function ">"  (Left, Right : in Unbounded_String) return Boolean;

    


  41. 

       function ">"  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  42. 

       function ">"  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  43. 

       function ">=" (Left, Right : in Unbounded_String) return Boolean;

    


  44. 

       function ">="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  45. 

       function ">="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  46. 

       -- Search subprograms

    


  47. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  48. 

       function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  49. 

       function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

    


  50. 

       function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
      return Natural;

    


  51. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                                := Maps.Identity)
      return Natural;

    


  52. 

       function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
      return Natural;

    


  53. 

       function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
      return Natural;

    


  54. 

       procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

    


  55. 

       -- String translation subprograms

    


  56. 

       function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
      return Unbounded_String;

    


  57. 

       procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

    


  58. 

       function Translate
     (Source  : in Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function)
      return Unbounded_String;

    


  59. 

       procedure Translate
     (Source  : in out Unbounded_String;
      Mapping : in Maps.Character_Mapping_Function);

    


  60. 

       -- String transformation subprograms

    


  61. 

       function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
      return Unbounded_String;

    


  62. 

       procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

    


  63. 

       function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
      return Unbounded_String;

    


  64. 

       procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

    


  65. 

       function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
      return Unbounded_String;

    


  66. 

       procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

    


  67. 

       function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
      return Unbounded_String;

    


  68. 

       procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

    


  69. 

       function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
      return Unbounded_String;

    


  70. 

       procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

    


  71. 

       function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
      return Unbounded_String;

    


  72. 

       procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

    


  73. 

       function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  74. 

       procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  75. 

       function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
      return Unbounded_String;

    


  76. 

       procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

    


  77. 

       function "*" (Left  : in Natural;
                 Right : in Character)
      return Unbounded_String;

    


  78. 

       function "*" (Left  : in Natural;
                 Right : in String)
      return Unbounded_String;

    


  79. 

       function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
      return Unbounded_String;

    


  80. 

    private
   ... -- not specified by the language
end Ada.Strings.Unbounded;

    


  81. Null_Unbounded_String represents the null String. If an object of type
Unbounded_String is not otherwise initialized, it will be initialized to
the same value as Null_Unbounded_String.


  82. The function Length returns the length of the String represented by
Source.


  83. The type String_Access provides a (non-private) access type for explicit
processing of unbounded-length strings. The procedure Free performs an
unchecked deallocation of an object of type String_Access.


  84. The function To_Unbounded_String(Source : in String) returns an
Unbounded_String that represents Source. The function
To_Unbounded_String(Length : in Natural) returns an Unbounded_String
that represents an uninitialized String whose length is Length.


  85. The function To_String returns the String with lower bound 1 represented
by Source. To_String and To_Unbounded_String are related as follows:


      

    1. If S is a String, then To_String(To_Unbounded_String(S)) = S.


    2. If U is an Unbounded_String, then To_Unbounded_String(To_String(U)) = U.
  1. For each of the Append procedures, the resulting string represented by the Source parameter is given by the concatenation of the original value of Source and the value of New_Item.
  2. Each of the "&" functions returns an Unbounded_String obtained by concatenating the string or character given or represented by one of the parameters, with the string or character given or represented by the other parameter, and applying To_Unbounded_String to the concatenation result string.
  3. The Element, Replace_Element, and Slice subprograms have the same effect as the corresponding bounded-length string subprograms.
  4. Each of the functions "=", "<", ">","<=", and ">=" returns the same result as the corresponding String operation applied to the String values given or represented by Left and Right.
  5. Each of the search subprograms (Index, Index_Non_Blank, Count, Find_Token) has the same effect as the corresponding subprogram in Strings.Fixed applied to the string represented by the Unbounded_String parameter.
  6. The Translate function has an analogous effect to the corresponding subprogram in Strings.Fixed. The translation is applied to the string represented by the Unbounded_String parameter, and the result is converted (via To_Unbounded_String) to an Unbounded_String.
  7. Each of the transformation functions (Replace_Slice, Insert, Overwrite, Delete), selector functions (Trim, Head, Tail), and constructor functions ("*") is likewise analogous to its corresponding subprogram in Strings.Fixed. For each of the subprograms, the corresponding fixed-length string subprogram is applied to the string represented by the Unbounded_String parameter, and To_Unbounded_String is applied the result string.
  8. For each of the procedures Translate, Replace_Slice, Insert, Overwrite, Delete, Trim, Head, and Tail, the resulting string represented by the Source parameter is given by the corresponding function for fixed-length strings applied to the string represented by Source's original value.

    Implementation Requirements
  9. No storage associated with an Unbounded_String object shall be lost upon assignment or scope exit.

Node:A.4.6, Next:, Previous:A.4.5, Up:A.4

String-Handling Sets and Mappings

  1. The language-defined package Strings.Maps.Constants declares Character_Set and Character_Mapping constants corresponding to classification and conversion functions in package Characters.Handling.

    Static Semantics
  2. The library package Strings.Maps.Constants has the following declaration: 
  3. package Ada.Strings.Maps.Constants is
   pragma Preelaborate(Constants);

  4.    Control_Set           : constant Character_Set;
   Graphic_Set           : constant Character_Set;
   Letter_Set            : constant Character_Set;
   Lower_Set             : constant Character_Set;
   Upper_Set             : constant Character_Set;
   Basic_Set             : constant Character_Set;
   Decimal_Digit_Set     : constant Character_Set;
   Hexadecimal_Digit_Set : constant Character_Set;
   Alphanumeric_Set      : constant Character_Set;
   Special_Set           : constant Character_Set;
   ISO_646_Set           : constant Character_Set;

  5.    Lower_Case_Map        : constant Character_Mapping;
     --Maps to lower case for letters, else identity
   Upper_Case_Map        : constant Character_Mapping;
     --Maps to upper case for letters, else identity
   Basic_Map             : constant Character_Mapping;
     --Maps to basic letter for letters, else identity

  6. private
   ... -- not specified by the language
end Ada.Strings.Maps.Constants;
  7. Each of these constants represents a correspondingly named set of characters or character mapping in Characters.Handling, see A.3.2.

Node:A.4.7, Next:, Previous:A.4.6, Up:A.4

Wide_String Handling

  1. Facilities for handling strings of Wide_Character elements are found in the packages Strings.Wide_Maps, Strings.Wide_Fixed, Strings.Wide_Bounded, Strings.Wide_Unbounded, and Strings.Wide_Maps.Wide_Constants. They provide the same string-handling operations as the corresponding packages for strings of Character elements.

    Static Semantics
  2. The package Strings.Wide_Maps has the following declaration. 
  3. package Ada.Strings.Wide_Maps is
   pragma Preelaborate(Wide_Maps);

  4.    -- Representation for a set of Wide_Character values:
   type Wide_Character_Set is private;

  5.    Null_Set : constant Wide_Character_Set;

  6.    type Wide_Character_Range is
     record
         Low  : Wide_Character;
         High : Wide_Character;
     end record;
   -- Represents Wide_Character range Low..High

  7.    type Wide_Character_Ranges is array (Positive range <>)
     of Wide_Character_Range;

  8.    function To_Set (Ranges : in Wide_Character_Ranges)
     return Wide_Character_Set;

  9.    function To_Set (Sphrerelevant
constructor and selector operations are provided.


    

    Static Semantics
    


  10. The library package Strings.Unbounded has the following declaration:


  11. 

    with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate(Unbounded);

    


  12. 

       type Unbounded_String is private;

    


  13. 

       Null_Unbounded_String : constant Unbounded_String;

    


  14. 

       function Length (Source : in Unbounded_String) return Natural;

    


  15. 

       type String_Access is access all String;
   procedure Free (X : in out String_Access);

    


  16. 

       -- Conversion, Concatenation, and Selection functions

    


  17. 

       function To_Unbounded_String (Source : in String)
      return Unbounded_String;

    


  18. 

       function To_Unbounded_String (Length : in Natural)
      return Unbounded_String;

    


  19. 

       function To_String (Source : in Unbounded_String) return String;

    


  20. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

    


  21. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

    


  22. 

       procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

    


  23. 

       function "&" (Left, Right : in Unbounded_String)
      return Unbounded_String;

    


  24. 

       function "&" (Left : in Unbounded_String; Right : in String)
      return Unbounded_String;

    


  25. 

       function "&" (Left : in String; Right : in Unbounded_String)
      return Unbounded_String;

    


  26. 

       function "&" (Left : in Unbounded_String; Right : in Character)
      return Unbounded_String;

    


  27. 

       function "&" (Left : in Character; Right : in Unbounded_String)
      return Unbounded_String;

    


  28. 

       function Element (Source : in Unbounded_String;
                     Index  : in Positive)
      return Character;

    


  29. 

       procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

    


  30. 

       function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
      return String;

    


  31. 

       function "="  (Left, Right : in Unbounded_String) return Boolean;

    


  32. 

       function "="  (Left : in Unbounded_String; Right : in String)
     return Boolean;

    


  33. 

       function "="  (Left : in String; Right : in Unbounded_String)
     return Boolean;

    


  34. 

       function "<"  (Left, Right : in Unbounded_String) return Boolean;

    


  35. 

       function "<"  (Left : in Unbounded_String; Right : in String)
     return Boolean;