Classe COleDateTime

Artigo
04/03/2023

Encapsula o tipo de dados DATE que é usado na automação OLE.

Sintaxe

class COleDateTime

Membros

Construtores públicos

Nome	Descrição
COleDateTime::COleDateTime	Constrói um objeto `COleDateTime`.

Métodos públicos

Nome	Descrição
COleDateTime::Format	Gera uma representação de cadeia de caracteres formatada de um objeto `COleDateTime`.
COleDateTime::GetAsDBTIMESTAMP	Chame esse método para obter a hora no objeto `COleDateTime` como uma estrutura de dados `DBTIMESTAMP`.
COleDateTime::GetAsSystemTime	Chame esse método para obter a hora no objeto `COleDateTime` como uma estrutura de dados SYSTEMTIME.
COleDateTime::GetAsUDATE	Chame esse método para obter a hora em `COleDateTime` como uma estrutura de dados `UDATE`.
COleDateTime::GetCurrentTime	Cria um objeto `COleDateTime` que representa a hora atual (função de membro estático).
COleDateTime::GetDay	Retorna o dia que esse objeto `COleDateTime` representa (1 a 31).
COleDateTime::GetDayOfWeek	Retorna o dia da semana que esse objeto `COleDateTime` representa (domingo = 1).
COleDateTime::GetDayOfYear	Retorna o dia do ano que esse objeto `COleDateTime` representa (Jan 1 = 1).
COleDateTime::GetHour	Retorna a hora que esse objeto `COleDateTime` representa (0 a 23).
COleDateTime::GetMinute	Retorna o minuto que esse objeto `COleDateTime` representa (0 a 59).
COleDateTime::GetMonth	Retorna o mês que esse objeto `COleDateTime` representa (1 a 12).
COleDateTime::GetSecond	Retorna o segundo que esse objeto `COleDateTime` representa (0 a 59).
COleDateTime::GetStatus	Obtém o status (validade) desse objeto `COleDateTime`.
COleDateTime::GetYear	Retorna o ano que esse objeto `COleDateTime` representa.
COleDateTime::ParseDateTime	Lê um valor de data/hora de uma cadeia de caracteres e define o valor de `COleDateTime`.
COleDateTime::SetDate	Define o valor desse objeto `COleDateTime` como o valor somente data especificado.
COleDateTime::SetDateTime	Define o valor desse objeto `COleDateTime` como o valor data/hora especificado.
COleDateTime::SetStatus	Define o status (validade) desse objeto `COleDateTime`.
COleDateTime::SetTime	Define o valor desse objeto `COleDateTime` como o valor somente hora especificado.

Operadores públicos

Nome	Descrição
COleDateTime::operator ==, COleDateTime::operator <, etc.	Compare dois valores `COleDateTime`.
COleDateTime::operator +, COleDateTime::operator -	Adicionar e subtrair valores `COleDateTime`.
COleDateTime::operator +=, COleDateTime::operator -=	Adicione e subtraia um valor `COleDateTime` desse objeto `COleDateTime`.
COleDateTime::operator =	Copia um valor `COleDateTime`.
COleDateTime::operator DATE, COleDateTime::operator Date*	Converte um valor `COleDateTime` em um `DATE` ou um `DATE*`.

Membros de Dados Públicos

Nome	Descrição
COleDateTime::m_dt	Contém o `DATE` subjacente a esse objeto `COleDateTime`.
COleDateTime::m_status	Contém o status desse objeto `COleDateTime`.

Comentários

COleDateTime não tem uma classe base.

É um dos tipos possíveis para o tipo de dados VARIANT da automação OLE. Um valor COleDateTime que representa um valor absoluto de data e hora.

O tipo DATE é implementado como um valor de ponto flutuante. Os dias são calculados a partir de 30 de dezembro de 1899, à meia-noite. A tabela a seguir mostra algumas datas e seus valores associados:

Data	Valor
29 de dezembro de 1899, meia-noite	-1,0
29 de dezembro de 1899, 6:00	-1,25
30 de dezembro de 1899, meia-noite	0,0
31 de dezembro de 1899, meia-noite	1.0
1 de janeiro de 1900, 6:00	2.25

Cuidado

Na tabela acima, os valores de dia se tornam negativos antes da meia-noite de 30 de dezembro de 1899, mas os valores de hora do dia não. Por exemplo, 6:00 é sempre representado por um valor fracionário 0,25 independentemente de o inteiro que representa o dia ser positivo (após 30 de dezembro de 1899) ou negativo (antes de 30 de dezembro de 1899). Isso significa que uma simples comparação do ponto flutuante classificaria erroneamente um COleDateTime que representa as 6:00 em 29/12/1899 como posterior a um representando 7:00 no mesmo dia.

A classe COleDateTime trata de datas de 1º de janeiro de 100 a 31 de dezembro de 9999. A classe COleDateTime usa o calendário gregoriano e não dá suporte a datas julianas. COleDateTime ignora o horário de verão. (Confira Data e hora: suporte a automação.)

Observação

Você só pode usar o formato %y para recuperar um ano de dois dígitos para datas a partir de 1900. Se você usar o formato %y em uma data antes de 1900, o código gerará uma falha ASSERT.

Esse tipo também é usado para representar valores somente data ou somente hora. Por convenção, a data 0 (30 de dezembro de 1899) é usada para valores somente hora, e a hora 00:00 (meia-noite) é usada para valores somente data.

Se você criar um objeto COleDateTime usando uma data menor que 100, a data será aceita, mas chamadas subsequentes a GetYear, GetMonth, GetDay, GetHour, GetMinute e GetSecond falharão e retornarão -1. Anteriormente, era possível usar datas de dois dígitos, mas as datas devem ser 100 ou maiores no MFC 4.2 e posterior.

