Repository files navigation

Scala macro that generates ultra-fast string interpolators.

A general idea and some parts of code was borrowed from a great article"Scala: String Interpolation Performance" by Dmitry Komanov.

A high-performance 100% compatible drop-in replacement of simple and raw string interpolators (s"" orraw"" literals).

Currently, it doesn't support formatting string interpolator (f"" literal), however this will probably be added soon.

Add the library to a dependency list:

libraryDependencies+="com.github.plokhotnyuk.fsi"%%"fsi-macros"%"0.6.3"

Add import and replace prefixs byfs (or for a raw string interpolatorraw byfraw):

importcom.github.plokhotnyuk.fsi._valhost="company.com"valpath="blog"fs"http://$host/$path"fraw"http://$host/$path"

That's it! You have got ~1.5x speed up in runtime and ~4x less usage of heap memory comparing to standard interpolatorswhich come with 2.12.8 version of Scala compiler.

Also, it is more efficient than a simple concatenation of strings by the+ operator or using string builders for that.

Check for benchmark results where the fast string interpolator compared with standard Scala interpolators, 3rd-partyinterpolators, Scala/Java string builders, and a string concatenation using JDK 8 and Scala 2.12.5:

• fInterpolator - standard string interpolator with formatting
• fastInterpolator - thefastring interpolator
• frawInterpolator - fast string interpolator replacement for raw string interpolator
• fsInterpolator - fast string interpolator replacement for simple string interpolator
• javaStringBuilder - java.lang.StringBuilder
• pInterpolator - theperfolation interpolator
• rawInterpolator - standard raw string interpolator
• sInterpolator - standard simple string interpolator
• scalaStringBuilder - scala.collection.mutable.StringBuilder
• scalaStringConcatenation -+ operand for strings

NOTE: Numbers can vary depending on use case, payload, JDK, and Scala versions. For cases, like templating with lotof nested cycles, please consider using offastring or string builders immediately.

Results of benchmarks which compare performance of Fast StringInterpolator with other alternatives for different cases of simple and nested loop usage, and for different versions ofJDK and Scala.

Let we have defined functions:def f(): Int anddef g(): Double, then in compile-time forfs"a${f()}bb${g()}"the following code will be generated:

{valfresh$macro$1:Int= f();valfresh$macro$2:Double= g();  com.github.plokhotnyuk.fsi.`package`.stringBuilder().append('a').append(fresh$macro$1).append("bb").append(fresh$macro$2).toString();}:String

You can check this by adding a compiler option:scalacOptions += "-Ymacro-debug-lite".

In this codecom.github.plokhotnyuk.fsi.`package`.stringBuilder() stands for getting a preallocated instance ofjava.lang.StringBuilder from the thread-local pool.

By default a buffer capacity of all createdjava.lang.StringBuilder instances is 16384 characters (32Kb). If limitis reached buffer size grows to ensure that whole string can fit in it. However next retrieval from the pool a newjava.lang.StringBuilder instance will be allocated with the default size of the buffer and returned to avoidexhausting of Java heap. So if you want to work with longer strings without reallocations then set a greater value forthe following JVM system property:com.github.plokhotnyuk.fsi.buffer.size.

To compile, run tests, check coverage, and check binary compatibility for different Scala versions use a command:

sbt ++2.11.12 clean coveragetest coverageReport mimaReportBinaryIssuessbt ++2.12.8 clean coveragetest coverageReport mimaReportBinaryIssues

Feel free to modify benchmarks and check how it works on your payload, JDK, and Scala versions.

To see throughput with allocation rate for different approaches of string concatenation run benchmarks with GC profilerfor a specified JDK and Scala versions using the following command:

sbt -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 .*'

It will save benchmark report in a specified JSON file.

Results that are stored in JSON can be easy plotted inJMH Visualizer by drugging & droppingof your file to the drop zone or using thesource parameter with an HTTP link to your file in the URL likehere.

Publish to the local Ivy repo:

sbt +publishLocal

Publish to the local Maven repo:

sbt +publishM2

For version numbering useRecommended Versioning Schemethat is used in the Scala ecosystem.

Double check binary and source compatibility (including behavior) and runrelease command (credentials required):

sbt release