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; ...};
The 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
CopyCreate a copy of part of a string or an array
LengthReturn the number of elements in an array or string
SetStringCopies characters from a buffer into a string
SliceCreates a slice of an array as an Open Array parameter
 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
  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)+' = '+
Show 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 . All rights reserved.  |  Home Page