getdate - Zeit und Datum in Benutzerformat umwandeln

Definition

#include <time.h>

struct tm *getdate (const char *string);

extern int getdate_err;

Beschreibung

getdate() wandelt benutzerdefinierbare Datums- und/oder Zeitangaben aus string in eine tm-Struktur um. Die Strukturdeklaration befindet sich in der Datei time.h (siehe auch ctime()).

Zum Zerlegen und Interpretieren der Eingabezeichenkette werden benutzerdefinierte Schablonen verwendet. Diese Schablonen sind Textdateien, welche der Benutzer anlegt; diese Textdateien werden über die Umgebungsvariable DATEMSK angegeben. Jede Zeile der Schablone stellt eine akzeptierbare Datums- und/oder Zeitangabe dar; dabei werden einige der Felddeskriptoren verwendet, die auch das Kommando date verwendet. Die erste Zeile in der Schablone, die der Eingabespezifikation entspricht, wird zur Interpretation und Umwandlung in das interne Zeitformat verwendet. Ist die Operation erfolgreich, so liefert die Funktion getdate() einen Zeiger auf eine Struktur vom Typ tm zurück; ansonsten wird NULL zurückgegeben und die globale Variable getdate_err gesetzt.

Die folgenden Felddeskriptoren werden unterstützt:

%%	das Gleiche wie %
%a	abgekürzter Wochentagsname
%A	ausgeschriebener Wochentagsname
%b	abgekürzter Monatsname
%B	ausgeschriebener Monatsname
%c	lokale Datums- und Zeitdarstellung
%d	Monatstag (01 - 31; die führende 0 ist optional)
%e	das Gleiche wie %d
%D	Datum als %m/%d/%y
%h	abgekürzter Monatsname
%H	Stunde (00 - 23)
%I	Stunde (01 - 12)
%m	Monatsnummer (01 - 12)
%M	Minute (00 - 59)
%n	das Gleiche wie \n
%p	lokales Äquivalent zu AM oder PM
%r	Zeit als %I:%M:%S %p
%R	Zeit als %H:%M
%S	Sekunde (00-61). Schaltsekunden sind erlaubt, jedoch sind Folgeeffekte bei der Benutzung von Algorithmen nicht vorhersehbar.
%t	Tabulator einfügen
%T	Zeit als %H:%M:%S
%w	Wochentagsnummer (0 - 6; Sonntag = 0)
%x	lokale Datumsrepräsentation
%X	lokale Zeitrepräsentation
%y	Jahr im aktuellen Jahrhundert (00 - 99)
%Y	Jahr als ccyy (z.B. 1997)
%Z	Zeitzonenname oder keine Zeichen, wenn keine Zeitzone existiert. Wenn die Zeitzone unter %Z nicht die Zeitzone ist, die getdate() erwartet, tritt ein Eingabefehler auf. getdate() berechnet eine passende Zeitzone ausgehend von den Daten, die der Funktion übergeben wurden, (wie z.B Stunde, Tag und Monat).

Beim Vergleich zwischen der Schablone und der Eingabespezifikation unterscheidet getdate() nicht zwischen Klein- und Großbuchstaben.

Die Monats- und Wochentagsnamen können aus einer beliebigen Kombination von kleinen und großen Buchstaben bestehen. Der Benutzer kann bestimmen, dass die Angabe der Eingabezeit oder des Eingabedatums sprachabhängig ist. Dies geschieht durch Setzen der Werte LC_TIME und LC_CTYPE bei setlocale().

Die Deskriptoren, bei denen Ziffern angegeben werden müssen, haben höchstens zwei Stellen. Führende Nullen sind erlaubt, können aber auch weggelassen werden. Leerstellen in der Schablone oder in string werden ignoriert.

Die Felddeskriptoren %c, %x und %X werden abgewiesen, wenn sie unzulässige Felddeskriptoren enthalten.

Die folgenden Regeln gelten für die Umwandlung von Eingabespezifikationen in das interne Format:

• Wenn %Z angegeben wird, setzt getdate() die Elemente der tm-Struktur auf die aktuelle Zeit der angegebenen Zeitzone. Andernfalls wird die formatierte Zeit mit der aktuellen Ortszeit initialisiert, als ob localtime() ausgeführt worden wäre.

• Ist nur der Wochentag angegeben, wird der aktuelle Tag angenommen, wenn der angegebene Wochentag identisch mit dem aktuellen Tag ist. Liegt der angegebene Tag vor dem aktuellen, wird der Wochentag aus der nächsten Woche genommen.

• Ist nur der Monat angegeben, wird der aktuelle Monat angenommen, wenn der angegebene Monat gleich dem aktuellen Monat ist. Ist der angegebene Monat kleiner als der aktuelle Monat, wird das nächste Jahr angenommen, wenn ansonsten kein Jahr angegeben ist. (Der erste Tag des Monats wird angenommen, wenn kein Tag angegeben ist.)

