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.

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

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

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

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

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
Contributor

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
@golang golang locked and limited conversation to collaborators Sep 2, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

4 participants