# Stew

# stew - status e-something w-something

(opens new window) (opens new window) (opens new window) (opens new window)

stew is collection of utilities, std library extensions and budding libraries that are frequently used at Status, but are too small to deserve their own git repository.

We also use stew as a staging ground for code that has yet to be battle-tested.

Some of these libraries may eventually be proposed for inclusion in Nim or broken out into separate repositories.

# Notable libraries

Libraries are documented either in-module or on a separate README in their respective folders

arrayops - small helpers and operations on array/openArray
assign2 - fast assignments (unlike the = operator in nim which is very slow)
bitops2 - an updated version of bitops.nim, filling in gaps in original code
byteutils - utilities that make working with the Nim byte type convenient
endians2 - utilities for converting to and from little / big endian integers
objects - get an object's base type at runtime, as a string
ptrops - pointer arithmetic utilities
result - friendly, exception-free value-or-error returns, similar to Option[T], from nim-result (opens new window)
shims - backports of nim devel code to the stable version that Status is using
sequtils2 - extensions to the sequtils module for working conveniently with seq
varints - helpers for working with variable length integers

# Layout

stew modules are made to be fairly independent of each other, but generally follow the following layout - if you've used C++'s boost, you'll feel right at home:

# Single-module libraries
stew/small.nim # small libraries that fits in one module

# Multi-module libraries
stew/libname.nim # Main import file
stew/libname/stuff.nim # Detail import file

# Nim standard library shims that contain forwards-compatibility code to manage
# support for multiple nim versions - code in here typically has been taken
# from nim `devel` branch and `name` will reexport the corresponding std lib
# module
stew/shims/macros.nim # module that reexports `macros.nim` adding code from newer nim versions

# Tests are in the tests folder (duh!)
# To execute, run either `all_tests.nim` or specific `test_xxx.nim` files:
nim c -r tests/all_tests

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Compatibility

One of the goals of stew is to provide backwards and forwards compatibility for different Nim versions, such that code using stew works well with multiple versions of Nim. If stew is not working with the Nim version you're using, we welcome patches.

You can create multiple versions of your code using the following pattern:

when (NimMajor,NimMinor,NimPatch) >= (0,19,9):
  discard
elif (NimMajor,NimMinor,NimPatch) >= (0,19,0):
  discard
else
  {.fatal: "unsupported nim version"}

1
2
3
4
5
6

# Using stew in your project

We do not recommend using this library as a normal nimble dependency - there are no versioned releases and we will not maintain API/ABI stability. Instead, make sure you pin your dependency to a specific git hash (for example using a submodule) or copy the file to your project instead.

Typically, you will import either a top-level library or drill down into its submodules:

import stew/bitops2
import stew/ranges/bitranges

1
2

⚠️ No API/ABI stability - pick a commit and stick with it ⚠️