Stringlist class: Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(24 intermediate revisions by 9 users not shown)
Line 1: Line 1:
The '''Stringlist''' class provides a facility that resembles an unbounded array of strings.
The '''Stringlist''' class provides a facility that resembles an unbounded array of strings.


While less generalized than a [[Collection class]], it has a richer set of methods than any Collection class.  Unfortunately, the Stringlist class cannot be thought of as either a subset
While less generalized than a <var>[[Collections|collection]]</var> class, it has a richer set of methods than any collection class.  Unfortunately, the <var>Stringlist</var> class cannot be thought of as either a subset or superset of collections, so it is not necessarily an obvious decision as to which to use.
or superset of collections, so it is not necessarily an obvious decision as to which to use.


See [[:Category:Stringlist methods]] for documentation on the Stringlist method API.
==Stringlist usage==
The <var>Stringlist</var> class is essentially an object-oriented version of [[$lists]]. It is strongly recommended that all new applications use <var>Stringlists</var> instead of $lists:


==Stringlist usage==
<ul>
<li>Because they use the object-oriented model of instantiation, <var>Stringlists</var> eliminate the confusing behavior of $lists that results from their being tied to the statement that created them.


The Stringlist class is essentially an object-oriented version of $lists (described in the ''Sirius Functions Reference Manual''). It is strongly recommended that all new applications use Stringlists instead of $lists:
<li><var>Stringlists</var> are strongly datatyped, so application errors resulting from misuse of $list identifiers are eliminated. Code is clearer because it is obvious that a variable is a <var>Stringlist</var> — $list identifiers are simply <var>Float</var>, <var>Fixed</var>, or <var>String</var> datatypes.


<ul>
<li>Because they use the object-oriented model of instantiation, Stringlists eliminate the confusing behavior of $lists that results from their being tied to the statement that created them.
<li>Stringlists are strongly datatyped, so application errors resulting from misuse of $list identifiers are eliminated. Code is clearer because it is obvious that a variable is a Stringlist -- $list identifiers are simply Float, Fixed, or String datatypes.
<li>Because of the way $lists are instantiated, they are essentially unusable inside class methods.
<li>Because of the way $lists are instantiated, they are essentially unusable inside class methods.
</ul>
</ul>


Stringlist objects are instantiated with the [[New (Stringlist function)|New]] function or with methods that return Stringlist instances "under the covers" such as the [[SortNew {Stringlist method)|SortNew]] or [[Copy (Stringlist method}|Copy]] methods.
<var>Stringlist</var> objects are instantiated with the <var>[[New_(Stringlist_constructor)|New]]</var> function or with methods that return <var>Stringlist</var> instances "under the covers" such as the <var>[[Sort (Stringlist subroutine)|Sort]]</var>, <var>[[SortNew (Stringlist function)|SortNew]]</var> or <var>[[Copy (Stringlist function)|Copy]]</var> methods.


