Center and Centre (String functions): Difference between revisions

From m204wiki
Jump to navigation Jump to search
 
(38 intermediate revisions by 7 users not shown)
Line 1: Line 1:
For a given input string and suitable specified length, this function                             
{{Template:String:Center and Centre subtitle}}
returns a string of the requested length that has the original string                             
embedded in the center.                                                                           
If the requested length is larger than the length of the input string,                             
pad characters are added to the input string to produce the returned string.                       
If the requested length is shorter, the input string's front and end are cropped                   
to produce the returned string.                                                                   
                                                                                                   
''''Centre'''' is a synonym for the Center function.                                               
                                                                                                   
This [[Intrinsic classes|intrinsic]] function is available as of version 7.3 of the [[Sirius Mods]].
===Center syntax===
  %outStr = string:Center(length, [Pad=char] [, OffsetLeft=bool])
===Syntax Terms===                                                                                 
<dl> 
<dt>%outStr                                                                     
<dd>A string variable to receive the result of the Center method.               
<dt>string                                                                       
<dd>The string to which the method is applied.                                   
<dt>length                                                                       
<dd>The number of characters in the output string.                               
If this value is greater than the length of the method object string,           
the method object string is padded on the right and left to the requested length.
If the method object is shorter than ''length'', it is                           
cropped on the left and right.                                                   
<dt>Pad=char                                                             
<dd>An optional, name-required, argument that indicates the character used to   
pad ''string'' on the right and left (if the ''length'' value                   
is greater than the length of ''string'').                                       
If an uneven number of pad characters is required,
the location of the extra pad character is determined by the value of the       
Offsetleft parameter.                                                           
                                                                               
