# Encoding — Base64, URL, HTML

> Encode and decode text — Base64, URL percent-encoding, and HTML escaping — with the C#-faithful spellings. `Convert.ToBase64String` / `FromBase64String` for binary, `Uri.EscapeDataString` / `UnescapeDataString` for URLs, `WebUtility.HtmlEncode` / `HtmlDecode` for HTML. All pure — no capability needed.

<!-- id: stdlib-encoding · area: stdlib · stability: stable · html: https://osysharp.com/reference/stdlib/encoding/ -->

## Summary        {#summary}
Three small encoding surfaces, spelled exactly as in C#, all **pure** (no capability, no `using` required):

```osy syntax
var b64  = Convert.ToBase64String(bytes);          // binary  → base64 text
var back = Convert.FromBase64String(b64);          // base64  → binary
var q    = Uri.EscapeDataString("a b&c");          // "a%20b%26c" — safe in a URL
var safe = WebUtility.HtmlEncode("<b>hi</b>");      // "&lt;b&gt;hi&lt;/b&gt;" — safe in HTML text
```

## Signature      {#signature}
```osy syntax
string  Convert.ToBase64String(byte[] bytes)     // Binary → base64 text
byte[]  Convert.FromBase64String(string s)       // base64 text → Binary
string  Uri.EscapeDataString(string s)           // percent-encode for a URL
string  Uri.UnescapeDataString(string s)         // reverse
string  WebUtility.HtmlEncode(string s)          // escape for HTML text
string  WebUtility.HtmlDecode(string s)          // reverse
```

## Description    {#description}
**Base64** — `Convert.ToBase64String` turns a `Binary` value (bytes, e.g. a file read via <span class="planned" title="this page is planned and not written yet">storage-file</span> or a
`Binary` property) into standard base64 text; `Convert.FromBase64String` reverses it. Use it to carry bytes inside a
JSON body or a text field.

**URL escaping** — `Uri.EscapeDataString` percent-encodes a string so it is safe inside a URL query value or path
segment (RFC 3986: a space becomes `%20`, `&` becomes `%26`, and so on). `Uri.UnescapeDataString` reverses it. Pair it
with [Http.*](https://osysharp.com/reference/http/facade/) when building a request URL from user input:

```osy syntax
var url = "https://api.example.com/search?q=" + Uri.EscapeDataString(term);
```

**HTML escaping** — `WebUtility.HtmlEncode` escapes `&`, `<`, `>`, `"` so a string is safe to place in HTML text
without injecting markup; `WebUtility.HtmlDecode` reverses it.

**Not yet available.** Raw UTF-8 byte conversion (`Encoding.UTF8.GetBytes` / `GetString`) is a planned follow-on —
Base64 already carries bytes as text, and JSON round-trips `byte[]` as base64 automatically. Ask for it when you need
raw UTF-8 bytes directly.

## Examples       {#examples}

Build a signed-looking token payload as base64:

```osy title="base64, round-tripped" test app=stdlib-encoding
string Encode(byte[] payload) {
  return Convert.ToBase64String(payload);
}

byte[] Decode(string base64) {
  return Convert.FromBase64String(base64);
}
```

Escape user input into an outbound request ([Http.*](https://osysharp.com/reference/http/facade/)):

```osy title="escaping user input into a URL" test app=stdlib-encoding
app Shop {
  model "model/**/*.osy";
  use Osysharp.Http;         // `use` is a MANIFEST declaration — it belongs in app.osy
}

string Search(string term) {
  var url = "https://api.example.com/search?q=" + Uri.EscapeDataString(term);
  var r = Http.Get(url);
  return r.Body;
}
```

Render user text safely into an HTML fragment:

```osy title="escaping user text into an HTML fragment" test app=stdlib-encoding
string Cell(string userText) {
  return "<td>" + WebUtility.HtmlEncode(userText) + "</td>";
}
```

## See also       {#see-also}
- [Uri](https://osysharp.com/reference/stdlib/uri/) — parse a URL into its parts (`new Uri(url).Host`)
- [Regex](https://osysharp.com/reference/stdlib/regex/) — pattern matching, replacing, and splitting text
- [Http.*](https://osysharp.com/reference/http/facade/) — the outbound HTTP surface these escapings feed