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

کدگذاری encoding

تبدیل متن و داده به پایه‌۶۴، شانزده‌شانزدهی و کدگذاری نشانی وب.

واردسازی کدگذاری

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

این بسته راه‌های رایج نوشتن بایت‌ها به شکل متن ساده را دارد: پایه‌۶۴ برای جا دادن داده‌ی دودویی در جیسون یا ایمیل، شانزده‌شانزدهی (هگز) برای نمایش بایت‌ها، و کدگذاری نشانی برای گذاشتن متن فارسی یا نویسه‌های خاص در نشانی وب.

قالب‌های بزرگ‌تر، مثل جیسون، یامل و اکس‌ام‌ال، زیربسته‌های خودشان را دارند که در همین گروه فهرست شده‌اند.

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

کدگذارها هیچ‌وقت شکست نمی‌خورند. کدگشاها، یعنی کدگشایی پایه۶۴، کدگشایی پایه۶۴ به بایت، کدگشایی شانزده و کدگشایی نشانی، خطادار هستند: با ورودی خراب یک خطا پرتاب می‌کنند که نوع آن نحو (نویسه‌ای که جایش آن‌جا نیست)، اتمام ناگهانی (متن وسط یک گروه، یک جفت یا یک گریز تمام شده) یا خارج از بازه (میان‌گیر کوچک است) است، همراه با جایگاه بایتی و خط و ستون مشکل.

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

  • کدگشایی داده‌ی دودویی به رشته. رشته در نخستین بایت صفر تمام می‌شود، پس کدگشایی پایه۶۴ و کدگشایی شانزده داده‌ی دودویی را ناقص برمی‌گردانند؛ کدگشایی پایه۶۴ به بایت را با یک میان‌گیر به کار ببرید.
  • فراموش کردن این‌که کدگشایی می‌تواند شکست بخورد. هر فراخوانی کدگشا تلاش می‌خواهد: درون بلوک تلاش: برای رسیدگی به خطا، یا پیش از فراخوانی در تابعی که خودش خطادار است تا خطا به بالا برود.
  • انتظار این‌که کدگشایی شانزده از فاصله یا پیشوند 0x بگذرد. این تابع برای هر بایت دقیقاً دو رقم هگز می‌خواند و چیز دیگری نمی‌پذیرد؛ جداکننده‌ها را اول بردارید.
  • کدگذاری نشانی فاصله را %20 می‌نویسد، ولی کدگشایی نشانی هم %20 و هم + را فاصله می‌خواند. %ای که دو رقم هگز پس از آن نیاید، مثل 50%، خطاست؛ آن را %25 بفرستید.

راهنما: سرآیند ورود پایه‌ی HTTP

احراز هویت پایه‌ی HTTP عبارت کاربر:گذرواژه را پس از واژه‌ی Basic به شکل پایه‌۶۴ می‌فرستد. پایه‌۶۴ رمزنگاری نیست و هر کسی می‌تواند آن را بگشاید، پس این روش فقط روی HTTPS جا دارد. ساختن سرآیند یک فراخوانی است؛ خواندنش در سمت کارساز یعنی گشودن با کدگشایی پایه۶۴ و جدا کردن در نخستین دونقطه، چون خود گذرواژه ممکن است دونقطه‌های دیگری داشته باشد.

encoding-guide-basic-auth.salam
واردسازی کدگذاری

تابع سرآیند پایه(کاربر: رشته، گذرواژه: رشته): رشته:
    برگشت "Basic " + کدگذاری.کدگذاری پایه۶۴(کاربر + ":" + گذرواژه)
پایان

تابع خواندن سرآیند(سرآیند: رشته، کاربر &: رشته، گذرواژه &: رشته): منطقی:
    اگر سرآیند.بیاب("Basic ") != ۰:
        برگشت نادرست
    پایان
    ناپایا جفت := ""
    تلاش:
        جفت = کدگذاری.کدگشایی پایه۶۴(سرآیند.زیررشته(۶، سرآیند.طول() - ۶))
    گرفتن خطا خ:
        سرچاپ "رد شد:"، خ.به رشته()
        برگشت نادرست
    پایان
    دونقطه := جفت.بیاب(":")
    اگر دونقطه < ۰:
        برگشت نادرست
    پایان
    کاربر = جفت.زیررشته(۰، دونقطه)
    گذرواژه = جفت.زیررشته(دونقطه + ۱، جفت.طول() - دونقطه - ۱)
    برگشت درست
پایان

