Clase CTime

  • Artículo

Representa una fecha y hora absolutas.

Sintaxis

class CTime

Miembros

Constructores públicos

Nombre Descripción
CTime::CTime Construye objetos CTime de varias maneras.

Métodos públicos

Nombre Descripción
CTime::Format Convierte un objeto CTime en una cadena con formato, en función de la zona horaria local.
CTime::FormatGmt Convierte un objeto CTime en una cadena con formato, en función de la hora UTC.
CTime::GetAsDBTIMESTAMP Convierte la información de tiempo almacenada en el objeto CTime en una estructura DBTIMESTAMP compatible con Win32.
CTime::GetAsSystemTime Convierte la información de tiempo almacenada en el objeto CTime en una estructura SYSTEMTIME compatible con Win32.
CTime::GetCurrentTime Crea un objeto CTime que representa la hora actual (función miembro estática).
CTime::GetDay Devuelve el día que representa el objeto CTime.
CTime::GetDayOfWeek Devuelve el día de la semana que representa el objeto CTime.
CTime::GetGmtTm Divide un objeto CTime en componentes, en función de la hora UTC.
CTime::GetHour Devuelve la hora representada por el objeto CTime.
CTime::GetLocalTm Divide un objeto CTime en componentes, en función de la zona horaria local.
CTime::GetMinute Devuelve el minuto representado por el objeto CTime.
CTime::GetMonth Devuelve el mes representado por el objeto CTime.
CTime::GetSecond Devuelve el segundo representado por el objeto CTime.
CTime::GetTime Devuelve un valor de __time64_t para el objeto CTime especificado.
CTime::GetYear Devuelve el año representado por el objeto CTime.
CTime::Serialize64 Serializa los datos hacia o desde un archivo.

Operadores

Nombre Descripción
operador + - Estos operadores agregan y restan objetos CTimeSpan y CTime.
operador +=, -= Estos operadores agregan y restan un objeto CTimeSpan a este objeto CTime.
operator = Operador de asignación.
operador ==, < , etc. Operadores de comparación.

Comentarios

CTime no tiene una clase base.

los valores CTime se basan en la hora universal coordinada (UTC), que es equivalente a la hora universal coordinada (hora media de Greenwich, GMT). Consulte Administración de hora para obtener información sobre cómo se determina la zona horaria.

Al crear un objeto CTime, establezca el parámetro nDST en 0 para indicar que la hora estándar está en vigor, en un valor mayor que 0 para indicar que el horario de verano está en vigor o en un valor menor que cero para que el código de la biblioteca en tiempo de ejecución de C calcule si el horario estándar o el horario de verano está en vigor. tm_isdst es un campo obligatorio. Si no se establece, su valor es indefinido y el valor devuelto de mktime es imprevisible. Si timeptr señala a una estructura tm devuelta por una llamada a asctime_s, _gmtime_s o localtime_s anterior, el campo tm_isdst contiene el valor correcto.

Una clase complementaria, CTimeSpan, representa un intervalo de tiempo.

Las clases CTime y CTimeSpan no están diseñadas para la derivación. Como no hay funciones virtuales, el tamaño de los objetos CTime y CTimeSpan es exactamente 8 bytes. La mayoría de las funciones miembro están insertadas.

Nota:

El límite de fecha superior es 31/12/3000. El límite inferior es 1/1/1970 12:00:00 a. m. GMT.

Para obtener más información sobre el uso de CTime, vea los artículos Fecha y hora, y Administración de hora en la referencia de Biblioteca en tiempo de ejecución.

Nota:

La estructura CTime cambió de MFC 7.1 a MFC 8.0. Si serializa una estructura CTime mediante el operador << de MFC 8.0 o una versión posterior, el archivo resultante no se podrá leer en versiones anteriores de MFC.

Requisitos

Encabezado: atltime.h

Operadores de comparación de CTime

Operadores de comparación.

