Skip to content

Latest commit

 

History

History
196 lines (163 loc) · 5.69 KB

README.md

File metadata and controls

196 lines (163 loc) · 5.69 KB
Raw

Fastring

Join the chat at https://gitter.im/Atry/fastring Scala CI Latest version Scaladoc

Fastring is a string formatting library for Scala. Fastring is also designed to be a template engine, and it is an excellent replacement of JSP, Scalate or FreeMarker.

It's simple to use

Fastring uses string interpolation syntax. For example, if you are writing a CGI page:

import com.dongxiguo.fastring.Fastring.Implicits._
def printHtml(link: java.net.URL) {
  val fastHtml = fast"<html><body><a href='$link'>Click Me!</a></body></html>"
  print(fastHtml)
}

It's extremely fast

I made a benchmark. I used 4 different ways to create a 545-characters string.

  1. Fastring (fast"Concat with $something" syntax);
  2. String concatenation (s"Concat with $something" syntax);
  3. Handwritten StringBuilder (stringBuilder ++= "Build from " ++= something syntax);
  4. java.util.Formatter (f"Format with $something" syntax).

This is the result from my Intel i5-3450 computer:

Fastring 
import com.dongxiguo.fastring.Fastring.Implicits._
def fast(a: Int) =
  fast"head ${
    (for (j <- 0 until 10 view) yield {
      fast"baz$j $a foo ${
        (for (i <- 0 until 4 view) yield {
          fast"$a i=$i"
        }).mkFastring(",")
      } bar\n"
    }).mkFastring("<hr/>")
  } tail"

fast(0).toString

 Took 669 nanoseconds to generate a 545-characters string.
(Simple and fast)
String concatenation 
def s(a: Int) =
  s"head ${
    (for (j <- 0 until 10 view) yield {
      s"baz$j $a foo ${
        (for (i <- 0 until 4 view) yield {
          s"$a i=$i"
        }).mkString(",")
      } bar\n"
    }).mkString("<hr/>")
  } tail"

s(0)

 Took 1738 nanoseconds to generate a 545-characters string.
(Simple but slow)
Handwritten StringBuilder 
def sb(sb: StringBuilder, a: Int) {
  sb ++= "head "
  var first = true
  for (j <- 0 until 10 view) {
    if (first) {
      first = false
    } else {
      sb ++= ""<hr/>""
    }
    sb ++=
      "baz" ++= j.toString ++=
      " " ++= a.toString ++= " foo ";
    {
      var first = true
      for (i <- 0 until 4 view) {
        if (first) {
          first = false
        } else {
          sb ++= ","
        }
        sb ++= a.toString
        sb ++= " i="
        sb ++= i.toString
      }
    }
    sb ++= " bar\n"
  }
  sb ++= " tail"
  sb
}

val s = new StringBuilder
sb(s, 0)
s.toString

 Took 537 nanoseconds to generate a 545-characters string.
(Fast but too trivial)
java.util.Formatter 
def f(a: Int) =
    f"head ${
      (for (j <- 0 until 10 view) yield {
        f"baz$j $a foo ${
          (for (i <- 0 until 4 view) yield {
            f"$a i=$i"
          }).mkString(",")
        } bar\n"
      }).mkString("<hr/>")
    } tail"

f(0)

 Took 7436 nanoseconds to generate a 545-characters string.
(Simple but extremely slow)

Fastring is so fast because it is lazily evaluated. It avoids coping content for nested String Interpolation. Thus, Fastring is very suitable to generate complex text content(e.g. HTML, JSON).

For example, in the previous benchmark for Fastring, the most of time was spent on invoking toString. You can avoid these overhead if you do not need a whole string. For example:

// Faster than: print(fast"My lazy string from $something")
fast"My lazy string from $something".foreach(print)

You can invoke foreach because Fastring is just a Traversable[String].

Utilities

There is a mkFastring method for Seq:

// Enable mkFastring method
import com.dongxiguo.fastring.Fastring.Implicits._

// Got Fastring("Seq.mkFastring: Hello, world")
fast"Seq.mkFastring: ${Seq("Hello", "world").mkFastring(", ")}"

// Also works, but slower:
// Got Fastring("Seq.mkString: Hello, world")
fast"Seq.mkString: ${Seq("Hello", "world").mkString(", ")}"

And a leftPad method for Byte, Short, Int and Long:

// Enable leftPad method
import com.dongxiguo.fastring.Fastring.Implicits._

// Got Fastring("Int.leftPad:   123")
fast"Int.leftPad: ${123.leftPad(5)}"

// Got Fastring("Int.leftPad: 00123")
fast"Int.leftPad: ${123.leftPad(5, '0')}"

Installation

Put these lines in your build.sbt if you use Sbt:

libraryDependencies += "com.dongxiguo" %% "fastring" % "latest.release"

See http://mvnrepository.com/artifact/com.dongxiguo/fastring_2.12 if you use Maven or other build systems.

Note that Fastring requires Scala 2.10, 2.11 or 2.12.