FastASCII 0.1.0 [ALPHA] — Zero-Allocation ASCII and UTF-8 Byte Engine for Java

⚡ A high-performance, zero-allocation byte processing library for Java, engineered for direct manipulation of primitive byte arrays without the devastating overhead of String instantiation or UTF-16 transcoding.

FastASCII is the foundational byte-level standard library for the FastJava ecosystem. It introduces a dual-layer architecture—leveraging HotSpot JIT-optimized scalar operations for small buffers, and an optional native SIMD backend for extreme-throughput bulk parsing.

To achieve a completely responsive, zero-latency parsing and rendering experience, FastASCII is the invisible backbone designed to power the rest of the FastJava ecosystem:

• ⚡ FastANSI — Relies on FastASCII for byte-native escape sequence scanning.
• 🚀 FastTerminal — Uses FastASCII to compose ANSI streams directly to memory for 60+ FPS zero-allocation rendering.
• 🖱️ FastMouse — Depends on FastASCII for ultra-fast integer tracking directly from standard input.

---

// Quick Start — Example

import fastascii.FastASCIIWriter;
import fastascii.FastASCIIReader;

public class Demo {
    public static void main(String[] args) {
        byte[] buffer = new byte[1024];
        
        // Write integers directly to bytes (Zero Allocation!)
        int bytesWritten = FastASCIIWriter.writeInt(buffer, 0, 404);
        
        // Write UTF-8 codepoints natively
        bytesWritten += FastASCIIWriter.writeUtf8(buffer, bytesWritten, 0x1F680); // 🚀

        // Parse unsigned integers blazingly fast
        int parsed = FastASCIIReader.parseUInt(buffer, 0, 3);
        System.out.println("Parsed: " + parsed);
    }
}

---

Table of Contents

• Mission
• Key Features
• Architecture & Dual-Layer Setup
• API Quick Reference
• Installation
• Platform JNI Capabilities
• License

---

🎯 Mission

The mission is to build the fastest, most robust byte manipulation kernel on the JVM. Java's standard library forces expensive String allocations and UTF-8 to UTF-16 conversions that destroy performance in hot loops. FastASCII operates exclusively on primitives, empowering developers to create parsers and renderers that rival ripgrep and simdjson in speed.

---

Key Features

• 🚫 Zero Allocations — Bypasses all String, StringBuilder, and Matcher instantiations.
• ⚡ JIT-Optimized Java — The core layer is pure Java, written specifically to trigger aggressive HotSpot compiler inlining for small buffers (like ANSI codes).
• 🏎️ SIMD Native Backend — For megabyte-sized logs or JSON files, seamlessly bridges to C++ SIMD (AVX2/SSE4.2) for extreme vector-accelerated throughput.
• 🌐 Native UTF-8 Encoding — Validates, encodes, and decodes UTF-8 codepoints natively at up to 4 GB/s using SIMD acceleration.
• 🎯 Universal Parsers — Built-in highly-optimized scalar search functions for indexOf, whitespace skipping, and integer parsing.

---

📊 Architecture & Dual-Layer Setup

FastASCII operates on two layers to ensure you never pay for JNI overhead when you don't need it.

[ FastASCII Library ]
  ├─ Pure Java Layer (Default)
  │    └─ JIT-optimized scalar ops (Best for strings < 1KB)
  │
  └─ FastASCII.Native (Optional JNI)
       └─ AVX2/SSE4.2 SIMD ops (Best for bulk parsing > 1KB)

The system will automatically utilize the pure Java layer for small terminal outputs, but can seamlessly fallback to the Native loader for gigabyte log parsing via FastCore.

---

API Quick Reference

Method	Description	Component
writeInt(buffer, offset, value)	Writes an integer directly into a byte buffer.	FastASCIIWriter
writeUtf8(buffer, offset, cp)	Encodes a codepoint directly to UTF-8 bytes.	FastASCIIWriter
parseUInt(buffer, start, end)	Blazing fast unsigned integer parsing from bytes.	FastASCIIReader
find(haystack, offset, len, needle)	Zero-allocation indexOf replacement.	FastASCIIScanner
decodeCodePoint(buf, off, len, out)	High-throughput UTF-8 to UTF-32 decoding.	FastUTF8

---

Installation

Option 1: Maven (Recommended)

Add the JitPack repository and the dependencies to your pom.xml:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <!-- FastASCII Library -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>fastascii</artifactId>
        <version>0.1.0</version>
    </dependency>

    <!-- FastCore (Optional Native Loader for SIMD) -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>fastcore</artifactId>
        <version>0.1.0</version>
    </dependency>
</dependencies>

Option 2: Gradle (via JitPack)

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.andrestubbe:fastascii:0.1.0'
    implementation 'com.github.andrestubbe:fastcore:0.1.0'
}

Option 3: Direct Download (No Build Tool)

Download the latest JARs directly to add them to your classpath:

1. 📦 fastascii-0.1.0.jar (The Core Library)
2. ⚙️ fastcore-0.1.0.jar (Optional Native Loader)

---

Platform JNI Capabilities

While fully functional in Pure Java, FastASCII is architected for native SIMD acceleration via FastASCII.Native:

• validateUtf8 — Validates massive text files at SIMD memory speeds.
• findSubstring — Acts as a vectorized memchr and strstr for log scraping.
• parseInt — SIMD integer parsing matching the raw speeds of simdjson.

---

License

MIT License — See LICENSE file for details.

---

Related Projects

• FastTerminal
• FastANSI
• FastMouse
• FastJSON
• FastFileScrape
• FastGLOB
• FastCore

---

Part of the FastJava Ecosystem — Making the JVM faster.