vieter-v
/
v
2
0
Fork 0
Code Issues Pull Requests Releases Activity

encoding: document all of the `encoding.base64` module (#8276)

pull/8281/head
Larpon 2021-01-22 21:29:05 +01:00 committed by GitHub
parent 081e3c46b4
commit 981b42125f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 51 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
vlib/encoding/base64/base64.v
View File

@ -1,28 +1,21 @@
// Copyright (c) 2019-2021 Alexander Medvednikov. All rights reserved. // Copyright (c) 2019-2021 Alexander Medvednikov. All rights reserved.
// Use of this source code is governed by an MIT license // Use of this source code is governed by an MIT license
// that can be found in the LICENSE file. // that can be found in the LICENSE file.
module base64 module base64
const ( const (
index = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, index = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 62, 63, 62, 62, 63, 52, 53, 54, 55,
62, 63, 62, 62, 63, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 0, 0, 0, 56, 57, 58, 59, 60, 61, 0, 0, 0, 0, 0, 0, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12,
0, 0, 0, 0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 0, 0, 0, 0, 63, 0, 26, 27, 28, 29,
17, 18, 19, 20, 21, 22, 23, 24, 25, 0, 0, 0, 0, 63, 0, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51]!
30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46,
47, 48, 49, 50, 51]!
ending_table = [0, 2, 1]! ending_table = [0, 2, 1]!
enc_table = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/' enc_table = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
) )
/* // decode decodes the base64 encoded `string` value passed in `data`.
decode - expects a base64 encoded string. Returns its decoded version. // Please note: If you need to decode many strings repeatedly, take a look at `decode_in_buffer`.
@param data - the encoded input string. // Example: assert base64.decode('ViBpbiBiYXNlIDY0') == 'V in base 64'
@return the decoded version of the input string data.
NB: if you need to decode many strings repeatedly, take a look at decode_in_buffer too.
*/
pub fn decode(data string) string { pub fn decode(data string) string {
size := data.len * 3 / 4 size := data.len * 3 / 4
if size <= 0 { if size <= 0 {
@ -32,13 +25,10 @@ pub fn decode(data string) string {
return tos(buffer, decode_in_buffer(data, buffer)) return tos(buffer, decode_in_buffer(data, buffer))
} }
/* // encode encodes the `string` value passed in `data` to base64.
decode - expects a string. Returns its base64 encoded version. // Please note: base64 encoding returns a `string` that is ~ 4/3 larger than the input.
@param data - the input string. // Please note: If you need to encode many strings repeatedly, take a look at `encode_in_buffer`.
@return the base64 encoded version of the input string. // Example: assert base64.encode('V in base 64') == 'ViBpbiBiYXNlIDY0'
NB: base64 encoding returns a string that is ~ 4/3 larger than the input.
NB: if you need to encode many strings repeatedly, take a look at encode_in_buffer too.
*/
pub fn encode(data string) string { pub fn encode(data string) string {
size := 4 * ((data.len + 2) / 3) size := 4 * ((data.len + 2) / 3)
if size <= 0 { if size <= 0 {
@ -48,34 +38,33 @@ pub fn encode(data string) string {
return tos(buffer, encode_in_buffer(data, buffer)) return tos(buffer, encode_in_buffer(data, buffer))
} }
// decode decodes base64url string to string // decode_url returns a decoded URL `string` version of
// the a base64 url encoded `string` passed in `data`.
pub fn decode_url(data string) string { pub fn decode_url(data string) string {
mut result := data.replace('-', '+') // 62nd char of encoding mut result := data.replace('-', '+') // 62nd char of encoding
result = data.replace('_', '/') // 63rd char of encoding result = data.replace('_', '/') // 63rd char of encoding
match result.len % 4 { // Pad with trailing '='s match result.len % 4 { // Pad with trailing '='s
2 { result += "==" } // 2 pad chars 2 { result += '==' } // 2 pad chars
3 { result += "=" } // 1 pad char 3 { result += '=' } // 1 pad char
else {} // no padding else {} // no padding
} }
return base64.decode(data) return decode(data)
} }
// encode encodes given string to base64url string // encode_url returns a base64 URL encoded `string` version
// of the value passed in `data`.
pub fn encode_url(data string) string { pub fn encode_url(data string) string {
mut result := base64.encode(data) mut result := encode(data)
// 62nd char of encoding, 63rd char of encoding, remove any trailing '='s // 62nd char of encoding, 63rd char of encoding, remove any trailing '='s
result = result.replace_each(['+', '-', '/', '_', '=', '']) result = result.replace_each(['+', '-', '/', '_', '=', ''])
return result return result
} }
/* // decode_in_buffer decodes the base64 encoded `string` reference passed in `data` into `buffer`.
decode_in_buffer - expects a string reference, and a buffer in which to store its decoded version. // decode_in_buffer returns the size of the decoded data in the buffer.
@param data - a reference/pointer to the input string that will be decoded. // Please note: The `buffer` should be large enough (i.e. 3/4 of the data.len, or larger)
@param buffer - a reference/pointer to the buffer that will hold the result. // to hold the decoded data.
The buffer should be large enough (i.e. 3/4 of the data.len, or larger) to hold the decoded data. // Please note: This function does NOT allocate new memory, and is thus suitable for handling very large strings.
@return the actual size of the decoded data in the buffer.
NB: this function does NOT allocate new memory, and is suitable for handling very large strings.
*/
pub fn decode_in_buffer(data &string, buffer byteptr) int { pub fn decode_in_buffer(data &string, buffer byteptr) int {
mut padding := 0 mut padding := 0
if data.ends_with('=') { if data.ends_with('=') {
@ -97,7 +86,6 @@ pub fn decode_in_buffer(data &string, buffer byteptr) int {
d = byteptr(data.str) d = byteptr(data.str)
b = byteptr(buffer) b = byteptr(buffer)
} }
for i < input_length { for i < input_length {
mut char_a := 0 mut char_a := 0
mut char_b := 0 mut char_b := 0
@ -131,14 +119,10 @@ pub fn decode_in_buffer(data &string, buffer byteptr) int {
return output_length return output_length
} }
/* // encode_in_buffer base64 encodes the `string` reference passed in `data` into `buffer`.
encode_in_buffer - expects a string reference, and a buffer in which to store its base64 encoded version. // encode_in_buffer returns the size of the encoded data in the buffer.
@param data - a reference/pointer to the input string. // Please note: The buffer should be large enough (i.e. 4/3 of the data.len, or larger) to hold the encoded data.
@param buffer - a reference/pointer to the buffer that will hold the result. // Please note: The function does NOT allocate new memory, and is suitable for handling very large strings.
The buffer should be large enough (i.e. 4/3 of the data.len, or larger) to hold the encoded data.
@return the actual size of the encoded data in the buffer.
NB: this function does NOT allocate new memory, and is suitable for handling very large strings.
*/
pub fn encode_in_buffer(data &string, buffer byteptr) int { pub fn encode_in_buffer(data &string, buffer byteptr) int {
input_length := data.len input_length := data.len
output_length := 4 * ((input_length + 2) / 3) output_length := 4 * ((input_length + 2) / 3)
@ -154,7 +138,6 @@ pub fn encode_in_buffer(data &string, buffer byteptr) int {
b = buffer b = buffer
etable = enc_table.str etable = enc_table.str
} }
for i < input_length { for i < input_length {
mut octet_a := 0 mut octet_a := 0
mut octet_b := 0 mut octet_b := 0