1 Introduction
1.1 Overview
std.lib.encode is part of the standard foundation library set. This page collects the public API reference for the namespace.
2 Walkthrough
2.1 Hexadecimal encoding
std.lib.encode converts byte arrays to hex strings and back. Use to-hex for the full string, to-hex-chars for a char array, and hex-chars for a single byte.
encode and decode hex
^{:refer std.lib.encode/to-hex :added "3.0"}
(to-hex (.getBytes "hello"))
=> "68656c6c6f"
^{:refer std.lib.encode/from-hex :added "3.0"}
(String. (from-hex "68656c6c6f"))
=> "hello"
^{:refer std.lib.encode/hex-chars :added "3.0"}
(hex-chars 255)
=> [\f \f]2.2 Base64 encoding
Base64 encoding works the same way: byte array in, ASCII string out.
encode and decode base64
^{:refer std.lib.encode/to-base64 :added "3.0"}
(-> (.getBytes "hello")
(to-base64))
=> "aGVsbG8="
^{:refer std.lib.encode/from-base64 :added "3.0"}
(-> (from-base64 "aGVsbG8=")
(String.))
=> "hello"3 API
- +hex-array+
- from-base64
- from-hex
- from-hex-chars
- hex-chars
- to-base64
- to-base64-bytes
- to-hex
- to-hex-chars
v 3.0
(defn ^"[B" from-base64
([^String input]
(.decode (Base64/getDecoder)
input)))link
(-> (from-base64 "aGVsbG8=") (String.)) => "hello"
v 3.0
(defn ^"[B" from-hex
([s]
(byte-array (map #(apply from-hex-chars %) (partition 2 s)))))link
(String. (from-hex "68656c6c6f")) => "hello"
v 3.0
(defn from-hex-chars
([^Character c1 ^Character c2]
(unchecked-byte
(+ (bit-shift-left (Character/digit c1 16) 4)
(Character/digit c2 16)))))link
(byte (from-hex-chars 2 a)) => 42
v 3.0
(defn ^chars hex-chars
([^Byte b]
(let [v (bit-and b 0xFF)]
[(+hex-array+ (bit-shift-right v 4))
(+hex-array+ (bit-and v 0x0F))])))link
(hex-chars 255) => [f f] (hex-chars 42) => [2 a]
v 3.0
(defn ^String to-base64
([bytes]
(.encodeToString (Base64/getEncoder)
bytes)))link
(-> (.getBytes "hello") (to-base64)) => "aGVsbG8="
v 3.0
(defn ^"[B" to-base64-bytes
([^"[B" bytes]
(.encode (Base64/getEncoder)
bytes)))link
(-> (.getBytes "hello") (to-base64-bytes) (String.)) => "aGVsbG8="
4 std.lib.encode: A Comprehensive Summary
The std.lib.encode namespace provides essential utility functions for encoding and decoding binary data into common string representations, specifically hexadecimal (hex) and Base64. These functions are crucial for tasks involving data serialization, secure transmission, and interoperability with systems that expect these formats.
4.1 Core Concepts:
- Hexadecimal Encoding: Converts raw byte arrays into a human-readable hexadecimal string representation, where each byte is represented by two hexadecimal characters (0-9, A-F).n* Base64 Encoding: Converts raw byte arrays into an ASCII string representation, suitable for transmission over mediums that do not handle binary data directly. Base64 is commonly used in MIME, JSON, and XML.
4.2 Key Functions:
hex-chars:n Purpose: Converts a single byte into its two corresponding hexadecimal characters.n Input: ABytevalue.n Output: A character array of two hexadecimal characters.n Usage:(hex-chars 255)=>[\f \f]nto-hex-chars:n Purpose: Converts a byte array into a character array of hexadecimal characters.n Input: Abyte[]array.n Output: Achar[]array.n Usage:(to-hex-chars (.getBytes "hello"))nto-hex:n Purpose: Converts a byte array into a hexadecimal string.n Input: Abyte[]array.n Output: AStringrepresenting the hexadecimal value.n Usage:(to-hex (.getBytes "hello"))=>"68656c6c6f"nfrom-hex-chars:n Purpose: Converts two hexadecimal characters back into a single byte value.n Input: TwoCharactervalues (hex digits).n Output: ABytevalue.n Usage:(byte (from-hex-chars \2 \a))=>42nfrom-hex:n Purpose: Converts a hexadecimal string back into a byte array.n Input: AStringrepresenting hexadecimal data.n Output: Abyte[]array.n Usage:(String. (from-hex "68656c6c6f"))=>"hello"nto-base64-bytes:n Purpose: Encodes a byte array into a Base64 byte array.n Input: Abyte[]array.n Output: Abyte[]array containing the Base64 encoded data.n Usage:(to-base64-bytes (.getBytes "hello"))nto-base64:n Purpose: Encodes a byte array into a Base64 string.n Input: Abyte[]array.n Output: AStringrepresenting the Base64 encoded data.n Usage:(to-base64 (.getBytes "hello"))=>"aGVsbG8="nfrom-base64:n Purpose: Decodes a Base64 string back into a byte array.n Input: AStringrepresenting Base64 encoded data.n Output: Abyte[]array.n * Usage:(String. (from-base64 "aGVsbG8="))=>"hello"
4.3 Usage Pattern:
This namespace is commonly used in scenarios such as:
- API Communication: Encoding binary data (e.g., images, files) for inclusion in JSON or XML payloads.n Security: Representing cryptographic keys, hashes, or signatures in a standard string format.n Data Storage: Storing binary data in text-based databases or configuration files.n* Debugging: Inspecting raw byte data in a more readable hexadecimal format.
By providing these straightforward encoding and decoding utilities, std.lib.encode simplifies the handling of binary-to-text conversions in Clojure applications.