CreateLines (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(31 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Template:Stringlist:CreateLines subtitle}}
{{Template:Stringlist:CreateLines subtitle}}


This method is used to create a delimited string from a Stringlist object. Generally, as the name of the method suggests, the string would be created with line-end character delimited lines. The CreateLines method accepts one positional argument and one name required argument, and it returns a string result.
This method is used to create a delimited string from a <var>Stringlist</var> object. Generally, as the name of the method suggests, the string would be created with line-end character delimited lines. The <var>CreateLines</var> method accepts one positional argument and one name required argument, and it returns a string result.


==Syntax==
==Syntax==
Line 7: Line 7:
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%string </th>
<tr><th>%string</th>
<td>This longstring is to contain the data in '''%sl'''. </td></tr>
<td>This <var>Longstring</var> is to contain the data in <var class="term">sl</var>. </td></tr>
<tr><th>sl </th>
<tr><th>sl</th>
<td>A Stringlist object. </td></tr>
<td>A <var>Stringlist</var> object. </td></tr>
<tr><th>delim </th>
<tr><th>delim</th>
<td>The delimiter string to be used between Stringlist items in the output string. This is an optional argument. If this argument is not specified, the delimiter used is X'25', which is an EBCDIC line-feed. If this argument is a null string, the Stringlist items are concatenated. </td></tr>
<td>The delimiter string to be used between <var>Stringlist</var> items in the output string. This is an optional argument. If this argument is not specified, the delimiter used is <code>X'25'</code>, which is an EBCDIC line-feed. If this argument is a null string, the <var>Stringlist</var> items are concatenated. </td></tr>
<tr><th><b>AddTrailingDelimiter=</b> boolean </th>
<tr><th><var>AddTrailingDelimiter</var></th>
<td>The name required argument <tt>.AddTrailingDelimiter</tt> is a boolean value that indicates whether a trailing delimiter should be added to the output string. This optional argument defaults to <tt>.true</tt>, which results in a trailing delimiter being added to the output string.</td></tr>
<td>The name required argument <var>AddTrailingDelimiter</var> is a <var>Boolean</var> value that indicates whether a trailing delimiter should be added to the output string. This optional argument defaults to <var>True</var>, which results in a trailing delimiter being added to the output string.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>All errors in CreateLines result in request cancellation.
<li>All errors in <var>CreateLines</var> result in request cancellation.
<li>The CreateLines method is available in <var class=product>Sirius Mods</var> Version 6.7 and later.
<li>The <var>[[ParseLines (String function)|ParseLines]]</var> function performs the inverse operation; that is, it creates a <var>Stringlist</var> consisting of substrings bewteen an identified separator string.
</ul>
</ul>


==Examples==
==Examples==
<ol>
<ol>
<li>The following loads a Stringlist with the names of the four greatest stooges and then places them into a string, separated by plus signs:
<li>The following loads a <var>Stringlist</var> with the names of the four greatest stooges and then places them into a string, separated by plus signs:
<pre>
<p class="code">%list is object stringList
%list is object stringList
%stooges is longstring
%stooges is longstring
%list = new
%list = new
Line 37: Line 36:
end text
end text
%stooges = %list:createLines('+')
%stooges = %list:createLines('+')
</pre>
</p>


After the CreateLines method, <tt>.%stooges</tt> contains the following:
After calling <var>CreateLines</var>, <code>%stooges</code> contains the following:
<pre>
<p class="code">Curly+Larry+Moe+Shemp+
Curly+Larry+Moe+Shemp+
</p>
</pre>
<li>In the following example, the contents of <var>Stringlist</var> <code>%sendData</code> are sent over a <var class="product">[[Janus Sockets]]</var> connection (using a <var>Socket</var> object) as line-feed delimited lines:
<li>In the following example, the contents of Stringlist <tt>.%sendData</tt> are sent over a ''[[Janus Sockets]]'' connection (using a Socket object) as line-feed delimited lines:
<p class="code">%sock is object socket
<pre>
%sock is object socket
%sendData is object stringList
%sendData is object stringList
...
...
%sock:send( %senddata:createLines($x2c('25')) )
%sock:send( %senddata:createLines($x2c('25')) )
</pre>
</p>