bool operator==(CTime time) const throw();
bool operator!=(CTime time) const throw();
bool operator<(CTime time) const throw();
bool operator>(CTime time) const throw();
bool operator<=(CTime time) const throw();
bool operator>=(CTime time) const throw();

Parámetros

time
Objeto CTime que se va a comparar.

Valor devuelto

Estos operadores comparan dos veces absolutas y devuelven TRUE si la condición es true; en caso contrario, FALSE.

Ejemplo

CTime t1 = CTime::GetCurrentTime();
CTime t2 = t1 + CTimeSpan(0, 1, 0, 0);    // 1 hour later
ATLASSERT(t1 != t2);
ATLASSERT(t1 < t2);
ATLASSERT(t1 <= t2);

CTime::CTime

Crea un nuevo objeto CTime inicializado con la hora especificada.

CTime() throw();
CTime(__time64_t time) throw();
CTime(int nYear, int nMonth, int nDay,
      int nHour, int nMin, int nSec, int nDST = -1);
CTime(WORD wDosDate, WORD wDosTime, int nDST = -1);
CTime(const SYSTEMTIME& st, int nDST = - 1) throw();
CTime(const FILETIME& ft, int nDST = - 1);
CTime(const DBTIMESTAMP& dbts, int nDST = -1) throw();

Parámetros

timeSrc
Indica un objeto CTime que ya existe.

time
Valor de tiempo __time64_t, que es el número de segundos después del 1 de enero de 1970 UTC. Tenga en cuenta que esto se ajustará a la hora local. Por ejemplo, si está en Nueva York y crea un objeto CTime pasando un parámetro de 0, CTime::GetMonth devolverá 12.

nYear, nMonth, nDay, nHour, nMin, nSec
Indica los valores de fecha y hora que se van a copiar en el objeto CTime nuevo.

nDST
Indica si el horario de verano está en vigor. Uno de tres valores es posible:

  • nDST establecido en 0Standard time está en vigor.

  • nDST establecido en un valor mayor que 0Daylight savings time está en vigor.

  • nDST establecido en un valor menor que 0The default. Calcula automáticamente si el horario estándar o el horario de verano están en vigor.

wDosDate, wDosTime
Valores de fecha y hora de MS-DOS que se va a convertir en un valor de fecha y hora y copiar en el objeto CTime nuevo.

st
Estructura SYSTEMTIME que se va a convertir en un valor de fecha y hora y copiar en el objeto CTime nuevo.

ft
Estructura FILETIME que se va a convertir en un valor de fecha y hora y copiar en el objeto CTime nuevo.

dbts
Referencia a una estructura DBTIMESTAMP que contiene la hora local actual.

Comentarios

Cada constructor se describe a continuación:

  • CTime();Construye un objeto CTime sin inicializar. Este constructor permite definir matrices de objetos CTime. Debe inicializar estas matrices con horas válidas antes de usarlas.

  • CTime( const CTime& ); Construye un objeto CTime desde otro valor CTime.

  • CTime( __time64_t ); Construye un objeto CTime a partir de un tipo __time64_t. Este constructor espera una hora UTC y convierte el resultado en una hora local antes de almacenar el resultado.

  • CTime( int, int, ...); Construye un objeto CTime a partir de componentes de hora local con cada componente restringido a los siguientes intervalos:

    Componente Intervalo
    nYear 1970-3000
    nMonth 1-12
    nDay 1-31
    nHour 0-23
    nMin 0-59
    nSec 0-59

    Este constructor realiza la conversión adecuada a UTC. La versión de depuración de la biblioteca MFC (Microsoft Foundation Class) afirma si uno o varios de los componentes de tiempo están fuera del intervalo. Debe validar los argumentos antes de llamar. Este constructor espera una hora local.

  • CTime( WORD, WORD ); Construye un objeto CTime a partir de los valores de fecha y hora de MS-DOS especificados. Este constructor espera una hora local.

  • CTime( const SYSTEMTIME& ); Construye un objeto CTime a partir de una estructura SYSTEMTIME. Este constructor espera una hora local.

  • CTime( const FILETIME& ); Construye un objeto CTime a partir de una estructura FILETIME. Probablemente no use la inicialización de CTime FILETIME de forma directa. Si usa un objeto CFile para manipular un archivo, CFile::GetStatus recupera la marca de tiempo del archivo mediante un objeto CTime inicializado con una estructura FILETIME. Este constructor supone una hora basada en UTC y convierte automáticamente el valor en la hora local antes de almacenar el resultado.

    Nota:

    El constructor que usa el parámetro DBTIMESTAMP solo está disponible cuando se incluye OLEDB.h.

