System.Insert

From RAD Studio API Documentation
Jump to: navigation, search

Delphi

procedure Insert(Substr: String; var Dest: String; Index: Integer);

Properties

Type Visibility Source Unit Parent
procedure public System.pas System System

Description

Inserts a substring into a string (or inserts a dynamic array into a dynamic array), beginning at a specified position.

In Delphi code, Insert merges Source into Dest at the position Dest[Index].

Parameters

Name Description
Source The string or array elements to insert in Dest. If Source is empty, Dest is not changed.
Dest The destination string or array, which is changed if the operation succeeds.
Index The insertion position:
  • For a string, if Index is less than 1, it is set to 1. If it is past the end of Dest, it is set to the length of Dest, turning the operation into an append.
  • For an array, System.Insert inserts a dynamic array at the beginning at the position index, and returns the modified array.

Note: Index is a character index (not a byte index). But it must be incremented by 2 to pass over a surrogate pair (see the Unicode specification). When iterating or counting the characters in a Unicode string, a surrogate pair is considered to be two characters.

Insert throws an EOutOfMemory exception if it is unable to allocate enough memory to accommodate the new returned string or array.

Dynamic Array Example

  
var
  A: array of integer;
begin
  ...
  A:=[1,2,3,4];
  Insert(5,A,2); // A will become [1,2,5,3,4]
  ...
end;

See Also

Code Examples