*[פונקציות מספריות](../perlfunc-by-category.md)*

# atan2

ארק טנגנס של `Y/X` בטווח ‎-π‎ עד π.

`atan2` הוא הארק־טנגנס בעל שני הארגומנטים — ההופכי של הטנגנס השומר על מספיק מידע על הקלטים שלו כדי להחזיר את הרביע הנכון. בשונה מ־`atan` חד־ארגומנטי, המכווץ את שני הסימנים של `Y` ו־`X` ליחס אחד ואינו יכול להבחין בין חצי המישור העליון לתחתון, `atan2` מסתכל על שני הארגומנטים ומחזיר זווית המכסה את המעגל המלא: ‎`(-π, π]`‎ רדיאנים. זוהי הדרך הקנונית ב־Perl להמיר קואורדינטות קרטזיות `(X, Y)` לזווית הקוטבית θ.

## תקציר

```perl
atan2 Y, X
```

## מה מוחזר

מספר בנקודה צפה, הזווית ברדיאנים בין ציר ה־x החיובי לנקודה `(X, Y)`, נמדדת נגד כיוון השעון. טווח: `-π < result ≤ π`. הסימן עוקב אחר `Y`: `Y` חיובי מניב זווית חיובית (חצי המישור העליון), `Y` שלילי מניב זווית שלילית (חצי המישור התחתון). להמרה למעלות יש להכפיל ב־`180 / π`:

```perl
my $deg = atan2($y, $x) * 180 / 3.14159265358979;
```

## דוגמאות

חישוב π בדיוק המכונה. הזווית מהראשית ל־`(0, 1)` היא בדיוק π/2, ולכן `atan2(1, 0) * 2` מניב π:

```perl
my $pi = atan2(1, 0) * 2;
printf "%.15f\n", $pi;          # 3.141592653589793
```

טיפול ברביעים. ארבעת הכיוונים העיקריים נופלים על כפולות מדויקות של π/2, כאשר `(−1, 0)` נמצא בגבול `+π`, לא `-π`:

```perl
print atan2( 1,  0), "\n";      #  1.5707963267949   (+π/2, up)
print atan2( 0,  1), "\n";      #  0                 (right)
print atan2(-1,  0), "\n";      # -1.5707963267949   (-π/2, down)
print atan2( 0, -1), "\n";      #  3.14159265358979  (+π, left)
```

המרה קוטבית. בהינתן נקודה `(X, Y)`, יש לשחזר רדיוס וזווית:

```perl
my ($x, $y) = (3, 4);
my $r     = sqrt($x*$x + $y*$y);    # 5
my $theta = atan2($y, $x);          # 0.927295218001612 rad ≈ 53.13°
```

טנגנס באמצעות הזהות הסטנדרטית. ל־Perl אין `tan` מובנה, אך [`sin`](sin.md) ו־[`cos`](cos.md) מספקים אותו ישירות — ו־`atan2` הופך את התוצאה ללא דו־משמעות:

```perl
sub tan { sin($_[0]) / cos($_[0]) }
my $angle = 0.7;
print atan2(tan($angle), 1), "\n";  # 0.7  (recovers the input)
```

סריקת מעגל מלא. איטרציה של `Y` סביב מעגל היחידה מראה שהטווח מכסה ‎`(-π, π]`‎:

```perl
for my $deg (0, 45, 90, 135, 180, -135, -90, -45) {
    my $rad = $deg * 3.14159265358979 / 180;
    printf "%4d°  ->  %+.4f rad\n",
        $deg, atan2(sin($rad), cos($rad));
}
```

## מקרי קצה

- **שני הארגומנטים אפס**: `atan2(0, 0)` אינו מוגדר מתמטית. הערך ש־Perl מחזיר הוא מה שה־`atan2(3)` של C בפלטפורמה מחזיר עבור מקרה זה — ב־glibc וב־musl זהו `0`, ו־POSIX מאפשר כל ערך ב־`[-π, π]`. אין להסתמך על תוצאה ספציפית; יש לבדוק `($x == 0 && $y == 0)` לפני הקריאה אם אפס הוא אפשרות אמיתית בקלטים.
- **אפסים עם סימן**: בפלטפורמות IEEE-754 `atan2(+0, -0)` מחזיר `+π` ו־`atan2(-0, -0)` מחזיר `-π`. זה משנה רק בקוד שעוקב במכוון אחר סימני אפס; רוב קוד ה־Perl לעולם אינו מבחין ביניהם.
- **אינסופים**: `atan2(Inf, Inf) == π/4`, `atan2(Inf, -Inf) == 3π/4`, `atan2(-Inf, Inf) == -π/4`, `atan2(-Inf, -Inf) == -3π/4`. הכיוון ”לעבר `(±Inf, ±Inf)`“ עדיין מהווה זווית מוגדרת היטב החוצה את הרביע המתאים.
- **קלטי NaN**: אם `Y` או `X` הם `NaN`, התוצאה היא `NaN`. מתפשט דרך כל אריתמטיקה נוספת — יש להגן באמצעות בדיקת `Scalar::Util::looks_like_number` על קלטים ממקורות לא־אמינים.
- **ארגומנטים לא־מספריים**: מחרוזות מומרות למספרים לפי כללי Perl הרגילים. `atan2("3", "4")` עובד; `atan2("abc", 1)` שווה־ערך ל־`atan2(0, 1)` ופולט אזהרת `Argument "abc" isn't numeric` תחת `use warnings`.
- **סדר הארגומנטים הוא `Y, X`, לא `X, Y`**: זה תואם את `atan2(3)` של C, את `ATAN2` של FORTRAN, ואת הארק־טנגנס בעל שני הארגומנטים בכל שפה אחרת. היפוך הארגומנטים מניב את הזווית המשלימה — באג עדין שבדיקות ברביע אחד בלבד יחמיצו.
- **`atan2` אינו `atan`**: אין צורה חד־ארגומנטית. `atan2($ratio)` הוא שגיאת תחביר באתר הקריאה. עבור הארק־טנגנס החד־ארגומנטי, יש להשתמש ב־`Math::Trig::atan` או `POSIX::atan`, או לכתוב אותו כ־`atan2($ratio, 1)`.

## הבדלים מן ה-upstream

תואם מלא ל־Perl 5.42 upstream.

## ראו גם

- [`sin`](sin.md) — סינוס; משתלב עם [`cos`](cos.md) לשחזור הקואורדינטות של זווית לאחר ש־`atan2` חילץ אותה
- [`cos`](cos.md) — קוסינוס; הרכיב `X` בעת המרת רדיוס וזווית בחזרה לקואורדינטות קרטזיות
- [`sqrt`](sqrt.md) — שורש ריבועי; בשימוש עם `atan2` בהמרה הקרטזית → הקוטבית `($r, $theta) = (sqrt($x**2+$y**2), atan2($y,$x))`
- <a class="pperl-ext" href="https://metacpan.org/pod/Math::Trig" title="External CPAN module — not shipped by pperl natively. Opens metacpan.org/pod/Math::Trig." target="_blank" rel="noopener"><code>Math::Trig</code><sub class="pperl-ext-marker">ext</sub></a> — מספק את `tan`, `atan`, `asin`, `acos` ואת המשפחה ההיפרבולית; גם מייצא את `pi` כקבוע כך שלא צריך לכתוב `atan2(1,0)*2`