base64encoding

README

base64encoding

A small but very efficient and fast base64 encoding/decoding library for go that offers a variety of default charsets but also the option to use your very own, user-defined charset.

Usage

An encoder is used for both, encoding and decoding. Every encoder you create is tied to its very own, immutable charset. This ensures consistency when encoding/decoding with the same encoder.

Creating an Encoder:

You may create an encoder in one of the following ways:

• encoder with the default charset that is url-safe but non-standard:

  encoder := base64encoding.New()
  

• encoder with the standard base64 charset (e.g. used for encoding pictures in base64 in HTML) that is not url-safe:

  encoder := base64encoding.NewWeb()
  

• encoder with a custom charset (or a constant of this library that wasn't given its own constructor) that is defined by the user. Note that the charset must be comprised of exactly 64 pairwise distinct ASCII characters:

  myCharset := base64encoding.EasilyReadableCodeSet  
  // or myCharset := "my_custoM-CharSeT+0123456789..." (omitting the rest)
  
  encoder, err := base64encoding.NewCustom(myCharset)
  if err != nil {
    // handle error caused by illegal charset (e.g. not pairwise distinct)
  }
  

Once you have created your encoder you may use it like that:

Encode:

data := []byte("some data: could be a picture, a UUID or whatever") 
stringB64encoded := encoder.Encode(data) 

Decode:

data, err := encoder.Decode(stringB64encoded)
if err != nil {
  // handle error (e.g. string not encoded with the encoder's charset)
}

Notes

• encoders are thread-safe. You may use the same encoder accross mutliple threads simultaneously, as the charset is read-only.

Documentation

Index

• Constants
• Variables
• type Encoder64
  • func New() Encoder64
  • func NewCustom(codeSet string) (Encoder64, error)
  • func NewWeb() Encoder64
  • func (enc Encoder64) CodeSet() string
  • func (enc Encoder64) Decode(encodedStr string) ([]byte, error)
  • func (enc Encoder64) DecodeNum(encodedStr string) (uint64, error)
  • func (enc Encoder64) Encode(bytes []byte) string
  • func (enc Encoder64) EncodeNum(num uint64) string

Constants

const Base64WebSet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"

Base64WebSet is the standard base64 set for encoding data(e.g. images) in html files. However, this is not secure for using in URLs due to the '/' character

const EasilyReadableCodeSet = "*)23456789abcdefghi_klmnopqrstuvwxyzABCDEFGH+JKLMNOPQRSTUVWXYZ-$"

EasilyReadableCodeSet is a set with no characters that look alike (e.g. 0 & O, l & I)

const StandardCodeSet = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-_"

StandardCodeSet is the default, http safe code set of base64encoding

Variables

var (
	// ErrNotDistinct indicates that a code set was provided that has at least two times the same rune
	ErrNotDistinct = errors.New("base64encoding: characters in codeSet are not pairwise distinct")

	// ErrIllegalRune inidcates that the code set had runes that were not legal
	ErrIllegalRune = errors.New(`base64encoding error: illegal rune: at least one character of the provided code set
	is not an ASCII or extended ASCII character`)
)

Types

type Encoder64

type Encoder64 struct {
	// contains filtered or unexported fields
}

Encoder64 with multiple methods. Contains codeSet

func New

func New() Encoder64

New returns a new Encoder64 with the standard, http safe code set

func NewCustom

func NewCustom(codeSet string) (Encoder64, error)

NewCustom returns a new Encoder64 with the provided custom 64 character code set and an error if the set is unfit. Please note: the first (left most) character of the string will be the least significant character (0 * 64^n), while the last will be the most significant(63 * 64^n)

func NewWeb

func NewWeb() Encoder64

NewWeb returns a new Encoder64 with the base64web encoding set used for encoding data in html

func (Encoder64) CodeSet

func (enc Encoder64) CodeSet() string

CodeSet returns the codeSet, which the encoder uses to, well, en/decode

func (Encoder64) Decode

func (enc Encoder64) Decode(encodedStr string) ([]byte, error)

Decode decodes a given string and returns an error if the string is not in a correct format

func (Encoder64) DecodeNum

func (enc Encoder64) DecodeNum(encodedStr string) (uint64, error)

DecodeNum decodes a given string, converts it to an unsigned int64 and returns an error if the string is not in a correct format

func (Encoder64) Encode

func (enc Encoder64) Encode(bytes []byte) string

Encode encodes a given byte array to base64

func (Encoder64) EncodeNum

func (enc Encoder64) EncodeNum(num uint64) string

EncodeNum encodes a given uint64 to base64 by splitting the num into a byte array