manual:chapter3:numformatting

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
manual:chapter3:numformatting [2017/08/13 12:21]
claudio [The Format String]
manual:chapter3:numformatting [2021/10/05 15:29] (current)
jojo1973 [Format localization]
Line 1: Line 1:
-==== Displaying and Formatting Numbers ====+===== Displaying and formatting numbers =====
 A number can be displayed on the screen in different ways, regardless of the internal precision or representation of the number. A number can be displayed on the screen in different ways, regardless of the internal precision or representation of the number.
-The following are examples of the possible appearance of numbers in newRPL: \\+The following are examples of the possible appearance of numbers in **newRPL**: \\
  
-''123456789.123456789'' (this is the default presentation) \\ +''123456789.123456789''  | This is the default presentation  | 
-''123,456,789.123 456 789'' (using thousand separators and also grouping the fractional digits) \\ +''123,456,789.123 456 789''  | Using thousands separators and also grouping the fractional digits  | 
-''1.23456789123456789E8'' (scientific notation) \\+''1.23456789123456789E8''  | Using scientific notation  |
  
-Up to 3 different ways to present numbers are used by the system, and they are active at all times. One format is for small numbers (whose absolute magnitude does not exceed a certain limit), another format for large numbers (whose absolute magnitude exceed a certain limit), and a third format for all other numbers in between. The default configuration presents numbers less than ''1E-12'' in scientific notation, numbers larger than ''1E12'' in scientific notation, and all others in standard notation. The cutoff limits for small and large numbers can be freely configured, as well as the formatting for each of the three ranges of numbers.+Up to 3 different ways to present numbers are used by the system, and they are active at all times. One format is for __small numbers__ (whose absolute magnitude does not exceed a certain limit), another format for __large numbers__ (whose absolute magnitude exceed a certain limit), and a third format for all other numbers in between (a.k.a. __normal numbers__ in this discussion).
  
-The primary way to change the number formatting is the ''SETNFMT'' command. This command accepts a single string or real numberor a list as arguments. Passing a single string changes all 3 formats to the desired format given by the string (the particular format of the string will be explained in short). The list allows fine grain control of what format to change as follows: \\ +The default configuration presents numbers less than ''1E-12'' in scientific notationnumbers greater than ''1E+12'' in scientific notation, and all others in standard notation. The cutoff limits for small and large numbers can be freely configuredas well as the formatting for each of the three ranges of numbers.
-''1E100 SETNFMT'' or ''1E-10 SETNFMT'': Passing a single positive real number will change the cutoff limits without altering the format itself. If the number is larger than one, the limit for large numbers will be changed. Likewiseif the number is less than one the limit for small numbers will be changed.\\+
  
-''"#.##" SETNFMT'': Passing a single string will change the format for all 3 number ranges to the desired format.\\+The primary way to change the number formatting is the ''[[manual:chapter6:flags:cmd_setnfmt|SETNFMT]]'' command. This command accepts a single string or real number, or a list as arguments:
  
