stdlib.md

So standard library

Solod provides a growing set of high-level packages similar to Go's stdlib, and a low-level package to help with C interop. For full API details, see the package documentation.

bytes • c • cmp • crypto/crand • encoding/binary • errors • fmt • io • log/slog • maps • math • math/bits • math/rand • mem • os • runtime • slices • strconv • strings • time • unicode • unicode/utf8

so/bytes

Byte slice operations. Offers an API similar to Go's bytes package, but with fewer features.

Functions:

• Clone returns a copy of a slice.
• Compare and Equal compare two slices lexicographically.
• Contains reports whether a subslice is within a slice.
• Count counts the number of non-overlapping instances of a subslice in a slice.
• Cut slices around the first instance of a separator.
• HasPrefix and HasSuffix report whether a slice begins/ends with a prefix/suffix.
• Index and IndexByte search for a subslice or byte within a slice.
• Join concatenates slices with a separator.
• Replace replaces occurrences of a subslice within a slice.
• Runes converts a byte slice to a rune slice.
• Split and SplitN split a slice into subslices.
• String creates a string from a byte slice.
• ToLower and ToUpper return a copy with all letters lowercased/uppercased.
• TrimLeft, TrimRight and TrimSpace trim characters from a slice.
• TrimPrefix and TrimSuffix trim a prefix/suffix from a slice.

Types:

• Buffer is a variable-sized buffer of bytes with Read and Write methods.
• Reader reads data from a byte slice.

so/c

Low-level C interop helpers for pointers, strings, and type information.

• Alignof and Sizeof return the alignment and size of type T.
• Alloca allocates an array on the stack.
• Assert aborts with a message if a condition is false.
• Bytes, Slice and String wrap C pointers to So types.
• CharPtr - cast a *byte to char*.
• PtrAdd, PtrAs and PtrAt manipulate pointers.
• Zero returns the zero value of type T.

so/cmp

Comparing ordered values. Based on Go's cmp package.

Functions:

• Compare returns -1, 0, or +1 for two ordered values.
• Equal reports whether two comparable values are equal.
• Less reports whether x is less than y.

Types:

• Func is a comparison function func(a, b any) int.
• FuncFor returns the appropriate comparison function for type T.

so/crypto/crand

Cryptographically secure random number generation.

• Read fills a slice with cryptographically secure random bytes.
• Reader is a global instance of a cryptographically secure RNG.
• Text returns a cryptographically random string using the base32 alphabet.

so/encoding/binary

Translation between numbers and byte sequences. Based on Go's encoding/binary package.

Types:

• ByteOrder specifies how to convert byte slices into unsigned integers.
• AppendByteOrder specifies how to append unsigned integers into a byte slice.
• LittleEndian and BigEndian implement ByteOrder and AppendByteOrder.

so/errors

Error creation from text messages.

• New(text string) error - create a new error with the given message.

So only supports sentinel errors, which are defined at the package level using New.

so/fmt

Formatted I/O with functions analogous to C's printf and scanf. Uses C format verbs (not Go verbs).

• Print and Println write strings to standard output.
• Printf formats and writes to standard output.
• Sprintf formats and writes to a string.
• Fprintf formats and writes to an io.Writer.
• Scanf scans formatted text from standard input.
• Sscanf scans formatted text from a string.
• Fscanf scans formatted text from an io.Reader.

Since Print and Println only take string arguments, you'll usually want to use the built-in functions print and println instead.

so/io

Basic interfaces to I/O primitives. Offers an API similar to Go's io package, but with fewer features.

Functions:

• Copy and CopyN copy data from a reader to a writer.
• ReadAll and ReadFull read data from a reader.

Types:

• Reader, Writer, and Closer are basic concepts for anything that does I/O.
• LimitedReader and SectionReader implement specialized readerss.
• Discard is a no-op writer.

so/log/slog

Simplified structured logging, inspired by Go's log/slog package. Provides leveled, key-value logging with zero-allocation formatting.

Functions:

• New creates a Logger from a Handler.
• SetDefault and Default manage the default logger.
• Debug, Info, Warn, Error log at the corresponding level using the default logger.
• String, Int, Float64, Bool, Time and Duration create key-value attributes.

Types:

• Logger logs messages through a Handler.
• TextHandler formats log records as timestamp LEVEL message key=value ... lines.
• Record holds a log event (time, level, message, attributes).
• Attr is a key-value pair. Value is a tagged union holding the value.
• Level represents severity.

so/maps

Generic hashmap similar to Go's built-in map[K]V, backed by a Robin Hood hash table with automatic grow.

Functions:

• New creates a new Map with a given allocator.

Types:

• Map is a generic hashmap with Get, Set, and Delete methods.
• Iter is an iterator over a map's key-value pairs.

so/math

Mathematical functions and constants. Offers the same API as Go's math package.

so/math/bits

Bit counting and manipulation functions. Offers the same API as Go's math/bits package.

so/math/rand

Pseudo-random number generation. Based on Go's math/rand/v2 package.

Top-level functions use a global Rand with a PCG source seeded by runtime.Seed.

Functions:

• Int, Int32, Int64 return non-negative pseudo-random integers.
• Uint, Uint32, Uint64 return pseudo-random unsigned integers.
• IntN, Int32N, Int64N return non-negative pseudo-random integers in [0,n).
• UintN, Uint32N, Uint64N return pseudo-random unsigned integers in [0,n).
• Float32 and Float64 return pseudo-random floats in [0.0,1.0).

Types:

• Source is an interface for a source of pseudo-random uint64 values.
• PCG is a PCG generator with 128 bits of internal state. Implements Source.
• Rand wraps a Source and provides the same methods as the top-level functions.

