کتابخانه‌ی استاندارد · کدگذاری و داده

مقدار `encoding/value`

مقدار پویا برای داده‌ای که شکلش را از پیش نمی‌دانید؛ زبان مشترک همه‌ی قالب‌های این گروه.

واردسازی کدگذاری.مقدار

در این صفحه

راهنما: پیمودن کل یک سند
راهنما: ساختن بار با فیلدهای اختیاری
راهنما: تغییر یک فیلد تودرتو
راهنما: ادغام عمیق تنظیم‌ها
راهنما: رونوشت، تبدیل و کلید نبوده
گونه‌ها
پایاها و متغیرها
تابع‌ها

مقدار نوع داده‌ی پویایی است که بسته‌های کدگذاری با هم به کار می‌برند. هر مقدار یکی از این‌هاست: تهی، منطقی، صحیح ۶۴ بیتی، اعشاری، رشته، آرایه‌ای از مقدارها یا شیئی که رشته‌ها را به مقدارها نگاشت می‌کند؛ فیلد kind می‌گوید کدام. جیسون، یامل، تامل، مسج‌پک و بسته‌های دیگر به آن کدگشایی می‌کنند و از آن کدگذاری می‌کنند، و تبدیل قالب قالب‌ها را از راه همین نوع به هم تبدیل می‌کند.

وقتی شکل داده هنگام نوشتن برنامه معلوم نیست سراغ مقدار بروید: بار یک وب‌هوک، پیکربندی‌ای با بخش‌های اختیاری، یا سندی که فقط از دستتان رد می‌شود. وقتی شکل داده ثابت است، کدگشایی مستقیم در یک ساختار (مثلاً با جیسون.واسریال سازی) کوتاه‌تر است و نوع‌ها را هم برایتان بررسی می‌کند.

تابع‌ها در چهار دسته

کار	تابع‌ها
ساختن مقدار	`مقدار تهی`، `مقدار منطقی`، `مقدار صحیح`، `مقدار اعشاری`، `مقدار رشته`، `آرایه جدید`، `شیء جدید`
پرسیدن نوع	`تهی است`، `منطقی است`، `صحیح است`، `اعشاری است`، `عدد است`، `رشته است`، `آرایه است`، `شیء است`
خواندن	`به منطقی`، `به صحیح`، `به اعشاری`، `به رشته`، `طول آرایه`، `عضو آرایه`، `مقدار کلید`، `مقدار کلید با وضعیت`، `شیء دارد`، `کلیدهای شیء`
تغییر دادن	`افزودن به آرایه`، `تنظیم عضو آرایه`، `تنظیم کلید`، `حذف کلید`، `رونوشت مقدار`، `آزادسازی مقدار`

اشتباه‌های رایج

خواندن هیچ‌وقت نوع را بررسی نمی‌کند. به رشته برای یک عدد "" می‌دهد و به صحیح برای یک رشته صفر. وقتی داده از بیرون می‌آید، اول با رشته است یا عدد است بپرسید.
نبودن یعنی تهی، تا هر عمقی. مقدار کلید برای کلید نبوده، یا برای چیزی که شیء نیست، تهی برمی‌گرداند؛ پس زنجیره‌ای مثل مقدار کلید(مقدار کلید(سند، "a")، "b") بی‌خطر است. عضو آرایه این‌طور نیست: شماره‌ای بیرون از طول آرایه برنامه را متوقف می‌کند.
رونوشت‌ها در بخش‌هایی مشترک‌اند. رونوشت یک شیء نگاشتش را با اصل شریک است، پس تنظیم کلید روی رونوشت اصل را هم عوض می‌کند. رونوشت یک آرایه عضوها را شریک است ولی طول را نه، پس افزودن به آرایه روی آرایه‌ای که از مقدار کلید گرفته‌اید تا وقتی آن را با تنظیم کلید برنگردانید گم می‌شود. برای رونوشت واقعی رونوشت مقدار را به کار ببرید.
ترتیب کلیدها به روش ساخت شیء بستگی دارد. کلیدهای شیء کلیدها را به ترتیبی برمی‌گرداند که با تنظیم کلید افزوده شده‌اند، و برای سند کدگشایی‌شده به ترتیب متن آن. شیئی که مقدار شیء از روی یک نگاشت ساخته، به ترتیب خود آن نگاشت می‌آید. اگر خروجی باید الفبایی باشد، کلیدها را مرتب کنید یا با چیدن کلیدها کدگذاری کنید.