Para más información, consulte la estructura SYSTEMTIME y FILETIME en Windows SDK. Consulte también la entrada Fecha y hora de MS-DOS en Windows SDK.

Ejemplo

time_t osBinaryTime;  // C run-time time (defined in <time.h>)
time(&osBinaryTime) ;  // Get the current time from the 
                         // operating system.
CTime time1; // Empty CTime. (0 is illegal time value.)
CTime time2 = time1; // Copy constructor.
CTime time3(osBinaryTime);  // CTime from C run-time time
CTime time4(1999, 3, 19, 22, 15, 0); // 10:15PM March 19, 1999

CTime::Format

Llame a esta función miembro para crear una representación con formato del valor de fecha y hora.

CString Format(LPCTSTR pszFormat) const;
CString Format(UINT nFormatID) const;

Parámetros

pszFormat
Cadena de formato similar a la cadena de formato printf. Los códigos de formato, precedidos por un signo de porcentaje (%), se reemplazan por el componente CTime correspondiente. Otros caracteres de la cadena de formato se copian sin cambios en la cadena devuelta. Consulte la función en tiempo de ejecución strftime para obtener una lista de códigos de formato.

nFormatID
Id. de la cadena que identifica este formato.

Valor devuelto

CString que contiene la hora con formato.

Comentarios

Si el estado de este objeto CTime es null, el valor devuelto es una cadena vacía.

Este método produce una excepción si el valor de fecha y hora que se va a formatear no va desde la medianoche, del 1 de enero de 1970 hasta el 31 de diciembre de 3000 Hora universal coordinada (UTC).

Ejemplo

CTime t(1999, 3, 19, 22, 15, 0); 
// 10:15 PM March 19, 1999
CString s = t.Format(_T("%A, %B %d, %Y"));
ATLASSERT(s == _T("Friday, March 19, 1999"));

CTime::FormatGmt

Genera una cadena con formato que corresponde a este objeto CTime.

CString FormatGmt(LPCTSTR pszFormat) const;
CString FormatGmt(UINT nFormatID) const;

Parámetros

pszFormat
Especifica una cadena de formato similar a la cadena de formato printf. Consulte strftime de la función en tiempo de ejecución para obtener más información.

nFormatID
Id. de la cadena que identifica este formato.

Valor devuelto

CString que contiene la hora con formato.

Comentarios

El valor de hora no se convierte y, por tanto, refleja la hora UTC.

Este método produce una excepción si el valor de fecha y hora que se va a formatear no va desde la medianoche, del 1 de enero de 1970 hasta el 31 de diciembre de 3000 Hora universal coordinada (UTC).

Ejemplo

Vea el ejemplo de CTime::Format.

CTime::GetAsDBTIMESTAMP

Llame a esta función miembro para convertir la información de hora almacenada en el objeto CTime en una estructura DBTIMESTAMP compatible con Win32.

bool GetAsDBTIMESTAMP(DBTIMESTAMP& dbts) const throw();

Parámetros

dbts
Referencia a una estructura DBTIMESTAMP que contiene la hora local actual.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

Almacena la hora resultante en la estructura dbts a la que se hace referencia. La estructura de datos DBTIMESTAMP inicializada por esta función tendrá su miembro fraction establecido en cero.

Ejemplo

CTime t = CTime::GetCurrentTime();
DBTIMESTAMP ts;
t.GetAsDBTIMESTAMP(ts); // Retrieves the time in t into the ts structure

