Changes the size of a string, or the size(s) of an array System unit
1  procedure SetLength ( var StringToChange : string; NewLength : Integer ) ;
2  procedure SetLength ( var ArrayToChange : Array type; Dim1Length : Integer {;Dim2Length : Integer; ...} ) ;
cThe SetLength procedure changes the size of a string, single dimensional dynamic array, or multidimensional dynamic array.
Version 1
When changing the size of a string StringToChange, the new size NewLength may be smaller, the same or larger than the existing string. In all cases, the size is in characters, and a new string is created regardless.
If the string is shorter, it gets truncated. If longer, the extra characters are not initialised. This can create odd effects - see the first example.
Version 2
A dynamic array is one that is not declared with a fixed size. Such a declaration creates a pointer only. Even a multi-dimensional dynamic array starts as a single, unitialised pointer. A multidimensional array is really just a single dimensional array that has arrays as elements.
SetLength sets the length of the dimensions Dim1Length, Dim2Length ... of the ArrayToChange. This may be performed multiple times - not just on an unitialised array. Subsequent calls will lose data, or add extra space. This extra space is only initialised if it contains strings, interfaces, or Variants.
Dim1Length refers to the left, outer dimension of the array.
Related commands
Copy Create a copy of part of a string or an array
Length Return the number of elements in an array or string
SetString Copies characters from a buffer into a string
Slice Creates a slice of an array as an Open Array parameter
 Author links

 Download this web site as a Windows program.

Example code : Make a string smaller or longer
  myString : string;
  onPos    : Integer;

  // Set up my string to hold a well known phrase
  myString := 'The cat sat on the mat';

  // Display this string

  // Now make the string longer
  SetLength(myString, 25);

  // Display this string again
  // Note that the string is prematurely terminated
  // This is because the extra characters are not initialised

  // Now make the string shorter - chop from 'sat' onwards
  onPos := AnsiPos('sat', myString);
  SetLength(myString, onPos-1);

  // Display this string again
  // Now the string is fully initialised
Show full unit code
   "The cat sat on the mat"
   "The cat sat on the mat
   "The cat "
Example code : Setting the length of single and multi-dimensional arrays
// Full Unit code.
// -----------------------------------------------------------
// You must store this code in a unit called Unit1 with a form
// called Form1 that has an OnCreate event called FormCreate.
unit Unit1;
  // The System unit does not need to be defined
  Forms, Dialogs;
  TForm1 = class(TForm)
    procedure FormCreate(Sender: TObject);
Form1: TForm1;
{$R *.dfm} // Include form definitions
procedure TForm1.FormCreate(Sender: TObject);

  singleArray : array of string;
  multiArray  : array of array of Word;
  i, j : Integer;

  // Set the length of a single dimension array
  SetLength(singleArray, 4);

  // Now fill it up : note that dynamic arrays start at 0
  ShowMessage('Single dimensional array :');
  for i := 0 to 3 do
    singleArray[i] := 'String '+IntToStr(i);
    ShowMessage('Element '+IntToStr(i)+' = '+singleArray[i]);

  // Set the length of a multi dimensional array
  SetLength(multiArray, 2, 3);

  // Now fill it up
  ShowMessage('Multi-dimensional array :');
  for i := 0 to 1 do
    for j := 0 to 2 do
      multiArray[i,j] := i + j;
      ShowMessage('Element '+IntToStr(i)+','+IntToStr(j)+' = '+
Hide full unit code
   Single dimensional array :
   Element 0 = 0
   Element 1 = 1
   Element 2 = 2
   Element 3 = 3
   Multi-dimensional array :
   Element 0,0 = 0
   Element 0,1 = 1
   Element 0,2 = 2
   Element 1,0 = 1
   Element 1,1 = 2
   Element 1,2 = 3
Delphi Programming Neil Moffatt 2002 - 2020. All rights reserved.  |  Home Page