-''{ 1E100 "#.##" } SETNFMT'': A list will change formats for each number range individually. Passing a number and a format string will change the cutoff limit and corresponding format for large or small numbers (depending on the given limit being >1  +  * passing a single string changes all 3 formats to the desired format given by the string (the particular format of the string will be explained below); 
-or <1). \\+  * passing a single positive real number will change the cutoff limits without altering the format itself. If the number is greater than ''1'', the limit for large numbers will be changedLikewise, if the number is less than ''1'' the limit for small numbers will be changed; 
 +  * a list will change formats for each number range individually. Passing a number and a format string will change the cutoff limit and corresponding format for large or small numbers (depending on the given limit being greater or less than ''1'')
 +  * if the list contains one or more strings without specifying any cutoff limits, the format will be changed in the following order: the first string on the list will change the format for normal numbers, the second one will change small numbers and the third one large numbers. 
 +  * If the list contains a cutoff limit followed by format string, the number will change the cutoff limit according to its magnitude, then the string immediately following the number will change the format corresponding to that limit.\\ \\ If a string after has no limit specified, it will follow the order __normal → small numbers → large numbers__. 
 +   
 +Here are some examples: 
 +^ ''[[manual:chapter6:flags:cmd_setnfmt|SETNFMT]]'' argument  ^ Effect 
 +| ''"#.##"''  | **Small numbers format:** ''#.##''\\ **Small numbers cutoff:** unchanged\\ **Normal numbers format:** ''#.##''\\ **Large numbers cutoff:** unchanged\\ **Large numbers format:** ''#.##'' 
 +| ''1E-10''  | **Small numbers format:** unchanged\\ **Small numbers cutoff:** ''1E-10''\\ **Normal numbers format:** unchanged\\ **Large numbers cutoff:** unchanged\\ **Large numbers format:** unchanged 
 +| ''{ 1E+15 "#.#0E" }''  | **Small numbers format:** unchanged\\ **Small numbers cutoff:** unchanged\\ **Normal numbers format:** unchanged\\ **Large numbers cutoff:** ''1E+15''\\ **Large numbers format:** ''#.#0E'' 
 +| '' "#.###" "#.###0E" "#.#0E"}''  | **Small numbers format:** ''#.###0E''\\ **Small numbers cutoff:** unchanged\\ **Normal numbers format:** ''#.###''\\ **Large numbers cutoff:** unchanged\\ **Large numbers format:** ''#.#0E'' 
 +| ''{ 1E-10 "#.##E#" "#.##" }''  | **Small numbers format:** ''#.##E#''\\ **Small numbers cutoff:** ''1E-10''\\ **Normal numbers format:** unchanged\\ **Large numbers cutoff:** unchanged\\ **Large numbers format:** ''#.##''  |
  
