Compartilhar via

Classe COleDateTimeSpan

  • Artigo

Representa um tempo relativo, um período de tempo.

Sintaxe

class COleDateTimeSpan

Membros

Construtores públicos

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

Métodos públicos

Nome Descrição
COleDateTimeSpan::Format Gera uma representação de cadeia de caracteres formatada de um objeto COleDateTimeSpan.
COleDateTimeSpan::GetDays Retorna a parte do dia do intervalo que esse objeto COleDateTimeSpan representa.
COleDateTimeSpan::GetHours Retorna a parte da hora do intervalo que esse objeto COleDateTimeSpan representa.
COleDateTimeSpan::GetMinutes Retorna a parte do minuto do intervalo que esse objeto COleDateTimeSpan representa.
COleDateTimeSpan::GetSeconds Retorna a parte do segundo do intervalo que esse objeto COleDateTimeSpan representa.
COleDateTimeSpan::GetStatus Obtém o status (validade) desse objeto COleDateTimeSpan.
COleDateTimeSpan::GetTotalDays Retorna o número de dias que esse objeto COleDateTimeSpan representa.
COleDateTimeSpan::GetTotalHours Retorna o número de horas que esse objeto COleDateTimeSpan representa.
COleDateTimeSpan::GetTotalMinutes Retorna o número de minutos que esse objeto COleDateTimeSpan representa.
COleDateTimeSpan::GetTotalSeconds Retorna o número de segundos que esse objeto COleDateTimeSpan representa.
COleDateTimeSpan::SetDateTimeSpan Define o valor desse objeto COleDateTimeSpan.
COleDateTimeSpan::SetStatus Define o status (validade) desse objeto COleDateTimeSpan.

Operadores públicos

Nome Descrição
operator +, - Adicione, subtraia e altere o sinal de valores COleDateTimeSpan.
operador +=, -= Adicione e subtraia um valor COleDateTimeSpan desse valor COleDateTimeSpan.
operador = Copia um valor COleDateTimeSpan.
operador ==, <, <= Compare dois valores COleDateTimeSpan.
operador double Converte esse valor COleDateTimeSpan para um double.

Membros de Dados Públicos

Nome Descrição
COleDateTimeSpan::m_span Contém o double subjacente a esse objeto COleDateTimeSpan.
COleDateTimeSpan::m_status Contém o status desse objeto COleDateTimeSpan.

Comentários

COleDateTimeSpan não tem uma classe base.

Um COleDateTimeSpan mantém o tempo em dias.

COleDateTimeSpan é usado com sua classe complementar COleDateTime. COleDateTime encapsula o tipo de dados DATE da automação OLE. COleDateTime representa valores temporais absolutos. Todos os cálculos COleDateTime envolvem valores COleDateTimeSpan. A relação entre essas classes é análoga à entre CTime e CTimeSpan.

Para obter mais informações sobre as classes COleDateTime e COleDateTimeSpan, consulte o artigo Data e Hora: Suporte à Automação.

Requisitos

Cabeçalho: ATLComTime.h

Operadores relacionais COleDateTimeSpan

Operadores de comparação.

bool operator==(const COleDateTimeSpan& dateSpan) const throw();
bool operator!=(const COleDateTimeSpan& dateSpan) const throw();
bool operator<(const COleDateTimeSpan& dateSpan) const throw();
bool operator>(const COleDateTimeSpan& dateSpan) const throw();
bool operator<=(const COleDateTimeSpan& dateSpan) const throw();
bool operator>=(const COleDateTimeSpan& dateSpan) const throw();

Parâmetros

dateSpan
O COleDateTimeSpan a ser comparado.

Valor de Devolução

Esses operadores comparam dois valores de intervalo de data/hora e retornam TRUE se a condição for verdadeira; caso contrário, FALSE.

Comentários

Observação

Um ATLASSERT ocorrerá se qualquer operando for inválido.

Exemplo

