کتابخانه‌ی استاندارد · پایه

اختیاری option

مقداری که ممکن است باشد یا نباشد، بدون پوچ و بدون عددهای جادویی مثل منفی یک.

واردسازی اختیاری

نام آرگومان‌ها شناسه‌ی خود کد است و معادل فارسی ندارد؛ گونه‌ها، کلیدواژه‌ها و نام بسته‌ها با معادل فارسی نوشته می‌شوند.

گاهی جواب یک تابع «هیچ» است: جستجو چیزی پیدا نکرده یا تنظیمی تعریف نشده. برگرداندن منفی یک یا رشته‌ی تهی برای این حالت راحت است، اما بعداً فراموش می‌شود و باگ می‌سازد. اختیاری<T> این را صریح می‌کند: یا یک مقدار از گونه‌ی T دارد، یا ندارد.

اگر علاوه بر «نبودن»، دلیل شکست هم مهم است، نتیجه مناسب‌تر است.

برخلاف نتیجه، اختیاری یک ساختار ساده با دو فیلد value و present است، نه یک جداشمار. همین چند پیامد دارد:

  • آن را با دارد یا .present بررسی می‌کنید، نه با همخوان، و عملگر ? روی آن کار نمی‌کند.
  • هیچ‌وقت پیش از بررسی سراغ .value نروید. در اختیاری خالی، این فیلد مقدار صفر گونه‌ی T است: برای عدد صفر، ولی برای رشته یک اشاره‌گر پوچ که چاپ کردن یا گرفتن طولش برنامه را از کار می‌اندازد.
  • اختیاری را فقط با یک مقدار و هیچ مقدار بسازید تا دو فیلدش همیشه با هم جور باشند.

T؟ شکل کوتاه اختیاری.اختیاری<T> است و به واردسازی نیاز ندارد: فیلدی که مهلت: صحیح؟ نوشته شده را می‌شود در مقدار ساختاری ننوشت، مقدار ساده خودکار در آن قرار می‌گیرد و پوچ یعنی خالی. فیلدهای اختیاری را ببینید.

جست‌وجویی که ممکن است چیزی پیدا نکند

جست‌وجو نمونه‌ی کلاسیک کاربرد اختیاری است. برگرداندن رشته‌ی خالی برای شماره‌ی تلفنی که نیست دوپهلوست، چون ممکن است یک مقدار خالی عمداً ذخیره شده باشد. تابعی که اختیاری<رشته> برمی‌گرداند در خود امضایش روشن می‌گوید که جواب ممکن است نباشد، و هر صدازننده‌ای باید این را در نظر بگیرد.

option-guide-lookup.salam
واردسازی اختیاری

تابع شماره‌ی تلفن(دفترچه: نگاشت<رشته، رشته>، نام: رشته): اختیاری.اختیاری<رشته>:
    اگر دفترچه.دارد(نام):
        برگشت اختیاری.یک مقدار(دفترچه.بگیر(نام))
    پایان
    برگشت اختیاری.هیچ مقدار()
پایان

تابع ریشه:
    ناپایا دفترچه := نگاشت {} برگردان نگاشت<رشته، رشته>
    دیرکن دفترچه.آزادکن()
    دفترچه.درج("سارا"، "۰۹۱۲ ۱۱۱ ۲۲۳۳")
    دفترچه.درج("امید"، "۰۹۳۵ ۴۴۴ ۵۵۶۶")
    هر نام در ["امید"، "ندا"]:
        ت := شماره‌ی تلفن(دفترچه، نام)
        اگر اختیاری.دارد(ت):
            سرچاپ نام + ":"، ت.مقدار
        وگرنه:
            سرچاپ نام + ": شماره‌ای ثبت نشده"
        پایان
    پایان
    سرچاپ "تماس با"، اختیاری.یابرگردان(شماره‌ی تلفن(دفترچه، "ندا")، "پذیرش")
پایان
خروجیامید: ۰۹۳۵ ۴۴۴ ۵۵۶۶ ندا: شماره‌ای ثبت نشده تماس با پذیرش

دارد و پس از آن .value برای کدی مناسب است که در دو حالت دو کار متفاوت می‌کند. وقتی پیش‌فرض معقولی هست، یابرگردان بررسی و جایگزین را در یک فراخوانی انجام می‌دهد، همان‌طور که خط آخر نشان می‌دهد.

تنظیمات اختیاری با مقدار پیش‌فرض

فیلد اختیاری «داده نشده» را از صفرِ واقعی یا رشته‌ی خالی جدا می‌کند؛ کاری که از یک فیلد صحیح ساده برنمی‌آید. پیش‌فرض هر فیلد اختیاری را مقدار خالی بگذارید تا بشود آن را در ساختن ساختار ننوشت، و پیش‌فرض واقعی را همان‌جا که مقدار به کار می‌رود اعمال کنید.

