Delphi Basics : SetLength command

DelphiBasics

SetLength
Procedure

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; ...};

Description

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

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

Download this web site as a Windows program.

Example code : Make a string smaller or longer

var
  myString : string;
  onPos    : Integer;

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

  // Display this string
  ShowMessage('"'+myString+'"');

  // 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
  ShowMessage('"'+myString+'"');

  // 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
  ShowMessage('"'+myString+'"');
end;

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

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

begin
  // 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
  begin
    singleArray[i] := 'String '+IntToStr(i);
    ShowMessage('Element '+IntToStr(i)+' = '+singleArray[i]);
  end;

  // 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
    begin
      multiArray[i,j] := i + j;
      ShowMessage('Element '+IntToStr(i)+','+IntToStr(j)+' = '+
                  IntToStr(multiArray[i,j]));
    end;
end;

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