عرض مصدر Arduino/math/map

<noinclude>{{DISPLAYTITLE:الدالة <code>map()‎</code> في  أردوينو}}</noinclude>
تعيد الدالة <code>map()‎</code> تموضع عدد من المجال الذي هو فيه إلى مجال آخر.

لا تقيِّد القيم ضمن المجال باستعمال الدالة <code>[[Arduino/math/constrain|constrain()‎]]</code> لأن خروج القيم عن المجال هو أمرٌ مقصود ومفيد أحيانًا. قد تستعمل الدالة [[Arduino/math/constrain|<code>constrain()‎</code>]] إمَّا قبل قبل أو بعد استعمال الدالة <code>map()‎</code> إن كان يراد تقييد القيم ضمن مجالات.

==البنية العامة==
<syntaxhighlight lang="arduino">
map(value, fromLow, fromHigh, toLow, toHigh)
</syntaxhighlight>ستعيد هذه الدالة تموضع القيمة <code>value</code> من الحد <code>fromLow</code> الأدنى للمجال القديم الواقعة ضمنه إلى الحد <code>toLow</code> الأدنى للمجال الجديد المقابل له، ومن الحد <code>fromHigh</code> الأعلى للمجال القديم إلى الحد <code>toHigh</code> الأعلى للمجال الجديد المقابل له، وسيعاد تموضع القيم الواقعة في المجال القديم إلى ما يقابلها من قيم في المجال الجديد.

انتبه إلى أنَّ الحدود الدنيا المعطاة للدالة لكلا المجالين قد تكون أكبر أو أصغر من الحدود العليا، لذا قد تُستعمَل الدالة <code>map()‎</code> لعكس مجالٍ من الأعداد:<syntaxhighlight lang="arduino">
y = map(x, 1, 50, 50, 1);
</syntaxhighlight>ويمكن للدالة أن تتعامل مع أعداد سالبة أيضًا:<syntaxhighlight lang="arduino">
y = map(x, 1, 50, 50, -100);
</syntaxhighlight>تتعامل الدالة مع أعداد صحيحة فقط، لذا لن تعيد أي عدد كسري أو عشري عندما يُفترَض أن يُعاد هذا النوع من العدد. تٌقتطَع الأجزاء العشرية المتبقية من العدد الكسري، ولن يُدوَّر العدد بحسب قيمة تلك الفواصل المقتطعة.

== المعاملات ==

=== <code>value</code> ===
العدد المراد إعادة تموضعه في المجال الجديد.

=== <code>fromLow</code> ===
الحد الأدنى للمجال الحالي الذي تقع القيمة <code>value</code> ضمنه.

=== <code>fromHigh</code> ===
الحد الأعلى للمجال الحالي الذي تقع القيمة <code>value</code> ضمنه.

=== <code>toLow</code> ===
الحد الأدنى للمجال الجديد المراد نقل القيمة <code>value</code> إليه.

=== <code>toHigh</code> ===
الحد الأعلى للمجال الجديد المراد نقل القيمة <code>value</code> إليه.

==القيم المعادة==
تعاد القيمة التي تقابل القيمة <code>value</code> في المجال الجديد.

== أمثلة ==
إعادة تموضع القيمة التشابهية المقاسة التي تكون عادةً بحجم 10 بت إلى الحجم 8 بت:<syntaxhighlight lang="arduino">
void setup() {}

void loop()
{
  int val = analogRead(0);
  val = map(val, 0, 1023, 0, 255);
  analogWrite(9, val);
}
</syntaxhighlight>

== ملحق ==
من أجل محبي الرياضيات، توضِّح الشيفرة التالية تفاصيل الدالة بأكملها:<syntaxhighlight lang="arduino">
long map(long x, long in_min, long in_max, long out_min, long out_max)
{
  return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;
}
</syntaxhighlight>
==ملاحظات وتحذيرات==
كما ذكر آنفًا، تتعامل الدالة <code>map()‎</code> مع الأعداد الصحيحة فقط. بناءً على ذلك، ستُحذَف الفواصل من العدد المعاد تموضعه. على سبيل المثال، تعاد القيمة 1 التي يمكن أن تقابل الكسور 3/2 و 4/3 و 5/4 جميعها رغم اختلاف قيمها الفعلية. بالتالي، إن كان مشروعك يتطلَّب إجراء حسابات دقيقة (مثل التعامل مع قيمة جهد بدقة ثلاث منازل عشرية)، فتجنب رجاءً استعمال الدالة وأجري العملية الحسابية يدويًّا ضمن شيفرتك بنفسك.
==انظر أيضًا==
* الدالة <code>[[Arduino/math/abs|abs()‎]]</code>: تحسب القيمة المطلقة للعدد المُمرَّر إليها.
* الدالة <code>[[Arduino/math/constrain|constrain()‎]]</code>: تقيِّد عددًا ضمن مجالٍ محدَّدٍ.
* الدالة <code>[[Arduino/math/max|max()‎]]</code>: تعيد أكبر قيمة من القيم الممرَّرة إليها.
* الدالة <code>[[Arduino/math/min|min()‎]]</code>: تعيد أصغر قيمة من القيم الممرَّرة إليها.

==مصادر==
*[https://www.arduino.cc/reference/en/language/functions/math/map/ صفحة الدالة map()‎ في توثيق أردوينو الرسمي.]
[[تصنيف: Arduino]]
[[تصنيف: Arduino Function]]
[[تصنيف: Arduino Math]]