feat: add base64 support

doc/specs/index.md

@@ -14,6 +14,7 @@ This is an index/directory of the specifications (specs) for each new module/fea
  - [ansi](./stdlib_ansi.html) - Terminal color and style escape sequences
  - [array](./stdlib_array.html) - Procedures for index manipulation and array handling
  - [ascii](./stdlib_ascii.html) - Procedures for handling ASCII characters
+ - [base64](./stdlib_base64.html) - Base64 encoding and decoding routines
  - [constants](./stdlib_constants.html) - Constants
  - [bitsets](./stdlib_bitsets.html) - Bitset data types and procedures
  - [error](./stdlib_error.html) - Catching and handling errors

doc/specs/stdlib_base64.md

@@ -0,0 +1,172 @@
+---
+title: base64
+---
+
+# The `stdlib_base64` module
+
+[TOC]
+
+## Introduction
+
+The `stdlib_base64` module provides procedures to encode and decode intrinsic
+Fortran data using the Base64 encoding scheme defined by RFC 4648.
+
+## Specification of the `stdlib_base64` procedures
+
+### `base64_encode`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Encodes intrinsic arrays into Base64 text.
+
+This is the ergonomic API for encoding. It allocates and returns the output
+string automatically.
+
+#### Syntax
+
+`res =` [[stdlib_base64(module):base64_encode(interface)]] `(data)`
+
+#### Class
+
+Function.
+
+#### Argument
+
+`data`: shall be a contiguous array of an intrinsic type (`real`, `integer`,
+`complex`, `logical`, or `integer(int8)`). It is an `intent(in)` argument.
+
+#### Result value
+
+The result `res` is an allocatable character string (`character(len=:)`)
+containing the Base64 representation of the input `data`.
+
+#### Example
+
+```fortran
+character(len=:), allocatable :: encoded
+integer(int8) :: bytes(3) = [77_int8, 97_int8, 110_int8]
+
+encoded = base64_encode(bytes)  ! "TWFu"
+```
+
+### `base64_encode_into`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Encodes bytes into a caller-provided output buffer.
+
+This is the preallocated API for throughput-sensitive workflows. It does not
+allocate and reports status through `err_state`. On success,
+`err_state%ok()` is `.true.` and `encoded_len` is the number of meaningful
+characters written to `str`.
+
+#### Syntax
+
+`call` [[stdlib_base64(module):base64_encode_into(subroutine)]] &
+`(bytes, str, encoded_len, err_state)`
+
+#### Class
+
+Pure module subroutine.
+
+#### Arguments
+
+`bytes`: shall be a contiguous array of type `integer(int8)`. It is an
+`intent(in)` argument.
+
+`str`: shall be an intrinsic character type. It is an `intent(out)` argument.
+
+`encoded_len`: shall be an `integer`. It is an `intent(out)` argument
+representing the number of encoded characters written.
+
+`err_state`: shall be a `type(state_type)` from `stdlib_error`. It is an
+`intent(out)` argument used to report success or errors.
+
+### `base64_decode`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Decodes Base64 text and returns an allocated byte string.
+
+This is the ergonomic API for decoding. It allocates and returns the result
+automatically. On error, an empty result is returned. If `err_state` is
+present, error details are reported there.
+
+#### Syntax
+
+`res =` [[stdlib_base64(module):base64_decode(function)]] `(str [, err_state])`
+
+#### Class
+
+Function.
+
+#### Arguments
+
+`str`: shall be an intrinsic character type. It is an `intent(in)` argument.
+
+`err_state` (optional): shall be a `type(state_type)` from `stdlib_error`.
+It is an `intent(out)` argument used to report invalid Base64 sequences.
+
+#### Result value
+
+The result `res` is an allocatable character string (`character(len=:)`)
+containing the decoded bytes.
+
+#### Example
+
+```fortran
+character(len=:), allocatable :: decoded
+
+decoded = base64_decode("TWFu")  ! "Man"
+```
+
+### `base64_decode_into`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Decodes Base64 text into a caller-provided output buffer.
+
+This is the preallocated API for throughput-sensitive workflows. It does not
+allocate and reports status through `err_state`. The optional `skip_despace`
+argument can be used when the input is already whitespace-free to bypass the
+despacing step.
+
+#### Syntax
+
+`call` [[stdlib_base64(module):base64_decode_into(subroutine)]] &
+`(str, res, decoded_len, err_state [, skip_despace])`
+
+#### Class
+
+Pure module subroutine.
+
+#### Arguments
+
+`str`: shall be an intrinsic character type. It is an `intent(in)` argument.
+
+`res`: shall be an intrinsic character type. It is an `intent(out)` argument.
+
+`decoded_len`: shall be an `integer`. It is an `intent(out)` argument
+representing the number of decoded bytes written.
+
+`err_state`: shall be a `type(state_type)` from `stdlib_error`. It is an
+`intent(out)` argument used to report success or errors.
+
+`skip_despace` (optional): shall be a `logical`. It is an `intent(in)`
+argument. If `.true.`, the routine assumes the input contains no whitespace.

