org.scalactic.anyvals.PosInt.scala Maven / Gradle / Ivy

Go to download
/*
 * Copyright 2001-2014 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.scalactic.anyvals

import scala.language.implicitConversions
import scala.collection.immutable.Range

/**
 * An AnyVal for positive Ints.
 *
 * Note: a PosInt may not equal 0. If you want positive
 * number or 0, use [[PosZInt]].
 *
 * 
 * Because PosInt is an AnyVal it will usually be
 * as efficient as an Int, being boxed only when an Int
 * would have been boxed.
 * 
 * 
 * 
 * The PosInt.apply factory method is implemented in terms of a macro that
 * checks literals for validity at compile time. Calling PosInt.apply with
 * a literal Int value will either produce a valid PosInt instance
 * at run time or an error at compile time. Here's an example:
 * 
 * 
 *  * scala> import anyvals._
 * import anyvals._
 *
 * scala> PosInt(1)
 * res0: org.scalactic.anyvals.PosInt = PosInt(1)
 *
 * scala> PosInt(0)
 * <console>:14: error: PosInt.apply can only be invoked on a positive (i > 0) integer literal, like PosInt(42).
 *               PosInt(0)
 *                     ^
 * 
 *
 * 
 * PosInt.apply cannot be used if the value being passed is a variable (i.e., not a literal), because
 * the macro cannot determine the validity of variables at compile time (just literals). If you try to pass a variable
 * to PosInt.apply, you'll get a compiler error that suggests you use a different factor method,
 * PosInt.from, instead:
 * 
 *
 *  * scala> val x = 1
 * x: Int = 1
 *
 * scala> PosInt(x)
 * <console>:15: error: PosInt.apply can only be invoked on an integer literal, like PosInt(42). Please use PosInt.from instead.
 *               PosInt(x)
 *                     ^
 * 
 *
 * 
 * The PosInt.from factory method will inspect the value at runtime and return an Option[PosInt]. If
 * the value is valid, PosInt.from will return a Some[PosInt], else it will return a None.
 * Here's an example:
 * 
 *
 *  * scala> PosInt.from(x)
 * res3: Option[org.scalactic.anyvals.PosInt] = Some(PosInt(1))
 *
 * scala> val y = 0
 * y: Int = 0
 *
 * scala> PosInt.from(y)
 * res4: Option[org.scalactic.anyvals.PosInt] = None
 * 
 * 
 * 
 * The PosInt.apply factory method is marked implicit, so that you can pass literal Ints
 * into methods that require PosInt, and get the same compile-time checking you get when calling
 * PosInt.apply explicitly. Here's an example:
 * 
 *
 *  * scala> def invert(pos: PosInt): Int = Int.MaxValue - pos
 * invert: (pos: org.scalactic.anyvals.PosInt)Int
 *
 * scala> invert(1)
 * res0: Int = 2147483646
 *
 * scala> invert(Int.MaxValue)
 * res1: Int = 0
 *
 * scala> invert(0)
 * <console>:15: error: PosInt.apply can only be invoked on a positive (i > 0) integer literal, like PosInt(42).
 *               invert(0)
 *                      ^
 *
 * scala> invert(-1)
 * <console>:15: error: PosInt.apply can only be invoked on a positive (i > 0) integer literal, like PosInt(42).
 *               invert(-1)
 *                       ^
 *
 * 
 *
 * 
 * This example also demonstrates that the PosInt companion object also defines implicit widening conversions
 * when either no loss of precision will occur or a similar conversion is provided in Scala. (For example, the implicit
 * conversion from Int to Float in Scala can lose precision.) This makes it convenient to
 * use a PosInt where an Int or wider type is needed. An example is the subtraction in the body
 * of the invert method defined above, Int.MaxValue - pos. Although Int.MaxValue is
 * an Int, which has no - method that takes a PosInt (the type of pos),
 * you can still subtract pos, because the PosInt will be implicitly widened to Int.
 * 
 *
 * @param value The Int value underlying this PosInt.
 */ 
final class PosInt private (val value: Int) extends AnyVal {

  /**
   * A string representation of this PosInt.
   */
  override def toString: String = s"PosInt($value)"

