<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
  <package name="lazutils">
    <!--
    ====================================================================
      TextStrings
    ====================================================================
    -->
    <module name="TextStrings">
      <short>
        <var>TTextStrings</var> describes TStrings descendants optimized for handling their complete text as a whole (instead of line by line).
        </short>
      <descr>
        <p>
          <file>textstrings.pas</file> contains <var>TStrings</var> descendants optimized for handling their complete text as a whole (instead of line by line).
        </p>
        <p>
          This file is part of the <file>lazutils</file> package.
        </p>
      </descr>

      <!-- unresolved type references -->
      <element name="Classes"/>
      <element name="SysUtils"/>
      <element name="LazUtilsStrConsts"/>

      <element name="TTextLineRange">
        <short>
          <var>TTextLineRange</var> - record structure showing start and end of line in text, the line as a string, and any user data.
        </short>
        <descr>
          <var>TTextLineRange</var> is a record type with information about lines of text in the TTextStrings component.
        </descr>
        <seealso>
          <link id="TTextStrings"/>
          <link id="#rtl.classes.TStrings.Strings">TStrings.Strings</link>
          <link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
        </seealso>
      </element>
      <element name="TTextLineRange.StartPos">
        <short>Offset to the start of the line in Text.</short>
      </element>
      <element name="TTextLineRange.EndPos">
        <short>End of the line in Text (the end-of-line sequence).</short>
      </element>
      <element name="TTextLineRange.Line">
        <short>Cached line as a String type.</short>
      </element>
      <element name="TTextLineRange.TheObject">
        <short>User object.</short>
      </element>

      <element name="PTextLineRange">
        <short>Pointer to a TTextLineRange type.</short>
      </element>

      <element name="TCustomMemoStrings">
        <short>Implements a string list used in Memo controls.</short>
        <descr>
          <p>
            <var>TCustomMemoStrings</var> is a <var>TStrings</var> descendant which works around the behavior of <var>TMemo.Lines</var>. In TMemo, Lines contains the text with wordwrap line endings. TCustomMemoStrings stores the text in an LFM without those wordwrap line endings.
          </p>
        </descr>
        <seealso>
          <link id="#rtl.classes.TStrings"/>
          <link id="#lcl.stdctrls.TCustomMemo"/>
          <link id="#lcl.stdctrls.TMemo"/>
          <link id="TTextStrings"/>
        </seealso>
      </element>

      <element name="TCustomMemoStrings.DoReadData">
        <short>Reads and stores the values used in the Strings property.</short>
        <descr>
          Used to read values for the component during LCL component streaming.
        </descr>
        <seealso/>
      </element>
      <element name="TCustomMemoStrings.DoReadData.Reader">
        <short>TReader instance used to load the values for the component.</short>
      </element>

      <element name="TCustomMemoStrings.DoWriteData">
        <short>Writes the values in the Strings property.</short>
        <descr>
          Used to write values for the component during LCL component streaming.
        </descr>
        <seealso/>
      </element>
      <element name="TCustomMemoStrings.DoWriteData.Writer">
        <short>TWriter instance used to write the values in the component.</short>
      </element>

      <element name="TCustomMemoStrings.DefineProperties">
        <short>
          Defines the Strings property and the read and write procedures for its data.
        </short>
        <descr/>
        <seealso/>
      </element>
      <element name="TCustomMemoStrings.DefineProperties.Filer">
        <short>TFiler instance used to read or write values for the component.</short>
      </element>

      <element name="TTextStrings">
        <short>
          Implements a string list optimized to handle the complete text as a whole (instead of line by line as in <var>TStringList</var>).
        </short>
        <descr>
          <p>
            TTextStrings is a <var>TCustomMemoStrings</var> descendant which implements a string list optimized for handling the complete text in the list (rather than on a line by line basis).
          </p>
          <p>
            The ancestor class ensures that lines of text with wordwrap line endings are handled in the component. TTextString uses an internal array of <var>TTextLineRange</var> instances to represent the lines of text. Overridden methods are provided to ensure that the internal line ranges are used to implement property values.
          </p>
          <p>
            TTextStrings is the type instantiated for use in the <var>Lines</var> property in <var>TCustomMemo</var>.
          </p>
        </descr>
        <seealso>
          <link id="#lcl.stdctrls.TCustomMemo.Create">TCustomMemo.Create</link>
          <link id="#lcl.stdctrls.TMemo">TMemo</link>
          <link id="TCustomMemoStrings"/>
        </seealso>
      </element>

      <element name="TTextStrings.FOnChange"/>
      <element name="TTextStrings.FOnChanging"/>

      <element name="TTextStrings.FArraysValid">
        <short>Boolean flag which indicates whether the array of line ranges is valid.</short>
      </element>

      <element name="TTextStrings.FLineCount">
        <short>Number of lines in the array of line ranges.</short>
      </element>

      <element name="TTextStrings.FLineCapacity">
        <short>Number of line ranges allocated for the component.</short>
      </element>

      <element name="TTextStrings.FLineRanges">
        <short>
          Pointer to an array of <var>TTextLineRange</var> instances used for the Strings in the component.
        </short>
      </element>

      <element name="TTextStrings.FText">
        <short>Member variable used to store the Text in the component.</short>
      </element>

      <element name="TTextStrings.FUpdateCount">
        <short>
          Number of times BeginUpdate has been called without a corresponding EndUpdate.
        </short>
      </element>

      <element name="TTextStrings.FChangedWhileUpdate">
        <short>Indicates if Changed was called after calling BeginUpdate.</short>
      </element>

      <element name="TTextStrings.GetTextStr">
        <short>Gets the value for the Text property.</short>
        <descr>
          <p>
            Overridden to re-implement the method from the ancestor class.
          </p>
        </descr>
        <seealso>
          <link id="#rtl.classes.TStrings.Text">TStrings.Text</link>
        </seealso>
      </element>
      <element name="TTextStrings.GetTextStr.Result">
        <short>Value for the Text property.</short>
      </element>

      <element name="TTextStrings.SetTextStr">
        <short>Sets the value for the Text property.</short>
        <descr>
          <p>
            Overridden to re-implement the method from the ancestor class.
          </p>
        </descr>
        <seealso>
          <link id="#rtl.classes.TStrings.Text">TStrings.Text</link>
        </seealso>
      </element>
      <element name="TTextStrings.SetTextStr.AValue">
        <short>New value for the Text property.</short>
      </element>

      <element name="TTextStrings.BuildArrays">
        <short>Clears and builds the array with the line ranges for the values in Text.</short>
        <descr>
          <p>
            <var>BuildArrays</var> is a method used to clear and build the internal array with the line ranges for the values in <var>Text</var>. BuildArrays detects the number of end-of-line sequences in Text, allocates memory for the dynamic array, and fills the <var>TTextLineRange</var> instances with their values.
          </p>
          <p>
            BuildArrays is called from methods used to read or write values in the <var>Strings</var>, <var>Objects</var>, or <var>Count</var> properties. It is called when the internal flag that indicates the array is valid has not been set.
          </p>
        </descr>
        <seealso>
          <link id="TTextStrings.ClearArrays"/>
          <link id="TTextStrings.Text"/>
          <link id="TTextStrings.GetCount"/>
          <link id="TTextStrings.GetLineEnd"/>
          <link id="TTextStrings.Insert"/>
          <link id="TTextStrings.Delete"/>
          <link id="TTextStrings.Exchange"/>
          <link id="TTextStrings.Move"/>
          <link id="TTextStrings.AddObject"/>
          <link id="TTextStrings.AddStrings"/>
          <link id="#rtl.classes.TStrings.Strings"/>
          <link id="#rtl.classes.TStrings.Objects"/>
          <link id="#rtl.classes.TStrings.Count"/>
          <link id="TTextLineRange"/>
        </seealso>
      </element>

      <element name="TTextStrings.GetCount">
        <short>Gets the value for the Count property.</short>
        <descr>
          <p>
            <var>GetCount</var> is overridden in <var>TTextStrings</var> to re-implement the method. It ensures that the internal array of line ranges is valid, and calls <var>BuildArrays</var> when the validity flag has not been set.
          </p>
          <p>
            The property value is set to the member value used to store the line count.
          </p>
          <p>
            GetCount does not call the inherited method.
          </p>
        </descr>
        <seealso>
          <link id="#rtl.classes.TStrings.Count"/>
        </seealso>
      </element>
      <element name="TTextStrings.GetCount.Result">
        <short>Value for the property.</short>
      </element>

      <element name="TTextStrings.Changed">
        <short>Performs actions needed after the value in Text is changed.</short>
        <descr>
          <p>
            <var>Changed</var> is a method used to perform actions needed <b>after</b> the value in the <var>Text</var> property has been changed. If <var>BeginUpdate</var> has been called without a corresponding <var>EndUpdate</var> call, no actions are performed in the method. Otherwise, the <var>OnChange</var> event handler is signalled (when assigned).
          </p>
          <p>
            Changed is called from the EndUpdate method when Text was modified following assignments to property values.
          </p>
        </descr>
        <seealso/>
      </element>

      <element name="TTextStrings.Changing">
        <short>Performs action needed when properties in the component are being updated.</short>
        <descr>
          <p>
            <var>Changing</var> is a method used to perform actions needed when property values in the component are being updated. It mimics the Changing behavior implemented in <var>TStringList</var>, where methods call Changing prior to updates to the  <var>Strings</var> or <var>Objects</var> properties.
          </p>
          <p>
            In <var>TTextStrings</var>, the method signals the <var>OnChanging</var> event handler (when assigned) if there are no updates already in progress.
          </p>
          <p>
            See <var>Changed</var> for the actions performed after property values have been updated.
          </p>
        </descr>
        <seealso>
          <link id="TTextStrings.OnChanging"/>
          <link id="TTextStrings.Changed"/>
          <link id="TTextStrings.Clear"/>
          <link id="#rtl.classes.TStrings.Strings">TStrings.Strings</link>
          <link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
        </seealso>
      </element>

      <element name="TTextStrings.Get">
        <short>Gets the value for the indexed Strings property.</short>
        <descr/>
        <seealso>
          <link id="#rtl.classes.TStrings.Strings">TStrings.Strings</link>
        </seealso>
      </element>
      <element name="TTextStrings.Get.Result">
        <short>Value for the indexed property.</short>
      </element>
      <element name="TTextStrings.Get.Index">
        <short>Ordinal position for the property value.</short>
      </element>

      <element name="TTextStrings.ClearArrays">
        <short>Clears the internal array of line ranges used in the component.</short>
        <descr>
          <p>
            <var>ClearArrays</var> 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 <var>TTextLineRange</var> instances in the array, and sets the references to <b>Nil</b>.
          </p>
          <p>
            The internal validity flag and the line counter are both reset to indicate that the array has not not been allocated.
          </p>
          <p>
            ClearArrays is called from the <var>BuildArrays</var>, <var>Clear</var>, and <var>AddStrings</var> methods.
          </p>
        </descr>
        <seealso>
          <link id="TTextStrings.BuildArrays"/>
          <link id="TTextStrings.Clear"/>
          <link id="TTextStrings.AddStrings"/>
          <link id="TTextLineRange"/>
        </seealso>
      </element>

      <element name="TTextStrings.GetObject">
        <short>Gets the value for the indexed Objects property.</short>
        <descr/>
        <seealso>
          <link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
        </seealso>
      </element>
      <element name="TTextStrings.GetObject.Result">
        <short>Value for the indexed property.</short>
      </element>
      <element name="TTextStrings.GetObject.Index">
        <short>Ordinal position in Objects with the property value.</short>
      </element>

      <element name="TTextStrings.Put">
        <short>Sets the value for the indexed Strings property.</short>
        <descr/>
        <seealso>
          <link id="#rtl.classes.TStrings.Strings">TStrings.Strings</link>
        </seealso>
      </element>
      <element name="TTextStrings.Put.Index">
        <short>Ordinal position for the new property value.</short>
      </element>
      <element name="TTextStrings.Put.S">
        <short>New value in the indexed property.</short>
      </element>

      <element name="TTextStrings.PutObject">
        <short>Sets a value in the indexed Objects property.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TTextStrings.PutObject.Index">
        <short>Ordinal position for the indexed property value.</short>
      </element>
      <element name="TTextStrings.PutObject.AnObject">
        <short>TObject instance stored in the indexed property.</short>
      </element>

      <element name="TTextStrings.GetLineLen">
        <short>
          Gets the length of a line (including optional end-of-line characters) at the specified position.
        </short>
        <descr/>
        <seealso/>
      </element>
      <element name="TTextStrings.GetLineLen.Result">
        <short>Length of the specified line.</short>
      </element>
      <element name="TTextStrings.GetLineLen.Index">
        <short>Ordinal position for the line examined in the method.</short>
      </element>
      <element name="TTextStrings.GetLineLen.IncludeNewLineChars">
        <short>True to include end-of-line characters in the line length.</short>
      </element>

      <element name="TTextStrings.GetLineEnd">
        <short>
          Gets the ordinal position where the specified line ends in the Text property.
        </short>
        <descr>
          Calls BuildArrays if the internal validity flag is not set.
        </descr>
        <seealso/>
      </element>
      <element name="TTextStrings.GetLineEnd.Result">
        <short>Offset in Text where the end of the specified line is located.</short>
      </element>
      <element name="TTextStrings.GetLineEnd.Index">
        <short>Ordinal position for the line examined in the method.</short>
      </element>
      <element name="TTextStrings.GetLineEnd.IncludeNewLineChars">
        <short>True to include end-of-line character(s) in the return value.</short>
      </element>

      <element name="TTextStrings.CountLineEndings">
        <short>Gets the number of end-of-line sequences found in the specified string.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TTextStrings.CountLineEndings.Result">
        <short>Number of end-of-line sequences found in s.</short>
      </element>
      <element name="TTextStrings.CountLineEndings.s">
        <short>String with the values examined in the method.</short>
      </element>

      <element name="TTextStrings.Create">
        <short>Constructor for the class instance.</short>
        <descr>
          <p>
            <var>Create</var> is the overridden constructor for the class instance, and calls the inherited method on entry. Create calls the <var>CheckSpecialChars</var> method (in the ancestor) to ensure that default values have assigned for the following properties:
          </p>
          <ul>
            <li>QuoteChar (")</li>
            <li>Delimiter (,)</li>
            <li>NameValueSeparator (=)</li>
            <li>TextLineBreakStyle (platform specific)</li>
          </ul>
        </descr>
        <seealso/>
      </element>

      <element name="TTextStrings.Destroy">
        <short>Destructor for the class instance.</short>
        <descr>
          <p>
            <var>Destroy</var> is the overridden destructor for the class instance. It calls the <var>Clear</var> method to remove the values in the component, and free the resources allocated to the internal array of line ranges.
          </p>
          <p>
            Destroy calls the inherited destructor prior to exiting from the method.
          </p>
        </descr>
        <seealso>
          <link id="TTextStrings.Clear"/>
          <link id="#rtl.classes.TStrings.Destroy">TStrings.Destroy</link>
        </seealso>
      </element>

      <element name="TTextStrings.Clear">
        <short>Clears the text and internal line ranges for the component.</short>
        <descr>
          <p>
            <var>Clear</var> is an overridden method which implements the abstract virtual method declared in the ancestor. It is used to remove the <var>Text</var> and line range information used in the component.
          </p>
          <p>
            Clear calls the <var>ClearArrays</var> method to free <var>TTextLineRange</var> resources allocated to the internal dynamic array. The internal line counter is reset to <b>0</b> (<b>zero</b>), and the Text property is set to an empty string (<b>''</b>).
          </p>
          <p>
            Clear is called when the component is freed, and before reading string values in the LCL component streaming mechanism.
          </p>
        </descr>
        <seealso>
          <link id="TTextStrings.Text"/>
          <link id="TTextStrings.ClearArrays"/>
          <link id="TTextStrings.Destroy"/>
          <link id="TTextLineRange"/>
          <link id="TCustomMemoStrings"/>
          <link id="#rtl.classes.TStrings.Clear">TStrings.Clear</link>
        </seealso>
      </element>

      <element name="TTextStrings.SetText">
        <short>Sets the value for the Text property from a PChar type.</short>
        <descr>
          <p>
            <var>SetText</var> is an overridden method used to set the value for the <var>Text</var> property using the specified <var>PChar</var> value.
          </p>
          <p>
            SetText stores the value in <var>TheText</var> 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 <var>TTextLineRange</var> instances to be re-populated during the next read access to <var>Strings</var> or <var>Objects</var>.
          </p>
          <p>
            SetText re-implements the method from the ancestor, and does <b>not</b> call the inherited method.
          </p>
        </descr>
        <seealso>
          <link id="#rtl.classes.TStrings.SetText">TStrings.SetText</link>
        </seealso>
      </element>
      <element name="TTextStrings.SetText.TheText">
        <short>New value for the property.</short>
      </element>

      <element name="TTextStrings.Insert">
        <short>Inserts the line of text in S at the specified position.</short>
        <descr>
          <p>
            <var>Insert</var> is an overridden method used to insert the line of text in S at the position specified in Index.
          </p>
          <p>
            <var>Index</var> contains the ordinal position in Strings where the line of text is inserted. Index must be in the range <b>0..<var>Count</var>-1</b> or an <var>EListError</var> exception is raised.
          </p>
          <p>
            <var>S</var> contains the line of text inserted in the method. S can contain an end-of-line sequence, but it is not required. The <var>LineEnding</var> for the platform is appended to the value in S if it is not already present.
          </p>
          <p>
            Insert calls <var>BuildArrays</var> 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 (<b>8</b>), and doubles each time the capacity is filled.
          </p>
          <p>
            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.
          </p>
          <p>
            Insert re-implements the method defined in the ancestor, and does <b>not</b> call the inherited method.
          </p>
          <p>
            Use <var>Add</var> or <var>AddStrings</var> to append one or more lines of text to the values in Strings.
          </p>
        </descr>
        <errors>
          Raises an EListError exception if Index contains an invalild position in the list of string values.
        </errors>
        <seealso>
          <link id="#rtl.classes.TStrings.Insert">TStrings.Insert</link>
        </seealso>
      </element>
      <element name="TTextStrings.Insert.Index">
        <short>Ordinal position where the line of text is inserted.</short>
      </element>
      <element name="TTextStrings.Insert.S">
        <short>Value for the line of text inserted in the method.</short>
      </element>

      <element name="TTextStrings.Delete">
        <short>Deletes the line of text at the specified position.</short>
        <descr>
          <p>
            <var>Delete</var> is an overridden method used to delete the line of text at the specified position. <var>BuildArrays</var> is called to populate the internal array of <var>TTextLineRange</var> instances when the internal validity flag is not set.
          </p>
          <p>
            <var>Index</var> contains the ordinal position in <var>Strings</var> for the line of text removed in the method. Index must be in the range <b>0..<var>Count</var>-1</b> or an <var>EStringListError</var> exception is raised.
          </p>
          <p>
            Line range information is used to adjust both <var>Text</var> 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.
          </p>
        </descr>
        <errors>
          Raises an EStringListError exception when Index is not a valid position in the list of string values.
        </errors>
        <seealso>
          <link id="TTextStrings.BuildArrays"/>
          <link id="TTextStrings.Text"/>
          <link id="TTextLineRange"/>
          <link id="EStringListError"/>
          <link id="#rtl.classes.TStrings.Count">TStrings.Count</link>
          <link id="#rtl.classes.TStrings.Delete">TStrings.Delete</link>
          <link id="#rtl.classes.TStrings.Strings">TStrings.Strings</link>
        </seealso>
      </element>
      <element name="TTextStrings.Delete.Index">
        <short>Ordinal position for the value removed from the Strings property.</short>
      </element>

      <element name="TTextStrings.Exchange">
        <short>Swaps the line values at the specified positions.</short>
        <descr>
          <p>
            <var>Exchange</var> 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.
          </p>
          <p>
            Values in Index1 and Index2 must be in the range 0..Count-1 or an EStringListError exception is raised.
          </p>
          <p>
            <var>BuildArrays</var> is called to populate the internal array of <var>TTextLineRange</var> instances when the internal validity flag is not set. <var>MakeTextBufferUnique</var> is called to ensure that the reference count for the <var>Text</var> member is <b>1</b>.
          </p>
          <p>
            When <var>Index2</var> is the last line of text, a LineEnding sequence is added to Text when not already present.
          </p>
          <p>
            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.
          </p>
          <p>
            Exchange also swaps the values in the Objects property at the specified index positions.
          </p>
          <p>
            Exchange re-implements the method defined in the ancestor, and does <b>not</b> call the inherited method.
          </p>
        </descr>
        <seealso>
          <link id="#rtl.classes.TStrings.Exchange">TStrings.Exchange</link>
        </seealso>
      </element>
      <element name="TTextStrings.Exchange.Index1">
        <short>First position for the value exchange.</short>
      </element>
      <element name="TTextStrings.Exchange.Index2">
        <short>Second position for the value exchange.</short>
      </element>

      <element name="TTextStrings.Move">
        <short>Moves a String value from the current position to the new position.</short>
        <descr/>
        <seealso>
          <link id="#rtl.classes.TStrings.Move">TStrings.Move</link>
        </seealso>
      </element>
      <element name="TTextStrings.Move.CurIndex">
        <short>Current ordinal position for the string.</short>
      </element>
      <element name="TTextStrings.Move.NewIndex">
        <short>New ordinal position for the string.</short>
      </element>

      <element name="TTextStrings.MakeTextBufferUnique">
        <short>Ensures that the reference count for the Text member is 1.</short>
        <descr>
          <p>
            Calls the UniqueString routine from the RTL <file>system</file> unit.
          </p>
        </descr>
        <seealso>
          <link id="#rtl.system.UniqueString">UniqueString</link>
        </seealso>
      </element>

      <element name="TTextStrings.BeginUpdate">
        <short>Starts an update process for the component.</short>
        <descr>
          <p>
            <var>BeginUpdate</var> is a method used to start an update process for the component. It increments an internal update counter used to consolidate <var>OnChanging</var> and <var>OnChange</var>  event notifications. The counter value is used in the <var>Changing</var> and <var>Changed</var> methods, and controls when the event notifications are enabled and performed.
          </p>
          <p>
            Use EndUpdate to decrement the internal update counter.
          </p>
        </descr>
        <seealso>
          <link id="TTextStrings.OnChanging"/>
          <link id="TTextStrings.OnChange"/>
          <link id="TTextStrings.Changing"/>
          <link id="TTextStrings.Changed"/>
          <link id="TTextStrings.EndUpdate"/>
          <link id="#rtl.classes.TStrings.BeginUpdate">TStrings.BeginUpdate</link>
        </seealso>
      </element>

      <element name="TTextStrings.EndUpdate">
        <short>Finishes an update process for the component.</short>
        <descr>
          <p>
            <var>EndUpdate</var> is a method used to finish an active update process for the component.
          </p>
          <p>
            For each call to <var>BeginUpdate</var>, there needs to be a corresponding call to EndUpdate. The methods are used as a pair to consolidate <var>OnChanging</var> and <var>OnChange</var> event notifications.
          </p>
          <p>
            EndUpdate decrements the internal update counter incremented by calling BeginUpdate. When the update counter is a positive non-zero value, the <var>Changed</var> method is not called and the <var>OnChange</var> event handler is not signalled.
          </p>
           <p>
             An <var>Exception</var> is raised if the internal update counter is &lt;= 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).
           </p>
           <p>
             Use BeginUpdate to start an update process by incrementing the value for the internal counter.
           </p>
        </descr>
        <errors>
          Raises an Exception if the internal update counter is &lt;;= 0 when the method is called.
        </errors>
        <seealso>
          <link id="TTextStrings.BeginUpdate"/>
           <link id="#rtl.classes.TStrings.EndUpdate">TStrings.EndUpdate</link>
        </seealso>
      </element>

      <element name="TTextStrings.GetText">
        <short>Gets the value for the Text property as a PChar type.</short>
        <descr/>
        <seealso>
          <link id="TTextStrings.Text"/>
          <link id="#rtl.classes.TStrings.GetText">TStrings.GetText</link>
        </seealso>
      </element>
      <element name="TTextStrings.GetText.Result">
        <short>Value for the property as a PChar type.</short>
      </element>

      <element name="TTextStrings.IndexOf">
        <short>Gets the ordinal position for the specified String value.</short>
        <descr/>
        <seealso>
          <link id="#rtl.classes.TStrings.IndexOf">TStrings.IndexOf</link>
        </seealso>
      </element>
      <element name="TTextStrings.IndexOf.Result">
        <short>Ordinal position for the requested value.</short>
      </element>
      <element name="TTextStrings.IndexOf.S">
        <short>Value to locate in the method.</short>
      </element>

      <element name="TTextStrings.Add">
        <short>Appends the specified text to the values in Strings.</short>
        <descr>
          <p>
            Calls <var>AddObject</var> to append the value in <var>S</var>. <b>Nil</b> is used as the value for the object parameter.
          </p>
        </descr>
        <seealso>
          <link id="#rtl.classes.TStrings.Add">TStrings.Add</link>
        </seealso>
      </element>
      <element name="TTextStrings.Add.Result">
        <short>Ordinal position in Strings where the value was stored.</short>
      </element>
      <element name="TTextStrings.Add.S">
        <short>String appended to the Strings property.</short>
      </element>

      <element name="TTextStrings.AddObject">
        <short>Adds a String and Object pair to the string list.</short>
      <descr>
        <p>
          Adds a <var>LineEnding</var> if the value in <var>Text</var> does not already end with one of the end-of-line characters.
        </p>
        <p>
          Calls <var>BuildArrays</var> when an object instance has been assigned to <var>AObject</var>.
        </p>
        <p>
          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.
        </p>
        <p>
          The value in AObject is stored in the <var>TTextLineRange</var> instance for the new line. The start and end positions, and the text are stored in the line range information.
        </p>
        <p>
          The internal line count is incremented prior to exiting from the method.
        </p>
      </descr>
        <seealso/>
      </element>
      <element name="TTextStrings.AddObject.Result">
        <short>Ordinal position where the string and object were stored.</short>
      </element>
      <element name="TTextStrings.AddObject.S">
        <short>String value added to component.</short>
      </element>
      <element name="TTextStrings.AddObject.AObject">
        <short>TObject instance (or Nil) added to the component.</short>
      </element>

      <element name="TTextStrings.AddStrings">
        <short>Adds the lines of text in TheStrings to the current class instance.</short>
        <descr>
          <p>
            <var>AddStrings</var> is an overridden method in <var>TTextStrings</var> used to add the lines of text in <var>TheStrings</var> to the current class instance. No actions are performed in the method when <var>TheStrings</var> does not contain any lines of text.
          </p>
          <p>
            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.
          </p>
        </descr>
        <seealso>
          <link id="TTextStrings.AddObject"/>
          <link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
          <link id="#rtl.classes.TStrings.AddStrings">TStrings.AddStrings</link>
        </seealso>
      </element>
      <element name="TTextStrings.AddStrings.TheStrings">
        <short>String list with the values added in the method.</short>
      </element>

      <element name="TTextStrings.LoadFromFile">
        <short>Loads the content in the string list from the specified file name.</short>
        <descr>
          <p>
            Creates a temporary <var>TFileStream</var> instance for the <var>FileName</var> argument.  The file handle is opened for reading, and shared write access is denied. The inherited <var>LoadFromStream</var> method is called to load the values in the string list from the file stream.
          </p>
        </descr>
        <seealso>
          <link id="#rtl.classes.TStrings.LoadFromFile">TStrings.LoadFromFile</link>
          <link id="TTextStrings.SaveToFile"/>
        </seealso>
      </element>
      <element name="TTextStrings.LoadFromFile.FileName">
        <short>File name with the values loaded in the method.</short>
      </element>

      <element name="TTextStrings.SaveToFile">
        <short>Saves the content in the string list to the specified file name.</short>
        <descr>
          <p>
            Creates a temporary <var>TFileStream</var> instance for the <var>FileName</var> argument. The file is created if it does not already exist. The inherited <var>SaveToStream</var> method is called to store content in the string list to the file stream.
          </p>
        </descr>
        <seealso>
          <link id="#rtl.classes.TStrings.SaveToFile">TStrings.SaveToFile</link>
          <link id="TTextStrings.LoadFromFile"/>
        </seealso>
      </element>
      <element name="TTextStrings.SaveToFile.FileName">
        <short>File name where the content is stored.</short>
      </element>

      <element name="TTextStrings.Text">
        <short>Contains the textual representation for the values in Strings.</short>
        <descr>
          <p>
            <var>Text</var> is a <var>String</var> property which contains the textual representation for the values in the <var>Strings</var> property. <var>TTextStrings</var> re-implements the Text property as defined in <var>TStrings</var>. The write specifier (<var>SetTextStr</var>) is overridden, and forces the internal array of line ranges to be rebuilt during the next read access.
          </p>
        </descr>
        <seealso>
          <link id="#rtl.classes.TStrings.Text">TStrings.Text</link>
        </seealso>
      </element>

      <element name="TTextStrings.OnChange">
        <short>
          Event handler signalled when values in Strings or Objects have been changed.
        </short>
        <descr>
          <p>
            <var>OnChange</var> is a <var>TNotifyEvent</var> property with the event handler signalled when values in the <var>Strings</var> and/or <var>Objects</var> properties have been changed.
          </p>
          <p>
            OnChange is signalled from the <var>Changed</var> method, and occurs after the property value(s) are stored in the component.
          </p>
        </descr>
        <seealso>
          <link id="TTextStrings.Changed"/>
          <link id="#rtl.classes.TStrings.Strings">TString.Strings</link>
          <link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
          <link id="#rtl.classes.TNotifyEvent">TNotifyEvent</link>
        </seealso>
      </element>

      <element name="TTextStrings.OnChanging">
        <short>Event handler signalled before properties are updated in the component.</short>
        <descr>
          <p>
            <var>OnChanging</var> is a <var>TNotifyEvent</var> property with the event handler signalled before the  <var>Strings</var> or <var>Objects</var> properties are updated in the component.
          </p>
          <p>
            OnChanging is signalled from the <var>Changing</var> method when an update process in not already active.
          </p>
        </descr>
        <seealso>
          <link id="TTextStrings.Changing"/>
          <link id="#rtl.classes.TStrings.Strings">TString.Strings</link>
          <link id="#rtl.classes.TStrings.Objects">TStrings.Objects</link>
          <link id="#rtl.classes.TNotifyEvent">TNotifyEvent</link>
        </seealso>
      </element>
    </module>
    <!-- TextStrings -->
  </package>
</fpdoc-descriptions>
