Build 0.6.5 release. Fixed.

* math: fix adjoint of Matrix2

Fix the adjoint of the Matrix2x2 implementation in the math module. This
also fixes the calculation of the inverse which depends on the adjoint.

* update release notes

.editorconfig

@@ -11,18 +11,15 @@ indent_style = space
 indent_size = 4
 
 [*.{c,cc,h}]
-indent_style = space
-indent_size = 4
+indent_style = tab
 
 [*.{c3}]
-indent_style = space
-indent_size = 4
+indent_style = tab
 
 [*.{json,toml,yml,gyp}]
 indent_style = space
 indent_size = 2
 
 [*.{py,pyi}]
-indent_style = space
-indent_size = 2
+indent_style = tab
 

.github/workflows/main.yml

@@ -51,7 +51,7 @@ jobs:
         run: |
           call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvarsall.bat" x64
           cd resources/testproject
-          ..\..\build\${{ matrix.build_type }}\c3c.exe --debug-log --emit-llvm run hello_world_win32
+          ..\..\build\${{ matrix.build_type }}\c3c.exe -vvv --emit-llvm run hello_world_win32
           dir build\llvm_ir
           ..\..\build\${{ matrix.build_type }}\c3c.exe clean
           dir build\llvm_ir
@@ -61,7 +61,13 @@ jobs:
         run: |
           cd resources/testproject
           call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvarsall.bat" x64
-          ..\..\build\${{ matrix.build_type }}\c3c.exe --debug-log build hello_world_win32_lib
+          ..\..\build\${{ matrix.build_type }}\c3c.exe -vvv build hello_world_win32_lib
+
+      - name: Compile and run dynlib-test
+        run: |
+          cd resources/examples/dynlib-test
+          ..\..\..\build\${{ matrix.build_type }}\c3c.exe dynamic-lib add.c3
+          ..\..\..\build\${{ matrix.build_type }}\c3c.exe compile-run test.c3 -l ./add.lib          
 
       - name: Vendor-fetch
         run: |
@@ -120,8 +126,8 @@ jobs:
           install: git binutils mingw-w64-x86_64-clang mingw-w64-x86_64-ninja mingw-w64-x86_64-cmake mingw-w64-x86_64-toolchain mingw-w64-x86_64-python
       - shell: msys2 {0}
         run: |
-            pacman --noconfirm -U https://mirror.msys2.org/mingw/mingw64/mingw-w64-x86_64-llvm-18.1.8-1-any.pkg.tar.zst
-            pacman --noconfirm -U https://mirror.msys2.org/mingw/mingw64/mingw-w64-x86_64-lld-18.1.8-1-any.pkg.tar.zst
+            pacman --noconfirm -U https://mirror.msys2.org/mingw/mingw64/mingw-w64-x86_64-llvm-19.1.4-1-any.pkg.tar.zst
+            pacman --noconfirm -U https://mirror.msys2.org/mingw/mingw64/mingw-w64-x86_64-lld-19.1.4-1-any.pkg.tar.zst
       - name: CMake
         run: |
           cmake -B build -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
@@ -141,7 +147,7 @@ jobs:
       - name: Build testproject
         run: |
           cd resources/testproject
-          ../../build/c3c run --debug-log
+          ../../build/c3c run -vvv
 
       - name: Vendor-fetch
         run: |
@@ -150,7 +156,7 @@ jobs:
       - name: Build testproject lib
         run: |
           cd resources/testproject
-          ../../build/c3c build hello_world_lib --cc cc --debug-log
+          ../../build/c3c build hello_world_lib --cc cc -vvv
 
       - name: run compiler tests
         run: |
@@ -197,12 +203,12 @@ jobs:
       - name: Build testproject
         run: |
           cd resources/testproject
-          ../../build/c3c run --debug-log
+          ../../build/c3c run -vvv
 
       - name: Build testproject lib
         run: |
           cd resources/testproject
-          ../../build/c3c build hello_world_lib --debug-log
+          ../../build/c3c build hello_world_lib -vvv
 
       - name: run compiler tests
         run: |
@@ -216,7 +222,7 @@ jobs:
       fail-fast: false
       matrix:
         build_type: [Release, Debug]
-        llvm_version: [17, 18, 19]
+        llvm_version: [17, 18, 19, 20]
 
     steps:
       - uses: actions/checkout@v4
@@ -311,6 +317,15 @@ jobs:
           ../build/c3c compile-run linux_stack.c3
           ../build/c3c compile-run examples/args.c3 -- foo -bar "baz baz"
 
+      - name: Compile and run dynlib-test
+        run: |
+          cd resources/examples/dynlib-test
+          ../../../build/c3c dynamic-lib add.c3
+          mv add.so libadd.so
+          cc test.c -L. -ladd -Wl,-rpath=.         
+          ./a.out
+          ../../../build/c3c compile-run test.c3 -L . -l add -z -Wl,-rpath=.           
+
       - name: Compile run unit tests
         run: |
           cd test
@@ -319,7 +334,7 @@ jobs:
       - name: Build testproject
         run: |
           cd resources/testproject
-          ../../build/c3c run --debug-log
+          ../../build/c3c run -vvv
 
       - name: Test WASM
         run: |
@@ -338,7 +353,7 @@ jobs:
       - name: Build testproject direct linker
         run: |
           cd resources/testproject
-          ../../build/c3c run --debug-log --linker=builtin
+          ../../build/c3c run -vvv --linker=builtin
 
       - name: Init a library & a project
         run: |
@@ -375,7 +390,7 @@ jobs:
       fail-fast: false
       matrix:
         build_type: [Release, Debug]
-        llvm_version: [17, 18, 19]
+        llvm_version: [17, 18, 19, 20]
     steps:
       - uses: actions/checkout@v4
       - name: Install common deps
@@ -461,12 +476,12 @@ jobs:
       - name: Build testproject
         run: |
           cd resources/testproject
-          ../../build/c3c run --debug-log
+          ../../build/c3c run -vvv
 
       - name: Build testproject direct linker
         run: |
           cd resources/testproject
-          ../../build/c3c run --debug-log --linker=builtin
+          ../../build/c3c run -vvv --linker=builtin
 
       - name: run compiler tests
         run: |
@@ -496,7 +511,7 @@ jobs:
       matrix:
         ubuntu_version: [20.04, 22.04]
         build_type: [Release, Debug]
-        llvm_version: [17, 18, 19]
+        llvm_version: [17, 18, 19, 20]
 
     steps:
       - uses: actions/checkout@v4
@@ -553,7 +568,7 @@ jobs:
       - name: Build testproject
         run: |
           cd resources/testproject
-          ../../build/c3c run --debug-log
+          ../../build/c3c run -vvv
 
       - name: Test WASM
         run: |
@@ -563,7 +578,7 @@ jobs:
       - name: Build testproject direct linker
         run: |
           cd resources/testproject
-          ../../build/c3c run --debug-log --linker=builtin
+          ../../build/c3c run -vvv --linker=builtin
 
       - name: Init a library & a project
         run: |
@@ -621,6 +636,12 @@ jobs:
           ../build/c3c compile-run -O5 examples/load_world.c3
           ../build/c3c compile-run examples/args.c3 -- foo -bar "baz baz"
 
+      - name: Compile and run dynlib-test
+        run: |
+          cd resources/examples/dynlib-test
+          ../../../build/c3c dynamic-lib add.c3
+          ../../../build/c3c compile-run test.c3 -l ./add.dylib          
+
       - name: Compile run unit tests
         run: |
           cd test
@@ -629,17 +650,17 @@ jobs:
       - name: Build testproject
         run: |
           cd resources/testproject
-          ../../build/c3c run --debug-log
+          ../../build/c3c run -vvv
 
       - name: Build testproject direct linker
         run: |
           cd resources/testproject
-          ../../build/c3c run --debug-log --linker=builtin
+          ../../build/c3c run -vvv --linker=builtin
 
       - name: Build testproject lib
         run: |
           cd resources/testproject
-          ../../build/c3c build hello_world_lib --debug-log
+          ../../build/c3c build hello_world_lib -vvv
 
       - name: run compiler tests
         run: |

.gitignore

@@ -19,6 +19,7 @@
 
 # Libraries
 *.lib
+*.tlb
 *.a
 *.la
 *.lo
@@ -75,3 +76,6 @@ TAGS
 /.cache/
 /compile_commands.json
 
+# 'nix build' resulting symlink
+result
+

CMakeLists.txt

@@ -64,6 +64,7 @@ option(C3_USE_MIMALLOC "Use built-in mimalloc" OFF)
 option(C3_USE_TB "Use TB" OFF)
 set(C3_MIMALLOC_TAG "v1.7.3" CACHE STRING "Used version of mimalloc")
 option(C3_WITH_LLVM "Build with LLVM" ON)
+option(C3_LLD_DIR "Use custom LLD directory" "")
 
 set(C3_USE_MIMALLOC OFF)
 if(C3_USE_MIMALLOC)
@@ -72,9 +73,9 @@ if(C3_USE_MIMALLOC)
     option(MI_PADDING OFF)
     option(MI_DEBUG_FULL OFF)
     FetchContent_Declare(
-    mimalloc
-    GIT_REPOSITORY https://github.com/microsoft/mimalloc.git
-    GIT_TAG ${C3_MIMALLOC_TAG}
+            mimalloc
+            GIT_REPOSITORY https://github.com/microsoft/mimalloc.git
+            GIT_TAG ${C3_MIMALLOC_TAG}
     )
     FetchContent_MakeAvailable(mimalloc)
 endif()
@@ -107,9 +108,9 @@ endif()
 # Clangd LSP support
 option(C3_ENABLE_CLANGD_LSP "Enable/Disable output of compile commands during generation." OFF)
 if(C3_ENABLE_CLANGD_LSP)
-set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+    set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
     execute_process(
-        COMMAND ${CMAKE_COMMAND} -E create_symlink
+            COMMAND ${CMAKE_COMMAND} -E create_symlink
             ${CMAKE_BINARY_DIR}/compile_commands.json
             ${CMAKE_SOURCE_DIR}/compile_commands.json
     )
@@ -118,15 +119,15 @@ endif(C3_ENABLE_CLANGD_LSP)
 if(C3_WITH_LLVM)
     if(CMAKE_C_COMPILER_ID STREQUAL "MSVC")
         if (C3_LLVM_VERSION STREQUAL "auto")
-            set(C3_LLVM_VERSION "18")
+            set(C3_LLVM_VERSION "19")
         endif()
         FetchContent_Declare(
                 LLVM_Windows
-                URL https://github.com/c3lang/win-llvm/releases/download/llvm_18_1_8_with_rt/llvm-18.1.8-windows-amd64-msvc17-libcmt.7z
+                URL https://github.com/c3lang/win-llvm/releases/download/llvm_19_1_5/llvm-19.1.5-windows-amd64-msvc17-libcmt.7z
         )
         FetchContent_Declare(
                 LLVM_Windows_debug
-                URL https://github.com/c3lang/win-llvm/releases/download/llvm_18_1_8_with_rt/llvm-18.1.8-windows-amd64-msvc17-libcmt-dbg.7z
+                URL https://github.com/c3lang/win-llvm/releases/download/llvm_19_1_5/llvm-19.1.5-windows-amd64-msvc17-libcmt-dbg.7z
         )
         if(CMAKE_BUILD_TYPE STREQUAL "Debug")
             message("Loading Windows LLVM debug libraries, this may take a while...")
@@ -172,45 +173,54 @@ if(C3_WITH_LLVM)
 
     if(NOT C3_LINK_DYNAMIC)
         set(LLVM_LINK_COMPONENTS
-            AllTargetsAsmParsers
-            AllTargetsCodeGens
-            AllTargetsDescs
-            AllTargetsDisassemblers
-            AllTargetsInfos
-            Analysis
-            AsmPrinter
-            BitReader
-            Core
-            DebugInfoPDB
-            InstCombine
-            IrReader
-            LibDriver
-            Linker
-            LTO
-            MC
-            MCDisassembler
-            native
-            nativecodegen
-            Object
-            Option
-            ScalarOpts
-            Support
-            Target
-            TransformUtils
-            WindowsManifest
-            WindowsDriver
+                AllTargetsAsmParsers
+                AllTargetsCodeGens
+                AllTargetsDescs
+                AllTargetsDisassemblers
+                AllTargetsInfos
+                Analysis
+                AsmPrinter
+                BitReader
+                Core
+                DebugInfoPDB
+                InstCombine
+                IrReader
+                LibDriver
+                Linker
+                LTO
+                MC
+                MCDisassembler
+                native
+                nativecodegen
+                Object
+                Option
+                ScalarOpts
+                Support
+                Target
+                TransformUtils
+                WindowsManifest
+                WindowsDriver
         )
 
         llvm_map_components_to_libnames(llvm_libs ${LLVM_LINK_COMPONENTS})
 
+        if(NOT ${C3_LLD_DIR} EQUAL "" AND EXISTS ${C3_LLD_DIR})
+            message("C3_LLD_DIR: " ${C3_LLD_DIR})
+            set(LLVM_LIBRARY_DIRS
+                    "${LLVM_LIBRARY_DIRS}"
+                    "${C3_LLD_DIR}"
+            )
+            list(REMOVE_DUPLICATES LLVM_LIBRARY_DIRS)
+        endif()
+
         # These don't seem to be reliable on windows.
         message(STATUS "using find_library")
-        find_library(LLD_COFF NAMES lldCOFF.lib lldCOFF.a liblldCOFF.a PATHS ${LLVM_LIBRARY_DIRS} NO_DEFAULT_PATH)
-        find_library(LLD_COMMON NAMES lldCommon.lib lldCommon.a liblldCommon.a PATHS ${LLVM_LIBRARY_DIRS} NO_DEFAULT_PATH)
-        find_library(LLD_ELF NAMES lldELF.lib lldELF.a liblldELF.a PATHS ${LLVM_LIBRARY_DIRS} NO_DEFAULT_PATH)
-        find_library(LLD_MACHO NAMES lldMachO.lib lldMachO.a liblldMachO.a PATHS ${LLVM_LIBRARY_DIRS} NO_DEFAULT_PATH)
-        find_library(LLD_MINGW NAMES lldMinGW.lib lldMinGW.a liblldMinGW.a PATHS ${LLVM_LIBRARY_DIRS} NO_DEFAULT_PATH)
-        find_library(LLD_WASM NAMES lldWasm.lib lldWasm.a liblldWasm.a PATHS ${LLVM_LIBRARY_DIRS} NO_DEFAULT_PATH)
+        find_library(LLD_COFF NAMES liblldCOFF.dylib lldCOFF.lib lldCOFF.a liblldCOFF.a PATHS ${LLVM_LIBRARY_DIRS} NO_DEFAULT_PATH)
+        find_library(LLD_COMMON NAMES liblldCommon.dylib lldCommon.lib lldCommon.a liblldCommon.a PATHS ${LLVM_LIBRARY_DIRS} NO_DEFAULT_PATH)
+        find_library(LLD_ELF NAMES liblldELF.dylib lldELF.lib lldELF.a liblldELF.a PATHS ${LLVM_LIBRARY_DIRS} NO_DEFAULT_PATH)
+        find_library(LLD_MACHO NAMES liblldMachO.dylib lldMachO.lib lldMachO.a liblldMachO.a PATHS ${LLVM_LIBRARY_DIRS} NO_DEFAULT_PATH)
+        find_library(LLD_MINGW NAMES liblldMinGW.dylib lldMinGW.lib lldMinGW.a liblldMinGW.a PATHS ${LLVM_LIBRARY_DIRS} NO_DEFAULT_PATH)
+        find_library(LLD_WASM NAMES liblldWasm.dylib lldWasm.lib lldWasm.a liblldWasm.a PATHS ${LLVM_LIBRARY_DIRS} NO_DEFAULT_PATH)
     else()
         find_library(LLVM NAMES libLLVM.so PATHS ${LLVM_LIBRARY_DIRS} NO_DEFAULT_PATH)
         set(llvm_libs ${LLVM})
@@ -234,27 +244,27 @@ endif()
 if(C3_WITH_LLVM)
     find_library(LLD_LOONG NAMES libLLVMLoongArchCodeGen.lib libLLVMLoongArchAsmParser.lib libLLVMLoongArchCodeGen.a libLLVMLoongArchAsmParser.a PATHS ${LLVM_LIBRARY_DIRS} NO_DEFAULT_PATH)
     set(lld_libs
-        ${LLD_COFF}
-        ${LLD_COMMON}
-        ${LLD_WASM}
-        ${LLD_MINGW}
-        ${LLD_ELF}
-        ${LLD_MACHO}
-        )
+            ${LLD_COFF}
+            ${LLD_COMMON}
+            ${LLD_WASM}
+            ${LLD_MINGW}
+            ${LLD_ELF}
+            ${LLD_MACHO}
+    )
 
     if (APPLE)
         set(lld_libs ${lld_libs} xar)
-        find_file(RT_ASAN_DYNAMIC NAMES libclang_rt.asan_osx_dynamic.dylib PATHS "${LLVM_LIBRARY_DIRS}/clang/${LLVM_MAJOR_VERSION}/lib/darwin")
-        find_file(RT_TSAN_DYNAMIC NAMES libclang_rt.tsan_osx_dynamic.dylib PATHS "${LLVM_LIBRARY_DIRS}/clang/${LLVM_MAJOR_VERSION}/lib/darwin")
-        find_file(RT_UBSAN_DYNAMIC NAMES libclang_rt.ubsan_osx_dynamic.dylib PATHS "${LLVM_LIBRARY_DIRS}/clang/${LLVM_MAJOR_VERSION}/lib/darwin")
-        find_file(RT_LSAN_DYNAMIC NAMES libclang_rt.lsan_osx_dynamic.dylib PATHS "${LLVM_LIBRARY_DIRS}/clang/${LLVM_MAJOR_VERSION}/lib/darwin")
+        find_file(RT_ASAN_DYNAMIC NAMES libclang_rt.asan_osx_dynamic.dylib PATHS "${LLVM_LIBRARY_DIR}/clang/${LLVM_MAJOR_VERSION}/lib/darwin")
+        find_file(RT_TSAN_DYNAMIC NAMES libclang_rt.tsan_osx_dynamic.dylib PATHS "${LLVM_LIBRARY_DIR}/clang/${LLVM_MAJOR_VERSION}/lib/darwin")
+        find_file(RT_UBSAN_DYNAMIC NAMES libclang_rt.ubsan_osx_dynamic.dylib PATHS "${LLVM_LIBRARY_DIR}/clang/${LLVM_MAJOR_VERSION}/lib/darwin")
+        find_file(RT_LSAN_DYNAMIC NAMES libclang_rt.lsan_osx_dynamic.dylib PATHS "${LLVM_LIBRARY_DIR}/clang/${LLVM_MAJOR_VERSION}/lib/darwin")
         set(sanitizer_runtime_libraries
                 ${RT_ASAN_DYNAMIC}
                 ${RT_TSAN_DYNAMIC}
                 # Unused
                 # ${RT_UBSAN_DYNAMIC}
                 # ${RT_LSAN_DYNAMIC}
-            )
+        )
     endif()
 
     message(STATUS "linking to llvm libs ${lld_libs}")
@@ -333,10 +343,10 @@ add_executable(c3c
         src/utils/cpus.c
         src/utils/unzipper.c
         src/compiler/decltable.c
-        src/compiler/mac_support.c 
+        src/compiler/mac_support.c
         src/compiler/windows_support.c
         src/compiler/codegen_asm.c
-        src/compiler/asm_target.c 
+        src/compiler/asm_target.c
         src/compiler/expr.c
         src/utils/time.c
         src/utils/http.c
@@ -344,7 +354,7 @@ add_executable(c3c
         src/build/common_build.c
         src/compiler/sema_const.c
         ${CMAKE_BINARY_DIR}/git_hash.h
-        )
+)
 
 if(GIT_FOUND AND EXISTS "${CMAKE_SOURCE_DIR}/.git")
     # We are inside of a git repository so rebuilding the hash every time something changes.
@@ -360,18 +370,18 @@ else()
 endif()
 
 if(C3_WITH_LLVM)
-    target_sources(c3c PRIVATE 
-        src/compiler/llvm_codegen.c
-        src/compiler/llvm_codegen_debug_info.c
-        src/compiler/llvm_codegen_expr.c
-        src/compiler/llvm_codegen_function.c
-        src/compiler/llvm_codegen_instr.c
-        src/compiler/llvm_codegen_module.c
-        src/compiler/llvm_codegen_stmt.c
-        src/compiler/llvm_codegen_type.c
-        src/compiler/llvm_codegen_value.c
-        src/compiler/llvm_codegen_storeload.c
-        src/compiler/llvm_codegen_builtins.c)
+    target_sources(c3c PRIVATE
+            src/compiler/llvm_codegen.c
+            src/compiler/llvm_codegen_debug_info.c
+            src/compiler/llvm_codegen_expr.c
+            src/compiler/llvm_codegen_function.c
+            src/compiler/llvm_codegen_instr.c
+            src/compiler/llvm_codegen_module.c
+            src/compiler/llvm_codegen_stmt.c
+            src/compiler/llvm_codegen_type.c
+            src/compiler/llvm_codegen_value.c
+            src/compiler/llvm_codegen_storeload.c
+            src/compiler/llvm_codegen_builtins.c)
 
     target_compile_definitions(c3c PUBLIC LLVM_AVAILABLE=1)
     add_library(c3c_wrappers STATIC wrapper/src/wrapper.cpp)
@@ -399,7 +409,7 @@ if (C3_USE_TB)
             tilde-backend/src/tb/x64/*.c
             tilde-backend/src/tb/wasm/*.c
             tilde-backend/src/tb/aarch64/*.c
-            )
+    )
     target_sources(c3c PRIVATE
             src/compiler/tilde_codegen.c
             src/compiler/tilde_codegen_instr.c
@@ -437,7 +447,7 @@ if(C3_WITH_LLVM)
 
     target_link_libraries(c3c_wrappers ${llvm_libs} ${lld_libs})
 
-else() 
+else()
 
     target_link_libraries(c3c ${llvm_libs} miniz ${lld_libs})
 
@@ -497,10 +507,10 @@ if(MSVC)
     if(C3_WITH_LLVM)
         set(clang_lib_dir ${llvm_dir}/lib/clang/${C3_LLVM_VERSION}/lib/windows)
         set(sanitizer_runtime_libraries
-            ${clang_lib_dir}/clang_rt.asan-x86_64.lib
-            ${clang_lib_dir}/clang_rt.asan_dynamic-x86_64.lib
-            ${clang_lib_dir}/clang_rt.asan_dynamic-x86_64.dll
-            ${clang_lib_dir}/clang_rt.asan_dynamic_runtime_thunk-x86_64.lib)
+                ${clang_lib_dir}/clang_rt.asan-x86_64.lib
+                ${clang_lib_dir}/clang_rt.asan_dynamic-x86_64.lib
+                ${clang_lib_dir}/clang_rt.asan_dynamic-x86_64.dll
+                ${clang_lib_dir}/clang_rt.asan_dynamic_runtime_thunk-x86_64.lib)
     endif()
 else()
     message(STATUS "using gcc/clang warning switches")
@@ -515,19 +525,24 @@ endif()
 install(TARGETS c3c DESTINATION bin)
 install(DIRECTORY lib/ DESTINATION lib/c3)
 
+# Man page install (OSX/Linux only)
+if (NOT WIN32)
+    install(FILES c3c.1 DESTINATION "share/man/man1")
+endif()
+
 if (C3_WITH_LLVM AND DEFINED sanitizer_runtime_libraries)
     add_custom_command(TARGET c3c POST_BUILD
-        COMMAND "${CMAKE_COMMAND}" -E rm -rf -- $<TARGET_FILE_DIR:c3c>/c3c_rt
-        COMMAND "${CMAKE_COMMAND}" -E make_directory $<TARGET_FILE_DIR:c3c>/c3c_rt
-        COMMAND "${CMAKE_COMMAND}" -E copy ${sanitizer_runtime_libraries} $<TARGET_FILE_DIR:c3c>/c3c_rt
-        VERBATIM
-        COMMENT "Copying sanitizer runtime libraries to output directory")
+            COMMAND "${CMAKE_COMMAND}" -E rm -rf -- $<TARGET_FILE_DIR:c3c>/c3c_rt
+            COMMAND "${CMAKE_COMMAND}" -E make_directory $<TARGET_FILE_DIR:c3c>/c3c_rt
+            COMMAND "${CMAKE_COMMAND}" -E copy ${sanitizer_runtime_libraries} $<TARGET_FILE_DIR:c3c>/c3c_rt
+            VERBATIM
+            COMMENT "Copying sanitizer runtime libraries to output directory")
 
     if (APPLE)
         # Change LC_ID_DYLIB to be rpath-based instead of having an absolute path
         add_custom_command(TARGET c3c POST_BUILD
-            COMMAND find $<TARGET_FILE_DIR:c3c>/c3c_rt -type f -name "*.dylib" -execdir ${LLVM_TOOLS_BINARY_DIR}/llvm-install-name-tool -id @rpath/{} {} $<SEMICOLON>
-            VERBATIM)
+                COMMAND find $<TARGET_FILE_DIR:c3c>/c3c_rt -type f -name "*.dylib" -execdir ${LLVM_TOOLS_BINARY_DIR}/llvm-install-name-tool -id @rpath/{} {} $<SEMICOLON>
+                VERBATIM)
     endif()
 
     install(DIRECTORY $<TARGET_FILE_DIR:c3c>/c3c_rt/ DESTINATION bin/c3c_rt)

README.md

@@ -55,7 +55,7 @@ fn void Stack.push(Stack* this, Type element)
     if (this.capacity == this.size)
     {
         this.capacity *= 2;
-		if (this.capacity < 16) this.capacity = 16;
+        if (this.capacity < 16) this.capacity = 16;
         this.elems = realloc(this.elems, Type.sizeof * this.capacity);
     }
     this.elems[this.size++] = element;
@@ -138,7 +138,7 @@ fn void main()
 
 ### Current status
 
-The current stable version of the compiler is **version 0.6.2**.
+The current stable version of the compiler is **version 0.6.4**.
 
 The upcoming 0.6.x releases will focus on expanding the standard library.
 Follow the issues [here](https://github.com/c3lang/c3c/issues).
@@ -303,7 +303,7 @@ called `hello_world` or `hello_world.exe`depending on platform.
 
 #### Compiling on Windows
 
-1. Make sure you have Visual Studio 17 2022 installed or alternatively install the "Buildtools for Visual Studio" (https://aka.ms/vs/17/release/vs_BuildTools.exe) and then select "Desktop development with C++" (there is also `c3c/resources/install_win_reqs.bat` to automate this)
+1. Make sure you have Visual Studio 17 2022 installed or alternatively install the "Buildtools for Visual Studio" (https://aka.ms/vs/17/release/vs_BuildTools.exe) and then select "Desktop development with C++"
 2. Install CMake
 3. Clone the C3C github repository: `git clone https://github.com/c3lang/c3c.git`
 4. Enter the C3C directory `cd c3c`.
@@ -385,6 +385,6 @@ Editor plugins can be found at https://github.com/c3lang/editor-plugins.
 
 ## Thank yous
 
-A huge "thank you" goes out to all contributors and sponsors.
+A huge **THANK YOU** goes out to all contributors and sponsors.
 
-A special thank you to sponsor [Caleb-o](https://github.com/Caleb-o) for going the extra mile.
+A special thank you to sponsors [Caleb-o](https://github.com/Caleb-o) and [devdad](https://github.com/devdad) for going the extra mile.

benchmarks/stdlib/sort/quicksort.c3

@@ -0,0 +1,69 @@
+module sort_bench;
+
+import std::sort;
+
+fn void init() @init
+{
+    set_benchmark_warmup_iterations(5);
+    set_benchmark_max_iterations(10_000);
+}
+
+fn void! quicksort_bench() @benchmark
+{
+	// test set: 500 numbers between 0 and 99;
+	int[] data = {
+		71, 28, 2, 13, 62, 10, 54, 78, 63, 86,
+		33, 65, 89, 51, 58, 0, 51, 16, 87, 30,
+		89, 14, 52, 41, 88, 25, 83, 91, 56, 86,
+		14, 64, 76, 18, 39, 24, 79, 62, 34, 58,
+		90, 24, 56, 73, 85, 82, 79, 63, 47, 69,
+		78, 29, 49, 28, 43, 47, 56, 53, 79, 56,
+		19, 63, 29, 52, 71, 93, 61, 46, 30, 11,
+		21, 26, 37, 86, 93, 74, 62, 0, 41, 17,
+		26, 27, 34, 11, 54, 69, 72, 44, 74, 3,
+		61, 62, 80, 90, 3, 82, 16, 12, 28, 1,
+		2, 49, 4, 44, 57, 86, 63, 74, 33, 41,
+		76, 77, 56, 57, 56, 88, 74, 71, 6, 59,
+		40, 42, 94, 55, 21, 17, 17, 63, 21, 83,
+		73, 19, 39, 88, 93, 74, 21, 0, 63, 45,
+		69, 66, 22, 68, 86, 86, 85, 67, 8, 50,
+		23, 98, 64, 80, 64, 36, 40, 30, 73, 36,
+		23, 14, 1, 77, 82, 8, 18, 73, 37, 86,
+		29, 70, 27, 87, 64, 81, 13, 0, 4, 83,
+		90, 17, 71, 66, 38, 39, 54, 22, 86, 18,
+		84, 66, 77, 25, 64, 93, 80, 91, 2, 92,
+		47, 32, 90, 16, 46, 29, 56, 87, 70, 73,
+		89, 41, 5, 54, 93, 63, 16, 39, 71, 84,
+		74, 91, 69, 59, 49, 87, 74, 37, 75, 83,
+		77, 19, 51, 44, 79, 62, 94, 20, 24, 83,
+		37, 70, 57, 32, 93, 8, 29, 11, 7, 92,
+		8, 23, 20, 21, 7, 70, 28, 20, 96, 6,
+		50, 58, 30, 61, 66, 42, 50, 54, 64, 7,
+		10, 53, 63, 44, 16, 39, 83, 73, 3, 29,
+		97, 32, 36, 68, 84, 64, 73, 5, 29, 13,
+		48, 3, 84, 65, 75, 68, 66, 22, 39, 33,
+		39, 24, 27, 85, 18, 34, 3, 63, 32, 9,
+		29, 66, 24, 90, 75, 50, 11, 95, 47, 14,
+		92, 1, 76, 45, 76, 41, 55, 54, 38, 67,
+		43, 40, 5, 61, 97, 11, 61, 24, 92, 24,
+		76, 53, 60, 34, 78, 80, 70, 75, 30, 90,
+		65, 99, 80, 61, 94, 75, 63, 67, 10, 35,
+		23, 42, 31, 48, 14, 68, 84, 14, 79, 1,
+		25, 94, 23, 53, 49, 69, 44, 73, 63, 51,
+		44, 96, 88, 51, 94, 24, 64, 72, 59, 81,
+		73, 93, 14, 35, 9, 53, 25, 48, 50, 88,
+		46, 97, 67, 40, 27, 17, 2, 42, 11, 82,
+		0, 46, 44, 38, 31, 88, 63, 88, 10, 82,
+		77, 61, 24, 39, 27, 33, 10, 91, 69, 22,
+		42, 74, 71, 13, 32, 56, 12, 46, 81, 74,
+		17, 26, 45, 50, 76, 84, 76, 36, 43, 65,
+		81, 64, 0, 49, 70, 11, 76, 19, 60, 55,
+		15, 98, 31, 91, 56, 8, 97, 9, 3, 94,
+		3, 88, 7, 2, 3, 98, 10, 51, 21, 79,
+		99, 3, 8, 76, 52, 13, 40, 90, 85, 15,
+		70, 77, 43, 30, 4, 89, 18, 21, 59, 17,
+	};
+	sort::quicksort(data);
+}
+
+

c3c.1

@@ -0,0 +1,552 @@
+.TH "c3c" "1" "2024-10-27" "C3 Compiler" "User Commands"
+.SH NAME
+c3c \- Compiler for the C3 programming language
+
+.SH SYNOPSIS
+.B c3c
+[\fIoptions\fR ...] \fIcommand\fR [\fIargs\fR ...]
+
+.SH DESCRIPTION
+.B c3c
+is the compiler for the C3 language, providing commands for compilation, project
+management, testing, and distribution. The available commands allow users to 
+compile files, initialize projects, build targets, run benchmarks, clean build 
+files, and more.
+
+.SH COMMANDS
+.PP
+.B c3c compile 
+\fIfile1\fR [\fIfile2\fR ...]
+.RS
+Compile files without a project into an executable.
+.RE
+.PP
+.B c3c init 
+\fIproject name\fR
+.RS
+Initialize a new project structure.
+.RE
+.PP
+.B c3c init-lib 
+\fIlibrary name\fR
+.RS
+Initialize a new library structure.
+.RE
+.PP
+.B c3c build 
+[\fItarget\fR]
+.RS
+Build the target in the current project.
+.RE
+.PP
+.B c3c benchmark
+.RS
+Run the benchmarks in the current project.
+.RE
+.PP
+.B c3c test
+.RS
+Run the unit tests in the current project.
+.RE
+.PP
+.B c3c clean
+.RS
+Clean all build files.
+.RE
+.PP
+.B c3c run 
+[\fItarget\fR] [-- [\fIarg1\fR ...]]
+.RS
+Run (and build if needed) the target in the current project.
+.RE
+.PP
+.B c3c dist 
+[\fItarget\fR]
+.RS
+Clean and build a target for distribution.
+.RE
+.PP
+.B c3c directives 
+[\fItarget\fR]
+.RS
+Generate documentation for the target.
+.RE
+.PP
+.B c3c bench 
+[\fItarget\fR]
+.RS
+Benchmark a target.
+.RE
+.PP
+.B c3c clean-run 
+[\fItarget\fR] [-- [\fIarg1\fR ...]]
+.RS
+Clean, then run the target.
+.RE
+.PP
+.B c3c compile-run 
+\fIfile1\fR [\fIfile2\fR ...] [-- [\fIarg1\fR ...]]
+.RS
+Compile files then immediately run the result.
+.RE
+.PP
+.B c3c compile-only 
+\fIfile1\fR [\fIfile2\fR ...]
+.RS
+Compile files but do not perform linking.
+.RE
+.PP
+.B c3c compile-benchmark 
+\fIfile1\fR [\fIfile2\fR ...]
+.RS
+Compile files into an executable and run benchmarks.
+.RE
+.PP
+.B c3c compile-test 
+\fIfile1\fR [\fIfile2\fR ...]
+.RS
+Compile files into an executable and run unit tests.
+.RE
+.PP
+.B c3c static-lib 
+\fIfile1\fR [\fIfile2\fR ...]
+.RS
+Compile files without a project into a static library.
+.RE
+.PP
+.B c3c dynamic-lib 
+\fIfile1\fR [\fIfile2\fR ...]
+.RS
+Compile files without a project into a dynamic library.
+.RE
+.PP
+.B c3c headers 
+\fIfile1\fR [\fIfile2\fR ...]
+.RS
+Analyze files and generate C headers for public methods.
+.RE
+.PP
+.B c3c vendor-fetch 
+\fIlibrary\fR ...
+.RS
+Fetch one or more libraries from the vendor collection.
+.RE
+.PP
+.B c3c project 
+\fIsubcommand\fR ...
+.RS
+Manipulate or view project files.
+.RE
+
+.SH OPTIONS
+.PP
+.B --stdlib 
+\fIdir\fR
+.RS
+Use this directory as the C3 standard library path.
+.RE
+.PP
+.B --no-entry
+.RS
+Do not generate (or require) a main function.
+.RE
+.PP
+.B --libdir 
+\fIdir\fR
+.RS
+Add this directory to the C3 library search paths.
+.RE
+.PP
+.B --lib 
+\fIname\fR
+.RS
+Add this library to the compilation.
+.RE
+.PP
+.B --path 
+\fIdir\fR
+.RS
+Use this as the base directory for the current command.
+.RE
+.PP
+.B --template 
+\fItemplate\fR
+.RS
+Select template for 'init': "exe", "static-lib", "dynamic-lib" or a path.
+.RE
+.PP
+.B --about
+Prints a short description of C3.
+.PP
+.B --symtab 
+\fIvalue\fR
+.RS
+Sets the preferred symtab size.
+.RE
+.PP
+.B --max-mem 
+\fIvalue\fR
+.RS
+Sets the preferred max memory size.
+.RE
+.PP
+.B --run-once
+.RS
+After running the output file, delete it immediately.
+.RE
+.PP
+.B -V, --version
+Print version information.
+.PP
+.B -E
+Lex only.
+.PP
+.B -P
+Only parse and output the AST as JSON.
+.PP
+.B -C
+Only lex, parse and check.
+.PP
+.B -
+\fIcode\fR...
+.RS
+Read code from standard in.
+.RE
+.PP
+.B -o 
+\fIfile\fR
+.RS
+Write output to \fIfile\fR.
+.RE
+.PP
+.B -O0
+Safe, no optimizations, emit debug info.
+.PP
+.B -O1
+Safe, high optimization, emit debug info.
+.PP
+.B -O2
+Unsafe, high optimization, emit debug info.
+.PP
+.B -O3
+Unsafe, high optimization, single module, emit debug info.
+.PP
+.B -O4
+Unsafe, highest optimization, relaxed maths, single module, emit debug info, no panic messages.
+.PP
+.B -O5
+Unsafe, highest optimization, fast maths, single module, emit debug info, no panic messages, no backtrace.
+.PP
+.B -Os
+Unsafe, high optimization, small code, single module, no debug info, no panic messages.
+.PP
+.B -Oz
+Unsafe, high optimization, tiny code, single module, no debug info, no panic messages, no backtrace.
+.PP
+.B -D 
+\fIname\fR
+.RS
+Add feature flag \fIname\fR.
+.RE
+.PP
+.B -U 
+\fIname\fR
+.RS
+Remove feature flag \fIname\fR.
+.RE
+.PP
+.B --trust=
+\fIoption\fR
+.RS
+Trust level: none (default), include ($include allowed), full ($exec / exec allowed).
+.RE
+.PP
+.B --output-dir 
+\fIdir\fR
+.RS
+Override general output directory.
+.RE
+.PP
+.B --threads 
+\fInumber\fR
+.RS
+Set the number of threads to use for compilation.
+.RE
+.PP
+.B --show-backtrace=
+\fIyes|no\fR
+.RS
+Show detailed backtrace on segfaults.
+.RE
+
+.PP
+.B -g
+Emit debug info.
+.PP
+.B -g0
+Emit no debug info.
+
+
+.PP
+.B -l 
+\fIlibrary\fR
+.RS
+Link with the library provided.
+.RE
+.PP
+.B -L 
+\fIlibrary\fR \fIdir\fR
+.RS
+Append the directory to the linker search paths.
+.RE
+.PP
+.B -z 
+\fIargument\fR
+.RS
+Send the \fIargument\fR as a parameter to the linker.
+.RE
+.PP
+.B --cc 
+\fIpath\fR
+.RS
+Set C compiler (for C files in projects and use as system linker).
+.RE
+.PP
+.B --linker=
+\fIoption\fR [\fIpath\fR]
+.RS
+Specify the linker: builtin, cc, custom (default is 'cc'). 'Custom' requires a path.
+.RE
+
+.PP
+.B --use-stdlib=
+\fIyes|no\fR
+.RS
+Include the standard library (default: yes).
+.RE
+.PP
+.B --link-libc=
+\fIyes|no\fR
+.RS
+Link libc and other default libraries (default: yes).
+.RE
+.PP
+.B --emit-stdlib=
+\fIyes|no\fR
+.RS
+Output files for the standard library (default: yes).
+.RE
+.PP
+.B --panicfn 
+\fIname\fR
+.RS
+Override the panic function name.
+.RE
+.PP
+.B --testfn 
+\fIname\fR
+.RS
+Override the test runner function name.
+.RE
+.PP
+.B --benchfn 
+\fIname\fR
+.RS
+Override the benchmark runner function name.
+.RE
+
+.PP
+.B --reloc=
+\fIoption\fR
+.RS
+Specify the relocation model: none, pic, PIC, pie, PIE.
+.RE
+.PP
+.B --x86cpu=
+\fIoption\fR
+.RS
+Set general level of x64 CPU: baseline, ssse3, sse4, avx1, avx2-v1, avx2-v2 (Skylake/Zen1+), avx512 (Icelake/Zen4+), native.
+.RE
+.PP
+.B --x86vec=
+\fIoption\fR
+.RS
+Set maximum type of vector use: none, mmx, sse, avx, avx512, default.
+.RE
+.PP
+.B --riscvfloat=
+\fIoption\fR
+.RS
+Set type of RISC-V float support: none, float, double.
+.RE
+.PP
+.B --memory-env=
+\fIoption\fR
+.RS
+Set the memory environment: normal, small, tiny, none.
+.RE
+.PP
+.B --strip-unused=
+\fIyes|no\fR
+.RS
+Strip unused code and globals from the output (default: yes).
+.RE
+.PP
+.B --fp-math=
+\fIoption\fR
+.RS
+Specify floating-point math behavior: strict, relaxed, fast.
+.RE
+.PP
+.B --win64-simd=
+\fIoption\fR
+.RS
+Windows SIMD ABI: array, full.
+.RE
+
+.PP
+.B --debug-stats
+Print debug statistics.
+.PP
+.B --print-linking
+Print linker arguments.
+.PP
+.B --debug-log
+Print debug logging to stdout.
+
+
+.PP
+.B --benchmarking
+Run built-in benchmarks.
+.PP
+.B --testing
+Run built-in tests.
+
+
+.PP
+.B --list-attributes
+List all attributes.
+.PP
+.B --list-builtins
+List all builtins.
+.PP
+.B --list-keywords
+List all keywords.
+.PP
+.B --list-operators
+List all operators.
+.PP
+.B --list-precedence
+List operator precedence order.
+.PP
+.B --list-project-properties
+List all available keys used in project.json files.
+.PP
+.B --list-manifest-properties
+List all available keys used in manifest.json files.
+.PP
+.B --list-targets
+List all architectures the compiler supports.
+.PP
+.B --list-type-properties
+List all type properties.
+
+
+.PP
+.B --print-output
+Print the object files created to stdout.
+.PP
+.B --print-input
+Print inputted C3 files to stdout.
+
+
+.PP
+.B --winsdk 
+\fIdir\fR
+.RS
+Set the directory for Windows system library files for cross-compilation.
+.RE
+.PP
+.B --wincrt=
+\fIoption\fR
+.RS
+Windows CRT linking: none, static-debug, static, dynamic-debug (default if debug info enabled), dynamic (default).
+.RE
+.PP
+.B --windef 
+\fIfile\fR
+.RS
+Use Windows 'def' file for function exports instead of 'dllexport'.
+.RE
+
+.PP
+.B --macossdk 
+\fIdir\fR
+.RS
+Set the directory for the MacOS SDK for cross-compilation.
+.RE
+.PP
+.B --macos-min-version 
+\fIver\fR
+.RS
+Set the minimum MacOS version to compile for.
+.RE
+.PP
+.B --macos-sdk-version 
+\fIver\fR
+.RS
+Set the MacOS SDK version to compile for.
+.RE
+
+.PP
+.B --linux-crt 
+\fIdir\fR
+.RS
+Set the directory to use for finding crt1.o and related files.
+.RE
+.PP
+.B --linux-crtbegin 
+\fIdir\fR
+.RS
+Set the directory to use for finding crtbegin.o and related files.
+.RE
+
+.PP
+.B --vector-conv=
+\fIoption\fR
+.RS
+Set vector conversion behavior: default, old.
+.RE
+.PP
+.B --sanitize=
+\fIoption\fR
+.RS
+Enable a sanitizer: address, memory, thread.
+.RE
+
+.SH EXAMPLES
+.PP
+Create a project:
+.RS
+.B c3c init new_project
+.RE
+.PP
+Create a library project:
+.RS
+.B c3c init-lib new_library
+.RE
+.PP
+Compile a file:
+.RS
+.B c3c compile main.c3
+.RE
+.PP
+Build the current project:
+.RS
+.B c3c build
+.RE
+.PP
+Run tests for the current project:
+.RS
+.B c3c test
+.RE

flake.lock

@@ -0,0 +1,61 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1726560853,
+        "narHash": "sha256-X6rJYSESBVr3hBoH0WbKE5KvhPU5bloyZ2L4K60/fPQ=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "c1dfcf08411b08f6b8615f7d8971a2bfa81d5e8a",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1730958623,
+        "narHash": "sha256-JwQZIGSYnRNOgDDoIgqKITrPVil+RMWHsZH1eE1VGN0=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "85f7e662eda4fa3a995556527c87b2524b691933",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,35 @@
+{
+  description = "C3 compiler flake";
+
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs?ref=nixpkgs-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs = { self, ... } @ inputs: inputs.flake-utils.lib.eachDefaultSystem 
+  (system: 
+    let pkgs = import inputs.nixpkgs { inherit system; }; in 
+    {
+      packages = {
+        default = self.packages.${system}.c3c;
+
+        c3c = pkgs.callPackage ./nix/default.nix {};
+
+        c3c-debug = pkgs.callPackage ./nix/default.nix { 
+          debug = true; 
+        };
+
+        c3c-nochecks = pkgs.callPackage ./nix/default.nix { 
+          debug = true; 
+          checks = false; 
+        };
+      };
+
+      devShells = {
+        default = pkgs.callPackage ./nix/shell.nix {
+          c3c = self.packages.${system}.c3c-nochecks; 
+        };
+      };
+    }
+  );
+}

lib/std/ascii.c3

@@ -53,9 +53,9 @@ fn bool char.is_blank(char c) => is_blank_m(c);
 fn bool char.is_cntrl(char c) => is_cntrl_m(c);
 fn char char.to_lower(char c) => (char)to_lower_m(c);
 fn char char.to_upper(char c) => (char)to_upper_m(c);
-/**
- * @require c.is_xdigit()
- **/
+<*
+ @require c.is_xdigit()
+*>
 fn char char.from_hex(char c) => c.is_digit() ? c - '0' : 10 + (c | 0x20) - 'a';
 
 fn bool uint.in_range(uint c, uint start, uint len) => in_range_m(c, start, len);

lib/std/atomic.c3

@@ -8,12 +8,12 @@ struct Atomic
 	Type data;
 }
 
-/**
- * Loads data atomically, by default this uses SEQ_CONSISTENT ordering.
- *
- * @param ordering "The ordering, cannot be release or acquire-release."
- * @require ordering != RELEASE && ordering != ACQUIRE_RELEASE : "Release and acquire-release are not valid for load"
- **/
+<*
+ Loads data atomically, by default this uses SEQ_CONSISTENT ordering.
+
+ @param ordering "The ordering, cannot be release or acquire-release."
+ @require ordering != RELEASE && ordering != ACQUIRE_RELEASE : "Release and acquire-release are not valid for load"
+*>
 macro Type Atomic.load(&self, AtomicOrdering ordering = SEQ_CONSISTENT)
 {
 	Type* data = &self.data;
@@ -28,12 +28,12 @@ macro Type Atomic.load(&self, AtomicOrdering ordering = SEQ_CONSISTENT)
 		case RELEASE: unreachable("Invalid ordering.");
 	}
 }
-/**
- * Stores data atomically, by default this uses SEQ_CONSISTENT ordering.
- *
- * @param ordering "The ordering, cannot be acquire or acquire-release."
- * @require ordering != ACQUIRE && ordering != ACQUIRE_RELEASE : "Acquire and acquire-release are not valid for store"
- **/
+<*
+ Stores data atomically, by default this uses SEQ_CONSISTENT ordering.
+
+ @param ordering "The ordering, cannot be acquire or acquire-release."
+ @require ordering != ACQUIRE && ordering != ACQUIRE_RELEASE : "Acquire and acquire-release are not valid for store"
+*>
 macro void Atomic.store(&self, Type value, AtomicOrdering ordering = SEQ_CONSISTENT)
 {
 	Type* data = &self.data;
@@ -131,16 +131,16 @@ macro @atomic_exec(#func, data, value, ordering) @local
 module std::atomic;
 import std::math;
 
-/**
- * @param [&in] ptr "the variable or dereferenced pointer to the data."
- * @param [in] y "the value to be added to ptr."
- * @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
- * @return "returns the old value of ptr"
- *
- * @require !$alignment || math::is_power_of_2($alignment) "Alignment must be a power of two."
- * @require types::is_int($typeof(*ptr)) || types::is_float($typeof(*ptr)) "Only integer/float pointers may be used."
- * @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- **/
+<*
+ @param [&in] ptr "the variable or dereferenced pointer to the data."
+ @param [in] y "the value to be added to ptr."
+ @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
+ @return "returns the old value of ptr"
+
+ @require !$alignment || math::is_power_of_2($alignment) "Alignment must be a power of two."
+ @require types::is_int($typeof(*ptr)) || types::is_float($typeof(*ptr)) "Only integer/float pointers may be used."
+ @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+*>
 macro fetch_add(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT, bool $volatile = false, usz $alignment = 0)
 {
 	$if $alignment == 0:
@@ -149,16 +149,16 @@ macro fetch_add(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT, bool $volatil
 	return $$atomic_fetch_add(ptr, y, $volatile, $ordering.ordinal, $alignment);
 }
 
-/**
- * @param [&in] ptr "the variable or dereferenced pointer to the data."
- * @param [in] y "the value to be added to ptr."
- * @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
- * @return "returns the old value of ptr"
- * 
- * @require !$alignment || math::is_power_of_2($alignment) "Alignment must be a power of two."
- * @require types::is_int($typeof(*ptr)) || types::is_float($typeof(*ptr)) "Only integer/float pointers may be used."
- * @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- **/
+<*
+ @param [&in] ptr "the variable or dereferenced pointer to the data."
+ @param [in] y "the value to be added to ptr."
+ @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
+ @return "returns the old value of ptr"
+
+ @require !$alignment || math::is_power_of_2($alignment) "Alignment must be a power of two."
+ @require types::is_int($typeof(*ptr)) || types::is_float($typeof(*ptr)) "Only integer/float pointers may be used."
+ @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+*>
 macro fetch_sub(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT, bool $volatile = false, usz $alignment = 0)
 {
 	$if $alignment == 0:
@@ -167,15 +167,15 @@ macro fetch_sub(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT, bool $volatil
 	return $$atomic_fetch_sub(ptr, y, $volatile, $ordering.ordinal, $alignment);
 }
 
-/**
- * @param [&in] ptr "the variable or dereferenced pointer to the data."
- * @param [in] y "the value to be added to ptr."
- * @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
- * @return "returns the old value of ptr"
- * 
- * @require types::is_int($typeof(*ptr)) || types::is_float($typeof(*ptr)) "Only integer/float pointers may be used."
- * @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- **/
+<*
+ @param [&in] ptr "the variable or dereferenced pointer to the data."
+ @param [in] y "the value to be added to ptr."
+ @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
+ @return "returns the old value of ptr"
+
+ @require types::is_int($typeof(*ptr)) || types::is_float($typeof(*ptr)) "Only integer/float pointers may be used."
+ @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+*>
 macro fetch_mul(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT)
 {
 	var $load_ordering = $ordering;
@@ -204,15 +204,15 @@ macro fetch_mul(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT)
 	return old_value;
 }
 
-/**
- * @param [&in] ptr "the variable or dereferenced pointer to the data."
- * @param [in] y "the value to be added to ptr."
- * @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
- * @return "returns the old value of ptr"
- * 
-* @require types::is_int($typeof(*ptr)) || types::is_float($typeof(*ptr)) "Only integer/float pointers may be used."
-* @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- **/
+<*
+ @param [&in] ptr "the variable or dereferenced pointer to the data."
+ @param [in] y "the value to be added to ptr."
+ @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
+ @return "returns the old value of ptr"
+
+ @require types::is_int($typeof(*ptr)) || types::is_float($typeof(*ptr)) "Only integer/float pointers may be used."
+ @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+*>
 macro fetch_div(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT)
 {
 	var $load_ordering = $ordering;
@@ -240,17 +240,17 @@ macro fetch_div(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT)
 	return old_value;
 }
 
-/**
- * @param [&in] ptr "the variable or dereferenced pointer to the data."
- * @param [in] y "the value to be added to ptr."
- * @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
- * @return "returns the old value of ptr"
- * 
- * @require !$alignment || math::is_power_of_2($alignment) "Alignment must be a power of two."
- * @require types::is_int($typeof(*ptr)) "Only integer pointers may be used."
- * @require types::is_int($typeof(y)) "The value for or must be an int"
- * @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- **/
+<*
+ @param [&in] ptr "the variable or dereferenced pointer to the data."
+ @param [in] y "the value to be added to ptr."
+ @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
+ @return "returns the old value of ptr"
+
+ @require !$alignment || math::is_power_of_2($alignment) "Alignment must be a power of two."
+ @require types::is_int($typeof(*ptr)) "Only integer pointers may be used."
+ @require types::is_int($typeof(y)) "The value for or must be an int"
+ @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+*>
 macro fetch_or(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT, bool $volatile = false, usz $alignment = 0)
 {
 	$if	types::is_int($typeof(*ptr)):
@@ -283,17 +283,17 @@ macro fetch_or(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT, bool $volatile
 	return old_value;
 }
 
-/**
- * @param [&in] ptr "the variable or dereferenced pointer to the data."
- * @param [in] y "the value to be added to ptr."
- * @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
- * @return "returns the old value of ptr"
- * 
- * @require !$alignment || math::is_power_of_2($alignment) "Alignment must be a power of two."
- * @require types::is_int($typeof(*ptr)) "Only integer pointers may be used."
- * @require types::is_int($typeof(y)) "The value for or must be an int"
- * @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- **/
+<*
+ @param [&in] ptr "the variable or dereferenced pointer to the data."
+ @param [in] y "the value to be added to ptr."
+ @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
+ @return "returns the old value of ptr"
+
+ @require !$alignment || math::is_power_of_2($alignment) "Alignment must be a power of two."
+ @require types::is_int($typeof(*ptr)) "Only integer pointers may be used."
+ @require types::is_int($typeof(y)) "The value for or must be an int"
+ @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+*>
 macro fetch_xor(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT, bool $volatile = false, usz $alignment = 0)
 {
 	$if	types::is_int($typeof(*ptr)):
@@ -326,17 +326,17 @@ macro fetch_xor(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT, bool $volatil
 	return old_value;
 }
 
-/**
- * @param [&in] ptr "the variable or dereferenced pointer to the data."
- * @param [in] y "the value to be added to ptr."
- * @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
- * @return "returns the old value of ptr"
- * 
- * @require !$alignment || math::is_power_of_2($alignment) "Alignment must be a power of two."
- * @require types::is_int($typeof(*ptr)) "Only integer pointers may be used."
- * @require types::is_int($typeof(y)) "The value for or must be an int"
- * @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- **/
+<*
+ @param [&in] ptr "the variable or dereferenced pointer to the data."
+ @param [in] y "the value to be added to ptr."
+ @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
+ @return "returns the old value of ptr"
+
+ @require !$alignment || math::is_power_of_2($alignment) "Alignment must be a power of two."
+ @require types::is_int($typeof(*ptr)) "Only integer pointers may be used."
+ @require types::is_int($typeof(y)) "The value for or must be an int"
+ @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+*>
 macro fetch_and(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT, bool $volatile = false, usz $alignment = 0)
 {
 	$if	types::is_int($typeof(*ptr)):
@@ -369,16 +369,16 @@ macro fetch_and(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT, bool $volatil
 	return old_value;
 }
 
-/**
- * @param [&in] ptr "the variable or dereferenced pointer to the data."
- * @param [in] y "the value to be added to ptr."
- * @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
- * @return "returns the old value of ptr"
- * 
- * @require types::is_int($typeof(*ptr)) "Only integer pointers may be used."
- * @require types::is_int($typeof(y)) "The value for or must be an int"
- * @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- **/
+<*
+ @param [&in] ptr "the variable or dereferenced pointer to the data."
+ @param [in] y "the value to be added to ptr."
+ @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
+ @return "returns the old value of ptr"
+
+ @require types::is_int($typeof(*ptr)) "Only integer pointers may be used."
+ @require types::is_int($typeof(y)) "The value for or must be an int"
+ @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+*>
 macro fetch_shift_right(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT)
 {
 	var $load_ordering = $ordering;
@@ -407,16 +407,16 @@ macro fetch_shift_right(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT)
 	return old_value;
 }
 
-/**
- * @param [&in] ptr "the variable or dereferenced pointer to the data."
- * @param [in] y "the value to be added to ptr."
- * @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
- * @return "returns the old value of ptr"
- * 
- * @require types::is_int($typeof(*ptr)) "Only integer pointers may be used."
- * @require types::is_int($typeof(y)) "The value for or must be an int"
- * @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- **/
+<*
+ @param [&in] ptr "the variable or dereferenced pointer to the data."
+ @param [in] y "the value to be added to ptr."
+ @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
+ @return "returns the old value of ptr"
+
+ @require types::is_int($typeof(*ptr)) "Only integer pointers may be used."
+ @require types::is_int($typeof(y)) "The value for or must be an int"
+ @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+*>
 macro fetch_shift_left(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT)
 {
 	var $load_ordering = $ordering;
@@ -445,14 +445,14 @@ macro fetch_shift_left(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT)
 	return old_value;
 }
 
-/**
- * @param [&in] ptr "the variable or dereferenced pointer to the data."
- * @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
- * @return "returns the old value of ptr"
- * 
- * @require types::is_int($typeof(*ptr)) "Only integer pointers may be used."
- * @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- **/
+<*
+ @param [&in] ptr "the variable or dereferenced pointer to the data."
+ @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
+ @return "returns the old value of ptr"
+
+ @require types::is_int($typeof(*ptr)) "Only integer pointers may be used."
+ @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+*>
 macro flag_set(ptr, AtomicOrdering $ordering = SEQ_CONSISTENT)
 {
 	$typeof(*ptr) old_value;
@@ -465,14 +465,14 @@ macro flag_set(ptr, AtomicOrdering $ordering = SEQ_CONSISTENT)
 	return old_value;
 }
 
-/**
- * @param [&in] ptr "the variable or dereferenced pointer to the data."
- * @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
- * @return "returns the old value of ptr"
- * 
- * @require types::is_int($typeof(*ptr)) "Only integer pointers may be used."
- * @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- **/
+<*
+ @param [&in] ptr "the variable or dereferenced pointer to the data."
+ @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
+ @return "returns the old value of ptr"
+
+ @require types::is_int($typeof(*ptr)) "Only integer pointers may be used."
+ @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+*>
 macro flag_clear(ptr, AtomicOrdering $ordering = SEQ_CONSISTENT)
 {
 	$typeof(*ptr) old_value;
@@ -485,15 +485,15 @@ macro flag_clear(ptr, AtomicOrdering $ordering = SEQ_CONSISTENT)
 	return old_value;
 }
 
-/**
- * @param [&in] ptr "the variable or dereferenced pointer to the data."
- * @param [in] y "the value to be added to ptr."
- * @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
- * @return "returns the old value of ptr"
- * 
- * @require types::is_int($typeof(*ptr)) || types::is_float($typeof(*ptr)) "Only integer/float pointers may be used."
- * @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- **/
+<*
+ @param [&in] ptr "the variable or dereferenced pointer to the data."
+ @param [in] y "the value to be added to ptr."
+ @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
+ @return "returns the old value of ptr"
+
+ @require types::is_int($typeof(*ptr)) || types::is_float($typeof(*ptr)) "Only integer/float pointers may be used."
+ @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+*>
 macro fetch_max(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT, bool $volatile = false, usz $alignment = 0)
 {
 	$if $alignment == 0:
@@ -502,15 +502,15 @@ macro fetch_max(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT, bool $volatil
 	return $$atomic_fetch_max(ptr, y, $volatile, $ordering.ordinal, $alignment);
 }
 
-/**
- * @param [&in] ptr "the variable or dereferenced pointer to the data."
- * @param [in] y "the value to be added to ptr."
- * @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
- * @return "returns the old value of ptr"
- * 
- * @require types::is_int($typeof(*ptr)) || types::is_float($typeof(*ptr)) "Only integer/float pointers may be used."
- * @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- **/
+<*
+ @param [&in] ptr "the variable or dereferenced pointer to the data."
+ @param [in] y "the value to be added to ptr."
+ @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
+ @return "returns the old value of ptr"
+
+ @require types::is_int($typeof(*ptr)) || types::is_float($typeof(*ptr)) "Only integer/float pointers may be used."
+ @require $ordering != AtomicOrdering.NOT_ATOMIC && $ordering != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+*>
 macro fetch_min(ptr, y, AtomicOrdering $ordering = SEQ_CONSISTENT, bool $volatile = false, usz $alignment = 0)
 {
 	$if $alignment == 0:

lib/std/bits.c3

@@ -1,13 +1,13 @@
 module std::bits;
 
-/**
- * @require types::is_intlike($typeof(i)) `The input must be an integer or integer vector`
- **/
+<*
+ @require types::is_intlike($typeof(i)) `The input must be an integer or integer vector`
+*>
 macro reverse(i) => $$bitreverse(i);
 
-/**
- * @require types::is_intlike($typeof(i)) `The input must be an integer or integer vector`
- **/
+<*
+ @require types::is_intlike($typeof(i)) `The input must be an integer or integer vector`
+*>
 macro bswap(i) @builtin => $$bswap(i);
 
 macro uint[<*>].popcount(self) => $$popcount(self);

lib/std/collections/anylist.c3

@@ -16,19 +16,20 @@ struct AnyList (Printable)
 }
 
 
-/**
- * @param initial_capacity "The initial capacity to reserve"
- * Use `init` for to use a custom allocator.
- **/
+<*
+ Use `init` for to use a custom allocator.
+
+ @param initial_capacity "The initial capacity to reserve"
+*>
 fn AnyList* AnyList.new_init(&self, usz initial_capacity = 16, Allocator allocator = null)
 {
 	return self.init(allocator ?: allocator::heap(), initial_capacity) @inline;
 }
 
-/**
- * @param [&inout] allocator "The allocator to use"
- * @param initial_capacity "The initial capacity to reserve"
- **/
+<*
+ @param [&inout] allocator "The allocator to use"
+ @param initial_capacity "The initial capacity to reserve"
+*>
 fn AnyList* AnyList.init(&self, Allocator allocator, usz initial_capacity = 16)
 {
 	self.allocator = allocator;
@@ -46,11 +47,11 @@ fn AnyList* AnyList.init(&self, Allocator allocator, usz initial_capacity = 16)
 	return self;
 }
 
-/**
- * Initialize the list using the temp allocator.
- *
- * @param initial_capacity "The initial capacity to reserve"
- **/
+<*
+ Initialize the list using the temp allocator.
+
+ @param initial_capacity "The initial capacity to reserve"
+*>
 fn AnyList* AnyList.temp_init(&self, usz initial_capacity = 16)
 {
 	return self.init(allocator::temp(), initial_capacity) @inline;
@@ -89,9 +90,9 @@ fn String AnyList.to_string(&self, Allocator allocator) @dynamic
 
 fn String AnyList.to_tstring(&self) => string::tformat("%s", *self);
 
-/**
- * Push an element on the list by cloning it.
- **/
+<*
+ Push an element on the list by cloning it.
+*>
 macro void AnyList.push(&self, element)
 {
 	if (!self.allocator) self.allocator = allocator::heap();
@@ -104,20 +105,20 @@ fn void AnyList.append_internal(&self, any element) @local
 	self.entries[self.size++] = element;
 }
 
-/**
- * Free a retained element removed using *_retained.
- **/
+<*
+ Free a retained element removed using *_retained.
+*>
 fn void AnyList.free_element(&self, any element) @inline
 {
 	allocator::free(self.allocator, element.ptr);
 }
 
-/**
- * Pop a value who's type is known. If the type is incorrect, this
- * will still pop the element.
- *
- * @return! CastResult.TYPE_MISMATCH, IteratorResult.NO_MORE_ELEMENT
- **/
+<*
+ Pop a value who's type is known. If the type is incorrect, this
+ will still pop the element.
+
+ @return! CastResult.TYPE_MISMATCH, IteratorResult.NO_MORE_ELEMENT
+*>
 macro AnyList.pop(&self, $Type)
 {
 	if (!self.size) return IteratorResult.NO_MORE_ELEMENT?;
@@ -125,10 +126,10 @@ macro AnyList.pop(&self, $Type)
 	return *anycast(self.entries[--self.size], $Type);
 }
 
-/**
- * Pop the last value and allocate the copy using the given allocator.
- * @return! IteratorResult.NO_MORE_ELEMENT
- **/
+<*
+ Pop the last value and allocate the copy using the given allocator.
+ @return! IteratorResult.NO_MORE_ELEMENT
+*>
 fn any! AnyList.copy_pop(&self, Allocator allocator = allocator::heap())
 {
 	if (!self.size) return IteratorResult.NO_MORE_ELEMENT?;
@@ -136,33 +137,33 @@ fn any! AnyList.copy_pop(&self, Allocator allocator = allocator::heap())
 	return allocator::clone_any(allocator, self.entries[--self.size]);
 }
 
-/**
- * Pop the last value and allocate the copy using the given allocator.
- * @return! IteratorResult.NO_MORE_ELEMENT
- * @deprecated `use copy_pop`
- **/
+<*
+ Pop the last value and allocate the copy using the given allocator.
+ @return! IteratorResult.NO_MORE_ELEMENT
+ @deprecated `use copy_pop`
+*>
 fn any! AnyList.new_pop(&self, Allocator allocator = allocator::heap())
 {
 	return self.copy_pop(allocator);
 }
 
-/**
- * Pop the last value and allocate the copy using the temp allocator
- * @return! IteratorResult.NO_MORE_ELEMENT
- * @deprecated `use tcopy_pop`
- **/
+<*
+ Pop the last value and allocate the copy using the temp allocator
+ @return! IteratorResult.NO_MORE_ELEMENT
+ @deprecated `use tcopy_pop`
+*>
 fn any! AnyList.temp_pop(&self) => self.copy_pop(allocator::temp());
 
-/**
- * Pop the last value and allocate the copy using the temp allocator
- * @return! IteratorResult.NO_MORE_ELEMENT
- **/
+<*
+ Pop the last value and allocate the copy using the temp allocator
+ @return! IteratorResult.NO_MORE_ELEMENT
+*>
 fn any! AnyList.tcopy_pop(&self) => self.copy_pop(allocator::temp());
 
-/**
- * Pop the last value. It must later be released using list.free_element()
- * @return! IteratorResult.NO_MORE_ELEMENT
- **/
+<*
+ Pop the last value. It must later be released using list.free_element()
+ @return! IteratorResult.NO_MORE_ELEMENT
+*>
 fn any! AnyList.pop_retained(&self)
 {
 	if (!self.size) return IteratorResult.NO_MORE_ELEMENT?;
@@ -178,9 +179,9 @@ fn void AnyList.clear(&self)
 	self.size = 0;
 }
 
-/**
- * Same as pop() but pops the first value instead.
- **/
+<*
+ Same as pop() but pops the first value instead.
+*>
 macro AnyList.pop_first(&self, $Type)
 {
 	if (!self.size) return IteratorResult.NO_MORE_ELEMENT?;
@@ -188,9 +189,9 @@ macro AnyList.pop_first(&self, $Type)
 	return *anycast(self.entries[0], $Type);
 }
 
-/**
- * Same as pop_retained() but pops the first value instead.
- **/
+<*
+ Same as pop_retained() but pops the first value instead.
+*>
 fn any! AnyList.pop_first_retained(&self)
 {
 	if (!self.size) return IteratorResult.NO_MORE_ELEMENT?;
@@ -198,18 +199,18 @@ fn any! AnyList.pop_first_retained(&self)
 	return self.entries[0];
 }
 
-/**
- * Same as new_pop() but pops the first value instead.
- * @deprecated `use copy_pop_first`
- **/
+<*
+ Same as new_pop() but pops the first value instead.
+ @deprecated `use copy_pop_first`
+*>
 fn any! AnyList.new_pop_first(&self, Allocator allocator = allocator::heap())
 {
 	return self.copy_pop_first(allocator) @inline;
 }
 
-/**
- * Same as new_pop() but pops the first value instead.
- **/
+<*
+ Same as new_pop() but pops the first value instead.
+*>
 fn any! AnyList.copy_pop_first(&self, Allocator allocator = allocator::heap())
 {
 	if (!self.size) return IteratorResult.NO_MORE_ELEMENT?;
@@ -218,20 +219,20 @@ fn any! AnyList.copy_pop_first(&self, Allocator allocator = allocator::heap())
 	return allocator::clone_any(allocator, self.entries[0]);
 }
 
-/**
- * Same as temp_pop() but pops the first value instead.
- **/
+<*
+ Same as temp_pop() but pops the first value instead.
+*>
 fn any! AnyList.tcopy_pop_first(&self) => self.copy_pop_first(allocator::temp());
 
-/**
- * Same as temp_pop() but pops the first value instead.
- * @deprecated `use tcopy_pop_first`
- **/
+<*
+ Same as temp_pop() but pops the first value instead.
+ @deprecated `use tcopy_pop_first`
+*>
 fn any! AnyList.temp_pop_first(&self) => self.new_pop_first(allocator::temp());
 
-/**
- * @require index < self.size
- **/
+<*
+ @require index < self.size
+*>
 fn void AnyList.remove_at(&self, usz index)
 {
 	if (!--self.size || index == self.size) return;
@@ -249,9 +250,9 @@ fn void AnyList.add_all(&self, AnyList* other_list)
 	}
 }
 
-/**
- * Reverse the elements in a list.
- **/
+<*
+ Reverse the elements in a list.
+*>
 fn void AnyList.reverse(&self)
 {
 	if (self.size < 2) return;
@@ -268,26 +269,26 @@ fn any[] AnyList.array_view(&self)
 	return self.entries[:self.size];
 }
 
-/**
- * Push an element to the front of the list.
- **/
+<*
+ Push an element to the front of the list.
+*>
 macro void AnyList.push_front(&self, type)
 {
 	self.insert_at(0, type);
 }
 
-/**
- * @require index < self.size
- **/
+<*
+ @require index < self.size
+*>
 macro void AnyList.insert_at(&self, usz index, type) @local
 {
 	any value = allocator::copy(self.allocator, type);
 	self.insert_at_internal(self, index, value);
 }
 
-/**
- * @require index < self.size
- **/
+<*
+ @require index < self.size
+*>
 fn void AnyList.insert_at_internal(&self, usz index, any value) @local
 {
 	self.ensure_capacity();
@@ -300,17 +301,17 @@ fn void AnyList.insert_at_internal(&self, usz index, any value) @local
 }
 
 
-/**
- * @require self.size > 0
- **/
+<*
+ @require self.size > 0
+*>
 fn void AnyList.remove_last(&self)
 {
 	self.free_element(self.entries[--self.size]);
 }
 
-/**
- * @require self.size > 0
- **/
+<*
+ @require self.size > 0
+*>
 fn void AnyList.remove_first(&self)
 {
 	self.remove_at(0);
@@ -346,17 +347,17 @@ fn usz AnyList.len(&self) @operator(len) @inline
 	return self.size;
 }
 
-/**
- * @require index < self.size "Index out of range"
- **/
+<*
+ @require index < self.size "Index out of range"
+*>
 macro AnyList.get(&self, usz index, $Type)
 {
 	return *anycast(self.entries[index], $Type);
 }
 
-/**
- * @require index < self.size "Index out of range"
- **/
+<*
+ @require index < self.size "Index out of range"
+*>
 fn any AnyList.get_any(&self, usz index) @inline
 {
 	return self.entries[index];
@@ -378,19 +379,19 @@ fn void AnyList.swap(&self, usz i, usz j)
 	self.entries[j] = temp;
 }
 
-/**
- * @param filter "The function to determine if it should be removed or not"
- * @return "the number of deleted elements"
- **/
+<*
+ @param filter "The function to determine if it should be removed or not"
+ @return "the number of deleted elements"
+*>
 fn usz AnyList.remove_if(&self, AnyPredicate filter)
 {
 	return self._remove_if(filter, false);
 }
 
-/**
- * @param selection "The function to determine if it should be kept or not"
- * @return "the number of deleted elements"
- **/
+<*
+ @param selection "The function to determine if it should be kept or not"
+ @return "the number of deleted elements"
+*>
 fn usz AnyList.retain_if(&self, AnyPredicate selection)
 {
 	return self._remove_if(selection, true);
@@ -458,9 +459,9 @@ macro usz AnyList._remove_using_test(&self, AnyTest filter, bool $invert, ctx) @
 	return size - self.size;
 }
 
-/**
- * Reserve at least min_capacity
- **/
+<*
+ Reserve at least min_capacity
+*>
 fn void AnyList.reserve(&self, usz min_capacity)
 {
 	if (!min_capacity) return;
@@ -476,9 +477,9 @@ macro any AnyList.@item_at(&self, usz index) @operator([])
 	return self.entries[index];
 }
 
-/**
- * @require index <= self.size "Index out of range"
- **/
+<*
+ @require index <= self.size "Index out of range"
+*>
 macro void AnyList.set(&self, usz index, value)
 {
 	if (index == self.size)

lib/std/collections/bitset.c3

@@ -1,6 +1,6 @@
-/**
- * @require SIZE > 0
- **/
+<*
+ @require SIZE > 0
+*>
 module std::collections::bitset(<SIZE>);
 
 def Type = uint;
@@ -23,9 +23,9 @@ fn usz BitSet.cardinality(&self)
 	return n;
 }
 
-/**
- * @require i < SIZE
- **/
+<*
+ @require i < SIZE
+*>
 fn void BitSet.set(&self, usz i)
 {
 	usz q = i / BITS;
@@ -33,9 +33,9 @@ fn void BitSet.set(&self, usz i)
 	self.data[q] |= 1 << r;
 }
 
-/**
- * @require i < SIZE
- **/
+<*
+ @require i < SIZE
+*>
 fn void BitSet.unset(&self, usz i)
 {
 	usz q = i / BITS;
@@ -43,9 +43,9 @@ fn void BitSet.unset(&self, usz i)
 	self.data[q] &= ~(1 << r);
 }
 
-/**
- * @require i < SIZE
- **/
+<*
+ @require i < SIZE
+*>
 fn bool BitSet.get(&self, usz i) @operator([]) @inline
 {
 	usz q = i / BITS;
@@ -58,18 +58,18 @@ fn usz BitSet.len(&self) @operator(len) @inline
 	return SZ * BITS;
 }
 
-/**
- * @require i < SIZE
- **/
+<*
+ @require i < SIZE
+*>
 fn void BitSet.set_bool(&self, usz i, bool value) @operator([]=) @inline
 {
 	if (value) return self.set(i);
 	self.unset(i);
 }
 
-/**
- * @require Type.kindof == UNSIGNED_INT
- **/
+<*
+ @require Type.kindof == UNSIGNED_INT
+*>
 module std::collections::growablebitset(<Type>);
 import std::collections::list;
 
@@ -82,10 +82,10 @@ struct GrowableBitSet
 	GrowableBitSetList data;
 }
 
-/**
- * @param initial_capacity
- * @param [&inout] allocator "The allocator to use, defaults to the heap allocator"
- **/
+<*
+ @param initial_capacity
+ @param [&inout] allocator "The allocator to use, defaults to the heap allocator"
+*>
 fn GrowableBitSet* GrowableBitSet.new_init(&self, usz initial_capacity = 1, Allocator allocator = allocator::heap())
 {
 	self.data.new_init(initial_capacity, allocator);

lib/std/collections/elastic_array.c3

@@ -1,9 +1,9 @@
 // Copyright (c) 2021-2024 Christoffer Lerno. All rights reserved.
 // Use of self source code is governed by the MIT license
 // a copy of which can be found in the LICENSE_STDLIB file.
-/**
- * @require MAX_SIZE >= 1 `The size must be at least 1 element big.`
- **/
+<*
+ @require MAX_SIZE >= 1 `The size must be at least 1 element big.`
+*>
 module std::collections::elastic_array(<Type, MAX_SIZE>);
 import std::io, std::math, std::collections::list_common;
 
@@ -60,9 +60,9 @@ fn void! ElasticArray.push_try(&self, Type element) @inline
 	self.entries[self.size++] = element;
 }
 
-/**
- * @require self.size < MAX_SIZE `Tried to exceed the max size`
- **/
+<*
+ @require self.size < MAX_SIZE `Tried to exceed the max size`
+*>
 fn void ElasticArray.push(&self, Type element) @inline
 {
 	self.entries[self.size++] = element;
@@ -79,9 +79,9 @@ fn void ElasticArray.clear(&self)
 	self.size = 0;
 }
 
-/**
- * @require self.size > 0
- **/
+<*
+ @require self.size > 0
+*>
 fn Type! ElasticArray.pop_first(&self)
 {
 	if (!self.size) return IteratorResult.NO_MORE_ELEMENT?;
@@ -89,18 +89,18 @@ fn Type! ElasticArray.pop_first(&self)
 	return self.entries[0];
 }
 
-/**
- * @require index < self.size
- **/
+<*
+ @require index < self.size
+*>
 fn void ElasticArray.remove_at(&self, usz index)
 {
 	if (!--self.size || index == self.size) return;
 	self.entries[index .. self.size - 1] = self.entries[index + 1 .. self.size];
 }
 
-/**
- * @require other_list.size + self.size <= MAX_SIZE
- **/
+<*
+ @require other_list.size + self.size <= MAX_SIZE
+*>
 fn void ElasticArray.add_all(&self, ElasticArray* other_list)
 {
 	if (!other_list.size) return;
@@ -110,10 +110,10 @@ fn void ElasticArray.add_all(&self, ElasticArray* other_list)
 	}
 }
 
-/**
- * Add as many elements as possible to the new array,
- * returning the number of elements that didn't fit.
- **/
+<*
+ Add as many elements as possible to the new array,
+ returning the number of elements that didn't fit.
+*>
 fn usz ElasticArray.add_all_to_limit(&self, ElasticArray* other_list)
 {
 	if (!other_list.size) return 0;
@@ -125,12 +125,12 @@ fn usz ElasticArray.add_all_to_limit(&self, ElasticArray* other_list)
 	return 0;
 }
 
-/**
- * Add as many values from this array as possible, returning the
- * number of elements that didn't fit.
- *
- * @param [in] array
- **/
+<*
+ Add as many values from this array as possible, returning the
+ number of elements that didn't fit.
+
+ @param [in] array
+*>
 fn usz ElasticArray.add_array_to_limit(&self, Type[] array)
 {
 	if (!array.len) return 0;
@@ -142,13 +142,13 @@ fn usz ElasticArray.add_array_to_limit(&self, Type[] array)
 	return 0;
 }
 
-/**
- * Add the values of an array to this list.
- *
- * @param [in] array
- * @require array.len + self.size <= MAX_SIZE `Size would exceed max.`
- * @ensure self.size >= array.len
- **/
+<*
+ Add the values of an array to this list.
+
+ @param [in] array
+ @require array.len + self.size <= MAX_SIZE `Size would exceed max.`
+ @ensure self.size >= array.len
+*>
 fn void ElasticArray.add_array(&self, Type[] array)
 {
 	if (!array.len) return;
@@ -160,33 +160,33 @@ fn void ElasticArray.add_array(&self, Type[] array)
 
 
 
-/**
- * IMPORTANT The returned array must be freed using free_aligned.
- **/
+<*
+ IMPORTANT The returned array must be freed using free_aligned.
+*>
 fn Type[] ElasticArray.to_new_aligned_array(&self)
 {
 	return list_common::list_to_new_aligned_array(Type, self, allocator::heap());
 }
 
-/**
- * IMPORTANT The returned array must be freed using free_aligned.
- **/
+<*
+ IMPORTANT The returned array must be freed using free_aligned.
+*>
 fn Type[] ElasticArray.to_aligned_array(&self, Allocator allocator)
 {
 	return list_common::list_to_new_aligned_array(Type, self, allocator);
 }
 
-/**
- * @require !type_is_overaligned() : "This function is not available on overaligned types"
- **/
+<*
+ @require !type_is_overaligned() : "This function is not available on overaligned types"
+*>
 macro Type[] ElasticArray.to_new_array(&self)
 {
 	return list_common::list_to_array(Type, self, allocator::heap());
 }
 
-/**
- * @require !type_is_overaligned() : "This function is not available on overaligned types"
- **/
+<*
+ @require !type_is_overaligned() : "This function is not available on overaligned types"
+*>
 macro Type[] ElasticArray.to_array(&self, Allocator allocator)
 {
 	return list_common::list_to_new_array(Type, self, allocator);
@@ -201,9 +201,9 @@ fn Type[] ElasticArray.to_tarray(&self)
 	$endif;
 }
 
-/**
- * Reverse the elements in a list.
- **/
+<*
+ Reverse the elements in a list.
+*>
 fn void ElasticArray.reverse(&self)
 {
 	list_common::list_reverse(self);
@@ -214,35 +214,35 @@ fn Type[] ElasticArray.array_view(&self)
 	return self.entries[:self.size];
 }
 
-/**
- * @require self.size < MAX_SIZE `List would exceed max size`
- **/
+<*
+ @require self.size < MAX_SIZE `List would exceed max size`
+*>
 fn void ElasticArray.push_front(&self, Type type) @inline
 {
 	self.insert_at(0, type);
 }
 
-/**
- * @require self.size < MAX_SIZE `List would exceed max size`
- **/
+<*
+ @require self.size < MAX_SIZE `List would exceed max size`
+*>
 fn void! ElasticArray.push_front_try(&self, Type type) @inline
 {
 	return self.insert_at_try(0, type);
 }
 
-/**
- * @require index <= self.size
- **/
+<*
+ @require index <= self.size
+*>
 fn void! ElasticArray.insert_at_try(&self, usz index, Type value)
 {
 	if (self.size == MAX_SIZE) return AllocationFailure.OUT_OF_MEMORY?;
 	self.insert_at(index, value);
 }
 
-/**
- * @require self.size < MAX_SIZE `List would exceed max size`
- * @require index <= self.size
- **/
+<*
+ @require self.size < MAX_SIZE `List would exceed max size`
+ @require index <= self.size
+*>
 fn void ElasticArray.insert_at(&self, usz index, Type type)
 {
 	for (usz i = self.size; i > index; i--)
@@ -253,9 +253,9 @@ fn void ElasticArray.insert_at(&self, usz index, Type type)
 	self.entries[index] = type;
 }
 
-/**
- * @require index < self.size
- **/
+<*
+ @require index < self.size
+*>
 fn void ElasticArray.set_at(&self, usz index, Type type)
 {
 	self.entries[index] = type;
@@ -310,19 +310,19 @@ fn void ElasticArray.swap(&self, usz i, usz j)
 	@swap(self.entries[i], self.entries[j]);
 }
 
-/**
- * @param filter "The function to determine if it should be removed or not"
- * @return "the number of deleted elements"
- **/
+<*
+ @param filter "The function to determine if it should be removed or not"
+ @return "the number of deleted elements"
+*>
 fn usz ElasticArray.remove_if(&self, ElementPredicate filter)
 {
 	return list_common::list_remove_if(self, filter, false);
 }
 
-/**
- * @param selection "The function to determine if it should be kept or not"
- * @return "the number of deleted elements"
- **/
+<*
+ @param selection "The function to determine if it should be kept or not"
+ @return "the number of deleted elements"
+*>
 fn usz ElasticArray.retain_if(&self, ElementPredicate selection)
 {
 	return list_common::list_remove_if(self, selection, true);
@@ -384,13 +384,13 @@ fn bool ElasticArray.equals(&self, ElasticArray other_list) @if(ELEMENT_IS_EQUAT
 	return true;
 }
 
-/**
- * Check for presence of a value in a list.
- *
- * @param [&in] self "the list to find elements in"
- * @param value "The value to search for"
- * @return "True if the value is found, false otherwise"
- **/
+<*
+ Check for presence of a value in a list.
+
+ @param [&in] self "the list to find elements in"
+ @param value "The value to search for"
+ @return "True if the value is found, false otherwise"
+*>
 fn bool ElasticArray.contains(&self, Type value) @if(ELEMENT_IS_EQUATABLE)
 {
 	foreach (i, v : self)
@@ -400,31 +400,31 @@ fn bool ElasticArray.contains(&self, Type value) @if(ELEMENT_IS_EQUATABLE)
 	return false;
 }
 
-/**
- * @param [&inout] self "The list to remove elements from"
- * @param value "The value to remove"
- * @return "true if the value was found"
- **/
+<*
+ @param [&inout] self "The list to remove elements from"
+ @param value "The value to remove"
+ @return "true if the value was found"
+*>
 fn bool ElasticArray.remove_last_item(&self, Type value) @if(ELEMENT_IS_EQUATABLE)
 {
 	return @ok(self.remove_at(self.rindex_of(value)));
 }
 
-/**
- * @param [&inout] self "The list to remove elements from"
- * @param value "The value to remove"
- * @return "true if the value was found"
- **/
+<*
+ @param [&inout] self "The list to remove elements from"
+ @param value "The value to remove"
+ @return "true if the value was found"
+*>
 fn bool ElasticArray.remove_first_item(&self, Type value) @if(ELEMENT_IS_EQUATABLE)
 {
 	return @ok(self.remove_at(self.index_of(value)));
 }
 
-/**
- * @param [&inout] self "The list to remove elements from"
- * @param value "The value to remove"
- * @return "the number of deleted elements."
- **/
+<*
+ @param [&inout] self "The list to remove elements from"
+ @param value "The value to remove"
+ @return "the number of deleted elements."
+*>
 fn usz ElasticArray.remove_item(&self, Type value) @if(ELEMENT_IS_EQUATABLE)
 {
 	return list_common::list_remove_item(self, value);
@@ -438,10 +438,10 @@ fn void ElasticArray.remove_all_from(&self, ElasticArray* other_list) @if(ELEMEN
 	foreach (v : other_list) self.remove_item(v);
 }
 
-/**
- * @param [&in] self
- * @return "The number non-null values in the list"
- **/
+<*
+ @param [&in] self
+ @return "The number non-null values in the list"
+*>
 fn usz ElasticArray.compact_count(&self) @if(ELEMENT_IS_POINTER)
 {
 	usz vals = 0;

lib/std/collections/enummap.c3

@@ -1,6 +1,6 @@
-/**
- * @require Enum.kindof == TypeKind.ENUM : "Only enums may be used with an enummap"
- **/
+<*
+ @require Enum.kindof == TypeKind.ENUM : "Only enums may be used with an enummap"
+*>
 module std::collections::enummap(<Enum, ValueType>);
 import std::io;
 struct EnumMap (Printable)
@@ -43,18 +43,18 @@ fn String EnumMap.to_tstring(&self) @dynamic
 	return string::tformat("%s", *self);
 }
 
-/**
- * @return "The total size of this map, which is the same as the number of enum values"
- * @pure
- **/
+<*
+ @return "The total size of this map, which is the same as the number of enum values"
+ @pure
+*>
 fn usz EnumMap.len(&self) @operator(len) @inline
 {
 	return self.values.len;
 }
 
-/**
- * @return "Retrieve a value given the underlying enum, if there is no entry, then the zero value for the value is returned."
- **/
+<*
+ @return "Retrieve a value given the underlying enum, if there is no entry, then the zero value for the value is returned."
+*>
 fn ValueType EnumMap.get(&self, Enum key) @operator([]) @inline
 {
 	return self.values[key.ordinal];

lib/std/collections/enumset.c3

@@ -2,9 +2,9 @@
 // Use of self source code is governed by the MIT license
 // a copy of which can be found in the LICENSE_STDLIB file.
 
-/**
- * @require Enum.kindof == TypeKind.ENUM : "Only enums may be used with an enumset"
- **/
+<*
+ @require Enum.kindof == TypeKind.ENUM : "Only enums may be used with an enumset"
+*>
 module std::collections::enumset(<Enum>);
 import std::io;
 

lib/std/collections/hashmap.c3

@@ -1,6 +1,9 @@
 // Copyright (c) 2023 Christoffer Lerno. All rights reserved.
 // Use of this source code is governed by the MIT license
 // a copy of which can be found in the LICENSE_STDLIB file.
+<*
+ @require $defined(Key{}.hash()) `No .hash function found on the key`
+*>
 module std::collections::map(<Key, Value>);
 import std::math;
 
@@ -13,25 +16,25 @@ struct HashMap
 	float load_factor;
 }
 
-/**
- * @param [&inout] allocator "The allocator to use"
- * @require capacity > 0 "The capacity must be 1 or higher"
- * @require load_factor > 0.0 "The load factor must be higher than 0"
- * @require !self.allocator "Map was already initialized"
- * @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
- **/
+<*
+ @param [&inout] allocator "The allocator to use"
+ @require capacity > 0 "The capacity must be 1 or higher"
+ @require load_factor > 0.0 "The load factor must be higher than 0"
+ @require !self.allocator "Map was already initialized"
+ @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
+*>
 fn HashMap* HashMap.new_init(&self, uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAULT_LOAD_FACTOR, Allocator allocator = null)
 {
 	return self.init(allocator ?: allocator::heap(), capacity, load_factor);
 }
 
-/**
- * @param [&inout] allocator "The allocator to use"
- * @require capacity > 0 "The capacity must be 1 or higher"
- * @require load_factor > 0.0 "The load factor must be higher than 0"
- * @require !self.allocator "Map was already initialized"
- * @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
- **/
+<*
+ @param [&inout] allocator "The allocator to use"
+ @require capacity > 0 "The capacity must be 1 or higher"
+ @require load_factor > 0.0 "The load factor must be higher than 0"
+ @require !self.allocator "Map was already initialized"
+ @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
+*>
 fn HashMap* HashMap.init(&self, Allocator allocator, uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAULT_LOAD_FACTOR)
 {
 	capacity = math::next_power_of_2(capacity);
@@ -42,25 +45,25 @@ fn HashMap* HashMap.init(&self, Allocator allocator, uint capacity = DEFAULT_INI
 	return self;
 }
 
-/**
- * @require capacity > 0 "The capacity must be 1 or higher"
- * @require load_factor > 0.0 "The load factor must be higher than 0"
- * @require !self.allocator "Map was already initialized"
- * @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
- **/
+<*
+ @require capacity > 0 "The capacity must be 1 or higher"
+ @require load_factor > 0.0 "The load factor must be higher than 0"
+ @require !self.allocator "Map was already initialized"
+ @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
+*>
 fn HashMap* HashMap.temp_init(&self, uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAULT_LOAD_FACTOR)
 {
 	return self.init(allocator::temp(), capacity, load_factor) @inline;
 }
 
-/**
- * @param [&inout] allocator "The allocator to use"
- * @require $vacount % 2 == 0 "There must be an even number of arguments provided for keys and values"
- * @require capacity > 0 "The capacity must be 1 or higher"
- * @require load_factor > 0.0 "The load factor must be higher than 0"
- * @require !self.allocator "Map was already initialized"
- * @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
- **/
+<*
+ @param [&inout] allocator "The allocator to use"
+ @require $vacount % 2 == 0 "There must be an even number of arguments provided for keys and values"
+ @require capacity > 0 "The capacity must be 1 or higher"
+ @require load_factor > 0.0 "The load factor must be higher than 0"
+ @require !self.allocator "Map was already initialized"
+ @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
+*>
 macro HashMap* HashMap.new_init_with_key_values(&self, ..., uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAULT_LOAD_FACTOR, Allocator allocator = allocator::heap())
 {
 	self.new_init(capacity, load_factor, allocator);
@@ -70,16 +73,16 @@ macro HashMap* HashMap.new_init_with_key_values(&self, ..., uint capacity = DEFA
 	return self;
 }
 
-/**
- * @param [in] keys "The keys for the HashMap entries"
- * @param [in] values "The values for the HashMap entries"
- * @param [&inout] allocator "The allocator to use"
- * @require keys.len == values.len "Both keys and values arrays must be the same length"
- * @require capacity > 0 "The capacity must be 1 or higher"
- * @require load_factor > 0.0 "The load factor must be higher than 0"
- * @require !self.allocator "Map was already initialized"
- * @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
- **/
+<*
+ @param [in] keys "The keys for the HashMap entries"
+ @param [in] values "The values for the HashMap entries"
+ @param [&inout] allocator "The allocator to use"
+ @require keys.len == values.len "Both keys and values arrays must be the same length"
+ @require capacity > 0 "The capacity must be 1 or higher"
+ @require load_factor > 0.0 "The load factor must be higher than 0"
+ @require !self.allocator "Map was already initialized"
+ @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
+*>
 fn HashMap* HashMap.new_init_from_keys_and_values(&self, Key[] keys, Value[] values, uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAULT_LOAD_FACTOR, Allocator allocator = allocator::heap())
 {
 	assert(keys.len == values.len);
@@ -91,13 +94,13 @@ fn HashMap* HashMap.new_init_from_keys_and_values(&self, Key[] keys, Value[] val
 	return self;
 }
 
-/**
- * @require $vacount % 2 == 0 "There must be an even number of arguments provided for keys and values"
- * @require capacity > 0 "The capacity must be 1 or higher"
- * @require load_factor > 0.0 "The load factor must be higher than 0"
- * @require !self.allocator "Map was already initialized"
- * @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
- **/
+<*
+ @require $vacount % 2 == 0 "There must be an even number of arguments provided for keys and values"
+ @require capacity > 0 "The capacity must be 1 or higher"
+ @require load_factor > 0.0 "The load factor must be higher than 0"
+ @require !self.allocator "Map was already initialized"
+ @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
+*>
 macro HashMap* HashMap.temp_init_with_key_values(&self, ..., uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAULT_LOAD_FACTOR)
 {
 	self.temp_init(capacity, load_factor);
@@ -107,16 +110,16 @@ macro HashMap* HashMap.temp_init_with_key_values(&self, ..., uint capacity = DEF
 	return self;
 }
 
-/**
- * @param [in] keys "The keys for the HashMap entries"
- * @param [in] values "The values for the HashMap entries"
- * @param [&inout] allocator "The allocator to use"
- * @require keys.len == values.len "Both keys and values arrays must be the same length"
- * @require capacity > 0 "The capacity must be 1 or higher"
- * @require load_factor > 0.0 "The load factor must be higher than 0"
- * @require !self.allocator "Map was already initialized"
- * @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
- **/
+<*
+ @param [in] keys "The keys for the HashMap entries"
+ @param [in] values "The values for the HashMap entries"
+ @param [&inout] allocator "The allocator to use"
+ @require keys.len == values.len "Both keys and values arrays must be the same length"
+ @require capacity > 0 "The capacity must be 1 or higher"
+ @require load_factor > 0.0 "The load factor must be higher than 0"
+ @require !self.allocator "Map was already initialized"
+ @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
+*>
 fn HashMap* HashMap.temp_init_from_keys_and_values(&self, Key[] keys, Value[] values, uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAULT_LOAD_FACTOR, Allocator allocator = allocator::heap())
 {
 	assert(keys.len == values.len);
@@ -128,29 +131,29 @@ fn HashMap* HashMap.temp_init_from_keys_and_values(&self, Key[] keys, Value[] va
 	return self;
 }
 
-/**
- * Has this hash map been initialized yet?
- *
- * @param [&in] map "The hash map we are testing"
- * @return "Returns true if it has been initialized, false otherwise"
- **/
+<*
+ Has this hash map been initialized yet?
+
+ @param [&in] map "The hash map we are testing"
+ @return "Returns true if it has been initialized, false otherwise"
+*>
 fn bool HashMap.is_initialized(&map)
 {
 	return (bool)map.allocator;
 }
 
-/**
- * @param [&in] other_map "The map to copy from."
- **/
+<*
+ @param [&in] other_map "The map to copy from."
+*>
 fn HashMap* HashMap.new_init_from_map(&self, HashMap* other_map)
 {
 	return self.init_from_map(other_map, allocator::heap()) @inline;
 }
 
-/**
- * @param [&inout] allocator "The allocator to use"
- * @param [&in] other_map "The map to copy from."
- **/
+<*
+ @param [&inout] allocator "The allocator to use"
+ @param [&in] other_map "The map to copy from."
+*>
 fn HashMap* HashMap.init_from_map(&self, HashMap* other_map, Allocator allocator)
 {
 	self.new_init(other_map.table.len, other_map.load_factor, allocator);
@@ -158,9 +161,9 @@ fn HashMap* HashMap.init_from_map(&self, HashMap* other_map, Allocator allocator
 	return self;
 }
 
-/**
- * @param [&in] other_map "The map to copy from."
- **/
+<*
+ @param [&in] other_map "The map to copy from."
+*>
 fn HashMap* HashMap.temp_init_from_map(&map, HashMap* other_map)
 {
 	return map.init_from_map(other_map, allocator::temp()) @inline;
@@ -198,10 +201,10 @@ fn Entry*! HashMap.get_entry(&map, Key key)
 	return SearchResult.MISSING?;
 }
 
-/**
- * Get the value or update and
- * @require $assignable(#expr, Value)
- **/
+<*
+ Get the value or update and
+ @require $assignable(#expr, Value)
+*>
 macro Value HashMap.@get_or_set(&map, Key key, Value #expr)
 {
 	if (!map.count)
@@ -295,12 +298,12 @@ fn Key[] HashMap.key_tlist(&map) @deprecated("Use 'tcopy_keys'")
 	return map.copy_keys(allocator::temp()) @inline;
 }
 
-/**
- * @deprecated "use copy_keys"
- **/
+<*
+ @deprecated "use copy_keys"
+*>
 fn Key[] HashMap.key_new_list(&map, Allocator allocator = allocator::heap())
 {
-	return map.copy_keys() @inline;
+	return map.copy_keys(allocator) @inline;
 }
 
 fn Key[] HashMap.copy_keys(&map, Allocator allocator = allocator::heap())
@@ -313,7 +316,11 @@ fn Key[] HashMap.copy_keys(&map, Allocator allocator = allocator::heap())
 	{
 		while (entry)
 		{
-			list[index++] = entry.key;
+			$if COPY_KEYS:
+				list[index++] = entry.key.copy(allocator);
+			$else
+				list[index++] = entry.key;
+			$endif
 			entry = entry.next;
 		}
 	}
@@ -342,9 +349,9 @@ macro HashMap.@each_entry(map; @body(entry))
 	}
 }
 
-/**
- * @deprecated `use tcopy_values`
- **/
+<*
+ @deprecated `use tcopy_values`
+*>
 fn Value[] HashMap.value_tlist(&map)
 {
 	return map.copy_values(allocator::temp()) @inline;
@@ -355,9 +362,9 @@ fn Value[] HashMap.tcopy_values(&map)
 	return map.copy_values(allocator::temp()) @inline;
 }
 
-/**
- * @deprecated `use copy_values`
- **/
+<*
+ @deprecated `use copy_values`
+*>
 fn Value[] HashMap.value_new_list(&map, Allocator allocator = allocator::heap())
 {
 	return map.copy_values(allocator);
@@ -475,6 +482,7 @@ fn void HashMap.free_internal(&map, void* ptr) @inline @private
 
 fn bool HashMap.remove_entry_for_key(&map, Key key) @private
 {
+	if (!map.count) return false;
 	uint hash = rehash(key.hash());
 	uint i = index_for(hash, map.table.len);
 	Entry* prev = map.table[i];

lib/std/collections/linkedlist.c3

@@ -20,19 +20,19 @@ struct LinkedList
 	Node *_last;
 }
 
-/**
- * @param [&inout] allocator "The allocator to use, defaults to the heap allocator"
- * @return "the initialized list"
- **/
+<*
+ @param [&inout] allocator "The allocator to use, defaults to the heap allocator"
+ @return "the initialized list"
+*>
 fn LinkedList* LinkedList.init(&self, Allocator allocator)
 {
 	*self = { .allocator = allocator };
 	return self;
 }
 
-/**
- * @return "the initialized list"
- **/
+<*
+ @return "the initialized list"
+*>
 fn LinkedList* LinkedList.new_init(&self)
 {
 	return self.init(allocator::heap()) @inline;
@@ -44,9 +44,9 @@ fn LinkedList* LinkedList.temp_init(&self)
 	return self.init(allocator::temp()) @inline;
 }
 
-/**
- * @require self.allocator
- **/
+<*
+ @require self.allocator
+*>
 macro void LinkedList.free_node(&self, Node* node) @private
 {
 	allocator::free(self.allocator, node);
@@ -124,9 +124,9 @@ fn void LinkedList.clear(&self)
 
 fn usz LinkedList.len(&self) @inline => self.size;
 
-/**
- * @require index < self.size
- **/
+<*
+ @require index < self.size
+*>
 macro Node* LinkedList.node_at_index(&self, usz index)
 {
 	if (index * 2 >= self.size)
@@ -140,33 +140,33 @@ macro Node* LinkedList.node_at_index(&self, usz index)
 	while (index--) node = node.next;
 	return node;
 }
-/**
- * @require index < self.size
- **/
+<*
+ @require index < self.size
+*>
 fn Type LinkedList.get(&self, usz index)
 {
 	return self.node_at_index(index).value;
 }
 
-/**
- * @require index < self.size
- **/
+<*
+ @require index < self.size
+*>
 fn void LinkedList.set(&self, usz index, Type element)
 {
 	self.node_at_index(index).value = element;
 }
 
-/**
- * @require index < self.size
- **/
+<*
+ @require index < self.size
+*>
 fn void LinkedList.remove_at(&self, usz index)
 {
 	self.unlink(self.node_at_index(index));
 }
 
-/**
- * @require index <= self.size
- **/
+<*
+ @require index <= self.size
+*>
 fn void LinkedList.insert_at(&self, usz index, Type element)
 {
 	switch (index)
@@ -179,9 +179,9 @@ fn void LinkedList.insert_at(&self, usz index, Type element)
 			self.link_before(self.node_at_index(index), element);
 	}
 }
-/**
- * @require succ != null
- **/
+<*
+ @require succ != null
+*>
 fn void LinkedList.link_before(&self, Node *succ, Type value) @private
 {
 	Node* pred = succ.prev;
@@ -199,9 +199,9 @@ fn void LinkedList.link_before(&self, Node *succ, Type value) @private
 	self.size++;
 }
 
-/**
- * @require self._first
- **/
+<*
+ @require self._first
+*>
 fn void LinkedList.unlink_first(&self) @private
 {
 	Node* f = self._first;
@@ -245,6 +245,11 @@ fn Type! LinkedList.pop(&self)
 	return self._last.value;
 }
 
+fn bool LinkedList.is_empty(&self)
+{
+	return !self._first;
+}
+
 fn Type! LinkedList.pop_front(&self)
 {
 	if (!self._first) return IteratorResult.NO_MORE_ELEMENT?;
@@ -290,9 +295,9 @@ fn bool LinkedList.remove_last_match(&self, Type t)  @if(ELEMENT_IS_EQUATABLE)
 	}
 	return false;
 }
-/**
- * @require self._last
- **/
+<*
+ @require self._last
+*>
 fn void LinkedList.unlink_last(&self) @inline @private
 {
 	Node* l = self._last;
@@ -310,9 +315,9 @@ fn void LinkedList.unlink_last(&self) @inline @private
 	self.size--;
 }
 
-/**
- * @require x != null
- **/
+<*
+ @require x != null
+*>
 fn void LinkedList.unlink(&self, Node* x) @private
 {
 	Node* next = x.next;

lib/std/collections/list.c3

@@ -19,10 +19,10 @@ struct List (Printable)
 	Type *entries;
 }
 
-/**
- * @param initial_capacity "The initial capacity to reserve"
- * @param [&inout] allocator "The allocator to use, defaults to the heap allocator"
- **/
+<*
+ @param initial_capacity "The initial capacity to reserve"
+ @param [&inout] allocator "The allocator to use, defaults to the heap allocator"
+*>
 fn List* List.new_init(&self, usz initial_capacity = 16, Allocator allocator = allocator::heap())
 {
 	self.allocator = allocator;
@@ -33,22 +33,22 @@ fn List* List.new_init(&self, usz initial_capacity = 16, Allocator allocator = a
 	return self;
 }
 
-/**
- * Initialize the list using the temp allocator.
- *
- * @param initial_capacity "The initial capacity to reserve"
- **/
+<*
+ Initialize the list using the temp allocator.
+
+ @param initial_capacity "The initial capacity to reserve"
+*>
 fn List* List.temp_init(&self, usz initial_capacity = 16)
 {
 	return self.new_init(initial_capacity, allocator::temp()) @inline;
 }
 
-/**
- * Initialize a new list with an array.
- *
- * @param [in] values `The values to initialize the list with.`
- * @require self.size == 0 "The List must be empty"
- **/
+<*
+ Initialize a new list with an array.
+
+ @param [in] values `The values to initialize the list with.`
+ @require self.size == 0 "The List must be empty"
+*>
 fn List* List.new_init_with_array(&self, Type[] values, Allocator allocator = allocator::heap())
 {
 	self.new_init(values.len, allocator) @inline;
@@ -56,12 +56,12 @@ fn List* List.new_init_with_array(&self, Type[] values, Allocator allocator = al
 	return self;
 }
 
-/**
- * Initialize a temporary list with an array.
- *
- * @param [in] values `The values to initialize the list with.`
- * @require self.size == 0 "The List must be empty"
- **/
+<*
+ Initialize a temporary list with an array.
+
+ @param [in] values `The values to initialize the list with.`
+ @require self.size == 0 "The List must be empty"
+*>
 fn List* List.temp_init_with_array(&self, Type[] values)
 {
 	self.temp_init(values.len) @inline;
@@ -69,9 +69,9 @@ fn List* List.temp_init_with_array(&self, Type[] values)
 	return self;
 }
 
-/**
- * @require self.capacity == 0 "The List must not be allocated"
- **/
+<*
+ @require self.capacity == 0 "The List must not be allocated"
+*>
 fn void List.init_wrapping_array(&self, Type[] types, Allocator allocator = allocator::heap())
 {
 	self.allocator = allocator;
@@ -128,9 +128,6 @@ fn void List.clear(&self)
 	self.set_size(0);
 }
 
-/**
- * @require self.size > 0
- **/
 fn Type! List.pop_first(&self)
 {
 	if (!self.size) return IteratorResult.NO_MORE_ELEMENT?;
@@ -138,9 +135,9 @@ fn Type! List.pop_first(&self)
 	return self.entries[0];
 }
 
-/**
- * @require index < self.size
- **/
+<*
+ @require index < self.size `Removed element out of bounds`
+*>
 fn void List.remove_at(&self, usz index)
 {
 	self.set_size(self.size - 1);
@@ -160,17 +157,17 @@ fn void List.add_all(&self, List* other_list)
 }
 
 
-/**
- * IMPORTANT The returned array must be freed using free_aligned.
- **/
+<*
+ IMPORTANT The returned array must be freed using free_aligned.
+*>
 fn Type[] List.to_new_aligned_array(&self, Allocator allocator = allocator::heap())
 {
 	return list_common::list_to_new_aligned_array(Type, self, allocator);
 }
 
-/**
- * @require !type_is_overaligned() : "This function is not available on overaligned types"
- **/
+<*
+ @require !type_is_overaligned() : "This function is not available on overaligned types"
+*>
 macro Type[] List.to_new_array(&self, Allocator allocator = allocator::heap())
 {
 	return list_common::list_to_new_array(Type, self, allocator);
@@ -185,9 +182,9 @@ fn Type[] List.to_tarray(&self)
 	$endif;
 }
 
-/**
- * Reverse the elements in a list.
- **/
+<*
+ Reverse the elements in a list.
+*>
 fn void List.reverse(&self)
 {
 	list_common::list_reverse(self);
@@ -198,12 +195,12 @@ fn Type[] List.array_view(&self)
 	return self.entries[:self.size];
 }
 
-/**
- * Add the values of an array to this list.
- *
- * @param [in] array
- * @ensure self.size >= array.len
- **/
+<*
+ Add the values of an array to this list.
+
+ @param [in] array
+ @ensure self.size >= array.len
+*>
 fn void List.add_array(&self, Type[] array)
 {
 	if (!array.len) return;
@@ -217,9 +214,9 @@ fn void List.push_front(&self, Type type) @inline
 	self.insert_at(0, type);
 }
 
-/**
- * @require index <= self.size
- **/
+<*
+ @require index <= self.size `Insert was out of bounds`
+*>
 fn void List.insert_at(&self, usz index, Type type)
 {
 	self.reserve(1);
@@ -231,9 +228,9 @@ fn void List.insert_at(&self, usz index, Type type)
 	self.entries[index] = type;
 }
 
-/**
- * @require index < self.size
- **/
+<*
+ @require index < self.size
+*>
 fn void List.set_at(&self, usz index, Type type)
 {
 	self.entries[index] = type;
@@ -278,6 +275,9 @@ fn usz List.len(&self) @operator(len) @inline
 	return self.size;
 }
 
+<*
+ @require index < self.size `Access out of bounds`
+*>
 fn Type List.get(&self, usz index) @inline
 {
 	return self.entries[index];
@@ -299,24 +299,27 @@ fn void List.free(&self)
 	self.entries = null;
 }
 
+<*
+ @require i < self.size && j < self.size `Access out of bounds`
+*>
 fn void List.swap(&self, usz i, usz j)
 {
 	@swap(self.entries[i], self.entries[j]);
 }
 
-/**
- * @param filter "The function to determine if it should be removed or not"
- * @return "the number of deleted elements"
- **/
+<*
+ @param filter "The function to determine if it should be removed or not"
+ @return "the number of deleted elements"
+*>
 fn usz List.remove_if(&self, ElementPredicate filter)
 {
 	return list_common::list_remove_if(self, filter, false);
 }
 
-/**
- * @param selection "The function to determine if it should be kept or not"
- * @return "the number of deleted elements"
- **/
+<*
+ @param selection "The function to determine if it should be kept or not"
+ @return "the number of deleted elements"
+*>
 fn usz List.retain_if(&self, ElementPredicate selection)
 {
 	return list_common::list_remove_if(self, selection, true);
@@ -361,16 +364,25 @@ fn void List.ensure_capacity(&self, usz min_capacity) @local
 	self.post_alloc(); // Add sanitizer annotation
 }
 
+<*
+ @require index < self.size `Access out of bounds`
+*>
 macro Type List.@item_at(&self, usz index) @operator([])
 {
 	return self.entries[index];
 }
 
+<*
+ @require index < self.size `Access out of bounds`
+*>
 fn Type* List.get_ref(&self, usz index) @operator(&[]) @inline
 {
 	return &self.entries[index];
 }
 
+<*
+ @require index < self.size `Access out of bounds`
+*>
 fn void List.set(&self, usz index, Type value) @operator([]=)
 {
 	self.entries[index] = value;
@@ -395,9 +407,9 @@ fn void List._update_size_change(&self,usz old_size, usz new_size)
 	                                         &self.entries[old_size],
 	                                         &self.entries[new_size]);
 }
-/**
- * @require new_size == 0 || self.capacity != 0
- **/
+<*
+ @require new_size == 0 || self.capacity != 0
+*>
 fn usz List.set_size(&self, usz new_size) @inline @private
 {
 	usz old_size = self.size;
@@ -412,9 +424,9 @@ macro void List.pre_free(&self) @private
 	self._update_size_change(self.size, self.capacity);
 }
 
-/**
- * @require self.capacity
- **/
+<*
+ @require self.capacity
+*>
 macro void List.post_alloc(&self) @private
 {
 	self._update_size_change(self.capacity, self.size);
@@ -451,13 +463,13 @@ fn bool List.equals(&self, List other_list) @if(ELEMENT_IS_EQUATABLE)
 	return true;
 }
 
-/**
- * Check for presence of a value in a list.
- *
- * @param [&in] self "the list to find elements in"
- * @param value "The value to search for"
- * @return "True if the value is found, false otherwise"
- **/
+<*
+ Check for presence of a value in a list.
+
+ @param [&in] self "the list to find elements in"
+ @param value "The value to search for"
+ @return "True if the value is found, false otherwise"
+*>
 fn bool List.contains(&self, Type value) @if(ELEMENT_IS_EQUATABLE)
 {
 	foreach (i, v : self)
@@ -467,30 +479,30 @@ fn bool List.contains(&self, Type value) @if(ELEMENT_IS_EQUATABLE)
 	return false;
 }
 
-/**
- * @param [&inout] self "The list to remove elements from"
- * @param value "The value to remove"
- * @return "true if the value was found"
- **/
+<*
+ @param [&inout] self "The list to remove elements from"
+ @param value "The value to remove"
+ @return "true if the value was found"
+*>
 fn bool List.remove_last_item(&self, Type value) @if(ELEMENT_IS_EQUATABLE)
 {
 	return @ok(self.remove_at(self.rindex_of(value)));
 }
 
-/**
- * @param [&inout] self "The list to remove elements from"
- * @param value "The value to remove"
- * @return "true if the value was found"
- **/
+<*
+ @param [&inout] self "The list to remove elements from"
+ @param value "The value to remove"
+ @return "true if the value was found"
+*>
 fn bool List.remove_first_item(&self, Type value) @if(ELEMENT_IS_EQUATABLE)
 {
 	return @ok(self.remove_at(self.index_of(value)));
 }
-/**
- * @param [&inout] self "The list to remove elements from"
- * @param value "The value to remove"
- * @return "the number of deleted elements."
- **/
+<*
+ @param [&inout] self "The list to remove elements from"
+ @param value "The value to remove"
+ @return "the number of deleted elements."
+*>
 fn usz List.remove_item(&self, Type value) @if(ELEMENT_IS_EQUATABLE)
 {
 	usz old_size = self.size;
@@ -512,10 +524,10 @@ fn void List.remove_all_from(&self, List* other_list) @if(ELEMENT_IS_EQUATABLE)
 	foreach (v : other_list) self.remove_item(v);
 }
 
-/**
- * @param [&in] self
- * @return "The number non-null values in the list"
- **/
+<*
+ @param [&in] self
+ @return "The number non-null values in the list"
+*>
 fn usz List.compact_count(&self) @if(ELEMENT_IS_POINTER)
 {
 	usz vals = 0;
@@ -534,32 +546,32 @@ fn usz List.compact(&self) @if(ELEMENT_IS_POINTER)
 
 // --> Deprecated
 
-/**
- * @param [&inout] self "The list to remove elements from"
- * @param value "The value to remove"
- * @return "true if the value was found"
- **/
+<*
+ @param [&inout] self "The list to remove elements from"
+ @param value "The value to remove"
+ @return "true if the value was found"
+*>
 fn bool List.remove_last_match(&self, Type value) @if(ELEMENT_IS_EQUATABLE) @deprecated
 {
 	return self.remove_last_item(value) @inline;
 }
 
-/**
- * @param [&inout] self "The list to remove elements from"
- * @param value "The value to remove"
- * @return "true if the value was found"
- **/
+<*
+ @param [&inout] self "The list to remove elements from"
+ @param value "The value to remove"
+ @return "true if the value was found"
+*>
 fn bool List.remove_first_match(&self, Type value) @if(ELEMENT_IS_EQUATABLE) @deprecated
 {
 	return self.remove_first_item(value) @inline;
 }
 
 
-/**
- * @param [&inout] self "The list to remove elements from"
- * @param value "The value to remove"
- * @return "the number of deleted elements."
- **/
+<*
+ @param [&inout] self "The list to remove elements from"
+ @param value "The value to remove"
+ @return "the number of deleted elements."
+*>
 fn usz List.remove_all_matches(&self, Type value) @if(ELEMENT_IS_EQUATABLE) @deprecated
 {
 	return self.remove_item(value) @inline;

lib/std/collections/list_common.c3

@@ -1,8 +1,8 @@
 module std::collections::list_common;
 
-/**
- * IMPORTANT The returned array must be freed using free_aligned.
- **/
+<*
+ IMPORTANT The returned array must be freed using free_aligned.
+*>
 macro list_to_new_aligned_array($Type, self, Allocator allocator)
 {
 	if (!self.size) return $Type[] {};

lib/std/collections/map.c3

@@ -21,11 +21,11 @@ struct MapImpl
 	float load_factor;
 }
 
-/**
- * @require capacity > 0 "The capacity must be 1 or higher"
- * @require load_factor > 0.0 "The load factor must be higher than 0"
- * @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
- **/
+<*
+ @require capacity > 0 "The capacity must be 1 or higher"
+ @require load_factor > 0.0 "The load factor must be higher than 0"
+ @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
+*>
 fn Map new(uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAULT_LOAD_FACTOR, Allocator allocator = allocator::heap())
 {
 	MapImpl* map = allocator::alloc(allocator, MapImpl);
@@ -33,11 +33,11 @@ fn Map new(uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAULT
 	return (Map)map;
 }
 
-/**
- * @require capacity > 0 "The capacity must be 1 or higher"
- * @require load_factor > 0.0 "The load factor must be higher than 0"
- * @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
- **/
+<*
+ @require capacity > 0 "The capacity must be 1 or higher"
+ @require load_factor > 0.0 "The load factor must be higher than 0"
+ @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
+*>
 fn Map temp(uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAULT_LOAD_FACTOR)
 {
 	MapImpl* map = mem::temp_alloc(MapImpl);
@@ -45,13 +45,13 @@ fn Map temp(uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAUL
 	return (Map)map;
 }
 
-/**
- * @param [&inout] allocator "The allocator to use"
- * @require $vacount % 2 == 0 "There must be an even number of arguments provided for keys and values"
- * @require capacity > 0 "The capacity must be 1 or higher"
- * @require load_factor > 0.0 "The load factor must be higher than 0"
- * @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
- **/
+<*
+ @param [&inout] allocator "The allocator to use"
+ @require $vacount % 2 == 0 "There must be an even number of arguments provided for keys and values"
+ @require capacity > 0 "The capacity must be 1 or higher"
+ @require load_factor > 0.0 "The load factor must be higher than 0"
+ @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
+*>
 macro Map new_init_with_key_values(..., uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAULT_LOAD_FACTOR, Allocator allocator = allocator::heap())
 {
 	Map map = new(capacity, load_factor, allocator);
@@ -61,15 +61,15 @@ macro Map new_init_with_key_values(..., uint capacity = DEFAULT_INITIAL_CAPACITY
 	return map;
 }
 
-/**
- * @param [in] keys "Array of keys for the Map entries"
- * @param [in] values "Array of values for the Map entries"
- * @param [&inout] allocator "The allocator to use"
- * @require keys.len == values.len "Both keys and values arrays must be the same length"
- * @require capacity > 0 "The capacity must be 1 or higher"
- * @require load_factor > 0.0 "The load factor must be higher than 0"
- * @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
- **/
+<*
+ @param [in] keys "Array of keys for the Map entries"
+ @param [in] values "Array of values for the Map entries"
+ @param [&inout] allocator "The allocator to use"
+ @require keys.len == values.len "Both keys and values arrays must be the same length"
+ @require capacity > 0 "The capacity must be 1 or higher"
+ @require load_factor > 0.0 "The load factor must be higher than 0"
+ @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
+*>
 fn Map new_init_from_keys_and_values(Key[] keys, Value[] values, uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAULT_LOAD_FACTOR, Allocator allocator = allocator::heap())
 {
 	assert(keys.len == values.len);
@@ -81,12 +81,12 @@ fn Map new_init_from_keys_and_values(Key[] keys, Value[] values, uint capacity =
 	return map;
 }
 
-/**
- * @require $vacount % 2 == 0 "There must be an even number of arguments provided for keys and values"
- * @require capacity > 0 "The capacity must be 1 or higher"
- * @require load_factor > 0.0 "The load factor must be higher than 0"
- * @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
- **/
+<*
+ @require $vacount % 2 == 0 "There must be an even number of arguments provided for keys and values"
+ @require capacity > 0 "The capacity must be 1 or higher"
+ @require load_factor > 0.0 "The load factor must be higher than 0"
+ @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
+*>
 macro Map temp_new_with_key_values(..., uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAULT_LOAD_FACTOR)
 {
 	Map map = temp(capacity, load_factor);
@@ -96,15 +96,15 @@ macro Map temp_new_with_key_values(..., uint capacity = DEFAULT_INITIAL_CAPACITY
 	return map;
 }
 
-/**
- * @param [in] keys "The keys for the HashMap entries"
- * @param [in] values "The values for the HashMap entries"
- * @param [&inout] allocator "The allocator to use"
- * @require keys.len == values.len "Both keys and values arrays must be the same length"
- * @require capacity > 0 "The capacity must be 1 or higher"
- * @require load_factor > 0.0 "The load factor must be higher than 0"
- * @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
- **/
+<*
+ @param [in] keys "The keys for the HashMap entries"
+ @param [in] values "The values for the HashMap entries"
+ @param [&inout] allocator "The allocator to use"
+ @require keys.len == values.len "Both keys and values arrays must be the same length"
+ @require capacity > 0 "The capacity must be 1 or higher"
+ @require load_factor > 0.0 "The load factor must be higher than 0"
+ @require capacity < MAXIMUM_CAPACITY "Capacity cannot exceed maximum"
+*>
 fn Map temp_init_from_keys_and_values(Key[] keys, Value[] values, uint capacity = DEFAULT_INITIAL_CAPACITY, float load_factor = DEFAULT_LOAD_FACTOR, Allocator allocator = allocator::heap())
 {
 	assert(keys.len == values.len);
@@ -116,9 +116,9 @@ fn Map temp_init_from_keys_and_values(Key[] keys, Value[] values, uint capacity
 	return map;
 }
 
-/**
- * @param [&in] other_map "The map to copy from."
- **/
+<*
+ @param [&in] other_map "The map to copy from."
+*>
 fn Map new_from_map(Map other_map, Allocator allocator = null)
 {
 	MapImpl* other_map_impl = (MapImpl*)other_map;
@@ -130,16 +130,16 @@ fn Map new_from_map(Map other_map, Allocator allocator = null)
 	MapImpl* map = (MapImpl*)new(other_map_impl.table.len, other_map_impl.load_factor, allocator ?: allocator::heap());
 	if (!other_map_impl.count) return (Map)map;
 	foreach (Entry *e : other_map_impl.table)
-    {
-    	if (!e) continue;
-    	map._put_for_create(e.key, e.value);
-    }
+	{
+		if (!e) continue;
+		map._put_for_create(e.key, e.value);
+	}
 	return (Map)map;
 }
 
-/**
- * @param [&in] other_map "The map to copy from."
- **/
+<*
+ @param [&in] other_map "The map to copy from."
+*>
 fn Map temp_from_map(Map other_map)
 {
 	return new_from_map(other_map, allocator::temp());
@@ -179,10 +179,10 @@ fn Entry*! Map.get_entry(map, Key key)
 	return SearchResult.MISSING?;
 }
 
-/**
- * Get the value or update and
- * @require $assignable(#expr, Value)
- **/
+<*
+ Get the value or update and
+ @require $assignable(#expr, Value)
+*>
 macro Value Map.@get_or_set(&self, Key key, Value #expr)
 {
 	MapImpl *map = (MapImpl*)*self;
@@ -421,9 +421,9 @@ fn void _init(MapImpl* impl, uint capacity, float load_factor, Allocator allocat
 	capacity = math::next_power_of_2(capacity);
 	*impl = {
 		.allocator = allocator,
-    	.load_factor = load_factor,
-    	.threshold = (uint)(capacity * load_factor),
-    	.table = allocator::new_array(allocator, Entry*, capacity)
+		.load_factor = load_factor,
+		.threshold = (uint)(capacity * load_factor),
+		.table = allocator::new_array(allocator, Entry*, capacity)
 	};
 }
 

lib/std/collections/maybe.c3

@@ -1,6 +1,6 @@
 module std::collections::maybe(<Type>);
 
-struct Maybe @adhoc
+struct Maybe
 {
 	Type value;
 	bool has_value;

lib/std/collections/object.c3

@@ -50,7 +50,7 @@ fn usz! Object.to_format(&self, Formatter* formatter) @dynamic
 			usz n = formatter.printf("{")!;
 			@stack_mem(1024; Allocator mem)
 			{
-				foreach (i, key : self.map.key_new_list(mem))
+				foreach (i, key : self.map.copy_keys(mem))
 				{
 					if (i > 0) n += formatter.printf(",")!;
 					n += formatter.printf(`"%s":`, key)!;
@@ -63,11 +63,11 @@ fn usz! Object.to_format(&self, Formatter* formatter) @dynamic
 			switch (self.type.kindof)
 			{
 				case SIGNED_INT:
-					return formatter.printf("%d", self.i)!;
+					return formatter.printf("%d", (int128)self.i)!;
 				case UNSIGNED_INT:
 					return formatter.printf("%d", (uint128)self.i)!;
 				case FLOAT:
-					return formatter.printf("%d", self.f)!;
+					return formatter.printf("%g", self.f)!;
 				case ENUM:
 					return formatter.printf("%d", self.i)!;
 				default:
@@ -148,9 +148,9 @@ fn bool Object.is_int(&self) @inline => self.type == int128.typeid;
 fn bool Object.is_keyable(&self) => self.is_empty() || self.is_map();
 fn bool Object.is_indexable(&self) => self.is_empty() || self.is_array();
 
-/**
- * @require self.is_keyable()
- **/
+<*
+ @require self.is_keyable()
+*>
 fn void Object.init_map_if_needed(&self) @private
 {
 	if (self.is_empty())
@@ -160,9 +160,9 @@ fn void Object.init_map_if_needed(&self) @private
 	}
 }
 
-/**
- * @require self.is_indexable()
- **/
+<*
+ @require self.is_indexable()
+*>
 fn void Object.init_array_if_needed(&self) @private
 {
 	if (self.is_empty())
@@ -172,9 +172,9 @@ fn void Object.init_array_if_needed(&self) @private
 	}
 }
 
-/**
- * @require self.is_keyable()
- **/
+<*
+ @require self.is_keyable()
+*>
 fn void Object.set_object(&self, String key, Object* new_object) @private
 {
 	self.init_map_if_needed();
@@ -218,9 +218,9 @@ macro Object* Object.set(&self, String key, value)
 	return val;
 }
 
-/**
- * @require self.is_indexable()
- **/
+<*
+ @require self.is_indexable()
+*>
 macro Object* Object.set_at(&self, usz index, String key, value)
 {
 	Object* val = self.object_from_value(value);
@@ -228,10 +228,10 @@ macro Object* Object.set_at(&self, usz index, String key, value)
 	return val;
 }
 
-/**
- * @require self.is_indexable()
- * @ensure return != null
- **/
+<*
+ @require self.is_indexable()
+ @ensure return != null
+*>
 macro Object* Object.push(&self, value)
 {
 	Object* val = self.object_from_value(value);
@@ -239,42 +239,42 @@ macro Object* Object.push(&self, value)
 	return val;
 }
 
-/**
- * @require self.is_keyable()
- **/
+<*
+ @require self.is_keyable()
+*>
 fn Object*! Object.get(&self, String key) => self.is_empty() ? SearchResult.MISSING? : self.map.get(key);
 
 
 fn bool Object.has_key(&self, String key) => self.is_map() && self.map.has_key(key);
 
-/**
- * @require self.is_indexable()
- **/
+<*
+ @require self.is_indexable()
+*>
 fn Object* Object.get_at(&self, usz index)
 {
 	return self.array.get(index);
 }
 
-/**
- * @require self.is_indexable()
- **/
+<*
+ @require self.is_indexable()
+*>
 fn usz Object.get_len(&self)
 {
 	return self.array.len();
 }
 
-/**
- * @require self.is_indexable()
- **/
+<*
+ @require self.is_indexable()
+*>
 fn void Object.push_object(&self, Object* to_append)
 {
 	self.init_array_if_needed();
 	self.array.push(to_append);
 }
 
-/**
- * @require self.is_indexable()
- **/
+<*
+ @require self.is_indexable()
+*>
 fn void Object.set_object_at(&self, usz index, Object* to_set)
 {
 	self.init_array_if_needed();
@@ -291,9 +291,9 @@ fn void Object.set_object_at(&self, usz index, Object* to_set)
 	self.array.set_at(index, to_set);
 }
 
-/**
- * @require $Type.kindof.is_int() "Expected an integer type."
- **/
+<*
+ @require $Type.kindof.is_int() "Expected an integer type."
+*>
 macro get_integer_value(Object* value, $Type)
 {
 	if (value.is_float())
@@ -313,19 +313,19 @@ macro get_integer_value(Object* value, $Type)
 }
 
 
-/**
- * @require self.is_indexable()
- * @require $Type.kindof.is_int() : "Expected an integer type"
- **/
+<*
+ @require self.is_indexable()
+ @require $Type.kindof.is_int() : "Expected an integer type"
+*>
 macro Object.get_integer_at(&self, $Type, usz index) @private
 {
 	return get_integer_value(self.get_at(index), $Type);
 }
 
-/**
- * @require self.is_keyable()
- * @require $Type.kindof.is_int() : "Expected an integer type"
- **/
+<*
+ @require self.is_keyable()
+ @require $Type.kindof.is_int() : "Expected an integer type"
+*>
 macro Object.get_integer(&self, $Type, String key) @private
 {
 	return get_integer_value(self.get(key), $Type);
@@ -355,9 +355,9 @@ fn uint! Object.get_uint_at(&self, usz index) => self.get_integer_at(uint, index
 fn ulong! Object.get_ulong_at(&self, usz index) => self.get_integer_at(ulong, index);
 fn uint128! Object.get_uint128_at(&self, usz index) => self.get_integer_at(uint128, index);
 
-/**
- * @require self.is_keyable()
- **/
+<*
+ @require self.is_keyable()
+*>
 fn String! Object.get_string(&self, String key)
 {
 	Object* value = self.get(key)!;
@@ -365,9 +365,9 @@ fn String! Object.get_string(&self, String key)
 	return value.s;
 }
 
-/**
- * @require self.is_indexable()
- **/
+<*
+ @require self.is_indexable()
+*>
 fn String! Object.get_string_at(&self, usz index)
 {
 	Object* value = self.get_at(index);
@@ -375,9 +375,9 @@ fn String! Object.get_string_at(&self, usz index)
 	return value.s;
 }
 
-/**
- * @require self.is_keyable()
- **/
+<*
+ @require self.is_keyable()
+*>
 macro String! Object.get_enum(&self, $EnumType, String key)
 {
 	Object value = self.get(key)!;
@@ -385,9 +385,9 @@ macro String! Object.get_enum(&self, $EnumType, String key)
 	return ($EnumType)value.i;
 }
 
-/**
- * @require self.is_indexable()
- **/
+<*
+ @require self.is_indexable()
+*>
 macro String! Object.get_enum_at(&self, $EnumType, usz index)
 {
 	Object value = self.get_at(index);
@@ -395,9 +395,9 @@ macro String! Object.get_enum_at(&self, $EnumType, usz index)
 	return ($EnumType)value.i;
 }
 
-/**
- * @require self.is_keyable()
- **/
+<*
+ @require self.is_keyable()
+*>
 fn bool! Object.get_bool(&self, String key)
 {
 	Object* value = self.get(key)!;
@@ -406,9 +406,9 @@ fn bool! Object.get_bool(&self, String key)
 }
 
 
-/**
- * @require self.is_indexable()
- **/
+<*
+ @require self.is_indexable()
+*>
 fn bool! Object.get_bool_at(&self, usz index)
 {
 	Object* value = self.get_at(index);
@@ -416,9 +416,9 @@ fn bool! Object.get_bool_at(&self, usz index)
 	return value.b;
 }
 
-/**
- * @require self.is_keyable()
- **/
+<*
+ @require self.is_keyable()
+*>
 fn double! Object.get_float(&self, String key)
 {
 	Object* value = self.get(key)!;
@@ -435,9 +435,9 @@ fn double! Object.get_float(&self, String key)
 	}
 }
 
-/**
- * @require self.is_indexable()
- **/
+<*
+ @require self.is_indexable()
+*>
 fn double! Object.get_float_at(&self, usz index)
 {
 	Object* value = self.get_at(index);

lib/std/collections/priorityqueue.c3

@@ -46,6 +46,7 @@ fn void PrivatePriorityQueue.temp_init(&self, usz initial_capacity = 16) @inline
 	self.heap.new_init(initial_capacity, allocator::temp()) @inline;
 }
 
+
 fn void PrivatePriorityQueue.push(&self, Type element)
 {
 	self.heap.push(element);
@@ -66,9 +67,18 @@ fn void PrivatePriorityQueue.push(&self, Type element)
 	}
 }
 
-/**
-* @require self != null
-*/
+fn void PrivatePriorityQueue.remove_at(&self, usz index)
+{
+	if (index == 0)
+	{
+		self.pop()!!;
+		return;
+	}
+	self.heap.remove_at(index);
+}
+<*
+ @require self != null
+*>
 fn Type! PrivatePriorityQueue.pop(&self)
 {
 	usz i = 0;
@@ -128,9 +138,9 @@ fn bool PrivatePriorityQueue.is_empty(&self)
 	return self.heap.is_empty();
 }
 
-/**
- * @require index < self.len()
- */
+<*
+ @require index < self.len()
+*>
 fn Type PrivatePriorityQueue.get(&self, usz index) @operator([])
 {
 	return self.heap[index];

lib/std/collections/range.c3

@@ -1,6 +1,6 @@
-/**
- * @require Type.is_ordered : "The type must be ordered"
- **/
+<*
+ @require Type.is_ordered : "The type must be ordered"
+*>
 module std::collections::range(<Type>);
 import std::io;
 
@@ -21,9 +21,9 @@ fn bool Range.contains(&self, Type value) @inline
 	return value >= self.start && value <= self.end;
 }
 
-/**
- * @require index < self.len() : "Can't index into an empty range"
- **/
+<*
+ @require index < self.len() : "Can't index into an empty range"
+*>
 fn Type Range.get(&self, usz index) @operator([])
 {
 	return (Type)(self.start + (usz)index);
@@ -86,9 +86,9 @@ fn String ExclusiveRange.to_tstring(&self)
 	return self.to_new_string(allocator::temp());
 }
 
-/**
- * @require index < self.len() : "Can't index into an empty range"
- **/
+<*
+ @require index < self.len() : "Can't index into an empty range"
+*>
 fn Type ExclusiveRange.get(&self, usz index) @operator([])
 {
 	return (Type)(self.start + index);

lib/std/collections/ringbuffer.c3

@@ -1,3 +1,6 @@
+<*
+ @require values::@is_int(SIZE) &&& SIZE > 0 "The size must be positive integer"
+*>
 module std::collections::ringbuffer(<Type, SIZE>);
 
 struct RingBuffer

lib/std/collections/tuple.c3

@@ -1,6 +1,6 @@
 module std::collections::tuple(<Type1, Type2>);
 
-struct Tuple @adhoc
+struct Tuple
 {
 	Type1 first;
 	Type2 second;
@@ -8,7 +8,7 @@ struct Tuple @adhoc
 
 module std::collections::triple(<Type1, Type2, Type3>);
 
-struct Triple @adhoc
+struct Triple
 {
 	Type1 first;
 	Type2 second;

lib/std/compression/qoi.c3

@@ -2,34 +2,34 @@ module std::compression::qoi;
 
 const uint PIXELS_MAX = 400000000;
 
-/**
- * Colorspace.
- * Purely informative. It will be saved to the file header,
- * but does not affect how chunks are en-/decoded.
- */
+<*
+ Colorspace.
+ Purely informative. It will be saved to the file header,
+ but does not affect how chunks are en-/decoded.
+*>
 enum QOIColorspace : char (char id)
 {
-    SRGB = 0, 	// sRGB with linear alpha
-    LINEAR = 1 	// all channels linear
+	SRGB = 0, 	// sRGB with linear alpha
+	LINEAR = 1 	// all channels linear
 }
 
-/**
- * Channels.
- * The channels used in an image.
- * AUTO can be used when decoding to automatically determine
- * the channels from the file's header.
- */
+<*
+ Channels.
+ The channels used in an image.
+ AUTO can be used when decoding to automatically determine
+ the channels from the file's header.
+*>
 enum QOIChannels : char (char id)
 {
 	AUTO = 0,
-    RGB = 3,
-    RGBA = 4
+	RGB = 3,
+	RGBA = 4
 }
 
-/**
- * Descriptor.
- * Contains information about an image.
- */
+<*
+ Descriptor.
+ Contains information about an image.
+*>
 struct QOIDesc
 {
 	uint width;
@@ -38,10 +38,10 @@ struct QOIDesc
 	QOIColorspace colorspace;
 }
 
-/**
- * QOI Errors.
- * These are all the possible bad outcomes.
- */
+<*
+ QOI Errors.
+ These are all the possible bad outcomes.
+*>
 fault QOIError
 {
 	INVALID_PARAMETERS,
@@ -56,21 +56,21 @@ fault QOIError
 module std::compression::qoi @if(!$feature(QOI_NO_STDIO));
 import std::io;
 
-/**
- * Encode raw RGB or RGBA pixels into a QOI image and write it to the
- * file system.
- * 
- * The desc struct must be filled with the image width, height, the
- * used channels (QOIChannels.RGB or RGBA) and the colorspace
- * (QOIColorspace.SRGB or LINEAR).
- * 
- * The function returns an optional, which can either be a QOIError
- * or the number of bytes written on success.
- * 
- * @param [in] filename `The file's name to write the image to`
- * @param [in] input `The raw RGB or RGBA pixels to encode`
- * @param [&in] desc `The descriptor of the image`
- */
+<*
+ Encode raw RGB or RGBA pixels into a QOI image and write it to the
+ file system.
+
+ The desc struct must be filled with the image width, height, the
+ used channels (QOIChannels.RGB or RGBA) and the colorspace
+ (QOIColorspace.SRGB or LINEAR).
+
+ The function returns an optional, which can either be a QOIError
+ or the number of bytes written on success.
+
+ @param [in] filename `The file's name to write the image to`
+ @param [in] input `The raw RGB or RGBA pixels to encode`
+ @param [&in] desc `The descriptor of the image`
+*>
 fn usz! write(String filename, char[] input, QOIDesc* desc)
 {
 	@pool() {
@@ -91,27 +91,27 @@ fn usz! write(String filename, char[] input, QOIDesc* desc)
 }
 
 
-/**
- * Read and decode a QOI image from the file system.
- * 
- * If channels is set to QOIChannels.AUTO, the function will
- * automatically determine the channels from the file's header.
- * However, if channels is RGB or RGBA, the output format will be
- * forced into this number of channels.
- * 
- * The desc struct will be filled with the width, height,
- * channels and colorspace of the image.
- * 
- * The function returns an optional, which can either be a QOIError
- * or a char[] pointing to the decoded pixels on success.
- * 
- * The returned pixel data should be free()d after use, or the decoding
- * and use of the data should be wrapped in a @pool() { ... }; block.
- * 
- * @param [in] filename `The file's name to read the image from`
- * @param [&out] desc `The descriptor to fill with the image's info`
- * @param channels `The channels to be used`
- */
+<*
+ Read and decode a QOI image from the file system.
+
+ If channels is set to QOIChannels.AUTO, the function will
+ automatically determine the channels from the file's header.
+ However, if channels is RGB or RGBA, the output format will be
+ forced into this number of channels.
+
+ The desc struct will be filled with the width, height,
+ channels and colorspace of the image.
+
+ The function returns an optional, which can either be a QOIError
+ or a char[] pointing to the decoded pixels on success.
+
+ The returned pixel data should be free()d after use, or the decoding
+ and use of the data should be wrapped in a @pool() { ... }; block.
+
+ @param [in] filename `The file's name to read the image from`
+ @param [&out] desc `The descriptor to fill with the image's info`
+ @param channels `The channels to be used`
+*>
 fn char[]! read(String filename, QOIDesc* desc, QOIChannels channels = AUTO, Allocator allocator = allocator::heap())
 {
 	// read file
@@ -128,19 +128,19 @@ fn char[]! read(String filename, QOIDesc* desc, QOIChannels channels = AUTO, All
 module std::compression::qoi;
 import std::bits;
 
-/**
- * Encode raw RGB or RGBA pixels into a QOI image in memory.
- * 
- * The function returns an optional, which can either be a QOIError
- * or a char[] pointing to the encoded data on success.
- * 
- * The returned qoi data should be free()d after use, or the encoding
- * and use of the data should be wrapped in a @pool() { ... }; block.
- * See the write() function for an example.
- * 
- * @param [in] input `The raw RGB or RGBA pixels to encode`
- * @param [&in] desc `The descriptor of the image`
- */
+<*
+ Encode raw RGB or RGBA pixels into a QOI image in memory.
+
+ The function returns an optional, which can either be a QOIError
+ or a char[] pointing to the encoded data on success.
+
+ The returned qoi data should be free()d after use, or the encoding
+ and use of the data should be wrapped in a @pool() { ... }; block.
+ See the write() function for an example.
+
+ @param [in] input `The raw RGB or RGBA pixels to encode`
+ @param [&in] desc `The descriptor of the image`
+*>
 fn char[]! encode(char[] input, QOIDesc* desc, Allocator allocator = allocator::heap())
 {
 	// check info in desc
@@ -266,27 +266,27 @@ fn char[]! encode(char[] input, QOIDesc* desc, Allocator allocator = allocator::
 }
 
 
-/**
- * Decode a QOI image from memory.
- * 
- * If channels is set to QOIChannels.AUTO, the function will
- * automatically determine the channels from the file's header.
- * However, if channels is RGB or RGBA, the output format will be
- * forced into this number of channels.
- * 
- * The desc struct will be filled with the width, height,
- * channels and colorspace of the image.
- * 
- * The function returns an optional, which can either be a QOIError
- * or a char[] pointing to the decoded pixels on success.
- * 
- * The returned pixel data should be free()d after use, or the decoding
- * and use of the data should be wrapped in a @pool() { ... }; block.
- * 
- * @param [in] data `The QOI image data to decode`
- * @param [&out] desc `The descriptor to fill with the image's info`
- * @param channels `The channels to be used`
- */
+<*
+ Decode a QOI image from memory.
+
+ If channels is set to QOIChannels.AUTO, the function will
+ automatically determine the channels from the file's header.
+ However, if channels is RGB or RGBA, the output format will be
+ forced into this number of channels.
+
+ The desc struct will be filled with the width, height,
+ channels and colorspace of the image.
+
+ The function returns an optional, which can either be a QOIError
+ or a char[] pointing to the decoded pixels on success.
+
+ The returned pixel data should be free()d after use, or the decoding
+ and use of the data should be wrapped in a @pool() { ... }; block.
+
+ @param [in] data `The QOI image data to decode`
+ @param [&out] desc `The descriptor to fill with the image's info`
+ @param channels `The channels to be used`
+*>
 fn char[]! decode(char[] data, QOIDesc* desc, QOIChannels channels = AUTO, Allocator allocator = allocator::heap())
 {
 	// check input data

lib/std/core/allocators/arena_allocator.c3

@@ -10,13 +10,14 @@ struct ArenaAllocator (Allocator)
 	usz used;
 }
 
-/**
- * Initialize a memory arena for use using the provided bytes.
- **/
-fn void ArenaAllocator.init(&self, char[] data)
+<*
+ Initialize a memory arena for use using the provided bytes.
+*>
+fn ArenaAllocator* ArenaAllocator.init(&self, char[] data)
 {
 	self.data = data;
 	self.used = 0;
+	return self;
 }
 
 fn void ArenaAllocator.clear(&self)
@@ -30,9 +31,9 @@ struct ArenaAllocatorHeader @local
 	char[*] data;
 }
 
-/*
- * @require ptr != null
- **/
+<*
+ @require ptr != null
+*>
 fn void ArenaAllocator.release(&self, void* ptr, bool) @dynamic
 {
 	assert((uptr)ptr >= (uptr)self.data.ptr, "Pointer originates from a different allocator.");
@@ -47,11 +48,11 @@ fn void ArenaAllocator.release(&self, void* ptr, bool) @dynamic
 fn usz ArenaAllocator.mark(&self) @dynamic => self.used;
 fn void ArenaAllocator.reset(&self, usz mark) @dynamic => self.used = mark;
 
-/**
- * @require !alignment || math::is_power_of_2(alignment)
- * @require alignment <= mem::MAX_MEMORY_ALIGNMENT `alignment too big`
- * @require size > 0
- **/
+<*
+ @require !alignment || math::is_power_of_2(alignment)
+ @require alignment <= mem::MAX_MEMORY_ALIGNMENT `alignment too big`
+ @require size > 0
+*>
 fn void*! ArenaAllocator.acquire(&self, usz size, AllocInitType init_type, usz alignment) @dynamic
 {
 	alignment = alignment_for_allocation(alignment);
@@ -69,12 +70,12 @@ fn void*! ArenaAllocator.acquire(&self, usz size, AllocInitType init_type, usz a
 	return mem;
 }
 
-/**
- * @require !alignment || math::is_power_of_2(alignment)
- * @require alignment <= mem::MAX_MEMORY_ALIGNMENT `alignment too big`
- * @require old_pointer != null
- * @require size > 0
- **/
+<*
+ @require !alignment || math::is_power_of_2(alignment)
+ @require alignment <= mem::MAX_MEMORY_ALIGNMENT `alignment too big`
+ @require old_pointer != null
+ @require size > 0
+*>
 fn void*! ArenaAllocator.resize(&self, void *old_pointer, usz size, usz alignment) @dynamic
 {
 	alignment = alignment_for_allocation(alignment);

lib/std/core/allocators/dynamic_arena.c3

@@ -12,10 +12,10 @@ struct DynamicArenaAllocator (Allocator)
 	usz page_size;
 }
 
-/**
- * @param [&inout] allocator
- * @require page_size >= 128
- **/
+<*
+ @param [&inout] allocator
+ @require page_size >= 128
+*>
 fn void DynamicArenaAllocator.init(&self, usz page_size, Allocator allocator)
 {
 	self.page = null;
@@ -60,10 +60,10 @@ struct DynamicArenaChunk @local
 	usz size;
 }
 
-/**
- * @require ptr
- * @require self.page `tried to free pointer on invalid allocator`
- */
+<*
+ @require ptr
+ @require self.page `tried to free pointer on invalid allocator`
+*>
 fn void DynamicArenaAllocator.release(&self, void* ptr, bool) @dynamic
 {
 	DynamicArenaPage* current_page = self.page;
@@ -74,11 +74,11 @@ fn void DynamicArenaAllocator.release(&self, void* ptr, bool) @dynamic
 	current_page.current_stack_ptr = null;
 }
 
-/**
- * @require size > 0 `Resize doesn't support zeroing`
- * @require old_pointer != null `Resize doesn't handle null pointers`
- * @require self.page `tried to realloc pointer on invalid allocator`
- */
+<*
+ @require size > 0 `Resize doesn't support zeroing`
+ @require old_pointer != null `Resize doesn't handle null pointers`
+ @require self.page `tried to realloc pointer on invalid allocator`
+*>
 fn void*! DynamicArenaAllocator.resize(&self, void* old_pointer, usz size, usz alignment) @dynamic
 {
 	DynamicArenaPage* current_page = self.page;
@@ -126,10 +126,10 @@ fn void DynamicArenaAllocator.reset(&self, usz mark = 0) @dynamic
 	self.page = page;
 }
 
-/**
- * @require math::is_power_of_2(alignment)
- * @require size > 0
- */
+<*
+ @require math::is_power_of_2(alignment)
+ @require size > 0
+*>
 fn void*! DynamicArenaAllocator._alloc_new(&self, usz size, usz alignment) @local
 {
 	// First, make sure that we can align it, extending the page size if needed.
@@ -156,10 +156,10 @@ fn void*! DynamicArenaAllocator._alloc_new(&self, usz size, usz alignment) @loca
 	return mem_start;
 }
 
-/**
- * @require size > 0 `acquire expects size > 0`
- * @require !alignment || math::is_power_of_2(alignment)
- */
+<*
+ @require size > 0 `acquire expects size > 0`
+ @require !alignment || math::is_power_of_2(alignment)
+*>
 fn void*! DynamicArenaAllocator.acquire(&self, usz size, AllocInitType init_type, usz alignment) @dynamic
 {
 	alignment = alignment_for_allocation(alignment);

lib/std/core/allocators/heap_allocator.c3

@@ -11,10 +11,10 @@ struct SimpleHeapAllocator (Allocator)
 	Header* free_list;
 }
 
-/**
- * @require allocator "An underlying memory provider must be given"
- * @require !self.free_list "The allocator may not be already initialized"
- **/
+<*
+ @require allocator "An underlying memory provider must be given"
+ @require !self.free_list "The allocator may not be already initialized"
+*>
 fn void SimpleHeapAllocator.init(&self, MemoryAllocFn allocator)
 {
 	self.alloc_fn = allocator;
@@ -49,9 +49,9 @@ fn void SimpleHeapAllocator.release(&self, void* old_pointer, bool aligned) @dyn
 	}
 }
 
-/**
- * @require old_pointer && bytes > 0
- **/
+<*
+ @require old_pointer && bytes > 0
+*>
 fn void*! SimpleHeapAllocator._realloc(&self, void* old_pointer, usz bytes) @local
 {
 	// Find the block header.
@@ -98,7 +98,7 @@ fn void*! SimpleHeapAllocator._alloc(&self, usz bytes) @local
 				return current + 1;
 			case current.size > aligned_bytes:
 				Header* unallocated = (Header*)((char*)current + aligned_bytes + Header.sizeof);
-				unallocated.size = current.size - aligned_bytes;
+				unallocated.size = current.size - aligned_bytes - Header.sizeof;
 				unallocated.next = current.next;
 				if (current == self.free_list)
 				{

lib/std/core/allocators/libc_allocator.c3

@@ -28,7 +28,7 @@ fn void*! LibcAllocator.acquire(&self, usz bytes, AllocInitType init_type, usz a
 			mem::clear(data, bytes, mem::DEFAULT_MEM_ALIGNMENT);
 			return data;
 		}
-        return libc::calloc(1, bytes) ?: AllocationFailure.OUT_OF_MEMORY?;
+		return libc::calloc(1, bytes) ?: AllocationFailure.OUT_OF_MEMORY?;
 	}
 	else
 	{
@@ -41,17 +41,17 @@ fn void*! LibcAllocator.acquire(&self, usz bytes, AllocInitType init_type, usz a
 		{
 			if (!(data = libc::malloc(bytes))) return AllocationFailure.OUT_OF_MEMORY?;
 		}
-        $if env::TESTING:
-		    for (usz i = 0; i < bytes; i++) ((char*)data)[i] = 0xAA;
-        $endif
-        return data;
+		$if env::TESTING:
+			for (usz i = 0; i < bytes; i++) ((char*)data)[i] = 0xAA;
+		$endif
+		return data;
 	}
 }
 
 fn void*! LibcAllocator.resize(&self, void* old_ptr, usz new_bytes, usz alignment) @dynamic
 {
 	if (alignment <= mem::DEFAULT_MEM_ALIGNMENT) return libc::realloc(old_ptr, new_bytes) ?: AllocationFailure.OUT_OF_MEMORY?;
-    void* new_ptr;
+	void* new_ptr;
 	if (posix::posix_memalign(&new_ptr, alignment, new_bytes)) return AllocationFailure.OUT_OF_MEMORY?;
 
 	$switch
@@ -90,10 +90,10 @@ fn void*! LibcAllocator.acquire(&self, usz bytes, AllocInitType init_type, usz a
 	}
 	void* data = alignment > 0 ? win32::_aligned_malloc(bytes, alignment) : libc::malloc(bytes);
 	if (!data) return AllocationFailure.OUT_OF_MEMORY?;
-    $if env::TESTING:
+	$if env::TESTING:
 		for (usz i = 0; i < bytes; i++) ((char*)data)[i] = 0xAA;
 	$endif
-    return data;
+	return data;
 }
 
 fn void*! LibcAllocator.resize(&self, void* old_ptr, usz new_bytes, usz alignment) @dynamic
@@ -109,8 +109,8 @@ fn void LibcAllocator.release(&self, void* old_ptr, bool aligned) @dynamic
 {
 	if (aligned)
 	{
-    	win32::_aligned_free(old_ptr);
-    	return;
+		win32::_aligned_free(old_ptr);
+		return;
 	}
 	libc::free(old_ptr);
 }
@@ -123,16 +123,16 @@ fn void*! LibcAllocator.acquire(&self, usz bytes, AllocInitType init_type, usz a
 	if (init_type == ZERO)
 	{
 		void* data = alignment ? @aligned_alloc(fn void*(usz bytes) => libc::calloc(bytes, 1), bytes, alignment)!! : libc::calloc(bytes, 1);
-        return data ?: AllocationFailure.OUT_OF_MEMORY?;
+		return data ?: AllocationFailure.OUT_OF_MEMORY?;
 	}
 	else
 	{
 		void* data = alignment ? @aligned_alloc(libc::malloc, bytes, alignment)!! : libc::malloc(bytes);
-        if (!data) return AllocationFailure.OUT_OF_MEMORY?;
-        $if env::TESTING:
-		    for (usz i = 0; i < bytes; i++) ((char*)data)[i] = 0xAA;
-        $endif
-        return data;
+		if (!data) return AllocationFailure.OUT_OF_MEMORY?;
+		$if env::TESTING:
+			for (usz i = 0; i < bytes; i++) ((char*)data)[i] = 0xAA;
+		$endif
+		return data;
 	}
 }
 

lib/std/core/allocators/on_stack_allocator.c3

@@ -16,10 +16,11 @@ struct OnStackAllocatorExtraChunk @local
 	void* data;
 }
 
-/**
- * @param [&inout] allocator
- * Initialize a memory arena for use using the provided bytes.
- **/
+<*
+ Initialize a memory arena for use using the provided bytes.
+
+ @param [&inout] allocator
+*>
 fn void OnStackAllocator.init(&self, char[] data, Allocator allocator)
 {
 	self.data = data;
@@ -54,9 +55,9 @@ struct OnStackAllocatorHeader
 	char[*] data;
 }
 
-/**
- * @require old_pointer
- **/
+<*
+ @require old_pointer
+*>
 fn void OnStackAllocator.release(&self, void* old_pointer, bool aligned) @dynamic
 {
 	if (allocation_in_stack_mem(self, old_pointer)) return;
@@ -98,11 +99,11 @@ fn OnStackAllocatorExtraChunk* on_stack_allocator_find_chunk(OnStackAllocator* a
 	return null;
 }
 
-/**
- * @require size > 0
- * @require old_pointer != null
- * @require alignment <= mem::MAX_MEMORY_ALIGNMENT `alignment too big`
- **/
+<*
+ @require size > 0
+ @require old_pointer != null
+ @require alignment <= mem::MAX_MEMORY_ALIGNMENT `alignment too big`
+*>
 fn void*! OnStackAllocator.resize(&self, void* old_pointer, usz size, usz alignment) @dynamic
 {
 	if (!allocation_in_stack_mem(self, old_pointer))
@@ -119,10 +120,10 @@ fn void*! OnStackAllocator.resize(&self, void* old_pointer, usz size, usz alignm
 	return mem;
 }
 
-/**
- * @require alignment <= mem::MAX_MEMORY_ALIGNMENT `alignment too big`
- * @require size > 0
- **/
+<*
+ @require alignment <= mem::MAX_MEMORY_ALIGNMENT `alignment too big`
+ @require size > 0
+*>
 fn void*! OnStackAllocator.acquire(&self, usz size, AllocInitType init_type, usz alignment) @dynamic
 {
 	bool aligned = alignment > 0;

lib/std/core/allocators/temp_allocator.c3

@@ -32,9 +32,9 @@ struct TempAllocatorPage
 macro usz TempAllocatorPage.pagesize(&self) => self.size & ~PAGE_IS_ALIGNED;
 macro bool TempAllocatorPage.is_aligned(&self) => self.size & PAGE_IS_ALIGNED == PAGE_IS_ALIGNED;
 
-/**
- * @require size >= 16
- **/
+<*
+ @require size >= 16
+*>
 fn TempAllocator*! new_temp_allocator(usz size, Allocator allocator)
 {
 	TempAllocator* temp = allocator::alloc_with_padding(allocator, TempAllocator, size)!;
@@ -134,11 +134,11 @@ fn void*! TempAllocator.resize(&self, void* pointer, usz size, usz alignment) @d
 	return data;
 }
 
-/**
- * @require size > 0
- * @require !alignment || math::is_power_of_2(alignment)
- * @require alignment <= mem::MAX_MEMORY_ALIGNMENT `alignment too big`
- **/
+<*
+ @require size > 0
+ @require !alignment || math::is_power_of_2(alignment)
+ @require alignment <= mem::MAX_MEMORY_ALIGNMENT `alignment too big`
+*>
 fn void*! TempAllocator.acquire(&self, usz size, AllocInitType init_type, usz alignment) @dynamic
 {
 	alignment = alignment_for_allocation(alignment);

lib/std/core/allocators/tracking_allocator.c3

@@ -26,29 +26,29 @@ struct TrackingAllocator (Allocator)
 	usz allocs_total;
 }
 
-/**
- * Initialize a tracking allocator to wrap (and track) another allocator.
- *
- * @param [&inout] allocator "The allocator to track"
- **/
+<*
+ Initialize a tracking allocator to wrap (and track) another allocator.
+
+ @param [&inout] allocator "The allocator to track"
+*>
 fn void TrackingAllocator.init(&self, Allocator allocator)
 {
 	*self = { .inner_allocator = allocator };
 	self.map.new_init(allocator: allocator);
 }
 
-/**
- * Free this tracking allocator.
- **/
+<*
+ Free this tracking allocator.
+*>
 fn void TrackingAllocator.free(&self)
 {
 	self.map.free();
 	*self = {};
 }
 
-/**
- * @return "the total allocated memory not yet freed."
- **/
+<*
+ @return "the total allocated memory not yet freed."
+*>
 fn usz TrackingAllocator.allocated(&self)
 {
 	usz allocated = 0;
@@ -59,14 +59,14 @@ fn usz TrackingAllocator.allocated(&self)
 	return allocated;
 }
 
-/**
- * @return "the total memory allocated (freed or not)."
- **/
+<*
+ @return "the total memory allocated (freed or not)."
+*>
 fn usz TrackingAllocator.total_allocated(&self) => self.mem_total;
 
-/**
- * @return "the total number of allocations (freed or not)."
- **/
+<*
+ @return "the total number of allocations (freed or not)."
+*>
 fn usz TrackingAllocator.total_allocation_count(&self) => self.allocs_total;
 
 fn Allocation[] TrackingAllocator.allocations_tlist(&self, Allocator allocator)
@@ -74,9 +74,9 @@ fn Allocation[] TrackingAllocator.allocations_tlist(&self, Allocator allocator)
 	return self.map.value_tlist();
 }
 
-/**
- * @return "the number of non-freed allocations."
- **/
+<*
+ @return "the number of non-freed allocations."
+*>
 fn usz TrackingAllocator.allocation_count(&self) => self.map.count;
 
 fn void*! TrackingAllocator.acquire(&self, usz size, AllocInitType init_type, usz alignment) @dynamic
@@ -86,7 +86,7 @@ fn void*! TrackingAllocator.acquire(&self, usz size, AllocInitType init_type, us
 	void*[MAX_BACKTRACE] bt;
 	backtrace::capture_current(&bt);
 	self.map.set((uptr)data, { data, size, bt });
-    self.mem_total += size;
+	self.mem_total += size;
 	return data;
 }
 
@@ -97,7 +97,7 @@ fn void*! TrackingAllocator.resize(&self, void* old_pointer, usz size, usz align
 	void*[MAX_BACKTRACE] bt;
 	backtrace::capture_current(&bt);
 	self.map.set((uptr)data, { data, size, bt });
-    self.mem_total += size;
+	self.mem_total += size;
 	self.allocs_total++;
 	return data;
 }
@@ -105,9 +105,9 @@ fn void*! TrackingAllocator.resize(&self, void* old_pointer, usz size, usz align
 fn void TrackingAllocator.release(&self, void* old_pointer, bool is_aligned) @dynamic
 {
 	if (catch self.map.remove((uptr)old_pointer))
-    {
-        unreachable("Attempt to release untracked pointer %p, this is likely a bug.", old_pointer);
-    }
+	{
+		unreachable("Attempt to release untracked pointer %p, this is likely a bug.", old_pointer);
+	}
 	self.inner_allocator.release(old_pointer, is_aligned);
 }
 
@@ -132,14 +132,14 @@ fn void! TrackingAllocator.fprint_report(&self, OutStream out)
 			if (!allocs[0].backtrace[0])
 			{
 				io::fprintn(out, "======== Memory Report ========")!;
-            	io::fprintn(out, "Size in bytes   Address")!;
-            	foreach (i, &allocation : allocs)
-            	{
-            	    entries++;
-            		total += allocation.size;
-            		io::fprintfn(out, "%13s   %p", allocation.size, allocation.ptr)!;
-            	}
-            	io::fprintn(out, "===============================")!;
+				io::fprintn(out, "Size in bytes   Address")!;
+				foreach (i, &allocation : allocs)
+				{
+					entries++;
+					total += allocation.size;
+					io::fprintfn(out, "%13s   %p", allocation.size, allocation.ptr)!;
+				}
+				io::fprintn(out, "===============================")!;
 
 			}
 			else
@@ -169,48 +169,48 @@ fn void! TrackingAllocator.fprint_report(&self, OutStream out)
 			io::fprintn(out, "* NO ALLOCATIONS FOUND *")!;
 		}
 		io::fprintfn(out, "- Total currently allocated memory:            %d", total)!;
-        io::fprintfn(out, "- Total current allocations:                   %d", entries)!;
-        io::fprintfn(out, "- Total allocations (freed and retained):      %d", self.allocs_total)!;
-        io::fprintfn(out, "- Total allocated memory (freed and retained): %d", self.mem_total)!;
-        if (leaks)
-        {
+		io::fprintfn(out, "- Total current allocations:                   %d", entries)!;
+		io::fprintfn(out, "- Total allocations (freed and retained):      %d", self.allocs_total)!;
+		io::fprintfn(out, "- Total allocated memory (freed and retained): %d", self.mem_total)!;
+		if (leaks)
+		{
 			io::fprintn(out)!;
 			io::fprintn(out, "Full leak report:")!;
-            foreach (i, &allocation : allocs)
-            {
-                if (!allocation.backtrace[3])
-                {
-                    io::fprintfn(out, "Allocation %d (%d bytes) - no backtrace available.", i + 1, allocation.size)!;
-                	continue;
+			foreach (i, &allocation : allocs)
+			{
+				if (!allocation.backtrace[3])
+				{
+					io::fprintfn(out, "Allocation %d (%d bytes) - no backtrace available.", i + 1, allocation.size)!;
+					continue;
 				}
-                BacktraceList backtraces = {};
-                usz end = MAX_BACKTRACE;
-                foreach (j, val : allocation.backtrace)
-                {
-                    if (!val)
-                	{
-                	    end = j;
-                	    break;
+				BacktraceList backtraces = {};
+				usz end = MAX_BACKTRACE;
+				foreach (j, val : allocation.backtrace)
+				{
+					if (!val)
+					{
+						end = j;
+						break;
 					}
 				}
-        		BacktraceList list = backtrace::symbolize_backtrace(allocation.backtrace[3..(end - 1)], allocator::temp())!;
-                io::fprintfn(out, "Allocation %d (%d bytes): ", i + 1, allocation.size)!;
-        		foreach (trace : list)
-        		{
-        			if (trace.has_file())
-                	{
-                	    io::fprintfn(out, "   %s (in %s:%d)", trace.function, trace.file, trace.line);
-                	    continue;
-                	}
-                	if (trace.is_unknown())
-                	{
-                	    io::fprintfn(out, "   ??? (in unknown)");
-                	    continue;
-                	}
+				BacktraceList list = backtrace::symbolize_backtrace(allocation.backtrace[3..(end - 1)], allocator::temp())!;
+				io::fprintfn(out, "Allocation %d (%d bytes): ", i + 1, allocation.size)!;
+				foreach (trace : list)
+				{
+					if (trace.has_file())
+					{
+						io::fprintfn(out, "   %s (in %s:%d)", trace.function, trace.file, trace.line);
+						continue;
+					}
+					if (trace.is_unknown())
+					{
+						io::fprintfn(out, "   ??? (in unknown)");
+						continue;
+					}
 					io::fprintfn(out, "   %s (source unavailable)", trace.function);
 				}
-        	}
-        }
+			}
+		}
 	};
 
 }

lib/std/core/array.c3

@@ -1,12 +1,12 @@
 module std::core::array;
 import std::core::array::slice;
 
-/**
- * @param [in] array
- * @param [in] element
- * @return "the first index of the element"
- * @return! SearchResult.MISSING
- **/
+<*
+ @param [in] array
+ @param [in] element
+ @return "the first index of the element"
+ @return! SearchResult.MISSING
+*>
 macro index_of(array, element)
 {
 	foreach (i, &e : array)
@@ -16,10 +16,10 @@ macro index_of(array, element)
 	return SearchResult.MISSING?;
 }
 
-/**
- * @require @typekind(array) == VECTOR || @typekind(array) == ARRAY
- * @require @typekind(array[0]) == VECTOR || @typekind(array[0]) == ARRAY
- **/
+<*
+ @require @typekind(array) == VECTOR || @typekind(array) == ARRAY
+ @require @typekind(array[0]) == VECTOR || @typekind(array[0]) == ARRAY
+*>
 macro slice2d(array, x = 0, xlen = 0, y = 0, ylen = 0)
 {
 	if (xlen < 1) xlen = $typeof(array[0]).len + xlen;
@@ -29,12 +29,12 @@ macro slice2d(array, x = 0, xlen = 0, y = 0, ylen = 0)
 }
 
 
-/**
- * @param [in] array
- * @param [in] element
- * @return "the last index of the element"
- * @return! SearchResult.MISSING
- **/
+<*
+ @param [in] array
+ @param [in] element
+ @return "the last index of the element"
+ @return! SearchResult.MISSING
+*>
 macro rindex_of(array, element)
 {
 	foreach_r (i, &e : array)
@@ -44,17 +44,17 @@ macro rindex_of(array, element)
 	return SearchResult.MISSING?;
 }
 
-/**
- * Concatenate two arrays or slices, returning a slice containing the concatenation of them.
- *
- * @param [in] arr1
- * @param [in] arr2
- * @param [&inout] allocator "The allocator to use, default is the heap allocator"
- * @require @typekind(arr1) == SLICE || @typekind(arr1) == ARRAY
- * @require @typekind(arr2) == SLICE || @typekind(arr2) == ARRAY
- * @require @typeis(arr1[0], $typeof(arr2[0])) "Arrays must have the same type"
- * @ensure result.len == arr1.len + arr2.len
- **/
+<*
+ Concatenate two arrays or slices, returning a slice containing the concatenation of them.
+
+ @param [in] arr1
+ @param [in] arr2
+ @param [&inout] allocator "The allocator to use, default is the heap allocator"
+ @require @typekind(arr1) == SLICE || @typekind(arr1) == ARRAY
+ @require @typekind(arr2) == SLICE || @typekind(arr2) == ARRAY
+ @require @typeis(arr1[0], $typeof(arr2[0])) "Arrays must have the same type"
+ @ensure result.len == arr1.len + arr2.len
+*>
 macro concat(arr1, arr2, Allocator allocator) @nodiscard
 {
 	var $Type = $typeof(arr1[0]);
@@ -69,33 +69,33 @@ macro concat(arr1, arr2, Allocator allocator) @nodiscard
 	}
 	return result;
 }
-/**
- * Concatenate two arrays or slices, returning a slice containing the concatenation of them.
- *
- * @param [in] arr1
- * @param [in] arr2
- * @param [&inout] allocator "The allocator to use, default is the heap allocator"
- * @require @typekind(arr1) == SLICE || @typekind(arr1) == ARRAY
- * @require @typekind(arr2) == SLICE || @typekind(arr2) == ARRAY
- * @require @typeis(arr1[0], $typeof(arr2[0])) "Arrays must have the same type"
- * @ensure result.len == arr1.len + arr2.len
- **/
+<*
+ Concatenate two arrays or slices, returning a slice containing the concatenation of them.
+
+ @param [in] arr1
+ @param [in] arr2
+ @param [&inout] allocator "The allocator to use, default is the heap allocator"
+ @require @typekind(arr1) == SLICE || @typekind(arr1) == ARRAY
+ @require @typekind(arr2) == SLICE || @typekind(arr2) == ARRAY
+ @require @typeis(arr1[0], $typeof(arr2[0])) "Arrays must have the same type"
+ @ensure result.len == arr1.len + arr2.len
+*>
 macro concat_new(arr1, arr2, Allocator allocator = allocator::heap()) @nodiscard
 {
 	return concat(arr1, arr2, allocator);
 }
 
-/**
- * Concatenate two arrays or slices, returning a slice containing the concatenation of them,
- * allocated using the temp allocator.
- *
- * @param [in] arr1
- * @param [in] arr2
- * @require @typekind(arr1) == SLICE || @typekind(arr1) == ARRAY
- * @require @typekind(arr2) == SLICE || @typekind(arr2) == ARRAY
- * @require @typeis(arr1[0], $typeof(arr2[0])) "Arrays must have the same type"
- * @ensure result.len == arr1.len + arr2.len
- **/
+<*
+ Concatenate two arrays or slices, returning a slice containing the concatenation of them,
+ allocated using the temp allocator.
+
+ @param [in] arr1
+ @param [in] arr2
+ @require @typekind(arr1) == SLICE || @typekind(arr1) == ARRAY
+ @require @typekind(arr2) == SLICE || @typekind(arr2) == ARRAY
+ @require @typeis(arr1[0], $typeof(arr2[0])) "Arrays must have the same type"
+ @ensure result.len == arr1.len + arr2.len
+*>
 macro tconcat(arr1, arr2) @nodiscard => concat(arr1, arr2, allocator::temp());
 
 module std::core::array::slice(<Type>);
@@ -142,18 +142,18 @@ macro void Slice2d.@each_ref(&self; @body(usz[<2>], Type*))
 	}
 }
 
-/**
- * @require idy >= 0 && idy < self.ylen
- **/
+<*
+ @require idy >= 0 && idy < self.ylen
+*>
 macro Type[] Slice2d.get(self, usz idy) @operator([])
 {
 	return (self.ptr + self.inner_len * (idy + self.ystart))[self.xstart:self.xlen];
 }
 
-/**
- * @require y >= 0 && y < self.ylen
- * @require x >= 0 && x < self.xlen
- **/
+<*
+ @require y >= 0 && y < self.ylen
+ @require x >= 0 && x < self.xlen
+*>
 fn Slice2d Slice2d.slice(&self, isz x = 0, isz xlen = 0, isz y = 0, isz ylen = 0)
 {
 	if (xlen < 1) xlen = self.xlen + xlen;

lib/std/core/bitorder.c3

@@ -87,10 +87,10 @@ bitstruct UInt128LE : uint128 @littleendian
 	uint128 val : 0..127;
 }
 
-/**
- * @require is_array_or_slice_of_char(bytes) "argument must be an array, a pointer to an array or a slice of char"
- * @require is_bitorder($Type) "type must be a bitorder integer"
- **/
+<*
+ @require is_array_or_slice_of_char(bytes) "argument must be an array, a pointer to an array or a slice of char"
+ @require is_bitorder($Type) "type must be a bitorder integer"
+*>
 macro read(bytes, $Type)
 {
 	char[] s;
@@ -103,10 +103,10 @@ macro read(bytes, $Type)
 	return bitcast(*(char[$Type.sizeof]*)s.ptr, $Type).val;
 }
 
-/**
- * @require is_arrayptr_or_slice_of_char(bytes) "argument must be a pointer to an array or a slice of char"
- * @require is_bitorder($Type) "type must be a bitorder integer"
- **/
+<*
+ @require is_arrayptr_or_slice_of_char(bytes) "argument must be a pointer to an array or a slice of char"
+ @require is_bitorder($Type) "type must be a bitorder integer"
+*>
 macro write(x, bytes, $Type)
 {
 	char[] s;

lib/std/core/builtin.c3

@@ -4,29 +4,29 @@
 module std::core::builtin;
 import libc, std::hash, std::io, std::os::backtrace;
 
-/**
- * Use `IteratorResult` when reading the end of an iterator, or accessing a result out of bounds.
- **/
+<*
+ Use `IteratorResult` when reading the end of an iterator, or accessing a result out of bounds.
+*>
 fault IteratorResult { NO_MORE_ELEMENT }
 
-/**
- * Use `SearchResult` when trying to return a value from some collection but the element is missing.
- **/
+<*
+ Use `SearchResult` when trying to return a value from some collection but the element is missing.
+*>
 fault SearchResult { MISSING }
 
-/**
- * Use `CastResult` when an attempt at conversion fails.
- **/
+<*
+ Use `CastResult` when an attempt at conversion fails.
+*>
 fault CastResult { TYPE_MISMATCH }
 
 def VoidFn = fn void();
 
-/**
- * Stores a variable on the stack, then restores it at the end of the
- * macro scope.
- *
- * @param variable `the variable to store and restore`
- **/
+<*
+ Stores a variable on the stack, then restores it at the end of the
+ macro scope.
+
+ @param variable `the variable to store and restore`
+*>
 macro void @scope(&variable; @body) @builtin
 {
 	var temp = *variable;
@@ -34,10 +34,10 @@ macro void @scope(&variable; @body) @builtin
 	@body();
 }
 
-/**
- * Swap two variables
- * @require $assignable(*b, $typeof(*a)) && $assignable(*a, $typeof(*b))
- **/
+<*
+ Swap two variables
+ @require $assignable(*b, $typeof(*a)) && $assignable(*a, $typeof(*b))
+*>
 macro void @swap(&a, &b) @builtin
 {
 	var temp = *a;
@@ -45,15 +45,15 @@ macro void @swap(&a, &b) @builtin
 	*b = temp;
 }
 
-/**
- * Convert an `any` type to a type, returning an failure if there is a type mismatch.
- *
- * @param v `the any to convert to the given type.`
- * @param $Type `the type to convert to`
- * @return `The any.ptr converted to its type.`
- * @ensure @typeis(return, $Type*)
- * @return! CastResult.TYPE_MISMATCH
- **/
+<*
+ Convert an `any` type to a type, returning an failure if there is a type mismatch.
+
+ @param v `the any to convert to the given type.`
+ @param $Type `the type to convert to`
+ @return `The any.ptr converted to its type.`
+ @ensure @typeis(return, $Type*)
+ @return! CastResult.TYPE_MISMATCH
+*>
 macro anycast(any v, $Type) @builtin
 {
 	if (v.type != $Type.typeid) return CastResult.TYPE_MISMATCH?;
@@ -71,23 +71,23 @@ fn bool print_backtrace(String message, int backtraces_to_ignore) @if(env::NATIV
 		if (catch backtrace) return false;
 		if (backtrace.len() <= backtraces_to_ignore) return false;
 		io::eprint("\nERROR: '");
-        io::eprint(message);
-        io::eprintn("'");
+		io::eprint(message);
+		io::eprintn("'");
 		foreach (i, &trace : backtrace)
-        {
-            if (i < backtraces_to_ignore) continue;
-            String inline_suffix = trace.is_inline ? " [inline]" : "";
-            if (trace.is_unknown())
-            {
+		{
+			if (i < backtraces_to_ignore) continue;
+			String inline_suffix = trace.is_inline ? " [inline]" : "";
+			if (trace.is_unknown())
+			{
 				io::eprintfn("  in ???%s", inline_suffix);
 				continue;
 			}
 			if (trace.has_file())
-            {
-                io::eprintfn("  in %s (%s:%d) [%s]%s", trace.function, trace.file, trace.line, trace.object_file, inline_suffix);
-                continue;
-            }
-            io::eprintfn("  in %s (source unavailable) [%s]%s", trace.function, trace.object_file, inline_suffix);
+			{
+				io::eprintfn("  in %s (%s:%d) [%s]%s", trace.function, trace.file, trace.line, trace.object_file, inline_suffix);
+				continue;
+			}
+			io::eprintfn("  in %s (source unavailable) [%s]%s", trace.function, trace.object_file, inline_suffix);
 		}
 		return true;
 	};
@@ -153,11 +153,11 @@ fn void panicf(String fmt, String file, String function, uint line, args...)
 	};
 }
 
-/**
- * Marks the path as unreachable. This will panic in safe mode, and in fast will simply be assumed
- * never happens.
- * @param [in] string "The panic message or format string"
- **/
+<*
+ Marks the path as unreachable. This will panic in safe mode, and in fast will simply be assumed
+ never happens.
+ @param [in] string "The panic message or format string"
+*>
 macro void unreachable(String string = "Unreachable statement reached.", ...) @builtin @noreturn
 {
 	$if env::COMPILER_SAFE_MODE:
@@ -166,19 +166,19 @@ macro void unreachable(String string = "Unreachable statement reached.", ...) @b
 	$$unreachable();
 }
 
-/**
- * Marks the path as unsupported, this is similar to unreachable.
- * @param [in] string "The error message"
- **/
+<*
+ Marks the path as unsupported, this is similar to unreachable.
+ @param [in] string "The error message"
+*>
 macro void unsupported(String string = "Unsupported function invoked") @builtin @noreturn
 {
 	panicf(string, $$FILE, $$FUNC, $$LINE, $vasplat);
 	$$unreachable();
 }
 
-/**
- * Unconditionally break into an attached debugger when reached.
- **/
+<*
+ Unconditionally break into an attached debugger when reached.
+*>
 macro void breakpoint() @builtin
 {
 	$$breakpoint();
@@ -199,13 +199,13 @@ macro any.as_inner(&self)
 	return $$any_make(self.ptr, self.type.inner);
 }
 
-/**
- * @param expr "the expression to cast"
- * @param $Type "the type to cast to"
- *
- * @require $sizeof(expr) == $Type.sizeof  "Cannot bitcast between types of different size."
- * @ensure @typeis(return, $Type)
- **/
+<*
+ @param expr "the expression to cast"
+ @param $Type "the type to cast to"
+
+ @require $sizeof(expr) == $Type.sizeof  "Cannot bitcast between types of different size."
+ @ensure @typeis(return, $Type)
+*>
 macro bitcast(expr, $Type) @builtin
 {
 	$if $Type.alignof <= $alignof(expr):
@@ -217,13 +217,13 @@ macro bitcast(expr, $Type) @builtin
 	$endif
 }
 
-/**
- * @param $Type `The type of the enum`
- * @param [in] enum_name `The name of the enum to search for`
- * @require $Type.kindof == ENUM `Only enums may be used`
- * @ensure @typeis(return, $Type)
- * @return! SearchResult.MISSING
- **/
+<*
+ @param $Type `The type of the enum`
+ @param [in] enum_name `The name of the enum to search for`
+ @require $Type.kindof == ENUM `Only enums may be used`
+ @ensure @typeis(return, $Type)
+ @return! SearchResult.MISSING
+*>
 macro enum_by_name($Type, String enum_name) @builtin
 {
 	typeid x = $Type.typeid;
@@ -234,65 +234,65 @@ macro enum_by_name($Type, String enum_name) @builtin
 	return SearchResult.MISSING?;
 }
 
-/**
- * Mark an expression as likely to be true
- *
- * @param #value "expression to be marked likely"
- * @param $probability "in the range 0 - 1"
- * @require $probability >= 0 && $probability <= 1.0
- **/
+<*
+ Mark an expression as likely to be true
+
+ @param #value "expression to be marked likely"
+ @param $probability "in the range 0 - 1"
+ @require $probability >= 0 && $probability <= 1.0
+*>
 macro bool @likely(bool #value, $probability = 1.0) @builtin
 {
-    $switch
-    $case env::BUILTIN_EXPECT_IS_DISABLED:
+	$switch
+	$case env::BUILTIN_EXPECT_IS_DISABLED:
 	return #value;
-    $case $probability == 1.0:
+	$case $probability == 1.0:
 	return $$expect(#value, true);
-    $default:
+	$default:
 	return $$expect_with_probability(#value, true, $probability);
-    $endswitch
+	$endswitch
 }
 
-/**
- * Mark an expression as unlikely to be true
- *
- * @param #value "expression to be marked unlikely"
- * @param $probability "in the range 0 - 1"
- * @require $probability >= 0 && $probability <= 1.0
- **/
+<*
+ Mark an expression as unlikely to be true
+
+ @param #value "expression to be marked unlikely"
+ @param $probability "in the range 0 - 1"
+ @require $probability >= 0 && $probability <= 1.0
+*>
 macro bool @unlikely(bool #value, $probability = 1.0) @builtin
 {
-    $switch
-    $case env::BUILTIN_EXPECT_IS_DISABLED:
+	$switch
+	$case env::BUILTIN_EXPECT_IS_DISABLED:
 	return #value;
-    $case $probability == 1.0:
+	$case $probability == 1.0:
 	return $$expect(#value, false);
-    $default:
+	$default:
 	return $$expect_with_probability(#value, false, $probability);
-    $endswitch
+	$endswitch
 }
 
-/**
- * @require values::@is_int(#value) || values::@is_bool(#value)
- * @require $assignable(expected, $typeof(#value))
- * @require $probability >= 0 && $probability <= 1.0
- **/
+<*
+ @require values::@is_int(#value) || values::@is_bool(#value)
+ @require $assignable(expected, $typeof(#value))
+ @require $probability >= 0 && $probability <= 1.0
+*>
 macro @expect(#value, expected, $probability = 1.0) @builtin
 {
-    $switch
-    $case env::BUILTIN_EXPECT_IS_DISABLED:
+	$switch
+	$case env::BUILTIN_EXPECT_IS_DISABLED:
 	return #value == expected;
-    $case $probability == 1.0:
+	$case $probability == 1.0:
 	return $$expect(#value, ($typeof(#value))expected);
-    $default:
+	$default:
 	return $$expect_with_probability(#value, expected, $probability);
-    $endswitch
+	$endswitch
 }
 
-/**
- * Locality for prefetch, levels 0 - 3, corresponding
- * to "extremely local" to "no locality"
- **/
+<*
+ Locality for prefetch, levels 0 - 3, corresponding
+ to "extremely local" to "no locality"
+*>
 enum PrefetchLocality
 {
 	NO_LOCALITY,
@@ -301,13 +301,13 @@ enum PrefetchLocality
 	VERY_NEAR,
 }
 
-/**
- * Prefetch a pointer.
+<*
+ Prefetch a pointer.
 
- * @param [in] ptr `Pointer to prefetch`
- * @param $locality `Locality ranging from none to extremely local`
- * @param $write `Prefetch for write, otherwise prefetch for read.`
- **/
+ @param [in] ptr `Pointer to prefetch`
+ @param $locality `Locality ranging from none to extremely local`
+ @param $write `Prefetch for write, otherwise prefetch for read.`
+*>
 macro @prefetch(void* ptr, PrefetchLocality $locality = VERY_NEAR, bool $write = false) @builtin
 {
 	$if !env::BUILTIN_PREFETCH_IS_DISABLED:
@@ -324,13 +324,24 @@ macro swizzle2(v, v2, ...) @builtin
 {
 	return $$swizzle2(v, v2, $vasplat);
 }
+<*
+ Return the excuse in the Optional if it is Empty, otherwise
+ return a null fault.
 
+ @require @typekind(#expr) == OPTIONAL : `@catch expects an Optional value`
+*>
 macro anyfault @catch(#expr) @builtin
 {
 	if (catch f = #expr) return f;
 	return anyfault {};
 }
 
+<*
+ Check if an Optional expression holds a value or is empty, returning true
+ if it has a value.
+
+ @require @typekind(#expr) == OPTIONAL : `@ok expects an Optional value`
+*>
 macro bool @ok(#expr) @builtin
 {
 	if (catch #expr) return false;
@@ -369,9 +380,9 @@ macro @is_empty_macro_slot(#arg) @builtin => @typeis(#arg, EmptySlot);
 macro @is_valid_macro_slot(#arg) @builtin => !@typeis(#arg, EmptySlot);
 
 const MAX_FRAMEADDRESS = 128;
-/**
- * @require n >= 0
- **/
+<*
+ @require n >= 0
+*>
 macro void* get_frameaddress(int n)
 {
 	if (n > MAX_FRAMEADDRESS) return null;
@@ -510,9 +521,9 @@ macro void* get_frameaddress(int n)
 	}
 }
 
-/**
- * @require n >= 0
- **/
+<*
+ @require n >= 0
+*>
 macro void* get_returnaddress(int n)
 {
 	if (n > MAX_FRAMEADDRESS) return null;

lib/std/core/builtin_comparison.c3

@@ -3,9 +3,9 @@
 // a copy of which can be found in the LICENSE_STDLIB file.
 module std::core::builtin;
 
-/**
- * @require types::@comparable_value(a) && types::@comparable_value(b)
- **/
+<*
+ @require types::@comparable_value(a) && types::@comparable_value(b)
+*>
 macro less(a, b) @builtin
 {
 	$switch
@@ -18,9 +18,9 @@ macro less(a, b) @builtin
 	$endswitch
 }
 
-/**
- * @require types::@comparable_value(a) && types::@comparable_value(b)
- **/
+<*
+ @require types::@comparable_value(a) && types::@comparable_value(b)
+*>
 macro less_eq(a, b) @builtin
 {
 	$switch
@@ -33,9 +33,9 @@ macro less_eq(a, b) @builtin
 	$endswitch
 }
 
-/**
- * @require types::@comparable_value(a) && types::@comparable_value(b)
- **/
+<*
+ @require types::@comparable_value(a) && types::@comparable_value(b)
+*>
 macro greater(a, b) @builtin
 {
 	$switch
@@ -48,9 +48,9 @@ macro greater(a, b) @builtin
 	$endswitch
 }
 
-/**
- * @require types::@comparable_value(a) && types::@comparable_value(b)
- **/
+<*
+ @require types::@comparable_value(a) && types::@comparable_value(b)
+*>
 macro int compare_to(a, b) @builtin
 {
 	$switch
@@ -62,9 +62,9 @@ macro int compare_to(a, b) @builtin
 		return (int)(a > b) - (int)(a < b);
 	$endswitch
 }
-/**
- * @require types::@comparable_value(a) && types::@comparable_value(b)
- **/
+<*
+ @require types::@comparable_value(a) && types::@comparable_value(b)
+*>
 macro greater_eq(a, b) @builtin
 {
 	$switch
@@ -77,9 +77,9 @@ macro greater_eq(a, b) @builtin
 	$endswitch
 }
 
-/**
- * @require types::@equatable_value(a) && types::@equatable_value(b) `values must be equatable`
- **/
+<*
+ @require types::@equatable_value(a) && types::@equatable_value(b) `values must be equatable`
+*>
 macro bool equals(a, b) @builtin
 {
 	$switch

lib/std/core/cinterop.c3

@@ -29,6 +29,12 @@ def CUChar = char;
 
 def CChar = $typefrom($$C_CHAR_IS_SIGNED ? ichar.typeid : char.typeid);
 
+enum CBool : CInt
+{
+	FALSE,
+	TRUE
+}
+
 // Helper macros
 macro typeid signed_int_from_bitsize(usz $bitsize) @private
 {

lib/std/core/conv.c3

@@ -9,10 +9,10 @@ const uint UTF16_SURROGATE_BITS @private = 10;
 const uint UTF16_SURROGATE_LOW_VALUE @private = 0xDC00;
 const uint UTF16_SURROGATE_HIGH_VALUE @private = 0xD800;
 
-/**
- * @param c `The utf32 codepoint to convert`
- * @param [out] output `the resulting buffer`
- **/
+<*
+ @param c `The utf32 codepoint to convert`
+ @param [out] output `the resulting buffer`
+*>
 fn usz! char32_to_utf8(Char32 c, char[] output)
 {
 	if (!output.len) return UnicodeResult.CONVERSION_FAILED?;
@@ -45,12 +45,12 @@ fn usz! char32_to_utf8(Char32 c, char[] output)
 	}
 }
 
-/**
- * Convert a code pointer into 1-2 UTF16 characters.
- *
- * @param c `The character to convert.`
- * @param [inout] output `the resulting UTF16 buffer to write to.`
- **/
+<*
+ Convert a code pointer into 1-2 UTF16 characters.
+
+ @param c `The character to convert.`
+ @param [inout] output `the resulting UTF16 buffer to write to.`
+*>
 fn void char32_to_utf16_unsafe(Char32 c, Char16** output)
 {
 	if (c < UTF16_SURROGATE_OFFSET)
@@ -66,13 +66,13 @@ fn void char32_to_utf16_unsafe(Char32 c, Char16** output)
 	(*output)++[0] = (Char16)low;
 }
 
-/**
- * Convert 1-2 UTF16 data points into UTF8.
- *
- * @param [in] ptr `The UTF16 data to convert.`
- * @param [inout] available `amount of UTF16 data available.`
- * @param [inout] output `the resulting utf8 buffer to write to.`
- **/
+<*
+ Convert 1-2 UTF16 data points into UTF8.
+
+ @param [in] ptr `The UTF16 data to convert.`
+ @param [inout] available `amount of UTF16 data available.`
+ @param [inout] output `the resulting utf8 buffer to write to.`
+*>
 fn void! char16_to_utf8_unsafe(Char16 *ptr, usz *available, char** output)
 {
 	Char16 high = *ptr;
@@ -100,10 +100,10 @@ fn void! char16_to_utf8_unsafe(Char16 *ptr, usz *available, char** output)
 	char32_to_utf8_unsafe(uc, output);
 	*available = 2;
 }
-/**
- * @param c `The utf32 codepoint to convert`
- * @param [inout] output `the resulting buffer`
- **/
+<*
+ @param c `The utf32 codepoint to convert`
+ @param [inout] output `the resulting buffer`
+*>
 fn usz char32_to_utf8_unsafe(Char32 c, char** output)
 {
 	switch
@@ -129,11 +129,11 @@ fn usz char32_to_utf8_unsafe(Char32 c, char** output)
 	}
 }
 
-/**
- * @param [in] ptr `pointer to the first character to parse`
- * @param [inout] size `Set to max characters to read, set to characters read`
- * @return `the parsed 32 bit codepoint`
- **/
+<*
+ @param [in] ptr `pointer to the first character to parse`
+ @param [inout] size `Set to max characters to read, set to characters read`
+ @return `the parsed 32 bit codepoint`
+*>
 fn Char32! utf8_to_char32(char* ptr, usz* size)
 {
 	usz max_size = *size;
@@ -184,10 +184,10 @@ fn Char32! utf8_to_char32(char* ptr, usz* size)
 	return uc + c & 0x3F;
 }
 
-/**
- * @param utf8 `An UTF-8 encoded slice of bytes`
- * @return `the number of encoded code points`
- **/
+<*
+ @param utf8 `An UTF-8 encoded slice of bytes`
+ @return `the number of encoded code points`
+*>
 fn usz utf8_codepoints(String utf8)
 {
 	usz len = 0;
@@ -198,11 +198,11 @@ fn usz utf8_codepoints(String utf8)
 	return len;
 }
 
-/**
- * Calculate the UTF8 length required to encode an UTF32 array.
- * @param [in] utf32 `the utf32 data to calculate from`
- * @return `the length of the resulting UTF8 array`
- **/
+<*
+ Calculate the UTF8 length required to encode an UTF32 array.
+ @param [in] utf32 `the utf32 data to calculate from`
+ @return `the length of the resulting UTF8 array`
+*>
 fn usz utf8len_for_utf32(Char32[] utf32)
 {
 	usz len = 0;
@@ -223,11 +223,11 @@ fn usz utf8len_for_utf32(Char32[] utf32)
 	return len;
 }
 
-/**
- * Calculate the UTF8 length required to encode an UTF16 array.
- * @param [in] utf16 `the utf16 data to calculate from`
- * @return `the length of the resulting UTF8 array`
- **/
+<*
+ Calculate the UTF8 length required to encode an UTF16 array.
+ @param [in] utf16 `the utf16 data to calculate from`
+ @return `the length of the resulting UTF8 array`
+*>
 fn usz utf8len_for_utf16(Char16[] utf16)
 {
 	usz len = 0;
@@ -255,11 +255,11 @@ fn usz utf8len_for_utf16(Char16[] utf16)
 	return len;
 }
 
-/**
- * Calculate the UTF16 length required to encode a UTF8 array.
- * @param utf8 `the utf8 data to calculate from`
- * @return `the length of the resulting UTF16 array`
- **/
+<*
+ Calculate the UTF16 length required to encode a UTF8 array.
+ @param utf8 `the utf8 data to calculate from`
+ @return `the length of the resulting UTF16 array`
+*>
 fn usz utf16len_for_utf8(String utf8)
 {
 	usz len = utf8.len;
@@ -279,10 +279,10 @@ fn usz utf16len_for_utf8(String utf8)
 	return len16;
 }
 
-/**
- * @param [in] utf32 `the UTF32 array to check the length for`
- * @return `the required length of an UTF16 array to hold the UTF32 data.`
- **/
+<*
+ @param [in] utf32 `the UTF32 array to check the length for`
+ @return `the required length of an UTF16 array to hold the UTF32 data.`
+*>
 fn usz utf16len_for_utf32(Char32[] utf32)
 {
 	usz len = utf32.len;
@@ -293,13 +293,13 @@ fn usz utf16len_for_utf32(Char32[] utf32)
 	return len;
 }
 
-/**
- * Convert an UTF32 array to an UTF8 array.
- *
- * @param [in] utf32
- * @param [out] utf8_buffer
- * @return `the number of bytes written.`
- **/
+<*
+ Convert an UTF32 array to an UTF8 array.
+
+ @param [in] utf32
+ @param [out] utf8_buffer
+ @return `the number of bytes written.`
+*>
 fn usz! utf32to8(Char32[] utf32, char[] utf8_buffer)
 {
 	char[] buffer = utf8_buffer;
@@ -313,13 +313,13 @@ fn usz! utf32to8(Char32[] utf32, char[] utf8_buffer)
 	return utf8_buffer.len - buffer.len;
 }
 
-/**
- * Convert an UTF8 array to an UTF32 array.
- *
- * @param [in] utf8
- * @param [out] utf32_buffer
- * @return `the number of Char32s written.`
- **/
+<*
+ Convert an UTF8 array to an UTF32 array.
+
+ @param [in] utf8
+ @param [out] utf32_buffer
+ @return `the number of Char32s written.`
+*>
 fn usz! utf8to32(String utf8, Char32[] utf32_buffer)
 {
 	usz len = utf8.len;
@@ -339,14 +339,14 @@ fn usz! utf8to32(String utf8, Char32[] utf32_buffer)
 	return len32;
 }
 
-/**
- * Copy an array of UTF16 data into an UTF8 buffer without bounds
- * checking. This will assume the buffer is sufficiently large to hold
- * the converted data.
- *
- * @param [in] utf16 `The UTF16 array containing the data to convert.`
- * @param [out] utf8_buffer `the (sufficiently large) buffer to hold the UTF16 data.`
- **/
+<*
+ Copy an array of UTF16 data into an UTF8 buffer without bounds
+ checking. This will assume the buffer is sufficiently large to hold
+ the converted data.
+
+ @param [in] utf16 `The UTF16 array containing the data to convert.`
+ @param [out] utf8_buffer `the (sufficiently large) buffer to hold the UTF16 data.`
+*>
 fn void! utf16to8_unsafe(Char16[] utf16, char* utf8_buffer)
 {
 	usz len16 = utf16.len;
@@ -358,14 +358,14 @@ fn void! utf16to8_unsafe(Char16[] utf16, char* utf8_buffer)
 	}
 }
 
-/**
- * Copy an array of UTF8 data into an UTF32 buffer without bounds
- * checking. This will assume the buffer is sufficiently large to hold
- * the converted data.
- *
- * @param [in] utf8 `The UTF8 buffer containing the data to convert.`
- * @param [out] utf32_buffer `the (sufficiently large) buffer to hold the UTF8 data.`
- **/
+<*
+ Copy an array of UTF8 data into an UTF32 buffer without bounds
+ checking. This will assume the buffer is sufficiently large to hold
+ the converted data.
+
+ @param [in] utf8 `The UTF8 buffer containing the data to convert.`
+ @param [out] utf32_buffer `the (sufficiently large) buffer to hold the UTF8 data.`
+*>
 fn void! utf8to32_unsafe(String utf8, Char32* utf32_buffer)
 {
 	usz len = utf8.len;
@@ -378,14 +378,14 @@ fn void! utf8to32_unsafe(String utf8, Char32* utf32_buffer)
 	}
 }
 
-/**
- * Copy an array of UTF8 data into an UTF16 buffer without bounds
- * checking. This will assume the buffer is sufficiently large to hold
- * the converted data.
- *
- * @param [in] utf8 `The UTF8 buffer containing the data to convert.`
- * @param [out] utf16_buffer `the (sufficiently large) buffer to hold the UTF8 data.`
- **/
+<*
+ Copy an array of UTF8 data into an UTF16 buffer without bounds
+ checking. This will assume the buffer is sufficiently large to hold
+ the converted data.
+
+ @param [in] utf8 `The UTF8 buffer containing the data to convert.`
+ @param [out] utf16_buffer `the (sufficiently large) buffer to hold the UTF8 data.`
+*>
 fn void! utf8to16_unsafe(String utf8, Char16* utf16_buffer)
 {
 	usz len = utf8.len;
@@ -398,14 +398,14 @@ fn void! utf8to16_unsafe(String utf8, Char16* utf16_buffer)
 	}
 }
 
-/**
- * Copy an array of UTF32 code points into an UTF8 buffer without bounds
- * checking. This will assume the buffer is sufficiently large to hold
- * the converted data.
- *
- * @param [in] utf32 `The UTF32 buffer containing the data to convert.`
- * @param [out] utf8_buffer `the (sufficiently large) buffer to hold the UTF8 data.`
- **/
+<*
+ Copy an array of UTF32 code points into an UTF8 buffer without bounds
+ checking. This will assume the buffer is sufficiently large to hold
+ the converted data.
+
+ @param [in] utf32 `The UTF32 buffer containing the data to convert.`
+ @param [out] utf8_buffer `the (sufficiently large) buffer to hold the UTF8 data.`
+*>
 fn void utf32to8_unsafe(Char32[] utf32, char* utf8_buffer)
 {
 	char* start = utf8_buffer;

lib/std/core/dstring.c3

@@ -5,9 +5,9 @@ distinct DString (OutStream) = void*;
 
 const usz MIN_CAPACITY @private = 16;
 
-/**
- * @require !self.data() "String already initialized"
- **/
+<*
+ @require !self.data() "String already initialized"
+*>
 fn DString DString.new_init(&self, usz capacity = MIN_CAPACITY, Allocator allocator = allocator::heap())
 {
 	if (capacity < MIN_CAPACITY) capacity = MIN_CAPACITY;
@@ -18,9 +18,9 @@ fn DString DString.new_init(&self, usz capacity = MIN_CAPACITY, Allocator alloca
 	return *self = (DString)data;
 }
 
-/**
- * @require !self.data() "String already initialized"
- **/
+<*
+ @require !self.data() "String already initialized"
+*>
 fn DString DString.temp_init(&self, usz capacity = MIN_CAPACITY)
 {
 	self.new_init(capacity, allocator::temp()) @inline;
@@ -77,24 +77,24 @@ fn void DString.replace(&self, String needle, String replacement)
 		foreach (i, c : str)
 		{
 			if (c == needle[match])
-    	    {
-    	        match++;
-    		    if (match == needle_len)
-    		    {
-    			    self.append_chars(replacement);
-    			    match = 0;
-    			    continue;
-    		    }
-    		    continue;
-    		}
-    		if (match > 0)
-    		{
-    		    self.append_chars(str[i - match:match]);
-    		    match = 0;
-    		}
-    		self.append_char(c);
-    	}
-    	if (match > 0) self.append_chars(str[^match:match]);
+			{
+				match++;
+				if (match == needle_len)
+				{
+					self.append_chars(replacement);
+					match = 0;
+					continue;
+				}
+				continue;
+			}
+			if (match > 0)
+			{
+				self.append_chars(str[i - match:match]);
+				match = 0;
+			}
+			self.append_char(c);
+		}
+		if (match > 0) self.append_chars(str[^match:match]);
 	};
 }
 
@@ -132,15 +132,15 @@ fn usz DString.capacity(self)
 	return self.data().capacity;
 }
 
-fn usz DString.len(&self) @dynamic
+fn usz DString.len(&self) @dynamic @operator(len)
 {
 	if (!*self) return 0;
 	return self.data().len;
 }
 
-/**
- * @require new_size <= self.len()
- */
+<*
+ @require new_size <= self.len()
+*>
 fn void DString.chop(self, usz new_size)
 {
 	if (!self) return;
@@ -154,6 +154,24 @@ fn String DString.str_view(self)
 	return (String)data.chars[:data.len];
 }
 
+<*
+ @require index < self.len()
+ @require self.data() "Empty string"
+*>
+fn char DString.char_at(self, usz index) @operator([])
+{
+	return self.data().chars[index];
+}
+
+<*
+ @require index < self.len()
+ @require self.data() "Empty string"
+*>
+fn char* DString.char_ref(&self, usz index) @operator(&[])
+{
+	return &self.data().chars[index];
+}
+
 fn usz DString.append_utf32(&self, Char32[] chars)
 {
 	self.reserve(chars.len);
@@ -165,10 +183,10 @@ fn usz DString.append_utf32(&self, Char32[] chars)
 	return self.data().len - end;
 }
 
-/**
- * @require index < self.len()
- **/
-fn void DString.set(self, usz index, char c)
+<*
+ @require index < self.len()
+*>
+fn void DString.set(self, usz index, char c) @operator([]=)
 {
 	self.data().chars[index] = c;
 }
@@ -184,9 +202,9 @@ fn void DString.append_repeat(&self, char c, usz times)
 	}
 }
 
-/**
- * @require c <= 0x10ffff
- */
+<*
+ @require c <= 0x10ffff
+*>
 fn usz DString.append_char32(&self, Char32 c)
 {
 	char[4] buffer @noinit;
@@ -333,20 +351,20 @@ fn void DString.append_char(&self, char c)
 	data.chars[data.len++] = c;
 }
 
-/**
- * @require start < self.len()
- * @require end < self.len()
- * @require end >= start "End must be same or equal to the start"
- **/
+<*
+ @require start < self.len()
+ @require end < self.len()
+ @require end >= start "End must be same or equal to the start"
+*>
 fn void DString.delete_range(&self, usz start, usz end)
 {
 	self.delete(start, end - start + 1);
 }
 
-/**
- * @require start < self.len()
- * @require start + len <= self.len()
- **/
+<*
+ @require start < self.len()
+ @require start + len <= self.len()
+*>
 fn void DString.delete(&self, usz start, usz len = 1)
 {
 	if (!len) return;
@@ -390,9 +408,9 @@ macro void DString.append(&self, value)
 	$endswitch
 }
 
-/**
- * @require index <= self.len()
- **/
+<*
+ @require index <= self.len()
+*>
 fn void DString.insert_chars_at(&self, usz index, String s)
 {
 	if (s.len == 0) return;
@@ -425,9 +443,9 @@ fn void DString.insert_chars_at(&self, usz index, String s)
 	}
 }
 
-/**
- * @require index <= self.len()
- **/
+<*
+ @require index <= self.len()
+*>
 fn void DString.insert_string_at(&self, usz index, DString str)
 {
 	StringData* other = str.data();
@@ -435,9 +453,9 @@ fn void DString.insert_string_at(&self, usz index, DString str)
 	self.insert_at(index, str.str_view());
 }
 
-/**
- * @require index <= self.len()
- **/
+<*
+ @require index <= self.len()
+*>
 fn void DString.insert_char_at(&self, usz index, char c)
 {
 	self.reserve(1);
@@ -449,9 +467,9 @@ fn void DString.insert_char_at(&self, usz index, char c)
 	data.len++;
 }
 
-/**
- * @require index <= self.len()
- **/
+<*
+ @require index <= self.len()
+*>
 fn usz DString.insert_char32_at(&self, usz index, Char32 c)
 {
 	char[4] buffer @noinit;
@@ -469,9 +487,9 @@ fn usz DString.insert_char32_at(&self, usz index, Char32 c)
 	return n;
 }
 
-/**
- * @require index <= self.len()
- **/
+<*
+ @require index <= self.len()
+*>
 fn usz DString.insert_utf32_at(&self, usz index, Char32[] chars)
 {
 	usz n = conv::utf8len_for_utf32(chars);

lib/std/core/mem.c3

@@ -13,175 +13,175 @@ macro bool @constant_is_power_of_2($x) @const @private
 	return $x != 0 && ($x & ($x - 1)) == 0;
 }
 
-/**
- * Load a vector from memory according to a mask assuming default alignment.
- *
- * @param ptr "The pointer address to load from."
- * @param mask "The mask for the load"
- * @param passthru "The value to use for non masked values"
- * @require $assignable(&&passthru, $typeof(ptr)) : "Pointer and passthru must match"
- * @require @typekind(passthru) == VECTOR : "Expected passthru to be a vector"
- * @require passthru.len == mask.len : "Mask and passthru must have the same length"
- *
- * @return "A vector with the loaded values where the mask is true, passthru where the mask is false"
- **/
+<*
+ Load a vector from memory according to a mask assuming default alignment.
+
+ @param ptr "The pointer address to load from."
+ @param mask "The mask for the load"
+ @param passthru "The value to use for non masked values"
+ @require $assignable(&&passthru, $typeof(ptr)) : "Pointer and passthru must match"
+ @require @typekind(passthru) == VECTOR : "Expected passthru to be a vector"
+ @require passthru.len == mask.len : "Mask and passthru must have the same length"
+
+ @return "A vector with the loaded values where the mask is true, passthru where the mask is false"
+*>
 macro masked_load(ptr, bool[<*>] mask, passthru)
 {
 	return $$masked_load(ptr, mask, passthru, 0);
 }
 
-/**
- * Load a vector from memory according to a mask.
- *
- * @param ptr "The pointer address to load from."
- * @param mask "The mask for the load"
- * @param passthru "The value to use for non masked values"
- * @param $alignment "The alignment to assume for the pointer"
- *
- * @require $assignable(&&passthru, $typeof(ptr)) : "Pointer and passthru must match"
- * @require @typekind(passthru) == VECTOR : "Expected passthru to be a vector"
- * @require passthru.len == mask.len : "Mask and passthru must have the same length"
- * @require @constant_is_power_of_2($alignment) : "The alignment must be a power of two"
- *
- * @return "A vector with the loaded values where the mask is true, passthru where the mask is false"
- **/
+<*
+ Load a vector from memory according to a mask.
+
+ @param ptr "The pointer address to load from."
+ @param mask "The mask for the load"
+ @param passthru "The value to use for non masked values"
+ @param $alignment "The alignment to assume for the pointer"
+
+ @require $assignable(&&passthru, $typeof(ptr)) : "Pointer and passthru must match"
+ @require @typekind(passthru) == VECTOR : "Expected passthru to be a vector"
+ @require passthru.len == mask.len : "Mask and passthru must have the same length"
+ @require @constant_is_power_of_2($alignment) : "The alignment must be a power of two"
+
+ @return "A vector with the loaded values where the mask is true, passthru where the mask is false"
+*>
 macro @masked_load_aligned(ptr, bool[<*>] mask, passthru, usz $alignment)
 {
 	return $$masked_load(ptr, mask, passthru, $alignment);
 }
 
-/**
- * Load values from a pointer vector, assuming default alignment.
- *
- * @param ptrvec "The vector of pointers to load from."
- * @param mask "The mask for the load"
- * @param passthru "The value to use for non masked values"
- *
- * @require @typekind(ptrvec) == VECTOR : "Expected ptrvec to be a vector"
- * @require @typekind(passthru) == VECTOR : "Expected passthru to be a vector"
- * @require $assignable(&&passthru[0], $typeof(ptrvec[0])) : "Pointer and passthru must match"
- * @require passthru.len == mask.len : "Mask and passthru must have the same length"
- * @require mask.len == ptrvec.len : "Mask and ptrvec must have the same length"
- *
- * @return "A vector with the loaded values where the mask is true, passthru where the mask is false"
- **/
+<*
+ Load values from a pointer vector, assuming default alignment.
+
+ @param ptrvec "The vector of pointers to load from."
+ @param mask "The mask for the load"
+ @param passthru "The value to use for non masked values"
+
+ @require @typekind(ptrvec) == VECTOR : "Expected ptrvec to be a vector"
+ @require @typekind(passthru) == VECTOR : "Expected passthru to be a vector"
+ @require $assignable(&&passthru[0], $typeof(ptrvec[0])) : "Pointer and passthru must match"
+ @require passthru.len == mask.len : "Mask and passthru must have the same length"
+ @require mask.len == ptrvec.len : "Mask and ptrvec must have the same length"
+
+ @return "A vector with the loaded values where the mask is true, passthru where the mask is false"
+*>
 macro gather(ptrvec, bool[<*>] mask, passthru)
 {
 	return $$gather(ptrvec, mask, passthru, 0);
 }
 
 
-/**
- * Load values from a pointer vector.
- *
- * @param ptrvec "The vector of pointers to load from."
- * @param mask "The mask for the load"
- * @param passthru "The value to use for non masked values"
- * @param $alignment "The alignment to assume for the pointers"
- *
- * @require @typekind(ptrvec) == VECTOR : "Expected ptrvec to be a vector"
- * @require @typekind(passthru) == VECTOR : "Expected passthru to be a vector"
- * @require $assignable(&&passthru[0], $typeof(ptrvec[0])) : "Pointer and passthru must match"
- * @require passthru.len == mask.len : "Mask and passthru must have the same length"
- * @require mask.len == ptrvec.len : "Mask and ptrvec must have the same length"
- * @require @constant_is_power_of_2($alignment) : "The alignment must be a power of two"
- *
- * @return "A vector with the loaded values where the mask is true, passthru where the mask is false"
- **/
+<*
+ Load values from a pointer vector.
+
+ @param ptrvec "The vector of pointers to load from."
+ @param mask "The mask for the load"
+ @param passthru "The value to use for non masked values"
+ @param $alignment "The alignment to assume for the pointers"
+
+ @require @typekind(ptrvec) == VECTOR : "Expected ptrvec to be a vector"
+ @require @typekind(passthru) == VECTOR : "Expected passthru to be a vector"
+ @require $assignable(&&passthru[0], $typeof(ptrvec[0])) : "Pointer and passthru must match"
+ @require passthru.len == mask.len : "Mask and passthru must have the same length"
+ @require mask.len == ptrvec.len : "Mask and ptrvec must have the same length"
+ @require @constant_is_power_of_2($alignment) : "The alignment must be a power of two"
+
+ @return "A vector with the loaded values where the mask is true, passthru where the mask is false"
+*>
 macro @gather_aligned(ptrvec, bool[<*>] mask, passthru, usz $alignment)
 {
 	return $$gather(ptrvec, mask, passthru, $alignment);
 }
 
 
-/**
- * Store parts of a vector according to the mask, assuming default alignment.
- *
- * @param ptr "The pointer address to store to."
- * @param value "The value to store masked"
- * @param mask "The mask for the store"
- *
- * @require $assignable(&&value, $typeof(ptr)) : "Pointer and value must match"
- * @require @typekind(value) == VECTOR : "Expected value to be a vector"
- * @require value.len == mask.len : "Mask and value must have the same length"
- **/
+<*
+ Store parts of a vector according to the mask, assuming default alignment.
+
+ @param ptr "The pointer address to store to."
+ @param value "The value to store masked"
+ @param mask "The mask for the store"
+
+ @require $assignable(&&value, $typeof(ptr)) : "Pointer and value must match"
+ @require @typekind(value) == VECTOR : "Expected value to be a vector"
+ @require value.len == mask.len : "Mask and value must have the same length"
+*>
 macro masked_store(ptr, value, bool[<*>] mask)
 {
 	return $$masked_store(ptr, value, mask, 0);
 }
 
-/**
- * @param ptr "The pointer address to store to."
- * @param value "The value to store masked"
- * @param mask "The mask for the store"
- * @param $alignment "The alignment of the pointer"
- *
- * @require $assignable(&&value, $typeof(ptr)) : "Pointer and value must match"
- * @require @typekind(value) == VECTOR : "Expected value to be a vector"
- * @require value.len == mask.len : "Mask and value must have the same length"
- * @require @constant_is_power_of_2($alignment) : "The alignment must be a power of two"
- *
- **/
+<*
+ @param ptr "The pointer address to store to."
+ @param value "The value to store masked"
+ @param mask "The mask for the store"
+ @param $alignment "The alignment of the pointer"
+
+ @require $assignable(&&value, $typeof(ptr)) : "Pointer and value must match"
+ @require @typekind(value) == VECTOR : "Expected value to be a vector"
+ @require value.len == mask.len : "Mask and value must have the same length"
+ @require @constant_is_power_of_2($alignment) : "The alignment must be a power of two"
+
+*>
 macro @masked_store_aligned(ptr, value, bool[<*>] mask, usz $alignment)
 {
 	return $$masked_store(ptr, value, mask, $alignment);
 }
 
-/**
- * @param ptrvec "The vector pointer containing the addresses to store to."
- * @param value "The value to store masked"
- * @param mask "The mask for the store"
- * @require @typekind(ptrvec) == VECTOR : "Expected ptrvec to be a vector"
- * @require @typekind(value) == VECTOR : "Expected value to be a vector"
- * @require $assignable(&&value[0], $typeof(ptrvec[0])) : "Pointer and value must match"
- * @require value.len == mask.len : "Mask and value must have the same length"
- * @require mask.len == ptrvec.len : "Mask and ptrvec must have the same length"
- *
- **/
+<*
+ @param ptrvec "The vector pointer containing the addresses to store to."
+ @param value "The value to store masked"
+ @param mask "The mask for the store"
+ @require @typekind(ptrvec) == VECTOR : "Expected ptrvec to be a vector"
+ @require @typekind(value) == VECTOR : "Expected value to be a vector"
+ @require $assignable(&&value[0], $typeof(ptrvec[0])) : "Pointer and value must match"
+ @require value.len == mask.len : "Mask and value must have the same length"
+ @require mask.len == ptrvec.len : "Mask and ptrvec must have the same length"
+
+*>
 macro scatter(ptrvec, value, bool[<*>] mask)
 {
 	return $$scatter(ptrvec, value, mask, 0);
 }
 
-/**
- * @param ptrvec "The vector pointer containing the addresses to store to."
- * @param value "The value to store masked"
- * @param mask "The mask for the store"
- * @param $alignment "The alignment of the load"
- *
- * @require @typekind(ptrvec) == VECTOR : "Expected ptrvec to be a vector"
- * @require @typekind(value) == VECTOR : "Expected value to be a vector"
- * @require $assignable(&&value[0], $typeof(ptrvec[0])) : "Pointer and value must match"
- * @require value.len == mask.len : "Mask and value must have the same length"
- * @require mask.len == ptrvec.len : "Mask and ptrvec must have the same length"
- * @require @constant_is_power_of_2($alignment) : "The alignment must be a power of two"
- **/
+<*
+ @param ptrvec "The vector pointer containing the addresses to store to."
+ @param value "The value to store masked"
+ @param mask "The mask for the store"
+ @param $alignment "The alignment of the load"
+
+ @require @typekind(ptrvec) == VECTOR : "Expected ptrvec to be a vector"
+ @require @typekind(value) == VECTOR : "Expected value to be a vector"
+ @require $assignable(&&value[0], $typeof(ptrvec[0])) : "Pointer and value must match"
+ @require value.len == mask.len : "Mask and value must have the same length"
+ @require mask.len == ptrvec.len : "Mask and ptrvec must have the same length"
+ @require @constant_is_power_of_2($alignment) : "The alignment must be a power of two"
+*>
 macro @scatter_aligned(ptrvec, value, bool[<*>] mask, usz $alignment)
 {
 	return $$scatter(ptrvec, value, mask, $alignment);
 }
 
-/**
- * @param [in] x "The variable or dereferenced pointer to load."
- * @param $alignment "The alignment to assume for the load"
- * @return "The value of x"
- *
- * @require @constant_is_power_of_2($alignment) : "The alignment must be a power of two"
- **/
+<*
+ @param [in] x "The variable or dereferenced pointer to load."
+ @param $alignment "The alignment to assume for the load"
+ @return "The value of x"
+
+ @require @constant_is_power_of_2($alignment) : "The alignment must be a power of two"
+*>
 macro @unaligned_load(&x, usz $alignment) @builtin
 {
 	return $$unaligned_load(x, $alignment);
 }
 
-/**
- * @param [out] x "The variable or dereferenced pointer to store to."
- * @param value "The value to store."
- * @param $alignment "The alignment to assume for the store"
- * @return "The value of x"
- *
- * @require $assignable(value, $typeof(*x)) : "The value doesn't match the variable"
- * @require @constant_is_power_of_2($alignment) : "The alignment must be a power of two"
- **/
+<*
+ @param [out] x "The variable or dereferenced pointer to store to."
+ @param value "The value to store."
+ @param $alignment "The alignment to assume for the store"
+ @return "The value of x"
+
+ @require $assignable(value, $typeof(*x)) : "The value doesn't match the variable"
+ @require @constant_is_power_of_2($alignment) : "The alignment must be a power of two"
+*>
 macro @unaligned_store(&x, value, usz $alignment) @builtin
 {
 	return $$unaligned_store(x, ($typeof(*x))value, $alignment);
@@ -192,9 +192,9 @@ macro @volatile_load(&x) @builtin
 	return $$volatile_load(x);
 }
 
-/**
- * @require $assignable(y, $typeof(*x)) : "The value doesn't match the variable"
- **/
+<*
+ @require $assignable(y, $typeof(*x)) : "The value doesn't match the variable"
+*>
 macro @volatile_store(&x, y) @builtin
 {
 	return $$volatile_store(x, ($typeof(*x))y);
@@ -211,58 +211,58 @@ enum AtomicOrdering : int
 	SEQ_CONSISTENT,     // Acquire semantics, ordered with other seq_consistent
 }
 
-/**
- * @param [in] x "the variable or dereferenced pointer to load."
- * @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
- * @param $volatile "whether the load should be volatile, defaults to 'false'"
- * @return "returns the value of x"
- *
- * @require $ordering != AtomicOrdering.RELEASE "Release ordering is not valid for load."
- * @require $ordering != AtomicOrdering.ACQUIRE_RELEASE "Acquire release is not valid for load."
- * @require types::may_load_atomic($typeof(x)) "Only integer, float and pointers may be used."
- * @require @typekind(x) == POINTER "You can only load from a pointer"
- **/
+<*
+ @param [in] x "the variable or dereferenced pointer to load."
+ @param $ordering "atomic ordering of the load, defaults to SEQ_CONSISTENT"
+ @param $volatile "whether the load should be volatile, defaults to 'false'"
+ @return "returns the value of x"
+
+ @require $ordering != AtomicOrdering.RELEASE "Release ordering is not valid for load."
+ @require $ordering != AtomicOrdering.ACQUIRE_RELEASE "Acquire release is not valid for load."
+ @require types::may_load_atomic($typeof(x)) "Only integer, float and pointers may be used."
+ @require @typekind(x) == POINTER "You can only load from a pointer"
+*>
 macro @atomic_load(&x, AtomicOrdering $ordering = SEQ_CONSISTENT, $volatile = false) @builtin
 {
 	return $$atomic_load(x, $volatile, (int)$ordering);
 }
 
-/**
- * @param [out] x "the variable or dereferenced pointer to store to."
- * @param value "the value to store."
- * @param $ordering "the atomic ordering of the store, defaults to SEQ_CONSISTENT"
- * @param $volatile "whether the store should be volatile, defaults to 'false'"
- *
- * @require $ordering != AtomicOrdering.ACQUIRE "Acquire ordering is not valid for store."
- * @require $ordering != AtomicOrdering.ACQUIRE_RELEASE "Acquire release is not valid for store."
- * @require types::may_load_atomic($typeof(x)) "Only integer, float and pointers may be used."
- **/
+<*
+ @param [out] x "the variable or dereferenced pointer to store to."
+ @param value "the value to store."
+ @param $ordering "the atomic ordering of the store, defaults to SEQ_CONSISTENT"
+ @param $volatile "whether the store should be volatile, defaults to 'false'"
+
+ @require $ordering != AtomicOrdering.ACQUIRE "Acquire ordering is not valid for store."
+ @require $ordering != AtomicOrdering.ACQUIRE_RELEASE "Acquire release is not valid for store."
+ @require types::may_load_atomic($typeof(x)) "Only integer, float and pointers may be used."
+*>
 macro void @atomic_store(&x, value, AtomicOrdering $ordering = SEQ_CONSISTENT, $volatile = false) @builtin
 {
 	$$atomic_store(x, value, $volatile, (int)$ordering);
 }
 
-/**
- * @require $success != AtomicOrdering.NOT_ATOMIC && $success != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- * @require $failure != AtomicOrdering.RELEASE && $failure != AtomicOrdering.ACQUIRE_RELEASE "Acquire release is not valid."
- **/
+<*
+ @require $success != AtomicOrdering.NOT_ATOMIC && $success != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+ @require $failure != AtomicOrdering.RELEASE && $failure != AtomicOrdering.ACQUIRE_RELEASE "Acquire release is not valid."
+*>
 macro compare_exchange(ptr, compare, value, AtomicOrdering $success = SEQ_CONSISTENT, AtomicOrdering $failure = SEQ_CONSISTENT, bool $volatile = true, bool $weak = false, usz $alignment = 0)
 {
 	return $$compare_exchange(ptr, compare, value, $volatile, $weak, $success.ordinal, $failure.ordinal, $alignment);
 }
 
-/**
- * @require $success != AtomicOrdering.NOT_ATOMIC && $success != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
- * @require $failure != AtomicOrdering.RELEASE && $failure != AtomicOrdering.ACQUIRE_RELEASE "Acquire release is not valid."
- **/
+<*
+ @require $success != AtomicOrdering.NOT_ATOMIC && $success != AtomicOrdering.UNORDERED "Acquire ordering is not valid."
+ @require $failure != AtomicOrdering.RELEASE && $failure != AtomicOrdering.ACQUIRE_RELEASE "Acquire release is not valid."
+*>
 macro compare_exchange_volatile(ptr, compare, value, AtomicOrdering $success = SEQ_CONSISTENT, AtomicOrdering $failure = SEQ_CONSISTENT)
 {
 	return compare_exchange(ptr, compare, value, $success, $failure, true);
 }
 
-/**
- * @require math::is_power_of_2(alignment)
- **/
+<*
+ @require math::is_power_of_2(alignment)
+*>
 fn usz aligned_offset(usz offset, usz alignment)
 {
 	return alignment * ((offset + alignment - 1) / alignment);
@@ -273,9 +273,9 @@ macro void* aligned_pointer(void* ptr, usz alignment)
 	return (void*)(uptr)aligned_offset((uptr)ptr, alignment);
 }
 
-/**
- * @require math::is_power_of_2(alignment)
- **/
+<*
+ @require math::is_power_of_2(alignment)
+*>
 fn bool ptr_is_aligned(void* ptr, usz alignment) @inline
 {
 	return (uptr)ptr & ((uptr)alignment - 1) == 0;
@@ -296,94 +296,96 @@ macro void clear_inline(void* dst, usz $len, usz $dst_align = 0, bool $is_volati
 	$$memset_inline(dst, (char)0, $len, $is_volatile, $dst_align);
 }
 
-/**
- * Copy memory from src to dst efficiently, assuming the memory ranges do not overlap.
- *
- * @param [&out] dst "The destination to copy to"
- * @param [&in] src "The source to copy from"
- * @param len "The number of bytes to copy"
- * @param $dst_align "the alignment of the destination if different from the default, 0 assumes the default"
- * @param $src_align "the alignment of the destination if different from the default, 0 assumes the default"
- * @param $is_volatile "True if this copy should be treated as volatile, i.e. it can't be optimized away."
- *
- * @require len == 0 || dst + len <= src || src + len <= dst : "Ranges may not overlap"
- **/
+<*
+ Copy memory from src to dst efficiently, assuming the memory ranges do not overlap.
+
+ @param [&out] dst "The destination to copy to"
+ @param [&in] src "The source to copy from"
+ @param len "The number of bytes to copy"
+ @param $dst_align "the alignment of the destination if different from the default, 0 assumes the default"
+ @param $src_align "the alignment of the destination if different from the default, 0 assumes the default"
+ @param $is_volatile "True if this copy should be treated as volatile, i.e. it can't be optimized away."
+
+ @require len == 0 || dst + len <= src || src + len <= dst : "Ranges may not overlap"
+*>
 macro void copy(void* dst, void* src, usz len, usz $dst_align = 0, usz $src_align = 0, bool $is_volatile = false, bool $inlined = false)
 {
 	$$memcpy(dst, src, len, $is_volatile, $dst_align, $src_align);
 }
 
-/**
- * Copy memory from src to dst efficiently, assuming the memory ranges do not overlap, it
- * will always be inlined and never call memcopy
- *
- * @param [&out] dst "The destination to copy to"
- * @param [&in] src "The source to copy from"
- * @param $len "The number of bytes to copy"
- * @param $dst_align "the alignment of the destination if different from the default, 0 assumes the default"
- * @param $src_align "the alignment of the destination if different from the default, 0 assumes the default"
- * @param $is_volatile "True if this copy should be treated as volatile, i.e. it can't be optimized away."
- *
- * @require $len == 0 || dst + $len <= src || src + $len <= dst : "Ranges may not overlap"
- **/
+<*
+ Copy memory from src to dst efficiently, assuming the memory ranges do not overlap, it
+ will always be inlined and never call memcopy
+
+ @param [&out] dst "The destination to copy to"
+ @param [&in] src "The source to copy from"
+ @param $len "The number of bytes to copy"
+ @param $dst_align "the alignment of the destination if different from the default, 0 assumes the default"
+ @param $src_align "the alignment of the destination if different from the default, 0 assumes the default"
+ @param $is_volatile "True if this copy should be treated as volatile, i.e. it can't be optimized away."
+
+ @require $len == 0 || dst + $len <= src || src + $len <= dst : "Ranges may not overlap"
+*>
 macro void copy_inline(void* dst, void* src, usz $len, usz $dst_align = 0, usz $src_align = 0, bool $is_volatile = false)
 {
 	$$memcpy_inline(dst, src, $len, $is_volatile, $dst_align, $src_align);
 }
 
-/**
- * Copy memory from src to dst but correctly handle the possibility of overlapping ranges.
- *
- * @param [&out] dst "The destination to copy to"
- * @param [&in] src "The source to copy from"
- * @param len "The number of bytes to copy"
- * @param $dst_align "the alignment of the destination if different from the default, 0 assumes the default"
- * @param $src_align "the alignment of the destination if different from the default, 0 assumes the default"
- * @param $is_volatile "True if this copy should be treated as volatile, i.e. it can't be optimized away."
- **/
+<*
+ Copy memory from src to dst but correctly handle the possibility of overlapping ranges.
+
+ @param [&out] dst "The destination to copy to"
+ @param [&in] src "The source to copy from"
+ @param len "The number of bytes to copy"
+ @param $dst_align "the alignment of the destination if different from the default, 0 assumes the default"
+ @param $src_align "the alignment of the destination if different from the default, 0 assumes the default"
+ @param $is_volatile "True if this copy should be treated as volatile, i.e. it can't be optimized away."
+*>
 macro void move(void* dst, void* src, usz len, usz $dst_align = 0, usz $src_align = 0, bool $is_volatile = false)
 {
 	$$memmove(dst, src, len, $is_volatile, $dst_align, $src_align);
 }
 
-/**
- * Sets all memory in a region to that of the provided byte.
- *
- * @param [&out] dst "The destination to copy to"
- * @param val "The value to copy into memory"
- * @param len "The number of bytes to copy"
- * @param $dst_align "the alignment of the destination if different from the default, 0 assumes the default"
- * @param $is_volatile "True if this copy should be treated as volatile, i.e. it can't be optimized away."
- *
- * @ensure !len || (dst[0] == val && dst[len - 1] == val)
- **/
+<*
+ Sets all memory in a region to that of the provided byte.
+
+ @param [&out] dst "The destination to copy to"
+ @param val "The value to copy into memory"
+ @param len "The number of bytes to copy"
+ @param $dst_align "the alignment of the destination if different from the default, 0 assumes the default"
+ @param $is_volatile "True if this copy should be treated as volatile, i.e. it can't be optimized away."
+
+ @ensure !len || (dst[0] == val && dst[len - 1] == val)
+*>
 macro void set(void* dst, char val, usz len, usz $dst_align = 0, bool $is_volatile = false)
 {
 	$$memset(dst, val, len, $is_volatile, $dst_align);
 }
 
-/**
- * Sets all memory in a region to that of the provided byte. Never calls OS memset.
- *
- * @param [&out] dst "The destination to copy to"
- * @param val "The value to copy into memory"
- * @param $len "The number of bytes to copy"
- * @param $dst_align "the alignment of the destination if different from the default, 0 assumes the default"
- * @param $is_volatile "True if this copy should be treated as volatile, i.e. it can't be optimized away."
- *
- * @ensure !$len || (dst[0] == val && dst[$len - 1] == val)
- **/
+<*
+ Sets all memory in a region to that of the provided byte. Never calls OS memset.
+
+ @param [&out] dst "The destination to copy to"
+ @param val "The value to copy into memory"
+ @param $len "The number of bytes to copy"
+ @param $dst_align "the alignment of the destination if different from the default, 0 assumes the default"
+ @param $is_volatile "True if this copy should be treated as volatile, i.e. it can't be optimized away."
+
+ @ensure !$len || (dst[0] == val && dst[$len - 1] == val)
+*>
 macro void set_inline(void* dst, char val, usz $len, usz $dst_align = 0, bool $is_volatile = false)
 {
 	$$memset_inline(dst, val, $len, $is_volatile, $dst_align);
 }
-/**
- * @require values::@inner_kind(a) == TypeKind.SLICE || values::@inner_kind(a) == TypeKind.POINTER
- * @require values::@inner_kind(b) == TypeKind.SLICE || values::@inner_kind(b) == TypeKind.POINTER
- * @require values::@inner_kind(a) != TypeKind.SLICE || len == -1
- * @require values::@inner_kind(a) != TypeKind.POINTER || len > -1
- * @require values::@assign_to(a, b) && values::@assign_to(b, a)
- **/
+<*
+ Test if n elements are equal in a slice, pointed to by a pointer etc.
+
+ @require values::@inner_kind(a) == TypeKind.SLICE || values::@inner_kind(a) == TypeKind.POINTER
+ @require values::@inner_kind(b) == TypeKind.SLICE || values::@inner_kind(b) == TypeKind.POINTER
+ @require values::@inner_kind(a) != TypeKind.SLICE || len == -1
+ @require values::@inner_kind(a) != TypeKind.POINTER || len > -1
+ @require values::@assign_to(a, b) && values::@assign_to(b, a)
+*>
 macro bool equals(a, b, isz len = -1, usz $align = 0)
 {
 	$if !$align:
@@ -429,15 +431,19 @@ macro bool equals(a, b, isz len = -1, usz $align = 0)
 	return true;
 }
 
+<*
+ Check if an allocation must be aligned given the type.
 
-macro type_alloc_must_be_aligned($Type)
+ @return `true if the alignment of the type exceeds DEFAULT_MEM_ALIGNMENT.`
+*>
+macro bool type_alloc_must_be_aligned($Type)
 {
 	return $Type.alignof > DEFAULT_MEM_ALIGNMENT;
 }
 
-/**
- * Run with a specific allocator inside of the macro body.
- **/
+<*
+ Run with a specific allocator inside of the macro body.
+*>
 macro void @scoped(Allocator allocator; @body())
 {
 	Allocator old_allocator = allocator::thread_allocator;
@@ -446,21 +452,37 @@ macro void @scoped(Allocator allocator; @body())
 	@body();
 }
 
-macro void @report_heap_allocs_in_scope(;@body())
+<*
+ Run the tracking allocator in the scope, then
+ print out stats.
+
+ @param $enabled "Set to false to disable tracking"
+*>
+macro void @report_heap_allocs_in_scope($enabled = true; @body())
 {
-	TrackingAllocator tracker;
-	tracker.init(allocator::thread_allocator);
-	Allocator old_allocator = allocator::thread_allocator;
-	allocator::thread_allocator = &tracker;
-	defer
-	{
-		allocator::thread_allocator = old_allocator;
-		tracker.print_report();
-		tracker.free();
-	}
+	$if $enabled:
+		TrackingAllocator tracker;
+		tracker.init(allocator::thread_allocator);
+		Allocator old_allocator = allocator::thread_allocator;
+		allocator::thread_allocator = &tracker;
+		defer
+		{
+			allocator::thread_allocator = old_allocator;
+			tracker.print_report();
+			tracker.free();
+		}
+	$endif
 	@body();
 }
 
+<*
+ Allocate [size] bytes on the stack to use for allocation,
+ with the heap allocator as the backing allocator.
+
+ Release everything on scope exit.
+
+ @param $size `the size of the buffer`
+*>
 macro void @stack_mem(usz $size; @body(Allocator mem)) @builtin
 {
 	char[$size] buffer;
@@ -488,10 +510,9 @@ struct TempState
 	TempAllocator* current;
 	usz mark;
 }
-
-/**
- * Push the current temp allocator. A push must always be balanced with a pop using the current state.
- **/
+<*
+ Push the current temp allocator. A push must always be balanced with a pop using the current state.
+*>
 fn TempState temp_push(TempAllocator* other = null)
 {
 	TempAllocator* current = allocator::temp();
@@ -503,9 +524,9 @@ fn TempState temp_push(TempAllocator* other = null)
 	return { old, current, current.used };
 }
 
-/**
- * Pop the current temp allocator. A pop must always be balanced with a push.
- **/
+<*
+ Pop the current temp allocator. A pop must always be balanced with a push.
+*>
 fn void temp_pop(TempState old_state)
 {
 	assert(allocator::thread_temp_allocator == old_state.current, "Tried to pop temp allocators out of order.");
@@ -580,10 +601,10 @@ fn void* malloc(usz size) @builtin @inline @nodiscard
 	return allocator::malloc(allocator::heap(), size);
 }
 
-/**
- * Allocate using an aligned allocation. This is necessary for types with a default memory alignment
- * exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
- **/
+<*
+ Allocate using an aligned allocation. This is necessary for types with a default memory alignment
+ exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
+*>
 fn void* malloc_aligned(usz size, usz alignment) @builtin @inline @nodiscard
 {
 	return allocator::malloc_aligned(allocator::heap(), size, alignment)!!;
@@ -595,11 +616,11 @@ fn void* tmalloc(usz size, usz alignment = 0) @builtin @inline @nodiscard
 	return allocator::temp().acquire(size, NO_ZERO, alignment)!!;
 }
 
-/**
- * @require $vacount < 2 : "Too many arguments."
- * @require $vacount == 0 ||| $assignable($vaexpr[0], $Type) : "The second argument must be an initializer for the type"
- * @require $Type.alignof <= DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'alloc_aligned' instead"
- **/
+<*
+ @require $vacount < 2 : "Too many arguments."
+ @require $vacount == 0 ||| $assignable($vaexpr[0], $Type) : "The second argument must be an initializer for the type"
+ @require $Type.alignof <= DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'alloc_aligned' instead"
+*>
 macro new($Type, ...) @nodiscard
 {
 	$if $vacount == 0:
@@ -611,12 +632,12 @@ macro new($Type, ...) @nodiscard
 	$endif
 }
 
-/**
- * Allocate using an aligned allocation. This is necessary for types with a default memory alignment
- * exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
- * @require $vacount < 2 : "Too many arguments."
- * @require $vacount == 0 ||| $assignable($vaexpr[0], $Type) : "The second argument must be an initializer for the type"
- **/
+<*
+ Allocate using an aligned allocation. This is necessary for types with a default memory alignment
+ exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
+ @require $vacount < 2 : "Too many arguments."
+ @require $vacount == 0 ||| $assignable($vaexpr[0], $Type) : "The second argument must be an initializer for the type"
+*>
 macro new_aligned($Type, ...) @nodiscard
 {
 	$if $vacount == 0:
@@ -628,27 +649,27 @@ macro new_aligned($Type, ...) @nodiscard
 	$endif
 }
 
-/**
- * @require $Type.alignof <= DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'alloc_aligned' instead"
- **/
+<*
+ @require $Type.alignof <= DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'alloc_aligned' instead"
+*>
 macro alloc($Type) @nodiscard
 {
 	return ($Type*)malloc($Type.sizeof);
 }
 
-/**
- * Allocate using an aligned allocation. This is necessary for types with a default memory alignment
- * exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
- **/
+<*
+ Allocate using an aligned allocation. This is necessary for types with a default memory alignment
+ exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
+*>
 macro alloc_aligned($Type) @nodiscard
 {
 	return ($Type*)malloc_aligned($Type.sizeof, $Type.alignof);
 }
 
-/**
- * @require $vacount < 2 : "Too many arguments."
- * @require $vacount == 0 ||| $assignable($vaexpr[0], $Type) : "The second argument must be an initializer for the type"
- **/
+<*
+ @require $vacount < 2 : "Too many arguments."
+ @require $vacount == 0 ||| $assignable($vaexpr[0], $Type) : "The second argument must be an initializer for the type"
+*>
 macro temp_new($Type, ...) @nodiscard
 {
 	$if $vacount == 0:
@@ -666,35 +687,35 @@ macro temp_alloc($Type) @nodiscard
 }
 
 
-/**
- * @require $Type.alignof <= DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'new_array_aligned' instead"
- **/
+<*
+ @require $Type.alignof <= DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'new_array_aligned' instead"
+*>
 macro new_array($Type, usz elements) @nodiscard
 {
 	return allocator::new_array(allocator::heap(), $Type, elements);
 }
 
-/**
- * Allocate using an aligned allocation. This is necessary for types with a default memory alignment
- * exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
- **/
+<*
+ Allocate using an aligned allocation. This is necessary for types with a default memory alignment
+ exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
+*>
 macro new_array_aligned($Type, usz elements) @nodiscard
 {
 	return allocator::new_array_aligned(allocator::heap(), $Type, elements);
 }
 
-/**
- * @require $Type.alignof <= DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'alloc_array_aligned' instead"
- **/
+<*
+ @require $Type.alignof <= DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'alloc_array_aligned' instead"
+*>
 macro alloc_array($Type, usz elements) @nodiscard
 {
 	return allocator::alloc_array(allocator::heap(), $Type, elements);
 }
 
-/**
- * Allocate using an aligned allocation. This is necessary for types with a default memory alignment
- * exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
- **/
+<*
+ Allocate using an aligned allocation. This is necessary for types with a default memory alignment
+ exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
+*>
 macro alloc_array_aligned($Type, usz elements) @nodiscard
 {
 	return allocator::alloc_array_aligned(allocator::heap(), $Type, elements);
@@ -715,10 +736,10 @@ fn void* calloc(usz size) @builtin @inline @nodiscard
 	return allocator::calloc(allocator::heap(), size);
 }
 
-/**
- * Allocate using an aligned allocation. This is necessary for types with a default memory alignment
- * exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
- **/
+<*
+ Allocate using an aligned allocation. This is necessary for types with a default memory alignment
+ exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
+*>
 fn void* calloc_aligned(usz size, usz alignment) @builtin @inline @nodiscard
 {
 	return allocator::calloc_aligned(allocator::heap(), size, alignment)!!;
@@ -753,7 +774,45 @@ fn void free_aligned(void* ptr) @builtin @inline
 fn void* trealloc(void* ptr, usz size, usz alignment = mem::DEFAULT_MEM_ALIGNMENT) @builtin @inline @nodiscard
 {
 	if (!size) return null;
-    if (!ptr) return tmalloc(size, alignment);
+	if (!ptr) return tmalloc(size, alignment);
 	return allocator::temp().resize(ptr, size, alignment)!!;
 }
 
+module std::core::mem @if(env::NO_LIBC);
+
+fn CInt __memcmp(void* s1, void* s2, usz n) @weak @export("memcmp")
+{
+	char* p1 = s1;
+	char* p2 = s2;
+	for (usz i = 0; i < n; i++, p1++, p2++)
+	{
+		char c1 = *p1;
+		char c2 = *p2;
+		if (c1 < c2) return -1;
+		if (c1 > c2) return 1;
+	}
+	return 0;
+}
+
+fn void* __memset(void* str, CInt c, usz n) @weak @export("memset")
+{
+	char* p = str;
+	char cc = (char)c;
+	for (usz i = 0; i < n; i++, p++)
+	{
+		*p = cc;
+	}
+	return str;
+}
+
+fn void* __memcpy(void* dst, void* src, usz n) @weak @export("memcpy")
+{
+	char* d = dst;
+	char* s = src;
+	for (usz i = 0; i < n; i++, d++, s++)
+	{
+		*d = *s;
+	}
+	return dst;
+}
+

lib/std/core/mem_allocator.c3

@@ -20,22 +20,22 @@ interface Allocator
 {
 	fn void reset(usz mark) @optional;
 	fn usz mark() @optional;
-	/**
-     * @require !alignment || math::is_power_of_2(alignment)
-     * @require alignment <= mem::MAX_MEMORY_ALIGNMENT `alignment too big`
-     * @require size > 0
-     **/
+	<*
+	 @require !alignment || math::is_power_of_2(alignment)
+	 @require alignment <= mem::MAX_MEMORY_ALIGNMENT `alignment too big`
+	 @require size > 0
+	*>
 	fn void*! acquire(usz size, AllocInitType init_type, usz alignment = 0);
-	/**
-     * @require !alignment || math::is_power_of_2(alignment)
-     * @require alignment <= mem::MAX_MEMORY_ALIGNMENT `alignment too big`
-     * @require ptr != null
-     * @require new_size > 0
-     **/
+	<*
+	 @require !alignment || math::is_power_of_2(alignment)
+	 @require alignment <= mem::MAX_MEMORY_ALIGNMENT `alignment too big`
+	 @require ptr != null
+	 @require new_size > 0
+	*>
 	fn void*! resize(void* ptr, usz new_size, usz alignment = 0);
-	/**
-     * @require ptr != null
-     **/
+	<*
+	 @require ptr != null
+	*>
 	fn void release(void* ptr, bool aligned);
 }
 
@@ -146,11 +146,11 @@ macro void free_aligned(Allocator allocator, void* ptr)
 	allocator.release(ptr, aligned: true);
 }
 
-/**
- * @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'new_aligned' instead"
- * @require $vacount < 2 : "Too many arguments."
- * @require $vacount == 0 ||| $assignable($vaexpr[0], $Type) : "The second argument must be an initializer for the type"
- **/
+<*
+ @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'new_aligned' instead"
+ @require $vacount < 2 : "Too many arguments."
+ @require $vacount == 0 ||| $assignable($vaexpr[0], $Type) : "The second argument must be an initializer for the type"
+*>
 macro new(Allocator allocator, $Type, ...) @nodiscard
 {
 	$if $vacount == 0:
@@ -162,11 +162,11 @@ macro new(Allocator allocator, $Type, ...) @nodiscard
 	$endif
 }
 
-/**
- * @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'new_aligned' instead"
- * @require $vacount < 2 : "Too many arguments."
- * @require $vacount == 0 ||| $assignable($vaexpr[0], $Type) : "The second argument must be an initializer for the type"
- **/
+<*
+ @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'new_aligned' instead"
+ @require $vacount < 2 : "Too many arguments."
+ @require $vacount == 0 ||| $assignable($vaexpr[0], $Type) : "The second argument must be an initializer for the type"
+*>
 macro new_try(Allocator allocator, $Type, ...) @nodiscard
 {
 	$if $vacount == 0:
@@ -178,12 +178,12 @@ macro new_try(Allocator allocator, $Type, ...) @nodiscard
 	$endif
 }
 
-/**
- * Allocate using an aligned allocation. This is necessary for types with a default memory alignment
- * exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
- * @require $vacount < 2 : "Too many arguments."
- * @require $vacount == 0 ||| $assignable($vaexpr[0], $Type) : "The second argument must be an initializer for the type"
- **/
+<*
+ Allocate using an aligned allocation. This is necessary for types with a default memory alignment
+ exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
+ @require $vacount < 2 : "Too many arguments."
+ @require $vacount == 0 ||| $assignable($vaexpr[0], $Type) : "The second argument must be an initializer for the type"
+*>
 macro new_aligned($Type, ...) @nodiscard
 {
 	$if $vacount == 0:
@@ -195,92 +195,92 @@ macro new_aligned($Type, ...) @nodiscard
 	$endif
 }
 
-/**
- * @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT
- **/
+<*
+ @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT
+*>
 macro new_with_padding(Allocator allocator, $Type, usz padding) @nodiscard
 {
 	return ($Type*)calloc_try(allocator, $Type.sizeof + padding);
 }
 
-/**
- * @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'alloc_aligned' instead"
- **/
+<*
+ @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'alloc_aligned' instead"
+*>
 macro alloc(Allocator allocator, $Type) @nodiscard
 {
 	return ($Type*)malloc(allocator, $Type.sizeof);
 }
 
-/**
- * @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'alloc_aligned' instead"
- **/
+<*
+ @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'alloc_aligned' instead"
+*>
 macro alloc_try(Allocator allocator, $Type) @nodiscard
 {
 	return ($Type*)malloc_try(allocator, $Type.sizeof);
 }
 
-/**
- * Allocate using an aligned allocation. This is necessary for types with a default memory alignment
- * exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
- **/
+<*
+ Allocate using an aligned allocation. This is necessary for types with a default memory alignment
+ exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
+*>
 macro alloc_aligned(Allocator allocator, $Type) @nodiscard
 {
 	return ($Type*)malloc_aligned(allocator, $Type.sizeof, $Type.alignof);
 }
 
-/**
- * @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT
- **/
+<*
+ @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT
+*>
 macro alloc_with_padding(Allocator allocator, $Type, usz padding) @nodiscard
 {
 	return ($Type*)malloc_try(allocator, $Type.sizeof + padding);
 }
 
-/**
- * @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'new_array_aligned' instead"
- **/
+<*
+ @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'new_array_aligned' instead"
+*>
 macro new_array(Allocator allocator, $Type, usz elements) @nodiscard
 {
 	return new_array_try(allocator, $Type, elements)!!;
 }
 
-/**
- * @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'new_array_aligned' instead"
- **/
+<*
+ @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'new_array_aligned' instead"
+*>
 macro new_array_try(Allocator allocator, $Type, usz elements) @nodiscard
 {
 	return (($Type*)calloc_try(allocator, $Type.sizeof * elements))[:elements];
 }
 
-/**
- * Allocate using an aligned allocation. This is necessary for types with a default memory alignment
- * exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
- **/
+<*
+ Allocate using an aligned allocation. This is necessary for types with a default memory alignment
+ exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
+*>
 macro new_array_aligned(Allocator allocator, $Type, usz elements) @nodiscard
 {
 	return (($Type*)calloc_aligned(allocator, $Type.sizeof * elements, $Type.alignof))[:elements]!!;
 }
 
-/**
- * @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'alloc_array_aligned' instead"
- **/
+<*
+ @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'alloc_array_aligned' instead"
+*>
 macro alloc_array(Allocator allocator, $Type, usz elements) @nodiscard
 {
 	return alloc_array_try(allocator, $Type, elements)!!;
 }
 
-/**
- * Allocate using an aligned allocation. This is necessary for types with a default memory alignment
- * exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
- **/
+<*
+ Allocate using an aligned allocation. This is necessary for types with a default memory alignment
+ exceeding DEFAULT_MEM_ALIGNMENT. IMPORTANT! It must be freed using free_aligned.
+*>
 macro alloc_array_aligned(Allocator allocator, $Type, usz elements) @nodiscard
 {
 	return (($Type*)malloc_aligned(allocator, $Type.sizeof * elements, $Type.alignof))[:elements]!!;
 }
 
-/**
- * @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'alloc_array_aligned' instead"
- **/
+<*
+ @require $Type.alignof <= mem::DEFAULT_MEM_ALIGNMENT : "Types with alignment exceeding the default must use 'alloc_array_aligned' instead"
+*>
 macro alloc_array_try(Allocator allocator, $Type, usz elements) @nodiscard
 {
 	return (($Type*)malloc_try(allocator, $Type.sizeof * elements))[:elements];
@@ -300,11 +300,11 @@ fn any clone_any(Allocator allocator, any value) @nodiscard
 }
 
 
-/**
- * @require bytes > 0
- * @require alignment > 0
- * @require bytes <= isz.max
- **/
+<*
+ @require bytes > 0
+ @require alignment > 0
+ @require bytes <= isz.max
+*>
 macro void*! @aligned_alloc(#alloc_fn, usz bytes, usz alignment)
 {
 	if (alignment < void*.alignof) alignment = void*.alignof;
@@ -338,10 +338,10 @@ macro void! @aligned_free(#free_fn, void* old_pointer)
 	$endif
 }
 
-/**
- * @require bytes > 0
- * @require alignment > 0
- **/
+<*
+ @require bytes > 0
+ @require alignment > 0
+*>
 macro void*! @aligned_realloc(#calloc_fn, #free_fn, void* old_pointer, usz bytes, usz alignment)
 {
 	AlignedBlock* desc = (AlignedBlock*)old_pointer - 1;
@@ -412,9 +412,9 @@ fn void destroy_temp_allocators_after_exit() @finalizer(65535) @local @if(env::L
 	destroy_temp_allocators();
 }
 
-/**
- * Call this to destroy any memory used by the temp allocators. This will invalidate all temp memory.
- **/
+<*
+ Call this to destroy any memory used by the temp allocators. This will invalidate all temp memory.
+*>
 fn void destroy_temp_allocators()
 {
 	if (!thread_temp_allocator) return;

lib/std/core/private/cpu_detect.c3

@@ -25,6 +25,11 @@ enum X86Feature
 {
 	ADX,
 	AES,
+	AMX_AVX512,
+	AMX_FP8,
+	AMX_MOVRS,
+	AMX_TF32,
+	AMX_TRANSPOSE,
 	AMX_BF16,
 	AMX_COMPLEX,
 	AMX_FP16,
@@ -34,6 +39,8 @@ enum X86Feature
 	AVX,
 	AVX10_1_256,
 	AVX10_1_512,
+	AVX10_2_256,
+	AVX10_2_512,
 	AVX2,
 	AVX5124FMAPS,
 	AVX5124VNNIW,
@@ -84,6 +91,7 @@ enum X86Feature
 	MOVBE,
 	MOVDIR64B,
 	MOVDIRI,
+	MOVRS,
 	MWAITX,
 	PCLMUL,
 	PCONFIG,

lib/std/core/runtime.c3

@@ -4,7 +4,7 @@
 module std::core::runtime;
 import libc, std::time, std::io, std::sort;
 
-struct ReflectedParam @if(!$defined(ReflectedParam))
+struct ReflectedParam (Printable) @if(!$defined(ReflectedParam))
 {
 	String name;
 	typeid type;

lib/std/core/sanitizer/asan.c3

@@ -14,21 +14,21 @@ module std::core::sanitizer::asan;
 
 def ErrorCallback = fn void (ZString);
 
-/**
- * Marks a memory region ([addr, addr+size)) as unaddressable.
- *
- * This memory must be previously allocated by your program. Instrumented
- * code is forbidden from accessing addresses in this region until it is
- * unpoisoned. This function is not guaranteed to poison the entire region -
- * it could poison only a subregion of [addr, addr+size) due to ASan
- * alignment restrictions.
- *
- * NOTE This function is not thread-safe because no two threads can poison or
- * unpoison memory in the same memory region simultaneously.
- *
- * @param addr "Start of memory region."
- * @param size "Size of memory region."
- **/
+<*
+ Marks a memory region ([addr, addr+size)) as unaddressable.
+
+ This memory must be previously allocated by your program. Instrumented
+ code is forbidden from accessing addresses in this region until it is
+ unpoisoned. This function is not guaranteed to poison the entire region -
+ it could poison only a subregion of [addr, addr+size) due to ASan
+ alignment restrictions.
+
+ NOTE This function is not thread-safe because no two threads can poison or
+ unpoison memory in the same memory region simultaneously.
+
+ @param addr "Start of memory region."
+ @param size "Size of memory region."
+*>
 macro poison_memory_region(void* addr, usz size)
 {
 	$if env::ADDRESS_SANITIZER: 
@@ -36,20 +36,20 @@ macro poison_memory_region(void* addr, usz size)
 	$endif 
 }
 
-/**
- * Marks a memory region ([addr, addr+size)) as addressable.
- *
- * This memory must be previously allocated by your program. Accessing
- * addresses in this region is allowed until this region is poisoned again.
- * This function could unpoison a super-region of [addr, addr+size) due
- * to ASan alignment restrictions.
- *
- * NOTE This function is not thread-safe because no two threads can
- * poison or unpoison memory in the same memory region simultaneously.
- *
- * @param addr "Start of memory region."
- * @param size "Size of memory region."
- **/
+<*
+ Marks a memory region ([addr, addr+size)) as addressable.
+
+ This memory must be previously allocated by your program. Accessing
+ addresses in this region is allowed until this region is poisoned again.
+ This function could unpoison a super-region of [addr, addr+size) due
+ to ASan alignment restrictions.
+
+ NOTE This function is not thread-safe because no two threads can
+ poison or unpoison memory in the same memory region simultaneously.
+
+ @param addr "Start of memory region."
+ @param size "Size of memory region."
+*>
 macro unpoison_memory_region(void* addr, usz size)
 {
 	$if env::ADDRESS_SANITIZER: 
@@ -57,11 +57,11 @@ macro unpoison_memory_region(void* addr, usz size)
 	$endif 
 }
 
-/**
- * Checks if an address is poisoned.
- * @return "True if 'addr' is poisoned (that is, 1-byte read/write access to this address would result in an error report from ASan). Otherwise returns false."
- * @param addr "Address to check."
- **/
+<*
+ Checks if an address is poisoned.
+ @return "True if 'addr' is poisoned (that is, 1-byte read/write access to this address would result in an error report from ASan). Otherwise returns false."
+ @param addr "Address to check."
+*>
 macro bool address_is_poisoned(void* addr)
 {
 	$if env::ADDRESS_SANITIZER:
@@ -71,28 +71,28 @@ macro bool address_is_poisoned(void* addr)
 	$endif
 }
 
-/**
- * Checks if a region is poisoned.
- *
- * If at least one byte in [beg, beg+size) is poisoned, returns the
- * address of the first such byte. Otherwise returns 0.
- *
- * @param beg "Start of memory region."
- * @param size "Start of memory region."
- * @return "Address of first poisoned byte."
- **/
+<*
+ Checks if a region is poisoned.
+
+ If at least one byte in [beg, beg+size) is poisoned, returns the
+ address of the first such byte. Otherwise returns 0.
+
+ @param beg "Start of memory region."
+ @param size "Start of memory region."
+ @return "Address of first poisoned byte."
+*>
 macro void* region_is_poisoned(void* beg, usz size)
 {
 	$if env::ADDRESS_SANITIZER:
-		return __asan_region_is_poisoned(addr);
+		return __asan_region_is_poisoned(beg, size);
 	$else
 		return null;
 	$endif
 }
 
-/**
- * Sets the callback function to be called during ASan error reporting.
- **/
+<*
+ Sets the callback function to be called during ASan error reporting.
+*>
 fn void set_error_report_callback(ErrorCallback callback)
 {
 	$if env::ADDRESS_SANITIZER:

lib/std/core/string.c3

@@ -1,5 +1,6 @@
 module std::core::string;
 import std::ascii;
+import std::io;
 
 distinct String @if(!$defined(String)) = inline char[];
 distinct ZString = inline char*;
@@ -33,11 +34,11 @@ fault NumberConversion
 }
 
 
-/**
- * Return a temporary ZString created using the formatting function.
- *
- * @param [in] fmt `The formatting string`
- **/
+<*
+ Return a temporary ZString created using the formatting function.
+
+ @param [in] fmt `The formatting string`
+*>
 fn ZString tformat_zstr(String fmt, args...)
 {
 	DString str = dstring::temp_with_capacity(fmt.len + args.len * 8);
@@ -45,12 +46,12 @@ fn ZString tformat_zstr(String fmt, args...)
 	return str.zstr_view();
 }
 
-/**
- * Return a new String created using the formatting function.
- *
- * @param [inout] allocator `The allocator to use`
- * @param [in] fmt `The formatting string`
- **/
+<*
+ Return a new String created using the formatting function.
+
+ @param [inout] allocator `The allocator to use`
+ @param [in] fmt `The formatting string`
+*>
 fn String format(String fmt, args..., Allocator allocator)
 {
 	@pool(allocator)
@@ -61,18 +62,18 @@ fn String format(String fmt, args..., Allocator allocator)
 	};
 }
 
-/**
- * Return a heap allocated String created using the formatting function.
- *
- * @param [in] fmt `The formatting string`
- **/
+<*
+ Return a heap allocated String created using the formatting function.
+
+ @param [in] fmt `The formatting string`
+*>
 fn String new_format(String fmt, args..., Allocator allocator = null) => format(fmt, ...args, allocator: allocator ?: allocator::heap());
 
-/**
- * Return a temporary String created using the formatting function.
- *
- * @param [in] fmt `The formatting string`
- **/
+<*
+ Return a temporary String created using the formatting function.
+
+ @param [in] fmt `The formatting string`
+*>
 fn String tformat(String fmt, args...)
 {
 	DString str = dstring::temp_with_capacity(fmt.len + args.len * 8);
@@ -80,12 +81,12 @@ fn String tformat(String fmt, args...)
 	return str.str_view();
 }
 
-/**
- * Return a new ZString created using the formatting function.
- *
- * @param [in] fmt `The formatting string`
- * @param [inout] allocator `The allocator to use`
- **/
+<*
+ Return a new ZString created using the formatting function.
+
+ @param [in] fmt `The formatting string`
+ @param [inout] allocator `The allocator to use`
+*>
 fn ZString new_format_zstr(String fmt, args..., Allocator allocator = allocator::heap())
 {
 	@pool(allocator)
@@ -96,14 +97,14 @@ fn ZString new_format_zstr(String fmt, args..., Allocator allocator = allocator:
 	};
 }
 
-/**
- * Check if a character is in a set.
- *
- * @param c `the character to check`
- * @param [in] set `The formatting string`
- * @pure
- * @return `True if a character is in the set`
- **/
+<*
+ Check if a character is in a set.
+
+ @param c `the character to check`
+ @param [in] set `The formatting string`
+ @pure
+ @return `True if a character is in the set`
+*>
 macro bool char_in_set(char c, String set)
 {
 	foreach (ch : set) if (ch == c) return true;
@@ -135,14 +136,14 @@ fn String join_new(String[] s, String joiner, Allocator allocator = allocator::h
 	};
 }
 
-/**
- * Remove characters from the front and end of a string.
- *
- * @param [in] string `The string to trim`
- * @param [in] to_trim `The set of characters to trim, defaults to whitespace`
- * @pure
- * @return `a substring of the string passed in`
- **/
+<*
+ Remove characters from the front and end of a string.
+
+ @param [in] string `The string to trim`
+ @param [in] to_trim `The set of characters to trim, defaults to whitespace`
+ @pure
+ @return `a substring of the string passed in`
+*>
 fn String String.trim(string, String to_trim = "\t\n\r ")
 {
 	usz start = 0;
@@ -154,14 +155,14 @@ fn String String.trim(string, String to_trim = "\t\n\r ")
 	return string[start..end];
 }
 
-/**
- * Check if the String starts with the needle.
- *
- * @param [in] string
- * @param [in] needle
- * @pure
- * @return `'true' if the string starts with the needle`
- **/
+<*
+ Check if the String starts with the needle.
+
+ @param [in] string
+ @param [in] needle
+ @pure
+ @return `'true' if the string starts with the needle`
+*>
 fn bool String.starts_with(string, String needle)
 {
 	if (needle.len > string.len) return false;
@@ -169,14 +170,14 @@ fn bool String.starts_with(string, String needle)
 	return string[:needle.len] == needle;
 }
 
-/**
- * Check if the String ends with the needle.
- *
- * @param [in] string
- * @param [in] needle
- * @pure
- * @return `'true' if the string ends with the needle`
- **/
+<*
+ Check if the String ends with the needle.
+
+ @param [in] string
+ @param [in] needle
+ @pure
+ @return `'true' if the string ends with the needle`
+*>
 fn bool String.ends_with(string, String needle)
 {
 	if (needle.len > string.len) return false;
@@ -184,28 +185,28 @@ fn bool String.ends_with(string, String needle)
 	return string[^needle.len..] == needle;
 }
 
-/**
- * Strip the front of the string if the prefix exists.
- *
- * @param [in] string
- * @param [in] needle
- * @pure
- * @return `the substring with the prefix removed`
- **/
+<*
+ Strip the front of the string if the prefix exists.
+
+ @param [in] string
+ @param [in] needle
+ @pure
+ @return `the substring with the prefix removed`
+*>
 fn String String.strip(string, String needle)
 {
 	if (!needle.len || !string.starts_with(needle)) return string;
 	return string[needle.len..];
 }
 
-/**
- * Strip the end of the string if the suffix exists.
- *
- * @param [in] string
- * @param [in] needle
- * @pure
- * @return `the substring with the suffix removed`
- **/
+<*
+ Strip the end of the string if the suffix exists.
+
+ @param [in] string
+ @param [in] needle
+ @pure
+ @return `the substring with the suffix removed`
+*>
 fn String String.strip_end(string, String needle)
 {
 	if (!needle.len || !string.ends_with(needle)) return string;
@@ -213,16 +214,16 @@ fn String String.strip_end(string, String needle)
 	return string[:(string.len - needle.len)];
 }
 
-/**
- * Split a string into parts, e.g "a|b|c" split with "|" yields { "a", "b", "c" }
- *
- * @param [in] s
- * @param [in] needle
- * @param [&inout] allocator "The allocator to use for the String[]"
- * @param max "Max number of elements, 0 means no limit, defaults to 0"
- * @require needle.len > 0 "The needle must be at least 1 character long"
- * @ensure return.len > 0
- **/
+<*
+ Split a string into parts, e.g "a|b|c" split with "|" yields { "a", "b", "c" }
+
+ @param [in] s
+ @param [in] needle
+ @param [&inout] allocator "The allocator to use for the String[]"
+ @param max "Max number of elements, 0 means no limit, defaults to 0"
+ @require needle.len > 0 "The needle must be at least 1 character long"
+ @ensure return.len > 0
+*>
 fn String[] String.split(s, String needle, usz max = 0, Allocator allocator = allocator::heap())
 {
 	usz capacity = 16;
@@ -253,51 +254,51 @@ fn String[] String.split(s, String needle, usz max = 0, Allocator allocator = al
 	return holder[:i];
 }
 
-/**
- * Split a string into parts, e.g "a|b|c" split with "|" yields { "a", "b", "c" }, using the heap allocator
- * to store the parts.
- *
- * @param [in] s
- * @param [in] needle
- * @param max "Max number of elements, 0 means no limit, defaults to 0"
- * @require needle.len > 0 "The needle must be at least 1 character long"
- * @ensure return.len > 0
- **/
+<*
+ Split a string into parts, e.g "a|b|c" split with "|" yields { "a", "b", "c" }, using the heap allocator
+ to store the parts.
+
+ @param [in] s
+ @param [in] needle
+ @param max "Max number of elements, 0 means no limit, defaults to 0"
+ @require needle.len > 0 "The needle must be at least 1 character long"
+ @ensure return.len > 0
+*>
 fn String[] String.new_split(s, String needle, usz max = 0) => s.split(needle, max, allocator::heap()) @inline;
 
-/**
- * This function is identical to String.split, but implicitly uses the
- * temporary allocator.
- *
- * @param [in] s
- * @param [in] needle
- * @param max "Max number of elements, 0 means no limit, defaults to 0"
- **/
+<*
+ This function is identical to String.split, but implicitly uses the
+ temporary allocator.
+
+ @param [in] s
+ @param [in] needle
+ @param max "Max number of elements, 0 means no limit, defaults to 0"
+*>
 fn String[] String.tsplit(s, String needle, usz max = 0) => s.split(needle, max, allocator::temp()) @inline;
 
-/**
- * Check if a substring is found in the string.
+<*
+ Check if a substring is found in the string.
 
- * @param [in] s
- * @param [in] needle "The string to look for."
- * @pure
- * @return "true if the string contains the substring, false otherwise"
- **/
+ @param [in] s
+ @param [in] needle "The string to look for."
+ @pure
+ @return "true if the string contains the substring, false otherwise"
+*>
 fn bool String.contains(s, String needle)
 {
 	return @ok(s.index_of(needle));
 }
 
-/**
- * Find the index of the first incidence of a string.
- *
- * @param [in] s
- * @param needle "The character to look for"
- * @pure
- * @ensure return < s.len
- * @return "the index of the needle"
- * @return! SearchResult.MISSING "if the needle cannot be found"
- **/
+<*
+ Find the index of the first incidence of a string.
+
+ @param [in] s
+ @param needle "The character to look for"
+ @pure
+ @ensure return < s.len
+ @return "the index of the needle"
+ @return! SearchResult.MISSING "if the needle cannot be found"
+*>
 fn usz! String.index_of_char(s, char needle)
 {
 	foreach (i, c : s)
@@ -307,17 +308,17 @@ fn usz! String.index_of_char(s, char needle)
 	return SearchResult.MISSING?;
 }
 
-/**
- * Find the index of the first incidence of a character.
- *
- * @param [in] s
- * @param needle "The character to look for"
- * @param start_index "The index to start with, may exceed max index."
- * @pure
- * @ensure return < s.len
- * @return "the index of the needle"
- * @return! SearchResult.MISSING "if the needle cannot be found starting from the start_index"
- **/
+<*
+ Find the index of the first incidence of a character.
+
+ @param [in] s
+ @param needle "The character to look for"
+ @param start_index "The index to start with, may exceed max index."
+ @pure
+ @ensure return < s.len
+ @return "the index of the needle"
+ @return! SearchResult.MISSING "if the needle cannot be found starting from the start_index"
+*>
 fn usz! String.index_of_char_from(s, char needle, usz start_index)
 {
 	usz len = s.len;
@@ -329,16 +330,16 @@ fn usz! String.index_of_char_from(s, char needle, usz start_index)
 	return SearchResult.MISSING?;
 }
 
-/**
- * Find the index of the first incidence of a character starting from the end.
- *
- * @param [in] s
- * @param needle "the character to find"
- * @pure
- * @ensure return < s.len
- * @return "the index of the needle"
- * @return! SearchResult.MISSING "if the needle cannot be found"
- **/
+<*
+ Find the index of the first incidence of a character starting from the end.
+
+ @param [in] s
+ @param needle "the character to find"
+ @pure
+ @ensure return < s.len
+ @return "the index of the needle"
+ @return! SearchResult.MISSING "if the needle cannot be found"
+*>
 fn usz! String.rindex_of_char(s, char needle)
 {
 	foreach_r (i, c : s)
@@ -348,17 +349,17 @@ fn usz! String.rindex_of_char(s, char needle)
 	return SearchResult.MISSING?;
 }
 
-/**
- * Find the index of the first incidence of a string.
- *
- * @param [in] s
- * @param [in] needle
- * @pure
- * @ensure return < s.len
- * @require needle.len > 0 : "The needle must be len 1 or more"
- * @return "the index of the needle"
- * @return! SearchResult.MISSING "if the needle cannot be found"
- **/
+<*
+ Find the index of the first incidence of a string.
+
+ @param [in] s
+ @param [in] needle
+ @pure
+ @ensure return < s.len
+ @require needle.len > 0 : "The needle must be len 1 or more"
+ @return "the index of the needle"
+ @return! SearchResult.MISSING "if the needle cannot be found"
+*>
 fn usz! String.index_of(s, String needle)
 {
 	usz needed = needle.len;
@@ -373,17 +374,17 @@ fn usz! String.index_of(s, String needle)
 	return SearchResult.MISSING?;
 }
 
-/**
- * Find the index of the last incidence of a string.
- *
- * @param [in] s
- * @param [in] needle
- * @pure
- * @ensure return < s.len
- * @require needle.len > 0 "The needle must be len 1 or more"
- * @return "the index of the needle"
- * @return! SearchResult.MISSING "if the needle cannot be found"
- **/
+<*
+ Find the index of the last incidence of a string.
+
+ @param [in] s
+ @param [in] needle
+ @pure
+ @ensure return < s.len
+ @require needle.len > 0 "The needle must be len 1 or more"
+ @return "the index of the needle"
+ @return! SearchResult.MISSING "if the needle cannot be found"
+*>
 fn usz! String.rindex_of(s, String needle)
 {
 	usz needed = needle.len;
@@ -466,7 +467,7 @@ fn void String.free(&s, Allocator allocator = allocator::heap())
 
 fn String String.tcopy(s) => s.copy(allocator::temp()) @inline;
 
-fn String ZString.copy(z, Allocator allocator = allocator::temp())
+fn String ZString.copy(z, Allocator allocator = allocator::heap())
 {
 	return z.str_view().copy(allocator) @inline;
 }
@@ -476,12 +477,12 @@ fn String ZString.tcopy(z)
 	return z.str_view().copy(allocator::temp()) @inline;
 }
 
-/**
- * Convert an UTF-8 string to UTF-16
- * @return "The UTF-16 string as a slice, allocated using the given allocator"
- * @return! UnicodeResult.INVALID_UTF8 "If the string contained an invalid UTF-8 sequence"
- * @return! AllocationFailure "If allocation of the string fails"
- **/
+<*
+ Convert an UTF-8 string to UTF-16
+ @return "The UTF-16 string as a slice, allocated using the given allocator"
+ @return! UnicodeResult.INVALID_UTF8 "If the string contained an invalid UTF-8 sequence"
+ @return! AllocationFailure "If allocation of the string fails"
+*>
 fn Char16[]! String.to_new_utf16(s, Allocator allocator = allocator::heap())
 {
 	usz len16 = conv::utf16len_for_utf8(s);
@@ -491,12 +492,12 @@ fn Char16[]! String.to_new_utf16(s, Allocator allocator = allocator::heap())
 	return data[:len16];
 }
 
-/**
- * Convert an UTF-8 string to UTF-16
- * @return "The UTF-16 string as a slice, allocated using the given allocator"
- * @return! UnicodeResult.INVALID_UTF8 "If the string contained an invalid UTF-8 sequence"
- * @return! AllocationFailure "If allocation of the string fails"
- **/
+<*
+ Convert an UTF-8 string to UTF-16
+ @return "The UTF-16 string as a slice, allocated using the given allocator"
+ @return! UnicodeResult.INVALID_UTF8 "If the string contained an invalid UTF-8 sequence"
+ @return! AllocationFailure "If allocation of the string fails"
+*>
 fn Char16[]! String.to_temp_utf16(s)
 {
 	return s.to_new_utf16(allocator::temp());
@@ -522,12 +523,12 @@ fn Char32[]! String.to_utf32(s, Allocator allocator)
 fn Char32[]! String.to_new_utf32(s) => s.to_utf32(allocator::heap()) @inline;
 fn Char32[]! String.to_temp_utf32(s) => s.to_utf32(allocator::temp()) @inline;
 
-/**
- * Convert a string to ASCII lower case.
- *
- * @param [inout] s
- * @pure
- **/
+<*
+ Convert a string to ASCII lower case.
+
+ @param [inout] s
+ @pure
+*>
 fn void String.convert_ascii_to_lower(s)
 {
 	foreach (&c : s) if (c.is_upper() @pure) *c += 'a' - 'A';
@@ -545,25 +546,25 @@ fn String String.temp_ascii_to_lower(s)
 	return s.new_ascii_to_lower(allocator::temp());
 }
 
-/**
- * Convert a string to ASCII upper case.
- *
- * @param [inout] s
- * @pure
- **/
+<*
+ Convert a string to ASCII upper case.
+
+ @param [inout] s
+ @pure
+*>
 fn void String.convert_ascii_to_upper(s)
 {
 	foreach (&c : s) if (c.is_lower() @pure) *c -= 'a' - 'A';
 }
 
-/**
- * Returns a string converted to ASCII upper case.
- *
- * @param [in] s
- * @param [inout] allocator
- *
- * @return `a new String converted to ASCII upper case.`
- **/
+<*
+ Returns a string converted to ASCII upper case.
+
+ @param [in] s
+ @param [inout] allocator
+
+ @return `a new String converted to ASCII upper case.`
+*>
 fn String String.new_ascii_to_upper(s, Allocator allocator = allocator::heap())
 {
 	String copy = s.copy(allocator);
@@ -576,10 +577,10 @@ fn StringIterator String.iterator(s)
 	return { s, 0 };
 }
 
-/**
- * @param [in] s
- * @return `a temporary String converted to ASCII upper case.`
- **/
+<*
+ @param [in] s
+ @return `a temporary String converted to ASCII upper case.`
+*>
 fn String String.temp_ascii_to_upper(s)
 {
 	return s.new_ascii_to_upper(allocator::temp());
@@ -627,9 +628,9 @@ fn usz String.utf8_codepoints(s)
 }
 
 
-/**
- * @require (base <= 10 && base > 1) || base == 16 : "Unsupported base"
- **/
+<*
+ @require (base <= 10 && base > 1) || base == 16 : "Unsupported base"
+*>
 macro String.to_integer(string, $Type, int base = 10)
 {
 	usz len = string.len;
@@ -749,4 +750,15 @@ fn String! Splitter.next(&self)
 	return remaining;
 }
 
+macro String new_struct_to_str(x, Allocator allocator = allocator::heap())
+{
+	DString s;
+	@stack_mem(512; Allocator mem)
+	{
+		s.new_init(allocator: mem);
+		io::fprint(&s, x)!!;
+	};
+	return s.copy_str(allocator);
+}
 
+macro String temp_struct_to_str(x) => new_struct_to_str(x, allocator::temp());

lib/std/core/string_to_real.c3

@@ -31,9 +31,9 @@ const MASK = KMAX - 1;
 const B1B_DIG = 2;
 const uint[2] B1B_MAX = { 9007199, 254740991 };
 
-/**
- * @require chars.len > 0
- **/
+<*
+ @require chars.len > 0
+*>
 macro double! decfloat(char[] chars, int $bits, int $emin, int sign)
 {
 	uint[KMAX] x;
@@ -266,7 +266,7 @@ macro double! decfloat(char[] chars, int $bits, int $emin, int sign)
 	y *= sign;
 
 	bool denormal;
-	/* Limit precision for denormal results */
+	// Limit precision for denormal results
 	uint bits = $bits;
 	if (bits > math::DOUBLE_MANT_DIG + e2 - $emin)
 	{

lib/std/core/types.c3

@@ -8,9 +8,9 @@ fault ConversionResult
 	VALUE_OUT_OF_RANGE,
 	VALUE_OUT_OF_UNSIGNED_RANGE,
 }
-/**
- * @require $Type.kindof.is_int() || $Type.kindof == TypeKind.ENUM "Argument was not an integer"
- **/
+<*
+ @require $Type.kindof.is_int() || $Type.kindof == TypeKind.ENUM "Argument was not an integer"
+*>
 macro any_to_int(any v, $Type)
 {
 	typeid any_type = v.type;
@@ -123,9 +123,9 @@ macro bool is_slice_convertable($Type)
 macro bool is_bool($Type) @const => $Type.kindof == TypeKind.BOOL;
 macro bool is_int($Type) @const  => $Type.kindof == TypeKind.SIGNED_INT || $Type.kindof == TypeKind.UNSIGNED_INT;
 
-/**
- * @require is_numerical($Type) "Expected a numerical type"
- **/
+<*
+ @require is_numerical($Type) "Expected a numerical type"
+*>
 macro bool is_signed($Type) @const
 {
 	$switch (inner_kind($Type))
@@ -139,9 +139,9 @@ macro bool is_signed($Type) @const
 	$endswitch
 }
 
-/**
- * @require is_numerical($Type) "Expected a numerical type"
- **/
+<*
+ @require is_numerical($Type) "Expected a numerical type"
+*>
 macro bool is_unsigned($Type) @const
 {
 	$switch (inner_kind($Type))
@@ -260,9 +260,9 @@ macro bool may_load_atomic($Type) @const
 macro lower_to_atomic_compatible_type($Type) @const
 {
 	$switch ($Type.kindof)
-    $case SIGNED_INT:
+	$case SIGNED_INT:
 	  $case UNSIGNED_INT:
-      return $Type.typeid;
+	  return $Type.typeid;
 		$case DISTINCT:
 			return lower_to_atomic_compatible_type($Type.inner);
 		$case FLOAT:
@@ -304,9 +304,9 @@ macro bool is_equatable_type($Type) @const
 	$endif
 }
 
-/**
- * Checks if a type implements the copy protocol.
- **/
+<*
+ Checks if a type implements the copy protocol.
+*>
 macro bool implements_copy($Type) @const
 {
 	return $defined($Type.copy) && $defined($Type.free);

lib/std/core/values.c3

@@ -3,9 +3,9 @@ module std::core::values;
 macro typeid @typeid(#value) @const @builtin => $typeof(#value).typeid;
 macro TypeKind @typekind(#value) @const @builtin => $typeof(#value).kindof;
 macro bool @typeis(#value, $Type) @const @builtin => $typeof(#value).typeid == $Type.typeid;
-/**
- * Return true if two values have the same type before any conversions.
- **/
+<*
+ Return true if two values have the same type before any conversions.
+*>
 macro bool @is_same_type(#value1, #value2) @const => $typeof(#value1).typeid == $typeof(#value2).typeid;
 macro bool @is_bool(#value) @const => types::is_bool($typeof(#value));
 macro bool @is_int(#value) @const => types::is_int($typeof(#value));

lib/std/crypto/rc4.c3

@@ -9,12 +9,12 @@ struct Rc4
 	char[256] state;
 }
 
-/**
- * Initialize the RC4 state.
- *
- * @param [in] key "The key to use"
- * @require key.len > 0 "The key must be at least 1 byte long"
- **/
+<*
+ Initialize the RC4 state.
+
+ @param [in] key "The key to use"
+ @require key.len > 0 "The key must be at least 1 byte long"
+*>
 fn void Rc4.init(&self, char[] key)
 {
 	// Init the state matrix
@@ -28,11 +28,11 @@ fn void Rc4.init(&self, char[] key)
 	self.j = 0;
 }
 
-/**
- * Run a single pass of en/decryption using a particular key.
- * @param [in] key
- * @param [inout] data
- **/
+<*
+ Run a single pass of en/decryption using a particular key.
+ @param [in] key
+ @param [inout] data
+*>
 fn void crypt(char[] key, char[] data)
 {
 	Rc4 rc4;
@@ -40,13 +40,13 @@ fn void crypt(char[] key, char[] data)
 	rc4.crypt(data, data);
 }
 
-/**
- * Encrypt or decrypt a sequence of bytes.
- *
- * @param [in] in "The input"
- * @param [out] out "The output"
- * @require in.len <= out.len "Output would overflow"
- **/
+<*
+ Encrypt or decrypt a sequence of bytes.
+
+ @param [in] in "The input"
+ @param [out] out "The output"
+ @require in.len <= out.len "Output would overflow"
+*>
 fn void Rc4.crypt(&self, char[] in, char[] out)
 {
 	uint i = self.i;
@@ -64,11 +64,11 @@ fn void Rc4.crypt(&self, char[] in, char[] out)
 	self.j = j;
 }
 
-/**
- * Clear the rc4 state.
- *
- * @param [&out] self "The RC4 State"
- **/
+<*
+ Clear the rc4 state.
+
+ @param [&out] self "The RC4 State"
+*>
 fn void Rc4.destroy(&self)
 {
 	*self = {};

lib/std/encoding/base32.c3

@@ -0,0 +1,406 @@
+module std::encoding::base32;
+
+// This module implements base32 encoding according to RFC 4648
+// (https://www.rfc-editor.org/rfc/rfc4648)
+
+struct Base32Alphabet
+{
+	char[32] encoding;
+	char[256] reverse;
+}
+
+const char NO_PAD = 0;
+const char DEFAULT_PAD = '=';
+
+<*
+ Encode the content of src into a newly allocated string
+ @param [in] src "The input to be encoded."
+ @param padding "The padding character or 0 if none"
+ @param alphabet "The alphabet to use"
+ @require padding < 0xFF "Invalid padding character"
+ @return "The encoded string."
+*>
+fn String! encode(char[] src, Allocator allocator, char padding = DEFAULT_PAD, Base32Alphabet* alphabet = &STANDARD)
+{
+	char[] dst = allocator::alloc_array(allocator, char, encode_len(src.len, padding));
+	return encode_buffer(src, dst, padding, alphabet);
+}
+
+<*
+ Decode the content of src into a newly allocated char array.
+ @param [in] src "The input to be encoded."
+ @param padding "The padding character or 0 if none"
+ @param alphabet "The alphabet to use"
+ @require padding < 0xFF "Invalid padding character"
+ @return "The decoded data."
+*>
+fn char[]! decode(char[] src, Allocator allocator, char padding = DEFAULT_PAD, Base32Alphabet* alphabet = &STANDARD)
+{
+	char[] dst = allocator::alloc_array(allocator, char, decode_len(src.len, padding));
+	return decode_buffer(src, dst, padding, alphabet);
+}
+
+fn String! encode_new(char[] code, char padding = DEFAULT_PAD, Base32Alphabet* alphabet = &STANDARD) @inline => encode(code, allocator::heap(), padding, alphabet);
+fn String! encode_temp(char[] code, char padding = DEFAULT_PAD, Base32Alphabet* alphabet = &STANDARD) @inline => encode(code, allocator::temp(), padding, alphabet);
+fn char[]! decode_new(char[] code, char padding = DEFAULT_PAD, Base32Alphabet* alphabet = &STANDARD) @inline => decode(code, allocator::heap(), padding, alphabet);
+fn char[]! decode_temp(char[] code, char padding = DEFAULT_PAD, Base32Alphabet* alphabet = &STANDARD) @inline => decode(code, allocator::temp(), padding, alphabet);
+
+<*
+ Calculate the length in bytes of the decoded data.
+ @param n "Length in bytes of input."
+ @param padding "The padding character or 0 if none"
+ @require padding < 0xFF "Invalid padding character"
+ @return "Length in bytes of the decoded data."
+*>
+fn usz decode_len(usz n, char padding)
+{
+	if (padding) return (n / 8) * 5;
+	// no padding
+	usz trailing = n % 8;
+	return n / 8 * 5 + (trailing * 5 ) / 8;
+}
+
+<*
+ Calculate the length in bytes of the encoded data.
+ @param n "Length in bytes on input."
+ @param padding "The padding character or 0 if none"
+ @require padding < 0xFF "Invalid padding character"
+ @return "Length in bytes of the encoded data."
+*>
+fn usz encode_len(usz n, char padding)
+{
+	// A character is encoded into 8 x 5-bit blocks.
+	if (padding) return (n + 4) / 5 * 8;
+
+	// no padding
+	usz trailing = n % 5;
+	return n / 5 * 8 + (trailing * 8 + 4) / 5;
+}
+
+<*
+ Decode the content of src into dst, which must be properly sized.
+ @param src "The input to be decoded."
+ @param dst "The decoded input."
+ @param padding "The padding character or 0 if none"
+ @param alphabet "The alphabet to use"
+ @require padding < 0xFF "Invalid padding character"
+ @require dst.len >= decode_len(src.len, padding) "Destination buffer too small"
+ @return "The resulting dst buffer"
+ @return! DecodingFailure
+*>
+fn char[]! decode_buffer(char[] src, char[] dst, char padding = DEFAULT_PAD, Base32Alphabet* alphabet = &STANDARD)
+{
+	if (src.len == 0) return dst[:0];
+	char* dst_ptr = dst;
+	usz dn = decode_len(src.len, padding);
+	usz n;
+	char[8] buf;
+	while (src.len > 0 && dst.len > 0)
+	{
+		usz i @noinit;
+		// load 8 bytes into buffer
+		for (i = 0; i < 8; i++)
+		{
+			if (src.len == 0)
+			{
+				if (padding > 0) return DecodingFailure.INVALID_PADDING?;
+				break;
+			}
+			if (src[0] == padding) break;
+			buf[i] = alphabet.reverse[src[0]];
+			if (buf[i] == INVALID) return DecodingFailure.INVALID_CHARACTER?;
+			src = src[1..];
+		}
+
+		// extract 5-bytes from the buffer which contains 8 x 5 bit chunks
+		switch (i)
+		{
+			case 8:
+				// |66677777|  dst[4]
+				// |   77777|  buf[7]
+				// |666     |  buf[6] << 5
+				dst[4] = buf[7] | buf[6] << 5;
+				n++;
+				nextcase 7;
+			case 7:
+				// |45555566|  dst[3]
+				// |      66|  buf[6] >> 3
+				// | 55555  |  buf[5] << 2
+				// |4       |  buf[4] << 7
+				dst[3] = buf[6] >> 3 | buf[5] << 2 | buf[4] << 7;
+				n++;
+				nextcase 5;
+			case 5:
+				// |33334444|  dst[2]
+				// |    4444|  buf[4] >> 1
+				// |3333    |  buf[3] << 4
+				dst[2] = buf[4] >> 1 | buf[3] << 4;
+				n++;
+				nextcase 4;
+			case 4:
+				// |11222223|  dst[1]
+				// |       3|  buf[3] >> 4
+				// |  22222 |  buf[2] << 1
+				// |11      |  buf[1] << 6
+				dst[1] = buf[3] >> 4 | buf[2] << 1 | buf[1] << 6;
+				n++;
+				nextcase 2;
+			case 2:
+				// |00000111|  dst[0]
+				// |     111|  buf[1] >> 2
+				// |00000   |  buf[0] << 3
+				dst[0] = buf[1] >> 2 | buf[0] << 3;
+				n++;
+			default:
+				return DecodingFailure.INVALID_CHARACTER?;
+		}
+		if (dst.len < 5) break;
+		dst = dst[5..];
+	}
+	return dst_ptr[:n];
+}
+
+<*
+ Encode the content of src into dst, which must be properly sized.
+ @param [in] src "The input to be encoded."
+ @param [inout] dst "The encoded input."
+ @param padding "The padding character or 0 if none"
+ @param alphabet "The alphabet to use"
+ @require padding < 0xFF "Invalid padding character"
+ @require dst.len >= encode_len(src.len, padding) "Destination buffer too small"
+ @return "The encoded size."
+*>
+fn String encode_buffer(char[] src, char[] dst, char padding = DEFAULT_PAD, Base32Alphabet* alphabet = &STANDARD)
+{
+	if (src.len == 0) return (String)dst[:0];
+
+	char* dst_ptr = dst;
+	usz n = (src.len / 5) * 5;
+	usz dn = encode_len(src.len, padding);
+
+	uint msb, lsb;
+	for (usz i = 0; i < n; i += 5)
+	{
+		// to fit 40 bits we need two 32-bit uints
+		msb = (uint)src[i] << 24 | (uint)src[i+1] << 16
+				| (uint)src[i+2] << 8 | (uint)src[i+3];
+		lsb = msb << 8 | (uint)src[i+4];
+
+		// now slice them into 5-bit chunks and translate to the
+		// alphabet.
+		dst[0] = alphabet.encoding[(msb >> 27) & MASK];
+		dst[1] = alphabet.encoding[(msb >> 22) & MASK];
+		dst[2] = alphabet.encoding[(msb >> 17) & MASK];
+		dst[3] = alphabet.encoding[(msb >> 12) & MASK];
+		dst[4] = alphabet.encoding[(msb >> 7) & MASK];
+		dst[5] = alphabet.encoding[(msb >> 2) & MASK];
+		dst[6] = alphabet.encoding[(lsb >> 5) & MASK];
+		dst[7] = alphabet.encoding[lsb & MASK];
+
+		dst = dst[8..];
+	}
+
+	usz trailing = src.len - n;
+	if (trailing == 0) return (String)dst_ptr[:dn];
+
+	msb = 0;
+	switch (trailing)
+	{
+		case 4:
+			msb |= (uint)src[n+3];
+			lsb = msb << 8;
+			dst[6] = alphabet.encoding[(lsb >> 5) & MASK];
+			dst[5] = alphabet.encoding[(msb >> 2) & MASK];
+			nextcase 3;
+		case 3:
+			msb |= (uint)src[n+2] << 8;
+			dst[4] = alphabet.encoding[(msb >> 7) & MASK];
+			nextcase 2;
+		case 2:
+			msb |= (uint)src[n+1] << 16;
+			dst[3] = alphabet.encoding[(msb >> 12) & MASK];
+			dst[2] = alphabet.encoding[(msb >> 17) & MASK];
+			nextcase 1;
+		case 1:
+			msb |= (uint)src[n] << 24;
+			dst[1] = alphabet.encoding[(msb >> 22) & MASK];
+			dst[0] = alphabet.encoding[(msb >> 27) & MASK];
+	}
+
+	// add the padding
+	if (padding > 0)
+	{
+		for (usz i = (trailing * 8 / 5) + 1; i < 8; i++)
+		{
+			dst[i] = padding;
+		}
+	}
+	return (String)dst_ptr[:dn];
+}
+
+const uint MASK @private = 0b11111;
+const char INVALID @private = 0xff;
+
+const int STD_PADDING = '=';
+const int NO_PADDING = -1;
+
+fault Base32Error
+{
+	DUPLICATE_IN_ALPHABET,
+	PADDING_IN_ALPHABET,
+	INVALID_CHARACTER_IN_ALPHABET,
+	DESTINATION_TOO_SMALL,
+	INVALID_PADDING,
+	CORRUPT_INPUT
+}
+
+struct Base32Encoder @deprecated
+{
+	Base32Alphabet alphabet;
+	char padding;
+}
+
+<*
+ @param encoder "The 32-character alphabet for encoding."
+ @param padding "Set to a negative value to disable padding."
+ @require padding < 256
+*>
+fn void! Base32Encoder.init(&self, Alphabet encoder = STD_ALPHABET, int padding = STD_PADDING)
+{
+	encoder.validate(padding)!;
+	*self = { .alphabet = { .encoding = (char[32])encoder }, .padding = padding < 0 ? (char)0 : (char)padding};
+}
+
+<*
+ Calculate the length in bytes of the encoded data.
+ @param n "Length in bytes on input."
+ @return "Length in bytes of the encoded data."
+*>
+fn usz Base32Encoder.encode_len(&self, usz n)
+{
+	return encode_len(n, self.padding);
+}
+
+<*
+ Encode the content of src into dst, which must be properly sized.
+ @param [in] src "The input to be encoded."
+ @param [inout] dst "The encoded input."
+ @return "The encoded size."
+ @return! Base32Error.DESTINATION_TOO_SMALL
+*>
+fn usz! Base32Encoder.encode(&self, char[] src, char[] dst)
+{
+	usz dn = self.encode_len(src.len);
+	if (dst.len < dn) return Base32Error.DESTINATION_TOO_SMALL?;
+	return encode_buffer(src, dst, self.padding, &self.alphabet).len;
+}
+
+struct Base32Decoder @deprecated
+{
+	Base32Alphabet alphabet;
+	char padding;
+}
+
+<*
+ @param decoder "The alphabet used for decoding."
+ @param padding "Set to a negative value to disable padding."
+ @require padding < 256
+*>
+fn void! Base32Decoder.init(&self, Alphabet decoder = STD_ALPHABET, int padding = STD_PADDING)
+{
+	decoder.validate(padding)!;
+	*self = { .alphabet = { .encoding = (char[32])decoder }, .padding = padding < 0 ? (char)0 : (char)padding };
+
+	self.alphabet.reverse[..] = INVALID;
+	foreach (char i, c : decoder)
+	{
+		self.alphabet.reverse[c] = i;
+	}
+}
+
+<*
+ Calculate the length in bytes of the decoded data.
+ @param n "Length in bytes of input."
+ @return "Length in bytes of the decoded data."
+*>
+fn usz Base32Decoder.decode_len(&self, usz n)
+{
+	return decode_len(n, self.padding);
+}
+
+<*
+ Decode the content of src into dst, which must be properly sized.
+ @param src "The input to be decoded."
+ @param dst "The decoded input."
+ @return "The decoded size."
+ @return! Base32Error.DESTINATION_TOO_SMALL, Base32Error.CORRUPT_INPUT
+*>
+fn usz! Base32Decoder.decode(&self, char[] src, char[] dst)
+{
+	if (src.len == 0) return 0;
+	usz dn = self.decode_len(src.len);
+	if (dst.len < dn) return Base32Error.DESTINATION_TOO_SMALL?;
+	return decode_buffer(src, dst, self.padding, &self.alphabet).len;
+}
+
+
+// Validate the 32-character alphabet to make sure that no character occurs
+// twice and that the padding is not present in the alphabet.
+fn void! Alphabet.validate(&self, int padding)
+{
+	bool[256] checked;
+	foreach (c : self)
+	{
+		if (checked[c])
+		{
+			return Base32Error.DUPLICATE_IN_ALPHABET?;
+		}
+		checked[c] = true;
+		if (c == '\r' || c == '\n')
+		{
+			return Base32Error.INVALID_CHARACTER_IN_ALPHABET?;
+		}
+	}
+	if (padding >= 0)
+	{
+		char pad = (char)padding;
+		if (pad == '\r' || pad == '\n')
+		{
+			return Base32Error.INVALID_PADDING?;
+		}
+		if (checked[pad])
+		{
+			return Base32Error.PADDING_IN_ALPHABET?;
+		}
+	}
+}
+
+distinct Alphabet = char[32];
+// Standard base32 Alphabet
+const Alphabet STD_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+// Extended Hex Alphabet
+const Alphabet HEX_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUV";
+
+const Base32Alphabet STANDARD = {
+	.encoding = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567",
+	.reverse = x`ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+                 ffffffffffffffffffffffffffffffffffff1a1b1c1d1e1fffffffffffffffff
+                 ff000102030405060708090a0b0c0d0e0f10111213141516171819ffffffffff
+                 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+                 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+                 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+                 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+                 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff`
+};
+
+const Base32Alphabet HEX = {
+	.encoding = "0123456789ABCDEFGHIJKLMNOPQRSTUV",
+	.reverse = x`ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+                 ffffffffffffffffffffffffffffffff00010203040506070809ffffffffffff
+                 ff0a0b0c0d0e0f101112131415161718191a1b1c1d1e1fffffffffffffffffff
+                 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+                 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+                 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+                 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+                 ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff`
+};

lib/std/encoding/base64.c3

@@ -5,14 +5,260 @@ import std::core::bitorder;
 // Specifically this section:
 // https://www.rfc-editor.org/rfc/rfc4648#section-4
 
+const char NO_PAD = 0;
+const char DEFAULT_PAD = '=';
+
+struct Base64Alphabet
+{
+	char[64] encoding;
+	char[256] reverse;
+}
+
+const Base64Alphabet STANDARD = {
+	.encoding = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/",
+	.reverse =
+	x`ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+	  ffffffffffffffffffffff3effffff3f3435363738393a3b3c3dffffffffffff
+	  ff000102030405060708090a0b0c0d0e0f10111213141516171819ffffffffff
+	  ff1a1b1c1d1e1f202122232425262728292a2b2c2d2e2f30313233ffffffffff
+	  ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+	  ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+	  ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+	  ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff`
+};
+
+const Base64Alphabet URL = {
+	.encoding = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_",
+	.reverse =
+	x`ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+	  ffffffffffffffffffffffffff3effff3435363738393a3b3c3dffffffffffff
+	  ff000102030405060708090a0b0c0d0e0f10111213141516171819ffffffff3f
+	  ff1a1b1c1d1e1f202122232425262728292a2b2c2d2e2f30313233ffffffffff
+	  ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+	  ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+	  ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+	  ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff`
+};
+
 const STD_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 const URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
 
+fn String encode(char[] src, Allocator allocator, char padding = DEFAULT_PAD, Base64Alphabet* alphabet = &STANDARD)
+{
+	char[] dst = allocator::alloc_array(allocator, char, encode_len(src.len, padding));
+	return encode_buffer(src, dst, padding, alphabet);
+}
+
+fn char[]! decode(char[] src, Allocator allocator, char padding = DEFAULT_PAD, Base64Alphabet* alphabet = &STANDARD)
+{
+	char[] dst = allocator::alloc_array(allocator, char, decode_len(src.len, padding))!;
+	return decode_buffer(src, dst, padding, alphabet);
+}
+
+fn String encode_new(char[] code, char padding = DEFAULT_PAD, Base64Alphabet* alphabet = &STANDARD) @inline => encode(code, allocator::heap(), padding, alphabet);
+fn String encode_temp(char[] code, char padding = DEFAULT_PAD, Base64Alphabet* alphabet = &STANDARD) @inline => encode(code, allocator::temp(), padding, alphabet);
+fn char[]! decode_new(char[] code, char padding = DEFAULT_PAD, Base64Alphabet* alphabet = &STANDARD) @inline => decode(code, allocator::heap(), padding, alphabet);
+fn char[]! decode_temp(char[] code, char padding = DEFAULT_PAD, Base64Alphabet* alphabet = &STANDARD) @inline => decode(code, allocator::temp(), padding, alphabet);
+
+
+<*
+ Calculate the size of the encoded data.
+ @param n "Size of the input to be encoded."
+ @param padding "The padding character or 0 if none"
+ @require padding < 0xFF "Invalid padding character"
+ @return "The size of the input once encoded."
+*>
+fn usz encode_len(usz n, char padding)
+{
+	if (padding) return (n + 2) / 3 * 4;
+	usz trailing = n % 3;
+	return n / 3 * 4 + (trailing * 4 + 2) / 3;
+}
+
+<*
+ Calculate the size of the decoded data.
+ @param n "Size of the input to be decoded."
+ @param padding "The padding character or 0 if none"
+ @require padding < 0xFF "Invalid padding character"
+ @return "The size of the input once decoded."
+ @return! DecodingFailure.INVALID_PADDING
+*>
+fn usz! decode_len(usz n, char padding)
+{
+	usz dn = n / 4 * 3;
+	usz trailing = n % 4;
+	if (padding)
+	{
+		if (trailing != 0) return DecodingFailure.INVALID_PADDING?;
+		// source size is multiple of 4
+		return dn;
+	}
+	if (trailing == 1) return DecodingFailure.INVALID_PADDING?;
+	return dn + trailing * 3 / 4;
+}
+
+<*
+ Encode the content of src into dst, which must be properly sized.
+ @param src "The input to be encoded."
+ @param dst "The encoded input."
+ @param padding "The padding character or 0 if none"
+ @param alphabet "The alphabet to use"
+ @require padding < 0xFF "Invalid padding character"
+ @return "The encoded size."
+ @return! Base64Error.DESTINATION_TOO_SMALL
+*>
+fn String encode_buffer(char[] src, char[] dst, char padding = DEFAULT_PAD, Base64Alphabet* alphabet = &STANDARD)
+{
+	if (src.len == 0) return (String)dst[:0];
+	usz dn = encode_len(src.len, padding);
+	char* dst_ptr = dst;
+	assert(dst.len >= dn);
+	usz trailing = src.len % 3;
+	char[] src3 = src[:^trailing];
+
+	while (src3.len > 0)
+	{
+		uint group = (uint)src3[0] << 16 | (uint)src3[1] << 8 | (uint)src3[2];
+		dst[0] = alphabet.encoding[group >> 18 & MASK];
+		dst[1] = alphabet.encoding[group >> 12 & MASK];
+		dst[2] = alphabet.encoding[group >> 6 & MASK];
+		dst[3] = alphabet.encoding[group & MASK];
+		dst = dst[4..];
+		src3 = src3[3..];
+	}
+
+	// Encode the remaining bytes according to:
+	// https://www.rfc-editor.org/rfc/rfc4648#section-3.5
+	switch (trailing)
+	{
+		case 1:
+			uint group = (uint)src[^1] << 16;
+			dst[0] = alphabet.encoding[group >> 18 & MASK];
+			dst[1] = alphabet.encoding[group >> 12 & MASK];
+			if (padding > 0)
+			{
+				dst[2] = padding;
+				dst[3] = padding;
+			}
+		case 2:
+			uint group = (uint)src[^2] << 16 | (uint)src[^1] << 8;
+			dst[0] = alphabet.encoding[group >> 18 & MASK];
+			dst[1] = alphabet.encoding[group >> 12 & MASK];
+			dst[2] = alphabet.encoding[group >> 6 & MASK];
+			if (padding > 0)
+			{
+				dst[3] = padding;
+			}
+		case 0:
+			break;
+		default:
+			unreachable();
+	}
+	return (String)dst_ptr[:dn];
+}
+
+<*
+ Decode the content of src into dst, which must be properly sized.
+ @param src "The input to be decoded."
+ @param dst "The decoded input."
+ @param padding "The padding character or 0 if none"
+ @param alphabet "The alphabet to use"
+ @require (decode_len(src.len, padding) ?? 0) <= dst.len "Destination buffer too small"
+ @require padding < 0xFF "Invalid padding character"
+ @return "The decoded data."
+ @return! DecodingFailure
+*>
+fn char[]! decode_buffer(char[] src, char[] dst, char padding = DEFAULT_PAD, Base64Alphabet* alphabet = &STANDARD)
+{
+	if (src.len == 0) return dst[:0];
+	usz dn = decode_len(src.len, padding)!;
+	assert(dst.len >= dn);
+
+	usz trailing = src.len % 4;
+	char* dst_ptr = dst;
+	char[] src4 = src;
+	switch
+	{
+		case !padding:
+			src4 = src[:^trailing];
+		default:
+			// If there is padding, keep the last 4 bytes for later.
+			// NB. src.len >= 4 as decode_len passed
+			trailing = 4;
+			if (src[^1] == padding) src4 = src[:^4];
+	}
+	while (src4.len > 0)
+	{
+		char c0 = alphabet.reverse[src4[0]];
+		char c1 = alphabet.reverse[src4[1]];
+		char c2 = alphabet.reverse[src4[2]];
+		char c3 = alphabet.reverse[src4[3]];
+		switch (0xFF)
+		{
+			case c0:
+			case c1:
+			case c2:
+			case c3:
+				return DecodingFailure.INVALID_CHARACTER?;
+		}
+		uint group = (uint)c0 << 18 | (uint)c1 << 12 | (uint)c2 << 6 | (uint)c3;
+		dst[0] = (char)(group >> 16);
+		dst[1] = (char)(group >> 8);
+		dst[2] = (char)group;
+		dst = dst[3..];
+		src4 = src4[4..];
+	}
+
+	if (trailing == 0) return dst_ptr[:dn];
+
+	src = src[^trailing..];
+	char c0 = alphabet.reverse[src[0]];
+	char c1 = alphabet.reverse[src[1]];
+	if (c0 == 0xFF || c1 == 0xFF) return DecodingFailure.INVALID_PADDING?;
+	if (!padding)
+	{
+		switch (src.len)
+		{
+			case 2:
+				uint group = (uint)c0 << 18 | (uint)c1 << 12;
+				dst[0] = (char)(group >> 16);
+			case 3:
+				char c2 = alphabet.reverse[src[2]];
+				if (c2 == 0xFF) return DecodingFailure.INVALID_CHARACTER?;
+				uint group = (uint)c0 << 18 | (uint)c1 << 12 | (uint)c2 << 6;
+				dst[0] = (char)(group >> 16);
+				dst[1] = (char)(group >> 8);
+		}
+	}
+	else
+	{
+		// Valid paddings are:
+		// 2: xx==
+		// 1: xxx=
+		switch (padding)
+		{
+			case src[2]:
+				if (src[3] != padding) return DecodingFailure.INVALID_PADDING?;
+				uint group = (uint)c0 << 18 | (uint)c1 << 12;
+				dst[0] = (char)(group >> 16);
+				dn -= 2;
+			case src[3]:
+				char c2 = alphabet.reverse[src[2]];
+				if (c2 == 0xFF) return DecodingFailure.INVALID_CHARACTER?;
+				uint group = (uint)c0 << 18 | (uint)c1 << 12 | (uint)c2 << 6;
+				dst[0] = (char)(group >> 16);
+				dst[1] = (char)(group >> 8);
+				dn -= 1;
+		}
+	}
+	return dst_ptr[:dn];
+}
+
 const MASK @private = 0b111111;
 
-struct Base64Encoder
+struct Base64Encoder @deprecated
 {
-	int padding;
+	char padding;
 	String alphabet;
 }
 
@@ -25,243 +271,109 @@ fault Base64Error
 	INVALID_CHARACTER,
 }
 
-/**
- * @param alphabet "The alphabet used for encoding."
- * @param padding "Set to a negative value to disable padding."
- * @require alphabet.len == 64
- * @require padding < 256
- * @return! Base64Error.DUPLICATE_IN_ALPHABET, Base64Error.PADDING_IN_ALPHABET
- **/
-fn void! Base64Encoder.init(&self, String alphabet, int padding = '=')
+<*
+ @param alphabet "The alphabet used for encoding."
+ @param padding "Set to a negative value to disable padding."
+ @require alphabet.len == 64
+ @require padding < 256
+ @return! Base64Error.DUPLICATE_IN_ALPHABET, Base64Error.PADDING_IN_ALPHABET
+*>
+fn Base64Encoder*! Base64Encoder.init(&self, String alphabet, int padding = '=')
 {
 	check_alphabet(alphabet, padding)!;
-	*self = { .padding = padding, .alphabet = alphabet };
+	*self = { .padding = padding < 0 ? 0 : (char)padding, .alphabet = alphabet };
+	return self;
 }
 
-/**
- * Calculate the size of the encoded data.
- * @param n "Size of the input to be encoded."
- * @return "The size of the input once encoded."
- **/
+<*
+ Calculate the size of the encoded data.
+ @param n "Size of the input to be encoded."
+ @return "The size of the input once encoded."
+*>
 fn usz Base64Encoder.encode_len(&self, usz n)
 {
-	if (self.padding >= 0) return (n + 2) / 3 * 4;
-	usz trailing = n % 3;
-	return n / 3 * 4 + (trailing * 4 + 2) / 3;
+	return encode_len(n, self.padding);
 }
 
-/**
- * Encode the content of src into dst, which must be properly sized.
- * @param src "The input to be encoded."
- * @param dst "The encoded input."
- * @return "The encoded size."
- * @return! Base64Error.DESTINATION_TOO_SMALL
- **/
+<*
+ Encode the content of src into dst, which must be properly sized.
+ @param src "The input to be encoded."
+ @param dst "The encoded input."
+ @return "The encoded size."
+ @return! Base64Error.DESTINATION_TOO_SMALL
+*>
 fn usz! Base64Encoder.encode(&self, char[] src, char[] dst)
 {
 	if (src.len == 0) return 0;
 	usz dn = self.encode_len(src.len);
 	if (dst.len < dn) return Base64Error.DESTINATION_TOO_SMALL?;
-	usz trailing = src.len % 3;
-	char[] src3 = src[:^trailing];
-
-	while (src3.len > 0)
-	{
-		uint group = (uint)src3[0] << 16 | (uint)src3[1] << 8 | (uint)src3[2];
-		dst[0] = self.alphabet[group >> 18 & MASK];
-		dst[1] = self.alphabet[group >> 12 & MASK];
-		dst[2] = self.alphabet[group >> 6 & MASK];
-		dst[3] = self.alphabet[group & MASK];
-		dst = dst[4..];
-		src3 = src3[3..];
-	}
-
-	// Encode the remaining bytes according to:
-	// https://www.rfc-editor.org/rfc/rfc4648#section-3.5
-	switch (trailing)
-	{
-		case 1:
-			uint group = (uint)src[^1] << 16;
-			dst[0] = self.alphabet[group >> 18 & MASK];
-			dst[1] = self.alphabet[group >> 12 & MASK];
-			if (self.padding >= 0)
-			{
-				char pad = (char)self.padding;
-				dst[2] = pad;
-				dst[3] = pad;
-			}
-		case 2:
-			uint group = (uint)src[^2] << 16 | (uint)src[^1] << 8;
-			dst[0] = self.alphabet[group >> 18 & MASK];
-			dst[1] = self.alphabet[group >> 12 & MASK];
-			dst[2] = self.alphabet[group >> 6 & MASK];
-			if (self.padding >= 0)
-			{
-				char pad = (char)self.padding;
-				dst[3] = pad;
-			}
-	}
-	return dn;
+	Base64Alphabet a = { .encoding = self.alphabet[:64] };
+	return encode_buffer(src, dst, self.padding, &a).len;
 }
 
-struct Base64Decoder
+struct Base64Decoder @deprecated
 {
-	int padding;
-	String alphabet;
-	char[256] reverse;
-	char invalid;
+	char padding;
+	Base64Alphabet encoding;
+	bool init_done;
 }
 
-/**
- * @param alphabet "The alphabet used for encoding."
- * @param padding "Set to a negative value to disable padding."
- * @require alphabet.len == 64
- * @require padding < 256
- * @return! Base64Error.DUPLICATE_IN_ALPHABET, Base64Error.PADDING_IN_ALPHABET
- **/
+import std;
+<*
+ @param alphabet "The alphabet used for encoding."
+ @param padding "Set to a negative value to disable padding."
+ @require alphabet.len == 64
+ @require padding < 256
+ @return! Base64Error.DUPLICATE_IN_ALPHABET, Base64Error.PADDING_IN_ALPHABET
+*>
 fn void! Base64Decoder.init(&self, String alphabet, int padding = '=')
 {
+	self.init_done = true;
 	check_alphabet(alphabet, padding)!;
-	*self = { .padding = padding, .alphabet = alphabet };
+	*self = { .padding = padding < 0 ? 0 : (char)padding, .encoding.encoding = alphabet[:64] };
+
+	self.encoding.reverse[..] = 0xFF;
 
-	bool[256] checked;
 	foreach (i, c : alphabet)
 	{
-		checked[c] = true;
-		self.reverse[c] = (char)i;
-	}
-	if (padding < 0)
-	{
-		self.invalid = 255;
-		return;
-	}
-	// Find a character for invalid neither in the alphabet nor equal to the padding.
-	char pad = (char)padding;
-	foreach (i, ok : checked)
-	{
-		if (!ok && (char)i != pad)
-		{
-			self.invalid = (char)i;
-			break;
-		}
+		self.encoding.reverse[c] = (char)i;
 	}
 }
 
-/**
- * Calculate the size of the decoded data.
- * @param n "Size of the input to be decoded."
- * @return "The size of the input once decoded."
- * @return! Base64Error.INVALID_PADDING
- **/
+<*
+ Calculate the size of the decoded data.
+ @param n "Size of the input to be decoded."
+ @return "The size of the input once decoded."
+ @return! Base64Error.INVALID_PADDING
+*>
 fn usz! Base64Decoder.decode_len(&self, usz n)
 {
-	usz dn = n / 4 * 3;
-	usz trailing = n % 4;
-	if (self.padding >= 0)
-	{
-		if (trailing != 0) return Base64Error.INVALID_PADDING?;
-		// source size is multiple of 4
-	}
-	else
-	{
-		if (trailing == 1) return Base64Error.INVALID_PADDING?;
-		dn += trailing * 3 / 4;
-	}
-	return dn;
+	return decode_len(n, self.padding) ?? Base64Error.INVALID_PADDING?;
 }
 
-/**
- * Decode the content of src into dst, which must be properly sized.
- * @param src "The input to be decoded."
- * @param dst "The decoded input."
- * @return "The decoded size."
- * @return! Base64Error.DESTINATION_TOO_SMALL, Base64Error.INVALID_PADDING, Base64Error.INVALID_CHARACTER
- **/
+<*
+ Decode the content of src into dst, which must be properly sized.
+ @param src "The input to be decoded."
+ @param dst "The decoded input."
+ @return "The decoded size."
+ @return! Base64Error.DESTINATION_TOO_SMALL, Base64Error.INVALID_PADDING, Base64Error.INVALID_CHARACTER
+*>
 fn usz! Base64Decoder.decode(&self, char[] src, char[] dst)
 {
 	if (src.len == 0) return 0;
 	usz dn = self.decode_len(src.len)!;
 	if (dst.len < dn) return Base64Error.DESTINATION_TOO_SMALL?;
-
-	usz trailing = src.len % 4;
-	char[] src4 = src;
-	switch
+	char[]! decoded = decode_buffer(src, dst, self.padding, &self.encoding);
+	if (catch err = decoded)
 	{
-		case self.padding < 0:
-			src4 = src[:^trailing];
+		case DecodingFailure.INVALID_PADDING:
+			return Base64Error.INVALID_PADDING?;
+		case DecodingFailure.INVALID_CHARACTER:
+			return Base64Error.INVALID_CHARACTER?;
 		default:
-			// If there is padding, keep the last 4 bytes for later.
-			// NB. src.len >= 4 as decode_len passed
-			trailing = 4;
-			char pad = (char)self.padding;
-			if (src[^1] == pad) src4 = src[:^4];
+			return err?;
 	}
-	while (src4.len > 0)
-	{
-		char c0 = self.reverse[src4[0]];
-		char c1 = self.reverse[src4[1]];
-		char c2 = self.reverse[src4[2]];
-		char c3 = self.reverse[src4[3]];
-		switch (self.invalid)
-		{
-			case c0:
-			case c1:
-			case c2:
-			case c3:
-				return Base64Error.INVALID_CHARACTER?;
-		}
-		uint group = (uint)c0 << 18 | (uint)c1 << 12 | (uint)c2 << 6 | (uint)c3;
-		dst[0] = (char)(group >> 16);
-		dst[1] = (char)(group >> 8);
-		dst[2] = (char)group;
-		dst = dst[3..];
-		src4 = src4[4..];
-	}
-
-	if (trailing == 0) return dn;
-
-	src = src[^trailing..];
-	char c0 = self.reverse[src[0]];
-	char c1 = self.reverse[src[1]];
-	if (c0 == self.invalid || c1 == self.invalid) return Base64Error.INVALID_PADDING?;
-	if (self.padding < 0)
-	{
-		switch (src.len)
-		{
-			case 2:
-				uint group = (uint)c0 << 18 | (uint)c1 << 12;
-				dst[0] = (char)(group >> 16);
-			case 3:
-				char c2 = self.reverse[src[2]];
-				if (c2 == self.invalid) return Base64Error.INVALID_CHARACTER?;
-				uint group = (uint)c0 << 18 | (uint)c1 << 12 | (uint)c2 << 6;
-				dst[0] = (char)(group >> 16);
-				dst[1] = (char)(group >> 8);
-		}
-	}
-	else
-	{
-		// Valid paddings are:
-		// 2: xx==
-		// 1: xxx=
-		char pad = (char)self.padding;
-		switch (pad)
-		{
-			case src[2]:
-				if (src[3] != pad) return Base64Error.INVALID_PADDING?;
-				uint group = (uint)c0 << 18 | (uint)c1 << 12;
-				dst[0] = (char)(group >> 16);
-				dn -= 2;
-			case src[3]:
-				char c2 = self.reverse[src[2]];
-				if (c2 == self.invalid) return Base64Error.INVALID_CHARACTER?;
-				uint group = (uint)c0 << 18 | (uint)c1 << 12 | (uint)c2 << 6;
-				dst[0] = (char)(group >> 16);
-				dst[1] = (char)(group >> 8);
-				dn -= 1;
-		}
-	}
-	return dn;
+	return decoded.len;
 }
 
 // Make sure that all bytes in the alphabet are unique and
@@ -285,4 +397,5 @@ fn void! check_alphabet(String alphabet, int padding) @local
 		if (checked[c]) return Base64Error.DUPLICATE_IN_ALPHABET?;
 		checked[c] = true;
 	}
-}
+}
+

lib/std/encoding/csv.c3

@@ -1,34 +1,73 @@
 module std::encoding::csv;
 import std::io;
 
+
 struct CsvReader
 {
 	InStream stream;
 	String separator;
 }
 
+struct CsvRow (Printable)
+{
+	String[] list;
+	String row;
+	Allocator allocator;
+}
+
+fn usz! CsvRow.to_format(&self, Formatter* f) @dynamic
+{
+	return f.printf("%s", self.list);
+}
+
+fn usz CsvRow.len(&self) @operator(len)
+{
+	return self.list.len;
+}
+
+<*
+ @require col < self.list.len
+*>
+fn String CsvRow.get_col(&self, usz col) @operator([])
+{
+	return self.list[col];
+}
+
 fn void CsvReader.init(&self, InStream stream, String separator = ",")
 {
 	self.stream = stream;
 	self.separator = separator;
 }
 
-fn String[]! CsvReader.read_new_row(self, Allocator allocator = allocator::heap())
+fn CsvRow! CsvReader.read_new_row(self)
 {
-	return self.read_new_row_with_allocator(allocator::temp()) @inline;
+	return self.read_row(allocator::heap()) @inline;
 }
 
-fn String[]! CsvReader.read_new_row_with_allocator(self, Allocator allocator = allocator::heap())
+<*
+ @param [&inout] allocator
+*>
+fn CsvRow! CsvReader.read_row(self, Allocator allocator)
 {
-	@pool(allocator)
-	{
-		return io::treadline(self.stream).split(self.separator, allocator: allocator);
-	};
+	String row = io::readline(self.stream, allocator: allocator)!;
+	defer catch allocator::free(allocator, row);
+	String[] list = row.split(self.separator, allocator: allocator);
+	return { list, row, allocator };
 }
 
-fn String[]! CsvReader.read_temp_row(self)
+fn CsvRow! CsvReader.read_temp_row(self)
 {
-	return self.read_new_row_with_allocator(allocator::temp()) @inline;
+	return self.read_row(allocator::temp()) @inline;
+}
+
+<*
+ @require self.allocator `Row already freed`
+*>
+fn void CsvRow.free(&self)
+{
+	allocator::free(self.allocator, self.list);
+	allocator::free(self.allocator, self.row);
+	self.allocator = null;
 }
 
 fn void! CsvReader.skip_row(self) @maydiscard
@@ -41,24 +80,19 @@ fn void! CsvReader.skip_row(self) @maydiscard
 
 macro CsvReader.@each_row(self, int rows = int.max; @body(String[] row))
 {
-	InputStream* stream = self.stream;
+	InStream stream = self.stream;
 	String sep = self.separator;
 	while (rows--)
 	{
 		@stack_mem(512; Allocator mem)
 		{
-			String[] parts;
-			@pool()
+			String! s = io::readline(stream, mem);
+			if (catch err = s)
 			{
-				String! s = stream.treadline();
-				if (catch err = s)
-				{
-					if (err == IoError.EOF) return;
-					return err?;
-				}
-				parts = s.split(sep, allocator: mem);
-			};
-			@body(parts);
+				if (err == IoError.EOF) return;
+				return err?;
+			}
+			@body(s.split(sep, allocator: mem));
 		};
 	}
 }

lib/std/encoding/encoding.c3

@@ -0,0 +1,7 @@
+module std::encoding;
+
+fault DecodingFailure
+{
+	INVALID_CHARACTER,
+	INVALID_PADDING,
+}

lib/std/encoding/hex.c3

@@ -0,0 +1,109 @@
+module std::encoding::hex;
+import std::encoding @norecurse;
+
+// The implementation is based on https://www.rfc-editor.org/rfc/rfc4648
+
+fn String encode_buffer(char[] code, char[] buffer)
+{
+	return (String)buffer[:encode_bytes(code, buffer)];
+}
+
+fn char[]! decode_buffer(char[] code, char[] buffer)
+{
+	return buffer[:decode_bytes(code, buffer)!];
+}
+
+fn String encode(char[] code, Allocator allocator)
+{
+	char[] data = allocator::alloc_array(allocator, char, encode_len(code.len));
+	return (String)data[:encode_bytes(code, data)];
+}
+
+fn char[]! decode(char[] code, Allocator allocator)
+{
+	char[] data = allocator::alloc_array(allocator, char, decode_len(code.len));
+	return data[:decode_bytes(code, data)!];
+}
+
+fn String encode_new(char[] code) @inline => encode(code, allocator::heap());
+fn String encode_temp(char[] code) @inline => encode(code, allocator::temp());
+fn char[]! decode_new(char[] code) @inline => decode(code, allocator::heap());
+fn char[]! decode_temp(char[] code) @inline => decode(code, allocator::temp());
+
+<*
+ Calculate the size of the encoded data.
+ @param n "Size of the input to be encoded."
+ @return "The size of the input once encoded."
+*>
+fn usz encode_len(usz n) => n * 2;
+
+<*
+ Encode the content of src into dst, which must be properly sized.
+ @param src "The input to be encoded."
+ @param dst "The encoded input."
+ @return "The encoded size."
+ @require dst.len >= encode_len(src.len) "Destination array is not large enough"
+*>
+fn usz encode_bytes(char[] src, char[] dst)
+{
+	usz j = 0;
+	foreach (v : src)
+	{
+		dst[j] = HEXALPHABET[v >> 4];
+		dst[j + 1] = HEXALPHABET[v & 0x0f];
+		j = j + 2;
+	}
+	return src.len * 2;
+}
+
+<*
+ Calculate the size of the decoded data.
+ @param n "Size of the input to be decoded."
+ @return "The size of the input once decoded."
+*>
+macro usz decode_len(usz n) => n / 2;
+
+<*
+ Decodes src into bytes. Returns the actual number of bytes written to dst.
+
+ Expects that src only contains hexadecimal characters and that src has even
+ length.
+
+ @param src "The input to be decoded."
+ @param dst "The decoded input."
+ @require src.len % 2 == 0 "src is not of even length"
+ @require dst.len >= decode_len(src.len) "Destination array is not large enough"
+ @return! DecodingFailure.INVALID_CHARACTER
+*>
+fn usz! decode_bytes(char[] src, char[] dst)
+{
+	usz i;
+	for (usz j = 1; j < src.len; j += 2)
+	{
+		char a = HEXREVERSE[src[j - 1]];
+		char b = HEXREVERSE[src[j]];
+		if (a > 0x0f || b > 0x0f) return DecodingFailure.INVALID_CHARACTER?;
+		dst[i] = (a << 4) | b;
+		i++;
+	}
+	return i;
+}
+
+const char[*] HEXALPHABET @private = "0123456789abcdef";
+const char[*] HEXREVERSE @private =
+x`ffffffffffffffffffffffffffffffff
+  ffffffffffffffffffffffffffffffff
+  ffffffffffffffffffffffffffffffff
+  00010203040506070809ffffffffffff
+  ff0a0b0c0d0e0fffffffffffffffffff
+  ffffffffffffffffffffffffffffffff
+  ff0a0b0c0d0e0fffffffffffffffffff
+  ffffffffffffffffffffffffffffffff
+  ffffffffffffffffffffffffffffffff
+  ffffffffffffffffffffffffffffffff
+  ffffffffffffffffffffffffffffffff
+  ffffffffffffffffffffffffffffffff
+  ffffffffffffffffffffffffffffffff
+  ffffffffffffffffffffffffffffffff
+  ffffffffffffffffffffffffffffffff
+  ffffffffffffffffffffffffffffffff`;

lib/std/hash/fnv32a.c3

@@ -8,7 +8,7 @@ distinct Fnv32a = uint;
 const FNV32A_START @private = 0x811c9dc5;
 const FNV32A_MUL @private = 0x01000193;
 
-macro void @update(uint* &h, char x) @private => *h = (*h * FNV32A_MUL) ^ x;
+macro void @update(&h, char x) @private => *h = (*h ^ ($typeof(*h))x) * FNV32A_MUL;
 
 fn void Fnv32a.init(&self)
 {
@@ -17,17 +17,17 @@ fn void Fnv32a.init(&self)
 
 fn void Fnv32a.update(&self, char[] data)
 {
-	uint h = (uint)*self;
+	Fnv32a h = *self;
 	foreach (char x : data)
 	{
 		@update(h, x);
 	}
-	*self = (Fnv32a)h;
+	*self = h;
 }
 
 macro void Fnv32a.update_char(&self, char c)
 {
-	@update(*self, x);
+	@update(*self, c);
 }
 
 fn uint encode(char[] data)
@@ -38,4 +38,4 @@ fn uint encode(char[] data)
 		@update(h, x);
 	}
 	return h;
-}
+}

lib/std/hash/fnv64a.c3

@@ -8,7 +8,7 @@ distinct Fnv64a = ulong;
 const FNV64A_START @private = 0xcbf29ce484222325;
 const FNV64A_MUL @private = 0x00000100000001b3;
 
-macro void @update(ulong* &h, char x) @private => *h = (*h * FNV64A_MUL) ^ x;
+macro void @update(&h, char x) @private => *h = (*h ^ ($typeof(*h))x) * FNV64A_MUL;
 
 fn void Fnv64a.init(&self)
 {
@@ -17,17 +17,17 @@ fn void Fnv64a.init(&self)
 
 fn void Fnv64a.update(&self, char[] data)
 {
-	ulong h = (ulong)*self;
+	Fnv64a h = *self;
 	foreach (char x : data)
 	{
 		@update(h, x);
 	}
-	*self = (Fnv64a)h;
+	*self = h;
 }
 
 macro void Fnv64a.update_char(&self, char c)
 {
-	@update(*self, x);
+	@update(*self, c);
 }
 
 fn ulong encode(char[] data)
@@ -38,4 +38,4 @@ fn ulong encode(char[] data)
 		@update(h, x);
 	}
 	return h;
-}
+}

lib/std/hash/hmac.c3

@@ -14,10 +14,10 @@ fn char[HASH_BYTES] hash(char[] key, char[] message)
 	return hmac.final();
 }
 
-/**
- * @require output.len > 0 "Output must be greater than zero"
- * @require output.len < int.max / HASH_BYTES "Output is too large"
- **/
+<*
+ @require output.len > 0 "Output must be greater than zero"
+ @require output.len < int.max / HASH_BYTES "Output is too large"
+*>
 fn void pbkdf2(char[] pw, char[] salt, uint iterations, char[] output)
 {
 	usz l = output.len / HASH_BYTES;

lib/std/hash/md5.c3

@@ -119,7 +119,7 @@ fn char* body(Md5* ctx, void* data, usz size)
 	char* ptr;
 	uint a, b, c, d;
 	uint saved_a, saved_b, saved_c, saved_d;
-    ptr = data;
+	ptr = data;
 	a = ctx.a;
 	b = ctx.b;
 	c = ctx.c;

lib/std/hash/sha1.c3

@@ -44,10 +44,10 @@ fn void Sha1.init(&self)
 	};
 }
 
-/**
- * @param [in] data
- * @require data.len <= uint.max
- **/
+<*
+ @param [in] data
+ @require data.len <= uint.max
+*>
 fn void Sha1.update(&self, char[] data)
 {
 	uint j = self.count[0];
@@ -154,10 +154,10 @@ macro @r4(&block, v, &wref, x, y, &z, i) @local
 	*wref = w.rotl(30);
 }
 
-/**
- * @param [&inout] state
- * @param [&in] buffer
- **/
+<*
+ @param [&inout] state
+ @param [&in] buffer
+*>
 fn void sha1_transform(uint* state, char* buffer) @local
 {
 	Long16 block;

lib/std/hash/sha256.c3

@@ -63,10 +63,10 @@ fn void Sha256.init(&self)
     };
 }
 
-/**
- * @param [in] data
- * @require data.len <= uint.max
- **/
+<*
+ @param [in] data
+ @require data.len <= uint.max
+*>
 fn void Sha256.update(&self, char[] data) {
     uint i = 0;
     uint len = data.len;
@@ -120,10 +120,10 @@ fn char[HASH_SIZE] Sha256.final(&self) {
     return hash;
 }
 
-/**
- * @param [&inout] state
- * @param [&in] buffer
- **/
+<*
+ @param [&inout] state
+ @param [&in] buffer
+*>
 fn void sha256_transform(uint* state, char* buffer) @local {
     uint a, b, c, d, e, f, g, h, t1, t2;
     uint[64] m;

lib/std/io/bits.c3

@@ -17,10 +17,10 @@ fn void BitReader.clear(&self) @inline
 	self.len = 0;
 }
 
-/**
- * @require nbits <= 8
- * @require self.len + nbits <= uint.sizeof * 8
- **/
+<*
+ @require nbits <= 8
+ @require self.len + nbits <= uint.sizeof * 8
+*>
 fn char! BitReader.read_bits(&self, uint nbits)
 {
 	uint bits = self.bits;
@@ -61,9 +61,9 @@ fn void! BitWriter.flush(&self)
 	self.len = 0;
 }
 
-/**
- * @require nbits <= 8
- **/
+<*
+ @require nbits <= 8
+*>
 fn void! BitWriter.write_bits(&self, uint bits, uint nbits)
 {
 	if (nbits == 0) return;

lib/std/io/file.c3

@@ -37,17 +37,17 @@ fn usz! get_size(String path)
 fn void! delete(String filename) => os::native_remove(filename) @inline;
 
 
-/**
- * @require self.file != null
- **/
+<*
+ @require self.file != null
+*>
 fn void! File.reopen(&self, String filename, String mode)
 {
 	self.file = os::native_freopen(self.file, filename, mode)!;
 }
 
-/**
- * @require self.file != null
- **/
+<*
+ @require self.file != null
+*>
 fn usz! File.seek(&self, isz offset, Seek seek_mode = Seek.SET) @dynamic
 {
 	os::native_fseek(self.file, offset, seek_mode)!;
@@ -57,9 +57,9 @@ fn usz! File.seek(&self, isz offset, Seek seek_mode = Seek.SET) @dynamic
 
 /*
 Implement later
-/**
- * @require self.file == null
- **/
+<*
+ @require self.file == null
+*>
 fn void! File.memopen(File* file, char[] data, String mode)
 {
 	@pool()
@@ -71,17 +71,17 @@ fn void! File.memopen(File* file, char[] data, String mode)
 */
 
 
-/**
- * @require self.file != null
- */
+<*
+ @require self.file != null
+*>
 fn void! File.write_byte(&self, char c) @dynamic
 {
 	return os::native_fputc(c, self.file);
 }
 
-/**
- * @param [&inout] self
- */
+<*
+ @param [&inout] self
+*>
 fn void! File.close(&self) @inline @dynamic
 {
 	if (self.file && libc::fclose(self.file))
@@ -105,26 +105,26 @@ fn void! File.close(&self) @inline @dynamic
 	self.file = null;
 }
 
-/**
- * @require self.file
- */
+<*
+ @require self.file
+*>
 fn bool File.eof(&self) @inline
 {
 	return libc::feof(self.file) != 0;
 }
 
-/**
- * @param [in] buffer
- */
+<*
+ @param [in] buffer
+*>
 fn usz! File.read(&self, char[] buffer) @dynamic
 {
 	return os::native_fread(self.file, buffer);
 }
 
-/**
- * @param [out] buffer
- * @require self.file `File must be initialized`
- */
+<*
+ @param [out] buffer
+ @require self.file `File must be initialized`
+*>
 fn usz! File.write(&self, char[] buffer) @dynamic
 {
 	return os::native_fwrite(self.file, buffer);
@@ -138,13 +138,13 @@ fn char! File.read_byte(&self) @dynamic
 	return (char)c;
 }
 
-/**
- * Load up to buffer.len characters. Returns IoError.OVERFLOW if the file is longer
- * than the buffer.
- *
- * @param filename "The path to the file to read"
- * @param [in] buffer "The buffer to read to"
- **/
+<*
+ Load up to buffer.len characters. Returns IoError.OVERFLOW if the file is longer
+ than the buffer.
+
+ @param filename "The path to the file to read"
+ @param [in] buffer "The buffer to read to"
+*>
 fn char[]! load_buffer(String filename, char[] buffer)
 {
 	File file = open(filename, "rb")!;
@@ -182,9 +182,20 @@ fn char[]! load_temp(String filename)
 	return load_new(filename, allocator::temp());
 }
 
-/**
- * @require self.file `File must be initialized`
- */
+fn void! save(String filename, char[] data)
+{
+	File file = open(filename, "wb")!;
+	defer (void)file.close();
+	while (data.len)
+	{
+		usz written = file.write(data)!;
+		data = data[written..];
+	}
+}
+
+<*
+ @require self.file `File must be initialized`
+*>
 fn void! File.flush(&self) @dynamic
 {
 	libc::fflush(self.file);

lib/std/io/formatter.c3

@@ -23,6 +23,46 @@ fault PrintFault
 def OutputFn = fn void!(void* buffer, char c);
 def FloatType = double;
 
+
+macro bool is_struct_with_default_print($Type)
+{
+	return $Type.kindof == STRUCT
+		&&& !$defined($Type.to_format)
+		&&& !$defined($Type.to_new_string)
+		&&& !$defined($Type.to_string);
+}
+
+<*
+ Introspect a struct and print it to a formatter
+
+ @require @typekind(value) == STRUCT `This macro is only valid on macros`
+*>
+macro usz! struct_to_format(value, Formatter* f, bool $force_dump)
+{
+    var $Type = $typeof(value);
+    usz total = f.print("{ ")!;
+    $foreach ($i, $member : $Type.membersof)
+        $if $i > 0:
+            total += f.print(", ")!;
+        $endif
+        $if $member.nameof != "":
+            total += f.printf("%s: ", $member.nameof)!;
+		$endif
+		$if ($force_dump &&& $member.typeid.kindof == STRUCT) |||
+			is_struct_with_default_print($typefrom($member.typeid)):
+			total += struct_to_format($member.get(value), f, $force_dump)!;
+		$else
+			total += f.printf("%s", $member.get(value))!;
+		$endif
+	$endforeach
+	return total + f.print(" }");
+}
+
+fn usz! ReflectedParam.to_format(&self, Formatter* f) @dynamic
+{
+	return f.printf("[Parameter '%s']", self.name);
+}
+
 fn usz! Formatter.printf(&self, String format, args...)
 {
 	return self.vprintf(format, args) @inline;
@@ -159,12 +199,6 @@ fn usz! Formatter.out_str(&self, any arg) @private
 			assert(i < arg.type.names.len, "Illegal enum value found, numerical value was %d.", i);
 			return self.out_substr(arg.type.names[i]);
 		case STRUCT:
-			if (arg.type == ReflectedParam.typeid)
-			{
-				ReflectedParam* param = arg.ptr;
-				return self.out_substr("[Parameter '")
-					+  self.out_substr(param.name) + self.out_substr("']");
-			}
 			return self.out_substr("<struct>");
 		case UNION:
 			return self.out_substr("<union>");
@@ -173,6 +207,10 @@ fn usz! Formatter.out_str(&self, any arg) @private
 		case FUNC:
 			return self.out_substr("<function>");
 		case DISTINCT:
+			if (arg.type == String.typeid)
+			{
+				return self.out_substr(*(String*)arg);
+			}
 			if (arg.type == ZString.typeid)
 			{
 				return self.out_substr(*(ZString*)arg ? ((ZString*)arg).str_view() : "(null)");
@@ -255,10 +293,6 @@ fn usz! Formatter.out_str(&self, any arg) @private
 		case SLICE:
 			// this is SomeType[] so grab the "SomeType"
 			typeid inner = arg.type.inner;
-			if (inner == char.typeid)
-			{
-				return self.out_substr(*(String*)arg);
-			}
 			if (inner == void.typeid) inner = char.typeid;
 			PrintFlags flags = self.flags;
 			uint width = self.width;
@@ -310,12 +344,12 @@ macro usz! @wrap_bad(Formatter* f, #action)
 	if (catch err = len)
 	{
 		case PrintFault.BUFFER_EXCEEDED:
-        case PrintFault.INTERNAL_BUFFER_EXCEEDED:
-            return f.first_err(err)?;
-        default:
-            err = f.first_err(PrintFault.INVALID_ARGUMENT);
-            f.out_substr("<INVALID>")!;
-            return err?;
+		case PrintFault.INTERNAL_BUFFER_EXCEEDED:
+			return f.first_err(err)?;
+		default:
+			err = f.first_err(PrintFault.INVALID_ARGUMENT);
+			f.out_substr("<INVALID>")!;
+			return err?;
 	}
 	return len;
 }
@@ -496,4 +530,4 @@ fn usz! Formatter.print(&self, String str)
 	}
 	foreach (c : str) self.out(c)!;
 	return self.idx;
-}
+}

lib/std/io/formatter_private.c3

@@ -119,14 +119,14 @@ fn FloatType! float_from_any(any arg) @private
 }
 
 
-/**
- * Read a simple integer value, typically for formatting.
- *
- * @param [inout] len_ptr "the length remaining."
- * @param [in] buf "the buf to read from."
- * @param maxlen "the maximum len that can be read."
- * @return "The result of the atoi."
- **/
+<*
+ Read a simple integer value, typically for formatting.
+
+ @param [inout] len_ptr "the length remaining."
+ @param [in] buf "the buf to read from."
+ @param maxlen "the maximum len that can be read."
+ @return "The result of the atoi."
+*>
 fn uint simple_atoi(char* buf, usz maxlen, usz* len_ptr) @inline @private
 {
 	uint i = 0;
@@ -214,7 +214,7 @@ fn usz! Formatter.floatformat(&self, FloatFormatting formatting, double y) @priv
 		// Add padding
 		if (!self.flags.left) len += self.pad(' ', self.width, 3 + pl)!;
 		String s = self.flags.uppercase ? "INF" : "inf";
-		if (y != y) s = self.flags.uppercase ? "NAN" : "nan";
+		if (math::is_nan(y)) s = self.flags.uppercase ? "NAN" : "nan";
 		len += s.len;
 		if (pl) len += self.out(is_neg ? '-' : '+')!;
 		len += self.out_chars(s)!;
@@ -642,7 +642,7 @@ fn usz! Formatter.out_reverse(&self, char[] buf) @private
 	// pad spaces up to given width
 	if (!self.flags.zeropad && !self.flags.left)
 	{
-    	n += self.pad(' ', self.width, len)!;
+		n += self.pad(' ', self.width, len)!;
 	}
 	// reverse string
 	while (len) n += self.out(buf[--len])!;
@@ -661,7 +661,7 @@ fn int! printf_parse_format_field(
 	if (c.is_digit()) return simple_atoi(format_ptr, format_len, index_ptr);
 	if (c != '*') return 0;
 	usz len = ++(*index_ptr);
-    if (len >= format_len) return FormattingFault.BAD_FORMAT?;
+	if (len >= format_len) return FormattingFault.BAD_FORMAT?;
 	if (*args_index_ptr >= args_len) return FormattingFault.BAD_FORMAT?;
 	any val = args_ptr[(*args_index_ptr)++];
 	if (!val.type.kindof.is_int()) return FormattingFault.BAD_FORMAT?;

lib/std/io/io.c3

@@ -45,16 +45,16 @@ fault IoError
 }
 
 
-/**
- * Read from a stream (default is stdin) to the next "\n"
- * or to the end of the stream, whatever comes first.
- * "\r" will be filtered from the String.
- *
- * @param stream `The stream to read from.`
- * @require @is_instream(stream) `The stream must implement InStream.`
- * @param [inout] allocator `the allocator to use.`
- * @return `The string containing the data read.`
- **/
+<*
+ Read from a stream (default is stdin) to the next "\n"
+ or to the end of the stream, whatever comes first.
+ "\r" will be filtered from the String.
+
+ @param stream `The stream to read from.`
+ @require @is_instream(stream) `The stream must implement InStream.`
+ @param [inout] allocator `the allocator to use.`
+ @return `The string containing the data read.`
+*>
 macro String! readline(stream = io::stdin(), Allocator allocator = allocator::heap())
 {
 	bool $is_stream = @typeis(stream, InStream);
@@ -65,52 +65,52 @@ macro String! readline(stream = io::stdin(), Allocator allocator = allocator::he
 		char val = stream.read_byte()!;
 	$endif
 
-    if (val == '\n') return "";
-    @pool(allocator)
-    {
-        DString str = dstring::temp_with_capacity(256);
-    	if (val != '\r') str.append(val);
-    	while (1)
-    	{
-    	    $if $is_stream:
-    	        char! c = func((void*)stream);
-    	    $else
-    	        char! c = stream.read_byte();
-    	    $endif
-    		if (catch err = c)
-    		{
-    			if (err == IoError.EOF) break;
-    			return err?;
-    		}
-    		if (c == '\r') continue;
-    		if (c == '\n') break;
-    		str.append_char(c);
-    	}
-    	return str.copy_str(allocator);
-    };
+	if (val == '\n') return "";
+	@pool(allocator)
+	{
+		DString str = dstring::temp_with_capacity(256);
+		if (val != '\r') str.append(val);
+		while (1)
+		{
+			$if $is_stream:
+				char! c = func((void*)stream);
+			$else
+				char! c = stream.read_byte();
+			$endif
+			if (catch err = c)
+			{
+				if (err == IoError.EOF) break;
+				return err?;
+			}
+			if (c == '\r') continue;
+			if (c == '\n') break;
+			str.append_char(c);
+		}
+		return str.copy_str(allocator);
+	};
 }
 
-/**
- * Reads a string, see `readline`, except the it is allocated
- * on the temporary allocator and does not need to be freed.
- *
- * @param stream `The stream to read from.`
- * @require @is_instream(stream) `The stream must implement InStream.`
- * @return `The temporary string containing the data read.`
- **/
+<*
+ Reads a string, see `readline`, except the it is allocated
+ on the temporary allocator and does not need to be freed.
+
+ @param stream `The stream to read from.`
+ @require @is_instream(stream) `The stream must implement InStream.`
+ @return `The temporary string containing the data read.`
+*>
 macro String! treadline(stream = io::stdin())
 {
 	return readline(stream, allocator::temp()) @inline;
 }
 
-/**
- * Print a value to a stream.
- *
- * @param out `the stream to print to`
- * @param x `the value to print`
- * @require @is_outstream(out) `The output must implement OutStream.`
- * @return `the number of bytes printed.`
- */
+<*
+ Print a value to a stream.
+
+ @param out `the stream to print to`
+ @param x `the value to print`
+ @require @is_outstream(out) `The output must implement OutStream.`
+ @return `the number of bytes printed.`
+*>
 macro usz! fprint(out, x)
 {
 	var $Type = $typeof(x);
@@ -122,19 +122,25 @@ macro usz! fprint(out, x)
 			$if $assignable(x, String):
 				return out.write((String)x);
 			$else
-				return fprintf(out, "%s", x);
+				$if is_struct_with_default_print($Type):
+					Formatter formatter;
+                    formatter.init(&out_putstream_fn, &&(OutStream)out);
+                    return struct_to_format(x, &formatter, false);
+				$else
+					return fprintf(out, "%s", x);
+				$endif
 			$endif
 	$endswitch
 }
 
-/**
- * Prints using a 'printf'-style formatting string.
- * See `printf` for details on formatting.
- *
- * @param [inout] out `The OutStream to print to`
- * @param [in] format `The printf-style format string`
- * @return `the number of characters printed`
- **/
+<*
+ Prints using a 'printf'-style formatting string.
+ See `printf` for details on formatting.
+
+ @param [inout] out `The OutStream to print to`
+ @param [in] format `The printf-style format string`
+ @return `the number of characters printed`
+*>
 fn usz! fprintf(OutStream out, String format, args...)
 {
 	Formatter formatter;
@@ -142,14 +148,14 @@ fn usz! fprintf(OutStream out, String format, args...)
 	return formatter.vprintf(format, args);
 }
 
-/**
- * Prints using a 'printf'-style formatting string,
- * appending '\n' at the end. See `printf`.
- *
- * @param [inout] out `The OutStream to print to`
- * @param [in] format `The printf-style format string`
- * @return `the number of characters printed`
- **/
+<*
+ Prints using a 'printf'-style formatting string,
+ appending '\n' at the end. See `printf`.
+
+ @param [inout] out `The OutStream to print to`
+ @param [in] format `The printf-style format string`
+ @return `the number of characters printed`
+*>
 fn usz! fprintfn(OutStream out, String format, args...) @maydiscard
 {
 	Formatter formatter;
@@ -160,9 +166,9 @@ fn usz! fprintfn(OutStream out, String format, args...) @maydiscard
 	return len + 1;
 }
 
-/**
- * @require @is_outstream(out) "The output must implement OutStream"
- */
+<*
+ @require @is_outstream(out) "The output must implement OutStream"
+*>
 macro usz! fprintn(out, x = "")
 {
 	usz len = fprint(out, x)!;
@@ -176,37 +182,37 @@ macro usz! fprintn(out, x = "")
 	return len + 1;
 }
 
-/**
- * Print any value to stdout.
- **/
+<*
+ Print any value to stdout.
+*>
 macro void print(x)
 {
 	(void)fprint(io::stdout(), x);
 }
 
-/**
- * Print any value to stdout, appending an '\n’ after.
- *
- * @param x "The value to print"
- **/
+<*
+ Print any value to stdout, appending an '\n’ after.
+
+ @param x "The value to print"
+*>
 macro void printn(x = "")
 {
 	(void)fprintn(io::stdout(), x);
 }
 
-/**
- * Print any value to stderr.
- **/
+<*
+ Print any value to stderr.
+*>
 macro void eprint(x)
 {
 	(void)fprint(io::stderr(), x);
 }
 
-/**
- * Print any value to stderr, appending an '\n’ after.
- *
- * @param x "The value to print"
- **/
+<*
+ Print any value to stderr, appending an '\n’ after.
+
+ @param x "The value to print"
+*>
 macro void eprintn(x)
 {
 	(void)fprintn(io::stderr(), x);
@@ -224,20 +230,20 @@ fn void! out_putchar_fn(void* data @unused, char c) @private
 	libc::putchar(c);
 }
 
-/**
- * Prints using a 'printf'-style formatting string.
- * To print integer numbers, use "%d" or "%x"/"%X,
- * the latter gives the hexadecimal representation.
- *
- * All types can be printed using "%s" which gives
- * the default representation of the value.
- *
- * To create a custom output for a type, implement
- * the Printable interface.
- *
- * @param [in] format `The printf-style format string`
- * @return `the number of characters printed`
- **/
+<*
+ Prints using a 'printf'-style formatting string.
+ To print integer numbers, use "%d" or "%x"/"%X,
+ the latter gives the hexadecimal representation.
+
+ All types can be printed using "%s" which gives
+ the default representation of the value.
+
+ To create a custom output for a type, implement
+ the Printable interface.
+
+ @param [in] format `The printf-style format string`
+ @return `the number of characters printed`
+*>
 fn usz! printf(String format, args...) @maydiscard
 {
 	Formatter formatter;
@@ -245,13 +251,13 @@ fn usz! printf(String format, args...) @maydiscard
 	return formatter.vprintf(format, args);
 }
 
-/**
- * Prints using a 'printf'-style formatting string,
- * appending '\n' at the end. See `printf`.
- *
- * @param [in] format `The printf-style format string`
- * @return `the number of characters printed`
- **/
+<*
+ Prints using a 'printf'-style formatting string,
+ appending '\n' at the end. See `printf`.
+
+ @param [in] format `The printf-style format string`
+ @return `the number of characters printed`
+*>
 fn usz! printfn(String format, args...) @maydiscard
 {
 	Formatter formatter;
@@ -262,13 +268,13 @@ fn usz! printfn(String format, args...) @maydiscard
 	return len + 1;
 }
 
-/**
- * Prints using a 'printf'-style formatting string
- * to stderr.
- *
- * @param [in] format `The printf-style format string`
- * @return `the number of characters printed`
- **/
+<*
+ Prints using a 'printf'-style formatting string
+ to stderr.
+
+ @param [in] format `The printf-style format string`
+ @return `the number of characters printed`
+*>
 fn usz! eprintf(String format, args...) @maydiscard
 {
 	Formatter formatter;
@@ -278,13 +284,13 @@ fn usz! eprintf(String format, args...) @maydiscard
 }
 
 
-/**
- * Prints using a 'printf'-style formatting string,
- * to stderr appending '\n' at the end. See `printf`.
- *
- * @param [in] format `The printf-style format string`
- * @return `the number of characters printed`
- **/
+<*
+ Prints using a 'printf'-style formatting string,
+ to stderr appending '\n' at the end. See `printf`.
+
+ @param [in] format `The printf-style format string`
+ @return `the number of characters printed`
+*>
 fn usz! eprintfn(String format, args...) @maydiscard
 {
 	Formatter formatter;
@@ -296,14 +302,14 @@ fn usz! eprintfn(String format, args...) @maydiscard
 	return len + 1;
 }
 
-/**
- * Prints using a 'printf'-style formatting string,
- * to a string buffer. See `printf`.
- *
- * @param [inout] buffer `The buffer to print to`
- * @param [in] format `The printf-style format string`
- * @return `a slice formed from the "buffer" with the resulting length.`
- **/
+<*
+ Prints using a 'printf'-style formatting string,
+ to a string buffer. See `printf`.
+
+ @param [inout] buffer `The buffer to print to`
+ @param [in] format `The printf-style format string`
+ @return `a slice formed from the "buffer" with the resulting length.`
+*>
 fn char[]! bprintf(char[] buffer, String format, args...) @maydiscard
 {
 	Formatter formatter;
@@ -332,19 +338,19 @@ struct BufferData @private
 module std::io @if (env::LIBC);
 import libc;
 
-/**
- * Libc `putchar`, prints a single character to stdout.
- **/
+<*
+ Libc `putchar`, prints a single character to stdout.
+*>
 fn void putchar(char c) @inline
 {
 	libc::putchar(c);
 }
 
-/**
- * Get standard out.
- *
- * @return `stdout as a File`
- **/
+<*
+ Get standard out.
+
+ @return `stdout as a File`
+*>
 fn File* stdout()
 {
 	static File file;
@@ -352,11 +358,11 @@ fn File* stdout()
 	return &file;
 }
 
-/**
- * Get standard err.
- *
- * @return `stderr as a File`
- **/
+<*
+ Get standard err.
+
+ @return `stderr as a File`
+*>
 fn File* stderr()
 {
 	static File file;
@@ -364,11 +370,11 @@ fn File* stderr()
 	return &file;
 }
 
-/**
- * Get standard in.
- *
- * @return `stdin as a File`
- **/
+<*
+ Get standard in.
+
+ @return `stdin as a File`
+*>
 fn File* stdin()
 {
 	static File file;
@@ -402,10 +408,3 @@ fn File* stdin()
 	return &stdin_file;
 }
 
-/**
- * Wrap bytes for reading using io functions.
- **/
-fn ByteReader wrap_bytes(char[] bytes)
-{
-	return { bytes, 0 };
-}

lib/std/io/os/file_libc.c3

@@ -1,10 +1,10 @@
 module std::io::os @if(env::LIBC);
 import libc;
 
-/**
- * @require mode.len > 0
- * @require filename.len > 0
- **/
+<*
+ @require mode.len > 0
+ @require filename.len > 0
+*>
 fn void*! native_fopen(String filename, String mode) @inline
 {
 	@pool()
@@ -41,10 +41,10 @@ fn void! native_remove(String filename)
 	};
 }
 
-/**
- * @require mode.len > 0
- * @require filename.len > 0
- **/
+<*
+ @require mode.len > 0
+ @require filename.len > 0
+*>
 fn void*! native_freopen(void* file, String filename, String mode) @inline
 {
 	@pool()

lib/std/io/os/file_nolibc.c3

@@ -21,31 +21,31 @@ FreadFn native_fread_fn @weak @if(!$defined(native_fread_fn));
 RemoveFn native_remove_fn @weak @if(!$defined(native_remove_fn));
 FputcFn native_fputc_fn @weak @if(!$defined(native_fputc_fn));
 
-/**
- * @require mode.len > 0
- * @require filename.len > 0
- **/
+<*
+ @require mode.len > 0
+ @require filename.len > 0
+*>
 fn void*! native_fopen(String filename, String mode) @inline
 {
 	if (native_fopen_fn) return native_fopen_fn(filename, mode);
 	return IoError.UNSUPPORTED_OPERATION?;
 }
 
-/**
- * Delete a file.
- *
- * @require filename.len > 0
- **/
+<*
+ Delete a file.
+
+ @require filename.len > 0
+*>
 fn void! native_remove(String filename) @inline
 {
 	if (native_remove_fn) return native_remove_fn(filename);
 	return IoError.UNSUPPORTED_OPERATION?;
 }
 
-/**
- * @require mode.len > 0
- * @require filename.len > 0
- **/
+<*
+ @require mode.len > 0
+ @require filename.len > 0
+*>
 fn void*! native_freopen(void* file, String filename, String mode) @inline
 {
 	if (native_freopen_fn) return native_freopen_fn(file, filename, mode);

lib/std/io/os/rmtree.c3

@@ -1,9 +1,9 @@
 module std::io::os @if(env::POSIX);
 import std::io, std::os, libc;
 
-/**
- * @require dir.str_view()
- **/
+<*
+ @require dir.str_view()
+*>
 fn void! native_rmtree(Path dir)
 {
 	DIRPtr directory = posix::opendir(dir.as_zstr());

lib/std/io/path.c3

@@ -96,6 +96,13 @@ enum MkdirPermissions
 	USER_AND_ADMIN
 }
 
+<*
+ Create a directory on a given path, optionally recursive.
+
+ @param path `The path to create`
+ @param recursive `If directories in between should be created if they're missing, defaults to false`
+ @param permissions `The permissions to set on the directory`
+*>
 fn bool! mkdir(Path path, bool recursive = false, MkdirPermissions permissions = NORMAL)
 {
 	if (!path.path_string.len) return PathResult.INVALID_PATH?;
@@ -111,12 +118,22 @@ fn bool! mkdir(Path path, bool recursive = false, MkdirPermissions permissions =
 	return os::native_mkdir(path, permissions);
 }
 
+<*
+ Tries to delete directory, which must be empty.
+
+ @param path `The path to delete`
+ @return `true if there was a directory to delete, false otherwise`
+ @return! PathResult.INVALID_PATH `if the path was invalid`
+*>
 fn bool! rmdir(Path path)
 {
 	if (!path.path_string.len) return PathResult.INVALID_PATH?;
 	return os::native_rmdir(path);
 }
 
+<*
+ Like [rmdir] but deletes a directory even if it contains items.
+*>
 fn void! rmtree(Path path)
 {
 	if (!path.path_string.len) return PathResult.INVALID_PATH?;
@@ -127,11 +144,21 @@ fn void! rmtree(Path path)
 	$endif
 }
 
+<*
+ Creates a new path.
+
+ @return! PathResult.INVALID_PATH `if the path was invalid`
+*>
 fn Path! new(String path, Allocator allocator = allocator::heap(), PathEnv path_env = DEFAULT_PATH_ENV)
 {
 	return { normalize(path.copy(allocator), path_env), path_env };
 }
 
+<*
+ Creates a new path using the temp allocator.
+
+ @return! PathResult.INVALID_PATH `if the path was invalid`
+*>
 fn Path! temp_new(String path, PathEnv path_env = DEFAULT_PATH_ENV)
 {
 	return new(path, allocator::temp(), path_env);
@@ -165,11 +192,11 @@ fn Path! Path.append(self, String filename, Allocator allocator = allocator::hea
 	return self.new_append(filename, allocator) @inline;
 }
 
-/**
- * Append the string to the current path.
- *
- * @param [in] filename
- **/
+<*
+ Append the string to the current path.
+
+ @param [in] filename
+*>
 fn Path! Path.new_append(self, String filename, Allocator allocator = allocator::heap())
 {
 	if (!self.path_string.len) return new(filename, allocator, self.env)!;
@@ -226,9 +253,9 @@ fn Path! Path.absolute(self, Allocator allocator = allocator::heap()) @deprecate
 	return self.new_absolute(allocator) @inline;
 }
 
-/**
- * @require self.env == DEFAULT_PATH_ENV : "This method is only available on native paths"
- **/
+<*
+ @require self.env == DEFAULT_PATH_ENV : "This method is only available on native paths"
+*>
 fn Path! Path.new_absolute(self, Allocator allocator = allocator::heap())
 {
 	String path_str = self.str_view();
@@ -283,14 +310,14 @@ fn String Path.dirname(self)
 	return path_str[:basename_start - 1];
 }
 
-/**
- * Test if the path has the given extension, so given the path /foo/bar.c3
- * this would be true matching the extension "c3"
- *
- * @param [in] extension `The extension name (not including the leading '.')`
- * @require extension.len > 0 : `The extension cannot be empty`
- * @return `true if the extension matches`
- **/
+<*
+ Test if the path has the given extension, so given the path /foo/bar.c3
+ this would be true matching the extension "c3"
+
+ @param [in] extension `The extension name (not including the leading '.')`
+ @require extension.len > 0 : `The extension cannot be empty`
+ @return `true if the extension matches`
+*>
 fn bool Path.has_extension(self, String extension)
 {
 	String basename = self.basename();
@@ -352,6 +379,13 @@ fn usz! volume_name_len(String path, PathEnv path_env) @local
 	}
 }
 
+<*
+ Get the path of the parent. This does not allocate, but returns a slice
+ of the path itself.
+
+ @return `The parent of the path as a non-allocated path`
+ @return! PathResult.NO_PARENT `if this path does not have a parent`
+*>
 fn Path! Path.parent(self)
 {
 	if (self.path_string.len == 1 && is_separator(self.path_string[0], self.env)) return PathResult.NO_PARENT?;
@@ -509,11 +543,11 @@ fn String Path.root_directory(self)
 
 def PathWalker = fn bool! (Path, bool is_dir, void*);
 
-/*
- * Walk the path recursively. PathWalker is run on every file and
- * directory found. Return true to abort the walk.
- * @require self.env == DEFAULT_PATH_ENV : "This method is only available on native paths"
- */
+<*
+ Walk the path recursively. PathWalker is run on every file and
+ directory found. Return true to abort the walk.
+ @require self.env == DEFAULT_PATH_ENV : "This method is only available on native paths"
+*>
 fn bool! Path.walk(self, PathWalker w, void* data)
 {
 	const PATH_MAX = 512;

lib/std/io/stream.c3

@@ -47,28 +47,28 @@ macro bool @is_outstream(#expr)
 	return $assignable(#expr, OutStream);
 }
 
-/**
- * @param [&out] ref
- * @require @is_instream(stream)
- **/
+<*
+ @param [&out] ref
+ @require @is_instream(stream)
+*>
 macro usz! read_any(stream, any ref)
 {
 	return read_all(stream, ((char*)ref)[:ref.type.sizeof]);
 }
 
-/**
- * @param [&in] ref "the object to write."
- * @require @is_outstream(stream)
- * @ensure return == ref.type.sizeof
- */
+<*
+ @param [&in] ref "the object to write."
+ @require @is_outstream(stream)
+ @ensure return == ref.type.sizeof
+*>
 macro usz! write_any(stream, any ref)
 {
 	return write_all(stream, ((char*)ref)[:ref.type.sizeof]);
 }
 
-/**
- * @require @is_instream(stream)
- */
+<*
+ @require @is_instream(stream)
+*>
 macro usz! read_all(stream, char[] buffer)
 {
 	if (buffer.len == 0) return 0;
@@ -77,9 +77,9 @@ macro usz! read_all(stream, char[] buffer)
 	return n;
 }
 
-/**
- * @require @is_instream(stream)
- */
+<*
+ @require @is_instream(stream)
+*>
 macro char[]! read_new_fully(stream, Allocator allocator = allocator::heap())
 {
 	usz len = available(stream)!;
@@ -93,9 +93,9 @@ macro char[]! read_new_fully(stream, Allocator allocator = allocator::heap())
 	return data[:len];
 }
 
-/**
- * @require @is_outstream(stream)
- */
+<*
+ @require @is_outstream(stream)
+*>
 macro usz! write_all(stream, char[] buffer)
 {
 	if (buffer.len == 0) return 0;
@@ -186,10 +186,10 @@ macro usz! copy_through_buffer(InStream in, OutStream dst, char[] buffer) @local
 
 const char[*] MAX_VARS @private = { [2] = 3, [4] = 5, [8] = 10 };
 
-/**
- * @require @is_instream(stream)
- * @require @typekind(x_ptr) == POINTER && $typeof(x_ptr).inner.kindof.is_int()
- **/
+<*
+ @require @is_instream(stream)
+ @require @typekind(x_ptr) == POINTER && $typeof(x_ptr).inner.kindof.is_int()
+*>
 macro usz! read_varint(stream, x_ptr)
 {
 	var $Type = $typefrom($typeof(x_ptr).inner);
@@ -223,10 +223,10 @@ macro usz! read_varint(stream, x_ptr)
 	}
 	return MathError.OVERFLOW?;
 }
-/**
- * @require @is_outstream(stream)
- * @require @typekind(x).is_int()
- **/
+<*
+ @require @is_outstream(stream)
+ @require @typekind(x).is_int()
+*>
 macro usz! write_varint(stream, x)
 {
 	var $Type = $typeof(x);
@@ -241,4 +241,205 @@ macro usz! write_varint(stream, x)
 	}
 	buffer[i] = (char)x;
 	return write_all(stream, buffer[:i + 1]);
+}
+
+<*
+ @require @is_instream(stream)
+*>
+macro ushort! read_be_ushort(stream)
+{
+	char hi_byte = stream.read_byte()!;
+	char lo_byte = stream.read_byte()!;
+	return (ushort)(hi_byte << 8 | lo_byte);
+}
+
+<*
+ @require @is_instream(stream)
+*>
+macro short! read_be_short(stream)
+{
+	return read_be_ushort(stream);
+}
+
+<*
+ @require @is_outstream(stream)
+*>
+macro void! write_be_short(stream, ushort s)
+{
+	stream.write_byte((char)(s >> 8))!;
+	stream.write_byte((char)s)!;
+}
+
+<*
+ @require @is_instream(stream)
+*>
+macro uint! read_be_uint(stream)
+{
+	uint val = stream.read_byte()! << 24;
+	val += stream.read_byte()! << 16;
+	val += stream.read_byte()! << 8;
+	return val + stream.read_byte()!;
+}
+
+<*
+ @require @is_instream(stream)
+*>
+macro int! read_be_int(stream)
+{
+	return read_be_uint(stream);
+}
+
+<*
+ @require @is_outstream(stream)
+*>
+macro void! write_be_int(stream, uint s)
+{
+	stream.write_byte((char)(s >> 24))!;
+	stream.write_byte((char)(s >> 16))!;
+	stream.write_byte((char)(s >> 8))!;
+	stream.write_byte((char)s)!;
+}
+
+<*
+ @require @is_instream(stream)
+*>
+macro ulong! read_be_ulong(stream)
+{
+	ulong val = (ulong)stream.read_byte()! << 56;
+	val += (ulong)stream.read_byte()! << 48;
+	val += (ulong)stream.read_byte()! << 40;
+	val += (ulong)stream.read_byte()! << 32;
+	val += (ulong)stream.read_byte()! << 24;
+	val += (ulong)stream.read_byte()! << 16;
+	val += (ulong)stream.read_byte()! << 8;
+	return val + stream.read_byte()!;
+}
+
+<*
+ @require @is_instream(stream)
+*>
+macro long! read_be_long(stream)
+{
+	return read_be_ulong(stream);
+}
+
+<*
+ @require @is_outstream(stream)
+*>
+macro void! write_be_long(stream, ulong s)
+{
+	stream.write_byte((char)(s >> 56))!;
+	stream.write_byte((char)(s >> 48))!;
+	stream.write_byte((char)(s >> 40))!;
+	stream.write_byte((char)(s >> 32))!;
+	stream.write_byte((char)(s >> 24))!;
+	stream.write_byte((char)(s >> 16))!;
+	stream.write_byte((char)(s >> 8))!;
+	stream.write_byte((char)s)!;
+}
+
+<*
+ @require @is_instream(stream)
+*>
+macro uint128! read_be_uint128(stream)
+{
+	uint128 val = (uint128)stream.read_byte()! << 120;
+	val += (uint128)stream.read_byte()! << 112;
+	val += (uint128)stream.read_byte()! << 104;
+	val += (uint128)stream.read_byte()! << 96;
+	val += (uint128)stream.read_byte()! << 88;
+	val += (uint128)stream.read_byte()! << 80;
+	val += (uint128)stream.read_byte()! << 72;
+	val += (uint128)stream.read_byte()! << 64;
+	val += (uint128)stream.read_byte()! << 56;
+	val += (uint128)stream.read_byte()! << 48;
+	val += (uint128)stream.read_byte()! << 40;
+	val += (uint128)stream.read_byte()! << 32;
+	val += (uint128)stream.read_byte()! << 24;
+	val += (uint128)stream.read_byte()! << 16;
+	val += (uint128)stream.read_byte()! << 8;
+	return val + stream.read_byte()!;
+}
+
+<*
+ @require @is_instream(stream)
+*>
+macro int128! read_be_int128(stream)
+{
+	return read_be_uint128(stream);
+}
+
+<*
+ @require @is_outstream(stream)
+*>
+macro void! write_be_int128(stream, uint128 s)
+{
+	stream.write_byte((char)(s >> 120))!;
+	stream.write_byte((char)(s >> 112))!;
+	stream.write_byte((char)(s >> 104))!;
+	stream.write_byte((char)(s >> 96))!;
+	stream.write_byte((char)(s >> 88))!;
+	stream.write_byte((char)(s >> 80))!;
+	stream.write_byte((char)(s >> 72))!;
+	stream.write_byte((char)(s >> 64))!;
+	stream.write_byte((char)(s >> 56))!;
+	stream.write_byte((char)(s >> 48))!;
+	stream.write_byte((char)(s >> 40))!;
+	stream.write_byte((char)(s >> 32))!;
+	stream.write_byte((char)(s >> 24))!;
+	stream.write_byte((char)(s >> 16))!;
+	stream.write_byte((char)(s >> 8))!;
+	stream.write_byte((char)s)!;
+}
+
+<*
+ @require @is_outstream(stream)
+ @require data.len < 256 "Data exceeded 255"
+*>
+macro usz! write_tiny_bytearray(stream, char[] data)
+{
+	stream.write_byte((char)data.len)!;
+	return stream.write(data) + 1;
+}
+
+<*
+ @require @is_instream(stream)
+*>
+macro char[]! read_tiny_bytearray(stream, Allocator allocator)
+{
+	int len = stream.read_byte()!;
+	if (!len) return {};
+	char[] data = allocator::alloc_array(allocator, char, len);
+	io::read_all(stream, data)!;
+	return data;
+}
+
+<*
+ @require @is_outstream(stream)
+ @require data.len < 0x1000 "Data exceeded 65535"
+*>
+macro usz! write_short_bytearray(stream, char[] data)
+{
+	io::write_be_short(stream, (ushort)data.len)!;
+	return stream.write(data) + 2;
+}
+
+<*
+ @require @is_instream(stream)
+*>
+macro char[]! read_short_bytearray(stream, Allocator allocator)
+{
+	int len = io::read_be_ushort(stream)!;
+	if (!len) return {};
+	char[] data = allocator::alloc_array(allocator, char, len);
+	io::read_all(stream, data)!;
+	return data;
+}
+
+<*
+ Wrap bytes for reading using io functions.
+*>
+fn ByteReader wrap_bytes(char[] bytes)
+{
+	return { bytes, 0 };
 }

lib/std/io/stream/buffer.c3

@@ -8,12 +8,12 @@ struct ReadBuffer (InStream)
 	usz write_idx;
 }
 
-/**
- * Buffer reads from a stream.
- * @param [inout] self
- * @require bytes.len > 0
- * @require self.bytes.len == 0 "Init may not run on already initialized data"
- **/
+<*
+ Buffer reads from a stream.
+ @param [inout] self
+ @require bytes.len > 0
+ @require self.bytes.len == 0 "Init may not run on already initialized data"
+*>
 fn ReadBuffer* ReadBuffer.init(&self, InStream wrapped_stream, char[] bytes)
 {
 	*self = { .wrapped_stream = wrapped_stream, .bytes = bytes };
@@ -68,12 +68,12 @@ struct WriteBuffer (OutStream)
 	usz index;
 }
 
-/**
- * Buffer writes to a stream. Call `flush` when done writing to the buffer.
- * @param [inout] self
- * @require bytes.len > 0 "Non-empty buffer required"
- * @require self.bytes.len == 0 "Init may not run on already initialized data"
- **/
+<*
+ Buffer writes to a stream. Call `flush` when done writing to the buffer.
+ @param [inout] self
+ @require bytes.len > 0 "Non-empty buffer required"
+ @require self.bytes.len == 0 "Init may not run on already initialized data"
+*>
 fn WriteBuffer* WriteBuffer.init(&self, OutStream wrapped_stream, char[] bytes)
 {
 	*self = { .wrapped_stream = wrapped_stream, .bytes = bytes };
@@ -121,13 +121,16 @@ fn usz! WriteBuffer.write(&self, char[] bytes) @dynamic
 fn void! WriteBuffer.write_byte(&self, char c) @dynamic
 {
 	usz n = self.bytes.len - self.index;
-	if (n == 0) self.write_pending()!;
-	self.bytes[0] = c;
-	self.index = 1;
+	if (n == 0)
+	{
+		self.write_pending()!;
+	}
+	self.bytes[self.index] = c;
+	self.index += 1;
 }
 
 fn void! WriteBuffer.write_pending(&self) @local
 {
 	self.index -= self.wrapped_stream.write(self.bytes[:self.index])!;
 	if (self.index != 0) return IoError.INCOMPLETE_WRITE?;
-}
+}

lib/std/io/stream/bytebuffer.c3

@@ -11,11 +11,11 @@ struct ByteBuffer (InStream, OutStream)
 	bool has_last;
 }
 
-/**
- * ByteBuffer provides a streamable read/write buffer.
- * max_read defines how many bytes might be kept before its internal buffer is shrinked.
- * @require self.bytes.len == 0 "Buffer already initialized."
- **/
+<*
+ ByteBuffer provides a streamable read/write buffer.
+ max_read defines how many bytes might be kept before its internal buffer is shrinked.
+ @require self.bytes.len == 0 "Buffer already initialized."
+*>
 fn ByteBuffer*! ByteBuffer.new_init(&self, usz max_read, usz initial_capacity = 16, Allocator allocator = allocator::heap())
 {
 	*self = { .allocator = allocator, .max_read = max_read };
@@ -29,10 +29,10 @@ fn ByteBuffer*! ByteBuffer.temp_init(&self, usz max_read, usz initial_capacity =
 	return self.new_init(max_read, initial_capacity, allocator::temp());
 }
 
-/**
- * @require buf.len > 0
- * @require self.bytes.len == 0 "Buffer already initialized."
- **/
+<*
+ @require buf.len > 0
+ @require self.bytes.len == 0 "Buffer already initialized."
+*>
 fn ByteBuffer*! ByteBuffer.init_with_buffer(&self, char[] buf)
 {
 	*self = { .max_read = buf.len, .bytes = buf };
@@ -93,9 +93,9 @@ fn char! ByteBuffer.read_byte(&self) @dynamic
 	return c;
 }
 
-/*
- * Only the last byte of a successful read can be pushed back.
- */
+<*
+ Only the last byte of a successful read can be pushed back.
+*>
 fn void! ByteBuffer.pushback_byte(&self) @dynamic
 {
 	if (!self.has_last) return IoError.EOF?;

lib/std/io/stream/bytewriter.c3

@@ -8,23 +8,23 @@ struct ByteWriter (OutStream)
 	Allocator allocator;
 }
 
-/**
- * @param [&inout] self
- * @param [&inout] allocator
- * @require self.bytes.len == 0 "Init may not run on already initialized data"
- * @ensure (bool)allocator, self.index == 0
- **/
+<*
+ @param [&inout] self
+ @param [&inout] allocator
+ @require self.bytes.len == 0 "Init may not run on already initialized data"
+ @ensure (bool)allocator, self.index == 0
+*>
 fn ByteWriter* ByteWriter.new_init(&self, Allocator allocator = allocator::heap())
 {
 	*self = { .bytes = {}, .allocator = allocator };
 	return self;
 }
 
-/**
- * @param [&inout] self
- * @require self.bytes.len == 0 "Init may not run on already initialized data"
- * @ensure self.index == 0
- **/
+<*
+ @param [&inout] self
+ @require self.bytes.len == 0 "Init may not run on already initialized data"
+ @ensure self.index == 0
+*>
 fn ByteWriter* ByteWriter.temp_init(&self)
 {
 	return self.new_init(allocator::temp()) @inline;
@@ -72,10 +72,10 @@ fn void! ByteWriter.write_byte(&self, char c) @dynamic
 	self.bytes[self.index++] = c;
 }
 
-/**
- * @param [&inout] self
- * @param reader
- **/
+<*
+ @param [&inout] self
+ @param reader
+*>
 fn usz! ByteWriter.read_from(&self, InStream reader) @dynamic
 {
 	usz start_index = self.index;

lib/std/io/stream/limitreader.c3

@@ -6,10 +6,10 @@ struct LimitReader (InStream)
 	usz limit;
 }
 
-/**
- * @param [&inout] wrapped_stream "The stream to read from"
- * @param limit "The max limit to read"
- **/
+<*
+ @param [&inout] wrapped_stream "The stream to read from"
+ @param limit "The max limit to read"
+*>
 fn LimitReader* LimitReader.init(&self, InStream wrapped_stream, usz limit)
 {
 	*self = { .wrapped_stream = wrapped_stream, .limit = limit };

lib/std/io/stream/multireader.c3

@@ -0,0 +1,70 @@
+module std::io;
+
+/* MultiReader implements the InStream interface and provides a logical
+ * concatenation of the provided readers. They are read sequentially. If all the
+ * data has been read, IoError.EOF is returned.
+ */
+struct MultiReader (InStream)
+{
+	InStream[] readers;
+	usz index;
+	Allocator allocator;
+}
+
+
+<*
+ @param [&inout] self
+ @param [&inout] allocator
+ @require self.readers.len == 0 "Init may not run on already initialized data"
+ @ensure self.index == 0
+*>
+fn MultiReader* MultiReader.new_init(&self, InStream... readers, Allocator allocator = allocator::heap())
+{
+	InStream []copy = allocator::new_array(allocator, InStream, readers.len);
+	copy[..] = readers[..];
+	*self = { .readers = copy, .allocator = allocator };
+	return self;
+}
+
+<*
+ @param [&inout] self
+ @require self.readers.len == 0 "Init may not run on already initialized data"
+ @ensure self.index == 0
+*>
+fn MultiReader* MultiReader.temp_init(&self, InStream... readers)
+{
+	return self.new_init(...readers, allocator: allocator::temp());
+}
+
+fn void MultiReader.free(&self)
+{
+	if (!self.allocator) return;
+	allocator::free(self.allocator, self.readers);
+	*self = {};
+}
+
+fn usz! MultiReader.read(&self, char[] bytes) @dynamic
+{
+	InStream r = self.readers[self.index];
+	usz! n = r.read(bytes);
+	if (catch err = n)
+	{
+		case IoError.EOF:
+			self.index++;
+			if (self.index >= self.readers.len)
+			{
+				return IoError.EOF?;
+			}
+			return self.read(bytes);
+		default:
+			return err?;
+	}
+	return n;
+}
+
+fn char! MultiReader.read_byte(&self) @dynamic
+{
+	char[1] data;
+	self.read(data[..])!;
+	return data[0];
+}

lib/std/io/stream/multiwriter.c3

@@ -0,0 +1,59 @@
+module std::io;
+
+/* MultiWriter implements the OutStream interface and duplicates any write
+ * operation to all the wrapped writers.
+ */
+struct MultiWriter (OutStream)
+{
+	OutStream[] writers;
+	Allocator allocator;
+}
+
+<*
+ @param [&inout] self
+ @param [&inout] allocator
+ @require writers.len > 0
+ @require self.writers.len == 0 "Init may not run on already initialized data"
+*>
+fn MultiWriter* MultiWriter.new_init(&self, OutStream... writers, Allocator allocator = allocator::heap())
+{
+	OutStream[] copy = allocator::new_array(allocator, OutStream, writers.len);
+	copy[..] = writers[..];
+	*self = { .writers = copy, .allocator = allocator };
+	return self;
+}
+
+<*
+ @param [&inout] self
+ @require writers.len > 0
+ @require self.writers.len == 0 "Init may not run on already initialized data"
+*>
+fn MultiWriter* MultiWriter.temp_init(&self, OutStream... writers)
+{
+	return self.new_init(...writers, allocator: allocator::temp());
+}
+
+fn void MultiWriter.free(&self)
+{
+	if (!self.allocator) return;
+	allocator::free(self.allocator, self.writers);
+	*self = {};
+}
+
+fn usz! MultiWriter.write(&self, char[] bytes) @dynamic
+{
+	usz n;
+	foreach (w : self.writers) 
+	{
+		n = w.write(bytes)!;
+		if (n != bytes.len) return IoError.INCOMPLETE_WRITE?;
+	}
+	return bytes.len;
+}
+
+fn void! MultiWriter.write_byte(&self, char c) @dynamic
+{
+	char[1] data;
+	data[0] = c;
+	self.write(data[..])!;
+}

lib/std/io/stream/scanner.c3

@@ -8,23 +8,23 @@ struct Scanner (InStream)
 	usz read_idx;
 }
 
-/**
- * Scanner provides a way to read delimited data (with newlines as the default).
- * The supplied buffer must be at least as large as the expected data length
- * including its pattern.
- *
- * @param [&in] stream "The stream to read data from."
- * @require buffer.len > 0 "Non-empty buffer required."
- **/
+<*
+ Scanner provides a way to read delimited data (with newlines as the default).
+ The supplied buffer must be at least as large as the expected data length
+ including its pattern.
+
+ @param [&in] stream "The stream to read data from."
+ @require buffer.len > 0 "Non-empty buffer required."
+*>
 fn void Scanner.init(&self, InStream stream, char[] buffer)
 {
 	*self = { .wrapped_stream = stream, .buf = buffer };
 }
 
 
-/**
- * Return and clear any remaining unscanned data.
- **/
+<*
+ Return and clear any remaining unscanned data.
+*>
 fn char[] Scanner.flush(&self) @dynamic
 {
 	assert(self.read_idx >= self.pattern_idx);
@@ -40,11 +40,11 @@ fn void! Scanner.close(&self) @dynamic
 	if (&self.wrapped_stream.close) return self.wrapped_stream.close();
 }
 
-/**
- * Scan the stream for the next split character and return data up to the match.
- * @require pattern.len > 0 "Non-empty pattern required."
- * @require self.buf.len > pattern.len "Pattern too large."
- **/
+<*
+ Scan the stream for the next split character and return data up to the match.
+ @require pattern.len > 0 "Non-empty pattern required."
+ @require self.buf.len > pattern.len "Pattern too large."
+*>
 fn char[]! Scanner.scan(&self, String pattern = "\n")
 {
 	if (self.read_idx == 0)

lib/std/io/stream/teereader.c3

@@ -0,0 +1,42 @@
+module std::io;
+
+struct TeeReader (InStream)
+{
+	InStream r;
+	OutStream w;
+}
+
+<* Returns a reader that implements InStream and that will write any data read
+ from the wrapped reader r to the writer w. There is no internal buffering.
+ 
+ @param [&inout] r "Stream r to read from."
+ @param [&inout] w "Stream w to write to what it reads from r."
+*>
+macro TeeReader tee_reader(InStream r, OutStream w) => { r, w };
+
+<*
+ @param [&inout] self
+ @param [&inout] r "Stream r to read from."
+ @param [&inout] w "Stream w to write to what it reads from r."
+ *>
+fn TeeReader* TeeReader.init(&self, InStream r, OutStream w)
+{
+	*self = tee_reader(r, w);
+	return self;
+}
+
+fn usz! TeeReader.read(&self, char[] bytes) @dynamic
+{
+	usz nr, nw;
+	nr = self.r.read(bytes)!;
+	nw = self.w.write(bytes[:nr])!;
+	if (nr != nw) return IoError.GENERAL_ERROR?;
+	return nr;
+}
+
+fn char! TeeReader.read_byte(&self) @dynamic
+{
+	char[1] data;
+	self.read(data[..])!;
+	return data[0];
+}

lib/std/libc/libc.c3

@@ -63,12 +63,6 @@ const bool BSD_FLAVOR_SIG @local = env::DARWIN || env::BSD_FAMILY;
 def Time_t = $typefrom(env::WIN32 ? long.typeid : CLong.typeid);
 def Off_t = $typefrom(env::WIN32 ? int.typeid : usz.typeid);
 
-struct Timespec
-{
-	Time_t tv_sec;
-	CLong tv_nsec;
-}
-
 module libc @if(env::LIBC);
 
 extern fn void abort();

lib/std/libc/libc_extra.c3

@@ -1,9 +1,11 @@
 module libc;
 import std::time;
 
-/**
- * @require self >= 0
- **/
+<*
+ Return a "timespec" from a duration.
+
+ @require self >= 0
+*>
 fn TimeSpec NanoDuration.to_timespec(self) @inline
 {
 	CLong ns = (CLong)(self % 1000_000_000);
@@ -11,9 +13,11 @@ fn TimeSpec NanoDuration.to_timespec(self) @inline
 	return { .s = sec, .ns = ns };
 }
 
-/**
- * @require self >= 0
- **/
+<*
+ Convert a duration to a timespec.
+
+ @require self >= 0
+*>
 fn TimeSpec Duration.to_timespec(self) @inline
 {
 	CLong ns = (CLong)(1000 * (self % time::SEC));

lib/std/libc/os/darwin.c3

@@ -17,10 +17,10 @@ struct Stat
 	Gid_t st_gid;
 	Dev_t st_rdev;
 
-	Timespec st_atimespec; // time of last access
-	Timespec st_mtimespec; // time of last data modification
-	Timespec st_ctimespec; // time of last status change
-	Timespec st_birthtimespec; // time of file creation(birth)
+	TimeSpec st_atimespec; // time of last access
+	TimeSpec st_mtimespec; // time of last data modification
+	TimeSpec st_ctimespec; // time of last status change
+	TimeSpec st_birthtimespec; // time of file creation(birth)
 	Off_t st_size; // file size, in bytes
 	Blkcnt_t st_blocks; // blocks allocated for file
 	Blksize_t st_blocksize; // optimal blocksize for I/O

lib/std/libc/os/posix.c3

@@ -11,6 +11,7 @@ const int RTLD_LAZY = 0x1;
 const int RTLD_NOW = 0x2;
 const int RTLD_LOCAL = 0x4;
 const int RTLD_GLOBAL = 0x8;
+const int RTLD_NODELETE = 0x1000;
 
 def Pid_t = int;
 def Uid_t = uint;
@@ -28,10 +29,10 @@ def SigActionFunction =  fn void(CInt, void*, void*);
 struct Sigaction
 {
 	union
-    {
-    	SignalFunction      sa_handler;
-    	SigActionFunction   sa_sigaction;
-    }
+	{
+		SignalFunction      sa_handler;
+		SigActionFunction   sa_sigaction;
+	}
 	CInt                    sa_flags @if(env::BSD_FAMILY);
 	Sigset_t                sa_mask; // 128
 	CInt                    sa_flags @if(!env::BSD_FAMILY);
@@ -61,17 +62,18 @@ module libc::termios @if(env::LIBC &&& env::POSIX);
 distinct Cc = char;
 distinct Speed = CUInt;
 distinct Tcflags = CUInt;
+distinct Tcactions = CInt;
 
-const Tcflags TCOOFF = 0;
-const Tcflags TCOON = 1;
-const Tcflags TCIOFF = 2;
-const Tcflags TCION = 3;
-const Tcflags TCIFLUSH = 0;
-const Tcflags TCOFLUSH = 1;
-const Tcflags TCIOFLUSH = 2;
-const Tcflags TCSANOW = 0;
-const Tcflags TCSADRAIN = 1;
-const Tcflags TCSAFLUSH = 2;
+const Tcactions TCOOFF = 0;
+const Tcactions TCOON = 1;
+const Tcactions TCIOFF = 2;
+const Tcactions TCION = 3;
+const Tcactions TCIFLUSH = 0;
+const Tcactions TCOFLUSH = 1;
+const Tcactions TCIOFLUSH = 2;
+const Tcactions TCSANOW = 0;
+const Tcactions TCSADRAIN = 1;
+const Tcactions TCSAFLUSH = 2;
 const Speed B0 = 0000000;
 const Speed B50 = 0000001;
 const Speed B75 = 0000002;
@@ -104,72 +106,72 @@ const Speed B3000000 = 0010015;
 const Speed B3500000 = 0010016;
 const Speed B4000000 = 0010017;
 const Speed MAX_BAUD = B4000000;
-const CInt VINTR = 0;
-const CInt VQUIT = 1;
-const CInt VERASE = 2;
-const CInt VKILL = 3;
-const CInt VEOF = 4;
-const CInt VTIME = 5;
-const CInt VMIN = 6;
-const CInt VSWTC = 7;
-const CInt VSTART = 8;
-const CInt VSTOP = 9;
-const CInt VSUSP = 10;
-const CInt VEOL = 11;
-const CInt VREPRINT = 12;
-const CInt VDISCARD = 13;
-const CInt VWERASE = 14;
-const CInt VLNEXT = 15;
-const CInt VEOL2 = 16;
-const CInt ISIG = 0000001;
-const CInt ICANON = 0000002;
-const CInt ECHO = 0000010;
-const CInt ECHOE = 0000020;
-const CInt ECHOK = 0000040;
-const CInt ECHONL = 0000100;
-const CInt NOFLSH = 0000200;
-const CInt TOSTOP = 0000400;
-const CInt IEXTEN = 0100000;
-const CInt CSIZE = 0000060;
-const CInt CS5 = 0000000;
-const CInt CS6 = 0000020;
-const CInt CS7 = 0000040;
-const CInt CS8 = 0000060;
-const CInt CSTOPB = 0000100;
-const CInt CREAD = 0000200;
-const CInt PARENB = 0000400;
-const CInt PARODD = 0001000;
-const CInt HUPCL = 0002000;
-const CInt CLOCAL = 0004000;
-const CInt OPOST = 0000001;
-const CInt OLCUC = 0000002;
-const CInt ONLCR = 0000004;
-const CInt OCRNL = 0000010;
-const CInt ONOCR = 0000020;
-const CInt ONLRET = 0000040;
-const CInt OFILL = 0000100;
-const CInt OFDEL = 0000200;
-const CInt VTDLY = 0040000;
-const CInt VT0 = 0000000;
-const CInt VT1 = 0040000;
-const CInt IGNBRK = 0000001;
-const CInt BRKINT = 0000002;
-const CInt IGNPAR = 0000004;
-const CInt PARMRK = 0000010;
-const CInt INPCK = 0000020;
-const CInt ISTRIP = 0000040;
-const CInt INLCR = 0000100;
-const CInt IGNCR = 0000200;
-const CInt ICRNL = 0000400;
-const CInt IUCLC = 0001000;
-const CInt IXON = 0002000;
-const CInt IXANY = 0004000;
-const CInt IXOFF = 0010000;
-const CInt IMAXBEL = 0020000;
-const CInt IUTF8 = 0040000;
+const Tcflags VINTR = 0;
+const Tcflags VQUIT = 1;
+const Tcflags VERASE = 2;
+const Tcflags VKILL = 3;
+const Tcflags VEOF = 4;
+const Tcflags VTIME = 5;
+const Tcflags VMIN = 6;
+const Tcflags VSWTC = 7;
+const Tcflags VSTART = 8;
+const Tcflags VSTOP = 9;
+const Tcflags VSUSP = 10;
+const Tcflags VEOL = 11;
+const Tcflags VREPRINT = 12;
+const Tcflags VDISCARD = 13;
+const Tcflags VWERASE = 14;
+const Tcflags VLNEXT = 15;
+const Tcflags VEOL2 = 16;
+const Tcflags ISIG = 0000001;
+const Tcflags ICANON = 0000002;
+const Tcflags ECHO = 0000010;
+const Tcflags ECHOE = 0000020;
+const Tcflags ECHOK = 0000040;
+const Tcflags ECHONL = 0000100;
+const Tcflags NOFLSH = 0000200;
+const Tcflags TOSTOP = 0000400;
+const Tcflags IEXTEN = 0100000;
+const Tcflags CSIZE = 0000060;
+const Tcflags CS5 = 0000000;
+const Tcflags CS6 = 0000020;
+const Tcflags CS7 = 0000040;
+const Tcflags CS8 = 0000060;
+const Tcflags CSTOPB = 0000100;
+const Tcflags CREAD = 0000200;
+const Tcflags PARENB = 0000400;
+const Tcflags PARODD = 0001000;
+const Tcflags HUPCL = 0002000;
+const Tcflags CLOCAL = 0004000;
+const Tcflags OPOST = 0000001;
+const Tcflags OLCUC = 0000002;
+const Tcflags ONLCR = 0000004;
+const Tcflags OCRNL = 0000010;
+const Tcflags ONOCR = 0000020;
+const Tcflags ONLRET = 0000040;
+const Tcflags OFILL = 0000100;
+const Tcflags OFDEL = 0000200;
+const Tcflags VTDLY = 0040000;
+const Tcflags VT0 = 0000000;
+const Tcflags VT1 = 0040000;
+const Tcflags IGNBRK = 0000001;
+const Tcflags BRKINT = 0000002;
+const Tcflags IGNPAR = 0000004;
+const Tcflags PARMRK = 0000010;
+const Tcflags INPCK = 0000020;
+const Tcflags ISTRIP = 0000040;
+const Tcflags INLCR = 0000100;
+const Tcflags IGNCR = 0000200;
+const Tcflags ICRNL = 0000400;
+const Tcflags IUCLC = 0001000;
+const Tcflags IXON = 0002000;
+const Tcflags IXANY = 0004000;
+const Tcflags IXOFF = 0010000;
+const Tcflags IMAXBEL = 0020000;
+const Tcflags IUTF8 = 0040000;
 
 extern fn CInt tcgetattr(Fd fd, Termios* self);
-extern fn CInt tcsetattr(Fd fd, CInt optional_actions, Termios* self);
+extern fn CInt tcsetattr(Fd fd, Tcactions optional_actions, Termios* self);
 extern fn CInt tcsendbreak(Fd fd, CInt duration);
 extern fn CInt tcdrain(Fd fd);
 extern fn CInt tcflush(Fd fd, CInt queue_selector);
@@ -181,13 +183,13 @@ extern fn CInt cfsetispeed(Termios* self, Speed speed);
 
 const CInt NCCS = 32;
 struct Termios {
-        Tcflags c_iflag;
-        Tcflags c_oflag;
-        Tcflags c_cflag;
-        Tcflags c_lflag;
-        Cc c_line;
-        Cc[NCCS] c_cc;
-        Speed c_ispeed;
-        Speed c_ospeed;
+		Tcflags c_iflag;
+		Tcflags c_oflag;
+		Tcflags c_cflag;
+		Tcflags c_lflag;
+		Cc c_line;
+		Cc[NCCS] c_cc;
+		Speed c_ispeed;
+		Speed c_ospeed;
 } 
 

lib/std/libc/termios.c3

@@ -9,7 +9,7 @@ fn Speed Termios.getISpeed(Termios* self) => cfgetispeed(self);
 fn int Termios.setOSpeed(Termios* self, Speed speed) => cfsetospeed(self, speed);
 fn int Termios.setISpeed(Termios* self, Speed speed) => cfsetispeed(self, speed);
 fn int Termios.getAttr(Termios* self, Fd fd) => tcgetattr(fd, self);
-fn int Termios.setAttr(Termios* self, Fd fd, int optional_actions) => tcsetattr(fd, optional_actions, self);
+fn int Termios.setAttr(Termios* self, Fd fd, Tcactions optional_actions) => tcsetattr(fd, optional_actions, self);
 
 module libc::termios @if(!env::LIBC ||| !env::POSIX);
 

lib/std/math/bigint.c3

@@ -1,6 +1,6 @@
-/**
- * Untested new big int implementation, missing unit tests. Etc
- */
+<*
+Untested new big int implementation, missing unit tests. Etc
+*>
 module std::math::bigint;
 import std::math::random;
 import std::io;
@@ -58,9 +58,9 @@ fn BigInt* BigInt.init_with_u128(&self, uint128 value)
 	return self;
 }
 
-/**
- * @require values.len <= MAX_LEN
- **/
+<*
+ @require values.len <= MAX_LEN
+*>
 fn BigInt* BigInt.init_with_array(&self, uint[] values)
 {
 	self.data[..] = 0;
@@ -109,7 +109,7 @@ fn BigInt*! BigInt.init_string_radix(&self, String value, int radix)
 	switch
 	{
 		case limit && !self.is_negative():
-		    return NumberConversion.INTEGER_OVERFLOW?;
+			return NumberConversion.INTEGER_OVERFLOW?;
 		case !limit && self.is_negative():
 			return NumberConversion.INTEGER_OVERFLOW?;
 	}
@@ -328,7 +328,7 @@ fn BigInt BigInt.unary_minus(&self)
 }
 
 
-macro void BigInt.div(self, BigInt other)
+macro BigInt BigInt.div(self, BigInt other)
 {
 	self.div_this(other);
 	return self;
@@ -503,8 +503,8 @@ fn BigInt BigInt.abs(&self)
 fn usz! BigInt.to_format(&self, Formatter* format) @dynamic
 {
 	@stack_mem(4100; Allocator mem)
-    {
-       return format.print(self.to_string_with_radix(10, mem));
+	{
+	   return format.print(self.to_string_with_radix(10, mem));
 	};
 }
 
@@ -513,9 +513,9 @@ fn String BigInt.to_string(&self, Allocator allocator) @dynamic
 	return self.to_string_with_radix(10, allocator);
 }
 
-/**
- * @require radix > 1 && radix <= 36 "Radix must be 2-36"
- **/
+<*
+ @require radix > 1 && radix <= 36 "Radix must be 2-36"
+*>
 fn String BigInt.to_string_with_radix(&self, int radix, Allocator allocator)
 {
 	if (self.is_zero()) return "0".copy(allocator);
@@ -555,9 +555,9 @@ fn String BigInt.to_string_with_radix(&self, int radix, Allocator allocator)
 	};
 }
 
-/**
- * @require !exp.is_negative() "Positive exponents only"
- **/
+<*
+ @require !exp.is_negative() "Positive exponents only"
+*>
 fn BigInt BigInt.mod_pow(&self, BigInt exp, BigInt mod)
 {
 	BigInt result_num = ONE;
@@ -624,11 +624,11 @@ fn BigInt BigInt.mod_pow(&self, BigInt exp, BigInt mod)
 	return result_num;
 }
 
-/*
- * Fast calculation of modular reduction using Barrett's reduction.
- * Requires x < b^(2k), where b is the base.  In this case, base is
- * 2^32 (uint).
- */
+<*
+ Fast calculation of modular reduction using Barrett's reduction.
+ Requires x < b^(2k), where b is the base.  In this case, base is
+ 2^32 (uint).
+*>
 fn BigInt barrett_reduction(BigInt x, BigInt n, BigInt constant)
 {
 	int k = n.len;
@@ -831,9 +831,17 @@ fn BigInt BigInt.gcd(&self, BigInt other)
 	return g;
 }
 
-/**
- * @require bits >> 5 < MAX_LEN "Required bits > maxlength"
- **/
+fn BigInt BigInt.lcm(&self, BigInt other)
+{
+	BigInt x = self.abs();
+	BigInt y = other.abs();
+	BigInt g = y.mult(x);
+	return g.div(x.gcd(y));
+}
+
+<*
+ @require bits >> 5 < MAX_LEN "Required bits > maxlength"
+*>
 fn void BigInt.randomize_bits(&self, Random random, int bits)
 {
 	int dwords = bits >> 5;
@@ -878,11 +886,11 @@ fn void BigInt.randomize_bits(&self, Random random, int bits)
 module std::math::bigint @private;
 
 
-/**
- * @param [&out] quotient
- * @param [&in] bi2
- * @param [&out] remainder
- **/
+<*
+ @param [&out] quotient
+ @param [&in] bi2
+ @param [&out] remainder
+*>
 fn void BigInt.single_byte_divide(&self, BigInt* bi2, BigInt* quotient, BigInt* remainder)
 {
 	uint[MAX_LEN] result;
@@ -930,11 +938,11 @@ fn void BigInt.single_byte_divide(&self, BigInt* bi2, BigInt* quotient, BigInt*
 	remainder.reduce_len();
 }
 
-/**
- * @param [&out] quotient
- * @param [&in] other
- * @param [&out] remainder
- **/
+<*
+ @param [&out] quotient
+ @param [&in] other
+ @param [&out] remainder
+*>
 fn void BigInt.multi_byte_divide(&self, BigInt* other, BigInt* quotient, BigInt* remainder)
 {
 	uint[MAX_LEN] result;
@@ -1105,16 +1113,3 @@ fn int shift_right(uint* data, int len, int shift_val) @inline
 	}
 	return find_length(data, buf_len);
 }
-
-
-
-
-
-
-
-
-
-
-
-
-

lib/std/math/math.c3

@@ -119,21 +119,21 @@ def MATRIX4_IDENTITY = matrix::IDENTITY4(<double>);
 def MATRIX4F_IDENTITY = matrix::IDENTITY4(<float>);
 
 
-/**
- * @require types::is_numerical($typeof(x)) `The input must be a numerical value or numerical vector`
- **/
+<*
+ @require types::is_numerical($typeof(x)) `The input must be a numerical value or numerical vector`
+*>
 macro deg_to_rad(x) {
     return x * PI / 180;
 }
 
-/**
- * @require types::is_numerical($typeof(x)) `The input must be a numerical value or numerical vector`
- **/
+<*
+ @require types::is_numerical($typeof(x)) `The input must be a numerical value or numerical vector`
+*>
 macro abs(x) => $$abs(x);
 
-/**
- * @require values::@is_int(x) `The input must be an integer`
- **/
+<*
+ @require values::@is_int(x) `The input must be an integer`
+*>
 macro sign(x)
 {
 	var $Type = $typeof(x);
@@ -144,10 +144,10 @@ macro sign(x)
 	$endif
 }
 
-/**
- * @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
- * @require values::@is_int(y) || values::@is_float(y) "Expected an integer or floating point value"
- **/
+<*
+ @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
+ @require values::@is_int(y) || values::@is_float(y) "Expected an integer or floating point value"
+*>
 macro atan2(x, y)
 {
 	$if @typeis(x, float) && @typeis(y, float):
@@ -157,23 +157,42 @@ macro atan2(x, y)
 	$endif
 }
 
-/**
- * @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
- * @require (@typekind(y) == ARRAY || @typekind(y) == VECTOR) &&& y.len == 2
- * @require $assignable(x, $typeof(y[0]))
- **/
-macro sincos(x, y)
+<*
+ @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
+ @require @typekind(sinp) == POINTER "Expected sinp to be a pointer"
+ @require values::@is_same_type(sinp, cosp) "Expected sinp and cosp to have the same type"
+ @require $assignable(x, $typeof(*sinp)) "Expected x and sinp/cosp to have the same type"
+*>
+macro sincos_ref(x, sinp, cosp)
 {
-	$if @typeid(y[0]) == float.typeid:
-		return _sincosf(x, y);
+	$if @typeid(*sinp) == float.typeid:
+		return _sincosf(x, sinp, cosp);
 	$else
-		return _sincos(x, y);
+		return _sincos(x, sinp, cosp);
 	$endif
 }
 
-/**
- * @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
- **/
+<*
+ Return a vector with sin / cos of the given angle.
+
+ @param x `the angle in radians`
+ @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
+*>
+macro sincos(x)
+{
+	$if @typeid(x) == float.typeid:
+		float[<2>] v @noinit;
+		_sincosf(x, &v[0], &v[1]);
+	$else
+		double[<2>] v @noinit;
+		_sincos(x, &v[0], &v[1]);
+	$endif
+	return v;
+}
+
+<*
+ @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
+*>
 macro atan(x)
 {
 	$if @typeid(x) == float.typeid:
@@ -183,9 +202,9 @@ macro atan(x)
 	$endif
 }
 
-/**
- * @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
- **/
+<*
+ @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
+*>
 macro atanh(x)
 {
 	$if @typeid(x) == float.typeid:
@@ -195,9 +214,9 @@ macro atanh(x)
 	$endif
 }
 
-/**
- * @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
- **/
+<*
+ @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
+*>
 macro acos(x)
 {
 	$if @typeid(x) == float.typeid:
@@ -207,9 +226,9 @@ macro acos(x)
 	$endif
 }
 
-/**
- * @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
- **/
+<*
+ @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
+*>
 macro acosh(x)
 {
 	$if @typeid(x) == float.typeid:
@@ -219,9 +238,9 @@ macro acosh(x)
 	$endif
 }
 
-/**
- * @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
- **/
+<*
+ @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
+*>
 macro asin(x)
 {
 	$if @typeid(x) == float.typeid:
@@ -231,9 +250,9 @@ macro asin(x)
 	$endif
 }
 
-/**
- * @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
- **/
+<*
+ @require values::@is_int(x) || values::@is_float(x) "Expected an integer or floating point value"
+*>
 macro asinh(x)
 {
 	$if @typeid(x) == float.typeid:
@@ -243,121 +262,121 @@ macro asinh(x)
 	$endif
 }
 
-/**
- * @require values::@is_floatlike(x) `The input must be a floating point value or float vector`
- **/
+<*
+ @require values::@is_floatlike(x) `The input must be a floating point value or float vector`
+*>
 macro ceil(x) => $$ceil(x);
 
-/**
- * Constrain the value to lie within the given interval.
- *
- * @param x "the value to clamp, may be a number or a numerical vector."
- * @param lower "the lower bounds"
- * @param upper "the upper bounds"
- * @return "lower if x < lower, upper if x > upper, otherwise return x."
- *
- * @require types::is_numerical($typeof(x)) `The input must be a numerical value or numerical vector`
- * @require values::@assign_to(lower, x) `The lower bound must be convertable to the value type.`
- * @require values::@assign_to(upper, x) `The upper bound must be convertable to the value type.`
- **/
+<*
+ Constrain the value to lie within the given interval.
+
+ @param x "the value to clamp, may be a number or a numerical vector."
+ @param lower "the lower bounds"
+ @param upper "the upper bounds"
+ @return "lower if x < lower, upper if x > upper, otherwise return x."
+
+ @require types::is_numerical($typeof(x)) `The input must be a numerical value or numerical vector`
+ @require values::@assign_to(lower, x) `The lower bound must be convertable to the value type.`
+ @require values::@assign_to(upper, x) `The upper bound must be convertable to the value type.`
+*>
 macro clamp(x, lower, upper) => $$max(($typeof(x))lower, $$min(x, ($typeof(x))upper));
 
-/**
- * @require values::@is_promotable_to_floatlike(mag) `The input must be a number value or float vector`
- * @require values::@assign_to(sgn, values::promote_int(mag))
- **/
+<*
+ @require values::@is_promotable_to_floatlike(mag) `The input must be a number value or float vector`
+ @require $defined(($typeof(values::promote_int(mag)))mag) `It's not possible to cast the sign to the type of the magnitude`
+*>
 macro copysign(mag, sgn) => $$copysign(values::promote_int_same(mag, sgn), ($typeof(values::promote_int_same(mag, sgn)))sgn);
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
+*>
 macro cos(x) => $$cos(x);
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
+*>
 macro cosec(x) => 1 / sin(x);
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
+*>
 macro cosech(x) => 2 / (exp(x) - exp(-x));
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
+*>
 macro cosh(x) => (exp(x) + exp(-x)) / 2.0;
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
+*>
 macro cotan(x) => cos(x) / sin(x);
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
+*>
 macro cotanh(x) => (exp(2.0 * x) + 1.0) / (exp(2.0 * x) - 1.0);
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
+*>
 macro exp(x) => $$exp(values::promote_int(x));
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
+*>
 macro exp2(x) => $$exp2(values::promote_int(x));
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number value or float vector`
+*>
 macro floor(x) => $$floor(values::promote_int(x));
 
-/**
- * @require values::@is_promotable_to_floatlike(a) `The input must be a number or float vector`
- * @require values::@is_promotable_to_floatlike(b) `The input must be a number or float vector`
- * @require values::@is_promotable_to_floatlike(c) `The input must be a number or float vector`
- * @require values::@is_same_vector_type(a, b) `The input types must be equal`
- * @require values::@is_same_vector_type(a, c) `The input types must match`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(a) `The input must be a number or float vector`
+ @require values::@is_promotable_to_floatlike(b) `The input must be a number or float vector`
+ @require values::@is_promotable_to_floatlike(c) `The input must be a number or float vector`
+ @require values::@is_same_vector_type(a, b) `The input types must be equal`
+ @require values::@is_same_vector_type(a, c) `The input types must match`
+*>
 macro fma(a, b, c) => $$fma(a, b, c);
 
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
- * @require values::@is_promotable_to_floatlike(y) `The input must be a number or a float vector`
- * @require values::@is_same_vector_type(x, y) `The input types must match`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
+ @require values::@is_promotable_to_floatlike(y) `The input must be a number or a float vector`
+ @require values::@is_same_vector_type(x, y) `The input types must match`
+*>
 macro hypot(x, y) => sqrt(sqr(x) + sqr(y));
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
+*>
 macro ln(x) => $$log(values::promote_int(x));
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
- * @require values::@is_promotable_to_floatlike(base) `The base must be a number or a float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
+ @require values::@is_promotable_to_floatlike(base) `The base must be a number or a float vector`
+*>
 macro log(x, base)
 {
 	return $$log(values::promote_int_same(x, base)) / $$log(values::promote_int_same(base, x));
 }
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
+*>
 macro log2(x) => $$log2(values::promote_int(x));
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
+*>
 macro log10(x) => $$log10(values::promote_int(x));
 
-/**
- * @require types::is_numerical($typeof(x)) `The input must be a floating point value or float vector`
- * @require types::is_same($typeof(x), $typeof(y)) `The input types must be equal`
- **/
+<*
+ @require types::is_numerical($typeof(x)) `The input must be a floating point value or float vector`
+ @require types::is_same($typeof(x), $typeof(y)) `The input types must be equal`
+*>
 macro max(x, y, ...)
 {
 	$if $vacount == 0:
@@ -371,10 +390,10 @@ macro max(x, y, ...)
 	$endif
 }
 
-/**
- * @require types::is_numerical($typeof(x)) `The input must be a numerical value or numerical vector`
- * @require types::is_same($typeof(x), $typeof(y)) `The input types must be equal`
- **/
+<*
+ @require types::is_numerical($typeof(x)) `The input must be a numerical value or numerical vector`
+ @require types::is_same($typeof(x), $typeof(y)) `The input types must be equal`
+*>
 macro min(x, y, ...)
 {
 	$if $vacount == 0:
@@ -388,21 +407,21 @@ macro min(x, y, ...)
 	$endif
 }
 
-/**
- * @require types::@is_float(a) `The input must be a floating point value`
- * @require types::@has_same(a, b, c) `The input types must be equal`
- **/
+<*
+ @require types::@is_float(a) `The input must be a floating point value`
+ @require types::@has_same(a, b, c) `The input types must be equal`
+*>
 macro muladd(a, b, c) => $$fmuladd(a, b, c);
 
-/**
- * @require values::@is_floatlike(x) `The input must be a floating point value or float vector`
- **/
+<*
+ @require values::@is_floatlike(x) `The input must be a floating point value or float vector`
+*>
 macro nearbyint(x) => $$nearbyint(x);
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
- * @require $assignable(exp, $typeof(values::promote_int(x))) || values::@is_int(exp) `The input must be an integer, castable to the type of x`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
+ @require $assignable(exp, $typeof(values::promote_int(x))) || values::@is_int(exp) `The input must be an integer, castable to the type of x`
+*>
 macro pow(x, exp)
 {
 	$if types::is_floatlike($typeof(exp)):
@@ -412,9 +431,9 @@ macro pow(x, exp)
 	$endif
 }
 
-/**
- * @require values::@is_promotable_to_float(x) : `The input must be integer or floating type`
- **/
+<*
+ @require values::@is_promotable_to_float(x) : `The input must be integer or floating type`
+*>
 macro frexp(x, int* e)
 {
 	$switch ($typeof(x))
@@ -426,9 +445,9 @@ macro frexp(x, int* e)
 	$endswitch
 }
 
-/**
- * @require values::@is_promotable_to_float(x) : `The input must be integer or floating type`
- **/
+<*
+ @require values::@is_promotable_to_float(x) : `The input must be integer or floating type`
+*>
 macro int signbit(x)
 {
 	$switch ($typeof(x))
@@ -440,64 +459,64 @@ macro int signbit(x)
 	$endswitch
 }
 
-/**
- * @require values::@is_floatlike(x) `The input must be a number or a float vector`
- **/
+<*
+ @require values::@is_floatlike(x) `The input must be a number or a float vector`
+*>
 macro rint(x) => $$rint(x);
 
-/**
- * @require values::@is_floatlike(x) `The input must be a floating point value or float vector`
- **/
+<*
+ @require values::@is_floatlike(x) `The input must be a floating point value or float vector`
+*>
 macro round(x) => $$round(x);
 
 
-/**
- * @require values::@is_floatlike(x) `The input must be a floating point value or float vector`
- **/
+<*
+ @require values::@is_floatlike(x) `The input must be a floating point value or float vector`
+*>
 macro round_to_decimals(x, int decimal_places)
 {
   var div = $$pow_int(($typeof(x))10, decimal_places);
   return round(div * x) / div;
 }
 
-/**
- * @require values::@is_floatlike(x) `The input must be a floating point value or float vector`
- **/
+<*
+ @require values::@is_floatlike(x) `The input must be a floating point value or float vector`
+*>
 macro roundeven(x) => $$roundeven(x);
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
+*>
 macro sec(x) => 1 / cos(x);
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
+*>
 macro sech(x) => 2 / (exp(x) + exp(-x));
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
+*>
 macro sin(x) => $$sin(values::promote_int(x));
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
+*>
 macro sinh(x) => (exp(x) - exp(-x)) / 2.0;
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
+*>
 macro sqr(x) => values::promote_int(x) * values::promote_int(x);
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
+*>
 macro sqrt(x) => $$sqrt(values::promote_int(x));
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
+*>
 macro tan(x)
 {
 	var $Type = $typeof(x);
@@ -511,9 +530,9 @@ macro tan(x)
 	$endswitch
 }
 
-/**
- * @require values::@is_promotable_to_float(x) `The input must be a float`
- **/
+<*
+ @require values::@is_promotable_to_float(x) `The input must be a float`
+*>
 macro bool is_finite(x)
 {
 	$switch ($typeof(x))
@@ -525,9 +544,9 @@ macro bool is_finite(x)
 	$endswitch
 }
 
-/**
- * @require values::@is_promotable_to_float(x) `The input must be a float`
- **/
+<*
+ @require values::@is_promotable_to_float(x) `The input must be a float`
+*>
 macro is_nan(x)
 {
 	$switch ($typeof(x))
@@ -539,9 +558,9 @@ macro is_nan(x)
 	$endswitch
 }
 
-/**
- * @require values::@is_promotable_to_float(x) `The input must be a float`
- **/
+<*
+ @require values::@is_promotable_to_float(x) `The input must be a float`
+*>
 macro is_inf(x)
 {
 	$switch ($typeof(x))
@@ -553,14 +572,14 @@ macro is_inf(x)
 	$endswitch
 }
 
-/**
- * @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
- **/
+<*
+ @require values::@is_promotable_to_floatlike(x) `The input must be a number or a float vector`
+*>
 macro tanh(x) => (exp(2.0 * x) - 1.0) / (exp(2.0 * x) + 1.0);
 
-/**
- * @require values::@is_floatlike(x) `The input must be a floating point value or float vector`
- **/
+<*
+ @require values::@is_floatlike(x) `The input must be a floating point value or float vector`
+*>
 macro trunc(x) => $$trunc(x);
 
 macro lerp(x, y, amount) @private => x + (y - x) * amount;
@@ -576,18 +595,18 @@ macro normalize(x) @private
 	return x * (1 / len);
 }
 
-/**
- * Use a mask to select values from either "then" or "else" vectors.
- *
- * @param mask "The mask to use for the select, 'true' will pick the then_value, 'false' the else_value"
- * @param then_value "The vector to get elements from where the mask is 'true'"
- * @param else_value "The vector to get elements from where the mask is 'false'"
- * @require values::@is_vector(then_value) && values::@is_vector(else_value) "'Then' and 'else' must be vectors."
- * @require values::@is_same_type(then_value, else_value) "'Then' and 'else' vectors must be of the same type."
- * @require then_value.len == mask.len "Mask and selected vectors must be of the same width."
- *
- * @return "a vector of the same type as then/else"
- **/
+<*
+ Use a mask to select values from either "then" or "else" vectors.
+
+ @param mask "The mask to use for the select, 'true' will pick the then_value, 'false' the else_value"
+ @param then_value "The vector to get elements from where the mask is 'true'"
+ @param else_value "The vector to get elements from where the mask is 'false'"
+ @require values::@is_vector(then_value) && values::@is_vector(else_value) "'Then' and 'else' must be vectors."
+ @require values::@is_same_type(then_value, else_value) "'Then' and 'else' vectors must be of the same type."
+ @require then_value.len == mask.len "Mask and selected vectors must be of the same width."
+
+ @return "a vector of the same type as then/else"
+*>
 macro select(bool[<*>] mask, then_value, else_value)
 {
 	return $$select(mask, then_value, else_value);
@@ -932,14 +951,14 @@ macro int128 int128.sat_shl(int128 x, int128 y) => $$sat_shl(x, y);
 macro int128! int128.overflow_add(int128 x, int128 y) => overflow_add_helper(x, y);
 macro int128! int128.overflow_sub(int128 x, int128 y) => overflow_sub_helper(x, y);
 macro int128! int128.overflow_mul(int128 x, int128 y) => overflow_mul_helper(x, y);
-/**
- * @require values::@is_int(x) `The input must be an integer`
- **/
+<*
+ @require values::@is_int(x) `The input must be an integer`
+*>
 macro bool is_odd(x) => (bool)(x & 1);
 
-/**
- * @require values::@is_int(x) `The input must be an integer`
- **/
+<*
+ @require values::@is_int(x) `The input must be an integer`
+*>
 macro bool is_even(x) => !is_odd(x);
 
 macro bool char.is_even(char x) => is_even(x);
@@ -972,9 +991,9 @@ macro bool uint128.is_odd(uint128 x) => is_odd(x);
 macro bool int128.is_even(int128 x) => is_even(x);
 macro bool int128.is_odd(int128 x) => is_odd(x);
 
-/**
- * @require types::is_underlying_int($typeof(x)) : `is_power_of_2 may only be used on integer types`
- */
+<*
+ @require types::is_underlying_int($typeof(x)) : `is_power_of_2 may only be used on integer types`
+*>
 macro bool is_power_of_2(x)
 {
 	return x != 0 && (x & (x - 1)) == 0;
@@ -1008,8 +1027,10 @@ extern fn double _atan(double x) @extern("atan");
 extern fn float _atanf(float x) @extern("atanf");
 extern fn double _atan2(double, double) @extern("atan2");
 extern fn float _atan2f(float, float) @extern("atan2f");
-extern fn void _sincos(double, double*) @extern("sincos");
-extern fn void _sincosf(float, float*) @extern("sincosf");
+extern fn void _sincos(double, double*, double*) @extern("__sincos") @link("m") @if(env::DARWIN);
+extern fn void _sincosf(float, float*, float*) @extern("__sincosf") @link("m") @if(env::DARWIN);
+extern fn void _sincos(double, double*, double*) @extern("sincos") @link("m") @if(!env::DARWIN);
+extern fn void _sincosf(float, float*, float*) @extern("sincosf") @link("m") @if(!env::DARWIN);
 extern fn double _tan(double x) @extern("tan");
 extern fn float _tanf(float x) @extern("tanf");
 extern fn double _scalbn(double x, int n) @extern("scalbn");
@@ -1116,50 +1137,108 @@ macro bool @is_same_vector_or_scalar(#vector_value, #vector_or_scalar) @private
 	return (values::@is_vector(#vector_or_scalar) &&& values::@is_same_vector_type(#vector_value, #vector_or_scalar)) ||| values::@is_int(#vector_or_scalar);
 }
 
-/**
- * @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
- * @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
- */
+<*
+ @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
+ @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
+*>
 macro char[<*>] char[<*>].muldiv(self, mul, div)  => mul_div_helper(self, mul, div);
 
-/**
- * @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
- * @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
- */
+<*
+ @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
+ @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
+*>
 macro ichar[<*>] ichar[<*>].muldiv(self, mul, div)  => mul_div_helper(self, mul, div);
 
-/**
- * @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
- * @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
- */
+<*
+ @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
+ @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
+*>
 macro short[<*>] short[<*>].muldiv(self, mul, div) => mul_div_helper(self, mul, div);
 
-/**
- * @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
- * @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
- */
+<*
+ @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
+ @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
+*>
 macro ushort[<*>] ushort[<*>].muldiv(self, mul, div) => mul_div_helper(self, mul, div);
 
-/**
- * @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
- * @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
- */
+<*
+ @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
+ @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
+*>
 macro int[<*>] int[<*>].muldiv(self, mul, div) => mul_div_helper(self, mul, div);
 
-/**
- * @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
- * @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
- */
+<*
+ @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
+ @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
+*>
 macro uint[<*>] uint[<*>].muldiv(self, mul, div) => mul_div_helper(self, mul, div);
 
-/**
- * @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
- * @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
- */
+<*
+ @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
+ @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
+*>
 macro long[<*>] long[<*>].muldiv(self, mul, div) => mul_div_helper(self, mul, div);
 
-/**
- * @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
- * @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
- */
-macro ulong[<*>] ulong[<*>].muldiv(self, mul, div) => mul_div_helper(self, mul, div);
+<*
+ @require @is_same_vector_or_scalar(self, mul) `mul must be a vector of the same type as self, or be an integer scalar`
+ @require @is_same_vector_or_scalar(self, div) `div must be a vector of the same type as self, or be an integer scalar`
+*>
+macro ulong[<*>] ulong[<*>].muldiv(self, mul, div) => mul_div_helper(self, mul, div);
+
+<*
+@require types::is_int($typeof(a)) `The input must be an integer`
+@require types::is_int($typeof(b)) `The input must be an integer`
+*>
+macro _gcd(a, b) @private
+{
+	if (a == 0) return b;
+	if (b == 0) return a;
+
+	var $Type = $typeof(a);
+	$Type r, aa, ab;
+	aa = abs(a);
+	ab = abs(b);
+	while (ab != 0)
+	{
+		r = aa % ab;
+		aa = ab;
+		ab = r;
+	}
+	return aa;
+}
+
+<*
+Calculate the least common multiple for the provided arguments.
+
+@require $vacount >= 2 `At least two arguments are required.`
+*>
+macro lcm(...)
+{
+	$typeof($vaarg[0]) result = $vaarg[0];
+	$for (var $i = 1; $i < $vacount; $i++)
+		$if $defined(result.lcm):
+			result = result.lcm($vaarg[$i]);
+		$else
+			result = (abs($vaarg[$i]) * abs(result)) / (_gcd($vaarg[$i], result));
+		$endif
+	$endfor
+	return result;
+}
+
+<*
+Calculate the greatest common divisor for the provided arguments.
+
+@require $vacount >= 2 `At least two arguments are required.`
+*>
+macro gcd(...)
+{
+	$typeof($vaarg[0]) result = $vaarg[0];
+	$for (var $i = 1; $i < $vacount; $i++)
+		$if $defined(result.gcd):
+			result = result.gcd($vaarg[$i]);
+		$else
+			result = _gcd($vaarg[$i], result);
+		$endif
+	$endfor
+	return result;
+}

lib/std/math/math_complex.c3

@@ -9,8 +9,8 @@ union Complex
 	Real[<2>] v;
 }
 
-
 const Complex IDENTITY = { 1, 0 };
+const Complex IMAGINARY = { 0, 1 };
 macro Complex Complex.add(self, Complex b) => Complex { .v = self.v + b.v };
 macro Complex Complex.add_each(self, Real b) => Complex { .v = self.v + b };
 macro Complex Complex.sub(self, Complex b) => Complex { .v = self.v - b.v };
@@ -22,3 +22,10 @@ macro Complex Complex.div(self, Complex b)
 	Real div = b.v.dot(b.v);
 	return Complex{ (self.r * b.r + self.c * b.c) / div, (self.c * b.r - self.r * b.c) / div };
 }
+macro Complex Complex.inverse(self)
+{
+	Real sqr = self.v.dot(self.v);
+	return Complex{ self.r / sqr, -self.c / sqr };
+}
+macro Complex Complex.conjugate(self) => Complex { .r = self.r, .c = -self.c };
+macro bool Complex.equals(self, Complex b) => self.v == b.v;

lib/std/math/math_i128.c3

@@ -62,124 +62,124 @@ macro uint128 @__udivmodti4(uint128 a, uint128 b, bool $return_rem)
 			$else
 				return (uint128)(n.high >> $$ctz(d.high));
 			$endif
-        }
-        sr = (uint)$$clz(d.high) - (uint)$$clz(n.high);
-        // 0 <= sr <= n_udword_bits - 2 or sr large
-        if (sr > 64 - 2)
-        {
-            $if $return_rem:
-                return n.all;
-            $else
-                return 0;
-            $endif
-        }
-        sr++;
-        // 1 <= sr <= n_udword_bits - 1
-        // q.all = n.all << (n_utword_bits - sr);
-        q.low = 0;
-        q.high = n.low << (64 - sr);
-        r.high = n.high >> sr;
-        r.low = (n.high << (64 - sr)) | (n.low >> sr);
-    }
-    else // d.s.low != 0
-    {
-        if (d.high == 0)
-        {
-            if (d.low & (d.low - 1) == 0) // if d is a power of 2
-            {
-                $if $return_rem:
-                    return (uint128)(n.low & (d.low - 1));
-                $else
-                    if (d.low == 1) return n.all;
-                    sr = (uint)$$ctz(d.low);
-                    q.high = n.high >> sr;
-                    q.low = (n.high << (64 - sr)) | (n.low >> sr);
-                    return q.all;
-               $endif
-            }
-            sr = 1 + 64 + (uint)$$clz(d.low) - (uint)$$clz(n.high);
-            // 2 <= sr <= n_utword_bits - 1
-            // q.all = n.all << (n_utword_bits - sr);
-            // r.all = n.all >> sr;
-            switch
-            {
-                case sr == 64:
+		}
+		sr = (uint)$$clz(d.high) - (uint)$$clz(n.high);
+		// 0 <= sr <= n_udword_bits - 2 or sr large
+		if (sr > 64 - 2)
+		{
+			$if $return_rem:
+				return n.all;
+			$else
+				return 0;
+			$endif
+		}
+		sr++;
+		// 1 <= sr <= n_udword_bits - 1
+		// q.all = n.all << (n_utword_bits - sr);
+		q.low = 0;
+		q.high = n.low << (64 - sr);
+		r.high = n.high >> sr;
+		r.low = (n.high << (64 - sr)) | (n.low >> sr);
+	}
+	else // d.s.low != 0
+	{
+		if (d.high == 0)
+		{
+			if (d.low & (d.low - 1) == 0) // if d is a power of 2
+			{
+				$if $return_rem:
+					return (uint128)(n.low & (d.low - 1));
+				$else
+					if (d.low == 1) return n.all;
+					sr = (uint)$$ctz(d.low);
+					q.high = n.high >> sr;
+					q.low = (n.high << (64 - sr)) | (n.low >> sr);
+					return q.all;
+			   $endif
+			}
+			sr = 1 + 64 + (uint)$$clz(d.low) - (uint)$$clz(n.high);
+			// 2 <= sr <= n_utword_bits - 1
+			// q.all = n.all << (n_utword_bits - sr);
+			// r.all = n.all >> sr;
+			switch
+			{
+				case sr == 64:
 					q.low = 0;
 					q.high = n.low;
 					r.high = 0;
 					r.low = n.high;
 				case sr < 64:
-                    q.low = 0;
-                    q.high = n.low << (64 - sr);
-                    r.high = n.high >> sr;
-                    r.low = (n.high << (64 - sr)) | (n.low >> sr);
-                default: // n_udword_bits + 1 <= sr <= n_utword_bits - 1
-                    q.low = n.low << (128 - sr);
-                    q.high = (n.high << (128 - sr)) | (n.low >> (sr - 64));
-                    r.high = 0;
-                    r.low = n.high >> (sr - 64);
-            }
-        }
-        else
-        {
+					q.low = 0;
+					q.high = n.low << (64 - sr);
+					r.high = n.high >> sr;
+					r.low = (n.high << (64 - sr)) | (n.low >> sr);
+				default: // n_udword_bits + 1 <= sr <= n_utword_bits - 1
+					q.low = n.low << (128 - sr);
+					q.high = (n.high << (128 - sr)) | (n.low >> (sr - 64));
+					r.high = 0;
+					r.low = n.high >> (sr - 64);
+			}
+		}
+		else
+		{
 			sr = (uint)$$clz(d.high) - (uint)$$clz(n.high);
-            // 0 <= sr <= n_udword_bits - 1 or sr large
-            if (sr > 64 - 1)
-            {
-                $if $return_rem:
-                    return n.all;
-                $else
-                    return 0;
-                $endif
-            }
+			// 0 <= sr <= n_udword_bits - 1 or sr large
+			if (sr > 64 - 1)
+			{
+				$if $return_rem:
+					return n.all;
+				$else
+					return 0;
+				$endif
+			}
 
-            sr++;
+			sr++;
 			// 1 <= sr <= n_udword_bits
 			// q.all = n.all << (n_utword_bits - sr);
 			// r.all = n.all >> sr;
 			q.low = 0;
-            if (sr == 64)
-            {
-                q.high = n.low;
-                r.high = 0;
-                r.low = n.high;
+			if (sr == 64)
+			{
+				q.high = n.low;
+				r.high = 0;
+				r.low = n.high;
 			}
 			else
 			{
 				r.high = n.high >> sr;
 				r.low = (n.high << (64 - sr)) | (n.low >> sr);
 				q.high = n.low << (64 - sr);
-            }
-        }
-    }
-    // Not a special case
-    // q and r are initialized with:
-    // q.all = n.all << (128 - sr);
-    // r.all = n.all >> sr;
-    // 1 <= sr <= n_utword_bits - 1
-    uint carry = 0;
-    for (; sr > 0; sr--)
-    {
-        // r:q = ((r:q)  << 1) | carry
-        r.high = (r.high << 1) | (r.low  >> (64 - 1));
-        r.low  = (r.low  << 1) | (q.high >> (64 - 1));
-        q.high = (q.high << 1) | (q.low  >> (64 - 1));
-        q.low  = (q.low  << 1) | carry;
-        // carry = 0;
-        // if (r.all >= d.all)
-        // {
-        //     r.all -= d.all;
-        //      carry = 1;
-        // }
-        int128 s = (int128)(d.all - r.all - 1) >> (128 - 1);
-        carry = (uint)(s & 1);
-        r.all -= d.all & s;
-    }
-    $if $return_rem:
+			}
+		}
+	}
+	// Not a special case
+	// q and r are initialized with:
+	// q.all = n.all << (128 - sr);
+	// r.all = n.all >> sr;
+	// 1 <= sr <= n_utword_bits - 1
+	uint carry = 0;
+	for (; sr > 0; sr--)
+	{
+		// r:q = ((r:q)  << 1) | carry
+		r.high = (r.high << 1) | (r.low  >> (64 - 1));
+		r.low  = (r.low  << 1) | (q.high >> (64 - 1));
+		q.high = (q.high << 1) | (q.low  >> (64 - 1));
+		q.low  = (q.low  << 1) | carry;
+		// carry = 0;
+		// if (r.all >= d.all)
+		// {
+		//     r.all -= d.all;
+		//      carry = 1;
+		// }
+		int128 s = (int128)(d.all - r.all - 1) >> (128 - 1);
+		carry = (uint)(s & 1);
+		r.all -= d.all & s;
+	}
+	$if $return_rem:
 		return r.all;
-    $else
+	$else
 		return (q.all << 1) | carry;
-    $endif
+	$endif
 }
 
 fn uint128 __umodti3(uint128 n, uint128 d) @extern("__umodti3") @weak @nostrip

lib/std/math/math_matrix.c3

@@ -197,7 +197,7 @@ fn Real Matrix4x4.determinant(&self)
 
 fn Matrix2x2 Matrix2x2.adjoint(&self)
 {
-	return { self.m00, -self.m01, -self.m10, self.m11 };
+	return { self.m11, -self.m01, -self.m10, self.m00 };
 }
 
 fn Matrix3x3 Matrix3x3.adjoint(&self)

lib/std/math/math_nolibc/atan.c3

@@ -38,11 +38,11 @@ fn double _atan(double x) @weak @extern("atan") @nostrip
 	{
 		case ix >= 0x44100000:
 			/* if |x| >= 2^66 */
-            if (math::is_nan(x)) return x;
-            double z = ATANHI[3] + 0x1p-120f;
-            return sign ? -z : z;
-        case ix < 0x3fdc0000:
-            /* |x| < 0.4375 */
+			if (math::is_nan(x)) return x;
+			double z = ATANHI[3] + 0x1p-120f;
+			return sign ? -z : z;
+		case ix < 0x3fdc0000:
+			/* |x| < 0.4375 */
 			if (ix < 0x3e400000)
 			{
 				/* |x| < 2^-27 */
@@ -55,8 +55,8 @@ fn double _atan(double x) @weak @extern("atan") @nostrip
 			}
 			id = -1;
 		case ix < 0x3ff30000:
-		    /* |x| < 1.1875 */
-		    x = math::abs(x);
+			/* |x| < 1.1875 */
+			x = math::abs(x);
 			if (ix < 0x3fe60000)
 			{
 				/*  7/16 <= |x| < 11/16 */
@@ -128,32 +128,32 @@ fn float _atanf(float x) @weak @extern("atanf") @nostrip
 	{
 		case ix < 0x3ee00000:
 			/* |x| < 0.4375 */
-            if (ix < 0x39800000)
-            {
-                /* |x| < 2**-12 */
-                if (ix < 0x00800000)
-                {
-                    /* raise underflow for subnormal x */
+			if (ix < 0x39800000)
+			{
+				/* |x| < 2**-12 */
+				if (ix < 0x00800000)
+				{
+					/* raise underflow for subnormal x */
 					float f = @volatile_load(x);
-                    f = f * f;
-                }
-            	return x;
-            }
-            id = -1;
-        case ix < 0x3f980000:
-            /* |x| < 1.1875 */
+					f = f * f;
+				}
+				return x;
+			}
+			id = -1;
+		case ix < 0x3f980000:
+			/* |x| < 1.1875 */
 			x = math::abs(x);
-	        if (ix < 0x3f300000)
-	        {
-	            /*  7/16 <= |x| < 11/16 */
-            	id = 0;
-            	x = (2.0f * x - 1.0f) / (2.0f + x);
-            	break;
-            }
-            /* 11/16 <= |x| < 19/16 */
-            id = 1;
-            x = (x - 1.0f) / (x + 1.0f);
-        case ix < 0x401c0000:
+			if (ix < 0x3f300000)
+			{
+				/*  7/16 <= |x| < 11/16 */
+				id = 0;
+				x = (2.0f * x - 1.0f) / (2.0f + x);
+				break;
+			}
+			/* 11/16 <= |x| < 19/16 */
+			id = 1;
+			x = (x - 1.0f) / (x + 1.0f);
+		case ix < 0x401c0000:
 			x = math::abs(x);
 			/* |x| < 2.4375 */
 			id = 2;
@@ -161,8 +161,8 @@ fn float _atanf(float x) @weak @extern("atanf") @nostrip
 		default:
 			/* 2.4375 <= |x| < 2**26 */
 			x = math::abs(x);
-        	id = 3;
-        	x = -1.0f / x;
+			id = 3;
+			x = -1.0f / x;
 	}
 	/* end of argument reduction */
 	float z = x * x;
@@ -213,7 +213,7 @@ fn double _atan2(double y, double x) @weak @extern("atan2") @nostrip
 			case 3: return -math::PI; /* atan(-0,-anything) =-pi */
 		}
 	}
-	// when x = 0 */
+	// when x = 0
 	if (ix | lx == 0) return m & 1 ? -math::PI_2 : math::PI_2;
 	/* when x is INF */
 	if (ix == 0x7ff00000)

lib/std/math/math_nolibc/cos.c3

@@ -51,7 +51,7 @@ fn float _cosf(float x) @extern("cosf") @weak @nostrip
  * ====================================================
  */
 
-fn double _cos(double x) @weak @nostrip
+fn double _cos(double x) @extern("cos")  @weak @nostrip
 {
 	// High word of x.
 	uint ix = (uint)(bitcast(x, ulong) >> 32);
@@ -61,14 +61,14 @@ fn double _cos(double x) @weak @nostrip
 	{
 		// |x| ~< pi/4
 		case ix <= 0x3fe921fb:
-		    if (ix < 0x3e46a09e)
-		    {
-		        // |x| < 2**-27 * sqrt(2)
-			    // raise inexact if x!=0
-			    force_eval_add(x, 0x1p120f);
-			    return 1.0;
-		    }
-		    return __cos(x, 0);
+			if (ix < 0x3e46a09e)
+			{
+				// |x| < 2**-27 * sqrt(2)
+				// raise inexact if x!=0
+				force_eval_add(x, 0x1p120f);
+				return 1.0;
+			}
+			return __cos(x, 0);
 		case ix >= 0x7ff00000:
 			// cos(Inf or NaN) is NaN
 			return x - x;

lib/std/math/math_nolibc/exp2.c3

@@ -88,8 +88,8 @@ fn double _exp2(double x) @extern("exp2") @weak @nostrip
 	{
 		if (abstop - _top12d(0x1p-54) >= 0x80000000)
 		{
-			// Avoid spurious underflow for tiny x.  */
-			// Note: 0 is common input.  */
+			// Avoid spurious underflow for tiny x.
+			// Note: 0 is common input.
 			return WANT_ROUNDING ? 1.0 + x : 1.0;
 		}
 		if (abstop >= _top12d(1024.0))
@@ -110,8 +110,8 @@ fn double _exp2(double x) @extern("exp2") @weak @nostrip
 		if (2 * u > 2 * bitcast(928.0, ulong)) abstop = 0;
 	}
 	const SHIFT = __EXP2_DATA.exp2_shift;
-	// exp2(x) = 2^(k/N) * 2^r, with 2^r in [2^(-1/2N),2^(1/2N)].  */
-	// x = k/N + r, with int k and r in [-1/2N, 1/2N].  */
+	// exp2(x) = 2^(k/N) * 2^r, with 2^r in [2^(-1/2N),2^(1/2N)].
+	// x = k/N + r, with int k and r in [-1/2N, 1/2N].
 	double kd = x + SHIFT;
 	ulong ki = bitcast(kd, ulong); /* k.  */
 	kd -= SHIFT; /* k/N for int k.  */
@@ -126,10 +126,10 @@ fn double _exp2(double x) @extern("exp2") @weak @nostrip
 	/* Evaluation is optimized assuming superscalar pipelined execution.  */
 	double r2 = r * r;
 	const C1 = __EXP2_DATA.exp2_poly[0];
-    const C2 = __EXP2_DATA.exp2_poly[1];
-    const C3 = __EXP2_DATA.exp2_poly[2];
-    const C4 = __EXP2_DATA.exp2_poly[3];
-    const C5 = __EXP2_DATA.exp2_poly[4];
+	const C2 = __EXP2_DATA.exp2_poly[1];
+	const C3 = __EXP2_DATA.exp2_poly[2];
+	const C4 = __EXP2_DATA.exp2_poly[3];
+	const C5 = __EXP2_DATA.exp2_poly[4];
 	/* Without fma the worst case error is 0.5/N ulp larger.  */
 	/* Worst case error is less than 0.5+0.86/N+(abs poly error * 2^53) ulp.  */
 	double tmp = tail + r * C1 + r2 * (C2 + r * C3) + r2 * r2 * (C4 + r * C5);

lib/std/math/math_nolibc/math_nolibc.c3

@@ -31,18 +31,18 @@ const Exp2fData __EXP2F_DATA @private = {
 		0x3feeace5422aa0db, 0x3feeb737b0cdc5e5, 0x3feec49182a3f090, 0x3feed503b23e255d,
 		0x3feee89f995ad3ad, 0x3feeff76f2fb5e47, 0x3fef199bdd85529c, 0x3fef3720dcef9069,
 		0x3fef5818dcfba487, 0x3fef7c97337b9b5f, 0x3fefa4afa2a490da, 0x3fefd0765b6e4540,
-    },
-    .shift_scaled = 0x1.8p+52 / (1 <<  5),
-    .poly = {
-        0x1.c6af84b912394p-5, 0x1.ebfce50fac4f3p-3, 0x1.62e42ff0c52d6p-1,
-    },
-    .shift = 0x1.8p+52,
-    .invln2_scaled = 0x1.71547652b82fep+0 * (1 << 5),
-    .poly_scaled = {
-        0x1.c6af84b912394p-5 / (1 <<  5) / (1 <<  5) / (1 <<  5),
-        0x1.ebfce50fac4f3p-3 / (1 <<  5) / (1 <<  5),
-        0x1.62e42ff0c52d6p-1 / (1 <<  5),
-    },
+	},
+	.shift_scaled = 0x1.8p+52 / (1 <<  5),
+	.poly = {
+		0x1.c6af84b912394p-5, 0x1.ebfce50fac4f3p-3, 0x1.62e42ff0c52d6p-1,
+	},
+	.shift = 0x1.8p+52,
+	.invln2_scaled = 0x1.71547652b82fep+0 * (1 << 5),
+	.poly_scaled = {
+		0x1.c6af84b912394p-5 / (1 <<  5) / (1 <<  5) / (1 <<  5),
+		0x1.ebfce50fac4f3p-3 / (1 <<  5) / (1 <<  5),
+		0x1.62e42ff0c52d6p-1 / (1 <<  5),
+	},
 };
 
 const EXP_TABLE_BITS = 7;

lib/std/math/math_nolibc/rempi.c3

@@ -62,7 +62,7 @@ fn int __rem_pio2f(float x, double *y)
 	}
 	if (ix >= 0x7f800000)
 	{
-		// x is inf or NaN */
+		// x is inf or NaN
 		*y = x - (double)x;
 		return 0;
 	}
@@ -181,9 +181,9 @@ fn int __rem_pio2_large(double* x, double* y, int e0, int nx, int prec)
 				iq[jz - 1] -= i << (24 - q0);
 				ih = iq[jz - 1] >> (23 - q0);
 			case q0 == 0:
-			    ih = iq[jz - 1] >> 23;
+				ih = iq[jz - 1] >> 23;
 			case z >= 0.5:
-			    ih = 2;
+				ih = 2;
 		}
 		if (ih > 0)
 		{
@@ -192,7 +192,7 @@ fn int __rem_pio2_large(double* x, double* y, int e0, int nx, int prec)
 			int carry = 0;
 			for (int i = 0; i < jz; i++)
 			{
-			    /* compute 1-q */
+				/* compute 1-q */
 				j = iq[i];
 				if (carry == 0)
 				{
@@ -365,17 +365,17 @@ fn int __rem_pio2_large(double* x, double* y, int e0, int nx, int prec)
  * pio2_3t:  pi/2 - (pio2_1+pio2_2+pio2_3)
  */
 
-/* caller must handle the case when reduction is not needed: |x| ~<= pi/4 */
+<* caller must handle the case when reduction is not needed: |x| ~<= pi/4 *>
 fn int __rem_pio2(double x, double *y)
 {
 	const double PIO4 = 0x1.921fb54442d18p-1;
-    const double INVPIO2 = 6.36619772367581382433e-01; /* 0x3FE45F30, 0x6DC9C883 */
-    const double PIO2_1 = 1.57079632673412561417e+00; /* 0x3FF921FB, 0x54400000 */
-    const double PIO2_1T = 6.07710050650619224932e-11; /* 0x3DD0B461, 0x1A626331 */
-    const double PIO2_2 = 6.07710050630396597660e-11; /* 0x3DD0B461, 0x1A600000 */
-    const double PIO2_2T = 2.02226624879595063154e-21; /* 0x3BA3198A, 0x2E037073 */
-    const double PIO2_3 = 2.02226624871116645580e-21; /* 0x3BA3198A, 0x2E000000 */
-    const double PIO2_3T = 8.47842766036889956997e-32; /* 0x397B839A, 0x252049C1 */
+	const double INVPIO2 = 6.36619772367581382433e-01; /* 0x3FE45F30, 0x6DC9C883 */
+	const double PIO2_1 = 1.57079632673412561417e+00; /* 0x3FF921FB, 0x54400000 */
+	const double PIO2_1T = 6.07710050650619224932e-11; /* 0x3DD0B461, 0x1A626331 */
+	const double PIO2_2 = 6.07710050630396597660e-11; /* 0x3DD0B461, 0x1A600000 */
+	const double PIO2_2T = 2.02226624879595063154e-21; /* 0x3BA3198A, 0x2E037073 */
+	const double PIO2_3 = 2.02226624871116645580e-21; /* 0x3BA3198A, 0x2E000000 */
+	const double PIO2_3T = 8.47842766036889956997e-32; /* 0x397B839A, 0x252049C1 */
 
 	ulong u = bitcast(x, ulong);
 	int sign = (int)(u >> 63);
@@ -452,37 +452,37 @@ fn int __rem_pio2(double x, double *y)
 		case ix < 0x413921fb:
 			break; // medium
 		case ix >= 0x7ff00000:
-		    // x is inf or NaN */
-            y[0] = y[1] = x - x;
-            return 0;
+			// x is inf or NaN
+			y[0] = y[1] = x - x;
+			return 0;
 		default:
 			// all other (large) arguments
-        	// set z = scalbn(|x|,-ilogb(x)+23)
-        	u = bitcast(x, ulong);
-        	u &= ((ulong)-1) >> 12;
-        	u |= (ulong)(0x3ff + 23) << 52;
-        	double z = bitcast(u, double);
-        	double[3] tx;
-        	int i;
-        	for (i = 0; i < 2; i++)
-        	{
-        		tx[i] = (double)(int)z;
-        		z = (z - tx[i]) * 0x1p24;
-        	}
-        	tx[i] = z;
-        	// skip zero terms, first term is non-zero
-        	while (tx[i] == 0.0) i--;
-        	double[2] ty;
-        	int n = __rem_pio2_large(&tx, &ty, (int)(ix >> 20) - (0x3ff + 23), i + 1, 1);
-        	if (sign)
-        	{
-        		y[0] = -ty[0];
-        		y[1] = -ty[1];
-        		return -n;
-        	}
-        	y[0] = ty[0];
-        	y[1] = ty[1];
-        	return n;
+			// set z = scalbn(|x|,-ilogb(x)+23)
+			u = bitcast(x, ulong);
+			u &= ((ulong)-1) >> 12;
+			u |= (ulong)(0x3ff + 23) << 52;
+			double z = bitcast(u, double);
+			double[3] tx;
+			int i;
+			for (i = 0; i < 2; i++)
+			{
+				tx[i] = (double)(int)z;
+				z = (z - tx[i]) * 0x1p24;
+			}
+			tx[i] = z;
+			// skip zero terms, first term is non-zero
+			while (tx[i] == 0.0) i--;
+			double[2] ty;
+			int n = __rem_pio2_large(&tx, &ty, (int)(ix >> 20) - (0x3ff + 23), i + 1, 1);
+			if (sign)
+			{
+				y[0] = -ty[0];
+				y[1] = -ty[1];
+				return -n;
+			}
+			y[0] = ty[0];
+			y[1] = ty[1];
+			return n;
 	}
 
 	// |x| ~< 2^20*(pi/2), medium size
@@ -512,7 +512,7 @@ fn int __rem_pio2(double x, double *y)
 	int ex = (int)(ix >> 20);
 	if (ex - ey > 16)
 	{
-		// 2nd round, good to 118 bits */
+		// 2nd round, good to 118 bits
 		double t = r;
 		w = fnn * PIO2_2;
 		r = t - w;

lib/std/math/math_nolibc/sincos.c3

@@ -16,7 +16,7 @@ module std::math::nolibc @if(env::NO_LIBC);
  * ====================================================
  */
 
-fn void sincosf(float x, float *sin, float *cos) @extern("sincosf") @weak @nostrip
+fn void sincosf(float x, float *sin, float *cos) @extern("__sincosf") @weak @nostrip
 {
 
 	uint ix = bitcast(x, uint);
@@ -64,20 +64,20 @@ fn void sincosf(float x, float *sin, float *cos) @extern("sincosf") @weak @nostr
 			if (ix <= 0x40afeddf)
 			{
 				// |x| ~<= 7*pi/4
-        		if (sign)
-        		{
-        		    *sin = __cosdf(x + S3PI2);
-        			*cos = -__sindf(x + S3PI2);
-        			return;
-        		}
-        		*sin = -__cosdf(x - S3PI2);
-        		*cos = __sindf(x - S3PI2);
-        		return;
-        	}
-        	*sin = __sindf(sign ? x + S4PI2 : x - S4PI2);
-        	*cos = __cosdf(sign ? x + S4PI2 : x - S4PI2);
-        case ix >= 0x7f800000:
-            // sin(Inf or NaN) is NaN
+				if (sign)
+				{
+					*sin = __cosdf(x + S3PI2);
+					*cos = -__sindf(x + S3PI2);
+					return;
+				}
+				*sin = -__cosdf(x - S3PI2);
+				*cos = __sindf(x - S3PI2);
+				return;
+			}
+			*sin = __sindf(sign ? x + S4PI2 : x - S4PI2);
+			*cos = __cosdf(sign ? x + S4PI2 : x - S4PI2);
+		case ix >= 0x7f800000:
+			// sin(Inf or NaN) is NaN
 			*sin = *cos = x - x;
 		default:
 			// general argument reduction needed
@@ -105,7 +105,7 @@ fn void sincosf(float x, float *sin, float *cos) @extern("sincosf") @weak @nostr
 
 }
 
-fn void sincos(double x, double *sin, double *cos) @extern("sincos") @weak @nostrip
+fn void sincos(double x, double *sin, double *cos) @extern("__sincos") @weak @nostrip
 {
 	// High word of x.
 	uint ix = (uint)(bitcast(x, ulong) >> 32);
@@ -129,8 +129,8 @@ fn void sincos(double x, double *sin, double *cos) @extern("sincos") @weak @nost
 			*cos = __cos(x, 0.0);
 		// sincos(Inf or NaN) is NaN
 		case ix >= 0x7ff00000:
-    		*sin = *cos = x - x;
-    	default:
+			*sin = *cos = x - x;
+		default:
 			// argument reduction needed
 			double[2] y;
 			int n = __rem_pio2(x, &y);

lib/std/math/math_nolibc/tan.c3

@@ -23,20 +23,20 @@ fn double tan(double x) @extern("tan") @weak @nostrip
 		case ix <= 0x3fe921fb:
 			if (ix < 0x3e400000)
 			{
-				// |x| < 2**-27 */
+				// |x| < 2**-27
 				/* raise inexact if x!=0 and underflow if subnormal */
 				force_eval_add(ix < 0x00100000 ? x / 0x1p120f : x + 0x1p120f, 0);
 				return x;
 			}
 			return __tan(x, 0.0, 0);
 		// tan(Inf or NaN) is NaN
-    	case ix >= 0x7ff00000:
-    		return x - x;
+		case ix >= 0x7ff00000:
+			return x - x;
 		default:
 			// argument reduction
 			double[2] y;
 			uint n = __rem_pio2(x, &y);
-            return __tan(y[0], y[1], n & 1);
+			return __tan(y[0], y[1], n & 1);
 
 	}
 }
@@ -83,7 +83,7 @@ fn float tanf(float x) @extern("tanf") @weak @nostrip
 				: __tandf(sign ? x + S2PI2 : x - S2PI2, 0);
 		// |x| ~<= 9*pi/4
 		case ix <= 0x40e231d5:
-			// |x| ~<= 7*pi/4 */
+			// |x| ~<= 7*pi/4
 			return ix <= 0x40afeddf
 				? __tandf(sign ? x + S3PI2 : x - S3PI2, 1)
 				: __tandf(sign ? x + S4PI2 : x - S4PI2, 0);

lib/std/math/math_random.c3

@@ -1,46 +1,46 @@
-/**
- * Randoms:
- * General usage -
- * 1. Create a Random (see std/math/random for various alternatives), or pick DefaultRandom
- * 2. Define it `DefaultRandom my_random;`
- * 3. Seed it: `random::seed(&my_random, some_seed);` or `rand::seed_entropy(&my_random);`
- * 4. Use it with the functions in random: `float random_float = random::next_float(&my_random);`
- *
- * For just a simple integer between 0 and n (not including n), you can use `rand(n)`.
- **/
+<*
+ Randoms:
+ General usage -
+ 1. Create a Random (see std/math/random for various alternatives), or pick DefaultRandom
+ 2. Define it `DefaultRandom my_random;`
+ 3. Seed it: `random::seed(&my_random, some_seed);` or `rand::seed_entropy(&my_random);`
+ 4. Use it with the functions in random: `float random_float = random::next_float(&my_random);`
+
+ For just a simple integer between 0 and n (not including n), you can use `rand(n)`.
+*>
 module std::math::random;
 
-/**
- * @require is_random(random)
- **/
+<*
+ @require is_random(random)
+*>
 macro void seed(random, seed)
 {
 	random.set_seed(@as_char_view(seed));
 }
 
-/**
- * Seed the random with some best effort entropy.
- *
- * @require is_random(random)
- **/
+<*
+ Seed the random with some best effort entropy.
+
+ @require is_random(random)
+*>
 macro void seed_entropy(random)
 {
 	random.set_seed(&&entropy());
 }
 
-/**
- * Get the next value between 0 and range (not including range).
- *
- * @require is_random(random)
- * @require range > 0
- **/
+<*
+ Get the next value between 0 and range (not including range).
+
+ @require is_random(random)
+ @require range > 0
+*>
 macro int next(random, uint range)
 {
 	if (range == 1) return 0;
 	uint mask = ~0U;
 	range--;
-    mask >>= range.clz();
-    uint x @noinit;
+	mask >>= range.clz();
+	uint x @noinit;
 	do
 	{
 		x = random.next_int() & mask;
@@ -49,12 +49,12 @@ macro int next(random, uint range)
 	return x;
 }
 
-/**
- * Get a random in the range [min, max], both included.
- *
- * @require is_random(random)
- * @require max >= min
- **/
+<*
+ Get a random in the range [min, max], both included.
+
+ @require is_random(random)
+ @require max >= min
+*>
 macro int next_in_range(random, int min, int max)
 {
 	return next(random, max - min + 1) + min;
@@ -65,28 +65,28 @@ def DefaultRandom = Sfc64Random;
 tlocal Sfc64Random default_random @private;
 tlocal bool default_random_initialized @private = false;
 
-/**
- * Seed the default random function.
- */
+<*
+Seed the default random function.
+*>
 fn void srand(ulong seed) @builtin
 {
 	default_random.set_seed(@as_char_view(seed));
 	default_random_initialized = true;
 }
 
-/**
- * Get a default random value between 0 and range (not including range)
- **/
+<*
+Get a default random value between 0 and range (not including range)
+*>
 fn int rand(int range) @builtin
 {
 	init_default_random();
 	return next(&default_random, range);
 }
 
-/**
- * Get a random in the range, both included.
- * @require max >= min
- **/
+<*
+Get a random in the range, both included.
+ @require max >= min
+*>
 fn int rand_in_range(int min, int max) @builtin
 {
 	init_default_random();
@@ -100,32 +100,32 @@ fn double rnd() @builtin
 	return val * 0x1.0p-53;
 }
 
-/**
- * Get 'true' or 'false'
- *
- * @require is_random(random)
- **/
+<*
+ Get 'true' or 'false'
+
+ @require is_random(random)
+*>
 macro bool next_bool(random)
 {
 	return (bool)(random.next_byte() & 1);
 }
 
-/**
- * Get a float between 0 and 1.0, not including 1.0.
- *
- * @require is_random(random)
- **/
+<*
+ Get a float between 0 and 1.0, not including 1.0.
+
+ @require is_random(random)
+*>
 macro float next_float(random)
 {
 	uint val = random.next_int() & (1 << 24 - 1);
 	return val / (float)(1 << 24);
 }
 
-/**
- * Get a double between 0 and 1.0, not including 1.0.
- *
- * @require is_random(random)
- **/
+<*
+ Get a double between 0 and 1.0, not including 1.0.
+
+ @require is_random(random)
+*>
 macro double next_double(random)
 {
 	ulong val = random.next_long() & (1UL << 53 - 1);