CTime::GetAsSystemTime

Llame a esta función miembro para convertir la información de hora almacenada en el objeto CTime en una estructura SYSTEMTIME compatible con Win32.

bool GetAsSystemTime(SYSTEMTIME& st) const throw();

Parámetros

timeDest
Referencia a una estructura SYSTEMTIME que guardará el valor de fecha y hora convertido del objeto CTime.

Valor devuelto

TRUE si es correcto; en caso contrario, FALSE.

Comentarios

GetAsSystemTime almacena la hora resultante en la estructura timeDest a la que se hace referencia. La estructura de datos SYSTEMTIME inicializada por esta función tendrá su miembro wMilliseconds establecido en cero.

Ejemplo

// Convert CTime to FILETIME
CTime time(CTime::GetCurrentTime());
SYSTEMTIME timeDest;
time.GetAsSystemTime(timeDest);
FILETIME fileTime;
::SystemTimeToFileTime(&timeDest, &fileTime);

CTime::GetCurrentTime

Devuelve un objeto CTime que representa el tiempo actual.

static CTime WINAPI GetCurrentTime() throw();

Comentarios

Devuelve la fecha y hora actuales del sistema en Hora universal coordinada (UTC).

Ejemplo

CTime t = CTime::GetCurrentTime();

CTime::GetDay

Devuelve el día que representa el objeto CTime.

int GetDay() const throw();

Valor devuelto

Devuelve el día del mes, en función de la hora local, en el intervalo de 1 a 31.

Comentarios

Esta función llama a GetLocalTm, que usa un búfer interno asignado estáticamente. Los datos de este búfer se sobrescriben debido a llamadas a otras funciones miembro CTime.

Ejemplo

// Example for CTime::GetDay, CTime::GetMonth, and CTime::GetYear
CTime t(1999, 3, 19, 22, 15, 0); // 10:15 PM March 19, 1999
ATLASSERT(t.GetDay() == 19);
ATLASSERT(t.GetMonth() == 3);
ATLASSERT(t.GetYear() == 1999);

CTime::GetDayOfWeek

Devuelve el día de la semana que representa el objeto CTime.

int GetDayOfWeek() const throw();

Valor devuelto

Devuelve el día de la semana en función de la hora local; 1 = domingo, 2 = lunes, hasta 7 = sábado.

Comentarios

Esta función llama a GetLocalTm, que usa un búfer interno asignado estáticamente. Los datos de este búfer se sobrescriben debido a llamadas a otras funciones miembro CTime.

Ejemplo

// Print out the day of the week using localized day name
UINT DayOfWeek[] = {
   LOCALE_SDAYNAME7,   // Sunday
   LOCALE_SDAYNAME1,   
   LOCALE_SDAYNAME2,
   LOCALE_SDAYNAME3,
   LOCALE_SDAYNAME4, 
   LOCALE_SDAYNAME5, 
   LOCALE_SDAYNAME6   // Saturday
};
TCHAR strWeekday[256];
CTime time(CTime::GetCurrentTime());   // Initialize CTime with current time
::GetLocaleInfo(LOCALE_USER_DEFAULT,   // Get string for day of the week from system
   DayOfWeek[time.GetDayOfWeek()-1],   // Get day of week from CTime
   strWeekday, sizeof(strWeekday) / sizeof(strWeekday[0]));
ATLTRACE(_T("%s\n"), strWeekday);               // Print out day of the week

CTime::GetGmtTm

Obtiene un struct tm que contiene una descomposición de la hora contenida en este objeto CTime.

struct tm* GetGmtTm(struct tm* ptm) const;

Parámetros

ptm
Apunta a un búfer que recibirá los datos de hora. Si este puntero es null, se produce una excepción.

Valor devuelto

Puntero a struct tm de relleno tal como se define en el archivo de inclusión TIME.H. Consulte gmtime, _gmtime32, _gmtime64 para el diseño de la estructura.

Comentarios

GetGmtTm devuelve UTC.

