TclJSONArray

The TCLJSONArray represents a JSON array within the TCLJSON library. It is a strongly typed container that can hold multiple JSON values, objects, or even other arrays, allowing developers to build hierarchical and complex JSON structures.

Feature	Use of	Definition
Create	Arr = TCLJSONArray.Create;	Creates a new, empty JSON array instance.
CreateFromJSON(const AJSON: string)	Arr = TCLJSONArray.CreateFromJSON('[{"Name":"Item1"}]');	Parses a JSON string and initializes the array with its content.
AddValue	Arr.AddValue(TCLJSONValue.Str('Hello'));	Adds a single JSON value to the end of the array.
GetItem	val = Arr.GetItem(0);	Retrieves the value at the specified index in the array.
Count	n = Arr.Count;	Returns the number of elements in the array.
AddObject	Arr.AddObject(obj);	Adds a JSON object to the array as a new element.
AddArray	Arr.AddArray(subArray);	Adds another JSON array as an element within this array.
Remove	Arr.Remove(Arr.Count - 1);	Removes the element at the specified index from the array.
RemoveValue	Arr.RemoveValue(val);	Removes the first occurrence of the specified JSON value from the array.
Clone	copyArr = Arr.Clone;	Creates a deep copy of the array and all its elements.
Merge	Arr.Merge(otherArr);	Appends all elements from another array into this array.
ToJSONString	jsonText = Arr.ToJSONString;	Returns the JSON-formatted string representation of the array.
Clear	Arr.Clear;	Removes all elements from the array, leaving it empty.

Hint!

Use GetItem and Count to safely iterate over the array without causing out-of-bounds errors.

Example: TCLJSONArray in Use

var
  Form1: TClForm;
  AddBtn, RemoveBtn, ShowBtn: TClProButton;
  InputEdt: TClProEdit;
  ItemsMemo: TClMemo;
  Arr: TCLJSONArray;

void CreateControls;
{
  InputEdt = Form1.AddNewProEdit(Form1, 'InputEdt', 'Enter item name...');
  InputEdt.Align = alTop;
  InputEdt.Height = 35;
  InputEdt.Margins.Top = 10;

  AddBtn = Form1.AddNewProButton(Form1, 'AddBtn', 'Add Item');
  AddBtn.Align = alTop;
  AddBtn.Margins.Top = 10;
  AddBtn.OnClick = 'AddItem';

  RemoveBtn = Form1.AddNewProButton(Form1, 'RemoveBtn', 'Remove Last');
  RemoveBtn.Align = alTop;
  RemoveBtn.Margins.Top = 10;
  RemoveBtn.OnClick = 'RemoveItem';

  ShowBtn = Form1.AddNewProButton(Form1, 'ShowBtn', 'Show JSON');
  ShowBtn.Align = alTop;
  ShowBtn.Margins.Top = 10;
  ShowBtn.OnClick = 'ShowJSON';

  ItemsMemo = Form1.AddNewMemo(Form1, 'ItemsMemo','');
  ItemsMemo.Align = alClient;
  ItemsMemo.Margins.Top = 10;
  ItemsMemo.ReadOnly = True;
}

void RefreshMemo;
var
  i: Integer;
  item: TCLJSONObject;
  lineStr: string;
{
  ItemsMemo.Lines.Clear;

  for (i = 0 to Arr.Count - 1) 
  {
    item = Arr.GetItem(i); 
    lineStr = item.GetValueByPath('Name').AsString + ' (' + item.GetValueByPath('CreatedAt').AsString + ')';
    ItemsMemo.Lines.Add(lineStr);
  }
}

void AddItem;
var
  nameStr: string;
  ItemObj: TCLJSONObject;
{
  nameStr = InputEdt.Text;

  if (nameStr == '') 
  {
    ShowMessage('Please enter an item name.');
    exit;
  }

  ItemObj = TCLJSONObject.Create;
  ItemObj.AddPair('Name', TCLJSONValue.Str(nameStr));
  ItemObj.AddPair('CreatedAt', TCLJSONValue.Str(DateTimeToStr(Now)));

  Arr.AddObject(ItemObj);
  RefreshMemo;

  InputEdt.Text = '';
}

void RemoveItem;
{
  if (Arr.Count > 0)
  {
    Arr.Remove(Arr.Count - 1);
    RefreshMemo;
  }
  else
    ShowMessage('Array is empty.');
}

void ShowJSON;
{
  ShowMessage('Current JSON:' + #13#10 + Arr.ToJSONString);
}

{
  Form1 = TClForm.Create(Self);
  Arr = TCLJSONArray.Create;

  CreateControls;
  Form1.Run;
}

Output:

See Also

• TclJSONValue
• TclJSONObject
• TclJSONPair
• TclJSON