Classe CTime

Representa uma data e hora absolutas.

Sintaxe

class CTime

Membros

Construtores Públicos

Métodos Públicos

Operadores

Observações

CTime não tem uma classe base.

CTime os valores baseiam-se no tempo universal coordenado (UTC), que é equivalente ao tempo universal coordenado (Greenwich Mean Time, GMT). Consulte Gestão do Tempo para informações sobre como o fuso horário é determinado.

Ao criar um CTime objeto, defina o nDST parâmetro para 0 para indicar que a hora padrão está em vigor, ou para um valor maior que 0 para indicar que a hora de verão está em vigor, ou para um valor inferior a zero para que o código da biblioteca de tempo de execução C calcule se a hora padrão ou a hora de verão está em vigor. tm_isdst é um campo obrigatório. Se não for definido, o seu valor é indefinido e o valor de retorno do mktime é imprevisível. Se timeptr apontar para uma estrutura tm devolvida por uma chamada anterior para asctime_s, _gmtime_s ou localtime_s, o tm_isdst campo contém o valor correto.

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

As CTime classes e CTimeSpan não foram concebidas para derivação. Como não existem funções virtuais, o tamanho dos CTime objetos e CTimeSpan é exatamente 8 bytes. A maioria das funções dos membros é inline.

Para mais informações sobre a utilização CTimede , consulte os artigos Data e Hora, e Gestão do Tempo na Run-Time Library Reference.

Requerimentos

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 CTime objeto a comparar.

Valor de retorno

Estes operadores comparam dois tempos absolutos e devolvem TRUE se a condição for verdadeira; caso contrário, FALSO.

Example

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 CTime objeto inicializado com o tempo especificado.

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 CTime objeto que já existe.

time
Um __time64_t valor temporal, que é o número de segundos após 1 de janeiro de 1970 UTC. Note que isto será ajustado à sua hora local. Por exemplo, se estiver em Nova Iorque e criar um CTime objeto passando um parâmetro 0, CTime::GetMonth devolverá 12.

nAno, nMês, nDia, nHora, nMin, nSec
Indica os valores de data e hora a serem copiados para o novo CTime objeto.

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

• O nDST definido para 0 hora padrão está em vigor.

• O nDST definido para um valor superior a 0 no horário de verão está em vigor.

• nDST definido para um valor inferior a 0O padrão. Calcula automaticamente se o horário padrão ou o horário de verão está em vigor.

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

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

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

DBTS
Uma referência a uma estrutura DBTIMESTAMP contendo a hora local atual.

Observações

Cada construtor é descrito abaixo:

• CTime(); Constrói um objeto não inicializado CTime . Este construtor permite definir CTime arrays de objetos. Deves inicializar esses arrays com tempos válidos antes de usares.

• CTime( const CTime& ); Constrói um CTime objeto a partir de outro CTime valor.

• CTime( __time64_t ); Constrói um CTime objeto a partir de um tipo __time64_t . Este construtor espera uma hora UTC e converte o resultado para uma hora local antes de o armazenar.

• CTime( int, int, ...); Constrói um CTime objeto a partir de componentes de tempo local, com cada componente restrito aos seguintes intervalos:

  Componente	Alcance
  nAno	1970-3000
  nMonth	1-12
  nDay	1-31
  nHour	0-23
  nMin	0-59
  nSec	0-59

  Este construtor faz a conversão apropriada para UTC. A versão Debug da Microsoft Foundation Class Library verifica se um ou mais componentes de tempo estão fora do alcance. Tens de validar os argumentos antes de ligar. Este construtor espera uma hora local.

• CTime( WORD, WORD ); Constrói um CTime objeto a partir dos valores especificados de MS-DOS data e hora. Este construtor espera uma hora local.

• CTime( const SYSTEMTIME& ); Constrói um CTime objeto a partir de uma SYSTEMTIME estrutura. Este construtor espera uma hora local.

• CTime( const FILETIME& ); Constrói um CTime objeto a partir de uma FILETIME estrutura. Muito provavelmente não vais usar CTime FILETIME a inicialização diretamente. Se usares um CFile objeto para manipular um ficheiro, CFile::GetStatus recupera o carimbo temporal do ficheiro através de um CTime objeto inicializado com uma FILETIME estrutura. Este construtor assume um tempo baseado no UTC e converte automaticamente o valor para hora local antes de armazenar o resultado.

  Observação

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