ptm no puede ser null. Si desea revertir al comportamiento anterior, en el que ptm podía ser null para indicar que se debe usar un búfer interno asignado estáticamente, entonces no defina _SECURE_ATL.

Ejemplo

// Compute difference between local time and GMT
CTime time(CTime::GetCurrentTime());
tm t1, t2;
time.GetLocalTm(&t1);
time.GetGmtTm(&t2);

ATLTRACE(_T("Difference between local time and GMT is %d hours.\n"), 
   t1.tm_hour - t2.tm_hour);

CTime::GetHour

Devuelve la hora representada por el objeto CTime.

int GetHour() const throw();

Valor devuelto

Devuelve la hora, en función de la hora local, en el intervalo de 0 a 23.

Comentarios

Esta función llama a GetLocalTm, que usa un búfer interno asignado estáticamente. Los datos de este búfer se sobrescriben debido a llamadas a otras funciones miembro CTime.

Ejemplo

// Example for CTime::GetHour, CTime::GetMinute, and CTime::GetSecond
CTime t(1999, 3, 19, 22, 15, 0); // 10:15 PM March 19, 1999
ATLASSERT(t.GetSecond() == 0);
ATLASSERT(t.GetMinute() == 15);
ATLASSERT(t.GetHour() == 22);

CTime::GetLocalTm

Obtiene una estructura struct tm que contiene una descomposición de la hora contenida en este objeto CTime.

struct tm* GetLocalTm(struct tm* ptm) const;

Parámetros

ptm
Apunta a un búfer que recibirá los datos de hora. Si este puntero es null, se produce una excepción.

Valor devuelto

Puntero a struct tm de relleno tal como se define en el archivo de inclusión TIME.H. Consulte gmtime, _gmtime32, _gmtime64 para el diseño de la estructura.

Comentarios

GetLocalTm devuelve la hora local.

ptm no puede ser null. Si desea revertir al comportamiento anterior, en el que ptm podía ser null para indicar que se debe usar un búfer interno asignado estáticamente, entonces no defina _SECURE_ATL.

Ejemplo

CTime t(1999, 3, 19, 22, 15, 0); // 10:15PM March 19, 1999
tm osTime;  // A structure containing time elements.
t.GetLocalTm(&osTime);
ATLASSERT(osTime.tm_mon == 2); // Note zero-based month!

CTime::GetMinute

Devuelve el minuto representado por el objeto CTime.

int GetMinute() const throw();

Valor devuelto

Devuelve el minuto, en función de la hora local, en el intervalo de 0 a 59.

Comentarios

Esta función llama a GetLocalTm, que usa un búfer interno asignado estáticamente. Los datos de este búfer se sobrescriben debido a llamadas a otras funciones miembro CTime.

Ejemplo

Consulte el ejemplo de GetHour.

CTime::GetMonth

Devuelve el mes representado por el objeto CTime.

int GetMonth() const throw();

Valor devuelto

Devuelve el mes, en función de la hora local, en el intervalo del 1 al 12 (1 = enero).

Comentarios

Esta función llama a GetLocalTm, que usa un búfer interno asignado estáticamente. Los datos de este búfer se sobrescriben debido a llamadas a otras funciones miembro CTime.

Ejemplo

Consulte el ejemplo de GetDay.

CTime::GetSecond

Devuelve el segundo representado por el objeto CTime.

int GetSecond() const throw();

Valor devuelto

Devuelve el segundo, según la hora local, en el intervalo de 0 a 59.

Comentarios

Esta función llama a GetLocalTm, que usa un búfer interno asignado estáticamente. Los datos de este búfer se sobrescriben debido a llamadas a otras funciones miembro CTime.

Ejemplo

Consulte el ejemplo de GetHour.

CTime::GetTime

Devuelve un valor de __time64_t para el objeto CTime especificado.

__time64_t GetTime() const throw();

Valor devuelto

GetTime devolverá el número de segundos entre el objeto CTime actual y el 1 de enero de 1970.

Ejemplo