  /**
   * Converts this PosInt to a Byte.
   */
  def toByte: Byte = value.toByte

  /**
   * Converts this PosInt to a Short.
   */
  def toShort: Short = value.toShort

  /**
   * Converts this PosInt to a Char.
   */
  def toChar: Char = value.toChar

  /**
   * Converts this PosInt to an Int.
   */
  def toInt: Int = value.toInt

  /**
   * Converts this PosInt to a Long.
   */
  def toLong: Long = value.toLong

  /**
   * Converts this PosInt to a Float.
   */
  def toFloat: Float = value.toFloat

  /**
   * Converts this PosInt to a Double.
   */
  def toDouble: Double = value.toDouble
  /**
  * Returns the bitwise negation of this value.
  * @example {{{
  * ~5 == -6
  * // in binary: ~00000101 ==
  * // 11111010
  * }}}
  */
  def unary_~ : Int = ~value
  /** Returns this value, unmodified. */
  def unary_+ : PosInt = this
  /** Returns the negation of this value. */
  def unary_- : Int = -value
  /**
   * Converts this PosInt's value to a string then concatenates the given string.
   */
  def +(x: String): String = value + x
  /**
  * Returns this value bit-shifted left by the specified number of bits,
  * filling in the new right bits with zeroes.
  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}
  */
  def <<(x: Int): Int = value << x
  /**
  * Returns this value bit-shifted left by the specified number of bits,
  * filling in the new right bits with zeroes.
  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}
  */
  def <<(x: Long): Int = value << x
  /**
  * Returns this value bit-shifted right by the specified number of bits,
  * filling the new left bits with zeroes.
  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}
  * @example {{{
  * -21 >>> 3 == 536870909
  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 ==
  * // 00011111 11111111 11111111 11111101
  * }}}
  */
  def >>>(x: Int): Int = value >>> x
  /**
  * Returns this value bit-shifted right by the specified number of bits,
  * filling the new left bits with zeroes.
  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}
  * @example {{{
  * -21 >>> 3 == 536870909
  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 ==
  * // 00011111 11111111 11111111 11111101
  * }}}
  */
  def >>>(x: Long): Int = value >>> x
  /**
  * Returns this value bit-shifted left by the specified number of bits,
  * filling in the right bits with the same value as the left-most bit of this.
  * The effect of this is to retain the sign of the value.
  * @example {{{
  * -21 >> 3 == -3
  * // in binary: 11111111 11111111 11111111 11101011 >> 3 ==
  * // 11111111 11111111 11111111 11111101
  * }}}
  */
  def >>(x: Int): Int = value >> x
  /**
  * Returns this value bit-shifted left by the specified number of bits,
  * filling in the right bits with the same value as the left-most bit of this.
  * The effect of this is to retain the sign of the value.
  * @example {{{
  * -21 >> 3 == -3
  * // in binary: 11111111 11111111 11111111 11101011 >> 3 ==
  * // 11111111 11111111 11111111 11111101
  * }}}
  */
  def >>(x: Long): Int = value >> x
  /** Returns `true` if this value is less than x, `false` otherwise. */
  def <(x: Byte): Boolean = value < x
  /** Returns `true` if this value is less than x, `false` otherwise. */
  def <(x: Short): Boolean = value < x
  /** Returns `true` if this value is less than x, `false` otherwise. */
  def <(x: Char): Boolean = value < x
  /** Returns `true` if this value is less than x, `false` otherwise. */
  def <(x: Int): Boolean = value < x
  /** Returns `true` if this value is less than x, `false` otherwise. */
  def <(x: Long): Boolean = value < x
  /** Returns `true` if this value is less than x, `false` otherwise. */
  def <(x: Float): Boolean = value < x
  /** Returns `true` if this value is less than x, `false` otherwise. */
  def <(x: Double): Boolean = value < x
  /** Returns `true` if this value is less than or equal to x, `false` otherwise. */
  def <=(x: Byte): Boolean = value <= x
  /** Returns `true` if this value is less than or equal to x, `false` otherwise. */
  def <=(x: Short): Boolean = value <= x
  /** Returns `true` if this value is less than or equal to x, `false` otherwise. */
  def <=(x: Char): Boolean = value <= x
  /** Returns `true` if this value is less than or equal to x, `false` otherwise. */
  def <=(x: Int): Boolean = value <= x
  /** Returns `true` if this value is less than or equal to x, `false` otherwise. */
  def <=(x: Long): Boolean = value <= x
  /** Returns `true` if this value is less than or equal to x, `false` otherwise. */
  def <=(x: Float): Boolean = value <= x
  /** Returns `true` if this value is less than or equal to x, `false` otherwise. */
  def <=(x: Double): Boolean = value <= x
  /** Returns `true` if this value is greater than x, `false` otherwise. */
  def >(x: Byte): Boolean = value > x
  /** Returns `true` if this value is greater than x, `false` otherwise. */
  def >(x: Short): Boolean = value > x
  /** Returns `true` if this value is greater than x, `false` otherwise. */
  def >(x: Char): Boolean = value > x
  /** Returns `true` if this value is greater than x, `false` otherwise. */
  def >(x: Int): Boolean = value > x
  /** Returns `true` if this value is greater than x, `false` otherwise. */
  def >(x: Long): Boolean = value > x
  /** Returns `true` if this value is greater than x, `false` otherwise. */
  def >(x: Float): Boolean = value > x
  /** Returns `true` if this value is greater than x, `false` otherwise. */
  def >(x: Double): Boolean = value > x
  /** Returns `true` if this value is greater than or equal to x, `false` otherwise. */
  def >=(x: Byte): Boolean = value >= x
  /** Returns `true` if this value is greater than or equal to x, `false` otherwise. */
  def >=(x: Short): Boolean = value >= x
  /** Returns `true` if this value is greater than or equal to x, `false` otherwise. */
  def >=(x: Char): Boolean = value >= x
  /** Returns `true` if this value is greater than or equal to x, `false` otherwise. */
  def >=(x: Int): Boolean = value >= x
  /** Returns `true` if this value is greater than or equal to x, `false` otherwise. */
  def >=(x: Long): Boolean = value >= x
  /** Returns `true` if this value is greater than or equal to x, `false` otherwise. */
  def >=(x: Float): Boolean = value >= x
  /** Returns `true` if this value is greater than or equal to x, `false` otherwise. */
  def >=(x: Double): Boolean = value >= x
  /**
  * Returns the bitwise OR of this value and `x`.
  * @example {{{
  * (0xf0 | 0xaa) == 0xfa
  * // in binary: 11110000
  * // | 10101010
  * // --------
  * // 11111010
  * }}}
  */
  def |(x: Byte): Int = value | x
  /**
  * Returns the bitwise OR of this value and `x`.
  * @example {{{
  * (0xf0 | 0xaa) == 0xfa
  * // in binary: 11110000
  * // | 10101010
  * // --------
  * // 11111010
  * }}}
  */
  def |(x: Short): Int = value | x
  /**
  * Returns the bitwise OR of this value and `x`.
  * @example {{{
  * (0xf0 | 0xaa) == 0xfa
  * // in binary: 11110000
  * // | 10101010
  * // --------
  * // 11111010
  * }}}
  */
  def |(x: Char): Int = value | x
  /**
  * Returns the bitwise OR of this value and `x`.
  * @example {{{
  * (0xf0 | 0xaa) == 0xfa
  * // in binary: 11110000
  * // | 10101010
  * // --------
  * // 11111010
  * }}}
  */
  def |(x: Int): Int = value | x
  /**
  * Returns the bitwise OR of this value and `x`.
  * @example {{{
  * (0xf0 | 0xaa) == 0xfa
  * // in binary: 11110000
  * // | 10101010
  * // --------
  * // 11111010
  * }}}
  */
  def |(x: Long): Long = value | x
  /**
  * Returns the bitwise AND of this value and `x`.
  * @example {{{
  * (0xf0 & 0xaa) == 0xa0
  * // in binary: 11110000
  * // & 10101010
  * // --------
  * // 10100000
  * }}}
  */
  def &(x: Byte): Int = value & x
  /**
  * Returns the bitwise AND of this value and `x`.
  * @example {{{
  * (0xf0 & 0xaa) == 0xa0
  * // in binary: 11110000
  * // & 10101010
  * // --------
  * // 10100000
  * }}}
  */
  def &(x: Short): Int = value & x
  /**
  * Returns the bitwise AND of this value and `x`.
  * @example {{{
  * (0xf0 & 0xaa) == 0xa0
  * // in binary: 11110000
  * // & 10101010
  * // --------
  * // 10100000
  * }}}
  */
  def &(x: Char): Int = value & x
  /**
  * Returns the bitwise AND of this value and `x`.
  * @example {{{
  * (0xf0 & 0xaa) == 0xa0
  * // in binary: 11110000
  * // & 10101010
  * // --------
  * // 10100000
  * }}}
  */
  def &(x: Int): Int = value & x
  /**
  * Returns the bitwise AND of this value and `x`.
  * @example {{{
  * (0xf0 & 0xaa) == 0xa0
  * // in binary: 11110000
  * // & 10101010
  * // --------
  * // 10100000
  * }}}
  */
  def &(x: Long): Long = value & x
  /**
  * Returns the bitwise XOR of this value and `x`.
  * @example {{{
  * (0xf0 ^ 0xaa) == 0x5a
  * // in binary: 11110000
  * // ^ 10101010
  * // --------
  * // 01011010
  * }}}
  */
  def ^(x: Byte): Int = value ^ x
  /**
  * Returns the bitwise XOR of this value and `x`.
  * @example {{{
  * (0xf0 ^ 0xaa) == 0x5a
  * // in binary: 11110000
  * // ^ 10101010
  * // --------
  * // 01011010
  * }}}
  */
  def ^(x: Short): Int = value ^ x
  /**
  * Returns the bitwise XOR of this value and `x`.
  * @example {{{
  * (0xf0 ^ 0xaa) == 0x5a
  * // in binary: 11110000
  * // ^ 10101010
  * // --------
  * // 01011010
  * }}}
  */
  def ^(x: Char): Int = value ^ x
  /**
  * Returns the bitwise XOR of this value and `x`.
  * @example {{{
  * (0xf0 ^ 0xaa) == 0x5a
  * // in binary: 11110000
  * // ^ 10101010
  * // --------
  * // 01011010
  * }}}
  */
  def ^(x: Int): Int = value ^ x
  /**
  * Returns the bitwise XOR of this value and `x`.
  * @example {{{
  * (0xf0 ^ 0xaa) == 0x5a
  * // in binary: 11110000
  * // ^ 10101010
  * // --------
  * // 01011010
  * }}}
  */
  def ^(x: Long): Long = value ^ x
  /** Returns the sum of this value and `x`. */
  def +(x: Byte): Int = value + x
  /** Returns the sum of this value and `x`. */
  def +(x: Short): Int = value + x
  /** Returns the sum of this value and `x`. */
  def +(x: Char): Int = value + x
  /** Returns the sum of this value and `x`. */
  def +(x: Int): Int = value + x
  /** Returns the sum of this value and `x`. */
  def +(x: Long): Long = value + x
  /** Returns the sum of this value and `x`. */
  def +(x: Float): Float = value + x
  /** Returns the sum of this value and `x`. */
  def +(x: Double): Double = value + x
  /** Returns the difference of this value and `x`. */
  def -(x: Byte): Int = value - x
  /** Returns the difference of this value and `x`. */
  def -(x: Short): Int = value - x
  /** Returns the difference of this value and `x`. */
  def -(x: Char): Int = value - x
  /** Returns the difference of this value and `x`. */
  def -(x: Int): Int = value - x
  /** Returns the difference of this value and `x`. */
  def -(x: Long): Long = value - x
  /** Returns the difference of this value and `x`. */
  def -(x: Float): Float = value - x
  /** Returns the difference of this value and `x`. */
  def -(x: Double): Double = value - x
  /** Returns the product of this value and `x`. */
  def *(x: Byte): Int = value * x
  /** Returns the product of this value and `x`. */
  def *(x: Short): Int = value * x
  /** Returns the product of this value and `x`. */
  def *(x: Char): Int = value * x
  /** Returns the product of this value and `x`. */
  def *(x: Int): Int = value * x
  /** Returns the product of this value and `x`. */
  def *(x: Long): Long = value * x
  /** Returns the product of this value and `x`. */
  def *(x: Float): Float = value * x
  /** Returns the product of this value and `x`. */
  def *(x: Double): Double = value * x
  /** Returns the quotient of this value and `x`. */
  def /(x: Byte): Int = value / x
  /** Returns the quotient of this value and `x`. */
  def /(x: Short): Int = value / x
  /** Returns the quotient of this value and `x`. */
  def /(x: Char): Int = value / x
  /** Returns the quotient of this value and `x`. */
  def /(x: Int): Int = value / x
  /** Returns the quotient of this value and `x`. */
  def /(x: Long): Long = value / x
  /** Returns the quotient of this value and `x`. */
  def /(x: Float): Float = value / x
  /** Returns the quotient of this value and `x`. */
  def /(x: Double): Double = value / x
  /** Returns the remainder of the division of this value by `x`. */
  def %(x: Byte): Int = value % x
  /** Returns the remainder of the division of this value by `x`. */
  def %(x: Short): Int = value % x
  /** Returns the remainder of the division of this value by `x`. */
  def %(x: Char): Int = value % x
  /** Returns the remainder of the division of this value by `x`. */
  def %(x: Int): Int = value % x
  /** Returns the remainder of the division of this value by `x`. */
  def %(x: Long): Long = value % x
  /** Returns the remainder of the division of this value by `x`. */
  def %(x: Float): Float = value % x
  /** Returns the remainder of the division of this value by `x`. */
  def %(x: Double): Double = value % x