Para evitar problemas, use uma data de quatro dígitos. Por exemplo:

COleDateTime mytime(1996, 1, 1, 0, 0, 0);

As operações aritméticas básicas para os valores COleDateTime usam a classe complementar COleDateTimeSpan. Os valores COleDateTimeSpan definem um intervalo de tempo. A relação entre essas classes é semelhante à relação entre CTime e CTimeSpan.

Para obter mais informações sobre as classes COleDateTime e COleDateTimeSpan, confira o artigo Data e hora: suporte à automação.

Requisitos

Cabeçalho: ATLComTime.h

Operadores relacionais COleDateTime

Operadores de comparação.

bool operator==(const COleDateTime& date) const throw();
bool operator!=(const COleDateTime& date) const throw();
bool operator<(const COleDateTime& date) const throw();
bool operator>(const COleDateTime& date) const throw();
bool operator<=(const COleDateTime& date) const throw();
bool operator>=(const COleDateTime& date) const throw();

Parâmetros

date
O objeto COleDateTime a ser comparado.

Comentários

Observação

Ocorrerá um ATLASSERT se um dos dois operandos for inválido.

Exemplos

COleDateTime dateOne(1995, 3, 15, 12, 0, 0); // 15 March 1995 12 noon
COleDateTime dateTwo(dateOne);             // 15 March 1995 12 noon
BOOL b;
b = dateOne == dateTwo;                    // TRUE
b = dateOne < dateTwo;                     // FALSE, same value
b = dateOne > dateTwo;                     // FALSE, same value
b = dateOne <= dateTwo;                    // TRUE, same value
b = dateOne >= dateTwo;                    // TRUE, same value   

dateTwo.SetStatus(COleDateTime::invalid);
b = dateOne == dateTwo;                    // FALSE, different status
b = dateOne != dateTwo;                    // TRUE, different status

Os operadores >=, <=, > e < serão assert se o objeto COleDateTime estiver definido como nulo.

VARIANT v = {};
v.vt = VT_NULL;
COleDateTime t1(v);
COleDateTime t2(v);
t1 = t1 + t2;

COleDateTime::COleDateTime

Constrói um objeto COleDateTime.

COleDateTime() throw();
COleDateTime(const VARIANT& varSrc) throw();
COleDateTime(DATE dtSrc) throw();
COleDateTime(time_t timeSrc) throw();
COleDateTime(__time64_t timeSrc) throw();
COleDateTime(const SYSTEMTIME& systimeSrc) throw();
COleDateTime(const FILETIME& filetimeSrc) throw();

COleDateTime(int nYear,
    int nMonth,
    int nDay,
    int nHour,
    int nMin,
    int nSec) throw();

COleDateTime(WORD wDosDate,
    WORD wDosTime) throw();
COleDateTime(const DBTIMESTAMP& timeStamp) throw();

Parâmetros

dateSrc
Um objeto COleDateTime existente a ser copiado no novo objeto COleDateTime.

varSrc
Uma estrutura de dados VARIANT existente (possivelmente um objeto COleVariant) a ser convertida em um valor de data/hora (VT_DATE) e copiada para o novo objeto COleDateTime.

dtSrc
Um valor de data/hora (DATE) a ser copiado no novo objeto COleDateTime.

timeSrc
Um valor time_t ou __time64_t a ser convertido em um valor de data/hora e copiado para o novo objeto COleDateTime.

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

filetimeSrc
Uma estrutura FILETIME a ser convertida em um valor de data/hora e copiada para o novo objeto COleDateTime. Um FILETIME usa o UTC (Tempo Coordenado Universal), portanto, se você passar uma hora local na estrutura, seus resultados estarão incorretos. Confira Horas do arquivo no SDK do Windows para obter mais informações.

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

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 COleDateTime.

timeStamp
Uma referência a uma estrutura DBTimeStamp que contém a hora local atual.

Comentários

Todos esses construtores criam objetos COleDateTime inicializados para o valor especificado. A tabela a seguir mostra intervalos válidos para cada componente de data e hora:

Componente de data/hora	Intervalo válido
year	100 - 9999
month	0 - 12
dia	0 - 31
hora	0 - 23
minute	0 - 59
second	0 - 59

Observe que o limite superior real do componente do dia varia de acordo com os componentes de mês e ano. Para obter detalhes, confira as funções membro SetDate ou SetDateTime.

A seguir, há uma descrição resumida de cada construtor:

COleDateTime() Constrói um COleDateTime objeto inicializado como 0 (meia-noite de 30 de dezembro de 1899).
COleDateTime(dateSrc ) Constrói um COleDateTime objeto a partir de um objeto existenteCOleDateTime.
COleDateTime(varSrc ) Constrói um COleDateTime objeto. Tenta converter uma estrutura VARIANT ou um objeto COleVariant em um valor de data/hora (VT_DATE). Se essa conversão tiver êxito, o valor convertido será copiado para o novo objeto COleDateTime. Caso contrário, o valor do objeto COleDateTime será definido como 0 (meia-noite, 30 de dezembro de 1899) e seu status será inválido.
COleDateTime(dtSrc ) Constrói um COleDateTime objeto a partir de um DATE valor.
COleDateTime(timeSrc ) Constrói um COleDateTime objeto a partir de um time_t valor.
COleDateTime(systimeSrc ) Constrói um COleDateTime objeto a partir de um SYSTEMTIME valor.
COleDateTime(filetimeSrc ) Constrói um COleDateTime objeto a partir de um FILETIME valor. . Um FILETIME usa o UTC (Tempo Coordenado Universal), portanto, se você passar uma hora local na estrutura, seus resultados estarão incorretos. Para obter mais informações, confira Horas de arquivo no SDK do Windows.
COleDateTime(nYear, nMonth, nDay, nHour, nMin, , nSec ) Constrói um COleDateTime objeto a partir dos valores numéricos especificados.
COleDateTime(wDosDate, wDosTime ) Constrói um COleDateTime objeto a partir dos valores de data e hora especificados do MS-DOS.