The system [[Discard (Stringlist method)|Discard]] method deletes a Stringlist object.
The system <var>[[Object variables#Discarding objects|Discard]]</var> method deletes a <var>Stringlist</var> object.


Stringlists are stored in CCATEMP, so they take minimal server table space no matter how large the Stringlist.
<var>Stringlists</var> are stored in CCATEMP, so they take minimal server table space no matter how large the <var>Stringlist</var>.


Like all system classes, Stringlists are considered '''longstring-capable''', that is, any string inputs and outputs are considered longstrings for expression-compilation purposes.  The main impact of this is that Stringlist inputs and outputs will have standard longstring truncation behavior: truncation by assignment results in request cancellation.
Like all system classes, <var>Stringlists</var> are considered <var>[[Longstrings|longstring]]</var>-capable, that is, any string inputs and outputs are considered <var>longstrings</var> for expression-compilation purposes.  The main impact of this is that <var>Stringlist</var> inputs and outputs will have standard <var>longstring</var> truncation behavior: truncation by assignment results in request cancellation.


In addition to the described methods, it is also possible to add data to a Stringlist with the [[Text and Html statements|HTML or Text statement]] using the '''To''' clause. This is especially useful if there is a block of mostly constant text to be added to a Stringlist.
In addition to the described methods, it is also possible to add data to a <var>Stringlist</var> with the <var>[[Text and Html statements|HTML/Text]]</var> statement using the <var>To</var> clause. This is especially useful if there is a block of mostly constant text to be added to a <var>Stringlist</var>.


Begin
<p class="code">Begin
    %sl is object Stringlist
  %sl is object Stringlist
    %sl = New
  %sl = New
    Text to %sl
  Text to %sl
    <html>
      <html>
    <head>
      <head>
    <title>Loading a complete web page into a stringlist</title>
      <title>Loading a complete web page into a stringlist</title>
    </head>
      </head>
    <body>
      <body>
    Each line of this text block is a new stringlist item.
      Each line of this text block is a new stringlist item.
    </body>
      </body>
    End Text
  End Text
    %sl:Print
  %sl:Print
End
End</p>


==Migrating from $lists to Stringlists==
==Migrating from $lists to Stringlists==
The <var>[[MoveFromId (Stringlist subroutine)|MoveFromId]]</var> and <var>[[MoveToId (Stringlist subroutine)|MoveToId]]</var> methods facilitate migration from $lists to <var>Stringlists</var>: <var>Stringlists</var> can be passed to code that works on $lists after being converted to a $list with <var>[[MoveToId (Stringlist subroutine)|MoveToId]]</var>; $lists can be converted to <var>Stringlists</var> with <var>[[MoveFromId (Stringlist subroutine)|MoveFromId]]</var>.


The [[MoveFromId (Stringlist method)|MoveFromId]] and [[MoveToId (Stringlist method)|MoveToId]] methods facilitate migration from $lists to Stringlists: Stringlists can be passed to code that works on $lists after being converted to a $list with MoveToId; $lists can be converted to Stringlists with MoveFromId.
==Compatibility==
<p><var>Stringlist</var> items can be as many as 2**31-1 bytes long.  While all methods work correctly with <var>Stringlist</var> items longer than 6124 bytes, a few methods such as <var>[[Locate and LocateUp (Stringlist_functions)|Locate]]</var> and <var>[[Locate and LocateUp_(Stringlist_functions)|LocateUp]]</var> restrict their processing to the first 6124 bytes of a <var>Stringlist</var> item.</p>


==Compatibility==
<p>There is no overall practical size limit on a stringlist object itself. The stringlist is maintained internally as a binary tree, to a maximum depth of three levels, similarly to a $list object. The stringlist object will be as compact a possible if it is built using the add method to add successive stringlist items to the end of the object, as opposed to using methods such as insert, delete, and replace, where the compaction of the stringlist object will be reduced.  </p>


Before ''Sirius Mods'' Version 6.6, Stringlist items were limited to 6124 bytes in
<p>For stringlists where the average stringlist item length is less than the pagesize ( 6144 ), then the maximum overall size of the stringlist object is approximately 3.5 Gigabytes. If the average stringlist item length is greater, up to the maximum item length of 2 gigabytes, then the overall object size can extend in theory up to 1.26 petabytes. </p>
length.


In ''Sirius Mods'' Version 6.6, this limitation was lifted, and Stringlist items can be
==List of Stringlist methods==
as many as 2**31-1 bytes long.  While, as of ''Sirius Mods'' Version 6.6, all methods work correctly with Stringlist items longer than 6124 bytes, a few methods such as Locate and LocateUp still restrict their processing to the first 6124 bytes of a Stringlist item.
The individual <var>Stringlist</var> methods are summarized in [[List of Stringlist methods|"List of Stringlist methods"]].


[[Category:Stringlists| Stringlists - an unbounded array of strings]]
[[Category:System classes]]

Latest revision as of 15:20, 20 May 2019

The Stringlist class provides a facility that resembles an unbounded array of strings.

While less generalized than a collection class, it has a richer set of methods than any collection class. Unfortunately, the Stringlist class cannot be thought of as either a subset or superset of collections, so it is not necessarily an obvious decision as to which to use.

Stringlist usage

The Stringlist class is essentially an object-oriented version of $lists. It is strongly recommended that all new applications use Stringlists instead of $lists:

  • Because they use the object-oriented model of instantiation, Stringlists eliminate the confusing behavior of $lists that results from their being tied to the statement that created them.
  • Stringlists are strongly datatyped, so application errors resulting from misuse of $list identifiers are eliminated. Code is clearer because it is obvious that a variable is a Stringlist — $list identifiers are simply Float, Fixed, or String datatypes.
  • Because of the way $lists are instantiated, they are essentially unusable inside class methods.

Stringlist objects are instantiated with the New function or with methods that return Stringlist instances "under the covers" such as the Sort, SortNew or Copy methods.

The system Discard method deletes a Stringlist object.

Stringlists are stored in CCATEMP, so they take minimal server table space no matter how large the Stringlist.

Like all system classes, Stringlists are considered longstring-capable, that is, any string inputs and outputs are considered longstrings for expression-compilation purposes. The main impact of this is that Stringlist inputs and outputs will have standard longstring truncation behavior: truncation by assignment results in request cancellation.

In addition to the described methods, it is also possible to add data to a Stringlist with the HTML/Text statement using the To clause. This is especially useful if there is a block of mostly constant text to be added to a Stringlist.

Begin %sl is object Stringlist %sl = New Text to %sl <html> <head> <title>Loading a complete web page into a stringlist</title> </head> <body> Each line of this text block is a new stringlist item. </body> End Text %sl:Print End

Migrating from $lists to Stringlists

The MoveFromId and MoveToId methods facilitate migration from $lists to Stringlists: Stringlists can be passed to code that works on $lists after being converted to a $list with MoveToId; $lists can be converted to Stringlists with MoveFromId.

Compatibility

Stringlist items can be as many as 2**31-1 bytes long. While all methods work correctly with Stringlist items longer than 6124 bytes, a few methods such as Locate and LocateUp restrict their processing to the first 6124 bytes of a Stringlist item.

There is no overall practical size limit on a stringlist object itself. The stringlist is maintained internally as a binary tree, to a maximum depth of three levels, similarly to a $list object. The stringlist object will be as compact a possible if it is built using the add method to add successive stringlist items to the end of the object, as opposed to using methods such as insert, delete, and replace, where the compaction of the stringlist object will be reduced.

For stringlists where the average stringlist item length is less than the pagesize ( 6144 ), then the maximum overall size of the stringlist object is approximately 3.5 Gigabytes. If the average stringlist item length is greater, up to the maximum item length of 2 gigabytes, then the overall object size can extend in theory up to 1.26 petabytes.

List of Stringlist methods

The individual Stringlist methods are summarized in "List of Stringlist methods".