Commit 640aaa04 authored by Luciano Joublanc's avatar Luciano Joublanc

Add scala doc to Primitives for #9.

parent b0c4f753
Pipeline #83580312 failed with stages
in 4 minutes and 50 seconds
......@@ -65,7 +65,8 @@ trait Implicits { self: Primitives =>
): PartialCodec.Aux[Map[K, V], 2] =
mapField(kCodec, vCodec)
implicit def packedList[A, W <: Int]( //TODO Not sure if context bound is excessive e.g. coproducts won't work.
/** By default, primitive types resolve to the packed list codec. */
implicit def implicitPackedList[A, W <: Int](
implicit field: PartialCodec.Aux[A, W],
isScalar: W =:!= 2
): PartialCodec.Aux[List[A], 2] =
......@@ -83,6 +84,7 @@ trait Implicits { self: Primitives =>
new ValueOf(H.value :: T.value)
implicit lazy val valueOfHNil: ValueOf[HNil] = new ValueOf(HNil)
implicit def implicitMessage[A, L <: HList, O <: HList](
implicit isProduct: Generic.Aux[A, L],
msg: Message.Aux[L, O],
......@@ -112,7 +114,7 @@ trait Implicits { self: Primitives =>
protected trait LowPrioImplicitCodecs {
/** Packed codecs take priority over this */
implicit def unpackedList[A, W <: Int](
implicit def implicitUnpackedList[A, W <: Int](
implicit field: PartialCodec.Aux[A, W]
): PartialCodec.Aux[List[A], W] =
repeated(field, packed = false)
......
......@@ -3,11 +3,15 @@ package scodec.protocols.protobuf.v3
import scodec.Codec
/** Codecs for the primitive elements in protobuffers. These are not 'full'
* codecs as they don't framing information, i.e. the index + wire-type
* information.
* codecs as they don't include framing information, i.e. the index +
* wire-type information.
*
* The API doc has been mostly copied from
* [[https://developers.google.com/protocol-buffers/docs/proto3#scalar this]]
* table.
*
* @see [[https://developers.google.com/protocol-buffers/docs/encoding]] for
* a description of each codec.
* the specification.
*/
trait Primitives { self =>
......@@ -17,42 +21,83 @@ trait Primitives { self =>
/** The type used to represent unsinged 64-bit integers. */
type ULong
/** Witness that [[UInt]] is a `scala.math.Integral`. */
/** Witness that [[UInt]] is a `scala.math.Integral`.
* This guarantees portability across platforms. A typical implementation will
* have an `implicit instance: Integral[UInt]` in the companion of `UInt`.
* @example {{{
* scala> import JVMPrimitives.{UInt, ULong}
* scala> import Integral.Implicits._
*
* scala> UInt(1) + UInt(2)
* res1: scodec.protocols.protobuf.v3.JVMPrimitives.UInt = UInt(3)
* }}}
*/
def uintIsIntegral: Integral[UInt]
/** Witness that [[ULong]] is a `scala.math.Integral`. */
/** Witness that [[ULong]] is a `scala.math.Integral`.
* @see [[uintIsIntegral]] for further explanation
*/
def ulongIsIntegral: Integral[ULong]
/** IEEE 754 double precision binary. */
def double: PartialCodec.Aux[Double, 1]
/** IEEE 754 single precision binary. */
def float: PartialCodec.Aux[Float, 5]
/** Uses variable-length encoding. Inefficient for encoding negative numbers
* – if your field is likely to have negative values, use [[sint32]] instead.
*/
def int32: PartialCodec.Aux[Int, 0]
/** Uses variable-length encoding. Inefficient for encoding negative numbers
* – if your field is likely to have negative values, use [[sint64]] instead.
*/
def int64: PartialCodec.Aux[Long, 0]
/** Uses variable-length encoding. */
def uint32: PartialCodec.Aux[UInt, 0]
/** Uses variable-length encoding. */
def uint64: PartialCodec.Aux[ULong, 0]
/** Uses variable-length encoding. Signed `int` value. These more efficiently
* encode negative numbers than regular [[int32]]s.
*/
def sint32: PartialCodec.Aux[Int, 0]
/** Uses variable-length encoding. Signed `int` value. These more efficiently
* encode negative numbers than regular [[int64]]s.
*/
def sint64: PartialCodec.Aux[Long, 0]
/** Always four bytes. More efficient than [[uint32]] if values are often
* greater than 228.
*/
def fixed32: PartialCodec.Aux[UInt, 5]
/** Always eight bytes. More efficient than [[uint64]] if values are often
* greater than 256. */
def fixed64: PartialCodec.Aux[ULong, 1]
/** Always four bytes. */
def sfixed32: PartialCodec.Aux[Int, 5]
/** Always eight bytes. */
def sfixed64: PartialCodec.Aux[Long, 1]
/** Always one byte. */
def bool: PartialCodec.Aux[Boolean, 0]
/** A string must always contain UTF-8 encoded or 7-bit ASCII text, and
* cannot be longer than 232.
* @param charset Default to UTF-8.
*/
def string(
implicit charset: java.nio.charset.Charset
): PartialCodec.Aux[String, 2]
/** May contain any arbitrary sequence of bytes no longer than 232. */
def bytes: PartialCodec.Aux[scodec.bits.ByteVector, 2]
protected[protobuf] def lengthDelimited[A] =
......
......@@ -40,8 +40,22 @@ import java.nio.charset.Charset
*
* scala> scodec.Codec[Foo].decode(res2.require)
* res4: scodec.Attempt[scodec.DecodeResult[Foo]] = Successful(DecodeResult(Foo(1,two),BitVector(empty)))
*
* scala> case class Choice(stringOrInt: Either[String, Int])
* defined class Choice
*
* // implicit derivation of a sealed trait ( Either is a Left or Right )
* scala> scodec.Codec[Choice]
* res5: scodec.Codec[Choice]
*
* }}}
*
* Note that implicit codecs will only resolve for top-level message objects i.e. `case class`es.
* For example, trying to summon a `Codec[Int]` will fail, but `Codec[Tuple1[Int]]` will work.
*
* So, if you have automatic implicit derivation, why would you want to use explicit codecs at all?
* - You are replicating a schema with out-of-order field indices.
*
*/
package object v3 extends ProtoBuf with JVMPrimitives with JVMImplicits {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment