Skip to content

Commit 4ff8039

Browse files
sdwheelerDCtheGeek
sdwheeler
authored and
DCtheGeek
committed
Fix #2695 - add info about numeric literals (#4151)
* Fix #2695 - add info about numeric literals * fix note block * review feedback * review feedback * fix byte types
1 parent 1d87ed4 commit 4ff8039

File tree

5 files changed

+959
-0
lines changed

5 files changed

+959
-0
lines changed

‎reference/3.0/Microsoft.PowerShell.Core/About/about_numeric_literals.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
ms.date: 04/09/2018
3+
schema: 2.0.0
4+
locale: en-us
5+
keywords: powershell,cmdlet
6+
title: About numeric literals
7+
---
8+
# About numeric literals
9+
10+
There are two kinds of numeric literals: integer and real. Both can have type
11+
and multiplier suffixes.
12+
13+
## Integer literals
14+
15+
Integer literals can be written in decimal or hexadecimal notation. Hexadecimal
16+
literals are prefixed with `0x` to distinguish them from decimal numbers.
17+
18+
Integer literals can have a type suffix and a multiplier suffix.
19+
20+
| Suffix | Meaning |
21+
| ------ | ------------------- |
22+
| l | long data type |
23+
| kb | kilobyte multiplier |
24+
| mb | megabyte multiplier |
25+
| gb | gigabyte multiplier |
26+
| tb | terabyte multiplier |
27+
| pb | petabyte multiplier |
28+
29+
The type of an integer literal is determined by its value, the type suffix, and
30+
the numeric multiplier suffix.
31+
32+
For an integer literal with no type suffix:
33+
34+
- If the value can be represented by type `[int]`, that is its type.
35+
- Otherwise, if the value can be represented by type `[long]`, that is its
36+
type.
37+
- Otherwise, if the value can be represented by type `[decimal]`, that is its
38+
type.
39+
- Otherwise, it is represented by type `[double]`.
40+
41+
For an integer literal with a type suffix:
42+
43+
- If the type suffix is `u` and the value can be represented by type `[int]`
44+
then its type is `[int]`.
45+
- If the type suffix is `u` and the value can be represented by type `[long]`
46+
then its type is `[long]`.
47+
- If its value can be represented by type specified then that is its type.
48+
- Otherwise, that literal is malformed.
49+
50+
## Real literals
51+
52+
Real literals can only be written in decimal notation. This notation can
53+
include fractional values following a decimal point and scientific notation
54+
using an exponential part.
55+
56+
The exponential part includes an 'e' followed by an optional sign (+/-) and a
57+
number representing the exponent. For example, the literal value `1e2` equals
58+
the numeric value 100.
59+
60+
Real literals can have a type suffix and a multiplier suffix.
61+
62+
| Suffix | Meaning |
63+
| ------ | ------------------- |
64+
| d | decimal data type |
65+
| kb | kilobyte multiplier |
66+
| mb | megabyte multiplier |
67+
| gb | gigabyte multiplier |
68+
| tb | terabyte multiplier |
69+
| pb | petabyte multiplier |
70+
71+
There are two kinds of real literal: double and decimal. These are indicated by
72+
the absence or presence, respectively, of decimal-type suffix. PowerShell does
73+
not support a literal representation of a `[float]` value. A double real
74+
literal has type `[double]`. A decimal real literal has type `[decimal]`.
75+
Trailing zeros in the fraction part of a decimal real literal are significant.
76+
77+
If the value of exponent-part's digits in a `[double]` real literal is less
78+
than the minimum supported, the value of that `[double]` real literal is 0. If
79+
the value of exponent-part's digits in a `[decimal]` real literal is less than
80+
the minimum supported, that literal is malformed. If the value of
81+
exponent-part's digits in a `[double]` or `[decimal]` real literal is greater
82+
than the maximum supported, that literal is malformed.
83+
84+
> [!NOTE]
85+
> The syntax permits a double real literal to have a long-type suffix.
86+
> PowerShell treats this case as an integer literal whose value is represented
87+
> by type `[long]`. This feature has been retained for backwards compatibility
88+
> with earlier versions of PowerShell. However, programmers are discouraged
89+
> from using integer literals of this form as they can easily obscure the
90+
> literal's actual value. For example, `1.2L` has value 1, `1.2345e1L` has
91+
> value 12, and `1.2345e-5L` has value 0, none of which are immediately
92+
> obvious.
93+
94+
## Numeric multipliers
95+
96+
For convenience, integer and real literals can contain a numeric multiplier,
97+
which indicates one of a set of commonly used powers of 10. The numeric
98+
multiplier can be written in any combination of upper or lowercase letters.
99+
100+
The multiplier suffixes can be used in combination with the `u`, `ul`, and `l`
101+
type suffixes.
102+
103+
### Multiplier examples
104+
105+
```
106+
PS> 1kb
107+
1024
108+
109+
PS> 1.30Dmb
110+
1363148.80
111+
112+
PS> 0x10Gb
113+
17179869184
114+
115+
PS> 1.4e23tb
116+
1.5393162788864E+35
117+
118+
PS> 0x12Lpb
119+
20266198323167232
120+
```
121+
122+
## Numeric type accelerators
123+
124+
PowerShell supports the following type accelerators:
125+
126+
| Accelerator | Note | Description |
127+
| ----------- | -------------------- | -------------------------------- |
128+
| `[byte]` | | Byte (unsigned) |
129+
| `[sbyte]` | | Byte (signed) |
130+
| `[Int16]` | | 16-bit integer |
131+
| `[UInt16]` | | 16-bit integer (unsigned) |
132+
| `[Int32]` | | 32-bit integer |
133+
| `[int]` | alias for `[int32]` | 32-bit integer |
134+
| `[UInt32]` | | 32-bit integer (unsigned) |
135+
| `[Int64]` | | 64-bit integer |
136+
| `[long]` | alias for `[int64]` | 64-bit integer |
137+
| `[UInt64]` | | 64-bit integer (unsigned) |
138+
| `[bigint]` | | See [BigInteger Struct][bigint] |
139+
| `[single]` | | Single precision floating point |
140+
| `[float]` | alias for `[single]` | Single precision floating point |
141+
| `[double]` | | Double precision floating point |
142+
| `[decimal]` | | 128-bit floating point |
143+
144+
### Working with other numeric types
145+
146+
To work with any other numeric types you must use type accelerators, which is
147+
not without some problems. For example, high integer values are always parsed
148+
as double before being cast to any other type.
149+
150+
```
151+
PS> [bigint]111111111111111111111111111111111111111111111111111111
152+
111111111111111100905595216014112456735339620444667904
153+
```
154+
155+
The value is parsed as a double first, losing precision in the higher ranges.
156+
To avoid this problem, enter values as strings and then convert them:
157+
158+
```
159+
PS> [bigint]'111111111111111111111111111111111111111111111111111111'
160+
111111111111111111111111111111111111111111111111111111
161+
```
162+
163+
## Examples
164+
165+
The following table contains several examples of numeric literals and lists
166+
their type and value:
167+
168+
| Number | Type | Value |
169+
| -------: | ------- | -----------: |
170+
| 100 | Int32 | 100 |
171+
| 100D | Decimal | 100 |
172+
| 100l | Int64 | 100 |
173+
| 1e2 | Double | 100 |
174+
| 1.e2 | Double | 100 |
175+
| 0x1e2 | Int32 | 482 |
176+
| 0x1e2L | Int64 | 482 |
177+
| 0x1e2D | Int32 | 7725 |
178+
| 482D | Decimal | 482 |
179+
| 482gb | Int64 | 517543559168 |
180+
| 0x1e2lgb | Int64 | 517543559168 |
181+
182+
> [!NOTE]
183+
> Any commands that look like a numeric literal must be executed using the the
184+
> call operator, otherwise they are interpreted as a number of the associated
185+
> type.
186+
187+
<!-- reference links -->
188+
[bigint]: /dotnet/api/system.numerics.biginteger

