[comment {-*- flibs -*- doctools manpage}]
[manpage_begin flibs/m_vstringformat n 1.0]
[copyright {2008 Michael Baudin michael.baudin@gmail.com}]
[moddesc flibs]
[titledesc {Formatting dynamic strings}]

[description]

The module [strong 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.


[section 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.
   
   [subsection "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".

[example {
      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 :

[example {
      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 :

[example {
      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 )
}]

   [subsection "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 :
[list_begin bullet]
[bullet] if the integer is negative, the "-" sign is at the begining of the string,
[bullet]  if the integer is positive, the "+" sign is not in the string.
[list_end]
   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".

[example {
      type ( t_vstring ) :: mystring
      mystring = vstring_format ( 2008 )
}]

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

[example {
      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.

[example {
      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".

   [subsection "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 :
   [list_begin bullet]
[bullet] 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.
[bullet]  the "write" statement has to manage a long string, even
     if the result is short, which raise performances issues.
[list_end]

   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.

   [subsection "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...

[section METHODS]

[list_begin definitions]

[call [method "vstring_format"] [arg value] [opt fmt]]
[list_begin arg]
[arg_def "<value type>, intent(in) ::" value]
[arg_def "<fmt type>, intent(in), optional ::" fmt]
[list_end]
Generic converter from a basic fortran data type into a vstring.
Returns a new dynamic string with type t_vstring by formating the 
given [arg value] against the optional format [arg fmt].
The [arg value] may be a logical or and integer of kind 1, 2, 4 or 8 to format.
If [arg 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.

[call [method "vstring_format"] [arg logical_value]]
[list_begin arg]
[arg_def "logical , intent(in) ::" logical_value]
[list_end]
Returns a new vstring by formatting the logical [arg logical_value] 
with automatic format.

[call [method "vstring_format"] [arg logical_value] [arg fmt]]
[list_begin arg]
[arg_def "logical , intent(in) ::" logical_value]
[arg_def "character(len=*), intent(in) ::" fmt]
[list_end]
Returns a new vstring by formatting the logical [arg logical_value] 
with the given character(len=*) format [arg fmt].

[call [method "vstring_format"] [arg logical_value] [arg fmt]]
[list_begin arg]
[arg_def "logical, intent(in) ::" logical_value]
[arg_def "type ( t_vstring ), intent(in) ::" fmt]
[list_end]
Returns a new vstring by formatting the logical [arg logical_value] 
with the given vstring format [arg fmt].

[call [method "vstring_format"] [arg integer_value]]
[list_begin arg]
[arg_def "integer (kind = INTEGER_KIND ), intent(in) ::" integer_value]
[list_end]
Returns a new vstring by formatting the integer [arg 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.

[call [method "vstring_format"] [arg integer_value] [arg fmt]]
[list_begin arg]
[arg_def "integer (kind = INTEGER_KIND ), intent(in) ::" integer_value]
[arg_def "character(len=*), intent(in) ::" fmt]
[list_end]
Returns a new vstring by formatting the integer [arg integer_value]
 with the given format [arg fmt].
The INTEGER_KIND kind of integer may by 1, 2, 4 or 8.

[call [method "vstring_format"] [arg integer_value] [arg fmt]]
[list_begin arg]
[arg_def "integer (kind = INTEGER_KIND ), intent(in) ::" integer_value]
[arg_def "type ( t_vstring ), intent(in) ::" fmt]
[list_end]
Returns a new vstring by formatting the integer [arg integer_value]
 with the given format [arg fmt].
The INTEGER_KIND kind of integer may by 1, 2, 4 or 8.

[list_end]

[manpage_end]