Para obter mais informações sobre o tipo de dados time_t, confira a função time na Referência da Biblioteca de Runtime.

Para obter mais informações, confira as estruturas SYSTEMTIME e FILETIME no SDK do Windows.

Para obter mais informações sobre os limites de valores COleDateTime, confira o artigo Data e hora: suporte à automação.

Observação

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

Exemplo

time_t osBinaryTime;   // C run-time time (defined in <time.h>)
time(&osBinaryTime);   // Get the current time from the 
                     // operating system.

COleDateTime time1;   // initialized to 00:00am, 30 December 1899
                     // (and m_nStatus is valid!)

COleDateTime time2 = time1; // Copy constructor
COleDateTime time3(osBinaryTime);   // from time_t
COleDateTime time4(1999, 3, 19, 22, 15, 0); // 10:15PM March 19, 1999

SYSTEMTIME sysTime;   // Win32 time information
GetSystemTime(&sysTime);

COleDateTime time5(sysTime);

COleDateTime::Format

Cria uma representação formatada do valor de data/hora.

CString Format(DWORD dwFlags = 0,  LCID lcid = LANG_USER_DEFAULT) const;
CString Format(LPCTSTR lpszFormat) const;
CString Format(UINT nFormatID) const;

Parâmetros

dwFlags
Indica um dos seguintes sinalizadores de localidade:

LOCALE_NOUSEROVERRIDE Use as configurações de localidade padrão do sistema em vez das configurações de usuário personalizadas.
VAR_TIMEVALUEONLY Ignore a parcela da data durante a análise.
VAR_DATEVALUEONLY Ignore a parcela da hora durante a análise.

lcid
Indica a ID de localidade a ser usada para a conversão. Para obter mais informações sobre identificadores de linguagem, confira Identificadores de linguagem.

lpszFormat
Uma cadeia de caracteres de formatação semelhante à cadeia de caracteres de formatação printf. Cada código de formatação, precedido por um sinal de porcentagem (%), será substituído pelo componente COleDateTime correspondente. Outros caracteres na cadeia de caracteres de formatação são copiados sem alteração para a cadeia de caracteres retornada. Para obter mais informações, confira a função em tempo de execução strftime. O valor e o significado dos códigos de formatação para Format são:

%H Horas no dia atual
%M Minutos na hora atual
%S Segundos no minuto atual
Sinal de porcentagem %%

nFormatID
A ID do recurso para a cadeia de caracteres de controle de formato.

Valor de retorno

Uma CString que contém o valor de data/hora formatado.

Comentários

Se o status desse objeto COleDateTime for nulo, o valor retornado será uma cadeia de caracteres vazia. Se o status for inválido, a cadeia de caracteres de retorno será especificada pelo recurso de cadeia de caracteres ATL_IDS_DATETIME_INVALID.

Uma breve descrição dos três formulários para essa função segue:

Format( dwFlags, lcid)
Esse formulário formata o valor usando as especificações de linguagem (IDs de localidade) para data e hora. Usando os parâmetros padrão, esse formulário imprimirá a data e a hora, a menos que a parcela de hora seja 0 (meia-noite), nesse caso, ele imprimirá apenas a data ou a parcela de data é 0 (30 de dezembro de 1899), nesse caso, ele imprimirá apenas a hora. Se o valor de data/hora for 0 (30 de dezembro de 1899, meia-noite), esse formulário com os parâmetros padrão imprimirá meia-noite.

Format( lpszFormat)
Esse formulário formata o valor usando a cadeia de caracteres de formato que contém códigos de formatação especiais que são precedidos por um sinal percentual (%), como em printf. A cadeia de caracteres de formatação é passada como um parâmetro para a função. Para obter mais informações sobre os códigos de formatação, confira strftime, wcsftime na Referência da Biblioteca de Runtime.

Format( nFormatID)
Esse formulário formata o valor usando a cadeia de caracteres de formato que contém códigos de formatação especiais que são precedidos por um sinal percentual (%), como em printf. A cadeia de caracteres de formatação é um recurso. A ID desse recurso de cadeia de caracteres é passada como o parâmetro. Para obter mais informações sobre os códigos de formatação, confira strftime, wcsftime na Referência da Biblioteca de Runtime.

Exemplo

COleDateTime t(1999, 3, 19, 22, 15, 0);

CString str = t.Format(_T("%A, %B %d, %Y"));
ASSERT(str == _T("Friday, March 19, 1999"));

COleDateTime::GetAsDBTIMESTAMP

Chame esse método para obter a hora no objeto COleDateTime como uma estrutura de dados DBTIMESTAMP.

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

Parâmetros

timeStamp
Uma referência a uma estrutura DBTimeStamp.

Valor de retorno

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

Comentários

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

Exemplo

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

COleDateTime::GetAsSystemTime

Chame esse método para obter a hora no objeto COleDateTime como uma estrutura de dados SYSTEMTIME.

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

Parâmetros

sysTime
Uma referência a uma estrutura SYSTEMTIME para receber o valor de data/hora convertido a partir do objeto COleDateTime.

Valor de retorno

Retornará TRUE se tiver êxito e FALSE se a conversão falhar ou se o objeto COleDateTime for NULL ou inválido.

Comentários

GetAsSystemTime armazena o tempo resultante no objeto sysTime referenciado. A estrutura de dados SYSTEMTIME inicializada por essa função terá seu membro wMilliseconds definido como zero.

Para obter mais informações sobre as informações de status mantidas em um objeto COleDateTime, confira GetStatus.

COleDateTime::GetAsUDATE