  // Stuff from RichInt:
  /**
   * Returns a string representation of this PosInt's underlying Int as an
   * unsigned integer in base 2.
   *
   * 
   * The unsigned integer value is the argument plus 2³²
   * if this PosInt's underlying Int is negative; otherwise it is equal to the
   * underlying Int.  This value is converted to a string of ASCII digits
   * in binary (base 2) with no extra leading 0s.
   * If the unsigned magnitude is zero, it is represented by a
   * single zero character '0'
   * ('\u0030'); otherwise, the first character of
   * the representation of the unsigned magnitude will not be the
   * zero character. The characters '0'
   * ('\u0030') and '1'
   * ('\u0031') are used as binary digits.
   * 
   *
   * @return  the string representation of the unsigned integer value
   *          represented by this PosInt's underlying Int in binary (base 2).
   */
  def toBinaryString: String = java.lang.Integer.toBinaryString(value)

  /**
   * Returns a string representation of this PosInt's underlying Int as an
   * unsigned integer in base 16.
   *
   * 
   * The unsigned integer value is the argument plus 2³²
   * if this PosInt's underlying Int is negative; otherwise, it is equal to the
   * this PosInt's underlying Int  This value is converted to a string of ASCII digits
   * in hexadecimal (base 16) with no extra leading
   * 0s. If the unsigned magnitude is zero, it is
   * represented by a single zero character '0'
   * ('\u0030'); otherwise, the first character of
   * the representation of the unsigned magnitude will not be the
   * zero character. The following characters are used as
   * hexadecimal digits:
   * 
   *
   * 
   *  0123456789abcdef
   * 
   *
   * These are the characters '\u0030' through
   * '\u0039' and '\u0061' through
   * '\u0066'. If uppercase letters are
   * desired, the toUpperCase method may
   * be called on the result.
   *
   * @return  the string representation of the unsigned integer value
   *          represented by this PosInt's underlying Int in hexadecimal (base 16).
   */
  def toHexString: String = java.lang.Integer.toHexString(value)