so/mem

Memory allocation with a pluggable allocator interface.

Functions:

• Alloc / Free - allocate/free a single value.
• AllocSlice / FreeSlice - allocate/free a slice.

Types:

• Allocator interface - custom allocator support (Alloc, Realloc, Free).
• SystemAllocator - default allocator backed by C calloc/realloc/free.
• Arena - bump allocator backed by a fixed buffer (Alloc, Realloc, Reset).

so/os

File I/O and filesystem operations. Offers an API similar to Go's os package, built on POSIX APIs.

Functions:

• Create, Open, OpenFile open files for reading and/or writing.
• ReadFile and WriteFile read or write an entire file.
• ReadDir reads a directory and returns its entries.
• Stat and Lstat return file information.
• Chmod, Chown, Lchown, Chtimes change file attributes.
• Rename renames (moves) a file.
• Remove removes a file or empty directory.
• Mkdir creates a directory.
• TempDir, CreateTemp, MkdirTemp work with temporary files and directories.
• Getwd and Chdir manage the current working directory.
• Getenv, LookupEnv, Setenv and Unsetenv manage environment variables.
• Getpid, Getppid, Getuid, Geteuid, Getgid, Getegid return process/user info.
• Exit terminates the program with the given status code.

Types:

• File represents an open file with methods for reading and writing data.
• FileInfo describes a file (returned by Stat and Lstat).
• FileMode represents a file's mode and permission bits.
• DirEntry describes an entry in a directory (returned by ReadDir).

so/runtime

Information about the environment where the program was compiled, and runtime utilities.

• GOOS and GOARCH specify the target operating system and architecture.
• Version returns So's compiler version (git commit hash or tag).
• Seed returns a cryptographically secure random 64-bit seed.

so/slices

Operations on slices:

• Make and MakeCap allocate a slice, Free deallocates it.
• Append appends elements to a heap slice, growing if needed.
• Extend appends another slice to a heap slice, growing if needed.
• Clone creates a shallow copy of the slice.
• Equal reports whether two slices are equal.
• Contains and Index search for value in a slice.
• Min, MinFunc, Max and MaxFunc return the minimum/maximum element.
• Sort, SortFunc and SortStableFunc sort slices.

so/strconv

Conversions between numbers and strings. Offers an API similar to Go's strconv package, but with fewer features.

• ParseBool and FormatBool convert bool ↔ string.
• Atoi, Itoa, ParseInt and FormatInt convert signed integer ↔ string.
• ParseUint and FormatUint convert unsigned integer ↔ string.
• ParseFloat and FormatFloat convert float ↔ string.

so/strings

String operations. Offers an API similar to Go's strings package, but with fewer features.

Functions:

• Clone returns a fresh copy of a string.
• Compare compares two strings lexicographically.
• Contains and ContainsFunc report whether a substring is within a string.
• Count counts the number of non-overlapping instances of a substring in a string.
• Cut slices a string around a separator.
• Fields and FieldsFunc split a string around whitespace or a predicate.
• HasPrefix and HasSuffix report whether a string begins/ends with a prefix/suffix.
• Index and IndexFunc search for a substring within a string.
• Join concatenates string slices with a separator.
• Repeat returns a string consisting of count copies of a string.
• Replace and ReplaceAll replace occurrences of a substring within a string.
• Split and SplitN split a string into substrings.
• ToLower and ToUpper return a copy with all letters lowercased/uppercased.
• Trim, TrimFunc and TrimSpace trim characters from a string.
• TrimPrefix and TrimSuffix trim a prefix/suffix from a string.

Types:

• Builder efficiently builds a string, minimizing memory copying.
• Reader reads data from a string.

so/time

Measuring and displaying time. Offers an API similar to Go's time package, but handles locations, formatting, and parsing differently.

Time is always stored as UTC internally. Formatting and parsing use C strftime/strptime verbs (e.g. %Y-%m-%d %H:%M:%S).

Constants:

• UTC - zero offset (UTC).
• Nanosecond, Microsecond, Millisecond, Second, Minute, Hour - common durations.

Functions:

• Now returns the current time in UTC (with monotonic clock reading).
• Date returns the Time for a given year, month, day, hour, min, sec, nsec, and offset (seconds east of UTC).
• Unix, UnixMilli, UnixMicro create a Time from a Unix timestamp.
• Since and Until return the duration elapsed since or until a given time.
• Parse parses a time string per layout (strptime verbs) with a given offset, returning a Time.

Types:

• Time represents an instant in time with nanosecond precision. Always UTC.
• Duration represents elapsed time as an int64 nanosecond count.
• CalDate is a date specified by year, month, and day.
• CalClock is a time of day specified by hour, minute, and second.
• Offset represents a fixed offset from UTC in seconds.

so/unicode

Data and functions to test certain properties of Unicode code points. Offers an API similar to Go's unicode package, but with fewer Unicode features (no support for graphic characters, punctuation, symbols, etc.).

• IsDigit, IsLetter and IsSpace check for different character classes.
• IsLower, IsUpper and IsTitle check for character case.
• ToLower, ToUpper and ToTitle change the character case.

so/unicode/utf8

Functions to convert between runes and UTF-8 byte sequences. Offers the same API as Go's unicode/utf8 package.

• DecodeRune and DecodeRuneInString unpacks a UTF-8-encoded rune from a byte slice or a string.
• EncodeRune writes a UTF-8-encoded rune into a byte slice.
• RuneCount and RuneCountInString return the number of runes in a byte slice or a string.
• ValidString reports whether a string consists entirely of valid UTF-8-encoded runes.