TTextStrings
describes TStrings descendants optimized for handling their complete text as a whole (instead of line by line).

textstrings.pas contains TStrings descendants optimized for handling their complete text as a whole (instead of line by line).

This file is part of the lazutils package.

TTextLineRange
- record structure showing start and end of line in text, the line as a string, and any user data.
TTextLineRange
is a record type with information about lines of text in the TTextStrings component.
TStrings.Strings TStrings.Objects
Offset to the start of the line in Text.
End of the line in Text (the end-of-line sequence).
Cached line as a String type.
User object.
Pointer to a TTextLineRange type.
Implements a string list used in Memo controls.

TCustomMemoStrings is a TStrings descendant which works around the behavior of TMemo.Lines. In TMemo, Lines contains the text with wordwrap line endings. TCustomMemoStrings stores the text in an LFM without those wordwrap line endings.

TStrings TCustomMemo TMemo
Reads and stores the values used in the Strings property.
Used to read values for the component during LCL component streaming.
TReader instance used to load the values for the component.
Writes the values in the Strings property.
Used to write values for the component during LCL component streaming.
TWriter instance used to write the values in the component.
Defines the Strings property and the read and write procedures for its data.
TFiler instance used to read or write values for the component.
Implements a string list optimized to handle the complete text as a whole (instead of line by line as in TStringList).

TTextStrings is a TCustomMemoStrings descendant which implements a string list optimized for handling the complete text in the list (rather than on a line by line basis).

The ancestor class ensures that lines of text with wordwrap line endings are handled in the component. TTextString uses an internal array of TTextLineRange instances to represent the lines of text. Overridden methods are provided to ensure that the internal line ranges are used to implement property values.

TTextStrings is the type instantiated for use in the Lines property in TCustomMemo.

TCustomMemo.Create TMemo
Boolean flag which indicates whether the array of line ranges is valid.
Number of lines in the array of line ranges.
Number of line ranges allocated for the component.
Pointer to an array of TTextLineRange instances used for the Strings in the component.
Member variable used to store the Text in the component.
Number of times BeginUpdate has been called without a corresponding EndUpdate.
Indicates if Changed was called after calling BeginUpdate.
Gets the value for the Text property.

Overridden to re-implement the method from the ancestor class.

TStrings.Text
Value for the Text property.
Sets the value for the Text property.

Overridden to re-implement the method from the ancestor class.

TStrings.Text
New value for the Text property.
Clears and builds the array with the line ranges for the values in Text.

BuildArrays is a method used to clear and build the internal array with the line ranges for the values in Text. BuildArrays detects the number of end-of-line sequences in Text, allocates memory for the dynamic array, and fills the TTextLineRange instances with their values.

BuildArrays is called from methods used to read or write values in the Strings, Objects, or Count properties. It is called when the internal flag that indicates the array is valid has not been set.

TStrings.Strings TStrings.Objects TStrings.Count
Gets the value for the Count property.

GetCount is overridden in TTextStrings to re-implement the method. It ensures that the internal array of line ranges is valid, and calls BuildArrays when the validity flag has not been set.

The property value is set to the member value used to store the line count.

GetCount does not call the inherited method.

TStrings.Count
Value for the property.
Performs actions needed after the value in Text is changed.

Changed is a method used to perform actions needed after the value in the Text property has been changed. If BeginUpdate has been called without a corresponding EndUpdate call, no actions are performed in the method. Otherwise, the OnChange event handler is signalled (when assigned).

Changed is called from the EndUpdate method when Text was modified following assignments to property values.

Performs action needed when properties in the component are being updated.

Changing is a method used to perform actions needed when property values in the component are being updated. It mimics the Changing behavior implemented in TStringList, where methods call Changing prior to updates to the Strings or Objects properties.

In TTextStrings, the method signals the OnChanging event handler (when assigned) if there are no updates already in progress.

See Changed for the actions performed after property values have been updated.

TStrings.Strings TStrings.Objects
Gets the value for the indexed Strings property.
TStrings.Strings
Value for the indexed property.
Ordinal position for the property value.
Clears the internal array of line ranges used in the component.

ClearArrays is a method used to free resources allocated to the internal array with the line ranges for the component. ClearArrays frees memory allocated for the TTextLineRange instances in the array, and sets the references to Nil.

The internal validity flag and the line counter are both reset to indicate that the array has not not been allocated.

ClearArrays is called from the BuildArrays, Clear, and AddStrings methods.