• Wird keine Stunde, Minute und Sekunde angegeben, wird die aktuelle Stunde, Minute und Sekunde übernommen.

• Wird kein Datum angegeben, wird der aktuelle Tag angenommen, wenn die angegebene Stunde größer als die aktuelle Stunde ist. Ist die angegebene Stunde kleiner als die aktuelle, so wird der nächste Tag angenommen.

getdate() benutzt die externe Variable oder das Makro getdate_err, um das Fehlergewicht zurückzugeben.

Returnwert

Zeiger auf eine Struktur tm

bei Erfolg.

Nullzeiger

bei Fehler. getdate_err wird gesetzt, um den Fehler anzuzeigen.

Fehler

getdate() schlägt fehlt, wenn einer der folgenden Fehler auftritt. Die Fehlergewichte werden in getdate_err zurückgeliefert. Der Inhalt von errno ist dabei ohne Bedeutung.

1

Die Umgebungsvariable DATEMSK ist undefiniert oder null.

2

Die Schablonendatei kann nicht zum Lesen geöffnet werden.

3

Der Dateistatus konnte nicht gelesen werden.

4

Die Schablonendatei ist keine reguläre Datei.

5

Fehler trat beim Lesen der Schablonendatei auf.

6

malloc() konnte nicht erfolgreich ausgeführt werden, da zu wenig Speicherplatz verfügbar war.

7

Es gibt keine Zeile aus der Schablonendatei, die der Eingabe entspricht.

8

Das Eingabeformat ist ungültig, z.B. February 31, oder es wurde eine Zeit angegeben, die nicht in einem Typ time_t dargestellt werden kann; t time_t enthält die Zeit in Sekunden seit 00:00:00 UTC, was dem 1. Januar 1970 entspricht.

Hinweise

Nachfolgende Aufrufe von getdate() ändern den Inhalt von getdate_err.

Die Deklaration der externen Variablen getdate_err ist in der Include-Datei time.h e enthalten. getdate_err sollte daher nicht explizit im Programm deklariert werden, sondern es sollte time.h eingefügt werden.

Daten vor 1970 und nach 2037 sind ungültig.

Beispiel 1

Möglicher Inhalt einer Schablone:

%m
%A %B %d, %Y, %H:%M:%S
%A
%B
%m/%d/%y %I %p
%d,%m,%Y %H:%M
at %A the %dst of %B in %Y
run job at %I %p,%B %dnd
%A den %d. %B %Y %H.%M Uhr

Beispiel 2

Einige Beispiele für gültige Eingabespezifikationen für die Schablone aus Beispiel 1:

getdate("10/1/87 4 PM");
getdate("Friday");
getdate("Friday September 19 1987, 10:30:30");
getdate("24,9,1986 10:30");
getdate("at monday the 1st of december in 1986");
getdate("run job at 3 PM, december 2nd");

Wenn die Umgebungsvariable LC_TIME gesetzt ist bzw. LANG auf german gesetzt wird, ist folgende Angabe gültig:

getdate("Freitag den 10. Oktober 1986 10.30 Uhr") ; 

Beispiel 3

Lokale Zeit- und Datumsangaben werden ebenfalls unterstützt. Beispiel 3 zeigt, wie lokale Datums- und Zeitangaben in Schablonen definiert werden können.

Aufruf	Zeile in Schablonendatei
getdate("11/27/86");	%m/%d/%y
getdate("27.11.86");	%d.%m.%y
getdate("86-11-27");	%y-%m-%d
getdate("Friday 12:00:00");	%A %H:%M:%S

Beispiel 4

Die folgenden Beispiele verdeutlichen die obigen Regeln. Es wird angenommen, dass das aktuelle Datum Montag 22. September 12:19:47 EDT 1986 ist und die Umgebungsvariablen LANG und LC_TIME nicht gesetzt sind.

Eingabe	Zeile in Schablonendatei	Datum
Mon	%a	Mon Sep 22 12:19:48 EDT 1986
Sun	%a	Sun Sep 28 12:19:49 EDT 1986
Fri	%a	Fri Sep 26 12:19:49 EDT 1986
September	%B	Mon Sep 1:19:49 EDT 1986
January	%B	Thu Jan 1:19:49 EST 1987
December	%B	Mon Dec 1:19:49 EST 1986
Sep Mon	%b %a	Mon Sep 1:19:50 EDT 1986
Jan Fri	%b %a	Fri Jan 2 12:19:50 EST 1987
Dec Mon	%b %a	Mon Dec 1:19:50 EST 1986
Jan Wed 198	%b %a %Y	Wed Jan 4 12:19:51 EST 1989
Fri 9	%a %H	Fri Sep 26 09:00:00 EDT 1986
Feb 10:30	%b %H:%S	Sun Feb 1 10:00:30 EST 1987
10:30	%H:%M	Tue Sep 23 10:30:00 EDT 1986
13:30	%H:%M	Mon Sep 22 13:30:00 EDT 1986

Siehe auch

ctime(), localtime(), setlocale(), strftime(), times(), time.h