COleDateTimeSpan spanOne(3, 12, 0, 0); // 3 days and 12 hours
COleDateTimeSpan spanTwo(spanOne);     // 3 days and 12 hours
BOOL b;
b = spanOne == spanTwo;                // TRUE
b = spanOne < spanTwo;                 // FALSE, same value
b = spanOne > spanTwo;                 // FALSE, same value
b = spanOne <= spanTwo;                // TRUE, same value
b = spanOne >= spanTwo;                // TRUE, same value   

spanTwo.SetStatus(COleDateTimeSpan::invalid);
b = spanOne == spanTwo;                // FALSE, different status
b = spanOne != spanTwo;                // TRUE, different status

 

COleDateTimeSpan ts1(100.0);   // one hundred days
COleDateTimeSpan ts2(110.0);   // ten more days

ASSERT((ts1 != ts2) && (ts1 < ts2) && (ts1 <= ts2));

COleDateTimeSpan::COleDateTimeSpan

Constrói um objeto COleDateTimeSpan.

COleDateTimeSpan() throw();
COleDateTimeSpan(double dblSpanSrc) throw();
COleDateTimeSpan(LONG lDays, int nHours, int nMins, int nSecs) throw();

Parâmetros

dblSpanSrc
O número de dias a serem copiados para o novo objeto COleDateTimeSpan.

lDays, nHours, nMins, nSecs
Indica os valores de dia e hora a serem copiados para o novo objeto COleDateTimeSpan.

Comentários

Todos esses construtores criam novos objetos COleDateTimeSpan inicializados para o valor especificado. Uma breve descrição de cada um desses construtores é mostrada abaixo:

  • COleDateTimeSpan( ) constrói um objeto COleDateTimeSpan inicializado a 0.

  • COleDateTimeSpan(dblSpanSrc) constrói um objeto COleDateTimeSpan a partir de um valor de ponto float.

  • COleDateTimeSpan(lDays,nHours,nMins,nSecs) constrói um objeto COleDateTimeSpan inicializado para os valores numéricos especificados.

O status do novo objeto COleDateTimeSpan é definido como válido.

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

Exemplo

COleDateTimeSpan spanOne(2.75);          // 2 days and 18 hours
COleDateTimeSpan spanTwo(2, 18, 0, 0);   // 2 days and 18 hours
COleDateTimeSpan spanThree(3, -6, 0, 0); // 2 days and 18 hours

COleDateTimeSpan ts1;               // Uninitialized time value
COleDateTimeSpan ts2a(ts1);         // Copy constructor
COleDateTimeSpan ts2b = ts1;         // Copy constructor again
COleDateTimeSpan ts3(100.0);          // 100 days
COleDateTimeSpan ts4(0, 1, 5, 12);   // 1 hour, 5 minutes, and 12 seconds

COleDateTimeSpan::Format

Gera uma representação de cadeia de caracteres formatada de um objeto COleDateTimeSpan.

CString Format(LPCTSTR pFormat) const;
CString Format(UINT nID) const;

Parâmetros

pFormat
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 COleDateTimeSpan correspondente. Outros caracteres na cadeia de caracteres de formatação são copiados sem alteração para a cadeia de caracteres retornada. O valor e o significado dos códigos de formatação para Format os quais estão listados abaixo:

  • %H horas no dia atual

  • %M minutos na hora atual

  • %S segundos no dia atual

  • Sinal de porcentagem %%

Os quatro códigos de formato listados acima são os únicos códigos que o Formato aceitará.

-

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

Valor de Devolução

Um CString que contém o valor de data/intervalo de tempo formatado.

Comentários

Chame essas funções para criar uma representação formatada do valor de intervalo de tempo. Se o status desse objeto COleDateTimeSpan 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 IDS_INVALID_DATETIMESPAN.

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