Chame esse método para obter a hora no objeto COleDateTime como uma estrutura de dados UDATE.

bool GetAsUDATE(UDATE& uDate) const throw();

Parâmetros

uDate
Uma referência a uma estrutura UDATE para receber o valor de data/hora convertido a partir do objeto COleDateTime.

Valor de retorno

Retornará TRUE se tiver êxito e FALSE se a conversão falhar ou se o objeto COleDateTime for NULL ou inválido.

Comentários

Uma estrutura UDATE representa uma data "descompactada".

COleDateTime::GetCurrentTime

Chame essa função membro estática para retornar o valor atual de data/hora.

static COleDateTime WINAPI GetCurrentTime() throw();

Exemplo

// example for COleDateTime::GetCurrentTime
COleDateTime dateTest;
   // dateTest value = midnight 30 December 1899

dateTest = COleDateTime::GetCurrentTime();
   // dateTest value = current date and time

// a second example for COleDateTime::GetCurrentTime
// Since GetCurrentTime() is a static member, you can use it in
// a constructor:

COleDateTime t1 = COleDateTime::GetCurrentTime();
COleDateTime t2(COleDateTime::GetCurrentTime());

// Or in a normal assignment operator

COleDateTime t3;
t3 = COleDateTime::GetCurrentTime();

// or even in an expression

 if (COleDateTime::GetCurrentTime().GetDayOfWeek() == 6)
    _tprintf(_T("Thank Goodness it is Friday!\n\n"));

COleDateTime::GetDay

Obtém o dia do mês representado por esse valor de data/hora.

int GetDay() const throw();

Valor de retorno

O dia do mês representado pelo valor desse objeto COleDateTime ou COleDateTime::error caso não tenha sido possível obter o dia.

Comentários

Os valores de retorno válidos variam entre 1 e 31.

Para obter informações sobre outras funções membro que consultam o valor desse objeto COleDateTime, confira as seguintes funções membro:

GetMonth
GetYear
GetHour
GetMinute
GetSecond
GetDayOfWeek
GetDayOfYear

Exemplo

COleDateTime t(1999, 3, 19, 22, 15, 0);  // 10:15PM March 19, 1999
ASSERT(t.GetDay() == 19);
ASSERT(t.GetMonth() == 3);
ASSERT(t.GetYear() == 1999);

COleDateTime::GetDayOfWeek

Obtém o dia da semana representado por esse valor de data/hora.

int GetDayOfWeek() const throw();

Valor de retorno

O dia da semana representado pelo valor desse objeto COleDateTime ou COleDateTime::error caso não tenha sido possível obter o dia da semana.

Comentários

Os valores de retorno válidos variam entre 1 e 7, em que 1=domingo, 2=segunda-feira e assim por diante.

Para obter informações sobre outras funções membro que consultam o valor desse objeto COleDateTime, confira as seguintes funções membro:

GetDay
GetMonth
GetYear
GetHour
GetMinute
GetSecond
GetDayOfYear

Exemplo

COleDateTime t(1999, 3, 19, 22, 15, 0); // 10:15PM March 19, 1999
ASSERT(t.GetDayOfWeek() == 6);          // it's a Friday

COleDateTime::GetDayOfYear

Obtém o dia do ano representado por esse valor de data/hora.

int GetDayOfYear() const throw();

Valor de retorno

O dia do ano representado pelo valor desse objeto COleDateTime ou COleDateTime::error caso não tenha sido possível obter o dia do ano.

Comentários

Os valores de retorno válidos variam entre 1 e 366, em que 1º de janeiro = 1.

Para obter informações sobre outras funções membro que consultam o valor desse objeto COleDateTime, confira as seguintes funções membro:

GetDay
GetMonth
GetYear
GetHour
GetMinute
GetSecond
GetDayOfWeek

Exemplo

COleDateTime t(1999, 3, 19, 22, 15, 0); // 10:15PM March 19, 1999
ASSERT(t.GetDayOfYear() == 78);         // 78th day of that year

COleDateTime::GetHour

Obtém a hora representada por esse valor de data/hora.

int GetHour() const throw();

Valor de retorno

A hora representada pelo valor desse objeto COleDateTime ou COleDateTime::error caso não tenha sido possível obter a hora.

Comentários

Os valores de retorno válidos variam entre 0 e 23.

Para obter informações sobre outras funções membro que consultam o valor desse objeto COleDateTime, confira as seguintes funções membro:

GetDay
GetMonth
GetYear
GetMinute
GetSecond
GetDayOfWeek
GetDayOfYear

Exemplo

COleDateTime t(1999, 3, 19, 22, 15, 0);  // 10:15PM March 19, 1999
ASSERT(t.GetSecond() == 0);
ASSERT(t.GetMinute() == 15);
ASSERT(t.GetHour() == 22);

COleDateTime::GetMinute

Obtém o minuto representado por esse valor de data/hora.

int GetMinute() const throw();

Valor de retorno

O minuto representado pelo valor desse objeto COleDateTime ou COleDateTime::error caso não tenha sido possível obter o minuto.

Comentários

Os valores de retorno válidos variam entre 0 e 59.

Para obter informações sobre outras funções membro que consultam o valor desse objeto COleDateTime, confira as seguintes funções membro:

GetDay
GetMonth
GetYear
GetHour
GetSecond
GetDayOfWeek
GetDayOfYear

Exemplo

Confira o exemplo de GetHour.

COleDateTime::GetMonth

Obtém o mês representado por esse valor de data/hora.

int GetMonth() const throw();

Valor de retorno

O mês representado pelo valor desse objeto COleDateTime ou COleDateTime::error caso não tenha sido possível obter o mês.

Comentários

Os valores de retorno válidos variam entre 1 e 12.

Para obter informações sobre outras funções membro que consultam o valor desse objeto COleDateTime, confira as seguintes funções membro:

