Classe CTime

Artigo
10/12/2023

Representa uma data e hora absolutas.

Sintaxe

class CTime

Membros

Construtores públicos

Nome	Descrição
CTime::CTime	Constrói objetos `CTime` de várias maneiras.

Métodos públicos

Nome	Descrição
CTime::Format	Converte um objeto `CTime` em uma cadeia de caracteres formatada – com base no fuso horário local.
CTime::FormatGmt	Converte um objeto `CTime` em uma cadeia de caracteres formatada – com base no UTC.
CTime::GetAsDBTIMESTAMP	Converte as informações de tempo armazenadas no objeto `CTime` em uma estrutura DBTIMESTAMP compatível com Win32.
CTime::GetAsSystemTime	Converte as informações de tempo armazenadas no objeto `CTime` em uma estrutura SYSTEMTIME compatível com Win32.
CTime::GetCurrentTime	Cria um objeto `CTime` que representa a hora atual (função de membro estático).
CTime::GetDay	Retorna o dia representado pelo objeto `CTime`.
CTime::GetDayOfWeek	Obtém o dia da semana representado pelo objeto `CTime`.
CTime::GetGmtTm	Divide um objeto `CTime` em componentes – com base em UTC.
CTime::GetHour	Retorna a hora representada pelo objeto `CTime`.
CTime::GetLocalTm	Divide um objeto `CTime` em componentes – com base no fuso horário local.
CTime::GetMinute	Retorna o minuto representado pelo objeto `CTime`.
CTime::GetMonth	Retorna o mês representado pelo objeto `CTime`.
CTime::GetSecond	Retorna o segundo representado pelo objeto `CTime`.
CTime::GetTime	Retorna um valor __time64_t para o objetivo `CTime` fornecido.
CTime::GetYear	Retorna o ano representado pelo objeto `CTime`.
CTime::Serialize64	Serializa dados de um arquivo ou para ele.

Operadores

Nome	Descrição
operator + -	Esses operadores adicionam e subtraem objetos `CTimeSpan` e `CTime`.
operador +=, -=	Esses operadores adicionam e subtraem um objeto `CTimeSpan` de um objeto `CTime` e para ele.
operador =	O operador de atribuição.
operator ==, < , etc.	Operadores de comparação.

Comentários

CTime não tem uma classe base.

Os valores CTime são baseados no UTC (tempo universal coordenado), que é equivalente ao Tempo Universal Coordenado (Greenwich Mean Time, GMT). Confira Gerenciamento de Tempo para obter informações sobre como o fuso horário é determinado.

Quando você criar um objeto CTime, defina o parâmetro nDST como 0 para indicar que a hora padrão está em vigor ou para um valor maior que 0 para indicar que o horário de verão está em vigor ou para um valor menor que zero para que o código da biblioteca em tempo de execução C compute se o horário padrão ou o horário de verão está em vigor. tm_isdst é um campo obrigatório. Se não definido, seu valor será indefinido e o valor retornado de mktime será imprevisível. Se timeptr apontar para uma estrutura tm retornada por uma chamada anterior para asctime_s, _gmtime_s ou localtime_s, o campo tm_isdst conterá o valor correto.

Uma classe complementar, CTimeSpan, representa um intervalo de tempo.

As classes CTime e CTimeSpan não foram projetadas para derivação. Como não há funções virtuais, o tamanho dos objetos CTime e CTimeSpan são exatamente 8 bytes. A maioria das funções de membro está embutida.

Observação

O limite máximo de data é 31/12/3000. O limite inferior é 1/1/1970 12:00:00 GMT.

Para obter mais informações sobre como usar CTime, confira os artigos Data e hora, e Gerenciamento de tempo na Referência da Biblioteca de Run-Time.

Observação

A estrutura CTime foi alterada da MFC 7.1 para a MFC 8.0. Se você serializar uma estrutura CTime usando o operador << em MFC 8.0 ou uma versão posterior, o arquivo resultante não será legível em versões mais antigas da MFC.

Requisitos

Cabeçalho: atltime.h

Operadores de comparação CTime

Operadores de comparação.

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
O objeto CTime a ser comparado.

Valor de Devolução

Esses operadores comparam duas vezes absolutas e retornam TRUE se a condição for verdadeira; caso contrário, FALSE.

Exemplo

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

Cria um novo objeto CTime inicializado com a 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 um objeto CTime que já existe.

time
Um valor temporal de __time64_t, que é o número de segundos após 1º de janeiro de 1970 UTC. Observe que isso será ajustado para a hora local. Por exemplo, se você estiver em Nova York e criar um objeto CTime passando um parâmetro de 0, CTime::GetMonth retornará 12.

