Luna/libluna/include/luna/Base64.h

/**
 * @file Base64.h
 * @author apio (cloudapio.eu)
 * @brief Base64 encoding and decoding.
 *
 * @copyright Copyright (c) 2023, the Luna authors.
 *
 */

#pragma once
#include <luna/Buffer.h>
#include <luna/String.h>

namespace Base64
{
    /**
     * @brief Encode a string into Base64.
     *
     * @param data The string to encode.
     * @return Result<String> An error, or the resulting Base64 string.
     */
    Result<String> encode(StringView data);

    /**
     * @brief Encode a slice of data into Base64.
     *
     * @param data The data to encode.
     * @return Result<String> An error, or the resulting Base64 string.
     */
    Result<String> encode(Slice<const u8> data);

    /**
     * @brief Encode a buffer into Base64.
     *
     * @param data The buffer to encode.
     * @return Result<String> An error, or the resulting Base64 string.
     */
    Result<String> encode(const Buffer& data);

    /**
     * @brief Decode a Base64 string.
     *
     * @param data The string to decode.
     * @param allow_garbage_chars Whether to skip non-Base64 characters instead of returning an error.
     * @return Result<Buffer> An error, or the raw decoded data.
     */
    Result<Buffer> decode(StringView data, bool allow_garbage_chars = false);

    /**
     * @brief Decode a Base64 string, returning a string instead of raw data.
     *
     * Note that decoded Base64 may be anything; invalid UTF-8, null characters in the middle of data, etc...
     * For this reason it is not recommended to use this function unless you're sure that what is decoded will be a
     * valid string (so, don't use this with untrusted user input).
     *
     * @param data The string to decode.
     * @param allow_garbage_chars Whether to skip non-Base64 characters instead of returning an error.
     * @return Result<String> An error, or the decoded string.
     */
    Result<String> decode_string(StringView data, bool allow_garbage_chars = false);
}