راهنما: پیمودن کل یک سند

یک تابع بازگشتی روی مقدار از پس هر شکلی برمی‌آید: برای شیء هر کلید را می‌بیند، برای آرایه هر شماره را، و هر چیز دیگر یک برگ است. این تابع مسیر هر برگ را چاپ می‌کند؛ کاربردی برای ثبت بار یک وب‌هوک در گزارش یا مقایسه‌ی سطربه‌سطر دو سند.

encoding-value-guide-walk.salam

واردسازی کدگذاری.مقدار
واردسازی کدگذاری.جیسون
واردسازی کدگذاری.خطای کدگذاری
واردسازی مرتب سازی
واردسازی رشته

تابع پیمودن(م: مقدار.مقدار، مسیر: رشته):
    اگر مقدار.شیء است(م):
        کلیدها := مقدار.کلیدهای شیء(م)
        مرتب سازی.مرتب سازی سریع(کلیدها)
        هر ک در کلیدها:
            پیمودن(مقدار.مقدار کلید(م، ک)، مسیر + "." + ک)
        پایان
    وگرنه مقدار.آرایه است(م):
        تکرار مقدار.طول آرایه(م) در ای:
            پیمودن(مقدار.عضو آرایه(م، ای)، مسیر + "[" + رشته.از عدد(ای) + "]")
        پایان
    وگرنه:
        سرچاپ مسیر، "="، مقدار.رشته اشکال زدایی(م)
    پایان
پایان

تابع ریشه:
    ناپایا خطا := خطای کدگذاری.بدون خطا()
    سند := جیسون.کدگشایی(`{"order": 1042, "customer": {"name": "Sara", "vip": true}, "lines": [{"sku": "BK-01", "qty": 2}, {"sku": "PN-07", "qty": 1}], "note": null}`، خطا)
    پیمودن(سند، "$")
پایان

خروجی$.customer.name = string(Sara) $.customer.vip = bool(true) $.lines[0].qty = int(2) $.lines[0].sku = string(BK-01) $.lines[1].qty = int(1) $.lines[1].sku = string(PN-07) $.note = null $.order = int(1042)

کلیدهای شیء کلیدها را به ترتیب افزوده شدن برمی‌گرداند، پس سند کدگشایی‌شده ترتیب متن خود را نگه می‌دارد. این برنامه آن‌ها را با مرتب سازی.مرتب سازی سریع مرتب می‌کند تا هر ورودی با ترتیب الفبایی چاپ شود. رشته اشکال زدایی هر برگ را همراه نوعش نشان می‌دهد.

راهنما: ساختن بار با فیلدهای اختیاری

یک ساختار همیشه همه‌ی فیلدهایش را می‌نویسد. وقتی برخی فیلدها باید فقط در صورت داشتن مقدار بیایند، همان‌طور که بسیاری از APIهای HTTP انتظار دارند، به جای ساختار یک شیء مقدار بسازید و فقط آنچه دارید را تنظیم کنید. جیسون.کدگذاری با چیدن کلیدها آن را به ترتیبی پایدار چاپ می‌کند.

encoding-value-guide-build.salam

واردسازی کدگذاری.مقدار
واردسازی کدگذاری.جیسون

