الدالة map()‎ في أردوينو

تعيد الدالة map()‎ تموضع عدد من المجال الذي هو فيه إلى مجال آخر.

لا تقيِّد القيم ضمن المجال باستعمال الدالة constrain()‎ لأن خروج القيم عن المجال هو أمرٌ مقصود ومفيد أحيانًا. قد تستعمل الدالة constrain()‎ إمَّا قبل قبل أو بعد استعمال الدالة map()‎ إن كان يراد تقييد القيم ضمن مجالات.

البنية العامة

map(value, fromLow, fromHigh, toLow, toHigh)

ستعيد هذه الدالة تموضع القيمة value من الحد fromLow الأدنى للمجال القديم الواقعة ضمنه إلى الحد toLow الأدنى للمجال الجديد المقابل له، ومن الحد fromHigh الأعلى للمجال القديم إلى الحد toHigh الأعلى للمجال الجديد المقابل له، وسيعاد تموضع القيم الواقعة في المجال القديم إلى ما يقابلها من قيم في المجال الجديد. انتبه إلى أنَّ الحدود الدنيا المعطاة للدالة لكلا المجالين قد تكون أكبر أو أصغر من الحدود العليا، لذا قد تُستعمَل الدالة map()‎ لعكس مجالٍ من الأعداد:

y = map(x, 1, 50, 50, 1);

ويمكن للدالة أن تتعامل مع أعداد سالبة أيضًا:

y = map(x, 1, 50, 50, -100);

تتعامل الدالة مع أعداد صحيحة فقط، لذا لن تعيد أي عدد كسري أو عشري عندما يُفترَض أن يُعاد هذا النوع من العدد. تٌقتطَع الأجزاء العشرية المتبقية من العدد الكسري، ولن يُدوَّر العدد بحسب قيمة تلك الفواصل المقتطعة.

المعاملات

value

العدد المراد إعادة تموضعه في المجال الجديد.

fromLow

الحد الأدنى للمجال الحالي الذي تقع القيمة value ضمنه.

fromHigh

الحد الأعلى للمجال الحالي الذي تقع القيمة value ضمنه.

toLow

الحد الأدنى للمجال الجديد المراد نقل القيمة value إليه.

toHigh

الحد الأعلى للمجال الجديد المراد نقل القيمة value إليه.

القيم المعادة

تعاد القيمة التي تقابل القيمة value في المجال الجديد.

أمثلة

إعادة تموضع القيمة التشابهية المقاسة التي تكون عادةً بحجم 10 بت إلى الحجم 8 بت:

void setup() {}

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

ملحق

من أجل محبي الرياضيات، توضِّح الشيفرة التالية تفاصيل الدالة بأكملها:

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;
}

ملاحظات وتحذيرات

كما ذكر آنفًا، تتعامل الدالة map()‎ مع الأعداد الصحيحة فقط. بناءً على ذلك، ستُحذَف الفواصل من العدد المعاد تموضعه. على سبيل المثال، تعاد القيمة 1 التي يمكن أن تقابل الكسور 3/2 و 4/3 و 5/4 جميعها رغم اختلاف قيمها الفعلية. بالتالي، إن كان مشروعك يتطلَّب إجراء حسابات دقيقة (مثل التعامل مع قيمة جهد بدقة ثلاث منازل عشرية)، فتجنب رجاءً استعمال الدالة وأجري العملية الحسابية يدويًّا ضمن شيفرتك بنفسك.

انظر أيضًا

• الدالة abs()‎: تحسب القيمة المطلقة للعدد المُمرَّر إليها.
• الدالة constrain()‎: تقيِّد عددًا ضمن مجالٍ محدَّدٍ.
• الدالة max()‎: تعيد أكبر قيمة من القيم الممرَّرة إليها.
• الدالة min()‎: تعيد أصغر قيمة من القيم الممرَّرة إليها.

مصادر

• صفحة الدالة map()‎ في توثيق أردوينو الرسمي.