Fonction strftime

Entête à inclure

#include <time.h>  // <ctime> en C++

Fonction strftime

size_t strftime( char * strBuffer, size_t maxSize, 
                 const char * format, const struct tm * pTime );

Cette fonction permet de convertir une structure de type struct tm, contenant des informations de date et d'heure en une chaîne de caractères C. Vous pouvez contrôler le format d'affichage, un peu à la manière d'un appel à la fonction sprintf.

Il existe un grand nombre d'éléments syntaxique pour introduire chaque partie d'une date. Ces éléments syntaxique sont introduit par un caractère %. Certains de ces éléments existent depuis très longtemps, d'autres on été rajoutés par la suite. Attention : tous les éléments syntaxique de formatage de votre date ne font pas tous partie des standards C89 ou C99. Voici un tableau présentant les principaux éléments de formatage disponibles pour cette fonction (la dernière colonne indiquant à quelle version du standard C est associé l'élément) :

Syntaxe	Correspondance	Exemple	Std
%a	Nom du jour sur 3 caractères	Mon	C89
%A	Nom complet du jour	Monday	C89
%b	Nom du mois sur 3 caractères	Apr	C89
%B	Nom complet du mois	April	C89
%c	Temps et heure	Mon Apr 07 21:56:02 2014	C89
%C	Année divisée par 100 (00..99)	20	C99
%d	Jour dans le mois sur 2 digits	07	C89
%D	Affichage court pour la date (%m/%d/%y)	04/07/14	C99
%e	Jour dans le mois (padding via un blanc)	7	C99
%F	Date au format YYYY-MM-DD (%Y-%m-%d)	2014-04-07	C99
%g	Comme %G sans le siècle, c'est-à-dire avec une année sur deux chiffres (00-99).	14	C99
%G	L'année ISO 8601 avec le siècle comme nombre décimal. L'année sur quatre chiffres correspond au numéro de la semaine ISO (voir %V). C'est le même format que %y, sauf que si le numéro de semaine appartient à l'année suivante ou précédente, c'est celle-ci qui est affichée à la place.	2014	C99
%h	Equivalent à %b	Apr	C99
%H	L'heure courant sur 24 heures (00..23). Padding avec le caractère 0.	21	C89
%I	L'heure courant sur 12 heures (01..12). Padding avec le caractère 0.	09	C89
%j	Le numéro du jour dans l'année sur trois digits (001..366). Padding avec le caractère 0.	097	C89
%k	L'heure courante sur 24 heures (0..23). Padding avec le caractère espace.	21	GNU
%l	L'heure courante sur 12 heures (1..12). Padding avec le caractère espace.	9	GNU
%m	Le numéro du mois sur deux digits (01..12). Padding avec le caractère 0.	04	C89
%M	La minute courante sur deux digits (00..59).	56	C89
%n	Un retour à la ligne (comme pour la fonction `printf`).		C99
%p	L'une des deux chaînes « AM » ou « PM » en fonction de l'heure (ou bien la traduction de ces chaînes en fonctions de la localisation). Midi est traité comme « PM » et minuit comme « AM ».	PM	C89
%P	Comparable à %p, mais les chaînes de caractères seront affichés en minuscules.	pm	GNU
%r	L'heure en notation a.m. ou p.m. Dans la localisation POSIX, c'est équivalent à %I:%M:%S %p.	09:56:02 PM	C99
%R	L'heure en format 24 heures (%H:%M) mais sans les secondes. Pour avoir les secondes veuillez utiliser le format %T.	21:56	C99
%s	Le nombre de secondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC.	1396900562	GNU
%S	La seconde, sous forme de nombre décimal (00-60).	02	C89
%t	Insère un caractère de tabulation, tout comme pour la fonction `printf`.		C99
%T	L'heure en notation 24 heures (%H:%M:%S). Utiliser %r pour l'avoir au format a.m. / p.m.	21:56:02	C99
%u	Le jour de la semaine sous forme décimal, de 1 (lundi) à 7. Veuillez utiliser %w si vous souhaitez débuter par dimanche.	7	C99
%U	Le numéro de la semaine dans l'année, sous forme de nombre décimal (00-53), en commençant le comptage au premier dimanche de l'année. Voir aussi %V et %W.	14	C89
%V	Le numéro de semaine ISO 8601:1988 de l'année en cours sous forme de nombre décimal dans l'intervalle 01-53, où la semaine 1 est la première ayant au moins 4 jours dans l'année en cours, et où lundi est le premier jour de la semaine. Voir aussi %U et %W.	15	C99
%w	Le numéro du jour de la semaine, sous forme décimale (0-6), dimanche valant 0. Voir aussi %u.	1	C89
%W	Le numéro de la semaine dans l'année, sous forme de nombre décimal (00-53), en commençant le comptage au premier Lundi de l'année.	14	C89
%x	La représentation usuelle de la date, sans l'heure, dans la localisation en cours.	04/07/14	C89
%X	La représentation usuelle de l'heure, sans la date, dans la localisation en cours.	21:56:02	C89
%y	L'année, sous forme de nombre décimal sur deux caractères (entre 00 et 99).	14	C89
%Y	L'année, sous forme de nombre décimal sur quatre caractères.	2014	C89
%z	Le fuseau horaire sous forme de décalage GMT. Nécessaire pour créer des dates conformes à la RFC 822 (avec « %a, %d %b %Y %H:%M:%S %z »).	+0200	C99
%Z	Le nom ou l'abréviation du fuseau horaire.	CEST	C89
%%	Permet simplement d'insérer un caractère « % ».	%	C89

