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 :

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 :

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