nYear, nMonth, nDay, nHour, nMin, nSec
Indica os valores de data e hora a serem copiados para o novo objeto CTime.

nDST
Indica se o horário de verão está em vigor. Pode ter um dos três valores:

nDST definido como o horário padrão está em vigor.
nDST definido como um valor maior que o horário de verão está em vigor.
nDST definido como um valor menor que O padrão. Calcula automaticamente se o horário padrão ou o horário de verão está em vigor.

wDosDate, wDosTime
Os valores de data e hora do MS-DOS a serem convertidos em um valor de data/hora e copiados para o novo objeto CTime.

St
Uma estrutura SYSTEMTIME a ser convertida em um valor de data/hora e copiada para o novo objeto CTime.

ft
Uma estrutura FILETIME a ser convertida em um valor de data/hora e copiada para o novo objeto CTime.

dbts
Uma referência a uma estrutura DBTIMESTAMP que contém a hora local atual.

Comentários

Cada construtor é descrito abaixo:

CTime(); Constrói um objeto CTime não inicializado. Esse construtor permite que você defina matrizes de objetos CTime. Você deve inicializar essas matrizes com tempos válidos antes de usar.
CTime( const CTime& ); Constrói um objeto CTime com base em outro valor CTime.
CTime( __time64_t ); Constrói um objeto CTime com base em um tipo __time64_t. Esse construtor espera uma hora em UTC e converte o resultado em uma hora local antes de armazenar o resultado.
CTime( int, int, ...); Constrói um objeto CTime de componentes de horário local com cada componente restrito aos seguintes intervalos:

Componente Intervalo

nYear 1970-3000

nMonth 1-12

nDay 1-31

nHour 0-23

nMin 0-59

nSec 0-59

Esse construtor faz a conversão apropriada para UTC. A versão de depuração da biblioteca Microsoft Foundation Class afirma se um ou mais componentes de tempo estão fora do intervalo. Você deve validar os argumentos antes de chamar. Este construtor espera uma hora local.
CTime( WORD, WORD ); Constrói um objeto CTime com base nos valores de data e hora do MS-DOS especificados. Este construtor espera uma hora local.
CTime( const SYSTEMTIME& ); Constrói um objeto CTime a partir de uma estrutura SYSTEMTIME. Este construtor espera uma hora local.
CTime( const FILETIME& ); Constrói um objeto CTime a partir de uma estrutura FILETIME. Provavelmente, você não usará a inicialização CTime FILETIME diretamente. Se você usar um objeto CFile para manipular um arquivo, CFile::GetStatus recuperará o carimbo de data/hora do arquivo para você por meio de um objeto CTime inicializado com uma estrutura FILETIME. Esse construtor pressupõe uma hora com base em UTC e converte automaticamente o valor em hora local antes de armazenar o resultado.

Observação

O construtor que usa o parâmetro DBTIMESTAMP só estará disponível quando o OLEDB.h estiver incluído.

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

Para obter mais informações, confira a estrutura SYSTEMTIME e FILETIME no SDK do Windows. Confira também a entrada Data e hora do MS-DOS no SDK do Windows.

Exemplo

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

Chame essa função de membro para criar uma representação formatada do valor de data e hora.

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

Parâmetros

pszFormat
Uma cadeia de caracteres de formatação semelhante à cadeia de caracteres de formatação printf. Os códigos de formatação, precedidos por um sinal de porcentagem (%), são substituídos pelo componente CTime correspondente. Outros caracteres na cadeia de caracteres de formatação são copiados sem alteração para a cadeia de caracteres retornada. Confira a função de tempo de execução strftime para obter uma lista de códigos de formatação.

nFormatID
A ID da cadeia de caracteres que identifica esse formato.

Valor de Devolução

Um CString que contém o tempo formatado.

Comentários

Se o status desse objeto CTime for nulo, o valor retornado será uma cadeia de caracteres vazia.

Esse método gerará uma exceção se o valor de data e hora para o formato não variar de meia-noite, 1º de janeiro de 1970 a 31 de dezembro de 3000, UTC (Hora Coordenada Universal).

Exemplo

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

Gera uma cadeia de caracteres formatada que corresponde a esse objeto CTime.

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

Parâmetros

pszFormat
Especifica uma cadeia de caracteres de formatação semelhante à cadeia de caracteres de formatação printf. Confira a função de tempo de execução strftime para obter detalhes.

nFormatID
A ID da cadeia de caracteres que identifica esse formato.

Valor de Devolução

Um CString que contém o tempo formatado.

Comentários

O valor temporal não é convertido e, portanto, reflete o UTC.

Esse método gerará uma exceção se o valor de data e hora para o formato não variar de meia-noite, 1º de janeiro de 1970 a 31 de dezembro de 3000, UTC (Hora Coordenada Universal).

