Many of the routines in wxml, and indeed in wcml which is built on top of wxml, are overloaded so that data may be passed to the same routine as string, integer, logical, real, or complex data.
In such cases, a few notes on the conversion of non-textual data to text is in order. The standard Fortran I/O formatting routines do not offer the control required for useful XML output, so FoX performs all its own formatting.
This formatting is done internally through a function which is also available publically to the user, str.
To use this in your program, import it via:
use FoX_common, only; str
and use it like so:
print*, str(data)
In addition, for ease of use, the // concatenation operator is overloaded, such that strings can easily be formed by concatenation of strings to other datatypes. To use this you must import it via:
use FoX_common, only: operator(//)
and use it like so:
integer :: data
print*, "This is a number "//data
This will work for all native Fortran data types - but no floating point formatting is available as described below with concatenation, only with str()
You may pass data of the following primitive types to str:
Character data is returned unchanged.
Logical data is output such that True values are converted to the string 'true', and False to the string 'false'.
Integer data is converted to the standard decimal representation.
Real numbers, both single and double precision, are converted to strings in one of two ways, with some control offered to the user. The output will conform to the real number formats specified by XML Schema Datatypes.
This may be done in one of two ways:
Exponential notation, with variable number of significant figures. Format strings of the form "sn" are accepted, where n is the number of significant figures.
Thus the number 111, when output with various formats, will produce the following output:
| s1 | 1e2 |
| s2 | 1.1e2 |
| s3 | 1.11e2 |
| s4 | 1.110e2 |
The number of significant figures should lie between 1 and the number of digits precision provided by the real kind. If a larger or smaller number is specified, output will be truncated accordingly. If unspecified, then a sensible default will be chosen.
This format is not permitted by XML Schema Datatypes 1.0, though it is in 2.0
Non-exponential notation, with variable number of digits after the decimal point. Format strings of the form "rn", where n is the number of digits after the decimal point.
Thus the number 3.14159, when output with various formats, will produce the following output:
| r0 | 3 |
| r1 | 3.1 |
| r2 | 3.14 |
| r3 | 3.142 |
The number of decimal places must lie between 0 and whatever would output the maximum digits precision for that real kind. If a larger or smaller number is specified, output will be truncated accorsingly. If unspecified, then a sensible default will be chosen.
This format is the only one permitted by XML Schema Datatypes 1.0
If no format is specified, then a default of exponential notation will be used.
If a format is specified not conforming to either of the two forms above, a run-time error will be generated.
NB Since by using FoX or str, you are passing real numbers through various functions, this means that they must be valid real numbers. A corollary of this is that if you pass in +/-Infinity, or NaN, then the behaviour of FoX is unpredictable, and may well result in a crash. This is a consequence of the Fortran standard, which strictly disallows doing anything at all with such numbers, including even just passing them to a subroutine.
Complex numbers will be output as pairs of real numbers, in the following way:
(1.0e0)+i(1.0e0)
where the two halves can be formatted in the way described for 'Real numbers' above; only one format may be specified, and it will apply to both.
All the caveats described above apply for complex number as well; that is, output of complex numbers either of whose components are infinite or NaN is illegal in Fortran, and more than likely will cause a crash in FoX.
All of the above types of data may be passed in as arrays and matrices as well. In this case, a string containing all the individual elements will be returned, ordered as they would be in memory, each element separated by a single space.
If the data is character data, then there is an additional option to str, delimiter which may be any single-character string, and will replace a space as the delimiter.
All functions in wxml which can accept arbitrary data (roughly, wherever you put anything that is not an XML name; attribute values, pseudo-attribute values, character data) will take scalars, arrays, and matrices of any of the above data types, with fmt= and delimiter= optional arguments where appropriate.
Similarly, wcml functions which can accept varied data will behave similarly.