تابع بار(نام: رشته، رایانامه: رشته، سن: صحیح، برچسب‌ها: وکتور<رشته>): مقدار.مقدار:
    ناپایا م := مقدار.شیء جدید()
    مقدار.تنظیم کلید(م، "name"، مقدار.مقدار رشته(نام))
    اگر رایانامه != "":
        مقدار.تنظیم کلید(م، "email"، مقدار.مقدار رشته(رایانامه))
    پایان
    اگر سن > ۰:
        مقدار.تنظیم کلید(م، "age"، مقدار.مقدار صحیح(سن))
    پایان
    اگر برچسب‌ها.طول() > ۰:
        ناپایا آرایه := مقدار.آرایه جدید()
        هر ب در برچسب‌ها:
            مقدار.افزودن به آرایه(آرایه، مقدار.مقدار رشته(ب))
        پایان
        مقدار.تنظیم کلید(م، "tags"، آرایه)
    پایان
    برگشت م
پایان

تابع ریشه:
    گزینه‌ها := جیسون.گزینه‌های جیسون { چیدن کلیدها = درست }
    ناپایا برچسب‌ها := وکتور {} برگردان وکتور<رشته>
    سرچاپ جیسون.کدگذاری(بار("Sara"، ""، ۰، برچسب‌ها)، گزینه‌ها)
    برچسب‌ها.بیفزا("beta")
    برچسب‌ها.بیفزا("vip")
    سرچاپ جیسون.کدگذاری(بار("Reza"، "[email protected]"، ۴۱، برچسب‌ها)، گزینه‌ها)
پایان

خروجی{"name": "Sara"} {"age": 41, "email": "[email protected]", "name": "Reza", "tags": ["beta", "vip"]}

راهنما: تغییر یک فیلد تودرتو

برای تغییر چیزی در عمق یک سند کدگشایی‌شده، بخش درونی را با مقدار کلید بگیرید، تغییرش دهید و با تنظیم کلید سر جایش بگذارید. برای شیء‌ها این برگرداندن به‌طور دقیق لازم نیست، چون نگاشت مشترک است، ولی برای آرایه‌ها لازم است: برنامه‌ی زیر نشان می‌دهد قلم تازه‌ی سفارش تا وقتی آرایه برنگردد دیده نمی‌شود.

encoding-value-guide-edit.salam

واردسازی کدگذاری.مقدار
واردسازی کدگذاری.جیسون
واردسازی کدگذاری.خطای کدگذاری

تابع قلم(کد کالا: رشته، تعداد: صحیح): مقدار.مقدار:
    ناپایا ق := مقدار.شیء جدید()
    مقدار.تنظیم کلید(ق، "sku"، مقدار.مقدار رشته(کد کالا))
    مقدار.تنظیم کلید(ق، "qty"، مقدار.مقدار صحیح(تعداد))
    برگشت ق
پایان

تابع ریشه:
    ناپایا خطا := خطای کدگذاری.بدون خطا()
    ناپایا سفارش := جیسون.کدگشایی(`{"id": 1042, "customer": {"name": "Sara"}, "lines": [{"sku": "BK-01", "qty": 2}]}`، خطا)

    ناپایا مشتری := مقدار.مقدار کلید(سفارش، "customer")
    مقدار.تنظیم کلید(مشتری، "tier"، مقدار.مقدار رشته("gold"))

    ناپایا قلم‌ها := مقدار.مقدار کلید(سفارش، "lines")
    مقدار.افزودن به آرایه(قلم‌ها، قلم("PN-07"، ۱))
    سرچاپ "پیش از تنظیم کلید:"، مقدار.طول آرایه(مقدار.مقدار کلید(سفارش، "lines"))، "قلم"
    مقدار.تنظیم کلید(سفارش، "lines"، قلم‌ها)
    سرچاپ "پس از تنظیم کلید:"، مقدار.طول آرایه(مقدار.مقدار کلید(سفارش، "lines"))، "قلم"

    سرچاپ جیسون.کدگذاری(سفارش، جیسون.گزینه‌های جیسون { چیدن کلیدها = درست })

    شهر := مقدار.مقدار کلید(مقدار.مقدار کلید(سفارش، "shipping")، "city")
    سرچاپ "شهر ارسال داده شده:"، وارونه مقدار.تهی است(شهر)، "[" + مقدار.به رشته(شهر) + "]"