Exemplo

Confira o exemplo de CTime::Format.

CTime::GetAsDBTIMESTAMP

Chame essa função membro para converter as informações de tempo armazenadas no objeto CTime em uma estrutura DBTIMESTAMP compatível com Win32.

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

Parâmetros

dbts
Uma referência a uma estrutura DBTIMESTAMP que contém a hora local atual.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Armazena o tempo resultante na estrutura dbts referenciada. A estrutura de dados DBTIMESTAMP inicializada por essa função terá seu membro fraction definido como zero.

Exemplo

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

CTime::GetAsSystemTime

Chame essa função membro para converter as informações de tempo armazenadas no objeto CTime em uma estrutura SYSTEMTIME compatível com Win32.

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

Parâmetros

timeDest
Uma referência a uma estrutura SYSTEMTIME que conterá o valor de data/hora convertido do objeto CTime.

Valor de Devolução

TRUE se tiver êxito; caso contrário, FALSE.

Comentários

GetAsSystemTime armazena o tempo resultante na estrutura timeDest referenciada. A estrutura de dados SYSTEMTIME inicializada por essa função terá seu membro wMilliseconds definido como zero.

Exemplo

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

CTime::GetCurrentTime

Retorna um objeto CTime que representa a hora atual.

static CTime WINAPI GetCurrentTime() throw();

Comentários

Retorna a data e a hora atuais do sistema no UTC (Tempo Universal Coordenado).

Exemplo

CTime t = CTime::GetCurrentTime();

CTime::GetDay

Retorna o dia representado pelo objeto CTime.

int GetDay() const throw();

Valor de Devolução

Retorna o dia do mês, com base na hora local, no intervalo de 1 a 31.

Comentários

Essa função chama GetLocalTm, que usa um buffer interno alocado estaticamente. Os dados nesse buffer são substituídos devido a chamadas para outras funções membro CTime.

Exemplo

// 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

Obtém o dia da semana representado pelo objeto CTime.

int GetDayOfWeek() const throw();

Valor de Devolução

Retorna o dia da semana com base na hora local; 1 = Domingo, 2 = Segunda-feira, a 7 = Sábado.

Comentários

Essa função chama GetLocalTm, que usa um buffer interno alocado estaticamente. Os dados nesse buffer são substituídos devido a chamadas para outras funções membro CTime.

Exemplo

// 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

Obtém um struct tm que contém uma decomposição do tempo contido neste objeto CTime.

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

Parâmetros

ptm
Aponta para um buffer que receberá os dados de hora. Se esse ponteiro for NULL, uma exceção será gerada.

Valor de Devolução

Um ponteiro para um struct tm preenchido conforme definido no arquivo de inclusão TIME.H. Confira gmtime, _gmtime32, _gmtime64 para o layout da estrutura.

Comentários

GetGmtTm retorna UTC.

ptm não pode ser NULL. Se você quiser reverter para o comportamento antigo, no qual o ptm pode ser NULL para indicar que um buffer interno alocado estaticamente deve ser usado, indefina _SECURE_ATL.

Exemplo

// 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

Retorna a hora representada pelo objeto CTime.

int GetHour() const throw();

Valor de Devolução

Retorna a hora, com base na hora local, no intervalo de 0 a 23.

Comentários

Essa função chama GetLocalTm, que usa um buffer interno alocado estaticamente. Os dados nesse buffer são substituídos devido a chamadas para outras funções membro CTime.

Exemplo

// 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

Obtém um struct tm que contém uma decomposição do tempo contido neste objeto CTime.

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

Parâmetros

ptm
Aponta para um buffer que receberá os dados de hora. Se esse ponteiro for NULL, uma exceção será gerada.

Valor de Devolução

Um ponteiro para um struct tm preenchido conforme definido no arquivo de inclusão TIME.H. Confira gmtime, _gmtime32, _gmtime64 para o layout da estrutura.

Comentários

GetLocalTm retorna hora local.

Exemplo

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

Retorna o minuto representado pelo objeto CTime.

int GetMinute() const throw();

Valor de Devolução

Retorna o minuto, com base no horário local, no intervalo de 0 a 59.

Comentários

Essa função chama GetLocalTm, que usa um buffer interno alocado estaticamente. Os dados nesse buffer são substituídos devido a chamadas para outras funções membro CTime.

Exemplo

Confira o exemplo de GetHour.

CTime::GetMonth

Retorna o mês representado pelo objeto CTime.

int GetMonth() const throw();

Valor de Devolução

Retorna o mês, com base na hora local, no intervalo de 1 a 12 (1 = janeiro).

Comentários

Essa função chama GetLocalTm, que usa um buffer interno alocado estaticamente. Os dados nesse buffer são substituídos devido a chamadas para outras funções membro CTime.