CTime t(2005, 10, 20, 23, 50, 0); // 11:50 PM October 20, 2005
time_t osBinaryTime = t.GetTime();  // time_t defined in <time.h>

_tprintf_s(_T("time_t = %ld\n"), osBinaryTime);

CTime::GetYear

Devuelve el año representado por el objeto CTime.

int GetYear();

Valor devuelto

Devuelve el año, según la hora local, en el intervalo comprendido entre el 1 de enero de 1970 y el 18 de enero de 2038 (ambos incluidos).

Comentarios

Esta función llama a GetLocalTm, que usa un búfer interno asignado estáticamente. Los datos de este búfer se sobrescriben debido a llamadas a otras funciones miembro CTime.

Ejemplo

Consulte el ejemplo de GetDay.

CTime::operator =

Operador de asignación.

CTime& operator=(__time64_t time) throw();

Parámetros

time
Nuevo valor de fecha y hora.

Valor devuelto

Objeto CTime actualizado.

Comentarios

Este operador de asignación sobrecargado copia la hora de origen en este objeto CTime. El almacenamiento de tiempo interno en un objeto CTime es independiente de la zona horaria. La conversión de zona horaria no es necesaria durante la asignación.

CTime::operator +, -

Estos operadores agregan y restan objetos CTimeSpan y CTime.

CTime operator+(CTimeSpan timeSpan) const throw();
CTime operator-(CTimeSpan timeSpan) const throw();
CTimeSpan operator-(CTime time) const throw();

Parámetros

timeSpan
Objeto CTimeSpan que se va a agregar o restar.

time
Objeto CTime que se va a restar.

Valor devuelto

Objeto CTime o CTimeSpan que representa el resultado de la operación.

Comentarios

Los objetos CTime representan la hora absoluta, los objetos CTimeSpan representan el tiempo relativo. Los dos primeros operadores permiten agregar y restar objetos CTimeSpan a objetos CTime. El tercer operador permite restar un objeto CTime de otro para suspender un objeto CTimeSpan.

Ejemplo

CTime t1(1999, 3, 19, 22, 15, 0); // 10:15 PM March 19, 1999
CTime t2(1999, 3, 20, 22, 15, 0); // 10:15 PM March 20, 1999
CTimeSpan ts = t2 - t1;             // Subtract 2 CTimes
ATLASSERT(ts.GetTotalSeconds() == 86400L);
ATLASSERT((t1 + ts) == t2);       // Add a CTimeSpan to a CTime.
ATLASSERT((t2 - ts) == t1);       // Subtract a CTimeSpan from a CTime.

CTime::operator +=, -=

Estos operadores agregan y restan un objeto CTimeSpan a este objeto CTime.

CTime& operator+=(CTimeSpan span) throw();
CTime& operator-=(CTimeSpan span) throw();

Parámetros

span
Objeto CTimeSpan que se va a agregar o restar.

Valor devuelto

Objeto CTime actualizado.

Comentarios

Estos operadores permiten agregar y restar un objeto CTimeSpan a este objeto CTime.

Ejemplo

CTime t(1999, 3, 19, 22, 15, 0); // 10:15 PM March 19, 1999
t += CTimeSpan(0, 1, 0, 0);      // 1 hour exactly
ATLASSERT(t.GetHour() == 23);

CTime::Serialize64

Nota:

Este método solo está disponible en proyectos MFC.

Serializa los datos asociados a la variable miembro hacia o desde un archivo.

CArchive& Serialize64(CArchive& ar);

Parámetros

Ar
Objeto CArchive que quiere actualizar.

Valor devuelto

Objeto CArchive actualizado.

Consulte también

asctime_s, _wasctime_s
_ftime_s, _ftime32_s, _ftime64_s
gmtime_s, _gmtime32_s, _gmtime64_s
localtime_s, _localtime32_s, _localtime64_s
strftime, wcsftime, _strftime_l, _wcsftime_l
time, _time32, _time64
CTimeSpan (clase)
Gráfico de jerarquías
Clases compartidas de ATL y MFC