تابع ریشه:
    س := سرآیند پایه("sara"، "p@ss:2026")
    سرچاپ "Authorization:"، س

    ناپایا کاربر := ""
    ناپایا گذرواژه := ""
    اگر خواندن سرآیند(س، کاربر، گذرواژه):
        سرچاپ "کاربر:"، کاربر
        سرچاپ "گذرواژه:"، گذرواژه
    پایان
    سرچاپ "سرآیند خراب پذیرفته شد:"، خواندن سرآیند("Basic !!not-base64!!"، کاربر، گذرواژه)
پایان
خروجیAuthorization: Basic c2FyYTpwQHNzOjIwMjY= کاربر: sara گذرواژه: p@ss:2026 رد شد: base64: invalid character '!' (line 1, column 1) سرآیند خراب پذیرفته شد: false

کدگشایی پایه۶۴ وقتی متن پایه‌۶۴ معتبر نباشد خطا پرتاب می‌کند، پس سرآیند خراب رد می‌شود و به یک نام کاربری بی‌معنی تبدیل نمی‌شود.

راهنما: کدگشای پایه‌۶۴ چه می‌پذیرد

کدگشایی پایه۶۴ شکل‌هایی را که پایه‌۶۴ در عمل دارد می‌پذیرد: با پرکننده یا بی آن، با الفبای استاندارد (+ و /) یا الفبای امن برای نشانی (- و _)، و فاصله، تب و شکستن خط در هر جا، چون پرونده‌های MIME و PEM پایه‌۶۴ را در ۷۶ یا ۶۴ نویسه می‌شکنند. هر چیز دیگری خطاست، پس یک غلط تایپی هیچ‌وقت به بایت‌های خراب تبدیل نمی‌شود.

encoding-guide-strict.salam
واردسازی کدگذاری

تابع بررسی(برچسب: رشته، متن: رشته):
    تلاش:
        سرچاپ برچسب، "درست:"، کدگذاری.کدگشایی پایه۶۴(متن)
    گرفتن خطا خ:
        سرچاپ برچسب، "رد شد:"، خ.نام نوع()، "در ستون"، خ.ستون
    پایان
پایان

تابع ریشه:
    بررسی("با پرکننده  "، "U2FsYW0=")
    بررسی("بی پرکننده  "، "U2FsYW0")
    بررسی("شکسته در خط"، "U2Fs\nYW0=")
    بررسی("نشانی‌امن   "، "Pz8_")
    بررسی("فارسی       "، کدگذاری.کدگذاری پایه۶۴("سلام"))
    بررسی("غلط تایپی   "، "U2Fs*W0=")
    بررسی("نیمه‌کاره    "، "U2FsY")
    بررسی("= اضافه     "، "U2E===")
پایان
خروجیبا پرکننده درست: Salam بی پرکننده درست: Salam شکسته در خط درست: Salam نشانی‌امن درست: ??? فارسی درست: سلام غلط تایپی رد شد: syntax error در ستون 5 نیمه‌کاره رد شد: unexpected end of input در ستون 6 = اضافه رد شد: syntax error در ستون 5

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

راهنما: دیدن بایت‌ها با شانزده‌شانزدهی

شانزده‌شانزدهی هر بایت را با دو رقم می‌نویسد و ساده‌ترین راه برای دیدن محتوای واقعی یک رشته است. حروف فارسی در UTF-8 هر کدام دو بایت‌اند، پس طول یک واژه‌ی فارسی تعداد بایت‌ها را می‌شمارد، نه حروف را. شانزده‌شانزدهی شکل رایج نوشتن چکیده‌ها، کلیدها و رنگ‌ها هم هست.

encoding-guide-hex.salam
واردسازی کدگذاری

تابع ریشه:
    واژه‌ها := ["A"، "é"، "س"، "سلام"]
    هر واژه در واژه‌ها:
        سرچاپ واژه، "برابر"، واژه.طول()، "بایت است:"، کدگذاری.کدگذاری شانزده(واژه)
    پایان

    ذخیره := "d8b3d984d8a7d985"
    تلاش:
        سرچاپ "کدگشایی‌شده:"، کدگذاری.کدگشایی شانزده(ذخیره)
        سرچاپ "حروف بزرگ هم کار می‌کند:"، کدگذاری.کدگشایی شانزده("D8B3D984D8A7D985")
        سرچاپ کدگذاری.کدگشایی شانزده("d8b3d")
    گرفتن خطا خ:
        سرچاپ "خطا:"، خ.به رشته()
    پایان
پایان
خروجیA برابر 1 بایت است: 41 é برابر 2 بایت است: c3a9 س برابر 2 بایت است: d8b3 سلام برابر 8 بایت است: d8b3d984d8a7d985 کدگشایی‌شده: سلام حروف بزرگ هم کار می‌کند: سلام خطا: hex: odd number of hex digits (line 1, column 6)

کدگذاری شانزده با حروف کوچک می‌نویسد و کدگشایی شانزده هر دو شکل را می‌خواند و با تعداد فرد رقم یا نویسه‌ای که رقم هگز نیست خطا پرتاب می‌کند.

