System.SetLength Function

Sets the length of a string or dynamic-array variable.

Pascal

procedure SetLength(var S; NewLength: Integer);

C++

SetLength( S, int NewLength);

File

System

Description

S is a Delphi string or dynamic-array variable.

NewLength is the new number of characters or elements in S.

For a short-string variable, SetLength simply sets the length-indicator character (the character at S[0]) to the given value. In this case, NewLength must be a value between 0 and 255.

For a long-string or dynamic-array variable, SetLength reallocates the string or array referenced by S to the given length. Existing characters in the string or elements in the array are preserved, but the content of newly allocated space is undefined. The one exception is when increasing the length of a dynamic array in which the elements are types that must be initialized (strings, Variants, Variant arrays, or records that contain such types). When S is a dynamic array of types that must be initialized, newly allocated space is set to 0 or nil.

For dynamic arrays, SetLength may take more than one length parameter (up to the number of array dimensions). Each parameter specifies the number of elements along a particular dimension.

Following a call to SetLength, S is guaranteed to reference a unique string or array—that is, a string or array with a reference count of one. If there is not enough memory available to reallocate the variable, SetLength raises an EOutOfMemory exception.

Delphi Examples:

Copy Code

{
This example determines the encoding of a source file and then
writes the file in any encoding chosen.  Use this project to
create files of any encoding.  This example requires two text edits
and a combobox.
}
procedure TForm1.Button1Click(Sender: TObject);
var
  LBuffer: TBytes;
  LByteOrderMark: TBytes;
  LOffset: Integer;
  LEncoding, DestEncoding: TEncoding;
  LFileStream: TFileStream;
  EncodingArray: array[0..5] of TEncoding;
begin
  LEncoding:= nil;
  EncodingArray[0]:= TEncoding.UTF8;
  EncodingArray[1]:= TEncoding.UTF7;
  EncodingArray[2]:= TEncoding.Unicode;
  EncodingArray[3]:= TEncoding.Default;
  EncodingArray[4]:= TEncoding.BigEndianUnicode;
  EncodingArray[5]:= TEncoding.ASCII;
  DestEncoding := EncodingArray[ComboBox1.ItemIndex];
  LFileStream := TFileStream.Create(Edit1.Text, fmOpenRead);
  try
    // Read file into buffer
    SetLength(LBuffer, LFileStream.Size);
//    LFileStream.Read(LBuffer[0], Length(LBuffer));
    LFileStream.ReadBuffer(Pointer(LBuffer)^, Length(LBuffer));

    // Identify encoding and convert buffer to UTF8
    LOffset := TEncoding.GetBufferEncoding(LBuffer, LEncoding);
//    for I := 0 to Length(LBuffer) - 1 do
//      Memo1.Lines.Add((LBuffer[I]));
    LBuffer := LEncoding.Convert(LEncoding, DestEncoding, LBuffer,
      LOffset, Length(LBuffer) - LOffset);
  finally
    LFileStream.Free;
  end;

  LFileStream := TFileStream.Create(Edit2.Text, fmCreate);
  try
    // Write an encoding byte order mark and buffer to output file
    LByteOrderMark := DestEncoding.GetPreamble;
    LFileStream.Write(LByteOrderMark[0], Length(LByteOrderMark));
    LFileStream.Write(LBuffer[0], Length(LBuffer));
  finally
    LFileStream.Free;
  end;
end;

procedure TForm1.FormCreate(Sender: TObject);
var
  StringList: TStrings;
begin
  StringList := TStringList.Create;
  try
    with StringList do begin
      Add('TEncoding.UTF8');
      Add('TEncoding.UTF7');
      Add('TEncoding.Unicode');
      Add('TEncoding.Default');
      Add('TEncoding.BigEndianUnicode');
      Add('TEncoding.ASCII');
    end;
    with ComboBox1 do begin
      Items.Assign(StringList);
      ItemIndex := 0;
    end;
  finally
    StringList.free;
  end;
end;