Format(pFormat)
Esse formulário formata o valor usando a cadeia de caracteres de formato que contém códigos de formatação especiais precedidos por um sinal percentual (%), como em printf. A cadeia de caracteres de formatação é passada como um parâmetro para a função.

Format(nID)
Esse formulário formata o valor usando a cadeia de caracteres de formato que contém códigos de formatação especiais 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.

Exemplo

// get the current time
COleDateTime tmStart = COleDateTime::GetCurrentTime();

// waste some time
CString str;
::Sleep(3000);

// get the current time again
COleDateTime tmFinish = COleDateTime::GetCurrentTime();

// find the difference
COleDateTimeSpan tmSpan = tmFinish - tmStart;

// tell the user
str = tmSpan.Format(_T("%S seconds elapsed"));
_tprintf_s(_T("%s\n"), (LPCTSTR) str);

COleDateTimeSpan::GetDays

Recupera a parte do dia deste valor de data/intervalo de tempo.

LONG GetDays() const throw();

Valor de Devolução

A parte do dia deste valor de data/intervalo de tempo.

Comentários

Os valores retornados dessa função variam entre 3.615.000 e 3.615.000, aproximadamente.

Para outras funções que consultam o valor de um objeto COleDateTimeSpan, confira as seguintes funções de membro:

Exemplo

COleDateTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ASSERT(ts.GetDays() == 3);

COleDateTimeSpan::GetHours

Recupera a parte da hora deste valor de data/intervalo de tempo.

LONG GetHours() const throw();

Valor de Devolução

A parte da hora deste valor de data/intervalo de tempo.

Comentários

Os valores retornados dessa função variam entre -23 e 23.

Para outras funções que consultam o valor de um objeto COleDateTimeSpan, confira as seguintes funções de membro:

Exemplo

COleDateTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ASSERT(ts.GetHours() == 1);

COleDateTimeSpan::GetMinutes

Recupera a parte do minuto deste valor de data/intervalo de tempo.

LONG GetMinutes() const throw();

Valor de Devolução

A parte dos minutos deste valor de data/intervalo de tempo.

Comentários

Os valores retornados dessa função variam entre 59 e 59.

Para outras funções que consultam o valor de um objeto COleDateTimeSpan, confira as seguintes funções de membro:

Exemplo

COleDateTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ASSERT(ts.GetMinutes() == 5);

COleDateTimeSpan::GetSeconds

Recupera a parte do segundo deste valor de data/intervalo de tempo.

LONG GetSeconds() const throw();

Valor de Devolução

A parte dos segundos deste valor de data/intervalo de tempo.

Comentários

Os valores retornados dessa função variam entre 59 e 59.

Para outras funções que consultam o valor de um objeto COleDateTimeSpan, confira as seguintes funções de membro:

Exemplo

COleDateTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ASSERT(ts.GetSeconds() == 12);

COleDateTimeSpan::GetStatus

Obtém o status (validade) desse objeto COleDateTimeSpan.

DateTimeSpanStatus GetStatus() const throw();

Valor de Devolução

O status desse valor COleDateTimeSpan.

Comentários

O valor retornado é definido pelo tipo enumerado DateTimeSpanStatus definido dentro da classe COleDateTimeSpan.

enum DateTimeSpanStatus{
   valid = 0,
   invalid = 1,
   null = 2,
};

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

  • COleDateTimeSpan::valid Indica que esse objeto COleDateTimeSpan é válido.

  • COleDateTimeSpan::invalid Indica que esse objeto COleDateTimeSpan é inválido; ou seja, seu valor pode estar incorreto.

  • COleDateTimeSpan::null Indica que esse objeto COleDateTimeSpan é 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 COleDateTimeSpan é inválido nos seguintes casos:

  • 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 COleDateTimeSpan::operator +, - e COleDateTimeSpan::operator +=, -=.

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

COleDateTimeSpan::GetTotalDays

Recupera esse valor de data/intervalo de tempo expresso em dias.

double GetTotalDays() const throw();

Valor de Devolução

