{"id":16444806,"url":"https://github.com/plokhotnyuk/fast-string-interpolator","last_synced_at":"2025-03-15T11:33:06.696Z","repository":{"id":30161625,"uuid":"124115842","full_name":"plokhotnyuk/fast-string-interpolator","owner":"plokhotnyuk","description":"Scala macro that generates ultra-fast string interpolators.","archived":false,"fork":false,"pushed_at":"2024-05-09T18:33:03.000Z","size":2714,"stargazers_count":88,"open_issues_count":9,"forks_count":6,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-05-21T01:04:21.523Z","etag":null,"topics":["high-performance","macro","scala","string-interpolation"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plokhotnyuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"plokhotnyuk","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2018-03-06T17:45:04.000Z","updated_at":"2024-06-19T02:48:11.461Z","dependencies_parsed_at":"2024-01-22T21:58:37.304Z","dependency_job_id":"43d1c24e-29c5-41f1-b7f0-5406043ee961","html_url":"https://github.com/plokhotnyuk/fast-string-interpolator","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plokhotnyuk%2Ffast-string-interpolator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plokhotnyuk%2Ffast-string-interpolator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plokhotnyuk%2Ffast-string-interpolator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plokhotnyuk%2Ffast-string-interpolator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plokhotnyuk","download_url":"https://codeload.github.com/plokhotnyuk/fast-string-interpolator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243725025,"owners_count":20337660,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["high-performance","macro","scala","string-interpolation"],"created_at":"2024-10-11T09:26:51.255Z","updated_at":"2025-03-15T11:33:06.314Z","avatar_url":"https://github.com/plokhotnyuk.png","language":"Scala","funding_links":["https://github.com/sponsors/plokhotnyuk"],"categories":["Table of Contents"],"sub_categories":["Tools"],"readme":"# Fast String Interpolator\n\n[![Actions Build](https://github.com/plokhotnyuk/fast-string-interpolator/workflows/build/badge.svg)](https://github.com/plokhotnyuk/fast-string-interpolator/actions)\n[![Scala Steward](https://img.shields.io/badge/Scala_Steward-helping-brightgreen.svg?style=flat\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAQCAMAAAARSr4IAAAAVFBMVEUAAACHjojlOy5NWlrKzcYRKjGFjIbp293YycuLa3pYY2LSqql4f3pCUFTgSjNodYRmcXUsPD/NTTbjRS+2jomhgnzNc223cGvZS0HaSD0XLjbaSjElhIr+AAAAAXRSTlMAQObYZgAAAHlJREFUCNdNyosOwyAIhWHAQS1Vt7a77/3fcxxdmv0xwmckutAR1nkm4ggbyEcg/wWmlGLDAA3oL50xi6fk5ffZ3E2E3QfZDCcCN2YtbEWZt+Drc6u6rlqv7Uk0LdKqqr5rk2UCRXOk0vmQKGfc94nOJyQjouF9H/wCc9gECEYfONoAAAAASUVORK5CYII=)](https://scala-steward.org)\n[![Maven Central](https://img.shields.io/badge/maven--central-0.6.3-blue.svg)](https://search.maven.org/search?q=com.github.plokhotnyuk.fsi)\n\nScala macro that generates ultra-fast string interpolators.\n\n## Acknowledgments\n\nA general idea and some parts of code was borrowed from a great article [\"Scala: String Interpolation Performance\" by Dmitry Komanov](https://medium.com/@dkomanov/scala-string-interpolation-performance-21dc85e83afd).\n\n## Goals, features, and limitations\n\nA high-performance 100% compatible drop-in replacement of simple and raw string interpolators (`s\"\"` or `raw\"\"` literals).\n\nCurrently, it doesn't support formatting string interpolator (`f\"\"` literal), however this will probably be added soon.\n\n## How to use\n\nAdd the library to a dependency list:\n\n```sbt\nlibraryDependencies += \"com.github.plokhotnyuk.fsi\" %% \"fsi-macros\" % \"0.6.3\"\n```\n\nAdd import and replace prefix `s` by `fs` (or for a raw string interpolator `raw` by `fraw`):\n\n```scala\nimport com.github.plokhotnyuk.fsi._\n\nval host = \"company.com\"\nval path = \"blog\"\nfs\"http://$host/$path\"\nfraw\"http://$host/$path\"\n```\n\nThat's it! You have got ~1.5x speed up in runtime and ~4x less usage of heap memory comparing to standard interpolators\nwhich come with 2.12.8 version of Scala compiler.\n\nAlso, it is more efficient than a simple concatenation of strings by the `+` operator or using string builders for that.\n\nCheck for benchmark results where the fast string interpolator compared with standard Scala interpolators, 3rd-party\ninterpolators, Scala/Java string builders, and a string concatenation using JDK 8 and Scala 2.12.5:\n- *fInterpolator* - standard string interpolator with formatting\n- *fastInterpolator* - the [fastring](https://github.com/Atry/fastring) interpolator\n- *frawInterpolator* - fast string interpolator replacement for raw string interpolator\n- *fsInterpolator* - fast string interpolator replacement for simple string interpolator\n- *javaStringBuilder* - java.lang.StringBuilder\n- *pInterpolator* - the [perfolation](https://github.com/outr/perfolation) interpolator\n- *rawInterpolator* - standard raw string interpolator\n- *sInterpolator* - standard simple string interpolator\n- *scalaStringBuilder* - scala.collection.mutable.StringBuilder\n- *scalaStringConcatenation* - `+` operand for strings\n\n[![Throughput](docs/fast_string_interpolator_throughput.png)](docs/fast_string_interpolator_throughput.png)\n\n[![Heap Usage](docs/fast_string_interpolator_heap_usage.png)](docs/fast_string_interpolator_heap_usage.png)\n\n*NOTE*: Numbers can vary depending on use case, payload, JDK, and Scala versions. For cases, like templating with lot\nof nested cycles, please consider using of [fastring](https://github.com/Atry/fastring) or string builders immediately.\n\n[Results of benchmarks](https://plokhotnyuk.github.io/fast-string-interpolator) which compare performance of Fast String\nInterpolator with other alternatives for different cases of simple and nested loop usage, and for different versions of\nJDK and Scala.\n\n### How it works\n\nLet we have defined functions: `def f(): Int` and `def g(): Double`, then in compile-time for `fs\"a${f()}bb${g()}\"`\nthe following code will be generated:\n\n```scala\n{\n  val fresh$macro$1: Int = f();\n  val fresh$macro$2: Double = g();\n  com.github.plokhotnyuk.fsi.`package`.stringBuilder().append('a').append(fresh$macro$1).append(\"bb\").append(fresh$macro$2).toString();\n}: String\n```\n\nYou can check this by adding a compiler option: `scalacOptions += \"-Ymacro-debug-lite\"`.\n\nIn this code ```com.github.plokhotnyuk.fsi.`package`.stringBuilder()``` stands for getting a preallocated instance of\n`java.lang.StringBuilder` from the thread-local pool.\n\nBy default a buffer capacity of all created `java.lang.StringBuilder` instances is 16384 characters (32Kb). If limit\nis reached buffer size grows to ensure that whole string can fit in it. However next retrieval from the pool a new\n`java.lang.StringBuilder` instance will be allocated with the default size of the buffer and returned to avoid\nexhausting of Java heap. So if you want to work with longer strings without reallocations then set a greater value for\nthe following JVM system property: `com.github.plokhotnyuk.fsi.buffer.size`.\n\n## How to contribute\n\n### Build\n\nTo compile, run tests, check coverage, and check binary compatibility for different Scala versions use a command:\n\n```sh\nsbt ++2.11.12 clean coverage test coverageReport mimaReportBinaryIssues\nsbt ++2.12.8 clean coverage test coverageReport mimaReportBinaryIssues\n```\n\n### Run benchmarks\n\nFeel free to modify benchmarks and check how it works on your payload, JDK, and Scala versions.\n\nTo see throughput with allocation rate for different approaches of string concatenation run benchmarks with GC profiler\nfor a specified JDK and Scala versions using the following command:\n\n```sh\nsbt -java-home /usr/lib/jvm/jdk1.8.0 -no-colors ++2.12.8 clean 'fsi-benchmark-core/jmh:run -jvm /usr/lib/jvm/jdk-11/bin/java -prof gc -rf json -rff jdk-11_scala-2.12.8.json .*'\n```\n\nIt will save benchmark report in a specified JSON file.\n\nResults that are stored in JSON can be easy plotted in [JMH Visualizer](http://jmh.morethan.io/) by drugging \u0026 dropping\nof your file to the drop zone or using the `source` parameter with an HTTP link to your file in the URL like\n[here](http://jmh.morethan.io/?source=https://plokhotnyuk.github.io/fast-string-interpolator/jdk-8_scala-2.12.5.json).\n\n### Publish locally\n\nPublish to the local Ivy repo:\n\n```sh\nsbt +publishLocal\n```\n\nPublish to the local Maven repo:\n\n```sh\nsbt +publishM2\n```\n\n### Release\n\nFor version numbering use [Recommended Versioning Scheme](http://docs.scala-lang.org/overviews/core/binary-compatibility-for-library-authors.html#recommended-versioning-scheme)\nthat is used in the Scala ecosystem.\n\nDouble check binary and source compatibility (including behavior) and run `release` command (credentials required):\n\n```sh\nsbt release\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplokhotnyuk%2Ffast-string-interpolator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplokhotnyuk%2Ffast-string-interpolator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplokhotnyuk%2Ffast-string-interpolator/lists"}