RAD Studio VCL Reference
ContentsIndex
PreviousUpNext
TStringBuilder Class
Create Constructor | TStringBuilder Fields | TStringBuilder Methods | TStringBuilder Properties | TStringBuilder Members | SysUtils | Description | See Also
Collapse All

An editable array of characters whose contents has all the functionality of a string object.

Class Hierarchy
Pascal
TStringBuilder = class;
C++
class TStringBuilder;
File
Description

Use a TStringBuilder as an editable string.  

The TStringBuilder class is completely compatable with the .Net framework's StringBuilder (MSDN) class. Use a TStringBuilder instance to hold a character array. This array can be modified after creation. Substrings can be appended, searched and replaced, or inserted. The character array can be queried by index or converted to a string for comparison.  

The character array can be referenced directly by using the Chars property. The Length property contains the current length of the character array.  

builder.Length = builder.ToString.Length;  

The Capacity property holds the current allocated storage space for this TStringBuilder instance. Capacity can be increased up to the value of MaxCapacity and down to the current value of Length. Capacity is increased if Length is increased, or the character array is altered by appending to increase it's length.  

The Append method converts a multitude of possible types to a string and appends that to the current character array. AppendFormat allows you to append several objects to the character array, each object with it's own format.  

The Equals method compares a specified object or another TStringBuilder to this instance of TStringBuilder.  

The Append, CopyTo, Insert, Remove and Replace methods access the character array by index or search the character as a string. The ToString method converts the character array to a string to provide string functionality.  

TStringBuilder is an implementation of the .NET StringBuilder (MSDN) class.  

C++ Examples: 

 

Copy Code
/*
This example exercises many of the members of the TStringBuilder class.
*/
template <class T>
void testAppend(T t)
{
    std::auto_ptr<TStringBuilder> builder(new TStringBuilder());
    builder->Append(t);
    UnicodeString s1 = builder->ToString();
    UnicodeString s2(t);
    assert(s1 == s2);
}


#if defined(_DELPHI_STRING_UNICODE)
const wchar_t* ext_chars =
    L"А Б В Г Д Є Ж Ѕ З И І"
    L"К Л М Н О П Ҁ Р С Т Ѹ"
    L"Ф Х Ѡ Ц Ч Ш Щ Ъ Ы Ь Ѣ"
    L"Ю ІА Ѧ Ѩ Ѫ Ѭ Ѯ Ѱ Ѳ Ѵ Ѥ";
#else
const char* ext_chars =
    "À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï"
    "Ð Ñ Ò Ó Ô Õ Ö × Ø Ù Ú Û Ü Ý Þ ß"
    "à á â ã ä å æ ç è é ê ë ì í î ï"
    "ð ñ ò ó ô õ ö ÷ ø ù ú û ü ý þ ÿ";
#endif

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
    {
        // Test starts out as empty
        std::auto_ptr<TStringBuilder> builder(new TStringBuilder());
        assert(builder->ToString() == System::String());
    }

    {
        // Append
        short s = 0xffe;
        testAppend(s);

        unsigned short us = 0xfffe;
        testAppend(us);
    }

    {
        const _DCHAR* p = ext_chars;

        std::auto_ptr<TStringBuilder> builder(new TStringBuilder());
        System::String str1(p);

        // Appending of wchar_t
        while (*p) 
        {
            builder->Append(*p++);
        }

        // Length property
        assert(builder->Length == str1.Length());

        // Subscript operator
        for (int i=0; i<str1.Length(); i++)
        {
            // NOTE: strings are 1-based
            assert((*(builder.get()))[i] == str1[i+1]);
        }

        // ToString()
        System::String str2 = builder->ToString();
        Edit1->Text = str1;
        Edit2->Text = str2;
        assert(str2 == str1);

        // Replace
        builder->Replace(' ', '.');
        UnicodeString str3;
        str3 = builder->ToString();
        Edit3->Text = str3;
        assert(str3 != str2);

        // Replace back
        builder->Replace(L'.', L' ');
        System::String str4 = builder->ToString();
        Edit4->Text = str4;
        assert(str2 == str4);
    }

    {
        System::String str(ext_chars);

        std::auto_ptr<TStringBuilder> builder(new TStringBuilder());

        // Insert at start when empty, at start when not empty and at end
        builder->Insert(0, str);
        builder->Insert(0, str);
        builder->Insert(builder->Length, str);

        // Concatenate string 3 times
        System::String str2;
        str2 += str;
        str2 += str;
        str2 += str;

        str = builder->ToString();

        Edit5->Text = str;
        assert(builder->ToString() == str2);
    }
    MessageDlg("All assertions passed in the TStringBuilder Test test.",
        mtInformation, TMsgDlgButtons() << mbOK, 0);
}
//---------------------------------------------------------------------------
void __fastcall TForm1::Button2Click(TObject *Sender)
{
    const _DCHAR* p = ext_chars;

    std::auto_ptr<TStringBuilder> builder(new TStringBuilder());

    // Appending of chars
    while (*p) 
    {
        builder->Append(*p++);
    }

    System::String str1(ext_chars);
    System::String str2 = builder->ToString();
    assert(str1 == str2);

    builder->Replace(_D(" "), _D("."));
    System::String str3;
    str3 = builder->ToString();
    assert(str1 != str3);

    builder->Replace(_D("."), _D(" "));
    System::String str4(builder->ToString());
    assert(str1 == str4);
    MessageDlg("All assertions passed in the TStringBuilder Replace test.",
        mtInformation, TMsgDlgButtons() << mbOK, 0);
}

 

See Also
Copyright(C) 2009 Embarcadero Technologies, Inc. All Rights Reserved.
What do you think about this topic? Send feedback!