Exemplo

Confira o exemplo de GetDay.

CTime::GetSecond

Retorna o segundo representado pelo objeto CTime.

int GetSecond() const throw();

Valor de Devolução

Retorna o segundo, com base no horário local, no intervalo de 0 a 59.

Comentários

Essa função chama GetLocalTm, que usa um buffer interno alocado estaticamente. Os dados nesse buffer são substituídos devido a chamadas para outras funções membro CTime.

Exemplo

Confira o exemplo de GetHour.

CTime::GetTime

Retorna um valor __time64_t para o objetivo CTime fornecido.

__time64_t GetTime() const throw();

Valor de Devolução

GetTime retornará o número de segundos entre o objeto atual CTime e 1º de janeiro de 1970.

Exemplo

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

Retorna o ano representado pelo objeto CTime.

int GetYear();

Valor de Devolução

Retorna o ano, com base na hora local, no intervalo de 1º de janeiro de 1970 até 18 de janeiro de 2038 (inclusive).

Comentários

Essa função chama GetLocalTm, que usa um buffer interno alocado estaticamente. Os dados nesse buffer são substituídos devido a chamadas para outras funções membro CTime.

Exemplo

Confira o exemplo de GetDay.

CTime::operator =

O operador de atribuição.

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

Parâmetros

time
O novo valor de data/hora.

Valor de Devolução

O objeto atualizado CTime.

Comentários

Esse operador de atribuição sobrecarregado copia o tempo de origem para esse objeto CTime. O armazenamento de tempo interno em um objeto CTime é independente do fuso horário. A conversão de fuso horário não é necessária durante a atribuição.

CTime::operator +, -

Esses operadores adicionam e subtraem objetos CTimeSpan e CTime.

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

Parâmetros

timeSpan
O objeto CTimeSpan a ser adicionado ou subtraído.

time
O objeto CTime a ser subtraído.

Valor de Devolução

Um objeto CTime ou CTimeSpan que representa o resultado da validação.

Comentários

Os objetos CTime representam o tempo absoluto, e os objetos CTimeSpan representam o tempo relativo. Os dois primeiros operadores permitem adicionar e subtrair objetos CTimeSpan de e para objetos CTime. O terceiro operador permite que você subtraia um objeto CTime de outro para produzir um objeto CTimeSpan.

Exemplo

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 +=, -=

Esses operadores adicionam e subtraem um objeto CTimeSpan de um objeto CTime e para ele.

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

Parâmetros

span
O objeto CTimeSpan a ser adicionado ou subtraído.

Valor de Devolução

O objeto atualizado CTime.

Comentários

Esses operadores permitem adicionar e subtrair um objeto CTimeSpan de e para este objeto CTime.

Exemplo

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

Observação

Esse método só está disponível em projetos MFC.

Serializa os dados associados à variável de membro de um arquivo morto ou para ele.

CArchive& Serialize64(CArchive& ar);

Parâmetros

ar
O objeto CArchive que você deseja atualizar.

Valor de Devolução

O objeto atualizado CArchive.

Confira também

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
Classe CTimeSpan
Gráfico da hierarquia
Classes compartilhadas ATL/MFC

Compartilhar via

Classe CTime

Sintaxe

Membros

Construtores públicos

Métodos públicos

Operadores

Comentários

Requisitos

Operadores de comparação CTime

Parâmetros

Valor de Devolução

Exemplo

CTime::CTime

Parâmetros

Comentários

Exemplo

CTime::Format

Parâmetros

Valor de Devolução

Comentários

Exemplo

CTime::FormatGmt

Parâmetros

Valor de Devolução

Comentários

Exemplo

CTime::GetAsDBTIMESTAMP

Parâmetros

Valor de Devolução

Comentários

Exemplo

CTime::GetAsSystemTime

Parâmetros

Valor de Devolução

Comentários

Exemplo

CTime::GetCurrentTime

Comentários

Exemplo

CTime::GetDay

Valor de Devolução

Comentários

Exemplo

CTime::GetDayOfWeek

Valor de Devolução

Comentários

Exemplo

CTime::GetGmtTm

Parâmetros

Valor de Devolução

Comentários

Exemplo

CTime::GetHour

Valor de Devolução

Comentários

Exemplo

CTime::GetLocalTm

Parâmetros

Valor de Devolução

Comentários

Exemplo

CTime::GetMinute

Valor de Devolução

Comentários

Exemplo

CTime::GetMonth

Valor de Devolução

Comentários

Exemplo

CTime::GetSecond

Valor de Devolução

Comentários

Exemplo

CTime::GetTime

Valor de Devolução

Exemplo

CTime::GetYear

Valor de Devolução

Comentários