-''1E-10 "#.##E#" "#.##" } SETNFMT'': If the list contains a string without specifying any cutoff limits, the format will be changed in the following order: the first string on the list will change the format for normal numbers, the second one will change small numbers and the third one large numbers. If a format string has a number preceding it, the number will change the cutoff limit, then the string immediately following the number will change the format corresponding to that limit. If a string after has no limit specified, it will follow the order as described. In this example, the list has the number''1E-10'' therefore it will set the limit for small numbers (since 1E-10 < 1) to the format "#.##E#". The following string will change the large numbers, since it doesn't have a limit but will follow the sequence "normal → small number → large number". If there was a string afterwards, it would change the normal numbers. To avoid any ambiguity, it is a good practice to specify the list with the formats in that order, whether they include the cutoff limits or not.+Regarding the last example, the first element is ''1E-10'' therefore the string immediately following will set the format for small numbers (since ''1E-10''''1'') to ''#.##E#''. The following string will change the large numbers, since no limit is specified and therefore the sequence __normal → small numbers → large numbers__ is followed. If there were third string afterwards, it would have changed the normal numbers. To avoid any ambiguity, it is a good practice to specify the list with the formats in that order, whether they include the cutoff limits or not
 + 
 +The default format is: 
 +<code> 
 +
 +  "#.12#."          @ Normal 
 +  1E-12 "#.12#.E*"  @ Small numbers (< 1E-12) 
 +  1E12 "#.12#.E*"   @ Large numbers (> 1E+12) 
 +
 +</code> 
 + 
 +Current format list can be retrieved using the ''[[manual:chapter6:flags:cmd_getnfmt|GETNFMT]]'' command.
  
 ---- ----
  
-==== The Format String ==== +==== The format string ==== 
-The format string uses the numeral (#) to represent digitsThe simplest format string is ''"#"''. The numeral in this case represents the integer part of the number, and its presence on the format string is mandatoryOne symbol represents the entire integer part of the number, as many digits as needed. +The format string defines how a number is displayed; in its basic form is very simple, but the syntax allows for great flexibility and its appearance can become a bit cryptic... at a first glance the structure of the string is
 +|  ''integer_part[fractional_part][approximation_dot][exponent_part]''  | 
 +Anything enclosed in ''[ ]'' is optional, the brackets ''< >'' and the vertical bar ''|'' separate mutually exclusive choices and the ellipsis ''...'' means repetition of a character. Now we can proceed examining each part separately. 
 + 
 +---- 
 + 
 +=== The INTEGER part === 
 +The //integer part// of the format string has the following format: 
 +|  ''[+][S[n]]#'' 
 +The simplest format string is just the hash sign ''"#"''In fact that's the only mandatory part: a single ''#'' represents the entire integer part of the number, as many digits as needed. 
  
 Other options to format the integer part of the number are as follows: Other options to format the integer part of the number are as follows:
  
-''"+#"'': A preceding ''+'' symbol will force the display of the sign even for positive numbers. The negative sign will always be displayed.+  * a plus sign ''+'' preceding the hash sign will force the display of the sign even for positive numbers. The negative sign will always be displayed
 +  * the uppercase ''S'' preceding the hash sign indicates the presence of a separator. By default the separator is spaced every 3 digits, but that can be controlled by including the number of digits in each group immediately following the ''S''; for example ''"S4#"'' will add the thousand separator every 4 digits. Valid values for ''S'' are ''1'' through ''15'', and the separator character used will be as defined by the command ''[[manual:chapter6:flags:cmd_setlocale|SETLOCALE]]''.
  
-''"S#"'': The uppercase ''S'' preceding the numeral indicates the presence of a separator. By default the separator is spaced every 3 digits, but that can be controlled by including the number of digits in each group immediately following the ''S'', for example ''"+S4#"'' will force the sign and add the thousand separator every 4 digitsValid values for S are 1 through 15, and the separator character used will be as defined by the command ''SETLOCALE''.+^ Format  ^ Number  ^ Displayed as  ^ 
 +''#''  | 123.456 ''123''  | 
 +''+#''  | 123.456 ''+123'' 
 +| ''S4#''  | 123456.789  | ''12 3457''  | 
 +| ''S3#''  | 123456.789  | ''123 457''  |
  
-''"#."'': A single trailing dot will display the trailing dot for approximate numbers, while no dot will be shown for exact numbers.+----
  
-To display the fraction part of the number, the string needs to include a decimal dot and at least one # symbol (NOTE: The format string must use a decimal dot, even if the decimal separator set in the Locale is a different character, but the correct character from Locale will be used when displaying numbers). The number of digits desired can be expressed in two different waysby the number of # symbols, or by including the actual number of digits preceding the #, for example ''"#.####"'' or ''"#.4#"'' will both display numbers with up to 4 decimal figures.+=== The FRACTIONAL part === 
 +The //fractional part// of the format string has the following format: 
 +|  ''.<#...|d#|A#>[0][S[n]]'' 
 + 
 +To display the fraction part of the number, the string needs to include a decimal dot and at least one ''#'' symbol
 + 
 +**NOTE**: The format string must use a decimal dot (a.k.a. //radix point//), even if the decimal separator defined by the ''[[manual:chapter6:flags:cmd_setlocale|SETLOCALE]]'' is a different character. 
 + 
 +The number of digits desired can be expressed in three different ways
 +  * by the number of ''#'' symbols
 +  * by including the actual number of digits preceding the ''#''
 +  * by using ''A#''The ''A'' here is replacing the number of decimal figures and means //all digits//, and will output as many digits as the number has stored. This is useful to store numbers as text or to edit a number, since it allows to recover the same number from the generated text.
  
 Various other options are available to format the fractional part of the number: Various other options are available to format the fractional part of the number:
  
-''"#.###0"'': Replacing the last # with a zero will append trailing zeros as needed to display the requested number of decimal figures. The zero counts as one additional digit, in this example total of 4 figures will be displayed.+  * when the number of decimal digits is expressed by a repetition of ''#'''s, replacing the last ''#'' with a ''0'' will append as many trailing zeros as needed to display the requested number of decimal figures. The ''0'' character counts as one additional digit
 +  * when the number of decimal digits is expressed by a number //d// followed by a ''#''a trailing ''0'' still indicates that trailing zeros need to be added **but** in this case the presence of ''0'' does not add another digit. 
 +  * the uppercase ''S'' following the last ''#'' or ''0'' indicates the presence of separator. By default the separator is spaced every 3 digits, but that can be controlled by including the number of digits in each group immediately following the ''S''; for example ''"S4"'' will add the fractional separator every digits. Valid values for ''S'' are ''1'' through ''15'', and the separator character used will be as defined by the command ''[[manual:chapter6:flags:cmd_setlocale|SETLOCALE]]''.\\ **NOTE**: the number of digits in a group must match between the integer and fractional part of the number, it's an invalid format string to request separators every //n// digits on the integer part, and //m// digits on the fractional part when //m≠n//.
  
