Overview

Relevant source files

• README.md
• examples/dirs/dirs_copy.go
• examples/dirs/dirs_walk.go
• examples/files/file_guard.go
• examples/files/files.go
• examples/files/stderr_to_file.go
• map.go
• map_ordered.go
• map_safe.go
• set.go
• slice.go

Purpose and Scope

This document provides a high-level introduction to the g functional programming framework for Go. It explains the framework's purpose, the problems it addresses, and provides an architectural overview of its major components. For installation instructions and first steps, see Getting Started. For detailed design philosophy and functional programming patterns, see Core Concepts and Design Philosophy.

Sources: README.md1-18

What is g?

The g framework is a functional programming library for Go that provides enhanced type wrappers, safe error handling primitives, and a comprehensive collection system with iterator support. It introduces zero-cost abstractions over Go's built-in types while maintaining full interoperability with standard Go code.

The framework is structured around six major subsystems that work together to enable functional programming patterns in Go:

1. Functional Types - Option[T] and Result[T] for null safety and error handling
2. Collection Types - Seven specialized data structures (Slice, Map, MapOrd, MapSafe, Set, Heap, Deque)
3. Iterator System - Lazy evaluation pipelines with 40+ transformation methods
4. Primitive Wrappers - Enhanced String, Bytes, Int, and Float types
5. I/O System - File and Dir with Result-based error handling
6. Concurrency - Typed synchronization primitives (Mutex[T], RwLock[T], Pool[T])

Sources: README.md1-68 slice.go1-17 map.go1-13

Core Problems Addressed

Null Safety

Go's zero values and nil pointers can cause runtime panics. The Option[T] type makes nullable values explicit:

Collections use Option[T] for safe access operations like Get(), Pop(), and Remove(), eliminating index-out-of-bounds panics.

Sources: slice.go432-439 map.go196-202

Error Handling

The Result[T] type replaces Go's (value, error) tuple pattern with a chainable, type-safe alternative:

Sources: README.md119-138

Collection Operations

Go's slices and maps lack built-in methods for common operations. The framework provides 90+ methods on Slice[T] and comprehensive APIs for all collection types:

• Safe indexing with negative index support
• Functional transformations (Map, Filter, Reduce)
• Sorting, searching, sampling
• Set operations (union, intersection, difference)

Sources: slice.go16-17 README.md164-201

Concurrent Access

Traditional Go requires careful manual synchronization. Typed locks bind data to its protection mechanism:

Sources: README.md433-451

Framework Architecture

The following diagram shows how the major components are organized and how they interact:

Key Integration Points:

• Collections → Iterators: All collections expose .Iter() methods that produce typed iterators
• Collections → Option: Safe access methods (Get, Pop, Remove) return Option[T]
• I/O → Result: File operations return Result[T] for type-safe error handling
• Type Conversions: Collections can convert between variants (e.g., Map → MapOrd → MapSafe)

Sources: slice.go121-140 map.go36-55 map_ordered.go81-89

Type System Structure

The framework implements a two-layer type system that wraps Go's built-in types while maintaining full interoperability:

Conversion Patterns:

Direction	Method	Example
Go → g	Constructor functions	g.SliceOf(1, 2, 3)
Go → g	Type casting	g.String("hello")
g → Go	.Std() method	slice.Std() returns []T
g → Go	Type casting	int(myInt)

The types maintain the same memory layout as their Go counterparts, making conversions zero-cost operations.

Sources: slice.go82-83 slice.go1064-1065 map.go107-108

Collection Type Selection

The framework provides seven collection types optimized for different use cases:

Type	Primary Use Case	Key Feature	File
Slice[T]	General-purpose list	90+ methods, indexable	slice.go
Map[K,V]	Key-value lookup	Entry API, O(1) access	map.go
MapOrd[K,V]	Insertion-ordered map	Maintains order, sortable	map_ordered.go
MapSafe[K,V]	Concurrent map	Thread-safe, lock-free reads	map_safe.go
Set[T]	Unique elements	Set operations, O(1) membership	set.go
Heap[T]	Priority queue	Custom comparator, O(log n) ops	heap.go
Deque[T]	Double-ended queue	O(1) front/back operations	deque.go

Selection Guide:

Sources: slice.go16-17 map.go12-13 map_ordered.go18-19 map_safe.go13-16 set.go6-7

Iterator System

All collections implement the .Iter() method that returns a typed iterator. Iterators provide lazy evaluation and can be chained together:

Iterator Methods by Category:

Category	Methods	Description
Filtering	Filter, Exclude, Take, Skip	Remove or limit elements
Mapping	Map, FilterMap, FlatMap	Transform elements
Combining	Chain, Zip, Enumerate	Combine iterators
Aggregating	Collect, Fold, Reduce, Count	Produce final values
Searching	Find, Any, All	Search for elements

Sources: slice.go121-140 README.md345-397

Error Handling Model

The framework uses two types for safe error handling:

Usage Patterns:

Return Type	Use When	Example Methods
T	Operation always succeeds	Len(), IsEmpty(), Clone()
Option[T]	Value may be absent	Get(), Pop(), First(), Last()
Result[T]	Operation may fail	File.Read(), String.TryInt(), Pool.Wait()

Sources: slice.go432-439 map.go196-202

File System Integration

The I/O system uses Result[T] for all operations that can fail, enabling error-aware iteration:

Example: Processing Files with Error Handling

The framework enables declarative file processing with integrated error handling:

Sources: examples/dirs/dirs_walk.go1-19 examples/files/files.go1-46

Concurrency Primitives

The framework provides three concurrency primitives that enforce correct synchronization at the type level:

Key Safety Features:

• Type-bound locking: Data cannot be accessed without acquiring the lock
• Guard-based access: Locks are released when guards go out of scope
• Ordered results: Pool[T] maintains submission order in results

Sources: README.md401-486 README.md489-536

Interoperability with Go

The framework maintains full interoperability with standard Go code through three mechanisms:

Pattern	Direction	Method
Wrapping	Go → g	Constructor functions (SliceOf, String)
Unwrapping	g → Go	.Std() method returns underlying Go type
Bridge functions	Go → g	ResultOf converts (T, error) to Result[T]

Example: Converting Between g and Go

This design allows gradual adoption of the framework in existing codebases without requiring a full rewrite.

Sources: slice.go82-83 slice.go1064-1065

Summary

The g framework provides a comprehensive functional programming toolkit for Go that addresses common pain points in Go development:

1. Type Safety: Option[T] and Result[T] eliminate null pointer errors and improve error handling
2. Rich Collections: Seven specialized collection types with 90+ methods each
3. Lazy Evaluation: Iterator system with 40+ chainable operations
4. Safe Concurrency: Typed locks that prevent unsynchronized access
5. Seamless Integration: Zero-cost conversions between g and standard Go types

For detailed information on specific subsystems, see:

• Functional Types for Option and Result documentation
• Collection Types for detailed collection APIs
• Iterator System for iterator methods and patterns
• Concurrency and Parallelism for Pool, Mutex, and RwLock

Sources: README.md1-738