کتابخانه توابع پیشنهادی
از آنجا که PAWN به عنوان یک زبان توسعه برنامه هدف‌گذاری شده است، بیشتر توابعی که برای برنامه‌های PAWN قابل دسترسی هستند، مختص برنامه میزبان خواهند بود. با این حال، مجموعه کوچکی از توابع ممکن است برای بسیاری از محیط‌ها مفید باشد.
• توابع اصلی
ماژول "اصلی" شامل مجموعه‌ای از توابع است که از زبان پشتیبانی می‌کنند. چندین تابع برای استخراج آرگومان‌ها از یک لیست آرگومان متغیر مورد نیاز هستند (صفحه 80 را ببینید).
| clamp | یک مقدار را در یک محدوده قرار می‌دهد | |
|---|---|---|
| نحو | clamp(value, min=cellmin, max=cellmax) | |
| value | مقداری که باید در محدوده قرار گیرد | |
| min | حد پایین محدوده. | |
| max | حد بالای محدوده. | |
| برمی‌گرداند | value اگر در محدوده min – max باشد؛ min اگر value کمتر از min باشد؛ و max اگر value بیشتر از max باشد. | |
| همچنین ببینید | max، min |
| funcidx | شاخص یک تابع عمومی را برمی‌گرداند | |
|---|---|---|
| نحو | funcidx(const name[]) | |
| برمی‌گرداند | شاخص تابع عمومی با نام مشخص شده. اگر هیچ تابع عمومی با نام داده شده وجود نداشته باشد، funcidx مقدار −1 را برمی‌گرداند. | |
| نکات: | یک برنامه میزبان یک تابع عمومی را از اسکریپت با ارسال شاخص تابع عمومی به amx_Exec اجرا می‌کند. با این تابع، اسکریپت می‌تواند شاخص یک تابع عمومی را پرس و جو کند، و بدین ترتیب "تابع بعدی برای فراخوانی" را به برنامه برگرداند. |
| getarg | دریافت یک آرگومان | |
|---|---|---|
| نحو | getarg(arg, index=0) | |
| arg | شماره ترتیب آرگومان، برای اولین آرگومان از 0 استفاده کنید. | |
| index | شاخص، در صورتی که arg به یک آرایه اشاره کند. | |
| برمی‌گرداند | مقدار آرگومان | |
| نکات: | این تابع یک آرگومان را از یک لیست آرگومان متغیر بازیابی می‌کند. وقتی آرگومان یک آرایه است، پارامتر index شاخص آرایه را مشخص می‌کند. مقدار برگشتی آرگومان بازیابی شده است. | |
| همچنین ببینید | numargs، setarg |
| heapspace | فضای آزاد هیپ را برمی‌گرداند | |
|---|---|---|
| نحو | heapspace() | |
| برمی‌گرداند | فضای آزاد روی هیپ. پشته و هیپ یک فضای حافظه مشترک را اشغال می‌کنند، بنابراین این مقدار تعداد بایت‌هایی را نشان می‌دهد که برای پشته یا هیپ باقی مانده است. | |
| نکات: | در صورت عدم وجود بازگشت، تجزیه‌کننده pawn همچنین می‌تواند تخمینی از فضای پشته/هیپ مورد نیاز ارائه دهد. |
| max | بزرگترین مقدار از بین دو عدد را برمی‌گرداند | |
|---|---|---|
| نحو | max(value1, value2) | |
| value1 | ||
| value2 | دو مقداری که می‌خواهید بزرگترین عدد را برای آنها پیدا کنید. | |
| برمی‌گرداند | مقدار بزرگتر از value1 و value2 | |
| همچنین ببینید | clamp، min |
| min | کوچکترین مقدار از بین دو عدد را برمی‌گرداند | |
|---|---|---|
| نحو | min(value1, value2) | |
| value1 | ||
| value2 | دو مقداری که می‌خواهید کوچکترین عدد را برای آنها پیدا کنید. | |
| برمی‌گرداند | مقدار کوچکتر از value1 و value2 | |
| همچنین ببینید | clamp، max |
| numargs | تعداد آرگومان‌ها را برمی‌گرداند | |
|---|---|---|
| نحو | numargs() | |
| برمی‌گرداند | تعداد آرگومان‌های ارسال شده به یک تابع؛ numargs در توابع با لیست آرگومان متغیر مفید است | |
| همچنین ببینید | getarg، setarg |
| random | یک عدد شبه-تصادفی را برمی‌گرداند | |
|---|---|---|
| نحو | random(max) | |
| max | محدودیت برای عدد تصادفی | |
| برمی‌گرداند | یک عدد شبه-تصادفی در محدوده 0 - max-1 | |
| نکات: | مولد عدد تصادفی استاندارد pawn احتمالاً یک مولد عدد شبه-تصادفی خطی هم‌نهشتی با محدوده و دوره 2³¹ است. مولدهای عدد شبه-تصادفی خطی هم‌نهشتی از همبستگی سریالی رنج می‌برند (به ویژه در بیت‌های پایین) و برای برنامه‌هایی که به اعداد تصادفی با کیفیت بالا نیاز دارند، مناسب نیستند. |
| setarg | ||
|---|---|---|
| نحو | setarg(arg, index=0, value) | |
| arg | شماره ترتیب آرگومان، برای اولین آرگومان از 0 استفاده کنید | |
| index | شاخص، در صورتی که arg به یک آرایه اشاره کند | |
| value | مقداری که آرگومان باید به آن تنظیم شود | |
| برمی‌گرداند | در صورت موفقیت true و در صورت نامعتبر بودن آرگومان یا شاخص، false | |
| نکات: | این تابع مقدار یک آرگومان را از یک لیست آرگومان متغیر تنظیم می‌کند. وقتی آرگومان یک آرایه است، پارامتر index شاخص آرایه را مشخص می‌کند. | |
| همچنین ببینید | getarg، numargs |
| swapchars | بایت‌ها را در یک cell جابجا می‌کند | |
|---|---|---|
| نحو | swapchars(c) | |
| c | مقداری که بایت‌های آن باید جابجا شوند | |
| برمی‌گرداند | مقداری که در آن بایت‌های پارامتر "c" جابجا شده‌اند (بایت پایین‌ترین تبدیل به بایت بالاترین می‌شود) |
| tolower | یک کاراکتر را به حروف کوچک تبدیل می‌کند | |
|---|---|---|
| نحو | tolower(c) | |
| c | کاراکتری که باید به حروف کوچک تبدیل شود. | |
| برمی‌گرداند | نسخه حروف بزرگ کاراکتر ورودی، اگر وجود داشته باشد، یا کد کاراکتر بدون تغییر "c" اگر حرف "c" معادل حروف کوچک نداشته باشد. | |
| نکات: | پشتیبانی از کاراکترهای اکسنت‌دار وابسته به پلتفرم است | |
| همچنین ببینید | toupper |
| toupper | یک کاراکتر را به حروف بزرگ تبدیل می‌کند | |
|---|---|---|
| نحو | toupper(c) | |
| c | کاراکتری که باید به حروف بزرگ تبدیل شود. | |
| برمی‌گرداند | نسخه حروف کوچک کاراکتر ورودی، اگر وجود داشته باشد، یا کد کاراکتر بدون تغییر "c" اگر حرف "c" معادل حروف بزرگ نداشته باشد. | |
| نکات: | پشتیبانی از کاراکترهای اکسنت‌دار وابسته به پلتفرم است | |
| همچنین ببینید | tolower |
خصوصیات، نام‌ها یا مقادیر با هدف عمومی هستند. روال‌های لیست خصوصیات یک لیست از این جفت‌های نام/مقدار را نگهداری می‌کنند که بین تمام ماشین‌های انتزاعی به اشتراک گذاشته می‌شود. بنابراین لیست خصوصیات راهی برای ماشین‌های انتزاعی همزمان برای تبادل اطلاعات است.
همه توابع "نگهداری خصوصیات" یک پارامتر اختیاری "id" دارند. می‌توانید از این پارامتر برای نشان دادن اینکه خصوصیت به کدام ماشین انتزاعی تعلق دارد، استفاده کنید. (یک برنامه میزبان که از ماشین‌های انتزاعی همزمان پشتیبانی می‌کند، معمولاً به هر ماشین انتزاعی یک شناسه منحصر به فرد می‌دهد.) هنگام پرس و جو (یا حذف) یک خصوصیت، مقدار id که وارد می‌کنید با مقادیر id لیست مطابقت داده می‌شود.
یک خصوصیت با "شناسه ماشین انتزاعی" آن به علاوه یک نام یا یک مقدار شناسایی می‌شود. رابط مبتنی بر نام به شما امکان می‌دهد یک مقدار (مثلاً دسته یک شیء) را به نامی به انتخاب خود متصل کنید. رابط مبتنی بر مقدار به شما امکان می‌دهد یک رشته را به یک عدد متصل کنید. تفاوت بین این دو اساساً کلید جستجو در مقابل پارامتر خروجی است.
همه توابع نگهداری خصوصیات یک پارامتر "name" و یک پارامتر "value" دارند. فقط یکی از این جفت باید پر شود. وقتی مقدار را می‌دهید، تابع getprop- erty نتیجه را در آرگومان رشته ذخیره می‌کند و تابع setproperty رشته را برای ذخیره از آرگومان رشته می‌خواند.
تعداد خصوصیاتی که می‌توانید اضافه کنید فقط توسط حافظه موجود محدود می‌شود.
getproperty(id=0, const name[]="", value=cellmin, string[]="")
هنگامی که نام وارد می‌شود، مقدار یک خصوصیت را برمی‌گرداند؛ هنگامی که مقدار وارد می‌شود، آرگومان رشته را پر می‌کند. رشته نام ممکن است یک رشته packed یا unpacked باشد. اگر خصوصیت وجود نداشته باشد، این تابع صفر برمی‌گرداند.
setproperty(id=0, const name[]="", value=cellmin, const string[]="")
یک خصوصیت جدید اضافه می‌کند یا یک خصوصیت موجود را تغییر می‌دهد.
deleteproperty(id=0, const name[]="", value=cellmin)
مقدار خصوصیت را برمی‌گرداند و سپس آن را حذف می‌کند. اگر خصوصیت وجود نداشته باشد، تابع صفر برمی‌گرداند.
existproperty(id=0, const name[]="", value=cellmin)
اگر خصوصیت وجود داشته باشد true و در غیر این صورت false برمی‌گرداند.
• توابع کنسول
برای اهداف آزمایشی، توابع کنسول که ورودی کاربر را می‌خوانند و رشته‌ها را در یک پنجره قابل اسکرول یا روی یک نمایشگر ترمینال استاندارد خروجی می‌دهند، اغلب مناسب هستند. همه انواع ترمینال و پیاده‌سازی‌ها ممکن است همه توابع را پیاده‌سازی نکنند —به ویژه توابعی که صفحه را پاک می‌کنند، رنگ‌های پیش‌زمینه و پس‌زمینه را تنظیم می‌کنند و موقعیت مکان‌نما را کنترل می‌کنند، به یک کنترل ترمینال گسترده نیاز دارند.
getchar(echo=true)
یک کاراکتر از صفحه کلید می‌خواند و آن را برمی‌گرداند. تابع می‌تواند به صورت اختیاری کاراکتر را در پنجره کنسول نمایش دهد.
getstring(string[], size=sizeof string, bool
pack=false): یک رشته از صفحه کلید می‌خواند. تابع getstring هنگامی که کلید enter فشرده شود یا حداکثر طول به دست آید، خواندن را متوقف می‌کند. حداکثر طول در cell ها (نه کاراکترها) است و شامل یک کاراکتر نول پایانی است. تابع می‌تواند هم رشته‌های packed و هم unpacked را بخواند؛ هنگام خواندن یک رشته packed، تابع ممکن است کاراکترهای بیشتری نسبت به آنچه پارامتر size مشخص می‌کند بخواند، زیرا هر cell چندین کاراکتر را نگه می‌دارد. مقدار برگشتی تعداد کاراکترهای خوانده شده، به استثنای کاراکتر نول پایانی است.
getvalue(base=10, end=' r', ...)
یک مقدار (یک عدد با علامت) از صفحه کلید می‌خواند. تابع getvalue به شما امکان می‌دهد یک مبنای عددی از 2 تا 36 (پارامتر base) با مبنای دهدهی به صورت پیش‌فرض بخوانید.
به طور پیش‌فرض ورودی هنگامی که کاربر کلید enter را فشار دهد پایان می‌یابد، اما یک یا چند کلید متفاوت ممکن است انتخاب شوند (پارامتر end و موارد بعدی). در لیست کلیدهای پایانی، یک عدد مثبت (مانند '\r') کلید را نمایش می‌دهد و ورودی را پایان می‌دهد، و یک عدد منفی ورودی را بدون نمایش کلید پایانی پایان می‌دهد.
print(const string[], foreground=-1, background=-1)
یک رشته ساده را روی کنسول چاپ می‌کند. رنگ‌های پیش‌زمینه و پس‌زمینه ممکن است به صورت اختیاری تنظیم شوند (اما توجه داشته باشید که یک ترمینال یا یک برنامه میزبان ممکن است از رنگ‌ها پشتیبانی نکند). برای لیست رنگ‌ها، setattr را در زیر ببینید.
printf(const format[], ...)
یک رشته با کدهای تعبیه شده چاپ می‌کند:
%b یک عدد را در این موقعیت در مبنای باینری چاپ می‌کند
%c یک کاراکتر در این موقعیت
%d یک عدد را در این موقعیت در مبنای دهدهی چاپ می‌کند
%f یک عدد نقطه شناور را در این موقعیت چاپ می‌کند (با فرض اینکه پشتیبانی نقطه شناور وجود داشته باشد)
%q یک عدد نقطه ثابت را در این موقعیت چاپ می‌کند (با فرض اینکه پشتیبانی نقطه ثابت وجود داشته باشد)
%r یا یک عدد نقطه شناور یا یک عدد نقطه ثابت را در این موقعیت چاپ می‌کند، بسته به آنچه در دسترس است؛ اگر هم پشتیبانی نقطه شناور و هم پشتیبانی نقطه ثابت وجود داشته باشد، %r معادل %f است (یعنی چاپ یک عدد نقطه شناور)
%s یک رشته کاراکتری را در این موقعیت چاپ می‌کند
%x یک عدد را در این موقعیت در مبنای هگزادسیمال چاپ می‌کند
تابع printf مشابه تابع printf زبان C کار می‌کند.
clrscr()
کنسول را پاک می‌کند و مکان‌نما را در گوشه بالا سمت چپ قرار می‌دهد.
clreol()
خطی را که مکان‌نما در آن قرار دارد، از موقعیت مکان‌نما تا حاشیه راست کنسول پاک می‌کند. این تابع مکان‌نما را حرکت نمی‌دهد.
gotoxy(x=1, y=1)
موقعیت مکان‌نما را روی کنسول تنظیم می‌کند. گوشه بالا سمت چپ در (1,1) است.
setattr(foreground=-1, background=-1)
رنگ‌های پیش‌زمینه و پس‌زمینه را برای متن نوشته شده روی کنسول تنظیم می‌کند. وقتی هر یک از دو پارامتر منفی باشد (یا حذف شود)، تنظیم رنگ مربوطه تغییر نخواهد کرد. مقدار رنگ باید مقداری بین صفر و هفت باشد، مطابق با دنباله‌های Escape ANSI، ISO 6429.
ثابت‌های از پیش تعریف شده برای رنگ‌ها عبارتند از سیاه (0)، قرمز (1)، سبز (2)، زرد (3)، آبی (4)، ارغوانی (5)، فیروزه‌ای (6) و سفید (7).
• توابع تاریخ/زمان
توابع برای دریافت و تنظیم تاریخ و زمان فعلی، و همچنین یک تایمر "رویداد" با دقت میلی‌ثانیه در یک یادداشت برنامه با عنوان "کتابخانه توابع زمان" که به صورت جداگانه در دسترس است، توضیح داده شده‌اند.
• ورودی/خروجی فایل
توابع برای مدیریت فایل‌های متنی و باینری، با پشتیبانی مستقیم از فایل‌های متنی UTF-8، در یک یادداشت برنامه با عنوان "کتابخانه پشتیبانی ورودی/خروجی فایل" که به صورت جداگانه در دسترس است، توضیح داده شده‌اند.
• محاسبات نقطه ثابت
ماژول محاسبات اعشاری نقطه ثابت برای pawn در یک یادداشت برنامه با عنوان "کتابخانه پشتیبانی نقطه ثابت" که به صورت جداگانه در دسترس است، توضیح داده شده است.
• محاسبات نقطه شناور
ماژول محاسبات نقطه شناور برای pawn در یک یادداشت برنامه با عنوان "کتابخانه پشتیبانی نقطه شناور" که به صورت جداگانه در دسترس است، توضیح داده شده است.
• دستکاری رشته
یک مجموعه عمومی از توابع دستکاری رشته، که هم روی رشته‌های packed و هم unpacked کار می‌کنند، در یک یادداشت برنامه با عنوان "کتابخانه دستکاری رشته" که به صورت جداگانه در دسترس است، توضیح داده شده است.
• رابط فراخوانی DLL
نسخه ماشین انتزاعی که به عنوان یک کتابخانه پیوند پویا برای Microsoft Windows ساخته شده است، یک تابع با هدف عمومی برای فراخوانی یک تابع از هر DLL در حافظه دارد. دو تابع همراه، یک DLL را از دیسک به حافظه بارگذاری می‌کنند و آن را تخلیه می‌کنند. توابع به گونه‌ای تنظیم شده‌اند که امکان اجرای همان اسکریپت کامپایل شده در هر دو نسخه 16 بیتی و 32 بیتی Microsoft Windows وجود دارد.
همه پارامترهای رشته ممکن است هم به فرم packed و هم unpacked باشند.
calldll(const dllname[], const function[], const typestr[], ...)
پارامتر dllname نام ماژول DLL است، معمولاً این همان نام فایل است. اگر DLL پیدا نشود، calldll دوباره تلاش می‌کند پس از افزودن "16" یا "32" به نام فایل، بسته به اینکه نسخه 16 بیتی یا 32 بیتی ماشین انتزاعی را اجرا می‌کنید. به عنوان مثال، اگر dllname را "USER" تنظیم کنید، calldll به USER در نسخه 16 بیتی ماشین انتزاعی و به USER32 در نسخه 32 بیتی متصل می‌شود.
پارامتر function نام تابع در DLL است. در نسخه 16 بیتی، این نام به بزرگی و کوچکی حروف حساس نیست، اما در نسخه 32 بیتی Microsoft Windows، نام‌های توابع صادر شده به بزرگی و کوچکی حروف حساس هستند. در نسخه 32 بیتی ماشین انتزاعی، اگر function پیدا نشود، calldll یک "A" بزرگ به نام اضافه می‌کند و دوباره تلاش می‌کند
—بسیاری از توابع در Windows 32 بیتی در دو نوع وجود دارند: ANSI و "Wide"، و این توابع به ترتیب با "A" یا "W" پسوند دارند. بنابراین اگر function "MessageBox" باشد، calldll MessageBox را در نسخه 16 بیتی Windows و MessageBoxA را در نسخه 32 بیتی فراخوانی می‌کند.
پارامتر رشته typestr تعداد آرگومان‌هایی را که تابع (در DLL) می‌گیرد و نوع آنها را نشان می‌دهد. برای هر آرگومان، یک حرف به رشته typestr اضافه می‌کنید:
h یک "handle" ویندوز (HWND، HDC، HPALETTE، HMEM و غیره)
i یک عدد صحیح با "اندازه بومی" (16 بیتی یا 32 بیتی، بسته به "بیتی بودن" ماشین انتزاعی).
l یک عدد صحیح 32 بیتی
p یک رشته packed
s یک رشته unpacked
w یک عدد صحیح 16 بیتی بدون علامت
وقتی حرف با حروف کوچک باشد، پارامتر مربوطه "با مقدار" منتقل می‌شود؛ وقتی با حروف بزرگ باشد، "با ارجاع" منتقل می‌شود. تفاوت بین رشته‌های packed و unpacked فقط زمانی مربوط است که پارامتر با ارجاع منتقل شود.
loaddll(const dllname[])
DLL مشخص شده را به حافظه بارگذاری می‌کند (یا شمارش استفاده آن را افزایش می‌دهد اگر قبلاً بارگذاری شده باشد). نام در پارامتر dllname ممکن است شامل یک مسیر کامل باشد. اگر هیچ مسیری مشخص نشده باشد، Microsoft Windows در دایرکتوری‌های سیستم خود برای DLL جستجو می‌کند. مشابه تابع calldll، این
تابع "16" یا "32" را به نام DLL اضافه می‌کند اگر DLL پیدا نشود، و سپس دوباره تلاش می‌کند.
freedll(const dllname[])
شمارش استفاده DLL را کاهش می‌دهد و اگر شمارش به صفر برسد، DLL را از حافظه حذف می‌کند. نام در پارامتر dllname ممکن است شامل یک مسیر کامل باشد، اما اطلاعات مسیر نادیده گرفته می‌شود. مشابه تابع calldll، این تابع "16" یا "32" را به نام DLL اضافه می‌کند اگر DLL پیدا نشود، و سپس دوباره تلاش می‌کند.
iswin32()
اگر ماشین انتزاعی نسخه 32 بیتی باشد (در حال اجرا در یک نسخه 32 بیتی از Microsoft Windows) true برمی‌گرداند؛ اگر ماشین انتزاعی نسخه 16 بیتی باشد (در حال اجرا در Windows 3.1x یا هر نسخه بعدی از Microsoft Windows) false برمی‌گرداند.
amx_Exec: به "راهنمای پیاده‌سازی کننده" مراجعه کنید