-''"#.4#0"'': Same as above, after the number of digits, a zero indicates that trailing zeros need to be addedWhen the number of digits is explicitly given the presence of the zero does not add another digit, in this example a total of will be displayed.+^ Format  ^ Number  ^ Displayed as  ^ 
 +| ''#.####''  | 123.45678  | ''123.4568'' 
 +''#.4#''  | 123.45678  | ''123.4568'' 
 +| ''#.A#''  | 123.45678  | ''123.45678'' 
 +| ''#.###0''  | 123.45  | ''123.4500'' 
 +| ''#.4#0''  | 123.45  | ''123.4500'' 
 +| ''#.8#0S4''  | 123.45  | ''123.4500 0000''  |
  
-''"#.A#"'': The ''A'' here is replacing the number of decimal figures and means all digits, and will output as many digits as the number has stored. This is useful to store numbers as text or to edit a number, since it allows to recover the same number from the generated text.+----
  
-''"#.###0S2"'': The ''S'' after the number of digits indicates the fractional digit separator needs to be included, in this case with an optional spacing of 2 digits. When a number of digits is not included, the default is 3 digits (NOTE: the number of digits in a group must match between the integer and fractional part of the number, it's an invalid format string to request separators every 'n' digits on the integer part, and 'mdigits on the fractional part when m≠n)Valid values for S are 1 through 15, and the separator character used will be as defined by the command ''SETLOCALE''.+=== The APPROXIMATION dot === 
 +The //approximation dot part// of the format string has the following format: 
 +|  ''[.]''  |
  
