Re: Numeric literals, take 1

On Thu, Nov 14, 2002 at 07:58:55PM +0100, Angel Faus wrote:
> Hi all,

Hi Angel,


> This is the numeric literals part, reformated to follow Michael's 
> outline.

My contribution is some copyediting and a few suggestions.  Take what
you think is worthwhile.
 


> -----------------------------------------
> =section * Numeric Literals
> 
> =section ** Integer and Decimal literals
> 
> There are many ways to specify literal numeric values in
> perl, but they default to base 10 for input and output.

s/perl/Perl/

(Aren't we still using the capitalization to distinguish between the
interpreter and the language?)



> Perl allows you to use the standard scientific notation

s/the//


> It works just like the standard scientific notation:

Delete this phrase; you've already said that this IS standard SN.


> the left portion of the C<e> is the coefficient, and the

s/the/The/

> right is the exponent, so a number of the form C<C.CCCeEE>
> is actually intepreted as C<C.CCC * 10**EE>.

I would suggest using XX for the exponent, so as to have less
confusion with the 'e'-as-exponent-marker.  Also, add a sentence
stating that the exponent marker may be in either case.  Then you get:

"...right is the exponent, so a number of the form C<C.CCCeXX> is
actually intepreted as C<C.CCC * 10**XX>.  You may use either upper-
or lowercase 'e' as the exponent marker, so, for example, 3.6e3 is the
same as 3.6E3."


> For example, the literal C<7.828e6> is interpreted as
> C<7823000>.

7828000, as was already pointed out


> You can use negative numbers in the exponent side, allowing
> you to write very small numbers.

"You may write very small numbers by using negative exponents."


> =section ** Radix Notation
> 
> For integer numbers, you can represent the literal value
> in any other base, using the C<radix:dddddddd> syntax.

s/other//



> a need to represent digits that are greater than 9.
> 
> You can do this in two ways:

Make the above be one paragraph; you haven't started a new thought
yet.
 


> Alphabetic characters: Following the standard convention,
> perl will interpret the A letter as the digit 10, the B
> letter as digit 11, and so on.

s/perl/Perl/

"...will interpret the letter A...the letter B as the digit...."
                                                  ^^^


> Separating by dots: You can also write each digit in its
> decimal representation, and separate digits using the C<.>
> character.

Although "separating by dots" is perfectly correct and fluid, I would
suggest using the term "dotted notation," just so people start getting
used to it.


>  my $m = 256:255.255.255.0;        # 256-base

"# base 256"


> For example, the integer 30 can be written in hexadecimal
> base in two equivalent ways:

Either say:
	"...in hexadecimal..." or
	"...in base 16...",
but don't mix them.



> Also note that a compile-time error will be generated
> if you specify a "digit" that is larger than your radix
> can support.  For instance,
> 
>  my $x = 3:23; # error

Very small nit:  the problem here is the digit 3, but on first glance
it looks like you are saying that the digit in question is 23.  Extend
the comment to explain:

  "my $x = 3:23; # error; can't use digit '3' in base 3"



> Beware that when writing negative integers, the negative
> character C<-> should be at the leftest point of the
> expression:

"When writing negative integers, be aware that the minus sign (C<->)
must always be the leftmost character in the literal, which means it
will come to the left of the radix when using radix notation."



>  my $z = -256:234.254;                  # negative number
>  my $e = 256:-234.254;                  # error
> 
> Keep in mind that once the number has been read by perl

Perl

> it becomes just a magnitude. That is it loses all trace of

s/That is it/That is, it/

> the way it was originally represented and is just a number. 
> Perl will use decimal base when printing all the numbers, no 
> matter what base did you use to type them.

Either say "base 10" or "decimal notation", not "decimal base".

I would suggest:

"Perl always uses decimal for printing numbers, regardless of what
base you used to enter them."


> =section ** Underscore character as a seprator
> 
> Perl allows the underscore character, C<_>, to be placed as

s/placed/used/

> a separator between the digits of any literal number. You
> can use this to break up long numbers into more readable
> forms.

"...to break up a long number into a more readable form."


> There aren't any rules to it; you can use it however
> you like:

"The only rule is that you may only use underscore between digits, not
between any other characters that is allowed to appear in a number."


>  123_456_000.000   (floating point)
>  2:0110_1000       (binary) 
>  16:FF_88_EE       (hexidecimal) 
>  1312512.25        (decimal number) 
>  1_312_512.25      (the same)
   1_312_512_.25     (error)
   1_312_512._25     (error)
   1.375_e56         (error)
   1.375e_56         (error)
>  _2_3_4____5___6   (error)

   
[delete intermediate comment, collapse examples together, add new
error examples]


> The C<1i> and C<-1i> numbers can be also written
> respectively, C<i> and C<-i>, so the previous example

"...C<i> and C<-i>, respectively, so the previous example..."



> In operations between C<NaN> and other numbers, the result
> is always C<NaN> again.

s/again//


> Moreover, C<NaN> is special in that it is never numerically
> equal to any number, so even the expression C<NaN == NaN>
> is false.
> 
> NOTE: what about C<NaN != NaN>, is it true or false?

It BETTER be true, or my head will explode! 


> For the C<Inf> values, perl will operate them following

Perl

> the standard conventions. For example:

"Standard"?  Standard for whom?  Mathematicians?  Other programming
languages?  (This is an honest question, I'm really don't know.)


> Here C<$P> and C<$N> represent respectively any positive
> and negative values, and C<$X> represents any finite number
> without restrictions (including complex numbers).

Put the above paragraph before the table, and:

"In the following table, C<$P> and C<$N> represent, respectively, any
positive or negative value, while C<$X> represents any finite number
whatsoever (including complex numbers)."  



> This can produce undesired effects when working with
> customs types of numbers, such as BigInt (arbitrary size
> integers) and BigRats (Decimal numbers with a precision
> level greater than the one of native types).

s/customs/certain/
s/Decimal/decimal/
s/the one of native types/any of the native types/

 
> C<7.77666555444333e+20>. When this is number is stored as

s/this is number/this number/

> a BigInt number it has alreadly lost the last digits.

s/number//
s/last/final/

 
> If you need to create BigInt numbers without risking to

s/risking to/risk of/

> lose precision, you should write them as a string literals:

s/lose/losing/
s/as a string/as string/

 
> In that case the conversion to a number type happens

s/number/numeric/



Angel, I hope it doesn't seem like I spilled too much red ink on
you...I really think you did a fabulous job!  


--Dks