option-guide-settings.salam
واردسازی اختیاری

ساختار تنظیمات:
    همگانی پهنا: اختیاری.اختیاری<صحیح> = اختیاری.هیچ مقدار() برگردان اختیاری.اختیاری<صحیح>
    همگانی عنوان: اختیاری.اختیاری<رشته> = اختیاری.هیچ مقدار() برگردان اختیاری.اختیاری<رشته>
پایان

تابع شرح(ت: تنظیمات): رشته:
    پ := اختیاری.یابرگردان(ت.پهنا، ۸۰)
    ع := اختیاری.یابرگردان(ت.عنوان، "بی‌نام")
    برگشت ع + " (" + پ + " ستون)"
پایان

تابع ریشه:
    سرچاپ شرح(تنظیمات {})
    سرچاپ شرح(تنظیمات { پهنا = اختیاری.یک مقدار(۱۲۰) })
    سرچاپ شرح(تنظیمات { پهنا = اختیاری.یک مقدار(۰)، عنوان = اختیاری.یک مقدار("گزارش") })
پایان
خروجیبی‌نام (80 ستون) بی‌نام (120 ستون) گزارش (0 ستون)

خط سوم نشان می‌دهد چرا این مهم است: پهنای صفر عمداً داده شده و همان می‌ماند، در حالی که دو خط اول به ۸۰ برمی‌گردند. پیش‌فرض فیلد باید گونه را صریح بنویسد، اختیاری.هیچ مقدار() برگردان اختیاری.اختیاری<صحیح>، چون در فیلد ساختار چیزی نیست که هیچ مقدار گونه‌اش را از آن بفهمد. درون بدنه‌ی تابع، نوع خروجی تابع این کار را می‌کند و همان اختیاری.هیچ مقدار() کافی است.

جست‌وجو در فهرستی از ساختارها

جست‌وجو در یک وکتور نخستین مورد پیداشده را برمی‌گرداند یا هیچ. این‌جا برنامه می‌داند که در آن لحظه حتماً یک کار باز هست، پس از انتظار استفاده می‌کند: اگر این فرض روزی غلط از آب درآید، برنامه با همان جمله می‌ایستد، نه این‌که با یک نام خالی ادامه دهد.

option-guide-first.salam
واردسازی اختیاری

ساختار کار:
    همگانی نام: رشته = ""
    همگانی انجام شده: منطقی = نادرست
پایان

تابع نخستین کار باز(کارها: وکتور<کار>): اختیاری.اختیاری<رشته>:
    هر ک در کارها:
        اگر وارونه ک.انجام شده:
            برگشت اختیاری.یک مقدار(ک.نام)
        پایان
    پایان
    برگشت اختیاری.هیچ مقدار()
پایان

تابع ریشه:
    ناپایا کارها := وکتور {} برگردان وکتور<کار>
    دیرکن کارها.آزادکن()
    کارها.بیفزا(کار { نام = "نوشتن آزمون‌ها"، انجام شده = درست })
    کارها.بیفزا(کار { نام = "رفع ایراد ورود" })
    کارها.بیفزا(کار { نام = "به‌روزرسانی راهنما" })
    بعدی := نخستین کار باز(کارها)
    سرچاپ "کار بعدی:"، اختیاری.انتظار(بعدی، "این‌جا همیشه یک کار باز هست")
    هر ش، ک در کارها:
        کارها.بنشان(ش، کار { نام = ک.نام، انجام شده = درست })
    پایان
    سرچاپ "کاری مانده؟"، اختیاری.دارد(نخستین کار باز(کارها))
پایان
خروجیکار بعدی: رفع ایراد ورود کاری مانده؟ false

اختیاری در این نمونه نام کار را نگه می‌دارد. اگر می‌خواهید خود کار را تغییر دهید، به‌جایش شماره‌ی خانه را به شکل اختیاری<صحیح> برگردانید و با کارها.بنشان بنویسید.

اختیاری یا نتیجه؟

وضعیتابزار
مقدار فقط وجود ندارد و این عادی استاختیاری
چیزی خراب شده و صدازننده باید بداند چه چیزینتیجه
نبودنش یعنی ایراد در برنامه‌ی شماانتظار با پیامی روشن
یک پیش‌فرض همیشه پذیرفتنی استیابرگردان

بازکن وقتی اختیاری خالی باشد با پیامی کلی می‌ایستد. انتظار بهتر است، چون پیامش به خواننده می‌گوید کدام فرض شکسته.

گونه‌ها

اختیاری Option

