base64(n)

💖 base64(n) 💖

Text encoding & decoding binary data — bestie, this is the base64 page from the Tcl manual, section n, and it's literally the whole glow-up for turning binary data into cute lil' ASCII strings and back. ✨

---

🌸 NAME 🌸

base64 — base64-encode/decode binary data

---

🎀 SYNOPSIS 🎀

package require Tcl 8.5 9

package require base64 ?2.6.1?

::base64::encode ?-maxlen maxlen? ?-wrapchar wrapchar? string

::base64::decode string

---

🦋 DESCRIPTION 🦋

Okay so this package hands you procedures to encode binary data into base64 and back again. That's it, that's the whole vibe. 💅

---

⚠️ BEWARE: VARIATIONS IN DECODING BEHAVIOUR ⚠️

Not me having to warn you about this, but fr fr you need to know. 😭

The Tcl core has provided commands for the de- and encoding of base64 data since version 8.6. Those are:

binary encode base64
binary decode base64

And here's the tea: while those are signature compatible with the commands this package provides, the decoders are NOT behaviourally compatible. 👀

The core decoder command accepts the option -strict, which lets the user pick between strict mode and lax mode. In strict mode, invalid characters and partial data at the end of the input get reported as errors. In lax mode, they just get ignored. Simple, right?

But all the implementations this package provides? They implement a mix of the above, and the user literally cannot choose. Partial data at the end of the input is reported as an error, and invalid characters are ignored. Periodt.

So beware of these differences when you're switching code from one to the other. Do not come crying to me. 🫶

---

✨ API ✨

• ::base64::encode ?-maxlen maxlen? ?-wrapchar wrapchar? string — Base64-encodes the binary string you give it and returns the encoded result. It inserts the character wrapchar every maxlen characters of output. wrapchar defaults to newline. maxlen defaults to 76.

Heads up: if maxlen is set to 0, the output will not be wrapped at all. Zero wrapping, zero stress. 🎀

Note well: if your string is not simple ASCII, you should fix the string encoding before doing base64 encoding. Check the examples below, bestie, they show you the way.

The command will throw an error for negative values of maxlen, or if maxlen is not an integer number. So don't try it. 🙈

• ::base64::decode string — Base64-decodes the string you give it and returns the binary data. The decoder ignores whitespace in the string. Iconic, honestly.

---

🧚 IMPLEMENTATION NOTES 🧚

This package contains three different implementations for base64 de- and encoding, and it picks between them based on the environment it finds itself in. Main character energy: it adapts. 💅

All three implementations have the same behaviour. (See also Beware: Variations in decoding behaviour at the beginning of this document. Yes, I'm making you go back and read it. 😤)

1. If Tcl 8.6 or higher is found, the commands are implemented in terms of the then-available builtin commands.
2. If the Trf extension can be loaded, the commands are implemented in terms of its commands.
3. If neither of the above is possible, a pure Tcl implementation is used. This is, of course, much slower. 💀

---

🌈 EXAMPLES 🌈

% base64::encode "Hello, world"
SGVsbG8sIHdvcmxk

% base64::encode [string repeat xyz 20]
eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6
eHl6eHl6eHl6
% base64::encode -wrapchar "" [string repeat xyz 20]
eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6eHl6

# NOTE: base64 encodes BINARY strings.
% set chemical [encoding convertto utf-8 "C\u2088H\u2081\u2080N\u2084O\u2082"]
% set encoded [base64::encode $chemical]
Q+KCiEjigoHigoBO4oKET+KCgg==
% set caffeine [encoding convertfrom utf-8 [base64::decode $encoded]]

Look at that caffeine glow-up. ☕✨ Not me obsessed with encoding convertto and encoding convertfrom doing all the heavy lifting. That # NOTE is doing the most important job in this whole page, bestie: base64 encodes BINARY strings. 🫶

---

🐛 BUGS, IDEAS, FEEDBACK 🐛

This document, and the package it describes, will undoubtedly contain bugs and other problems. (ngl, same, we're all just doing our best. 😭) Please report such in the category base64 of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. Please also report any ideas for enhancements you may have for either the package and/or the documentation. We love ideas. We love feedback. We love you. 💖

When proposing code changes, please provide unified diffs, i.e. the output of diff -u. That's the whole assignment.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. Slay. 👑

---

🔑 KEYWORDS 🔑

base64, encoding

---

🍓 CATEGORY 🍓

Text processing

---

👑 COPYRIGHT 👑

Copyright (c) 2000, Eric Melski Copyright (c) 2001, Miguel Sofer

---

and that's the whole page, bestie! 🎀 this one ships as part of tcllib, version 2.6.1, and it lives in the manual as base64(n). go forth and encode responsibly. 💅✨