In this example, the delimiter parameter (<tt>.$x2c('25')</tt>) was really unnecessary because it's the default. In this example, one would presume that the socket is in<tt>.CHAR</tt> mode, that is, data is being translated from EBCDIC to ASCII. Obviously, the CreateLines method does nothing that you could not do quite easily in User Language. It is just a little more convenient and efficient.<li>The default behavior of CreateLines is to add a trailing delimiter. This default is based on the fact that most ASCII applications end the last line of a file with the line-end character(s), so they expect other applications to do the same. Still, the default can produce somewhat undesirable behavior, especially in interactions with [[ParseLines (Stringlist subroutine)]].  
In this example, the delimiter parameter (<code>$x2c('25')</code>) was really unnecessary because it's the default. In this example, one would presume that the socket is in <var>CHAR</var> mode, that is, data is being translated from EBCDIC to ASCII. Obviously, the <var>CreateLines</var> method does nothing that you could not do quite easily in <var class="product">User Language</var>. It is just a little more convenient and efficient.<li>The default behavior of <var>CreateLines</var> is to add a trailing delimiter. This default is based on the fact that most ASCII applications end the last line of a file with the line-end character(s), so they expect other applications to do the same. Still, the default can produce somewhat undesirable behavior, especially in interactions with <var>ParseLines</var>.
In the following example, a string is created without a trailing line delimiter:
In the following example, a string is created without a trailing line delimiter:
<pre>
<p class="code">%sendString = %senddata:createLines($x2c('25'), addTrailingDelimiter=false)
%sendString = %senddata:createLines($x2c('25'), addTrailingDelimiter=false)
</p>
</pre>
</ol>
</ol>


[[Category:Stringlist methods|CreateLines function]]
==See also==
{{Template:Stringlist:CreateLines footer}}

Latest revision as of 15:22, 31 October 2012

Create delimited string from Stringlist (Stringlist class)


This method is used to create a delimited string from a Stringlist object. Generally, as the name of the method suggests, the string would be created with line-end character delimited lines. The CreateLines method accepts one positional argument and one name required argument, and it returns a string result.

Syntax

%string = sl:CreateLines[( [delim], [AddTrailingDelimiter= boolean])]

Syntax terms

%string This Longstring is to contain the data in sl.
sl A Stringlist object.
delim The delimiter string to be used between Stringlist items in the output string. This is an optional argument. If this argument is not specified, the delimiter used is X'25', which is an EBCDIC line-feed. If this argument is a null string, the Stringlist items are concatenated.
AddTrailingDelimiter The name required argument AddTrailingDelimiter is a Boolean value that indicates whether a trailing delimiter should be added to the output string. This optional argument defaults to True, which results in a trailing delimiter being added to the output string.

Usage notes

  • All errors in CreateLines result in request cancellation.
  • The ParseLines function performs the inverse operation; that is, it creates a Stringlist consisting of substrings bewteen an identified separator string.

Examples

  1. The following loads a Stringlist with the names of the four greatest stooges and then places them into a string, separated by plus signs:

    %list is object stringList %stooges is longstring %list = new text to %list Curly Larry Moe Shemp end text %stooges = %list:createLines('+')

    After calling CreateLines, %stooges contains the following:

    Curly+Larry+Moe+Shemp+

  2. In the following example, the contents of Stringlist %sendData are sent over a Janus Sockets connection (using a Socket object) as line-feed delimited lines:

    %sock is object socket %sendData is object stringList ... %sock:send( %senddata:createLines($x2c('25')) )

    In this example, the delimiter parameter ($x2c('25')) was really unnecessary because it's the default. In this example, one would presume that the socket is in CHAR mode, that is, data is being translated from EBCDIC to ASCII. Obviously, the CreateLines method does nothing that you could not do quite easily in User Language. It is just a little more convenient and efficient.
  3. The default behavior of CreateLines is to add a trailing delimiter. This default is based on the fact that most ASCII applications end the last line of a file with the line-end character(s), so they expect other applications to do the same. Still, the default can produce somewhat undesirable behavior, especially in interactions with ParseLines. In the following example, a string is created without a trailing line delimiter:

    %sendString = %senddata:createLines($x2c('25'), addTrailingDelimiter=false)

See also