1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
# Logarithm RPN Operators
gt provides three logarithm operators: `lg` (base 2), `log` (base 10), and `ln` (natural log, base *e*). Each is a unary operator that pops a single value from the stack, computes the logarithm, and pushes the result.
Logarithm results are always unitless (Cool metric), regardless of whether the input carried a metric.
## How RPN Works
For unary operators, the operand precedes the operator:
```
Input: 8 lg
Step Stack
---- -----
8 [8]
lg [3]
Result: 3
```
## Operators
### `lg` — Logarithm Base 2
Computes the base-2 logarithm: log₂(*x*).
log₂(*x*) = *y* means 2^*y* = *x*. It answers: "To what power must be raised to produce *x*?"
#### Examples
```
$ echo "8 lg" | gt
3
$ echo "1024 lg" | gt
10
$ echo "1 lg" | gt
0
$ echo "1e-10 lg" | gt
-33.21928095
```
#### Use cases
- **Information theory** — Number of bits needed to represent *x* distinct values (e.g., log₂(1024) = 10 bits).
- **Algorithms** — Time complexity of divide-and-conquer algorithms (O(log n)).
- **Computer science** — Tree height, binary search steps.
---
### `log` — Logarithm Base 10
Computes the base-10 logarithm: log₁₀(*x*).
log₁₀(*x*) = *y* means 10^*y* = *x*. It answers: "To what power must 10 be raised to produce *x*?"
#### Examples
```
$ echo "1000 log" | gt
3
$ echo "100 log" | gt
2
$ echo "10 log" | gt
1
$ echo "1 log" | gt
0
$ echo "1e-10 log" | gt
-10
```
#### Use cases
- **Decibels (dB)** — Sound intensity and signal power ratios: L = 10 · log₁₀(P/P₀). Example: `1000 10 / log 10 *` → 30 dB.
- **pH scale** — Acidity/alkalinity: pH = -log₁₀([H⁺]). Example: `1e-7 log 0 -` → 7 (neutral water).
- **Order of magnitude** — Quick estimate of size: log₁₀(500) ≈ 2.7 means "between 100 and 1000".
- **Scientific notation** — The integer part of log₁₀(*x*) gives the exponent.
---
### `ln` — Natural Logarithm
Computes the natural logarithm: ln(*x*) = logₑ(*x*), where *e* ≈ 2.718281828.
ln(*x*) = *y* means *e*^*y* = *x*. It is the inverse of the exponential function and the integral of 1/*t* from 1 to *x*.
#### Examples
```
$ echo "e ln" | gt
1
$ echo "2.718281828 ln" | gt
0.9999999998
$ echo "1 ln" | gt
0
$ echo "7.38905609893065 ln" | gt
2
```
#### Use cases
- **Continuous growth** — Compound interest, population growth: A = A₀ · e^(rt). Solve for t: t = ln(A/A₀) / r.
- **Probability & statistics** — Normal distribution, likelihood functions.
- **Calculus** — Derivative of ln(*x*) is 1/*x*; integral of 1/*x* is ln(|*x*|).
- **Entropy** — Shannon entropy uses natural log in thermodynamics.
---
## Edge Cases
All three operators are **undefined for non-positive numbers**. Zero and negative inputs produce an error:
```
$ echo "0 lg" | gt
Error: lg undefined for non-positive numbers
$ echo "-5 log" | gt
Error: log undefined for non-positive numbers
$ echo "0 ln" | gt
Error: ln undefined for non-positive numbers
$ echo "-1 ln" | gt
Error: ln undefined for non-positive numbers
```
### Summary table
| Input | Result |
|----------|-------------------------------|
| *x* > 0 | Computed normally |
| *x* = 0 | Error (undefined) |
| *x* < 0 | Error (undefined) |
| *x* = 1 | 0 (for all three operators) |
| empty | Error (stack underflow) |
---
## Metric Handling
Logarithms always produce unitless results. Even when the input carries a metric, the result is Cool (no metric):
```
$ echo "100Mbps lg" | gt # treats as number with metric, result is Cool
```
This is mathematically correct — taking a logarithm of a dimensioned quantity requires a reference value (e.g., log₁₀(P/P₀) for decibels), so gt treats the operands as their numeric values.
|
