Is the documentation from Embarcadero wrong for EncodeDateTime?

Question

The documentation for System.DateUtils.EncodeDateTime() says:

Valid hour values are 0 through 24. (If the specified hour is 24, the minute, second, and millisecond values should all be 0, and the resulting TDateTime value represents midnight at the end of the specified day and the beginning of the next day).

If I try to do EncodeDateTime(2008,1,1,24,0,0,0); I receive an exception.

What am I doing wrong?

Answer 1

This is a defect in the documentation. The implementation of TryEncodeTime, which is what does the actual work, goes like this:

function TryEncodeTime(Hour, Min, Sec, MSec: Word; out Time: TDateTime): Boolean;
var
  TS: TTimeStamp;
begin
  Result := False;
  if (Hour < HoursPerDay) and (Min < MinsPerHour) and (Sec < SecsPerMin) 
    and (MSec < MSecsPerSec) then
  begin
    ....
    Result := True;
  end;
end;

Since HoursPerDay is 24, it is clear that the implementation does not agree with the documentation.

This isn't even behaviour that has changed over time. The TryEncodeTime method has always behaved this way. For instance, the analogous function from Delphi 5 looks like this:

function DoEncodeTime(Hour, Min, Sec, MSec: Word; var Time: TDateTime): Boolean;
begin
  Result := False;
  if (Hour < 24) and (Min < 60) and (Sec < 60) and (MSec < 1000) then
  begin
    Time := (Hour * 3600000 + Min * 60000 + Sec * 1000 + MSec) / MSecsPerDay;
    Result := True;
  end;
end;