Package Variable_Length
(Documentation)

• General
  • Files in this distribution:
  • Portability
  • Copyright, etc.
  • About Adalog
• What package Variable_Length does
  • Package Variable_Length
  • Package Variable_Length.IO
  • Questions and answers
• Technical notes
• A final note...

General

Files in this distribution:

The file names match the GNAT "krunching" for DOS. If you are using GNAT on systems with long file names, use gnatchop to recreate the proper names.

Portability

Fully portable.
This package uses no compiler specific feature nor any feature defined in an annex.

Copyright, etc.

Packages Variable_Length, Variable_Length.IO and their documentation are (C) Copyright 1997 ADALOG.

This software is distributed under Adalog's "advertiseware" license. 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). Therefore:

Rights to use, distribute or modify in any way this software and its documentation are hereby granted, provided:

1. You do not remove or change the initial comment in the source files that contains the copyright notice and the reference to Adalog's activities. Similarly, you do not remove this copyright notice and the reference to Adalog's activities from this documentation. Additionnal headers in source files, or changes to the documentation are otherwise allowed.
2. You distribute this documentation with any copy of the software (whether as source or compiled form).
3. If you make modifications to the software or this documentation, these modifications must be properly identified as additions or modifications not originating from Adalog. If you make a valuable addition, we would appreciate (but do not require) to be kept informed by sending a message to rosen@adalog.fr.

This software 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.

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.

About Adalog

ADALOG is providing training, consultancy and expertise in Ada and related software engineering techniques. For more info about our services:

What package Variable_Length does

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.

Package Variable_Length

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.

Package Variable_Length.IO

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.

Questions and answers

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...

Technical notes

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.

A final note...

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 !