> For the complete documentation index, see [llms.txt](https://mind-expression-docs.gitbook.io/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mind-expression-docs.gitbook.io/home/how-to-guides/intelligent-process/package-kernel-numbers.md).

# Package: Kernel-Numbers

## Class: Number

### Introduction

**Environment: `container`**

A common abstract superclass for all Number implementations. It is the superclass of all classes that represent numbers, for example Integer, Float, and Fraction, etc. The binary operators `+`,`=`,`*`,`/` are defined for all numbers, so we can do arithmetic.

For example:

```smalltalk
1+2*8
```

We support traditional arithmetic precedence, so the above expression is equivalent to:

```smalltalk
1+(2*8)
```

### Class Method

#### Category: instance creation

* **`new`** - Create a new number object. The default value is 1.

### Instance Method

#### Category: arithmetic

* **`*`** - Multiply two numbers.
* **`+`** - Add two numbers.
* **`-`** - Subtract two numbers.
* **`/`** - Divide two numbers.
* **`abs`** - answer a number that is the absolute value (positive magnitude) of the receiver.

  For example:

  ```smalltalk
  "ab = 243.2"
  ab := -243.2 abs
  ```
* **`even`** - Answer whether the receiver is an even number.

  For example:

  ```smalltalk
  4 even = true.
  ```
* **`floor`** - answer a Number that is the floor value (positive magnitude) of the receiver.

  For example:

  ```smalltalk
  "ab = 25"
  ab := 25.75 floor
  ```
* **`odd`** - Answer whether the receiver is an odd number.

  For example:

  ```smalltalk
  3 odd = true.
  ```
* **`raisedTo:`** - answer the receiver raised to aNumber.

  For example:

  ```smalltalk
  (2 raisedTo: 8) = 256.
  (8 raisedTo: 2) = 64.
  (2 raisedTo: (1/12)) = 1.0.
  (2 raisedTo: -1) = (1/2).
  ```

#### Category: comparing

* **`<`** - Compare the receiver with the argument and answer with true if the receiver is less than the argument. Otherwise answer false.
* **`<=`** - Compare the receiver with the argument and answer true if the receiver is less than or equal to the argument. Otherwise answer false.
* **`=`** - Compare the receiver with the argument and answer true if the receiver is equal to the argument. Otherwise answer false.
* **`>`** - answer whether the receiver sorts after aString. The collation order is simple ascii (with case differences).
* **`>=`** - Compare the receiver with the argument and answer true if the receiver is greater than or equal to the argument. Otherwise answer false.
* **`isFloat`** - Test if object is float.

  For example:

  ```smalltalk
  2 isFloat = false.
  vn := 3.5 asFloat.
  vn isFloat = true.
  ```
* **`isInteger`** - Test if object is integer.

  For example:

  ```smalltalk
  -1 isInteger = true.
  2 isInteger = true.
  vn := 3.5 asFloat.
  vn isInteger = false.
  ```
* **`isZero`** - Test if number is zero.

  For example:

  ```smalltalk
  0.0 isZero = true.
  2 isZero = false.
  ```
* **`max:`** - Answer the greater of the two numbers in arguments

  For example:

  ```smalltalk
  x := 3 max: 5. "x = 5"
  x := 8 max: 5. "x = 8"
  x := 3 max: 3. "x = 3"
  ```
* **`min:`** - Answer the lesser of the two numbers in arguments

  For example:

  ```smalltalk
  x := 3 min: 5. "x = 3"
  x := 8 min: 5. "x = 5"
  x := 3 min: 3. "x = 3"
  ```
* **`negative`** - Test if number is negative.

  For example:

  ```smalltalk
  -1 negative = true.
  2 negative = false.
  0 negative = false.
  ```
* **`positive`** - Test if number is positive.

  For example:

  ```smalltalk
  1 positive = true.
  -2 positive = false.
  0 positive = true.
  ```
* **`strictlyPositive`** - test if number is greater than zero.

  For example:

  ```smalltalk
  1 strictlyPositive = true.
  -2 strictlyPositive = false.
  0 strictlyPositive = false.
  ```

#### Category: controlling

* **`timesRepeat:`** - Evaluate the argument, aBlock, the number of times represented by the receiver.

  For example:

  ```smalltalk
  "Print aaa"
  3 timesRepeat: [ Console print: 'a'].
  ```
* **`to:`** - Normally compiled in-line, and therefore not overridable.

  Build an array of the integers from the receiver to the argument, aNumber, and evaluate aBlock with each of the integers as the argument.

  For example:

  ```smalltalk
  "array = [1 2 3 4 5]"
  array := 1 to: 5 . 
  ```
* **`to:by:do:`** - Normally compiled in-line, and therefore not overridable. Evaluate aBlock for each element of the interval (self to: stop by: step).

  For example:

  ```smalltalk
  "Print 0 2 4 6"
  0 to: 6 by: 2 do: [:i | Console print: i, ' '].
  ```
* **`to:do:`** - Normally compiled in-line, and therefore not overridable. Evaluate aBlock for each element of the interval (self to: stop by: 1).

  For example:

  ```smalltalk
  "Print 1 2 3 4 5"
  1 to: 5 do: [:i | Console print: i, ' '].
  ```

#### Category: converting

* **`asCharacter`** - Answer the Character whose value is the receiver.

  For example:

  ```smalltalk
  65 asCharacter = $A.
  ```
* **`asCustomNumber:`** - The custom numeric format specifiers

  The custom numeric format specifiers answer a string that is the receiver formatted according to the format string. The format string is a string that contains a number of placeholders that are replaced by the corresponding values of the receiver.

  Here is a list of available format String.

  \[`0`] \*\* Zero placeholder\*\*. Replaces the zero with the corresponding digit if one is present; otherwise, zero appears in the result string.

  **Example:**

  ```smalltalk
  (12.34 asCustomNumber: '0') = '12'.
  (12.34 asCustomNumber: '00') = '12'.
  (12.34 asCustomNumber: '000') = '012'.
  (12.34 asCustomNumber: '0000') = '0012'.
  (12.44 asCustomNumber: '00') = '0013'.
  ```

  \[`#`] **Digit placeholder**. Replaces the “#” symbol with the corresponding digit if one is present; otherwise, no digit appears in the result string.

  No digit appears in the result string if the corresponding digit in the input string is a non-significant 0.

  **Example:**

  ```smalltalk
  (12.34 asCustomNumber: '#') = '12'.
  (12.34 asCustomNumber: '##') = '12'.
  (12.34 asCustomNumber: '###') = '12'.
  (12.34 asCustomNumber: '####') = '12'.
  (12.44 asCustomNumber: '##') = '0013'.
  ```

  `.`

  \[`.`] **Decimal point**. Determines the location of the decimal separator in the result string.

  **Example:**

  ```smalltalk
  (12.34 asCustomNumber: '0.0') = '12.3'.
  (12.44 asCustomNumber: '.00') = '12.34.
  (12.44 asCustomNumber: '.') = '12'.
  ```

  \[`,`] **Group separator and number scaling**. Can be used as both a group separator (also known as a thousand separator) and a number scaling specifier.

  * As a **group separator**, it inserts a localized group separator character between each group.
  * As a **number scaling specifier**, it divides a number by 1000 for each comma specified.

  To specify a group separator, place one or more commas between two digit placeholders (0 or #) that format the integral digits of a number. This results in a group separator character being inserted between each number group in the integral part of the output.

  To specify a number scaling specifier, place one or more commas immediately to the left of the explicit or implicit decimal point.

  **Example - As a Group Separator:**

  ```smalltalk
  (12345678 asCustomNumber: '#,#') = '12,345,678'.
  ```

  **Example – As a Number Scaling Specifier**:

  ```smalltalk
  (12000 asCustomNumber: '#,') = '12'.
  (1234567890 asCustomNumber: '#,,') = '1235'.
  ```

  **Example – As Both**:

  ```smalltalk
  (1234567890 asCustomNumber: '#,#,') = '1,234,568'.
  (1234567890 asCustomNumber: '#,#,,') = '1,235'.
  ```

  \[`%`] **Percentage placeholder**. Multiplies a number by 100 and inserts a localized percentage symbol in the result string.

  **Example:**

  ```smalltalk
  (0.1234 asCustomNumber: '#.# %') = '12.3 %'.
  (0.1235 asCustomNumber: '#.#%') = '12.4%'.
  (0.125 asCustomNumber: '#. %') = '13 %'.
  (0.1234 asCustomNumber: '#.#%') = '12.3%'.
  ```

  \[`‰`] **Per mille placeholder**. Multiplies a number by 1000 and inserts a localized per mille symbol in the result string.

  **Example:**

  ```smalltalk
  (0.01234 asCustomNumber: '#.# ‰') = '12.3 ‰'.
  (0.01235 asCustomNumber: '#.# ‰') = '12.4 ‰'.
  (0.0125 asCustomNumber: '#. ‰') = '13 ‰'.
  (0.01234 asCustomNumber: '#.# ‰') = '12.3 ‰'.
  ```

  \[`E0` `E+0` `E-0` `e0` `e+0` `e-0`] **Exponential notation**. If followed by at least one zero (`0`), formats the result using exponential notation. The case (`E` or `e`) indicates the case of the exponent symbol in the result string. The number of zeros following the `E` or `e` character determines the minimum number of digits in the exponent. A plus sign (`+`) indicates that a sign character always precedes the exponent. A minus sign (`-`) indicates that a sign character precedes only negative exponents.

  **Example:**

  ```smalltalk
  (123456789 asCustomNumber: '0e0') = '1e8'.
  (123456789 asCustomNumber: '0e+0') = '1e+8'.
  (123456789 asCustomNumber: '0E+00') = '1E+08'.
  (1234.56789 asCustomNumber: '0.0##e+00') = '1.235e+03'.
  (12.3456789-12 asCustomNumber: '0e-0') = '3e-1'.
  ```

  \[`\`] **Escape character**. Causes the next character to be interpreted as a literal rather than as a custom format specifier.

  **Example**:

  ```smalltalk
  (123 asCustomNumber: '\#0000') = '#0123'.
  ```

  \[`'string'` `"string"`] **Literal string delimiter**. Indicates that the enclosed characters should be copied to the result string unchanged.

  **Example**:

  ```smaltalk
  (23 asCustomNumber: '## Degrees') = '23 Degrees'.
  ```

  \[`;`, Other] **All other characters.** The character is copied to the result string unchanged.

  **Example**:

  ```smalltalk
  (12 asCustomNumber: '# °C') = '12 °C'.
  ```
* **`asFloat`** - Answer the number as a float data type.

  For example:

  ```smalltalk
  w := 3 / 2 asFloat. "w = 1.5"
  w := 2 asFloat. "w = 2.0"
  ```
* **`asInteger`** - return the integer present in the receiver, or nil. In case of float, returns the integer part.

  For example:

  ```smalltalk
  120 asInteger = 120.
  120.3 asInteger = 120.
  ```
* **`asString`** - Converts a number into a string.

  For example:

  ```smalltalk
  str := 12 asString. "returns '12'"
  str := 12.3 asString. "returns '12.3'"
  ```
* **`roundTo:`** - Answer the number, rounded to the nearest multiple of the other argument.

  For example:

  ```smalltalk
  z := 23 roundTo: 5. "z = 25"
  z := 9 roundTo: 4. "z = 8"
  ```
* **`truncateTo:`** - Answer the number, truncated to the nearest multiple of the other argument.

  For example:

  ```smalltalk
  z := 23 truncateTo: 5. "z = 20"
  z := 9 truncateTo: 4. "z = 8"
  ```

#### Category: math

* **`cos`** - Answer the cosine of the number. The argument is assumed to be in radians.

  For example:

  ```smalltalk
  z := 1.0472 cos. "z = 0.49999788"
  ```
* **`exp`** - Answer the e raised to the number.

  For example:

  ```smalltalk
  z := 3 exp. "z = 20.085537"
  ```
* **`ln`** - Answer the natural log (base e) of the number.

  For example:

  ```smalltalk
  z := 23 ln. "z = 3.1354943"
  ```
* **`log:`** - Answer the log of the number, base of number in second argument.

  For example:

  ```smalltalk
  z := 23 log: 3. "z = 2.85405"
  ```
* **`sin`** - Answer the sine of the number. The angle is assumed to be in radians.

  For example:

  ```smalltalk
  z := 0.523599 sin. "z = 0.5000002"
  ```
* **`sqrt`** - Answer the square root of the number.

  For example:

  ```smalltalk
  z := 4 sqrt. "z = 2.0"
  ```
* **`squared`** - Answer the square of the number.

  For example:

  ```smalltalk
  z := 13 squared. "z = 169"
  z := -4 squared. "z = 16"
  ```
* **`tan`** - Answer the tangent of the number. The angle is assumed to be in radians.

  For example:

  ```smalltalk
  z := 0.785398 tan. "z = 0.9999997"
  ```
* **`tanh`** - Answer the hyperbolic tangent of the number. The angle is assumed to be in radians.

  For example:

  ```smalltalk
  z := 23 tanh. "z = 1.0"
  ```