- Generated by
1.9.8
|
BDE 4.39.x Production Release
|
Provide value-semantic attribute class for decoder options.
Provide value-semantic attribute class for decoder options.
This component provides a value-semantic attribute class for specifying options for bdlde::Base64Decoder.
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.
ignoreMode: which types of characters, if any, are to be ignorede_IGNORE_NONE : no input is ignored, any invalid Base64 character in the input will produce an errore_IGNORE_WHITESPACE : whitespace in the input is ignored (normally whitespace characters are invalid Base64 input)e_IGNORE_UNRECOGNIZED : all invalid Base64 characters in the input are ignored (no invalid input errors)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 : bool : if true, indicates that output is padded with '=' characters to a multiple of 4 characters.The ‘Base64DecoderOptions’ type provides a set of factory class methods, custom, mime, standard, and urlStafe to easily create a Base64DecoderOptions object having typical configuration parameters. Always use these methods to create a 'Base64DecoderOptions' object, the object is copyable, but the value constructor is private.
| class method | ignoreMode | alphabet | isPadded |
|---|---|---|---|
| custom | any | any | any |
| mime | (e_IGNORE_WHITESPACE) | e_BASIC | true |
| standard | (e_IGNORE_NONE) | e_BASIC | (true) |
| urlSafe | (e_IGNORE_NONE) | e_URL | (false) |
Note that in the above table, values in parentheses – e.g. (e_IGNORE_NONE) indicate a default which may be overrideen by a user-supplied value.
Below is some background on standards related to base64 encoding.
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.
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.
This section illustrates intended use of this component.
Suppose we want a Base64DecoderOptions object configured for MIME encoding, meaning alphabet == e_BASIC, isPadded == true, and ignoreMode = e_IGNORE_WHITESPACE.
First, we call the mime class method, and we're done.
Then, we check the attributes:
Now, we stream the object:
Finally, we observe the output:
Suppose we want a Base64DecoderOptions object configured for translating URL's. That would mean alphabet == e_URL, isPadded == false, and ignoring neither unrecognized characters nor whitespace.
First, the class method urlSafe returns an object configured exactly that way, so we simply call it:
Then, we check the attributes:
Now, we stream the object:
Finally, we observe the output:
Suppose we want an options object configured for standard Base64:
First, we can simply call the standard class method:
Then, we check the attributes:
Now, we stream the object:
Finally, we observe the output:
Suppose we want a really strangely configured options object with alphabet == e_URL, and padding, and ignoring neither unrecognized characters nor whitespace.
First, we can simply call the custom class method. The padded and unrecognizedIsError == true arguments are last, and they default to true, so we don't have to pass that.
Then, we check the attributes:
Now, we stream the object:
Finally, we observe the output:
1.9.8