Gets the value for the indexed Objects property.
TStrings.Objects
Value for the indexed property.
Ordinal position in Objects with the property value.
Sets the value for the indexed Strings property.
TStrings.Strings
Ordinal position for the new property value.
New value in the indexed property.
Sets a value in the indexed Objects property.
Ordinal position for the indexed property value.
TObject instance stored in the indexed property.
Gets the length of a line (including optional end-of-line characters) at the specified position.
Length of the specified line.
Ordinal position for the line examined in the method.
True to include end-of-line characters in the line length.
Gets the ordinal position where the specified line ends in the Text property.
Calls BuildArrays if the internal validity flag is not set.
Offset in Text where the end of the specified line is located.
Ordinal position for the line examined in the method.
True to include end-of-line character(s) in the return value.
Gets the number of end-of-line sequences found in the specified string.
Number of end-of-line sequences found in s.
String with the values examined in the method.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited method on entry. Create calls the CheckSpecialChars method (in the ancestor) to ensure that default values have assigned for the following properties:

- QuoteChar (")
- Delimiter (,)
- NameValueSeparator (=)
- TextLineBreakStyle (platform specific)

Destructor for the class instance.

Destroy is the overridden destructor for the class instance. It calls the Clear method to remove the values in the component, and free the resources allocated to the internal array of line ranges.

Destroy calls the inherited destructor prior to exiting from the method.

TStrings.Destroy
Clears the text and internal line ranges for the component.

Clear is an overridden method which implements the abstract virtual method declared in the ancestor. It is used to remove the Text and line range information used in the component.

Clear calls the ClearArrays method to free TTextLineRange resources allocated to the internal dynamic array. The internal line counter is reset to 0 (zero), and the Text property is set to an empty string ('').

Clear is called when the component is freed, and before reading string values in the LCL component streaming mechanism.

TStrings.Clear
Sets the value for the Text property from a PChar type.

SetText is an overridden method used to set the value for the Text property using the specified PChar value.

SetText stores the value in TheText to the member used for the Text property. It also resets the internal validity flag for the array of of line ranges. This forces the TTextLineRange instances to be re-populated during the next read access to Strings or Objects.

SetText re-implements the method from the ancestor, and does not call the inherited method.

TStrings.SetText
New value for the property.
Inserts the line of text in S at the specified position.

Insert is an overridden method used to insert the line of text in S at the position specified in Index.

Index contains the ordinal position in Strings where the line of text is inserted. Index must be in the range 0..Count-1 or an EListError exception is raised.

S contains the line of text inserted in the method. S can contain an end-of-line sequence, but it is not required. The LineEnding for the platform is appended to the value in S if it is not already present.

Insert calls BuildArrays to populate the array of TTextLineRange instances when the internal validity flag is not set. It also ensures that the internal array is re-allocated when the number of lines reaches the line capacity. Line capacity starts at eight (8), and doubles each time the capacity is filled.

Memory allocated for the TTextLineRange instances is shifted when Index is not the last line of text in the component. The text in S, and the start and end positions in Text are stored in the line range information. The range information for lines after Index is adjusted to reflect the length of the inserted text.

Insert re-implements the method defined in the ancestor, and does not call the inherited method.

Use Add or AddStrings to append one or more lines of text to the values in Strings.

Raises an EListError exception if Index contains an invalild position in the list of string values.
TStrings.Insert
Ordinal position where the line of text is inserted.
Value for the line of text inserted in the method.
Deletes the line of text at the specified position.

Delete is an overridden method used to delete the line of text at the specified position. BuildArrays is called to populate the internal array of TTextLineRange instances when the internal validity flag is not set.

Index contains the ordinal position in Strings for the line of text removed in the method. Index must be in the range 0..Count-1 or an EStringListError exception is raised.

Line range information is used to adjust both Text and the internal array of TTextLineRange instance. The line, including end-of-line characters, is removed from Text. The line counter is decremented, and the array of line ranges is updated. Line ranges after Index are updated to move their start and end positions downward by the length of the removed line. The memory at the end of the line ranges is zero-filled to prevent corruption.

Raises an EStringListError exception when Index is not a valid position in the list of string values.
TStrings.Count TStrings.Delete TStrings.Strings
Ordinal position for the value removed from the Strings property.
Swaps the line values at the specified positions.

Exchange is an overridden method used to swap the line values at the positions specified in Index1 and Index2. No actions are performed in the method when Index1 and Index2 contain the same value.

Values in Index1 and Index2 must be in the range 0..Count-1 or an EStringListError exception is raised.

BuildArrays is called to populate the internal array of TTextLineRange instances when the internal validity flag is not set. MakeTextBufferUnique is called to ensure that the reference count for the Text member is 1.

When Index2 is the last line of text, a LineEnding sequence is added to Text when not already present.

GetLineLen is called to get the length for both lines including end-of-line characters. Temporary buffers are allocated for both TTextLineRange instances, and a memory buffer is allocated using the size for the larger of the two lines. The largest line is saved to the memory buffer, and used to shift the values in Text as needed. Range information for lines between Index1 and Index2 are adjusted to reflect their new start and end positions.

Exchange also swaps the values in the Objects property at the specified index positions.

Exchange re-implements the method defined in the ancestor, and does not call the inherited method.

TStrings.Exchange
First position for the value exchange.
Second position for the value exchange.
Moves a String value from the current position to the new position.
TStrings.Move
Current ordinal position for the string.
New ordinal position for the string.
Ensures that the reference count for the Text member is 1.

Calls the UniqueString routine from the RTL system unit.

UniqueString
Starts an update process for the component.

BeginUpdate is a method used to start an update process for the component. It increments an internal update counter used to consolidate OnChanging and OnChange event notifications. The counter value is used in the Changing and Changed methods, and controls when the event notifications are enabled and performed.

Use EndUpdate to decrement the internal update counter.

TStrings.BeginUpdate
Finishes an update process for the component.

EndUpdate is a method used to finish an active update process for the component.

For each call to BeginUpdate, there needs to be a corresponding call to EndUpdate. The methods are used as a pair to consolidate OnChanging and OnChange event notifications.

EndUpdate decrements the internal update counter incremented by calling BeginUpdate. When the update counter is a positive non-zero value, the Changed method is not called and the OnChange event handler is not signalled.

An Exception is raised if the internal update counter is <= 0 when the method is called. When the counter value reaches 0, the Changed method is called to signal the OnChange event handler (when assigned).

Use BeginUpdate to start an update process by incrementing the value for the internal counter.

Raises an Exception if the internal update counter is <;= 0 when the method is called.
TStrings.EndUpdate
Gets the value for the Text property as a PChar type.
TStrings.GetText
Value for the property as a PChar type.
Gets the ordinal position for the specified String value.
TStrings.IndexOf
Ordinal position for the requested value.
Value to locate in the method.
Appends the specified text to the values in Strings.

Calls AddObject to append the value in S. Nil is used as the value for the object parameter.

TStrings.Add
Ordinal position in Strings where the value was stored.
String appended to the Strings property.
Adds a String and Object pair to the string list.

Adds a LineEnding if the value in Text does not already end with one of the end-of-line characters.

Calls BuildArrays when an object instance has been assigned to AObject.

Recalculates the number of lines in the internal line ranges array. If the number of lines is larger than the current capacity for the array, the capacity is doubled. The memory for the line range array is re-allocated to the new capacity, and the unused portion is zero-filled.

The value in AObject is stored in the TTextLineRange instance for the new line. The start and end positions, and the text are stored in the line range information.

The internal line count is incremented prior to exiting from the method.

Ordinal position where the string and object were stored.
String value added to component.
TObject instance (or Nil) added to the component.
Adds the lines of text in TheStrings to the current class instance.

AddStrings is an overridden method in TTextStrings used to add the lines of text in TheStrings to the current class instance. No actions are performed in the method when TheStrings does not contain any lines of text.

Builds (or re-builds) the internal array of line ranges for the class instance. Values from the Objects property in TheStrings are also copied in the method.

TStrings.Objects TStrings.AddStrings
String list with the values added in the method.
Loads the content in the string list from the specified file name.

Creates a temporary TFileStream instance for the FileName argument. The file handle is opened for reading, and shared write access is denied. The inherited LoadFromStream method is called to load the values in the string list from the file stream.

TStrings.LoadFromFile
File name with the values loaded in the method.
Saves the content in the string list to the specified file name.

Creates a temporary TFileStream instance for the FileName argument. The file is created if it does not already exist. The inherited SaveToStream method is called to store content in the string list to the file stream.

TStrings.SaveToFile
File name where the content is stored.
Contains the textual representation for the values in Strings.

Text is a String property which contains the textual representation for the values in the Strings property. TTextStrings re-implements the Text property as defined in TStrings. The write specifier (SetTextStr) is overridden, and forces the internal array of line ranges to be rebuilt during the next read access.

TStrings.Text
Event handler signalled when values in Strings or Objects have been changed.

OnChange is a TNotifyEvent property with the event handler signalled when values in the Strings and/or Objects properties have been changed.

OnChange is signalled from the Changed method, and occurs after the property value(s) are stored in the component.

TString.Strings TStrings.Objects TNotifyEvent
Event handler signalled before properties are updated in the component.

OnChanging is a TNotifyEvent property with the event handler signalled before the Strings or Objects properties are updated in the component.

OnChanging is signalled from the Changing method when an update process in not already active.

TString.Strings TStrings.Objects TNotifyEvent