پایان

خروجیپیش از تنظیم کلید: 1 قلم پس از تنظیم کلید: 2 قلم {"customer": {"name": "Sara", "tier": "gold"}, "id": 1042, "lines": [{"qty": 2, "sku": "BK-01"}, {"qty": 1, "sku": "PN-07"}]} شهر ارسال داده شده: false []

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

راهنما: ادغام عمیق تنظیم‌ها

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

encoding-value-guide-merge.salam

واردسازی کدگذاری.مقدار
واردسازی کدگذاری.جیسون
واردسازی کدگذاری.خطای کدگذاری

تابع ادغام(پایه: مقدار.مقدار، رو: مقدار.مقدار): مقدار.مقدار:
    اگر وارونه مقدار.شیء است(پایه) یا وارونه مقدار.شیء است(رو):
        برگشت مقدار.رونوشت مقدار(رو)
    پایان
    ناپایا نتیجه := مقدار.رونوشت مقدار(پایه)
    هر ک در مقدار.کلیدهای شیء(رو):
        تازه := مقدار.مقدار کلید(رو، ک)
        اگر مقدار.شیء دارد(نتیجه، ک):
            مقدار.تنظیم کلید(نتیجه، ک، ادغام(مقدار.مقدار کلید(نتیجه، ک)، تازه))
        وگرنه:
            مقدار.تنظیم کلید(نتیجه، ک، مقدار.رونوشت مقدار(تازه))
        پایان
    پایان
    برگشت نتیجه
پایان

تابع ریشه:
    ناپایا خطا := خطای کدگذاری.بدون خطا()
    پیش فرض‌ها := جیسون.کدگشایی(`{"server": {"host": "0.0.0.0", "port": 8080}, "log": {"level": "info", "json": false}, "plugins": ["auth"]}`، خطا)
    پایگاه := جیسون.کدگشایی(`{"server": {"port": 9000}, "log": {"level": "debug"}, "plugins": ["auth", "cache"]}`، خطا)

    پیکر := ادغام(پیش فرض‌ها، پایگاه)
    سرچاپ جیسون.کدگذاری(پیکر، جیسون.گزینه‌های جیسون { تورفتگی = "  "، چیدن کلیدها = درست })
    سرچاپ "پیش‌فرض‌ها دست‌نخورده:"، مقدار.به صحیح(مقدار.مقدار کلید(مقدار.مقدار کلید(پیش فرض‌ها، "server")، "port"))
پایان

خروجی{ "log": { "json": false, "level": "debug" }, "plugins": [ "auth", "cache" ], "server": { "host": "0.0.0.0", "port": 9000 } } پیش‌فرض‌ها دست‌نخورده: 8080

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

راهنما: رونوشت، تبدیل و کلید نبوده

سپردن یک مقدار به متغیری تازه محتوایش را رونوشت نمی‌کند: فیلدهای یک شیء در نگاشتی مشترک‌اند، پس تغییر از راه رونوشت در اصل هم دیده می‌شود. هر وقت رونوشتی مستقل لازم دارید رونوشت مقدار را صدا بزنید و پس از کار با آزادسازی مقدار آزادش کنید. فقط مقدارهایی را آزاد کنید که چیز دیگری در آن‌ها شریک نیست، چون آزاد کردن یک رونوشت ساده نگاشت اصل را هم آزاد می‌کند.

encoding-value-guide-pitfalls.salam

واردسازی کدگذاری.مقدار