Esse valor de data/intervalo de tempo expresso em dias. Embora essa função seja protótipo para retornar um duplo, ela sempre retornará um valor inteiro.

Comentários

Os valores retornados dessa função variam entre -3,65e6 e 3,65e6, aproximadamente.

Para outras funções que consultam o valor de um objeto COleDateTimeSpan, confira as seguintes funções de membro:

Exemplo

COleDateTimeSpan ts(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
ASSERT(ts.GetTotalDays() == 3);
ASSERT(ts.GetTotalHours() == 73);
ASSERT(ts.GetTotalMinutes() == 4385);
ASSERT(ts.GetTotalSeconds() == 263112);

COleDateTimeSpan::GetTotalHours

Recupera esse valor de data/intervalo de tempo expresso em horas.

double GetTotalHours() const throw();

Valor de Devolução

Esse valor de data/intervalo de tempo expresso em horas. Embora essa função seja protótipo para retornar um duplo, ela sempre retornará um valor inteiro.

Comentários

Os valores retornados dessa função variam entre -8,77e7 e 8,77e7., aproximadamente.

Para outras funções que consultam o valor de um objeto COleDateTimeSpan, confira as seguintes funções de membro:

Exemplo

Veja o exemplo de GetTotalDays.

COleDateTimeSpan::GetTotalMinutes

Recupera esse valor de data/intervalo de tempo expresso em minutos.

double GetTotalMinutes() const throw();

Valor de Devolução

Esse valor de data/intervalo de tempo expresso em minutos. Embora essa função seja protótipo para retornar um duplo, ela sempre retornará um valor inteiro.

Comentários

Os valores retornados dessa função variam entre -5.26e9 e 5.26e9., aproximadamente.

Para outras funções que consultam o valor de um objeto COleDateTimeSpan, confira as seguintes funções de membro:

Exemplo

Veja o exemplo de GetTotalDays.

COleDateTimeSpan::GetTotalSeconds

Recupera esse valor de data/intervalo de tempo expresso em segundos.

double GetTotalSeconds() const throw();

Valor de Devolução

Esse valor de data/intervalo de tempo expresso em segundos. Embora essa função seja protótipo para retornar um duplo, ela sempre retornará um valor inteiro.

Comentários

Os valores retornados dessa função variam entre -3,16e11 e 3,16e11, aproximadamente.

Para outras funções que consultam o valor de um objeto COleDateTimeSpan, confira as seguintes funções de membro:

Exemplo

Veja o exemplo de GetTotalDays.

COleDateTimeSpan::m_span

O valor de double subjacente para esse objeto COleDateTime.

double m_span;

Comentários

Esse valor expressa o intervalo de data/hora em dias.

Cuidado

Alterar o valor no membro de dados double alterará o valor desse objeto COleDateTimeSpan. Ele não altera o status desse objeto COleDateTimeSpan.

COleDateTimeSpan::m_status

O tipo desse membro de dados é o tipo enumerado DateTimeSpanStatus, que é definido na classe COleDateTimeSpan.

DateTimeSpanStatus m_status;

Comentários

enum DateTimeSpanStatus{
   valid = 0,
   invalid = 1,
   null = 2,
   };

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

  • COleDateTimeSpan::valid Indica que esse objeto COleDateTimeSpan é válido.

  • COleDateTimeSpan::invalid Indica que esse objeto COleDateTimeSpan é inválido; ou seja, seu valor pode estar incorreto.

  • COleDateTimeSpan::null Indica que esse objeto COleDateTimeSpan é 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 COleDateTimeSpan é inválido nos seguintes casos:

  • 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 COleDateTimeSpan::operator +, - e COleDateTimeSpan::operator +=, -=.

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.

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

COleDateTimeSpan::operator =

Copia um valor COleDateTimeSpan.

COleDateTimeSpan& operator=(double dblSpanSrc) throw();

Comentários

Esse operador de atribuição sobrecarregado copia o valor de intervalo de data/hora de origem para esse objeto COleDateTimeSpan.

COleDateTimeSpan::operator +, -

Adicione, subtraia e altere o sinal de valores COleDateTimeSpan.

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

Comentários

Os dois primeiros operadores permitem adicionar e subtrair valores de data/intervalo de tempo. O terceiro permite alterar o sinal de um valor de data/intervalo de tempo.

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

Se um dos operandos é inválido e o outro não for nulo, o status do valor COleDateTimeSpan 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.

Exemplo

COleDateTimeSpan ts1(3, 1, 5, 12); // 3 days, 1 hour, 5 min, and 12 sec
COleDateTimeSpan ts2(100.0 / (24 * 3600.0)); // 100 seconds
COleDateTimeSpan ts3 = ts1 + ts2;
ASSERT(ts3.GetSeconds() == 52); // 6 mins, 52 secs

COleDateTimeSpan::operator +=, -=

Adicione e subtraia um valor COleDateTimeSpan desse valor COleDateTimeSpan.

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

Comentários

Esses operadores permitem adicionar e subtrair valores de data/intervalo de tempo desse objeto COleDateTimeSpan. Se um dos operandos for nulo, o status do valor resultante COleDateTimeSpan será nulo.

Se um dos operandos é inválido e o outro não for nulo, o status do valor COleDateTimeSpan 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.

Exemplo

COleDateTimeSpan ts1(10.0); // 10 days
COleDateTimeSpan ts2(100.0); // 100 days
ts2 -= ts1;
ASSERT(ts2.GetTotalDays() == 90);

COleDateTimeSpan::operator double

Converte esse valor COleDateTimeSpan para um double.

operator double() const throw();

Comentários

Esse operador retorna o valor desse COleDateTimeSpan como um número de ponto flutuante de dias.

COleDateTimeSpan::SetDateTimeSpan

Define o valor desse valor de data/intervalo de tempo.

void SetDateTimeSpan(LONG lDays, int nHours, int nMins, int nSecs) throw();

Parâmetros

lDays, nHours, nMins, nSecs
Indique os valores de intervalo de data e hora a serem copiados para esse objeto COleDateTimeSpan.

Comentários

Para funções que consultam o valor de um objeto COleDateTimeSpan, confira as seguintes funções de membro:

Exemplo

COleDateTimeSpan spanOne;
COleDateTimeSpan spanTwo;
spanOne.SetDateTimeSpan(0, 2, 45, 0);  // 2 hours and 45 seconds
spanTwo.SetDateTimeSpan(0, 3, -15, 0); // 2 hours and 45 seconds

COleDateTimeSpan::SetStatus

Define o status (validade) desse objeto COleDateTimeSpan.

void SetStatus(DateTimeSpanStatus status) throw();

Parâmetros

status
O novo valor de status para este objeto COleDateTimeSpan.

Comentários

O valor do parâmetro status é definido pelo tipo enumerado DateTimeSpanStatus, que é definido dentro da classe COleDateTimeSpan.

enum DateTimeSpanStatus{
   valid = 0,
   invalid = 1,
   null = 2,
   };

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

  • COleDateTimeSpan::valid Indica que esse objeto COleDateTimeSpan é válido.

  • COleDateTimeSpan::invalid Indica que esse objeto COleDateTimeSpan é inválido; ou seja, seu valor pode estar incorreto.

  • COleDateTimeSpan::null Indica que esse objeto COleDateTimeSpan é 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++.)

    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. Observe que o operador de atribuição (operator =) e SetDateTimeSpan definem o status para o objeto com base nos valores de origem.

Exemplo

// if the person is not still in school, set days to graduation to null
if (!m_bStillInSchool || m_dtDateOfGraduation.GetStatus() == COleDateTime::null)
   m_dtsDaysToGraduation.SetStatus(COleDateTimeSpan::null);

Confira também

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