راهنما: گذاشتن متن در نشانی

مقدار یک پرسش در نشانی نمی‌تواند فاصله، &، = یا حروف غیر اَسکی را همان‌طور که هستند داشته باشد. کدگذاری نشانی همه چیز را جز حروف، ارقام و - _ . ~ می‌گریزاند، پس نتیجه در هر جای نشانی بی‌خطر است. کدگشایی نشانی کار را برمی‌گرداند و + را هم مثل فرم‌های HTML فاصله می‌خواند؛ گریز خرابی مثل 50%off آن را به پرتاب خطا وا می‌دارد.

encoding-guide-url.salam
واردسازی کدگذاری

تابع پیوند(پایه: رشته، پرسش: رشته، شهر: رشته): رشته:
    برگشت پایه + "?q=" + کدگذاری.کدگذاری نشانی(پرسش) + "&city=" + کدگذاری.کدگذاری نشانی(شهر)
پایان

تابع ریشه:
    نشانی := پیوند("https://example.com/search"، "coffee & cake"، "تهران")
    سرچاپ نشانی

    تلاش:
        تکه := "coffee%20%26%20cake"
        سرچاپ "q برابر است با"، کدگذاری.کدگشایی نشانی(تکه)
        سرچاپ "به‌علاوه یعنی فاصله:"، کدگذاری.کدگشایی نشانی("tea+time")
        سرچاپ "رفت و برگشت:"، کدگذاری.کدگشایی نشانی(کدگذاری.کدگذاری نشانی("a/b?c=d")) == "a/b?c=d"
        سرچاپ کدگذاری.کدگشایی نشانی("50%off")
    گرفتن خطا خ:
        سرچاپ "خطا:"، خ.به رشته()
    پایان
پایان
خروجیhttps://example.com/search?q=coffee%20%26%20cake&city=%D8%AA%D9%87%D8%B1%D8%A7%D9%86 q برابر است با coffee & cake به‌علاوه یعنی فاصله: tea time رفت و برگشت: true خطا: url: malformed percent escape (line 1, column 3)

هر مقدار را جدا کدگذاری کنید و با & به هم بچسبانید، همان‌طور که پیوند می‌کند: کدگذاری کل نشانی یک‌جا ? و & را هم که ساختار نشانی‌اند می‌گریزاند. برای رشته‌های پرسش کامل با کلیدهای تکراری بسته‌ی پرس‌وجو حساب‌وکتاب را انجام می‌دهد و بسته‌ی نشانی وب نشانی‌های کامل را تجزیه می‌کند و دوباره می‌سازد.

کدام کدگذاری برای کدام کار

کاربه کار ببرید
داده‌ی دودویی درون جیسون، ایمیل یا سرآیندکدگذاری پایه۶۴، کدگذاری بایت‌ها پایه۶۴
خواندن پایه‌۶۴ از کاربر یا پروندهکدگشایی پایه۶۴، کدگشایی پایه۶۴ به بایت
چکیده‌ها، کلیدها، خروجی اشکال‌زداییکدگذاری شانزده، کدگشایی شانزده
یک مقدار در مسیر یا پرسش نشانیکدگذاری نشانی، کدگشایی نشانی

تابع‌ها

کدگذاری پایه۶۴ Base64Encode

تابع کدگذاری پایه۶۴(data: رشته): رشته
متن را به پایه‌۶۴ استاندارد (با = در انتها) تبدیل می‌کند.
encoding-Base64.salam
واردسازی کدگذاری
واردسازی حافظه

تابع ریشه:
    ک := کدگذاری.کدگذاری پایه۶۴("سلام دنیا")
    سرچاپ ک
    ب := حافظه.تخصیص(۳ برگردان طبیعی۶۴)
    حافظه.تنظیم(ب، ۲۵۵، ۳ برگردان طبیعی۶۴)
    سرچاپ کدگذاری.کدگذاری بایت‌ها پایه۶۴(ب، ۳)
    خروجی := حافظه.تخصیص(۸ برگردان طبیعی۶۴)
    تلاش:
        سرچاپ کدگذاری.کدگشایی پایه۶۴(ک)
        سرچاپ کدگذاری.کدگشایی پایه۶۴("YWJj")، کدگذاری.کدگشایی پایه۶۴("YQ")، کدگذاری.کدگشایی پایه۶۴("Pz8_")
        سرچاپ کدگذاری.کدگشایی پایه۶۴ به بایت("AAEC"، خروجی، ۸)
        سرچاپ کدگذاری.کدگشایی پایه۶۴("***")
    گرفتن خطا خ:
        سرچاپ خ.نام نوع() + ": " + خ.به رشته()
    پایان
    تلاش:
        _ := کدگذاری.کدگشایی پایه۶۴ به بایت("AAECAwQF"، خروجی، ۴)
    گرفتن خطا خ:
        سرچاپ خ.به رشته()
    پایان
    حافظه.آزادسازی(ب)
    حافظه.آزادسازی(خروجی)
