0
# Ruby Functions
1

2
Ruby standard library functions ported to JavaScript. This module contains 1 mathematical function from Ruby's Math module.
3

4
## Capabilities
5

6
### Math Functions (1 function)
7

8
Mathematical function from Ruby's Math standard library module.
9

10
```javascript { .api }
11
/**
12
 * Ruby Math module function
13
 */
14
ruby.Math.acos(x)  // Arc cosine (inverse cosine) function
15
```
16

17
**Usage Examples:**
18

19
```javascript
20
const locutus = require('locutus');
21

22
// Calculate arc cosine
23
const result1 = locutus.ruby.Math.acos(1);     // 0 (radians)
24
const result2 = locutus.ruby.Math.acos(0);     // 1.5707963267948966 (π/2 radians)
25
const result3 = locutus.ruby.Math.acos(-1);    // 3.141592653589793 (π radians)
26
const result4 = locutus.ruby.Math.acos(0.5);   // 1.0471975511965979 (π/3 radians)
27

28
// Convert result to degrees
29
const degrees = locutus.ruby.Math.acos(0.5) * (180 / Math.PI); // 60 degrees
30
```
31

32
## Function Details
33

34
### acos(x)
35

36
Returns the arc cosine (inverse cosine) of x in radians.
37

38
```javascript { .api }
39
/**
40
 * Return the arc cosine of x in radians
41
 * @param {number} x - A number between -1 and 1 (inclusive)
42
 * @returns {number} The arc cosine of x in radians (0 to π)
43
 */
44
ruby.Math.acos(x)
45
```
46

47
**Parameters:**
48
- `x` (number): A numeric value between -1 and 1 (inclusive)
49

50
**Returns:**
51
- (number): The arc cosine of `x` in radians, ranging from 0 to π
52

53
**Domain and Range:**
54
- **Domain**: -1 ≤ x ≤ 1
55
- **Range**: 0 ≤ acos(x) ≤ π
56

57
**Special Values:**
58
- `acos(1)` returns `0`
59
- `acos(0)` returns `π/2` (approximately 1.5707963267948966)
60
- `acos(-1)` returns `π` (approximately 3.141592653589793)
61

62
**Examples:**
63
```javascript
64
const locutus = require('locutus');
65

66
// Standard values
67
locutus.ruby.Math.acos(1);      // 0
68
locutus.ruby.Math.acos(0);      // 1.5707963267948966 (π/2)
69
locutus.ruby.Math.acos(-1);     // 3.141592653589793 (π)
70

71
// Common trigonometric values
72
locutus.ruby.Math.acos(0.5);           // 1.0471975511965979 (π/3, or 60°)
73
locutus.ruby.Math.acos(Math.sqrt(2)/2); // 0.7853981633974483 (π/4, or 45°)
74
locutus.ruby.Math.acos(Math.sqrt(3)/2); // 0.5235987755982988 (π/6, or 30°)
75

76
// Edge cases
77
locutus.ruby.Math.acos(0.9999);  // Very close to 0
78
locutus.ruby.Math.acos(-0.9999); // Very close to π
79

80
// Invalid input (outside domain) returns NaN
81
locutus.ruby.Math.acos(2);       // NaN
82
locutus.ruby.Math.acos(-2);      // NaN
83
```
84

85
## Use Cases
86

87
The Ruby `acos` function is useful for:
88

89
- **Trigonometric Calculations**: Computing angles from cosine values
90
- **Geometric Operations**: Finding angles in triangles and other shapes  
91
- **Physics Simulations**: Calculating angles in vector operations
92
- **Computer Graphics**: Angle calculations for rotations and transformations
93
- **Engineering Applications**: Converting between different angle representations
94

95
```javascript
96
const locutus = require('locutus');
97

98
// Calculate angle between two vectors
99
function angleBetweenVectors(v1, v2) {
100
  // Calculate dot product
101
  const dotProduct = v1.x * v2.x + v1.y * v2.y + v1.z * v2.z;
102
  
103
  // Calculate magnitudes
104
  const mag1 = Math.sqrt(v1.x * v1.x + v1.y * v1.y + v1.z * v1.z);
105
  const mag2 = Math.sqrt(v2.x * v2.x + v2.y * v2.y + v2.z * v2.z);
106
  
107
  // Calculate cosine of angle
108
  const cosTheta = dotProduct / (mag1 * mag2);
109
  
110
  // Return angle in radians
111
  return locutus.ruby.Math.acos(cosTheta);
112
}
113

114
// Convert radians to degrees
115
function radiansToDegrees(radians) {
116
  return radians * (180 / Math.PI);
117
}
118

119
// Calculate triangle angle from sides (law of cosines)
120
function triangleAngle(a, b, c) {
121
  // Calculate angle opposite to side 'a'
122
  const cosA = (b * b + c * c - a * a) / (2 * b * c);
123
  return locutus.ruby.Math.acos(cosA);
124
}
125

126
// Examples
127
const vector1 = { x: 1, y: 0, z: 0 };
128
const vector2 = { x: 0, y: 1, z: 0 };
129
const angle = angleBetweenVectors(vector1, vector2);
130
console.log(`Angle: ${radiansToDegrees(angle)}°`); // 90°
131

132
const triangleAngleA = triangleAngle(3, 4, 5); // Right triangle
133
console.log(`Triangle angle: ${radiansToDegrees(triangleAngleA)}°`); // ~36.87°
134
```
135

136
## Mathematical Notes
137

138
The arc cosine function is the inverse of the cosine function:
139
- If `cos(θ) = x`, then `acos(x) = θ`
140
- The function is defined only for values between -1 and 1
141
- The output is always between 0 and π radians (0° to 180°)
142
- The function is decreasing: as x increases from -1 to 1, acos(x) decreases from π to 0
143

144
## Import Patterns
145

146
```javascript
147
// Full module access
148
const locutus = require('locutus');
149
locutus.ruby.Math.acos(0.5);
150

151
// Individual function import
152
const acos = require('locutus/ruby/Math/acos');
153
acos(0.5);  // 1.0471975511965979
154

155
// Note: Ruby uses Math (capital M) unlike JavaScript's math (lowercase)
156
// This follows Ruby's naming convention where Math is a module
157
```