# flibs/m_vstringformat(n) 1.0 "flibs"

## NAME

flibs/m_vstringformat - Formatting dynamic strings

## TABLE OF CONTENTS

TABLE OF CONTENTS
SYNOPSIS
DESCRIPTION
OVERVIEW
Formatting logical values
Formatting integer values
Limitations
Planned features
METHODS
COPYRIGHT

## SYNOPSIS

vstring_format value ?fmt?
vstring_format logical_value
vstring_format logical_value fmt
vstring_format logical_value fmt
vstring_format integer_value
vstring_format integer_value fmt
vstring_format integer_value fmt

## DESCRIPTION

The module m_vstringformat provides services to format one string, that is to say to convert a basic fortran data type into a dynamic vstring. The current version of m_vstringformat can handle logical variables and integers of all kinds. The format can be given by the client code, or computed automatically. The format can be given as a basic character string, or as a vstring.

## OVERVIEW

The only method provided here is vstring_format, which takes one basic basic fortran data type as the first argument (and, optionnaly, a format), and returns a dynamic string which represents that value.

### Formatting logical values

One can format a logical into a vstring with automatic or explicit format. In the following sample, one format the ".false." logical into a vstring. After formatting, the string "mystring" has a length of 1 and its content is "F".

          logical :: mybool
          type ( t_vstring ) :: mystring
          mybool = .false.
          mystring = vstring_format ( mybool )

In the following sample, one format the ".false." logical into a vstring with an explicit format given as a character string :

          logical :: mybool
          type ( t_vstring ) :: mystring
          mybool = .false.
          mystring = vstring_format ( mybool , "(L3)" )

After formatting, the string "mystring" has a length of 3 and its content is " F". In the following sample, one format the ".false." logical into a vstring with an explicit format given as a vstring :

          logical :: mybool
          type ( t_vstring ) :: mystring
          type ( t_vstring ) :: myformat
          mybool = .false.
          call vstring_new ( myformat , "(L3)" )
          mystring = vstring_format ( mybool , myformat )
          call vstring_free ( myformat )

### Formatting integer values

One can format an integer into a vstring, with automatic or explict format. The string formatting system can handle all fortran kinds of integers. The automatic format makes so that the resulting string has the length which exactly matches the number of digits necessary to represent the integer :

- if the integer is negative, the "-" sign is at the begining of the string,
- if the integer is positive, the "+" sign is not in the string.

In the following example, one formats the integer 2008 into a vstring. After formatting, the string has a length of 4 and its content is the string "2008".

          type ( t_vstring ) :: mystring
          mystring = vstring_format ( 2008 )

To acheive the same effect, one can use the "I0" format of the fortran 90 standard :

          type ( t_vstring ) :: mystring
          mystring = vstring_format ( 2008 , "(I0)" )

The component can handle long integers with specified kinds 1, 2, 4 or 8. In the following example, one automatically format a 32-bits integer (1073741824 = 2**31) into a dynamic string.

          integer (kind=4) :: integerkind4 = 1073741824
          mystring = vstring_format ( integerkind4 )

After formatting, the string has a length of 4 and its content is the string "1073741824".

### Limitations

The current implementation of the string formatting is based on the standard "write" fortran statement, which takes a basic character string as argument. Moreover the format given to the string formatting command is not analysed at all, so that the length of the resulting string is not computed. The current component use therefore a character string of fixed length VSTRING_FORMAT_MAXIMUM_FORMAT_LENGTH. This leads to at least two limitations :

- if the client code has to manage formated strings which length is over VSTRING_FORMAT_MAXIMUM_FORMAT_LENGTH characters, the current algorithm will generate an error at execution time.
- the "write" statement has to manage a long string, even if the result is short, which raise performances issues.

The current string formatting takes only one value. An effective implementation would in fact take a list of one or more arguments, which may be of different types. The current implementation does not manage real values. The limitations of the current component are so strong that the component should not be released... but is useful to format integers and that is why it has been finally released.

### Planned features

It is expected that future releases of this component can manage more basic data types, including real types of all kinds. Future releases may also extend the formats by taking into account string formatting coming from other languages than fortran (for example C), including: - the "-" specification which specifies that the converted argument should be left-justified in its field - the "+" specification which specifies that a number should always be printed with a sign, even if positive. - etc...

## METHODS

vstring_format value ?fmt?
  <value type>, intent(in) :: value
  <fmt type>, intent(in), optional :: fmt
  Generic converter from a basic fortran data type into a vstring. Returns a new dynamic string with type t_vstring by formating the given value against the optional format fmt. The value may be a logical or and integer of kind 1, 2, 4 or 8 to format. If fmt is provided, then this format is used to compute the new string. If format is provided, it may be either with a character(len=*) type or with a t_vstring type. If format is not provided, an automatic format is computed and applied to compute the new string. With automatic format, the computed string has a minimum length, that is, does not contain any blank and begins with "-" only if the value is a strictly negative integer.
vstring_format logical_value
  logical , intent(in) :: logical_value
  Returns a new vstring by formatting the logical logical_value with automatic format.
vstring_format logical_value fmt
  logical , intent(in) :: logical_value
  character(len=*), intent(in) :: fmt
  Returns a new vstring by formatting the logical logical_value with the given character(len=*) format fmt.
vstring_format logical_value fmt
  logical, intent(in) :: logical_value
  type ( t_vstring ), intent(in) :: fmt
  Returns a new vstring by formatting the logical logical_value with the given vstring format fmt.
vstring_format integer_value
  integer (kind = INTEGER_KIND ), intent(in) :: integer_value
  Returns a new vstring by formatting the integer integer_value with an automatic format. With automatic format, the computed string has a minimum length, that is, does not contain any blank and begins with "-" only if the integer_value is a strictly negative integer. The INTEGER_KIND kind of integer may by 1, 2, 4 or 8.
vstring_format integer_value fmt
  integer (kind = INTEGER_KIND ), intent(in) :: integer_value
  character(len=*), intent(in) :: fmt
  Returns a new vstring by formatting the integer integer_value with the given format fmt. The INTEGER_KIND kind of integer may by 1, 2, 4 or 8.
vstring_format integer_value fmt
  integer (kind = INTEGER_KIND ), intent(in) :: integer_value
  type ( t_vstring ), intent(in) :: fmt
  Returns a new vstring by formatting the integer integer_value with the given format fmt. The INTEGER_KIND kind of integer may by 1, 2, 4 or 8.

## COPYRIGHT

Copyright © 2008 Michael Baudin michael.baudin@gmail.com