variable_length.ads |
package Variable_Length specification |
variable_length.adb |
package Variable_Length body |
variable_length-io.ads |
package Variable_Length.IO specification |
variable_length-io.adb |
package Variable_Length.IO body |
variable_length.html |
(this file) package Variable_Length documentation |
Fully portable.
This package uses no compiler specific feature nor any feature
defined in an annex.
Packages Variable_Length and Variable_Length.IO are © Copyright 1997-2015 ADALOG.
Variable_Length is free software; you can redistribute it and/or modify it under terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. This unit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License distributed with this program; see file COPYING. If not, write to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
As a special exception, if other files instantiate generics from this program, or if you link units from this program with other files to produce an executable, this does not by itself cause the resulting executable to be covered by the GNU General Public License. This exception does not however invalidate any other reasons why the executable file might be covered by the GNU Public License.
This document is Copyright © 1997-2015 Adalog. This document may be copied, in whole or in part, in any form or by any means, as is or with alterations, provided that (1) alterations are clearly marked as alterations and (2) this copyright notice is included unmodified in any copy.The goal of this license is to make this product widely available as an advertisement for Adalog activities and a demonstration of Adalog's know-how in Ada development, without imposing any constraint on the user, except that code not made by Adalog should not be confused with original code (we cannot accept responsability for your bugs).
Although we do not require it, you are very welcome, if you find this software useful, to send us a note at rosen@adalog.fr. We also welcome critics, suggestions for improvement, etc.
ADALOG is providing training, consultancy and expertise in Ada and related software engineering techniques. For more info about our services:
| 2 rue du Docteur Lombard 92441 Issy-Les-Moulineaux CEDEX FRANCE |
Tel: +33 1 45 29 21 52 | E-m: info@adalog.fr
URL: http://www.adalog.fr/ |
This package provides a simple "variable length string"
type. It is useful when you just want to store strings whose
maximum length is known beforehand. It provides operations that
are consistent with those defined in the Bounded_String
and Unbounded_String packages.
type Variable_String (Max : Positive) is private;
This is the basic type, representing a string of characters of
maximum length Max. It does not use any
dynamic allocation.
function Length (Source : Variable_String) return Natural;
This function returns the current (actual) length of the
string. Note that there is no need to provide a function to
return the maximum length, since the discriminant Max
is directly accessible.
procedure Move
(Source : in Variable_String;
Target : out Variable_String;
Drop : in Ada.Strings.Truncation := Ada.Strings.Error);
This procedure copies Source to Target.
Note that normal assignment is available for Variable_String,
but that it will raise Constraint_Error if the
discriminants of LHS and RHS do not match. This procedure allows
to move between variables with different discriminants. If the
current length of Source is bigger than the maximum
length of Target, the behaviour is defined by the
value of Drop (see package Ada.Strings
in your favorite Reference Manual).
function To_String (Source : Variable_String) return String;
This function returns the value of the actual string contained
in Source as a regular String.
function To_Variable_String
(Max : Positive;
Source : String := "";
Drop : Ada.Strings.Truncation := Ada.Strings.Error)
return Variable_String;
procedure To_Variable_String
(Source : in String := "";
Target : out Variable_String;
Drop : in Ada.Strings.Truncation := Ada.Strings.Error);
These subprograms are used to convert regular strings into Variable_String.
In the function, it is necessary to pass (Max) the
maximum length of the created value. In the procedure, Source
is copied into Target, and the maximum size is the
one of Target. In either case, if the length of Source
is bigger than the maximum length, the behaviour is defined by
the value of Drop (see package Ada.Strings
in your favorite Reference Manual).
function "&" (Left : Variable_String; Right : String) return Variable_String ; function "&" (Left : Variable_String; Right : Character) return Variable_String ; function "&" (Left : Variable_String; Right : Variable_String) return Variable_String ;
These functions are used to catenate a (String, Character,
Variable_String) to a Variable_String.
In any case, the maximum length of the result is the one of Left.
If the length of the catenation is bigger than the maximum
length, Length_Error is raised.
function "=" (Left : Variable_String; Right : Variable_String) return Boolean; function "=" (Left : Variable_String; Right : String ) return Boolean; function "=" (Left : String; Right : Variable_String) return Boolean; function "<" (Left : Variable_String; Right : Variable_String) return Boolean; function "<" (Left : Variable_String; Right : String ) return Boolean; function "<" (Left : String; Right : Variable_String) return Boolean;
(And similarly for "<=", ">",
">=")
These are comparison functions between Variable_String
and (String, Character, Variable_String).
Of course, only the significant part of a Variable_String
is compared!
Length_Error : exception renames Ada.Strings.Length_Error;
This is the usual renaming of exception, as provided by other packages.
procedure Get_Line (File : in File_Type; Item : out Variable_String); procedure Get_Line (Item : out Variable_String);
These procedures behave as the regular Get_Line
from Ada.Text_IO, the main difference being that
there is no Last parameter; rather, the actual
length of the Variable_String tells how many
characters were read.
procedure Put_Line (File : in File_Type; Item : in Variable_String); procedure Put_Line (Item : in Variable_String);
These procedures behave as the regular Put_Line
from Ada.Text_IO.
procedure Put (File : in File_Type; Item : in Variable_String); procedure Put (Item : in Variable_String);
These procedures behave as the regular Put from Ada.Text_IO.
Q: Why use Variable_String rather than String,
Bounded_String, or Unbounded_String?
A: Each kind of string is appropriate to different usage.
As a rule of thumb, here is a short summary of when to use each:
String is convenient for fixed length
strings, like messages. Variable_String is convenient for the
storage of variable lengths strings, that have no
particular semantic meaning: input strings,
formatting, ... Bounded_String is convenient to implement an
abstract data type as a string. For example, you may have
a logical name like Person_Name that you
want to implement as a variable length string. The
maximum length results from program analysis, and it is
appropriate to have a separate type for each, since you
don't want to assign a Person_Name to a Person_Address
for example. Unbounded_String is appropriate as a huge
storage of characters, like in a text processing system
where you may want to store the whole document as a
single structure. Q: Why aren't all functions of Bounded_String
provided ?
A: The idea of Variable_String is mainly to
provide storage when the length of the string is not know
beforehand. "Natural" operations are provided, but we
didn't want to overload the package with rarely used functions.
If you need "sophisticated" functions, just extract the
String, work on this, and if necessary convert the
result back to Variable_String. Admitedly, the
boundary between "natural" and "sophisticated"
functions is a matter of judgement...
Q: Why do the "&" functions always raise Length_Error?
A: Since it is an operator, there is no way to provide a
third argument equivalent to the Drop parameter of
other operations. Raising Length_Error seems the
best default in this case. This is the same as the standard
string packages. We could have provided Append
functions, but see previous paragraph...
There is not much to say about the implementation. It uses the obvious discriminated type approach, and the body of the package should be quite straightforward to read. Note the use array slices where appropriate.
If you found this package useful...
If you think that getting it from us saved you some time...
If it showed you some usages of Ada that you didn't think about...
Maybe you should consider using Adalog's consulting and training services !