GetDay
GetYear
GetHour
GetMinute
GetSecond
GetDayOfWeek
GetDayOfYear

Exemplo

Confira o exemplo de GetDay.

COleDateTime::GetSecond

Obtém o segundo representado por esse valor de data/hora.

int GetSecond() const throw();

Valor de retorno

O segundo representado pelo valor desse objeto COleDateTime ou COleDateTime::error caso não tenha sido possível obter o segundo.

Comentários

Os valores de retorno válidos variam entre 0 e 59.

Observação

A classe COleDateTime não dá suporte a segundos intercalares.

Para obter mais informações sobre a implementação de COleDateTime, confira o artigo Data e hora: suporte à automação.

Para obter informações sobre outras funções membro que consultam o valor desse objeto COleDateTime, confira as seguintes funções membro:

GetDay
GetMonth
GetYear
GetHour
GetMinute
GetDayOfWeek
GetDayOfYear

Exemplo

Confira o exemplo de GetHour.

COleDateTime::GetStatus

Obtém o status (validade) de um determinado objeto COleDateTime.

DateTimeStatus GetStatus() const throw();

Valor de retorno

Retorna o status desse valor COleDateTime. Se você chamar GetStatus em um objeto COleDateTime construído com o padrão, ele retornará válido. Se você chamar GetStatus em um COleDateTime objeto inicializado com o construtor definido como nulo, GetStatus retornará nulo.

Comentários

O valor retornado é definido pelo tipo enumerado DateTimeStatus definido dentro da classe COleDateTime.

enum DateTimeStatus
{
   error = -1,
   valid = 0,
   invalid = 1,    // Invalid date (out of range, etc.)
   null = 2,       // Literally has no value
};

Para obter uma breve descrição desses valores de status, consulte a seguinte lista:

COleDateTime::error Indica que ocorreu um erro ao tentar obter parte do valor de data/hora.
COleDateTime::valid Indica que esse objeto COleDateTime é válido.
COleDateTime::invalid Indica que esse objeto COleDateTime é inválido; ou seja, seu valor pode estar incorreto.
COleDateTime::null Indica que esse objeto COleDateTime é nulo, ou seja, que nenhum valor foi fornecido para esse objeto. (Isso é "nulo" no sentido de banco de dados de "não ter valor", em vez do NULL do C++.)

O status de um objeto COleDateTime é inválido nos seguintes casos:

Se seu valor for definido a partir de um valor VARIANT ou COleVariant que não pôde ser convertido em um valor de data/hora.
Se seu valor for definido a partir de um valor time_t, SYSTEMTIME ou FILETIME que não pôde ser convertido em um valor de data/hora válido.
Se seu valor for definido por SetDateTime com valores de parâmetro inválidos.
Se esse objeto tiver experimentado um estouro ou um estouro negativo durante uma operação de atribuição aritmética, por exemplo, += ou -=.
Se um valor inválido foi atribuído a esse objeto.
Se o status desse objeto foi explicitamente definido como inválido usando SetStatus.

Para obter mais informações sobre as operações que podem definir o status como inválido, confira as seguintes funções de membro:

COleDateTime
SetDateTime
operator +, -
operador +=, -=

Para obter mais informações sobre os limites de valores COleDateTime, confira o artigo Data e hora: suporte à automação.

Exemplo

COleDateTime t;

// this one is a leap year
t.SetDateTime(2000, 2, 29, 5, 0, 0);
ASSERT(t.GetStatus() == COleDateTime::valid);

// this date isn't valid
t.SetDateTime(1925, 2, 30, 5, 0, 0);
ASSERT(t.GetStatus() == COleDateTime::invalid);

// the only way to set null is to set null!
t.SetStatus(COleDateTime::null);
ASSERT(t.GetStatus() == COleDateTime::null);

COleDateTime::GetYear

Obtém o ano representado por esse valor de data/hora.

int GetYear() const throw();

Valor de retorno

O ano representada pelo valor desse objeto COleDateTime ou COleDateTime::error caso não tenha sido possível obter o ano.

Comentários

Os valores de retorno válidos variam entre 100 e 9999, o que inclui o século.

Para obter informações sobre outras funções membro que consultam o valor desse objeto COleDateTime, confira as seguintes funções membro:

GetDay
GetMonth
GetHour
GetMinute
GetSecond
GetDayOfWeek
GetDayOfYear

Para obter mais informações sobre os limites de valores COleDateTime, confira o artigo Data e hora: suporte à automação.

Exemplo

Confira o exemplo de GetDay.

COleDateTime::m_dt

A estrutura DATE subjacente para esse objeto COleDateTime.

DATE m_dt;

Comentários

Cuidado

Alterar o valor no objeto DATE acessado pelo ponteiro retornado por essa função alterará o valor desse objeto COleDateTime. Ele não altera o status desse objeto COleDateTime.

Para obter mais informações sobre a implementação do objeto DATE, confira o artigo Data e hora: suporte à automação.

COleDateTime::m_status

Contém o status desse objeto COleDateTime.

DateTimeStatus m_status;

Comentários

O tipo desse membro de dados é o tipo enumerado DateTimeStatus, que é definido na classe COleDateTime. Para obter mais informações, confira COleDateTime::GetStatus.

Cuidado

Esse membro de dados é para situações avançadas de programação. Você deve usar as funções de membro embutidas GetStatus e SetStatus. Confira SetStatus para ver mais precauções sobre como definir explicitamente esse membro de dados.

COleDateTime::operator =

Copia um valor COleDateTime.