  /**
   * Returns a string representation of this PosInt's underlying Int as an
   * unsigned integer in base 8.
   *
   * The unsigned integer value is this PosInt's underlying Int plus 2³²
   * if the underlying Int is negative; otherwise, it is equal to the
   * underlying Int.  This value is converted to a string of ASCII digits
   * in octal (base 8) with no extra leading 0s.
   *
   * 
If the unsigned magnitude is zero, it is represented by a
   * single zero character '0'
   * ('\u0030'); otherwise, the first character of
   * the representation of the unsigned magnitude will not be the
   * zero character. The following characters are used as octal
   * digits:
   *
   * 

   * 01234567
   * 
   *
   * These are the characters '\u0030' through
   * '\u0037'.
   *
   * @return  the string representation of the unsigned integer value
   *          represented by this PosInt's underlying Int in octal (base 8).
   */
  def toOctalString: String = java.lang.Integer.toOctalString(value)

  /**
  * Create a Range from this PosInt value
  * until the specified end (exclusive) with step value 1.
  *
  * @param end The final bound of the range to make.
  * @return A [[scala.collection.immutable.Range]] from `this` up to but
  * not including `end`.
  */
  def until(end: Int): Range = Range(value, end)

  /**
  * Create a Range from this PosInt value
  * until the specified end (exclusive) with the specified step value.
  *
  * @param end The final bound of the range to make.
  * @param step The number to increase by for each step of the range.
  * @return A [[scala.collection.immutable.Range]] from `this` up to but
  * not including `end`.
  */
  def until(end: Int, step: Int): Range = Range(value, end, step)