Para mais informações, consulte as estruturas SYSTEMTIME e FILETIME no SDK do Windows. Veja também a entrada MS-DOS Data e Hora no SDK do Windows.

Example

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::Formato

Chame esta função membro para criar uma representação formatada do valor data-hora.

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

Parâmetros

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

nFormatID
O ID da cadeia que identifica este formato.

Valor de retorno

Um CString que contém a hora formatada.

Observações

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

Este método lança uma exceção se o valor data-hora para o formato não variar da meia-noite de 1 de janeiro de 1970 até 31 de dezembro de 3000 Hora Universal Coordenada (UTC).

Example

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 formatada que corresponde a este CTime objeto.

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

Parâmetros

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

nFormatID
O ID da cadeia que identifica este formato.

Valor de retorno

Um CString que contém a hora formatada.

Observações

O valor do tempo não é convertido e, por isso, reflete o UTC.

Este método lança uma exceção se o valor data-hora para o formato não variar da meia-noite de 1 de janeiro de 1970 até 31 de dezembro de 3000 Hora Universal Coordenada (UTC).

Example

Veja o exemplo para CTime::Format.

CTime::GetAsDBTIMESTAMP

Chame esta função membro para converter a informação de tempo armazenada no CTime objeto para uma estrutura DBTIMESTAMP compatível com Win32.

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

Parâmetros

DBTS
Uma referência a uma estrutura DBTIMESTAMP contendo a hora local atual.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

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

Example

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

CTime::GetAsSystemTime.

Chame esta função membro para converter a informação de tempo armazenada no CTime objeto para uma estrutura SYSTEMTIME compatível com Win32.

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

Parâmetros

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

Valor de retorno

VERDADEIRO se for bem-sucedido; caso contrário, FALSO.

Observações

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

Example

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

CTime::GetCurrentTime

Devolve um CTime objeto que representa o tempo atual.

static CTime WINAPI GetCurrentTime() throw();

Observações

Devolve a data e hora atuais do sistema em Tempo Universal Coordenado (UTC).

Example

CTime t = CTime::GetCurrentTime();   

CTime::GetDay

Devolve o dia representado pelo CTime objeto.

int GetDay() const throw();

Valor de retorno

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

Observações

Esta função chama GetLocalTm, que utiliza um buffer interno alocado estaticamente. Os dados neste buffer são sobrescritos devido a chamadas a outras CTime funções membros.

Example

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

Devolve o dia da semana representado pelo CTime objeto.

int GetDayOfWeek() const throw();

Valor de retorno

Devolve o dia da semana com base na hora local; 1 = domingo, 2 = segunda-feira, às 7 = sábado.

Observações

Esta função chama GetLocalTm, que utiliza um buffer interno alocado estaticamente. Os dados neste buffer são sobrescritos devido a chamadas a outras CTime funções membros.

Example

// 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 uma estrutura tm que contém uma decomposição do tempo contido neste CTime objeto.

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

Parâmetros

PTM
Aponta para um buffer que receberá os dados de tempo. Se este ponteiro for NULL, é lançada uma exceção.

Valor de retorno

Um apontador para uma struct preenchida tm , conforme definido no ficheiro include TIME.H. Veja gmtime, _gmtime32 _gmtime64 para a disposição da estrutura.

Observações

GetGmtTm devolve o UTC.

O ptm não pode ser NULL. Se quiseres reverter ao comportamento antigo, em que o ptm podia ser NULL para indicar que um buffer interno e alocado estaticamente deve ser usado, então desdefine _SECURE_ATL.

Example

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

Devolve a hora representada pelo CTime objeto.

int GetHour() const throw();

Valor de retorno

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

Observações

Esta função chama GetLocalTm, que utiliza um buffer interno alocado estaticamente. Os dados neste buffer são sobrescritos devido a chamadas a outras CTime funções membros.

Example

