Mega Code Archive
Setlength - changes the size of a string, or the size[s] of an array system unit
<![CDATA[
1 procedure SetLength ( var StringToChange : string; NewLength : Integer ) ;
2 procedure SetLength ( var ArrayToChange : Array type; Dim1Length : Integer {;Dim2Length : Integer; ...} ) ;
Description
The SetLength procedure chnages 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
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
]]>