The default for ''char'' is the blank character.                               
Specifying an explicit null results in no padding.                             
<dt>OffsetLeft=bool                                                             
<dd>An optional, name-required, argument that is a                             
boolean value indicating where to put the extra character if the               
requested padding or cropping is asymmetric.                                   
If the required number of pad characters or characters to be cropped is not even,
the default (''''False'''') is to produce an extra character on the right.     
                                                                               
</dl>                                                                           
===Usage Notes===                                                               
*The ''length'' value must be a non-negative number; a negative number results in request cancellation.   
For a ''length'' greater than 255, the output variable must be defined as a longstring.               
A ''length'' value greater than the declared length of the output string results in a request cancellation.             
*The pad parameter value must be either null or a single character. A longer value results in a compilation error.                     
===Examples===                                                     
                                                                   
The following request prints ''''++++Hello, World!+++'''',         
then ''''llo, World''''                                             
    begin                                                           
      %x is string len 15                                           
      %out is  string len 20                                       
      %len is float                                                 
      %x = 'Hello, World!'                             
      %len = 20                                       
      %out = %x:center(%len, Pad='+', OffsetLeft=True) 
      [[Intrinsic classes#printtext|printText]] {%out}        
                                                       
      %len = 10                                       
      %out = %x:center(%len, Pad='+', OffsetLeft=True) 
      printText {%out}                                
    end


===See also===                                                                                       
For a given input string and suitable specified length, <var>Center</var> / <var>Centre</var> returns a string of the requested length that has the original string embedded in the center.  If the requested length is larger than the length of the input string, pad characters are added to the input string to produce the returned string.  If the requested length is shorter, the input string's beginning and end are cropped to produce the returned string.
[[List of Intrinsic String Methods]]


<var>Centre</var> is a synonym for the <var>Center</var> function.


[[Category:Intrinsic String methods|Center function]]
==Syntax==
[[Category:Intrinsic methods]]
{{Template:String:Center syntax}}
[[Category:System methods]]
{{Template:String:Centre syntax}}
 
===Syntax terms===
<table class="syntaxTable">
<tr><th>%outString</th>
<td>A string variable to receive the result of the <var>Center</var> / <var>Centre</var> method.</td></tr>
<tr><th>string</th>
<td>The string to which the method is applied.</td></tr>
 
<tr><th>length</th>
<td>The number of characters desired in the output <var class="term">%string</var>.  If this value is greater than the length of the method object <var class="term">string</var>, the method object <var class="term">string</var> is padded on both the right and left to the requested length. If the method object is shorter than <var class="term">length</var>, it is cropped on both the left and right.</td></tr>
 
<tr><th><var>Pad</var></th>
<td>This is an optional, [[Notation conventions for methods#Named parameters|name required]], parameter that defines the character used to pad <var class="term">string</var> on the right and left (if the <var class="term">length</var> value is greater than the length of <var class="term">string</var>).  If an uneven number of pad characters is required, the location of the extra pad character is determined by the value of the <var>OffsetLeft</var> parameter.  The default for <var class="term">c</var> is a blank character (<code>' '</code>). Specifying an explicit null (<code><nowiki>''</nowiki></code>) results in no padding.</td></tr>
 
<tr><th><var>OffsetLeft</var></th>
<td>An optional, name-required, argument that is a <var>[[Boolean enumeration|Boolean]]</var> enumeration value indicating where to put the extra character if the requested padding or cropping is asymmetric.  If the required number of pad characters or characters to be cropped is not even, the default (<code>False</code>) is to produce an extra character on the right.</td></tr>
</table>
 
==Usage notes==
<ul><li>The <var class="term">length</var> value must be a non-negative number; a negative number results in request cancellation.  For a <var class="term">length</var> greater than 255, the output variable must be defined as a longstring.  A <var class="term">length</var> value greater than the declared length of the output string results in a request cancellation.
 
<li>The <var>Pad</var> parameter value must be either null or a single character. A longer value results in a compilation error.
 
<li><var>Center</var> / <var>Centre</var> is available as of <var class="product">Sirius Mods</var> version 7.3.
</ul>
 
==Examples==
The following request prints
<p><code>++++Hello, World!+++</code>, then</p>
<p><code>ello, Worl</code></p>.
<p class="code">begin
  %x is string len 15
  %out is  string len 20
  %len is float
  %x = 'Hello, World!'
  %len = 20
  %out = %x:center(%len, Pad='+', OffsetLeft=True)
  [[PrintText statement|printText]] {%out}
 
  %len = 10
  %out = %x:center(%len, Pad='+', OffsetLeft=True)
  printText {%out}
end
</p>
 
==See also==
{{Template:String:Center and Centre footer}}

Latest revision as of 17:23, 10 January 2014

Center the input string within a return string of a specified length (String class)


For a given input string and suitable specified length, Center / Centre returns a string of the requested length that has the original string embedded in the center. If the requested length is larger than the length of the input string, pad characters are added to the input string to produce the returned string. If the requested length is shorter, the input string's beginning and end are cropped to produce the returned string.

Centre is a synonym for the Center function.

Syntax

%outString = string:Center( length, [Pad= c], [OffsetLeft= boolean])

%outString = string:Centre( length, [Pad= c], [OffsetLeft= boolean])

Syntax terms

%outString A string variable to receive the result of the Center / Centre method.
string The string to which the method is applied.
length The number of characters desired in the output %string. If this value is greater than the length of the method object string, the method object string is padded on both the right and left to the requested length. If the method object is shorter than length, it is cropped on both the left and right.
Pad This is an optional, name required, parameter that defines the character used to pad string on the right and left (if the length value is greater than the length of string). If an uneven number of pad characters is required, the location of the extra pad character is determined by the value of the OffsetLeft parameter. The default for c is a blank character (' '). Specifying an explicit null ('') results in no padding.
OffsetLeft An optional, name-required, argument that is a Boolean enumeration value indicating where to put the extra character if the requested padding or cropping is asymmetric. If the required number of pad characters or characters to be cropped is not even, the default (False) is to produce an extra character on the right.

Usage notes

  • The length value must be a non-negative number; a negative number results in request cancellation. For a length greater than 255, the output variable must be defined as a longstring. A length value greater than the declared length of the output string results in a request cancellation.
  • The Pad parameter value must be either null or a single character. A longer value results in a compilation error.
  • Center / Centre is available as of Sirius Mods version 7.3.

Examples

The following request prints

++++Hello, World!+++, then

ello, Worl

.

begin %x is string len 15 %out is string len 20 %len is float %x = 'Hello, World!' %len = 20 %out = %x:center(%len, Pad='+', OffsetLeft=True) printText {%out} %len = 10 %out = %x:center(%len, Pad='+', OffsetLeft=True) printText {%out} end

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Center_and_Centre_(String_functions)&oldid=66795"