تابع ریشه:
    ناپایا الف := مقدار.شیء جدید()
    مقدار.تنظیم کلید(الف، "n"، مقدار.مقدار صحیح(۱))

    ناپایا مشترک := الف
    مقدار.تنظیم کلید(مشترک، "n"، مقدار.مقدار صحیح(۲))
    سرچاپ "پس از ویرایش رونوشت ساده:"، مقدار.به صحیح(مقدار.مقدار کلید(الف، "n"))

    ناپایا جدا := مقدار.رونوشت مقدار(الف)
    مقدار.تنظیم کلید(جدا، "n"، مقدار.مقدار صحیح(۳))
    سرچاپ "پس از ویرایش رونوشت کامل:"، مقدار.به صحیح(مقدار.مقدار کلید(الف، "n"))

    سرچاپ "به صحیح ۲.۹:"، مقدار.به صحیح(مقدار.مقدار اعشاری(۲.۹))
    سرچاپ "به اعشاری ۳:"، مقدار.به اعشاری(مقدار.مقدار صحیح(۳))
    سرچاپ "به صحیح \"5\":"، مقدار.به صحیح(مقدار.مقدار رشته("5"))
    سرچاپ "۱ با ۱.۰ یکسان است:"، مقدار.یکسان است(مقدار.مقدار صحیح(۱)، مقدار.مقدار اعشاری(۱.۰))

    ناپایا یافت شد := نادرست
    _ := مقدار.مقدار کلید با وضعیت(الف، "missing"، یافت شد)
    سرچاپ "کلید نبوده یافت شد:"، یافت شد

    مقدار.آزادسازی مقدار(جدا)
پایان

خروجیپس از ویرایش رونوشت ساده: 2 پس از ویرایش رونوشت کامل: 2 به صحیح ۲.۹: 2 به اعشاری ۳: 3 به صحیح "5": 0 ۱ با ۱.۰ یکسان است: false کلید نبوده یافت شد: false

به صحیح عدد اعشاری را رو به صفر می‌بُرد و به اعشاری عدد صحیح را گسترش می‌دهد، ولی هیچ‌کدام متن را تجزیه نمی‌کنند: رشته ۰ می‌دهد. اول نوع را با صحیح است، عدد است یا رشته است بررسی کنید.
یکسان است نوع‌ها را هم مقایسه می‌کند، پس عدد صحیح ۱ و اعشاری ۱.۰ دو مقدار متفاوت‌اند.
مقدار کلید برای کلید نبوده یک مقدار تهی می‌دهد؛ مقدار کلید با وضعیت افزون بر آن می‌گوید کلید بوده یا نه.

گونه‌ها

مقدار `Value`

ساختار مقدار

یک مقدار پویا: تهی، منطقی، صحیح، اعشاری، رشته، آرایه یا شیء.

نام	انگلیسی	گونه	توضیح
نوع	`kind`	`صحیح`	نوع مقدار؛ یکی از ثابت‌های `نوع`.
مقدار منطقی	`b`	`منطقی = نادرست`	مقدار منطقی.
مقدار صحیح	`i`	`صحیح۶۴ = 0`	مقدار صحیح.
مقدار اعشاری	`n`	`اعشار۶۴ = 0`	مقدار اعشاری.
مقدار رشته	`s`	`رشته = ""`	مقدار رشته.
عضوهای آرایه	`arr`	`وکتور<مقدار>`	عضوهای آرایه.
عضوهای شیء	`obj`	`نگاشت<رشته، مقدار>`	کلیدها و مقدارهای شیء.
ترتیب کلیدها	`order`	`صحیح۶۴ = 0`	دستگیره‌ی داخلی فهرستی که ترتیب افزوده شدن کلیدها به یک شیء با `تنظیم کلید` را ثبت می‌کند. `حذف کلید` آن را به‌روز نگه می‌دارد. مستقیم از آن استفاده نکنید؛ `کلیدهای شیء` آن را می‌خواند.

encoding-value-Value.salam