// 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 uma estrutura tm contendo uma decomposição do tempo contido neste CTime objeto.

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

Parâmetros

PTM
Aponta para um buffer que receberá os dados de tempo. Se este ponteiro for NULL, é lançada uma exceção.

Valor de retorno

Um apontador para uma struct preenchida tm , conforme definido no ficheiro include TIME.H. Veja gmtime, _gmtime32 _gmtime64 para a disposição da estrutura.

Observações

GetLocalTm Retorna a hora local.

O ptm não pode ser NULL. Se quiseres reverter ao comportamento antigo, em que o ptm podia ser NULL para indicar que um buffer interno e alocado estaticamente deve ser usado, então desdefine _SECURE_ATL.

Example

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

Devolve o minuto representado pelo CTime objeto.

int GetMinute() const throw();

Valor de retorno

Devolve o minuto, com base na hora local, no intervalo de 0 a 59.

Observações

Esta função chama GetLocalTm, que utiliza um buffer interno alocado estaticamente. Os dados neste buffer são sobrescritos devido a chamadas a outras CTime funções membros.

Example

Veja o exemplo do GetHour.

CTime::GetMonth

Devolve o mês representado pelo CTime objeto.

int GetMonth() const throw();

Valor de retorno

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

Observações

Esta função chama GetLocalTm, que utiliza um buffer interno alocado estaticamente. Os dados neste buffer são sobrescritos devido a chamadas a outras CTime funções membros.

Example

Veja o exemplo do GetDay.

CTime::GetSecond

Devolve a segunda representada pelo CTime objeto.

int GetSecond() const throw();

Valor de retorno

Devolve a segunda, com base na hora local, no intervalo de 0 a 59.

Observações

Esta função chama GetLocalTm, que utiliza um buffer interno alocado estaticamente. Os dados neste buffer são sobrescritos devido a chamadas a outras CTime funções membros.

Example

Veja o exemplo do GetHour.

CTime::GetTime

Devolve um valor __time64_t para o objeto dado CTime .

__time64_t GetTime() const throw();

Valor de retorno

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

Example

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

Devolve o ano representado pelo CTime objeto.

int GetYear();

Valor de retorno

Devolve o ano, com base na hora local, no intervalo de 1 de janeiro de 1970 a 18 de janeiro de 2038 (inclusive).

Observações

Esta função chama GetLocalTm, que utiliza um buffer interno alocado estaticamente. Os dados neste buffer são sobrescritos devido a chamadas a outras CTime funções membros.

Example

Veja o exemplo do 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 retorno

O objeto atualizado CTime .

Observações

Este operador de atribuição sobrecarregado copia o tempo fonte para este CTime objeto. O armazenamento interno de tempo num CTime objeto é independente do fuso horário. A conversão de fuso horário não é necessária durante a atribuição.

CTime::operador +, -

Estes operadores somam e subtraem CTimeSpan e CTime objetos.

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

Parâmetros

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

time
O CTime objeto a ser subtraído.

Valor de retorno

A CTime ou CTimeSpan objeto que representa o resultado da operação.

Observações

CTime Os objetos representam o tempo absoluto, CTimeSpan os objetos representam o tempo relativo. Os dois primeiros operadores permitem-lhe adicionar e subtrair CTimeSpan objetos para e de CTime objetos. O terceiro operador permite-lhe subtrair um CTime objeto de outro para obter um CTimeSpan objeto.

Example

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

Estes operadores somam e subtraem um CTimeSpan objeto a e a esse CTime objeto.

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

Parâmetros

Vão
O CTimeSpan objeto a ser adicionado ou subtraído.

Valor de retorno

O objeto atualizado CTime .

Observações

Estes operadores permitem-lhe adicionar e subtrair um CTimeSpan objeto a e a partir desse CTime objeto.

Example

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

Serializa os dados associados à variável membro para ou a partir de um arquivo.

CArchive& Serialize64(CArchive& ar);

Parâmetros

ar
O CArchive objeto que queres atualizar.

Valor de retorno

O objeto atualizado CArchive .

Consulte 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
tempo, _time32, _time64
Classe CTimeSpan
Gráfico de Hierarquia
Classes compartilhadas ATL/MFC