Returns a text or string result of the replacing in the indicated string of the arguments passed to the function according to the format rules.

To reference the arguments there are several methodes:

  • explicit index

    The format contains the index of the argument. The index of the argument is an integer which indicates the position of the argument in the list of arguments (starting at 1). The first arguments is referenced by '1$', the second by '2$', etc. For example: "%4$s %3$s %2$s %1$s %4$s %3$s %2$s %1$s", "a", "b", "c", "d" --> "d c b a d c b a" If does not exist the indicated argument an exception is produced MissingFormatArgumentException.

  • relative index

    The format contains the character '<' ('\u003c'), indicates which the argument of the previous formt should be reused. Por ejemplo: "%s %s %s %s", "a", "b", "c", "d" --> "a b b b" If the previous argument does not exist, an exception MissingFormatArgumentException is produced.

  • ordinary index

    The format does not contain the index of the argument not the character '<'. The sequential order is used. For example: "%s %s %s %s", "a", "b", "c", "d" --> "a b c d" If it does not exist argument through a position an exception MissingFormatArgumentException is produced.

It is also possible to use all the ways in a same text or string. For example: "%2$s %s %s %s", "a", "b", "c", "d" --> "b a a b" The arguments 'b' are 'c' are ignored because any format makes reference to them.

1 string.format

<string.format format='format'>
    <format_text /> ?
    <value /> +
</string.format>

Exceptions

requires at least 1 argument ...

The entry format text has not been specified.

java.util.MissingFormatArgumentException: Format specifier ...

An argument which does not exist has been required.

See also

https://docs.oracle.com/javase/7/docs/api/java/lang/String.html#format(java.lang.String,%20java.lang.Object...)

http://java.sun.com/j2se/1.5.0/docs/api/java/util/Formatter.html

Example

This example shows how an exception (MissingFormatArgumentException) is produced because it requires the argument with index 4 (4$) and this does not exist (the function receives only 3 arguments).

Copy 
<xsql-script name='string_format'>
    <body>
        <set name='format_text'>%4$s %3$s %2$s %1$s %4$s %3$s %2$s %1$s</set>
        <println>
            <string.format>
                <format_text/>
                <string>a</string>
                <string>b</string>
                <string>c</string>
            </string.format>
        </println>
    </body>
</xsql-script>

Returns:

Copy 
c b a c b a
Example

This example formats a simple text and illustrate how tha arguments are referenced.

Copy 
<xsql-script name='string_format'>
   <body>
       <!-- d c b a d c b a -->
       <set name='format_text'>%4$s %3$s %2$s %1$s %4$s %3$s %2$s %1$s</set>
       <println>
           <string.format>
               <format_text/>
               <string>a</string>
               <string>b</string>
               <string>c</string>
               <string>d</string>
           </string.format>
       </println>
   </body>
</xsql-script>

Returns:

Copy 
d c b a d c b a
Example

This example formats the number [e]. The precision and the size can be used to round and align the value. Optionally, you can indicate a language for the decimal separator ('en' uses the '.' as separator).

Copy 
<xsql-script name='string_format'>
   <body>
       <!-- e =    +2.7183 -->
       <set name='format_text'>e = %+10.4f</set>
       <println>
           <string.format lang='en'>
               <format_text/>
               <math.e />
           </string.format>
       </println>
   </body>
</xsql-script>

Returns:

Copy 
e =    +2.7183

2017.3

The following examples shows functionalities added in the version 2017.3

Example

Example with the classic form and the new attribute of 2017.3:

Copy 
<xsql-script>
    <body>
        <!-- The character which will be used to separate the decimals depend of the user configuration, -->
        <!-- by default is "," causing a fail of the example, -->
        <!-- Classical mode of the string.format without format attribute -->
        <assert.equals>
            <string>The problem A is 10 divided by 3.142</string>
            <string.format>
                <string>The problem %s is %02d divided by %.3f</string>
                <string>A</string>
                <integer>10</integer>
                <number>3.1416</number>
            </string.format>
        </assert.equals>

        <!-- Modo 2017.3 de string.format con format attribute -->
        <assert.equals>
            <string>The problem A is 10 divided by 3.142</string>
            <string.format format='The problem %s is %02d divided by %.3f'>
                <string>A</string>
                <integer>10</integer>
                <number>3.1416</number>
            </string.format>
        </assert.equals>
    </body>
</xsql-script>
Example

Example using array:

Copy 
<xsql-script>
    <body>
    <!-- Mode 2017.3 of string.format with format attribute  -->
        <assert.equals>
            <string>The quick brown fox jumps over the lazy dog</string>
            <string.format format='The quick %s fox %s over the lazy %s'>
                <string>brown</string>
                <string>jumps</string>
                <string>dog</string>
            </string.format>
        </assert.equals>

        <!-- 2017.3 without format attribute + arguments as array -->
        <assert.equals>
            <string>The quick brown fox jumps over the lazy dog</string>
            <string.format>
                <string>The quick %s fox %s over the lazy %s</string>
                <array>
                    <string>brown</string>
                    <string>jumps</string>
                    <string>dog</string>
                </array>
            </string.format>
        </assert.equals>

        <!-- 2017.3 format attribute + arguments con array -->
        <assert.equals>
            <string>The quick brown fox jumps over the lazy dog</string>
            <string.format format='The quick %s fox %s over the lazy %s'>
                <array>
                    <string>brown</string>
                    <string>jumps</string>
                    <string>dog</string>
                </array>
            </string.format>
        </assert.equals>
    </body>
</xsql-script>