Masked Decimal Conversion (MD, ML, MR)

Masked Decimal Conversion (MD, ML, MR)

Top  Previous  Next

 

The masked decimal conversion codes convert a number between its internal and external forms. The formats available provide scaling, currency symbol insertion, thousands separation and a variety of methods for handling negative numbers.

 

Scaling provides a means by which items such as currency values which are usually written as pounds and pence (or dollars and cents) can be handled internally as integer numbers of pence (or cents) for faster and precise calculation. Scaling is performed by specifying the position of an assumed decimal point.

 

Input conversion allows for some degree of flexibility in the exact format used. For example, any of the negative value representations may be used regardless of the method actually defined in the conversion code.

 

The three masked decimal conversion codes are

 

MDConvert without regard to justification
MLLeft justify the converted result
MRRight justify the converted result

 

The full format of this conversion code is

 

ML n {f} {,} {$} {s}  {[intl]} {P} {Z} {T} {x{c}} {fx}

 

where

 

nis a digit in the range 0 to 9 specifying the number of digits to appear to the right of the decimal point. Rounding occurs on output conversion in the fractional part and, if the result is an integer, the decimal point does not appear.

 

fis a digit in the range 0 to 9 specifying the position of the implied decimal point in the data to be converted. For example, if the value supplied to an output conversion is 12345 and f is 2, the result is 123.45. Conversely, if the value supplied to an input conversion is 123.45 and f is 2, the result is 12345. If omitted, f defaults to the same value as n.

 

,specifies that the national language convention thousands separator is to be inserted between every third digit to the left of the decimal point. The default delimiter is a comma but this may be changed by use of the NLS command or the SETNLS QMBasic statement.

 

$specifies that the national currency symbol should be used as a prefix to the converted data on output conversion and may be present on input conversion. The default currency symbol is a dollar sign but this may be changed by use of the NLS command or the SETNLS QMBasic statement.

 

sspecifies the handling of the numeric sign of the value.

 

+places a + or - sign to the right of the converted data.

 

-places a - sign to the right of negative values or a space to the right of positive values.

 

(encloses negative values in round brackets. A positive value has a space placed to its right.  This element is not allowed when the PICK.ML.CONV.MASK mode of the OPTION command is in effect.

 

<encloses negative values in angle brackets. A positive value has a space placed to its right.

 

Cplaces the letters cr to the right of negative values or two spaces to the right of positive values. Use the CRDB.UPCASE keyword of the OPTION command to change this to CR.

 

Dplaces the letters db to the right of negative values or two spaces to the right of positive values. Use the CRDB.UPCASE keyword of the OPTION command to change this to DB.

 

Input conversion accepts any of these representations of a negative value regardless of the actual conversion code used.

 

[intl]specifies alternative international handling of currency symbols and separators. intl consists of up to four comma separated items which specify the prefix, thousands separator, decimal separator and suffix to be applied to the converted value. These components should be quoted if there is any potential confusion.

 

Zspecifies that a zero value should be represented by a null string on output conversion. This option is ignored on input conversion.

 

Tspecifies that trailing decimal places should be truncated rather than rounded. This option is ignored on input conversion.

 

x{c}specifies that the result of an output conversion is to be a field of x characters, left or right justified as specified by use of ML or MR. If the converted data is longer than x characters it will be truncated to fit. If it is less than x characters it is padded using character c or spaces if c is not specified. The value of x may be one or two digits.
 
On input conversion, the value of x is ignored and all occurrences of character c, or spaces if c is not specified, within the data are ignored.

 

fxis an alternative style of padding specification. It cannot be used with x{c}.

f specifies the padding character to be used; * for asterisk, # for space, % for zero.

x specifies the field width.

The fx element may be a complete mask as used in format specifications (e.g. #3-#4). For compatibility with Pick style systems, when the PICK.ML.CONV.MASK mode of the OPTION command is in effect, the fx element of ML and MR conversions may be enclosed in round brackets.

 

 

Masked Decimal Output Conversion

 

If the input data is a null string, the ML and MR codes normally treat this as zero and return an appropriately formatted conversion of the number zero. If the PICK.NULL mode of the OPTION command is active, a null string will be returned.

 

The following table sets out a variety of combinations of masked decimal output conversion features.

 

Value

Conversion

Result

0

MD0

'0'

0

MD0Z

''

 

 

 

Sign handling

12345678

MD0

'12345678'

-12345678

MD0

'-12345678'

12345678

MD0+

'12345678+'

-12345678

MD0+

'12345678-'

12345678

MD0-

'12345678 '

-12345678

MD0-

'12345678-'

12345678

MD0<

' 12345678 '

-12345678

MD0<

'<12345678>'

12345678

MD0(

' 12345678 '

-12345678

MD0(

'(12345678)'

12345678

MD0C

'12345678  '

-12345678

MD0C

'12345678CR'

12345678

MD0D

'12345678  '

-12345678

MD0D

'12345678DB'

 

 

 

Scale factors

12345678

MD22

'123456.78'

1234567.89

MD22

'12345.68'

-12345678

MD22

'-123456.78'

12345678

MD02

'123457'

12345678

MD02T

'123456'

 

 

 

Thousands separators and currency symbols

1234567

MD0,

'1,234,567'

12345678

MD2,$

'$123,456.78'

 

 

 

Left justification and padding

0

ML004*

'0***'

12345678

ML0010*

'12345678**'

12345678

ML0+12*

'12345678+***'

-12345678

ML0+12*

'12345678-***'

12345678

ML0-12*

'12345678 ***'

12345678

ML0(12*

'12345678 ***'

-12345678

ML0(12*

'(12345678)**'

12345678

ML0C12*

'12345678  **'

-12345678

ML0C12*

'12345678CR**'

 

 

 

Right justification and padding

0

MR004*

'***0'

12345678

MR0010*

'**12345678'

12345678

MR0+12*

'***12345678+'

-12345678

MR0+12*

'***12345678-'

12345678

MR0-12*

'***12345678 '

12345678

MR0(12*

'***12345678 '

-12345678

MR0(12*

'**(12345678)'

12345678

MR0C12*

'**12345678  '

-12345678

MR0C12*

'**12345678CR'

 

 

Masked Decimal Input Conversion Examples

 

The behaviour of a masked decimal input conversion with invalid data provides close compatibility with other multivalue products but may not be exactly identical as there is some variation. The MD code will return a null string as its result. The ML and MR codes return the converted form of the leading numeric part of the data, ignoring any further characters. If there is no leading numeric part, the original data is returned unconverted. The QMBasic ICONV() function will return a status code of 1 when attempting to convert invalid data with the MD, ML and MR codes.

 

The following table sets out a variety of combinations of masked decimal conversion features.

 

Value

Conversion

Result

''

MD0

''

'0'

MD0

'0'

 

 

 

Sign handling

'12345678'

MD0

'12345678'

'-12345678'

MD0

'-12345678'

'12345678-'

MD0

'-12345678'

'<12345678>'

MD0

'-12345678'

'(12345678)'

MD0

'-12345678'

'12345678CR'

MD0

'-12345678'

'12345678DB'

MD0

'-12345678'

 

 

 

Scale factors

'123456.78'

MD2

'12345678'

'123456.78'

MD23

'1234567.8'

 

 

 

Currency symbols and thousands separators

'12,345'

MD0,

'12345'

'$123,456.78'

MD2,$

'12345678'

'($123456.78)'

MD22$(

'-12345678'