COleDateTime& operator=(const VARIANT& varSrc) throw();
COleDateTime& operator=(DATE dtSrc) throw();
COleDateTime& operator=(const time_t& timeSrc) throw();
COleDateTime& operator=(const __time64_t& timeSrc) throw();
COleDateTime& operator=(const SYSTEMTIME& systimeSrc) throw();
COleDateTime& operator=(const FILETIME& filetimeSrc) throw();
COleDateTime& operator=(const UDATE& uDate) throw();

Comentários

Esses operadores de atribuição sobrecarregados copiam o valor de data/hora de origem nesse objeto COleDateTime. A seguir, há uma descrição resumida de cada um desses operadores de atribuição sobrecarregados:

operador =( dateSrc ) O valor e o status do operando são copiados para este COleDateTime objeto.
operador =( varSrc ) Se a conversão do valor VARIANT (ou objeto COleVariant) em uma data/hora (VT_DATE) for bem-sucedida, o valor convertido será copiado para esse COleDateTime objeto e seu status será definido como válido. Se a conversão não tiver êxito, o valor desse objeto será definido como zero (30 de dezembro de 1899, meia-noite), e seu status será inválido.
operador =( dtSrc ) O valor é copiado DATE para este COleDateTime objeto e seu status é definido como válido.
operador =( timeSrc ) O time_t valor or __time64_t é convertido e copiado para este COleDateTime objeto. Se a conversão tiver êxito, o status desse objeto será definido como válido; se não tiver êxito, ele será definido como inválido.
operador =( systimeSrc ) O valor SYSTEMTIME é convertido e copiado para este COleDateTime objeto. Se a conversão tiver êxito, o status desse objeto será definido como válido; se não tiver êxito, ele será definido como inválido.
operador =( uDate ) O valor é convertido e copiado UDATE para este COleDateTime objeto. Se a conversão tiver êxito, o status desse objeto será definido como válido; se não tiver êxito, ele será definido como inválido. Uma estrutura UDATE representa uma data "descompactada". Para saber mais informações, confira a função VarDateFromUdate.
operador =( filetimeSrc ) O valor FILETIME é convertido e copiado para este COleDateTime objeto. Se a conversão tiver êxito, o status desse objeto será definido como válido; caso contrário, ele será definido como inválido. FILETIME usa o UTC (Tempo Coordenado Universal), portanto, se você passar uma hora UTC na estrutura, seus resultados serão convertidos da hora UTC para a hora local e eles serão armazenados como tempo variante. Esse comportamento é o mesmo que no Visual C++ 6.0 e Visual C++.NET 2003 SP2. Para obter mais informações, confira Horas de arquivo no SDK do Windows.

Para obter mais informações, confira a entrada VARIANT no SDK do Windows.

Para obter mais informações sobre o tipo de dados time_t, confira a função time na Referência da Biblioteca de Runtime.

Para obter mais informações, confira as estruturas SYSTEMTIME e FILETIME no SDK do Windows.

Para obter mais informações sobre os limites de valores COleDateTime, confira o artigo Data e hora: suporte à automação.

COleDateTime::operator +, -

Adicionar e subtrair valores ColeDateTime.

COleDateTime operator+(COleDateTimeSpan dateSpan) const throw();
COleDateTime operator-(COleDateTimeSpan dateSpan) const throw();
COleDateTimeSpan operator-(const COleDateTime& date) const throw();

Comentários

Os objetos COleDateTime representam tempos absolutos. Os objetos COleDateTimeSpan representam tempos relativos. Os dois primeiros operadores permitem adicionar e subtrair um valor COleDateTimeSpan de um valor COleDateTime. O terceiro operador permite subtrair um valor COleDateTime de outro para gerar um valor COleDateTimeSpan.

Se um dos operandos for nulo, o status do valor resultante COleDateTime será nulo.

Se o valor COleDateTime resultante ficar fora dos limites de valores aceitáveis, o status desse valor COleDateTime será inválido.

Se um dos operandos é inválido e o outro não for nulo, o status do valor COleDateTime resultante é inválido.

Os operadores + e - serão declarados se o objeto COleDateTime estiver definido como nulo. Confira Operadores relacionais COleDateTime para obter um exemplo.

Para obter mais informações sobre os valores de status válido, inválido e nulo, consulte a variável de membro m_status.

Para obter mais informações sobre os limites de valores COleDateTime, confira o artigo Data e hora: suporte à automação.

Exemplo

COleDateTime t1(1999, 3, 19, 22, 15, 0); // 10:15PM March 19, 1999
COleDateTime t2(1999, 3, 20, 22, 15, 0); // 10:15PM March 20, 1999

// Subtract 2 COleDateTimes
COleDateTimeSpan ts = t2 - t1;

// one day is 24 * 60 * 60 == 86400 seconds
ASSERT(ts.GetTotalSeconds() == 86400L);

// Add a COleDateTimeSpan to a COleDateTime.
ASSERT((t1 + ts) == t2);

// Subtract a COleDateTimeSpan from a COleDateTime.
ASSERT((t2 - ts) == t1);

COleDateTime::operator +=, -=

Adicione e subtraia um valor ColeDateTime desse objeto COleDateTime.

COleDateTime& operator+=(COleDateTimeSpan dateSpan) throw();
COleDateTime& operator-=(COleDateTimeSpan dateSpan) throw();

Comentários

Esses operadores permitem adicionar e subtrair um valor COleDateTimeSpan de e para esse COleDateTime. Se um dos operandos for nulo, o status do valor resultante COleDateTime será nulo.

Se o valor COleDateTime resultante ficar fora dos limites de valores aceitáveis, o status desse valor COleDateTime será definido como inválido.

Se um dos operandos é inválido e o outro não for nulo, o status do valor COleDateTime resultante é inválido.

Para obter mais informações sobre os valores de status válido, inválido e nulo, consulte a variável de membro m_status.

Os operadores += e -= serão declarados se o objeto COleDateTime estiver definido como nulo. Confira Operadores relacionais COleDateTime para obter um exemplo.

