flibs/m_vstringformat(n) 1.0 "flibs"

NAME

flibs/m_vstringformat - Formatting dynamic strings

    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

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.