src/core/stdlib_ascii.fypp

@@ -65,6 +65,7 @@ module stdlib_ascii
     character(len=*), public, parameter :: letters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz" !! A .. Za .. z
     character(len=*), public, parameter :: uppercase = letters(1:26) !! A .. Z
     character(len=*), public, parameter :: lowercase = letters(27:) !! a .. z
+    character(len=*), public, parameter :: base64_alphabet = letters//digits//"+/" !! RFC 4648 Base64 alphabet
     character(len=*), public, parameter :: whitespace = " "//TAB//VT//CR//LF//FF !! ASCII _whitespace
 
 

src/strings/CMakeLists.txt

@@ -1,4 +1,7 @@
 set(strings_fppFiles
+    stdlib_base64_encode.fypp
+    stdlib_base64_decode.fypp
+    stdlib_base64.fypp
     stdlib_string_type.fypp
     stdlib_string_type_constructor.fypp
     stdlib_str2num.fypp

src/strings/stdlib_base64.fypp

@@ -0,0 +1,177 @@
+! SPDX-Identifier: MIT
+#:include "common.fypp"
+
+!> Base64 encoding and decoding algorithms
+!>
+!> This module provides procedures to safely encode and decode data
+!> using the standard Base64 encoding scheme defined in RFC 4648.
+!>
+!> @note
+!> **Experimental:** This API is currently considered experimental and 
+!> may be subject to change in future releases of `stdlib`.
+
+module stdlib_base64
+    use stdlib_kinds, only: sp, dp, xdp, qp, int8, int16, int32, int64, lk, c_bool
+    use, intrinsic :: iso_c_binding, only: c_size_t
+    use stdlib_ascii, only: base64_alphabet
+    use stdlib_error, only: state_type
+
+    implicit none
+    private
+
+    public :: base64_encode, base64_encode_into
+    public :: base64_decode, base64_decode_into
+
+    ! Branchless RFC 4648 decode map: byte -> 6-bit value, invalid -> -1.
+    ! The main loop OR-reduces values and checks once at the end.
+    integer(int8), parameter :: DT(0:255) = int( [ &
+        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, &
+        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, &
+        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,62,-1,-1,-1,63, &
+        52,53,54,55,56,57,58,59,60,61,-1,-1,-1,-1,-1,-1, &
+        -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,10,11,12,13,14, &
+        15,16,17,18,19,20,21,22,23,24,25,-1,-1,-1,-1,-1, &
+        -1,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40, &
+        41,42,43,44,45,46,47,48,49,50,51,-1,-1,-1,-1,-1, &
+        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, &
+        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, &
+        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, &
+        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, &
+        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, &
+        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, &
+        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1, &
+        -1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1  &
+    ], int8)
+
+    ! Branchless stream-compaction mask for despace step: keep(1) / drop(0).
+    integer(int32), parameter :: IS_VAL(0:255) = int([ &
+        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, &
+        0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, &
+        0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, &
+        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, &
+        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, &
+        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, &
+        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, &
+        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, &
+        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, &
+        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, &
+        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, &
+        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, &
+        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, &
+        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, &
+        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, &
+        1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1  &
+    ], int32)
+
+    !> Encodes intrinsic arrays into Base64 text.
+    !>
+    !> This is the ergonomic API for encoding. It allocates and returns the
+    !> output string automatically.
+    !>
+    !> Use this form when convenience matters more than avoiding allocations.
+    !>
+    !> Example:
+    !>```fortran
+    !> character(len=:), allocatable :: encoded
+    !> integer(int8) :: bytes(3) = [77_int8, 97_int8, 110_int8]
+    !> encoded = base64_encode(bytes)  ! "TWFu"
+    !>```
+    interface base64_encode
+#:for k1, t1, _, _ in REAL_KINDS_TYPES
+        module procedure :: base64_encode_real_${k1}$
+#:endfor
+#:for k1, t1, _, _ in INT_KINDS_TYPES
+        module procedure :: base64_encode_int_${k1}$
+#:endfor
+#:for k1, t1, _ in CMPLX_KINDS_TYPES
+        module procedure :: base64_encode_cmplx_${k1}$
+#:endfor
+#:for k1, t1 in LOG_KINDS_TYPES
+        module procedure :: base64_encode_logical_${k1}$
+#:endfor
+    end interface base64_encode
+
+    interface
+#:for k1, t1, _, _ in REAL_KINDS_TYPES
+        module function base64_encode_real_${k1}$(data) result(str)
+            ${t1}$, intent(in), target, contiguous :: data(..)
+            character(len=:), allocatable :: str
+        end function base64_encode_real_${k1}$
+#:endfor
+
+#:for k1, t1, _, _ in INT_KINDS_TYPES
+        module function base64_encode_int_${k1}$(data) result(str)
+            ${t1}$, intent(in), target, contiguous :: data(..)
+            character(len=:), allocatable :: str
+        end function base64_encode_int_${k1}$
+#:endfor
+
+#:for k1, t1, _ in CMPLX_KINDS_TYPES
+        module function base64_encode_cmplx_${k1}$(data) result(str)
+            ${t1}$, intent(in), target, contiguous :: data(..)
+            character(len=:), allocatable :: str
+        end function base64_encode_cmplx_${k1}$
+#:endfor
+
+#:for k1, t1 in LOG_KINDS_TYPES
+        module function base64_encode_logical_${k1}$(data) result(str)
+            ${t1}$, intent(in), target, contiguous :: data(..)
+            character(len=:), allocatable :: str
+        end function base64_encode_logical_${k1}$
+#:endfor
+
+        module function base64_encode_bytes(bytes) result(str)
+            integer(int8), intent(in), target, contiguous :: bytes(:)
+            character(len=:), allocatable, target :: str
+        end function base64_encode_bytes
+
+        !> Encodes bytes into a caller-provided output buffer.
+        !>
+        !> This is the preallocated API for throughput-sensitive workflows.
+        !> It does not allocate and reports status through `err_state`.
+        !>
+        !> On success, `err_state%ok()` is `.true.` and `encoded_len` is the
+        !> number of meaningful characters written into `str`.
+        pure module subroutine base64_encode_into(bytes, str, encoded_len, err_state)
+            integer(int8), intent(in), target, contiguous :: bytes(:)
+            character(len=*), intent(out), target :: str
+            integer, intent(out) :: encoded_len
+            type(state_type), intent(out) :: err_state
+        end subroutine base64_encode_into
+
+        !> Decodes Base64 text into a caller-provided output buffer.
+        !>
+        !> This is the preallocated API for throughput-sensitive workflows.
+        !> It does not allocate and reports status through `err_state`.
+        !>
+        !> The optional `skip_despace` input can be used when the input is
+        !> already whitespace-free.
+        pure module subroutine base64_decode_into(str, res, decoded_len, err_state, skip_despace)
+            character(len=*), intent(in) :: str
+            character(len=*), intent(out) :: res
+            integer, intent(out) :: decoded_len
+            type(state_type), intent(out) :: err_state
+            logical, intent(in), optional :: skip_despace
+        end subroutine base64_decode_into
+
+        !> Decodes Base64 text and returns an allocated byte-string.
+        !>
+        !> This is the ergonomic API for decoding. It allocates and returns
+        !> the result automatically.
+        !>
+        !> On error, an empty result is returned. If `err_state` is present,
+        !> details are stored there.
+        !>
+        !> Example:
+        !>```fortran
+        !> character(len=:), allocatable :: decoded
+        !> decoded = base64_decode("TWFu")  ! "Man"
+        !>```
+        module function base64_decode(str, err_state) result(res)
+            character(len=*), intent(in) :: str
+            type(state_type), intent(out), optional :: err_state
+            character(len=:), allocatable :: res
+        end function base64_decode
+    end interface
+
+end module stdlib_base64