ساختار اختیاری<T>
ساختاری که یک مقدار و یک پرچم «هست یا نیست» را کنار هم نگه می‌دارد. آن را با یک مقدار یا هیچ مقدار بسازید تا دو فیلدش همیشه با هم جور باشند.
نامانگلیسیگونهتوضیح
مقدارvalueTخود مقدار. اگر present نادرست باشد، مقدار صفر گونه‌ی T است؛ برای رشته یعنی اشاره‌گری پوچ که به‌کار بردنش برنامه را از کار می‌اندازد، پس اول present را بررسی کنید.
موجودpresentمنطقیاگر مقداری در کار باشد، درست است.
option-Option.salam
واردسازی اختیاری

تابع جستجو(نام‌ها: وکتور<رشته>، دنبال: رشته): اختیاری.اختیاری<صحیح>:
    هر ش، ن در نام‌ها:
        اگر ن == دنبال:
            برگشت اختیاری.یک مقدار(ش)
        پایان
    پایان
    برگشت اختیاری.هیچ مقدار()
پایان

تابع ریشه:
    ناپایا نام‌ها := وکتور {} برگردان وکتور<رشته>
    دیرکن نام‌ها.آزادکن()
    نام‌ها.بیفزا("علی")
    نام‌ها.بیفزا("مریم")
    ی := جستجو(نام‌ها، "مریم")
    ن := جستجو(نام‌ها، "رضا")
    سرچاپ اختیاری.دارد(ی)، اختیاری.ندارد(ی)، ی.مقدار، ی.موجود
    سرچاپ اختیاری.دارد(ن)، اختیاری.ندارد(ن)
    سرچاپ اختیاری.بازکن(ی)، اختیاری.انتظار(ی، "باید پیدا می‌شد")
    سرچاپ اختیاری.یابرگردان(ن، -۱)
پایان
خروجیtrue false 1 true false true 1 1 -1

دارد is_some

تابع دارد(): منطقی
شکل روشی دارد: اگر مقداری در کار باشد، درست است.
option-Methods.salam
ساختار مشتری:
    همگانی مهلت: صحیح؟
پایان

تابع ریشه:
    الف := مشتری { }
    ب := مشتری { مهلت = ۳۰ }
    سرچاپ الف.مهلت.دارد()، الف.مهلت.ندارد()، الف.مهلت.یابرگردان(۵)
    سرچاپ ب.مهلت.دارد()، ب.مهلت.ندارد()، ب.مهلت.یابرگردان(۵)، ب.مهلت.بازکن()
پایان
خروجیfalse true 5 true false 30 30

ندارد is_none

تابع ندارد(): منطقی
شکل روشی ندارد: اگر خالی باشد، درست است.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: option-Methods.salam

یابرگردان unwrap_or

تابع یابرگردان(fallback: T): T
شکل روشی یابرگردان: مقدار، یا اگر خالی باشد، جایگزینی که داده‌اید.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: option-Methods.salam

بازکن unwrap

تابع بازکن(): T
شکل روشی بازکن: مقدار، یا اگر خالی باشد، خطای مرگبار.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: option-Methods.salam

تابع‌ها

یک مقدار Some

تابع یک مقدار<T>(x: T): اختیاری<T>
یک اختیاری می‌سازد که مقدار دارد.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: option-Option.salam

هیچ مقدار None

تابع هیچ مقدار<T>(): اختیاری<T>
یک اختیاری خالی می‌سازد. گونه‌ی T از جایی که مقدار به کار می‌رود، مثلاً گونه‌ی برگشتی تابع، معلوم می‌شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: option-Option.salam

دارد IsSome

تابع دارد<T>(o: اختیاری<T>): منطقی
اگر اختیاری مقدار داشته باشد، درست برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: option-Option.salam

ندارد IsNone

تابع ندارد<T>(o: اختیاری<T>): منطقی
اگر اختیاری خالی باشد، درست برمی‌گرداند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: option-Option.salam

یابرگردان UnwrapOr

تابع یابرگردان<T>(o: اختیاری<T>، fallback: T): T
مقدار را برمی‌گرداند، یا اگر خالی باشد، مقدار پیش‌فرضی که داده‌اید.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: option-Option.salam

بازکن Unwrap

تابع بازکن<T>(o: اختیاری<T>): T
مقدار را برمی‌گرداند. اگر اختیاری خالی باشد، برنامه با خطای مرگبار called Unwrap on a None value متوقف می‌شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: option-Option.salam

انتظار Expect

تابع انتظار<T>(o: اختیاری<T>، msg: رشته): T
مثل بازکن، ولی اگر خالی باشد با پیامی که خودتان داده‌اید متوقف می‌شود؛ پیام خوب، پیدا کردن مشکل را آسان می‌کند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: option-Option.salam