bdlde_base64encoderoptions

Detailed Description

Provide a value-semantic attribute class for encoder options.

Outline

• Purpose
• Classes
• Description
  • Attributes
  • Pre-Defined Styles
  • Standards References
    • RFC-2045 - Mime Standard
    • RFC-4648 - The Base16|32|64 Encoding Standard
  • Usage
    • Example 1: Basic Usage
    • Example 2:
    • Example 3:
    • Example 4:

Purpose

Provide a value-semantic attribute class for encoder options.

Classes

• bdlde::Base64EncoderOptions: options for encoder

See also

bdlde_base64decoderoptions, bdlde_base64encoder, bdlde_base64decoder, bdlde_base64alphabet

Description

This component provides a value-semantic attribute class for specifying options for bdlde::Base64Encoder.

This class supports default-generated copy construction and copy assignment, but the constructor is private. To create an object one must call one of the class methods, which will return a newly-constructed object by value. Specialized class methods are provided to create objects configured for the mime, urlSafe, and standard configurations.

Other configurations may be obtained by specifying arguments to the custom class method, or by calling the setters after the object is created.

Attributes

Name           Type
-------------  --------------------
maxLineLength  int
alphabet       Base64Alphabet::Enum
isPaded        bool

• maxLineLength: the maximum number of Base64 characters to output before inserting a '
  '. If this value is 0, maxLineLength is ignored, and no '
  ' characters are output in the Base64 text.
• alphabet: describes the set of available characters (or alphabet) that may appear in the resulting encoded text. Note that Base64 encoding breaks binary data into 64 bit blocks, where the numeric values 0-61 are encoded using [0-9a-zA-Z], the alphabet only impacts how the values 62 and 63 are represented:
  • e_BASIC : defined in standard RFC 2045 section 6.8, and should be the default choice, uses '+' and '/' for 62 and 63, respectively,
  • e_URL : defined in RFC 4648 section 5, creates an encoded representation suitable for use in a URL or filename. The alphabet avoids characters like '/' that have a special meaning in the context of a URL or filename. Uses '-' and '_' for 62 and 63, respectively.
• isPadded : if true, indicates that output is padded with '=' characters to a multiple of 4 characters.

Pre-Defined Styles

The constructor is private; the client is expected to use the public class methods to create 'option's objects. The 'custom' class method can create any arbitrary value, plus there are 3 pre-defined class methods. The following table shows the hard-wired attribute values of these class methods – if a value is in parentheses, it means the attribute is a parameter of the method and the value in parentheses is its default value.

class method	maxLineLength	alphabet	isPadded
custom	any	any	any
mime	76	e_BASIC	true
standard	0 [disabled]	e_BASIC	(true)
urlSafe	0 [disabled]	e_URL	(false)

Note that in the above table, values in parentheses – e.g. (true) indicate a default which may be overrideen by a user-supplied value.

Standards References

Below is some background on standards related to base64 encoding.

RFC-2045 - Mime Standard

The Base64 encoding originated as a way of encoding arbitrary binary data into the body of ASCII-only emails. This was the MIME standard, https://datatracker.ietf.org/doc/html/rfc2045#section-6.8

The mime factory function creates a Base64Encoder configured to the MIME specification.

RFC-4648 - The Base16|32|64 Encoding Standard {#bdlde_base64encoderoptions-rfc-4648—the-base16|32|64-encoding-standard}

Eventually, Base64 encoding was separately standardized in RFC-4648: https://datatracker.ietf.org/doc/html/rfc464

This standard differs slightly from the original MIME Base64 encoding in that the encoding doesn't have line feeds, and the padding at the end of a line is optional.

This standard provides a couple variants of the alphabet of characters that can be used to encode the data.

Standard Alphabet - the standard alphabet is described in https://datatracker.ietf.org/doc/html/rfc4648#section-4. A factory function standard is provided to create a Base64Encoder configured to use the standard alphabet.

** URL and Filename Safe Alphabet** - An alternative alphabet for encoding data to be used in file names or URLs in https://datatracker.ietf.org/doc/html/rfc4648#section-5. A factory function urlSafe is provided to create a Base64Encoder configured to use the URL and filename safe alphabet. This alphabet avoids characters, like '/', that have a special meaning the the context of a file name or URL.

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage

Suppose we want a Base64EncoderOptions object configured for MIME encoding, meaning maxLineLength == 76, alphabet == e_BASIC, and isPadded == true.

First, it turns out that those are the default values of the attributes, so all we have to do is default construct an object, and we're done.

const bdlde::Base64EncoderOptions& mimeOptions =
                                       bdlde::Base64EncoderOptions::mime();

Then, we check the attributes:

assert(mimeOptions.maxLineLength() == 76);
assert(mimeOptions.alphabet()      == bdlde::Base64Alphabet::e_BASIC);
assert(mimeOptions.isPadded()      == true);

Now, we stream the object:

mimeOptions.print(cout);

Finally, we observe the output:

[
    maxLineLength = 76
    alphabet = BASIC
    isPadded = true
]

Example 2:

Suppose we want a Base64EncoderOptions object configured for translating URL's. That would mean a maxLineLength == 0, alphabet == e_URL, and isPadded == false.

First, the class method urlSafe returns an object configured exactly that way, so we simply call it:

const bdlde::Base64EncoderOptions& urlOptions =
                                    bdlde::Base64EncoderOptions::urlSafe();

Then, we check the attributes:

assert(urlOptions.maxLineLength() == 0);
assert(urlOptions.alphabet()      == bdlde::Base64Alphabet::e_URL);
assert(urlOptions.isPadded()      == false);

Now, we stream the object:

urlOptions.print(cout);

Finally, we observe the output:

[
    maxLineLength = 0
    alphabet = URL
    isPadded = false
]

Example 3:

Suppose we want an options object configured for standard Base64:

First, we can simply call the standard class method:

const bdlde::Base64EncoderOptions& standardOptions =
                                   bdlde::Base64EncoderOptions::standard();

Then, we check the attributes:

assert(standardOptions.maxLineLength() == 0);
assert(standardOptions.alphabet()      == bdlde::Base64Alphabet::e_BASIC);
assert(standardOptions.isPadded()      == true);

Now, we stream the object:

standardOptions.print(cout);

Finally, we observe the output:

[
    maxLineLength = 0
    alphabet = BASIC
    isPadded = true
]

Example 4:

Suppose we want a really strangely configured options object with maxLineLength == 200, alphabet == e_URL, and padding.

First, we can simply call the custom class method:

const bdlde::Base64EncoderOptions& customOptions =
          bdlde::Base64EncoderOptions::custom(200,
                                              bdlde::Base64Alphabet::e_URL,
                                              true);

Then, we check the attributes:

assert(customOptions.maxLineLength() == 200);
assert(customOptions.alphabet()      == bdlde::Base64Alphabet::e_URL);
assert(customOptions.isPadded()      == true);

Now, we stream the object:

cout << customOptions << endl;

Finally, we observe the output:

[ maxLineLength = 200 alphabet = URL isPadded = true ]