Mirror of forum.nim-lang.org

14043 :: Nim 2.4.0 - SSO porting guide

• Araq (orginal) [2026-07-12T13:29:28+02:00] view original

  SSO strings

  Nim's new strings API is compatible with Nimony's so porting is always beneficial, even if these strings do not improve the performance.

  Here is our porting guide:

  Purpose	Use	Notes
  Read-only raw pointer	readRawData(s, start = 0)	valid while s is alive & untouched
  Raw pointer that survives moves/copies	readRawDataStable(s, start = 0)	takes var string; promotes small strings to heap first
  Bulk write into a string	beginStore(s, newLen, start = 0) … endStore(s)	sets length, ensures unique ownership, returns writable ptr

  Rules of thumb:

  • Reading bytes (memcpy out of a string, memmem, scanning): replace addr s[i] / unsafeAddr s[i] with readRawData(s, i).
  • Writing bytes in bulk (memcpy/fread into a string): replace setLen + addr s[oldLen] with beginStore(s, newLen, start) followed by endStore(s). beginStore already sets the length and does the copy-on-write / unique-ownership dance, so an explicit prepareMutation is no longer needed.
  • A pointer that must outlive the current scope (e.g. a cursor stored next to its buffer): use readRawDataStable, which forces the string onto the heap so the payload address is stable.
  • Single-element write s[i] = c still works unchanged — the compiler lowers it to nimStrPutV3, which handles COW internally. You no longer need prepareMutation(s) before an indexed assignment.

  Before / after examples

  Bulk copy into a string:

  
  # before
  result.setLen newLen
  copyMem(addr result[oldLen], buf, buflen)
  
  # after
  copyMem(beginStore(result, newLen, oldLen), buf, buflen)
  endStore(result)
  Run

  Reading bytes out of a string:

  
  # before
  copyMem(dest, addr(s.data[s.pos]), n)
  
  # after
  copyMem(dest, readRawData(s.data, s.pos), n)
  Run

  Read into a slice of a string:

  
  # before
  prepareMutation(buffer)                       # COW literal guard under ARC
  result = s.readData(addr buffer[slice.a], count)
  
  # after
  result = s.readData(beginStore(buffer, slice.b + 1 - slice.a, slice.a), count)
  endStore(buffer)
  Run

  cstring conversions

  • Converting string → cstring still works, but the C string is only valid as long as the source string is alive and unmodified.
  • If you need a stable, NUL-terminated buffer to hand to C, keep the owning string alive and derive the pointer from it (via readRawDataStable / the normal cstring conversion) rather than caching the pointer past a move.

  Migration checklist

  • [ ] Grep your code for addr s[, unsafeAddr s[, addr(...data[, and any cached pointer/cstring into a string.
  • [ ] Replace read accesses with readRawData (or readRawDataStable if the pointer escapes the current scope / must survive a move).
  • [ ] Replace setLen + raw write with beginStore / endStore.
  • [ ] Drop now-redundant prepareMutation calls before indexed writes and beginStore.
  • [ ] Don't assume addr s[0] is stable across add, reassignment, or passing the string by value.
  • [ ] Build once with --strings:sso and once without to confirm the code compiles and behaves identically under both.

  Because the helper API has identical signatures on every string backend, code written this way keeps working under refc/ARC/ORC without SSO — you can port incrementally and flip --strings:sso on when ready.

  Once again, in order to avoid confusions:

  Updating your code is not required, but beneficial. The same API works for all `mm` switches and is also offered by Nimony/Nim 3.

---