org.scalatest.matchers.LazyArg.scala Maven / Gradle / Ivy


/*
 * Copyright 2001-2013 Artima, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.scalatest.matchers

/**
 * Transforms a given object's toString with a given function lazily.
 *
 * 
 * This class is intended to be used with the mapResult method of
 * MatcherProducers, which you can use to 
 * modify error messages when composing matchers. This class exists to enable those error messages
 * to be modified lazily, so that toString is invoked on the given
 * arg, and its result transformed by the given function f, only when and if
 * the toString method is invoked on the LazyArg. As a performance optimization, ScalaTest's
 * MatchResult avoids invoking toString on objects
 * until and unless an error message is actually needed, to minimize unecessary creation and concatenation
 * of strings. The LazyArg class enables this same performance optimization when composing
 * matchers.
 * 
 *
 * 
 * The other design goal of LazyArg is to make the internal arg available for inspection
 * in an IDE. In a future version of ScalaTest, the args of MatchResult that were used
 * to create the error message will be included in the TestFailedException, so they can be inspected
 * in IDEs. This is why the arg field of LazyArg is public.
 * 
 *
 * 
 * For an example of using LazyArg, see the Composing matchers
 * section in the main documentation for trait Matcher.
 * 
 *
 * @param arg the argument
 * @param f a function that given the arg will produce a String
 */
final case class LazyArg(val arg: Any)(f: Any => String) {
 
  /**
   * Returns the result of invoking the function f, passed to the LazyArg
   * constructor, on field arg.
   */
  override def toString = f(arg.toString)
}