Attention : il n'existe pas de standard GNU pour C. Ce que nous voulu faire passer comme information, c'est que les formats associés ne peuvent être utilisés que sur le compilateur gcc proposé par la « GNU Compiler Collection ».

C99 définit aussi deux « modificateurs » permettant d'obtenir des représentations alternatives pour certains éléments de formatage : les modificateurs E et O. Pour obtenir des affichages dépendants de la localisation, il est possible d'utiliser les séquences suivantes : %Ec, %EC, %Ex, %EX, %Ey, %EY. Pour obtenir d'autres formats numériques, il est possible d'utiliser les séquences suivantes : %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy. Nous vous laissons le soin de tester ces séquences.

Paramètres

strBuffer : un pointeur vers le bloc de mémoire dans lequel stocker la chaîne formatée produite. Attention, il est de votre responsabilité d'allouer ce bloc avec une taille suffisamment conséquente.
maxSize : la taille maximale du bloc de mémoire passé via le paramètre précédent. Attention à ne pas vous tromper entre la taille utilisée lors de l'allocation du bloc de mémoire et celle passée à ce paramètre : afin d'éviter toute erreur, le mieux serait certainement d'utiliser une constante (ou une macro, comme dans l'exemple ci-dessous).
format : un pointeur vers la chaîne de caractères décrivant le format à utiliser (voir le tableau ci-dessus pour la liste des possibilités de formatage).
pTime : un pointeur constant sur une structure de type struct tm contenant les informations de date et d'heure.

Valeur de retour

Si la taille du bloc de mémoire alloué est suffisamment grande pour contenir la chaîne produite (avec le caractère de terminaison de la chaîne '\0') alors la fonction renverra le nombre de caractères produit par ce formatage, mais sans le caractère '\0'.

Si, par contre, la taille de bloc de mémoire dans lequel produire la chaîne, était trop courte, alors la valeur retournée sera 0. Dans ce cas, vous devrait alors considérer le contenu de cette zone mémoire comme étant indéterminé.

Exemple de code

#include <stdio.h>
#include <time.h>

#define MAX_SIZE 80

int main( int argc, char * argv[] ) {

    time_t timestamp = time( NULL );
    struct tm * pTime = localtime( & timestamp );

    char buffer[ MAX_SIZE ];
    strftime( buffer, MAX_SIZE, "%d/%m/%Y %H:%M:%S", pTime );
    printf( "Date and french time : %s\n", buffer );
            
    return 0;
}

Voici le résultat produit par ce programme.

$> gcc -o Sample Sample.c
$> ./Sample
Date and french time : 22/11/2014 22:27:07
$>

Fonctions et types connexes

asctime
ctime
gmtime
localtime
struct tm
time
time_t

La fonction mktime

La structure timespec

Améliorations / Corrections

Fonction strftime

Entête à inclure

Fonction strftime

Paramètres

Valeur de retour

Exemple de code

Fonctions et types connexes