Para obter mais informações sobre os limites de valores COleDateTime, confira o artigo Data e hora: suporte à automação.

COleDateTime::operator DATE

Converte um valor ColeDateTime em um DATE.

operator DATE() const throw();

Comentários

Esse operador retorna um objeto DATE cujo valor é copiado desse objeto COleDateTime. Para obter mais informações sobre a implementação do objeto DATE, confira o artigo Data e hora: suporte à automação.

O operador DATE será assert se o objeto COleDateTime for definido como nulo. Confira Operadores relacionais COleDateTime para obter um exemplo.

COleDateTime::ParseDateTime

Analisa uma cadeia de caracteres para ler um valor de data/hora.

bool ParseDateTime(
    LPCTSTR lpszDate,
    DWORD dwFlags = 0,
    LCID lcid = LANG_USER_DEFAULT) throw();

Parâmetros

lpszDate
Um ponteiro para a cadeia de caracteres terminada em nulo que deve ser analisada. Para obter detalhes, consulte Observações.

dwFlags
Indica sinalizadores para configurações de localidade e análise. Um ou mais dos seguintes sinalizadores:

LOCALE_NOUSEROVERRIDE Use as configurações de localidade padrão do sistema, em vez de configurações de usuário personalizadas.
VAR_TIMEVALUEONLY Ignore a parcela da data durante a análise.
VAR_DATEVALUEONLY Ignore a parcela da hora durante a análise.

lcid
Indica a ID de localidade a ser usada para a conversão.

Valor de retorno

Retornará TRUE se a cadeia de caracteres tiver sido convertida com êxito em um valor de data/hora; caso contrário, retornará FALSE.

Comentários

Se a cadeia de caracteres tiver sido convertida com êxito em um valor de data/hora, o valor desse objeto COleDateTime será definido como esse valor e seu status como válido.

Observação

Os valores de ano devem estar entre 100 e 9999 (inclusive).

O parâmetro lpszDate pode ter uma variedade de formatos. Por exemplo, as seguintes cadeias de caracteres contêm formatos aceitáveis de data/hora:

"25 January 1996"

"8:30:00"

"20:30:00"

"January 25, 1996 8:30:00"

"8:30:00 Jan. 25, 1996"

"1/25/1996 8:30:00" // always specify the full year, even in a 'short date' format

A ID da localidade também será afetada se o formato de cadeia de caracteres puder ser convertido em um valor de data/hora.

No caso de VAR_DATEVALUEONLY, o valor da hora é definido como hora 0 ou meia-noite. No caso de VAR_TIMEVALUEONLY, o valor da data é definido como data 0, ou seja, 30 de dezembro de 1899.

Caso não tenha sido possível converter a cadeia de caracteres em um valor de data/hora ou caso tenha havido um estouro numérico, o status desse objeto COleDateTime será inválido.

Para obter mais informações sobre os limites e a implementação de valores COleDateTime, confira o artigo Data e hora: suporte à automação.

COleDateTime::SetDate

Define a data desse objeto COleDateTime.

int SetDate(
    int nYear,
    int nMonth,
    int nDay) throw();

Parâmetros

nYear
Indica o ano a ser copiado nesse objeto COleDateTime.

nMonth
Indica o mês a ser copiado nesse objeto COleDateTime.

nDay
Indica o dia a ser copiado nesse objeto COleDateTime.

Valor de retorno

Zero se o valor desse objeto COleDateTime tiver sido definido com êxito; caso contrário, 1. Esse valor retornado é baseado no tipo enumerado DateTimeStatus. Para obter mais informações, confira a função de membro SetStatus.

Comentários

A data é definida como os valores especificados. A hora é definida para a hora 0, meia-noite.

Confira a tabela a seguir para obter limites para os valores de parâmetro:

Parâmetro	Limites
nYear	100 - 9999
nMonth	1 - 12
nDay	0 - 31

Se o dia do mês estourar, ele será convertido no dia correto do próximo mês, e o mês e/ou ano será incrementado adequadamente. Um valor diário de zero indica o último dia do mês anterior. O comportamento é o mesmo que SystemTimeToVariantTime.

Se o valor de data especificado pelos parâmetros não for válido, o status desse objeto será definido como COleDateTime::invalid. Você deve usar o GetStatus para verificar a validade do valor DATE e não deve assumir que o valor de m_dt permanecerá não modificado.

Eis alguns exemplos de valores de data:

nYear	nMonth	nDay	Valor
2000	2	29	29 de fevereiro de 2000
1776	7	4	4 de julho de 1776
1925	4	35	35 de abril de 1925 (data inválida)
10000	1	1	1 janeiro de 10000 (data inválida)

Para definir a data e a hora, confira COleDateTime::SetDateTime.

Para obter informações sobre funções membro que consultam o valor desse objeto COleDateTime, confira as seguintes funções membro:

GetDay
GetMonth
GetYear
GetHour
GetMinute
GetSecond
GetDayOfWeek
GetDayOfYear

Para obter mais informações sobre os limites de valores COleDateTime, confira o artigo Data e hora: suporte à automação.

Exemplo

// set only the date, time set to midnight
dt.SetDate(1999, 3, 19);
ASSERT(dt.GetYear() == 1999);
ASSERT(dt.GetDay() == 19);
ASSERT(dt.GetMonth() == 3);
ASSERT(dt.GetHour() == 0);
ASSERT(dt.GetMinute() == 0);
ASSERT(dt.GetSecond() == 0);

// setting the time only resets the date to 1899!
dt.SetTime(22, 15, 0);
ASSERT(dt.GetYear() == 1899);
ASSERT(dt.GetDay() == 30);
ASSERT(dt.GetMonth() == 12);
ASSERT(dt.GetHour() == 22);
ASSERT(dt.GetMinute() == 15);
ASSERT(dt.GetSecond() == 0);