پایان
خروجی2LPZhNin2YUg2K/ZhtuM2Kc= //// سلام دنیا abc a ??? 3 syntax error: base64: invalid character '*' (line 1, column 1) base64: decoded data needs 6 bytes but the buffer holds 4

کدگذاری بایت‌ها پایه۶۴ Base64EncodeBytes

تابع کدگذاری بایت‌ها پایه۶۴(data: تهی*، n: صحیح): رشته
n بایت از حافظه را به پایه‌۶۴ تبدیل می‌کند.

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

کدگشایی پایه۶۴ Base64Decode

تابع کدگشایی پایه۶۴(s: رشته): Throws<رشته>
پایه‌۶۴ را به متن برمی‌گرداند. هر دو الفبای استاندارد (+/) و امن برای نشانی (-_) خوانده می‌شوند، پرکننده اختیاری است و فاصله نادیده گرفته می‌شود. برای هر نویسه‌ی دیگر، داده پس از پرکننده‌ی = یا پرکننده‌ی بیش از اندازه نحو پرتاب می‌کند، و وقتی متن یک نویسه پس از شروع گروه تمام شود یا یک = کم داشته باشد اتمام ناگهانی؛ خطا جایگاه، خط و ستون را دارد.

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

کدگذاری شانزده HexEncode

تابع کدگذاری شانزده(data: رشته): رشته
هر بایت متن را با دو رقم شانزده‌شانزدهی کوچک می‌نویسد.
encoding-Hex.salam
واردسازی کدگذاری

تابع ریشه:
    ش := کدگذاری.کدگذاری شانزده("Hi!")
    سرچاپ کدگذاری.مقدار شانزده("f")، کدگذاری.مقدار شانزده("A")، کدگذاری.مقدار شانزده("z")
    ن := کدگذاری.کدگذاری نشانی("نام=علی & سن=۳۰")
    سرچاپ ن
    تلاش:
        سرچاپ ش، کدگذاری.کدگشایی شانزده(ش)
        سرچاپ کدگذاری.کدگشایی نشانی(ن)
        سرچاپ کدگذاری.کدگشایی شانزده("4869z1")
    گرفتن خطا خ:
        سرچاپ خ.به رشته()
    پایان
    تلاش:
        سرچاپ کدگذاری.کدگشایی نشانی("100%")
    گرفتن خطا خ:
        سرچاپ خ.به رشته()
    پایان
پایان
خروجی15 10 -1 %D9%86%D8%A7%D9%85%3D%D8%B9%D9%84%DB%8C%20%26%20%D8%B3%D9%86%3D%DB%B3%DB%B0 486921 Hi! نام=علی & سن=۳۰ hex: invalid character 'z' (line 1, column 5) url: incomplete percent escape (line 1, column 4)

مقدار شانزده HexVal

تابع مقدار شانزده(c: رشته): صحیح
مقدار نخستین نویسه به‌عنوان یک رقم شانزده‌شانزدهی، یا ‎-1 اگر رقم نباشد.

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

کدگشایی شانزده HexDecode

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

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

کدگذاری نشانی URLEncode

تابع کدگذاری نشانی(s: رشته): رشته
متن را بایت‌به‌بایت با هگز حروف بزرگ برای نشانی وب درصدی‌کدگذاری می‌کند؛ حروف و رقم‌های لاتین و -_.~ دست‌نخورده می‌مانند و فاصله %20 می‌شود.

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

کدگشایی نشانی URLDecode

تابع کدگشایی نشانی(s: رشته): Throws<رشته>
کدگذاری درصدی را برمی‌گرداند و + را فاصله می‌کند. وقتی پس از % دو رقم هگز نیاید نحو و وقتی متن وسط یک گریز تمام شود اتمام ناگهانی پرتاب می‌کند.

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

کدگشایی پایه۶۴ به بایت Base64DecodeBytes

تابع کدگشایی پایه۶۴ به بایت(s: رشته، out: تهی*، cap: صحیح): Throws<صحیح>
پایه‌۶۴ را، همان‌طور که کدگشایی پایه۶۴ می‌خواند، در حافظه‌ی out با ظرفیت cap کدگشایی می‌کند و تعداد بایت‌های نوشته‌شده را برمی‌گرداند. همان خطاهای کدگشایی پایه۶۴ را پرتاب می‌کند، و وقتی داده بیش از cap بایت لازم داشته باشد خارج از بازه.

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