واردسازی کدگذاری.مقدار

تابع ریشه:
    ناپایا کاربر := مقدار.شیء جدید()
    مقدار.تنظیم کلید(کاربر، "name"، مقدار.مقدار رشته("نرگس"))
    مقدار.تنظیم کلید(کاربر، "age"، مقدار.مقدار صحیح(۳۴))
    مقدار.تنظیم کلید(کاربر، "height"، مقدار.مقدار اعشاری(۱.۶۸))
    مقدار.تنظیم کلید(کاربر، "admin"، مقدار.مقدار منطقی(نادرست))
    مقدار.تنظیم کلید(کاربر، "phone"، مقدار.مقدار تهی())
    ناپایا زبان‌ها := مقدار.آرایه جدید()
    مقدار.افزودن به آرایه(زبان‌ها، مقدار.مقدار رشته("fa"))
    مقدار.افزودن به آرایه(زبان‌ها، مقدار.مقدار رشته("en"))
    مقدار.تنظیم عضو آرایه(زبان‌ها، ۱، مقدار.مقدار رشته("ar"))
    مقدار.تنظیم کلید(کاربر، "langs"، زبان‌ها)
    سرچاپ مقدار.رشته اشکال زدایی(کاربر)
    سرچاپ مقدار.طول شیء(کاربر)، مقدار.شیء دارد(کاربر، "age")، مقدار.کلیدهای شیء(کاربر)
    سرچاپ مقدار.به رشته(مقدار.مقدار کلید(کاربر، "name"))، مقدار.به صحیح(مقدار.مقدار کلید(کاربر، "age"))، مقدار.به اعشاری(مقدار.مقدار کلید(کاربر، "height"))، مقدار.به منطقی(مقدار.مقدار کلید(کاربر، "admin"))
    ز := مقدار.مقدار کلید(کاربر، "langs")
    سرچاپ مقدار.آرایه است(ز)، مقدار.طول آرایه(ز)، مقدار.به رشته(مقدار.عضو آرایه(ز، ۱))
    ناپایا هست := نادرست
    _ := مقدار.مقدار کلید با وضعیت(کاربر، "email"، هست)
    سرچاپ هست
    ت := مقدار.مقدار کلید(کاربر، "phone")
    سرچاپ مقدار.تهی است(ت)، مقدار.منطقی است(ت)، مقدار.صحیح است(مقدار.مقدار صحیح(۱))، مقدار.اعشاری است(مقدار.مقدار اعشاری(۱.۰))، مقدار.عدد است(مقدار.مقدار صحیح(۱))
    سرچاپ مقدار.رشته است(مقدار.مقدار رشته(""))، مقدار.شیء است(کاربر)، ت.نوع == مقدار.نوع تهی، مقدار.نوع شیء
    ناپایا ک := مقدار.رونوشت مقدار(کاربر)
    سرچاپ مقدار.یکسان است(ک، کاربر)
    حذف شد := مقدار.حذف کلید(ک، "phone")
    سرچاپ حذف شد، مقدار.یکسان است(ک، کاربر)
    ناپایا عددها := وکتور {} برگردان وکتور<مقدار.مقدار>
    عددها.بیفزا(مقدار.مقدار صحیح(۱))
    ناپایا فیلدها := نگاشت {} برگردان نگاشت<رشته، مقدار.مقدار>
    فیلدها.درج("x"، مقدار.مقدار آرایه(عددها))
    سرچاپ مقدار.رشته اشکال زدایی(مقدار.مقدار شیء(فیلدها))
    مقدار.آزادسازی مقدار(ک)
پایان

خروجیobject{name: string(نرگس), age: int(34), height: float(1.68), admin: bool(false), phone: null, langs: array[string(fa), string(ar)]} 6 true ["name", "age", "height", "admin", "phone", "langs"] نرگس 34 1.68 false true 2 ar false true false true true true true true true 6 true true false object{x: array[int(1)]}