  /**
  * Create an inclusive Range from this PosInt value
  * to the specified end with step value 1.
  *
  * @param end The final bound of the range to make.
  * @return A [[scala.collection.immutable.Range]] from `'''this'''` up to
  * and including `end`.
  */
  def to(end: Int): Range.Inclusive = Range.inclusive(value, end)

  /**
  * Create an inclusive Range from this PosInt value
  * to the specified end with the specified step value.
  *
  * @param end The final bound of the range to make.
  * @param step The number to increase by for each step of the range.
  * @return A [[scala.collection.immutable.Range]] from `'''this'''` up to
  * and including `end`.
  */
  def to(end: Int, step: Int): Range.Inclusive = Range.inclusive(value, end, step)

  // No point to call abs on a PosInt.
  /**
  * Returns this if this > that or that otherwise.
  */
  def max(that: PosInt): PosInt = if (math.max(value, that.value) == value) this else that

  /**
  * Returns this if this < that or that otherwise.
  */
  def min(that: PosInt): PosInt = if (math.min(value, that.value) == value) this else that
}

/**
 * The companion object for PosInt that offers factory methods that
 * produce PosInts, implicit widening conversions from PosInt
 * to other numeric types, and maximum and minimum constant values for PosInt.
 */
object PosInt {
  /**
   * The largest value representable as a positive Int, which is PosInt(2147483647).
   */
  final val MaxValue: PosInt = PosInt.from(Int.MaxValue).get
  /**
   * The smallest value representable as a positive Int, which is PosInt(1).
   */
  final val MinValue: PosInt = PosInt.from(1).get // Can't use the macro here