COleDateTime::SetDateTime

Define a data e a hora desse objeto COleDateTime.

int SetDateTime(
    int nYear,
    int nMonth,
    int nDay,
    int nHour,
    int nMin,
    int nSec) throw();

Parâmetros

nYear, nMonth, nDay, nHour, nMin, nSec
Indique os componentes de data e hora a serem copiados nesse objeto COleDateTime.

Valor de retorno

Comentários

Confira a tabela a seguir para obter limites para os valores de parâmetro:

Parâmetro	Limites
nYear	100 - 9999
nMonth	1 - 12
nDay	0 - 31
nHour	0 - 23
nMin	0 - 59
nSec	0 - 59

Se o valor de data ou hora especificado pelos parâmetros não for válido, o status desse objeto será definido como inválido, e o valor desse objeto não será alterado.

Eis alguns exemplos de valores de hora:

nHour	nMin	nSec	Valor
1	3	3	01:03:03
23	45	0	23:45:00
25	30	0	Inválido
9	60	0	Inválido

Eis alguns exemplos de valores de data:

nYear	nMonth	nDay	Valor
1995	4	15	15 de abril de 1995
1789	7	14	17 de julho de 1789
1925	2	30	Inválido
10000	1	1	Inválido

Para definir somente a data, confira COleDateTime::SetDate. Para definir somente a hora, confira COleDateTime::SetTime.

Para obter informações sobre funções membro que consultam o valor desse objeto COleDateTime, confira as seguintes funções membro:

GetDay
GetMonth
GetYear
GetHour
GetMinute
GetSecond
GetDayOfWeek
GetDayOfYear

Para obter mais informações sobre os limites de valores COleDateTime, confira o artigo Data e hora: suporte à automação.

Exemplo

Confira o exemplo de GetStatus.

COleDateTime::SetStatus

Define o status desse objeto COleDateTime.

void SetStatus(DateTimeStatus status) throw();

Parâmetros

status
O novo valor de status para este objeto COleDateTime.

Comentários

O valor do parâmetro status é definido pelo tipo enumerado DateTimeStatus, que é definido dentro da classe COleDateTime. Confira COleDateTime::GetStatus para obter detalhes.

Cuidado

Essa função é para situações de programação avançadas. Essa função não altera os dados nesse objeto. Na maioria das vezes, ela será usada para definir o status como nulo ou inválido. O operador de atribuição (operator =) e SetDateTime definem o status para o objeto com base nos valores de origem.

Exemplo

Confira o exemplo de GetStatus.

COleDateTime::SetTime

Define a hora desse objeto COleDateTime.

int SetTime(
    int nHour,
    int nMin,
    int nSec) throw();

Parâmetros

nHour, nMin, nSec
Indique os componentes de hora a serem copiados para esse objeto COleDateTime.

Valor de retorno

Comentários

A hora é definida para os valores especificados. A data é definida como data 0, ou seja, 30 de dezembro de 1899.

Confira a tabela a seguir para obter limites para os valores de parâmetro:

Parâmetro	Limites
nHour	0 - 23
nMin	0 - 59
nSec	0 - 59

Se o valor de hora especificado pelos parâmetros não for válido, o status desse objeto será definido como inválido, e o valor desse objeto não será alterado.

Eis alguns exemplos de valores de hora:

nHour	nMin	nSec	Valor
1	3	3	01:03:03
23	45	0	23:45:00
25	30	0	Inválido
9	60	0	Inválido

Para definir a data e a hora, confira COleDateTime::SetDateTime.

Para obter informações sobre funções membro que consultam o valor desse objeto COleDateTime, confira as seguintes funções membro:

GetDay
GetMonth
GetYear
GetHour
GetMinute
GetSecond
GetDayOfWeek
GetDayOfYear

Para obter mais informações sobre os limites de valores COleDateTime, confira o artigo Data e hora: suporte à automação.

Exemplo

Confira o exemplo de SetDate.

Confira também

Classe COleVariant
Classe CTime
Classe CTimeSpan
Gráfico da hierarquia
Classes compartilhadas ATL/MFC

Partilhar via

Classe COleDateTime

Sintaxe

Membros

Construtores públicos

Métodos públicos

Operadores públicos

Membros de Dados Públicos

Comentários

Requisitos

Operadores relacionais COleDateTime

Parâmetros

Comentários

Exemplos

COleDateTime::COleDateTime

Parâmetros

Comentários

Exemplo

COleDateTime::Format

Parâmetros

Valor de retorno

Comentários

Exemplo

COleDateTime::GetAsDBTIMESTAMP

Parâmetros

Valor de retorno

Comentários

Exemplo

COleDateTime::GetAsSystemTime

Parâmetros

Valor de retorno

Comentários

COleDateTime::GetAsUDATE

Parâmetros

Valor de retorno

Comentários

COleDateTime::GetCurrentTime

Exemplo

COleDateTime::GetDay

Valor de retorno

Comentários

Exemplo

COleDateTime::GetDayOfWeek

Valor de retorno

Comentários

Exemplo

COleDateTime::GetDayOfYear

Valor de retorno

Comentários

Exemplo

COleDateTime::GetHour

Valor de retorno

Comentários

Exemplo

COleDateTime::GetMinute

Valor de retorno

Comentários

Exemplo

COleDateTime::GetMonth

Valor de retorno

Comentários

Exemplo

COleDateTime::GetSecond

Valor de retorno

Comentários

Exemplo

COleDateTime::GetStatus

Valor de retorno

Comentários

Exemplo

COleDateTime::GetYear

Valor de retorno

Comentários

Exemplo

COleDateTime::m_dt

Comentários

COleDateTime::m_status

Comentários

COleDateTime::operator =

Comentários