9.4. Fonctions et opérateurs de chaînes

La fonction format produit une sortie formatée suivant une chaîne de formatage, dans un style similaire à celui de la fonction C sprintf.

format(chaine_format text [, arg_format "any" [, ...] ])

chaine_format est une chaîne de formatage qui indique comment le résultat doit être formatté. Le texte de la chaîne de formatage est copié directement dans le résultat, sauf quand des spécificateurs de formatage sont utilisés. Ces spécificateur agissent comme des pointeurs dans la chaîne, définissant comment les arguments suivants de la fonction doivent être formatés et insérés dans le résultat. Chaque argument arg_format est converti en texte suivant les règles de sortie habituelles pour son type de données, puis formaté et inséré dans la chaîne en résultat suivant les spécificateurs de format.

Les spécificateurs de format sont introduits par un symbole % et ont la forme suivante :

%[position][drapeaux][longueur]type

où les composants sont :

En plus des spécificateurs de format décrit ci-dessus, la séquence spéciale %% peut être utilisée pour afficher un caractère litéral %.

Voici quelques exemples des conversions basiques de format :

SELECT format('Hello %s', 'World');
Résultat : Hello World

SELECT format('Testing %s, %s, %s, %%', 'one', 'two', 'three');
Résultat : Testing one, two, three, %

SELECT format('INSERT INTO %I VALUES(%L)', 'Foo bar', E'O\'Reilly');
Résultat : INSERT INTO "Foo bar" VALUES('O''Reilly')

SELECT format('INSERT INTO %I VALUES(%L)', 'locations', E'C:\\Program Files');
Résultat : INSERT INTO locations VALUES(E'C:\\Program Files')

Voici quelques exemples utilisant le champ longueur et le drapeau - :

SELECT format('|%10s|', 'foo');
Résultat : |       foo|

SELECT format('|%-10s|', 'foo');
Résultat : |foo       |

SELECT format('|%*s|', 10, 'foo');
Résultat : |       foo|

SELECT format('|%*s|', -10, 'foo');
Résultat : |foo       |

SELECT format('|%-*s|', 10, 'foo');
Résultat : |foo       |

SELECT format('|%-*s|', -10, 'foo');
Résultat : |foo       |

Ces exemples montrent l'utilisation des champs position :

SELECT format('Testing %3$s, %2$s, %1$s', 'one', 'two', 'three');
Résultat : Testing three, two, one

SELECT format('|%*2$s|', 'foo', 10, 'bar');
Résultat : |       bar|

SELECT format('|%1$*2$s|', 'foo', 10, 'bar');
Résultat : |       foo|

Contrairement à la fonction C standard sprintf, la fonction format de PostgreSQL™ permet que les spécificateurs de format avec ou sans le champ position soient mixés dans la même chaîne de formatage. Un spécificateur de format sans un champ position utilise toujours le prochain argument après que le dernier argument soit consommé. De plus, la fonction format ne requiert pas que tous les arguments de fonction soient utilisés dans la chaîne de formatage. Par exemple :

SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
Résultat : Testing three, two, three

Les spécificateurs de format %I et %L sont particulièrement utiles pour construire proprement des requêtes SQL dynamiques. Voir Exemple 40.1, « Mettre entre guillemets des valeurs dans des requêtes dynamiques ».