Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

encoding/base64: documentation can show the alphabet used for encoding #55126

Closed
shaneHowearth opened this issue Sep 18, 2022 · 3 comments
Closed

encoding/base64: documentation can show the alphabet used for encoding #55126

shaneHowearth opened this issue Sep 18, 2022 · 3 comments
Labels
Documentation NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Go1.22

Comments

@shaneHowearth
Copy link

The encoding variables make reference to the RFC on how they work, but it's not clear from Go's documentation, nor the RFC, how they differ (note that they are defined in the RFC, but the naming, and link, means it's not an easy lookup for the first time users, I broke some code at work not knowing the difference and it was discovered because a consumer was using the other set) - is there a cleaner way to say
URLEncoding uses the following characterset

 Table 2: The "URL and Filename safe" Base 64 Alphabet

     Value Encoding  Value Encoding  Value Encoding  Value Encoding
         0 A            17 R            34 i            51 z
         1 B            18 S            35 j            52 0
         2 C            19 T            36 k            53 1
         3 D            20 U            37 l            54 2
         4 E            21 V            38 m            55 3
         5 F            22 W            39 n            56 4
         6 G            23 X            40 o            57 5
         7 H            24 Y            41 p            58 6
         8 I            25 Z            42 q            59 7
         9 J            26 a            43 r            60 8
        10 K            27 b            44 s            61 9
        11 L            28 c            45 t            62 - (minus)
        12 M            29 d            46 u            63 _
        13 N            30 e            47 v           (underline)
        14 O            31 f            48 w
        15 P            32 g            49 x
        16 Q            33 h            50 y         (pad) =

and StdEncoding uses the following

                      Table 1: The Base 64 Alphabet

     Value Encoding  Value Encoding  Value Encoding  Value Encoding
         0 A            17 R            34 i            51 z
         1 B            18 S            35 j            52 0
         2 C            19 T            36 k            53 1
         3 D            20 U            37 l            54 2
         4 E            21 V            38 m            55 3
         5 F            22 W            39 n            56 4
         6 G            23 X            40 o            57 5
         7 H            24 Y            41 p            58 6
         8 I            25 Z            42 q            59 7
         9 J            26 a            43 r            60 8
        10 K            27 b            44 s            61 9
        11 L            28 c            45 t            62 +
        12 M            29 d            46 u            63 /
        13 N            30 e            47 v
        14 O            31 f            48 w         (pad) =
        15 P            32 g            49 x
        16 Q            33 h            50 y

As well as the reasoning that is already present in the docs.
@cherrymui cherrymui changed the title base64 encoding documentation encoding/base64: documentation Sep 19, 2022
@cherrymui
Copy link
Member

The encoding is standard and not defined by Go. I think reference the RFC is the right approach.

cc @rsc

@cherrymui cherrymui added this to the Unplanned milestone Sep 19, 2022
@cherrymui cherrymui added the NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. label Sep 19, 2022
@shaneHowearth
Copy link
Author

shaneHowearth commented Sep 19, 2022 •
edited

FTR - I'm not suggesting that Go is defining the character sets, I'm asking that the character sets being used be explicitly mentioned in the documentation (As I say, a bug occurred due to a misunderstanding of the character sets, with one tool claiming that the set used meant our implementation was "broken" - when all it was was URL Encoding had been used instead of standard).

Also - the links drop you at the index of the RFC, which isn't that flash, meaning that people have to work out that they were dropped at the index, not at the point that the character sets for their chosen encoding is defined

@gopherbot
Copy link

Change https://go.dev/cl/525296 mentions this issue: encoding: show the alphabet for base32 and base64

@dmitshur dmitshur added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. labels Sep 3, 2023
@dmitshur dmitshur modified the milestones: Unplanned, Go1.22 Sep 3, 2023
@dmitshur dmitshur changed the title encoding/base64: documentation encoding/base64: documentation can show the alphabet used for encoding Sep 3, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Go1.22
Development

No branches or pull requests
4 participants
@dmitshur @shaneHowearth @gopherbot @cherrymui