-''"#.###0."'': The trailing dot will display the dot on approximate numbers.+In **newRPL** the real numbers can be represented as [[manual:chapter3:reals#approximate-versus-exact|exact]] or [[manual:chapter3:reals#approximate-versus-exact|approximate]], the latter property indicated by a trailing dot ''.'' following the fractional (or just the integer, if missing) part of the number.
  
-''"#.#0E"'': number will be displayed in scientific notation when the exponent letter ''e'' or ''E'' is included in the format string after the fractional part. In this example, 2 decimal figures will be shown (adding trailing zeros as needed) in scientific notation, using capital ''E'' to separate the exponent from the mantissa.+It is possible to turn on or off the display of the approximation dot adding a single dot ''.'' character just after the integer and fractional part of the format. 
 + 
 +**NOTE**: the approximation dot is always displayed as a dot: the command ''[[manual:chapter6:flags:cmd_setlocale|SETLOCALE]]'' can change the appearance of the decimal separator only. 
 + 
 +^ Format  ^ Number  ^ Displayed as  ^ 
 +''#.####''  | 123.45678.  | ''123.4568'' 
 +| ''#.####.''  | 123.45678.  | ''123.4568.'' 
 + 
 +---- 
 + 
 +=== The EXPONENT part === 
 +The //exponent part// of the format string has the following format: 
 +|  ''<E|e>[*][+][<n|#>]'' 
 + 
 +To display a number in __scientific__ or __engineering__ notation (with an optional preferred exponent) the exponent letter ''E'' or ''e'' is included in the format string after the fractional part. The difference between the two notations is the following: 
 +  * in __scientific__ notation the integer part is a single digit number from ''0'' to ''9''; 
 +  * in __engineering__ notation the integer part is a number from ''0'' to ''999''; 
 +  * in __engineering__ notation with a preferred exponent the integer part is chosen such as the exponent is as specified. 
 + 
 +Various other options are available to format the exponent part of the number: 
 + 
 +  * an asterisk ''*'' following the exponent letter will suppress the exponent in scientific notation when the exponent is ''0''; 
 +  * plus sign ''+'' after the exponent letter will force the exponent sign for positive exponents. Negative exponents are always displayed with the sign; 
 +  * when the hash symbol ''#'' is present after the exponent letter, it activates engineering notation. The displayed number will have an exponent multiple of 3, chosen by the system to ensure the integer part of the mantissa is between ''1'' and ''999''; 
 +  * when a number is present after the exponent letter, it activates engineering notation and indicates a preferred exponentAll numbers will display using the requested exponent. The preferred exponent can be in the range ''-21'' to ''+21'', and has to be a __multiple of 3__.\\ **NOTE**: When using engineering notation with a preferred exponent, the asterisk will **always** suppress the exponent and not only when it's ''0''
 + 
 +^ Format  ^ Number  ^ Displayed as  ^ 
 +| ''#.##.E''  | 0.01234.  | ''1.23.E-2'' 
 +| ''#.##.e''  | 0.01234.  | ''1.23.e-2'' 
 +| ''#.##.E''  | 3.5  | ''3.5E0'' 
 +| ''#.##.E+''  | 3.5  | ''3.5E+0'' 
 +| ''#.##.E*''  | 3.5  | ''3.5'' 
 +| ''#.##.E+#''  | 35150  | ''35.15E+3'' 
 +| ''#.##.E+3''  | 35  | ''0.04E+3'' 
 +| ''#.##.E*+3''  | 35  | ''0.04'' 
 + 
 +----
  
-''"#.#0E*"'': An asterisk following the exponent letter will suppress the exponent in scientific mode when the exponent is zero. For example the number ''1.5'' will display as ''1.50E0'' unless the asterisk is present in the format string to suppress it. and show only ''1.50''.+==== Format localization ==== 
 +The ''[[manual:chapter6:flags:cmd_setnfmt|SETNFMT]]'' command allows great customization with respect to the grouping of digits in the integer and fractional parts of the number; the command ''[[manual:chapter6:flags:cmd_setlocale|SETLOCALE]]'' allows customization of the characters that delimit these groupings.
  
-''"#.#0E*+"'': A plus sign after the exponent letter will force the exponent sign for positive exponents (negative exponents are always displayed with the sign).+''[[manual:chapter6:flags:cmd_setlocale|SETLOCALE]]'' accepts a 4-character string which defines what character must be used for each grouping: the following table shows the default setting.
  
-''"#.#0E*+3"'': When a number is present after the exponent letter, it activates engineering mode, and indicates preferred exponentAll numbers will display using the requested exponent (engineering mode with a fixed exponent). The preferred exponent can be in the range -21 to +21, and has to be a multiple of 3. When using engineering mode with preferred exponent, the asterisk will always suppress the exponent (not only when it's zero).+^ Position  ^ Character  ^ Function  ^ Notes  ^ 
 +| **1**  | ''.''  | Decimal separator  | This is the character used to divide the integer part of a number from the fractional part. This character is **NOT** the same as the [[manual:chapter3:reals#approximate-versus-exact|approximation dot]] which is always displayed as dot | 
 +| **2**  | **U**+2009\\ (thin space | Integer separator  | This is the character used to divide the digits groups in the integer part of a number. 
 +| **3**  | **U**+2009\\ (thin space)  | Fractional separator  | This is the character used to divide the digits groups in the fractional part of a number. 
 +| **4**  | '',''  | Arguments separator  | This is the character used to divide the arguments of a symbolic function (e.g. ''%%'%%GCD(16,32)%%'%%'') or the real and imaginary parts of a complex number (e.g. ''(1,-2)'').  |
  
-''"#.#0E*+#"'': When the preferred exponent is expressed as a numeral symbol, it activates engineering mode without a preferred exponent. The displayed number will have an exponent multiple of 3, chosen by the system to ensure the integer part of the mantissa is between 1 and 999.+The ''[[manual:chapter6:flags:cmd_getlocale|GETLOCALE]]'' command returns on the stack the localization string.
  
 ---- ----
  
 +==== Preset formats ====
 +A different, user friendly way to change the display of numbers is to use the preset formats that are provided by **newRPL**. These presets are quickly accessed via the keyboard and can be combined in many different ways:
  
 +  * **ON<sup>hold</sup>-SP** cycles thru number format presets;
 +  * **ON<sup>hold</sup>-DOT** cycles thru localization presets;
 +  * **ON<sup>hold</sup>-{1...9}** selects the length of the fractional part in scientific or engineering mode;
 +  * **ON<sup>hold</sup>-{MUL/DIV}** switches to engineering mode and selects ''Auto'' (no preferred exponent) or a preferred exponent in the range ''-21'' to ''21'' in steps by 3.
 +\\ \\ 
 +**__Base number format presets__**
 +^ Preset name  ^ Small numbers format  ^ Small numbers cutoff  ^ Normal numbers format  ^ Large numbers cutoff  ^ Large numbers format  ^
 +| **STD**  | ''#.12#.E*''  | ''1E-12''  | ''#.12#.''  | ''1E+12''  | ''#.12#.E*''  |
 +| **FIX**  | ''#.12#.E*''  | ''1E-12''  | ''#.12#0.''  | ''1E+12''  | ''#.12#.E*''  |
 +| **SCI**  | ''#.12#.E*''  | ''1E-12''  | ''#.12#.E''  | ''1E+12''  | ''#.12#.E*''  |
 +| **ENG**  | ''#.12#.E*''  | ''1E-12''  | ''#.12#.E*#''  | ''1E+12''  | ''#.12#.E*''  |
 +\\ \\ 
 +**__Base localization presets__**
 +^ Preset name  ^ Integer grouping  ^ Fractional grouping  ^ Decimal separator  ^ Integer separator  ^ Fractional separator  ^ Arguments separator  ^
 +| ''1000.000000'' | **No** | **No** | ''.'' | **U**+2009\\ (thin space) | **U**+2009\\ (thin space) | '','' |
 +| ''1,000.000000'' | **Yes** | **No** | ''.'' | '','' | **U**+2009\\ (thin space) | '';'' |
 +| ''1 000.000000'' | **Yes** | **No** | ''.'' | **U**+2009\\ (thin space) | **U**+2009\\ (thin space) | '','' |
 +| ''1000.000 000'' | **No** | **Yes** | ''.'' | **U**+2009\\ (thin space) | **U**+2009\\ (thin space) | '','' |
 +| ''1,000.000 000'' | **Yes** | **Yes** | ''.'' | '','' | **U**+2009\\ (thin space) | '';'' |
 +| ''1 000.000 000'' | **Yes** | **Yes** | ''.'' | **U**+2009\\ (thin space) | **U**+2009\\ (thin space) | '','' |
 +| ''1000,000000'' | **No** | **No** | '','' | **U**+2009\\ (thin space) | **U**+2009\\ (thin space) | '';'' |
 +| ''1.000,000000'' | **Yes** | **No** | '','' | ''.'' | **U**+2009\\ (thin space) | '';'' |
 +| ''1 000,000000'' | **Yes** | **No** | '','' | **U**+2009\\ (thin space) | **U**+2009\\ (thin space) | '';'' |
 +| ''1000,000 000'' | **No** | **Yes** | '','' | **U**+2009\\ (thin space) | **U**+2009\\ (thin space) | '';'' |
 +| ''1.000,000 000'' | **Yes** | **Yes** | '','' | ''.'' | **U**+2009\\ (thin space) | '';'' |
 +| ''1 000,000 000'' | **Yes** | **Yes** | '','' | **U**+2009\\ (thin space) | **U**+2009\\ (thin space) | '';'' |
  • manual/chapter3/numformatting.1502652078.txt.gz
  • Last modified: 2017/08/13 12:21
  • by claudio