func strwrite

Syntax

   strwrite (valuelist)

Formal Declaration

   strwrite:str (valuelist:str)

Parameters

valuelist

A list of expressions, in the form of a single string, to be formatted. The expressions can be separated by blanks or commas:

   value1, value2 value3 ...

An optional format specification can be appended to each expression, introduced with a required colon, in order to select one of the following: a specific output base, left or right justification, blank or zero fill, and a field width for the value.

   value1[:fmtspec1] value2[:fmtspec2] ...

A format specification string is a list of selected format directives, with each directive separated by blanks, commas or nothing at all:

   "directive1 directive2, directive3directive4 ..."

The following table lists the supported format directives that can be entered in upper- or lower-case:

+

Current output base ($, #, or % prefix displayed)

-

Current output base (no prefix)

+<

Current input base ($, #, or % prefix displayed)

-<

Current input base (no prefix)

$

Hex output base ($ prefix displayed)

#

Decimal output base (# prefix displayed)

%

Octal output base (% prefix displayed)

H

Hex output base (no prefix)

D

Decimal output base (no prefix)

O

Octal output base (no prefix)

A

ASCII base (use "." for non-printable chars)

N

ASCII base (loads actual non-printable chars)

L

Left justified

R

Right justified

B

Blank filled

Z

Zero filled

M

Minimum field width, based on value

F

Fixed field width, based on the type of value

Wn

User specified field width n

T

Typed (display the type of the value)

U

Untyped (do not display the type of the value)

QS

Quote single (surround w/ single quotes)

QD

Quote double (surround w/ double quotes)

QO

Quote original (surround w/ original quote character)

QN

Quote none (no quotes)

The M directive (minimum field width) selects the minimum possible field width necessary to format all significant digits (or characters in the case of string inputs).

The F directive (fixed field width) selects a fixed field width based on type of the value and the selected output base. Fixed field widths are listed in the following table:

Types	hex($,H)	dec(#,D)	oct(%,O)	ascii(A,N)
S16,U16	4	6	6	2
S32,U32	8	10	11	4
S64	16	20	22	8
SPTR	8	10	11	4
LPTR Class	8.8	10.10	11.11	8
EADDR Class	8.16	10.20	11.22	12
STR	field width = length of the string

The Wn directive (variable field width) allows the user to specify the desired field width. The W directive can be specified with an arbitrary expression. If the specified width is less than the minimum necessary width to display the value, then the user width is ignored, and the minimum width used instead. All significant digits are always printed. For example:

• number:"w6"

• or

• number:"w2*3"

The number of positions specified (either by Wn or F) does not include the characters required for the radix indicator (if specified) or sign (if negative). Also, the sign and radix indicator will always be positioned just preceding the first (leftmost) character.

Zero versus blank fill applies to leading spaces (for right justification) Trailing spaces are always blank filled.

In specifications with quotes, the quotes do not count in the number of positions specified. The string is built such that it appears inside the quotes as it would without the quotes.

The T directive (typed) displays the type of the value, preceding the value.

The U directive (untyped) suppresses the display of the type. Types are displayed in upper case, with a single trailing blank. The width of the type display string varies, based on the type, and it is independent of any specified width (M, F, or Wn) for the value display.

For values of type LPTR (long pointer, sid.offset, or seg.offset) and EADDR (extended address, sid.offset or ldev.offset), two separate format directives can be specified. Each is separated by a dot, ".", to indicate individual formatting choices for the "sid" portion and the "offset" portion. This is true for all code pointers (ACPTR - absolute code pointers: CST, CSTX; LCPTR - Logical Code Pointers: PROG, GRP, PUB, LGRP, LPUB, SYS, User, TRANS). For example:

   pc:"+.-, w4.8, r.l, b.z"

The following default values are used for omitted format directives. Note that the default format directives depend on the type of value to be formatted:

   value type                 default format
   ----------                 --------------
   STR, BOOL                  - R B M U
   U16,S16,U32,S32,S64        + R B M U
   SPTR                       + R Z F U
   LPTR                       +.-  R.L  B.Z  M.F  U
    ACPTR    LCPTR            +.-  R.L  B.Z  M.F  T
     CST      PROG            +.-  R.L  B.Z  M.F  T
     CSTX     GRP             +.-  R.L  B.Z  M.F  T
              PUB             +.-  R.L  B.Z  M.F  T
              LGRP            +.-  R.L  B.Z  M.F  T
              LPUB            +.-  R.L  B.Z  M.F  T
              SYS             +.-  R.L  B.Z  M.F  T
              USER            +.-  R.L  B.Z  M.F  T
              TRANS           +.-  R.L  B.Z  M.F  T
   EADDR                      +.-  R.L  B.Z  M.F  U
    SADDR                     +.-  R.L  B.Z  M.F  T

Note that absolute code pointers, logical code pointers and secondary addresses display their types (T) by default. All other types default to (U) untyped.

The Cn (Column n) directive moves the current output buffer position to the specified column position prior to the next write into the output buffer. Column numbers start at column 1. For example:

   number:"c6"

NOTE: The Cn directive is ignored by the ASC function but is honored by the W, WL and WP commands.

Examples

   $nmdat > var save = strwrite('1 2 3 "-->" 4:"z w4 r z"  5')
   $nmdat > wl save
   $1$2$3-->0004$5

   wl ASC(1+2, "w4")

   var title = strwrite('"Current Pin:"  pin:"w4", " PC:",  pc')

Limitations, Restrictions