commit c5c2869f3bda94a2b651bee5582106f17561f743
parent 7ed3b806920b887058bba943e4609cf510a6fe48
Author: Drew DeVault <sir@cmpwn.com>
Date: Sun, 8 Aug 2021 22:13:00 +0200
encoding::base64: improve docs, trim down module
It might be a good idea to trim this further by removing some of the
functions which work with base64-encoded data as a byte slice. Since
base 64 is defined as a text format, it may make sense for this module
to only support representing it as a str (or indirectly, via an
io::stream).
Signed-off-by: Drew DeVault <sir@cmpwn.com>
Diffstat:
3 files changed, 21 insertions(+), 78 deletions(-)
diff --git a/bufio/README b/bufio/README
@@ -1,6 +1,6 @@
bufio provides [[io::stream]] implementations which provide buffered I/O
support, as well as scanner utility functions which pair well with buffered
-streams for maximum efficiency.
+streams for optimal efficiency.
Two streams are provided which can read from or write to byte slices. [[fixed]]
uses a caller-supplied statically-allocated buffer for storage, producing an
diff --git a/encoding/base64/README b/encoding/base64/README
@@ -1,5 +1,19 @@
-Implementation of the base 64 encoding as per RFC 4648. This implementation
-does not support invalid padding due to security concerns described in the
-RFC.
+Implementation of the base 64 encoding as defined by RFC 4648.
+
+There are various functions available for decoding and encoding. The decode
+family accepts an [[io::stream]] as input, while the decodeslice and decodestr
+family of functions accept slices and strings as input, respectively.
+[[decode]] accepts an [[io::stream]] for the output, and [[decodeslice]] and
+[[decodestr]] dynamically allocate a slice or string to write the output to, and
+return it to the caller (who is then responsible for freeing it). The _static
+family of functions, such as [[decode_static]], accept a caller-allocated slice
+to write the output to. A similar set of functions is provided for encoding.
+
+Each function accepts the desired base64 alphabet as its first argument. You may
+provide your own alphabet, but [[standard]] and [[urlsafe]], as defined by the
+RFC, are provided for your convenience.
+
+Due to security concerns described by the RFC, this implementation rejects
+invalid padding.
https://datatracker.ietf.org/doc/html/rfc4648#section-12
diff --git a/encoding/base64/base64.ha b/encoding/base64/base64.ha
@@ -74,18 +74,6 @@ export fn encode(
return z;
};
-// Calls [[encode]] with the [[standard]] base 64 encoding alphabet.
-export fn stdencode(
- sink: *io::stream,
- b: []u8,
-) (size | io::error) = encode(standard, sink, b);
-
-// Calls [[encode]] with the [[urlsafe]] base 64 encoding alphabet.
-export fn urlencode(
- sink: *io::stream,
- b: []u8,
-) (size | io::error) = encode(urlsafe, sink, b);
-
// Encodes a byte slice using a base 64 encoding alphabet, with padding, and
// returns it. The caller must free the return value.
export fn encodestr(alphabet: []u8, b: []u8) str = {
@@ -94,12 +82,6 @@ export fn encodestr(alphabet: []u8, b: []u8) str = {
return strio::finish(sink);
};
-// Calls [[encodestr]] with the [[standard]] base 64 encoding alphabet.
-export fn stdencodestr(b: []u8) str = encodestr(standard, b);
-
-// Calls [[encodestr]] with the [[urlsafe]] base 64 encoding alphabet.
-export fn urlencodestr(b: []u8) str = encodestr(urlsafe, b);
-
@test fn encode() void = {
const in: [_]u8 = ['f', 'o', 'o', 'b', 'a', 'r'];
const expect: [_]str = [
@@ -196,18 +178,6 @@ export fn decode(
return z;
};
-// Calls [[decode]] with the [[standard]] base 64 encoding alphabet.
-export fn stddecode(
- in: *io::stream,
- out: *io::stream,
-) (size | invalid | io::error) = decode(standard, in, out);
-
-// Calls [[decode]] with the [[urlsafe]] base 64 encoding alphabet.
-export fn urldecode(
- in: *io::stream,
- out: *io::stream,
-) (size | invalid | io::error) = decode(urlsafe, in, out);
-
// Decodes base 64-encoded data in the given base 64 alphabet, with padding,
// from an [[io::stream]]. The number of bytes written is returned.
export fn decode_static(
@@ -224,16 +194,6 @@ export fn decode_static(
};
};
-// Calls [[decode_static]] with the [[standard]] base 64 encoding alphabet.
-export fn stddecode_static(out: []u8, in: *io::stream) (size | invalid) = {
- return decode_static(standard, out, in);
-};
-
-// Calls [[decode_static]] with the [[urlsafe]] base 64 encoding alphabet.
-export fn urldecode_static(out: []u8, in: *io::stream) (size | invalid) = {
- return decode_static(urlsafe, out, in);
-};
-
// Decodes a string of base 64-encoded data in the given base 64 encoding
// alphabet, with padding, into a byte slice. The caller must free the return
// value.
@@ -241,12 +201,6 @@ export fn decodestr(alphabet: []u8, in: str) ([]u8 | invalid) = {
return decodeslice(alphabet, strings::toutf8(in));
};
-// Calls [[decodestr]] with the [[standard]] base 64 encoding alphabet.
-export fn stddecodestr(in: str) ([]u8 | invalid) = decodestr(standard, in);
-
-// Calls [[decodestr]] with the [[urlsafe]] base 64 encoding alphabet.
-export fn urldecodestr(in: str) ([]u8 | invalid) = decodestr(urlsafe, in);
-
// Decodes a string of base 64-encoded data in the given base 64 encoding
// alphabet, with padding. The number of bytes written is returned.
export fn decodestr_static(
@@ -257,16 +211,6 @@ export fn decodestr_static(
return decodeslice_static(alphabet, out, strings::toutf8(in));
};
-// Calls [[decodestr_static]] with the [[standard]] base 64 encoding alphabet.
-export fn stddecodestr_static(out: []u8, in: str) (size | invalid) = {
- return decodestr_static(standard, out, in);
-};
-
-// Calls [[decodestr_static]] with the [[urlsafe]] base 64 encoding alphabet.
-export fn urldecodestr_static(out: []u8, in: str) (size | invalid) = {
- return decodestr_static(urlsafe, out, in);
-};
-
// Decodes a byte slice of base 64-encoded data in the given base 64 encoding
// alphabet, with padding, into a byte slice. The caller must free the return
// value.
@@ -281,12 +225,6 @@ export fn decodeslice(alphabet: []u8, in: []u8) ([]u8 | invalid) = {
};
};
-// Calls [[decodeslice]] with the [[standard]] base 64 encoding alphabet.
-export fn stddecodeslice(in: []u8) ([]u8 | invalid) = decodeslice(standard, in);
-
-// Calls [[decodeslice]] with the [[urlsafe]] base 64 encoding alphabet.
-export fn urldecodeslice(in: []u8) ([]u8 | invalid) = decodeslice(urlsafe, in);
-
// Decodes a byte slice of base 64-encoded data in the given base 64 encoding
// alphabet, with padding. The number of bytes written is returned.
export fn decodeslice_static(
@@ -299,16 +237,6 @@ export fn decodeslice_static(
return decode_static(alphabet, out, in);
};
-// Calls [[decodeslice_static]] with the [[standard]] base 64 encoding alphabet.
-export fn stddecodeslice_static(out: []u8, in: []u8) (size | invalid) = {
- return decodeslice_static(standard, out, in);
-};
-
-// Calls [[decodeslice_static]] with the [[urlsafe]] base 64 encoding alphabet.
-export fn urldecodeslice_static(out: []u8, in: []u8) (size | invalid) = {
- return decodeslice_static(urlsafe, out, in);
-};
-
@test fn decode() void = {
const in: [_]str = [
"",
@@ -321,7 +249,7 @@ export fn urldecodeslice_static(out: []u8, in: []u8) (size | invalid) = {
];
const expect: [_]u8 = ['f', 'o', 'o', 'b', 'a', 'r'];
for (let i = 0z; i < len(in); i += 1) {
- let s = stddecodestr(in[i]) as []u8;
+ let s = decodestr(standard, in[i]) as []u8;
defer free(s);
assert(bytes::equal(s, expect[..i]));
};
@@ -338,6 +266,7 @@ export fn urldecodeslice_static(out: []u8, in: []u8) (size | invalid) = {
];
const badindex: [_]size = [1, 2, 3, 0, 0, 1, 3, 4];
for (let i = 0z; i < len(bad); i += 1) {
- assert(stddecodestr(bad[i]) as invalid == badindex[i]: invalid);
+ let result = decodestr(standard, bad[i]);
+ assert(result as invalid == badindex[i]: invalid);
};
};