‎reference/4.0/Microsoft.PowerShell.Core/About/about_numeric_literals.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
ms.date: 04/09/2018
3+
schema: 2.0.0
4+
locale: en-us
5+
keywords: powershell,cmdlet
6+
title: About numeric literals
7+
---
8+
# About numeric literals
9+
10+
There are two kinds of numeric literals: integer and real. Both can have type
11+
and multiplier suffixes.
12+
13+
## Integer literals
14+
15+
Integer literals can be written in decimal or hexadecimal notation. Hexadecimal
16+
literals are prefixed with `0x` to distinguish them from decimal numbers.
17+
18+
Integer literals can have a type suffix and a multiplier suffix.
19+
20+
| Suffix | Meaning |
21+
| ------ | ------------------- |
22+
| l | long data type |
23+
| kb | kilobyte multiplier |
24+
| mb | megabyte multiplier |
25+
| gb | gigabyte multiplier |
26+
| tb | terabyte multiplier |
27+
| pb | petabyte multiplier |
28+
29+
The type of an integer literal is determined by its value, the type suffix, and
30+
the numeric multiplier suffix.
31+
32+
For an integer literal with no type suffix:
33+
34+
- If the value can be represented by type `[int]`, that is its type.
35+
- Otherwise, if the value can be represented by type `[long]`, that is its
36+
type.
37+
- Otherwise, if the value can be represented by type `[decimal]`, that is its
38+
type.
39+
- Otherwise, it is represented by type `[double]`.
40+
41+
For an integer literal with a type suffix:
42+
43+
- If the type suffix is `u` and the value can be represented by type `[int]`
44+
then its type is `[int]`.
45+
- If the type suffix is `u` and the value can be represented by type `[long]`
46+
then its type is `[long]`.
47+
- If its value can be represented by type specified then that is its type.
48+
- Otherwise, that literal is malformed.
49+
50+
## Real literals
51+
52+
Real literals can only be written in decimal notation. This notation can
53+
include fractional values following a decimal point and scientific notation
54+
using an exponential part.
55+
56+
The exponential part includes an 'e' followed by an optional sign (+/-) and a
57+
number representing the exponent. For example, the literal value `1e2` equals
58+
the numeric value 100.
59+
60+
Real literals can have a type suffix and a multiplier suffix.
61+
62+
| Suffix | Meaning |
63+
| ------ | ------------------- |
64+
| d | decimal data type |
65+
| kb | kilobyte multiplier |
66+
| mb | megabyte multiplier |
67+
| gb | gigabyte multiplier |
68+
| tb | terabyte multiplier |
69+
| pb | petabyte multiplier |
70+
71+
There are two kinds of real literal: double and decimal. These are indicated by
72+
the absence or presence, respectively, of decimal-type suffix. PowerShell does
73+
not support a literal representation of a `[float]` value. A double real
74+
literal has type `[double]`. A decimal real literal has type `[decimal]`.
75+
Trailing zeros in the fraction part of a decimal real literal are significant.
76+
77+
If the value of exponent-part's digits in a `[double]` real literal is less
78+
than the minimum supported, the value of that `[double]` real literal is 0. If
79+
the value of exponent-part's digits in a `[decimal]` real literal is less than
80+
the minimum supported, that literal is malformed. If the value of
81+
exponent-part's digits in a `[double]` or `[decimal]` real literal is greater
82+
than the maximum supported, that literal is malformed.
83+
84+
> [!NOTE]
85+
> The syntax permits a double real literal to have a long-type suffix.
86+
> PowerShell treats this case as an integer literal whose value is represented
87+
> by type `[long]`. This feature has been retained for backwards compatibility
88+
> with earlier versions of PowerShell. However, programmers are discouraged
89+
> from using integer literals of this form as they can easily obscure the
90+
> literal's actual value. For example, `1.2L` has value 1, `1.2345e1L` has
91+
> value 12, and `1.2345e-5L` has value 0, none of which are immediately
92+
> obvious.
93+
94+
## Numeric multipliers
95+
96+
For convenience, integer and real literals can contain a numeric multiplier,
97+
which indicates one of a set of commonly used powers of 10. The numeric
98+
multiplier can be written in any combination of upper or lowercase letters.
99+
100+
The multiplier suffixes can be used in combination with the `u`, `ul`, and `l`
101+
type suffixes.
102+
103+
### Multiplier examples
104+
105+
```
106+
PS> 1kb
107+
1024
108+
109+
PS> 1.30Dmb
110+
1363148.80
111+
112+
PS> 0x10Gb
113+
17179869184
114+
115+
PS> 1.4e23tb
116+
1.5393162788864E+35
117+
118+
PS> 0x12Lpb
119+
20266198323167232
120+
```
121+
122+
## Numeric type accelerators
123+
124+
PowerShell supports the following type accelerators:
125+
126+
| Accelerator | Note | Description |
127+
| ----------- | -------------------- | -------------------------------- |
128+
| `[byte]` | | Byte (unsigned) |
129+
| `[sbyte]` | | Byte (signed) |
130+
| `[Int16]` | | 16-bit integer |
131+
| `[UInt16]` | | 16-bit integer (unsigned) |
132+
| `[Int32]` | | 32-bit integer |
133+
| `[int]` | alias for `[int32]` | 32-bit integer |
134+
| `[UInt32]` | | 32-bit integer (unsigned) |
135+
| `[Int64]` | | 64-bit integer |
136+
| `[long]` | alias for `[int64]` | 64-bit integer |
137+
| `[UInt64]` | | 64-bit integer (unsigned) |
138+
| `[bigint]` | | See [BigInteger Struct][bigint] |
139+
| `[single]` | | Single precision floating point |
140+
| `[float]` | alias for `[single]` | Single precision floating point |
141+
| `[double]` | | Double precision floating point |
142+
| `[decimal]` | | 128-bit floating point |
143+
144+
### Working with other numeric types
145+
146+
To work with any other numeric types you must use type accelerators, which is
147+
not without some problems. For example, high integer values are always parsed
148+
as double before being cast to any other type.
149+
150+
```
151+
PS> [bigint]111111111111111111111111111111111111111111111111111111
152+
111111111111111100905595216014112456735339620444667904
153+
```
154+
155+
The value is parsed as a double first, losing precision in the higher ranges.
156+
To avoid this problem, enter values as strings and then convert them:
157+
158+
```
159+
PS> [bigint]'111111111111111111111111111111111111111111111111111111'
160+
111111111111111111111111111111111111111111111111111111
161+
```
162+
163+
## Examples
164+
165+
The following table contains several examples of numeric literals and lists
166+
their type and value:
167+
168+
| Number | Type | Value |
169+
| -------: | ------- | -----------: |
170+
| 100 | Int32 | 100 |
171+
| 100D | Decimal | 100 |
172+
| 100l | Int64 | 100 |
173+
| 1e2 | Double | 100 |
174+
| 1.e2 | Double | 100 |
175+
| 0x1e2 | Int32 | 482 |
176+
| 0x1e2L | Int64 | 482 |
177+
| 0x1e2D | Int32 | 7725 |
178+
| 482D | Decimal | 482 |
179+
| 482gb | Int64 | 517543559168 |
180+
| 0x1e2lgb | Int64 | 517543559168 |
181+
182+
> [!NOTE]
183+
> Any commands that look like a numeric literal must be executed using the the
184+
> call operator, otherwise they are interpreted as a number of the associated
185+
> type.
186+
187+
<!-- reference links -->
188+
[bigint]: /dotnet/api/system.numerics.biginteger

0 commit comments

Comments
 (0)