  // TODO: Use one method for validation, as suggested in I think the UK.

  /**
   * A factory method that produces an Option[PosInt] given an
   * Int value.
   *
   * 
   * This method will inspect the passed Int value and if
   * it is a positive Int, i.e., a value greater
   * than 0, it will return a PosInt representing that value,
   * wrapped in a Some. Otherwise, the passed Int
   * value is 0 or negative, so this method will return None.
   * 
   *
   * 
   * This factory method differs from the apply factory method
   * in that apply is implemented via a macro that inspects
   * Int literals at compile time, whereas from inspects
   * Int values at run time. 
   * 
   *
   * @param value the Int to inspect, and if positive, return
   *     wrapped in a Some[PosInt].
   * @return the specified Int value wrapped
   *     in a Some[PosInt], if it is positive, else None.
   */
  def from(value: Int): Option[PosInt] =
    if (PosIntMacro.isValid(value)) Some(new PosInt(value)) else None

  import language.experimental.macros

  /**
   * A factory method, implemented via a macro, that produces a PosInt
   * if passed a valid Int literal, otherwise a compile time error.
   *
   * 
   * The macro that implements this method will inspect the specified Int
   * expression at compile time. If
   * the expression is a positive Int literal, i.e., with a
   * value greater than 0, it will return a PosInt representing that value.
   * Otherwise, the passed Int 
   * expression is either a literal that is 0 or negative, or is not a literal, so
   * this method will give a compiler error.
   * 
   *
   * 
   * This factory method differs from the from factory method
   * in that this method is implemented via a macro that inspects
   * Int literals at compile time, whereas from inspects
   * Int values at run time. 
   * 
   *
   * @param value the Int literal expression to inspect at compile time,
   *     and if positive, to return wrapped in a PosInt at run time.
   * @return the specified, valid Int literal value wrapped
   *     in a PosInt. (If the specified expression is not a valid
   *     Int literal, the invocation of this method will not
   *     compile.)
   */
  implicit def apply(value: Int): PosInt = macro PosIntMacro.apply

