New (CharacterMap constructor): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
{{Template:CharacterMap:New subtitle}}
{{Template:CharacterMap:New subtitle}}
<p>
</p>


The <var>New</var> method creates a character map, which associates individual
The <var>New</var> method creates a character map, which associates individual
characters from an In string (the "input table") with the characters
characters from an <var>In</var> string (the "input table") with the characters
in the corresponding position in the "output table".
in the corresponding position in the "output table".
The output table consists of the characters in the Out string (plus copies of
The output table consists of the characters in the <var>Out</var> string (plus copies of
the Pad character, if necessary).
the <var>Pad</var> character, if necessary).
 
==Syntax==
==Syntax==
{{Template:CharacterMap:New syntax}}
{{Template:CharacterMap:New syntax}}
Line 15: Line 14:
<tr><th>%characterMap</th>
<tr><th>%characterMap</th>
<td>A <var>CharacterMap</var> object variable.</td></tr>
<td>A <var>CharacterMap</var> object variable.</td></tr>
<tr><th><var>[%(CharacterMap):]</var></th>
<tr><th><var>[%(CharacterMap):]</var></th>
<td>The optional class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a <var>CharacterMap</var> <var>Constructor</var>.</td></tr>
<td>The optional class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a <var>CharacterMap</var> <var>Constructor</var>.</td></tr>
<tr><th><var>In</var></th>
<tr><th><var>In</var></th>
<td>A required, name required, argument that specifies the "input table" characters in the mapping.
<td>A required, [[Notation conventions for methods#Named parameters|name required]], argument that specifies the "input table" characters in the mapping.
No character duplications are allowed in the In string, which may not be more than 256 characters.</td></tr>
No character duplications are allowed in the In string, which may not be more than 256 characters.</td></tr>
<tr><th><var>Out</var></th>
<tr><th><var>Out</var></th>
<td>An optional, name required, argument that specifies the "output table" characters.
<td>An optional, name required, argument that specifies the "output table" characters.
<var>Out</var> may not be longer than <var>In</var>; it may be shorter, however, as long as a pad character is specified. <var>Out</var> may not be more than 256 characters.</td></tr>
<var>Out</var> may not be longer than <var>In</var>; it may be shorter, however, as long as a pad character is specified. <var>Out</var> may not be more than 256 characters.</td></tr>
<tr><th><var>Pad</var></th>
<tr><th><var>Pad</var></th>
<td>An optional, name required, argument that specifies the character used to pad the output table string on the right if it is shorter than <var>In</var>.
<td>An optional, name required, argument that specifies the character used to pad the output table string on the right if it is shorter than <var>In</var>.
Line 37: Line 40:
%charMap = %charMap:new(in='A', out='-')
%charMap = %charMap:new(in='A', out='-')
</p>
</p>
<li>Case is respected in all character specifications.
<li>Case is respected in all character specifications.
<li>If the In string is longer than the Out string, the "extra" In
 
characters are associated with the Pad character.
<li>If the <var>In</var> string is longer than the <var>Out</var> string, the "extra" <var>In</var>
In this case, it is a request-canceling error if no Pad character is present.
characters are associated with the <var>Pad</var> character.
<li>The Out argument can be omitted, as long as a Pad argument is present.
In this case, it is a request-canceling error if no <var>Pad</var> character is present.
The Pad argument has no default.
 
<li>For an example of a <var>New</var> method call, see the [[CharacterMap class#Example|CharacterMap class]] page.
<li>The <var>Out</var> argument can be omitted, as long as a <var>Pad</var> argument is present.
The <var>Pad</var> argument has no default.
 
</ul>
</ul>
==Example==
{{Template:CharacterMap example}}


==See also==
==See also==
{{Template:CharacterMap:New footer}}
{{Template:CharacterMap:New footer}}

Latest revision as of 16:16, 10 October 2016

Create CharacterMap object (CharacterMap class)


The New method creates a character map, which associates individual characters from an In string (the "input table") with the characters in the corresponding position in the "output table". The output table consists of the characters in the Out string (plus copies of the Pad character, if necessary).

Syntax

%characterMap = [%(CharacterMap):]New( In= string, [Out= string], [Pad= c])

Syntax terms

%characterMap A CharacterMap object variable.
[%(CharacterMap):] The optional class name in parentheses denotes a Constructor. See "Usage notes", below, for more information about invoking a CharacterMap Constructor.
In A required, name required, argument that specifies the "input table" characters in the mapping. No character duplications are allowed in the In string, which may not be more than 256 characters.
Out An optional, name required, argument that specifies the "output table" characters. Out may not be longer than In; it may be shorter, however, as long as a pad character is specified. Out may not be more than 256 characters.
Pad An optional, name required, argument that specifies the character used to pad the output table string on the right if it is shorter than In.

Pad must be a single character, only.

Usage notes

  • As described in "Using New or other Constructors", New can be invoked with no object, with an explicit class name, or with an object variable in the class, even if that object is Null:

    %charMap = new(in='A', out='-') %charMap = %(CharacterMap):new(in='A', out='-') %charMap = %charMap:new(in='A', out='-')

  • Case is respected in all character specifications.
  • If the In string is longer than the Out string, the "extra" In characters are associated with the Pad character. In this case, it is a request-canceling error if no Pad character is present.
  • The Out argument can be omitted, as long as a Pad argument is present. The Pad argument has no default.

Example

Most of the CharacterMap methods are shown in the following example, which also features the intrinsic String function, Translate. In the example, a new CharacterMap is the argument for the Translate method; then that map is copied and modified, and the modified map is used in a second Translate call:

begin %map is object characterMap %map2 is object characterMap %ls is longstring %map = New(in='x-', out='!c') %ls = 'xu--exx' printtext {~} = '{%ls:translate(%map)}' %map2 = %map:Copy %map2:Update(in='x',out='s') printtext {~} = '{%ls:translate(%map2)}' end

The result is:

%ls:translate(%map) = '!ucce!!' %ls:translate(%map2) = 'success'

See also