  /**
   * Implicit widening conversion from PosInt to Int.
   *
   * @param pos the PosInt to widen
   * @return the Int value underlying the specified PosInt.
   */
  implicit def widenToInt(pos: PosInt): Int = pos.value

  /**
   * Implicit widening conversion from PosInt to Long.
   *
   * @param pos the PosInt to widen
   * @return the Int value underlying the specified PosInt,
   *     widened to Long.
   */
  implicit def widenToLong(pos: PosInt): Long = pos.value

  /**
   * Implicit widening conversion from PosInt to Float.
   *
   * @param pos the PosInt to widen
   * @return the Int value underlying the specified PosInt,
   *     widened to Float.
   */
  implicit def widenToFloat(pos: PosInt): Float = pos.value

  /**
   * Implicit widening conversion from PosInt to Double.
   *
   * @param pos the PosInt to widen
   * @return the Int value underlying the specified PosInt,
   *     widened to Double.
   */
  implicit def widenToDouble(pos: PosInt): Double = pos.value

  /**
   * Implicit widening conversion from PosInt to PosLong.
   *
   * @param pos the PosInt to widen
   * @return the Int value underlying the specified PosInt,
   *     widened to Long and wrapped in a PosLong.
   */
  implicit def widenToPosLong(pos: PosInt): PosLong = PosLong.from(pos.value).get

  /**
   * Implicit widening conversion from PosInt to PosFloat.
   *
   * @param pos the PosInt to widen
   * @return the Int value underlying the specified PosInt,
   *     widened to Float and wrapped in a PosFloat.
   */
  implicit def widenToPosFloat(pos: PosInt): PosFloat = PosFloat.from(pos.value).get

  /**
   * Implicit widening conversion from PosInt to PosDouble.
   *
   * @param pos the PosInt to widen
   * @return the Int value underlying the specified PosInt,
   *     widened to Double and wrapped in a PosDouble.
   */
  implicit def widenToPosDouble(pos: PosInt): PosDouble = PosDouble.from(pos.value).get

  /**
   * Implicit widening conversion from PosInt to PosZInt.
   *
   * @param pos the PosInt to widen
   * @return the Int value underlying the specified PosInt,
   wrapped in a PosZInt.
   */
  implicit def widenToPosZInt(pos: PosInt): PosZInt = PosZInt.from(pos.value).get

  /**
   * Implicit widening conversion from PosInt to PosZLong.
   *
   * @param pos the PosInt to widen
   * @return the Int value underlying the specified PosInt,
   *     widened to Long and wrapped in a PosZLong.
   */
  implicit def widenToPosZLong(pos: PosInt): PosZLong = PosZLong.from(pos.value).get

  /**
   * Implicit widening conversion from PosInt to PosZFloat.
   *
   * @param pos the PosInt to widen
   * @return the Int value underlying the specified PosInt,
   *     widened to Float and wrapped in a PosZFloat.
   */
  implicit def widenToPosZFloat(pos: PosInt): PosZFloat = PosZFloat.from(pos.value).get

  /**
   * Implicit widening conversion from PosInt to PosZDouble.
   *
   * @param pos the PosInt to widen
   * @return the Int value underlying the specified PosInt,
   *     widened to Double and wrapped in a PosZDouble.
   */
  implicit def widenToPosZDouble(pos: PosInt): PosZDouble = PosZDouble.from(pos.value).get

  /**
   * Implicit Ordering instance.
   */
  implicit val posIntOrd: Ordering[PosInt] =
    new Ordering[PosInt] {
      def compare(x: PosInt, y: PosInt): Int = x - y
    } 
}