Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
107 lines (95 sloc) 13.4 KB

scodec Cheatsheet

scodec comes with a large number of predefined codecs and combinators.

This list is a work-in-progress overview over the predefined codecs.

Primitive Codecs

Name Result Type Description Min Bits Max Bits Coding Examples
bits scodec.bits.BitVector All the remaining bits 0 bin"11010110101"11010110 101₂ (11 bits)
bytes scodec.bits.ByteVector All the remaining bytes 0 hex"5468697320697320"54 68 69 73 20 69 73 20₁₆ (8 bytes)
byte Byte A single byte 8 8 89: Byte59₁₆ (1 byte)
ushort8 Short 8-bit unsigned short 8 8 240: Shortf0₁₆ (1 byte)
short16 Short 16-bit big-endian short 16 16 0x1234: Short12 34₁₆ (2 bytes)
int8 Int 8-bit integer 8 8 0x1212₁₆ (1 byte)
int16 Int 16-bit big-endian integer 16 16 0x123412 34₁₆ (2 bytes)
int24 Int 24-bit big-endian integer 24 24 0x12345612 34 56₁₆ (3 bytes)
int32 Int 32-bit big-endian integer 32 32 0x1234567812 34 56 78₁₆ (4 bytes)
int64 Long 64-bit big-endian integer 64 64 0x12345678abcdefL00 12 34 56 78 ab cd ef₁₆ (8 bytes)
uint2 Int 2-bit unsigned integer 2 2 0x311₂ (2 bits)
uint4 Int 4-bit unsigned integer 4 4 0x60110₂ (4 bits)
uint8 Int 8-bit unsigned integer 8 8 0xadad₁₆ (1 byte)
uint16 Int 16-bit big-endian unsigned integer 16 16 0xadacad ac₁₆ (2 bytes)
uint32 Long 32-bit big-endian unsigned integer 32 32 0x81234567L81 23 45 67₁₆ (4 bytes)
int8L Int 8-bit little-endian integer 8 8 0x1212₁₆ (1 byte)
int16L Int 16-bit little-endian integer 16 16 0x123434 12₁₆ (2 bytes)
int24L Int 24-bit little-endian integer 24 24 0x12345656 34 12₁₆ (3 bytes)
int32L Int 32-bit little-endian integer 32 32 0x1234567878 56 34 12₁₆ (4 bytes)
int64L Long 64-bit little-endian integer 64 64 0x12345678abcdefLef cd ab 78 56 34 12 00₁₆ (8 bytes)
uint2L Int 2-bit little-endian unsigned integer 2 2 0x311₂ (2 bits)
uint4L Int 4-bit little-endian unsigned integer 4 4 0x60110₂ (4 bits)
uint8L Int 8-bit little-endian unsigned integer 8 8 0xadad₁₆ (1 byte)
uint16L Int 16-bit little-endian unsigned integer 16 16 0xadacac ad₁₆ (2 bytes)
uint32L Long 32-bit little-endian unsigned integer 32 32 0x81234567L67 45 23 81₁₆ (4 bytes)
vint Int Variable-length big-endian integer 1 5 0x0101₁₆ (1 byte)
0x123a3 02₁₆ (2 bytes)
0x1234b4 24₁₆ (2 bytes)
0x12345c5 c6 04₁₆ (3 bytes)
0x123456d6 e8 48₁₆ (3 bytes)
0x1234567e7 8a 8d 09₁₆ (4 bytes)
0x12345678f8 ac d1 91 01₁₆ (5 bytes)
vintL Int Variable-length little-endian integer 1 5 0x123456c8 e8 56₁₆ (3 bytes)
vlong Long Variable-length big-endian long 1 9 0x81234567abcdLcd d7 9e ab b4 a4 20₁₆ (7 bytes)
vlongL Long Variable-length little-endian long 1 9 0x81234567abcdLa0 a4 b4 ab 9e d7 4d₁₆ (7 bytes)
vpbcd Long Variable-length packed decimal longs 1 9 1L0001₂ (4 bits)
123L00010010 0011₂ (12 bits)
12345L00010010 00110100 0101₂ (20 bits)
12345678901L00010010 00110100 01010110 01111000 10010000 0001₂ (44 bits)
float Float 32-bit big-endian IEEE 754 floating point number 32 32 1.234234387f3f 9d fb 64₁₆ (4 bytes)
floatL Float 32-bit little-endian IEEE 754 floating point number 32 32 1.234234387f64 fb 9d 3f₁₆ (4 bytes)
double Double 64-bit big-endian IEEE 754 floating point number 64 64 1.234234387d3f f3 bf 6c 8e 7c 37 bd₁₆ (8 bytes)
doubleL Double 64-bit little-endian IEEE 754 floating point number 64 64 1.234234387dbd 37 7c 8e 6c bf f3 3f₁₆ (8 bytes)
bool Boolean 1-bit boolean 1 1 true1₂ (1 bit)
ascii String US-ASCII String consuming remaining input 0 "The lazy dog"54 68 65 20 6c 61 7a 79 20 64 6f 67₁₆ (12 bytes)
utf8 String UTF8 String consuming remaining input 0 "árvíztűrő ütvefúrógép"c3 a1 72 76 c3 ad 7a 74 c5 b1 72 c5 91 20 c3 bc 74 76 65 66 c3 ba 72 c3 b3 67 c3 a9 70₁₆ (29 bytes)
cstring String Null-terminated US-ASCII String 0 "The lazy dog"54 68 65 20 6c 61 7a 79 20 64 6f 67 00₁₆ (13 bytes)
ascii32 String US-ASCII String prefixed by 32-bit 2s complement big-endian size field 32 "The lazy dog"00 00 00 0c 54 68 65 20 6c 61 7a 79 20 64 6f 67₁₆ (16 bytes)
ascii32L String US-ASCII String prefixed by 32-bit 2s complement little-endian size field 32 "The lazy dog"0c 00 00 00 54 68 65 20 6c 61 7a 79 20 64 6f 67₁₆ (16 bytes)
utf8_32 String UTF8 String prefixed by 32-bit 2s complement big-endian size field 32 "árvíztűrő ütvefúrógép"00 00 00 1d c3 a1 72 76 c3 ad 7a 74 c5 b1 72 c5 91 20 c3 bc 74 76 65 66 c3 ba 72 c3 b3 67 c3 a9 70₁₆ (33 bytes)
utf8_32L String UTF8 String prefixed by 32-bit 2s complement little-endian size field 32 "árvíztűrő ütvefúrógép"1d 00 00 00 c3 a1 72 76 c3 ad 7a 74 c5 b1 72 c5 91 20 c3 bc 74 76 65 66 c3 ba 72 c3 b3 67 c3 a9 70₁₆ (33 bytes)
uuid java.util.UUID UUID as 2 64-bit big-endian longs 128 128 UUID.fromString("f41561aa-f759-4cde-ab07-c0c0cc0db8d8")f4 15 61 aa f7 59 4c de ab 07 c0 c0 cc 0d b8 d8₁₆ (16 bytes)

Parameterized Codecs

Name Description Example usage Example result type Example Min Bits Example Max Bits Coding Examples
constant Constant bits constant(bin"110101") Unit 6 6 ()110101₂ (6 bits)
constant Constant bits constant(bin"10") Unit 2 2 ()10₂ (2 bits)
constant Constant bytes constant(hex"1234567890") Unit 40 40 ()12 34 56 78 90₁₆ (5 bytes)
constant Constant bytes constant(hex"abcdef") Unit 24 24 ()ab cd ef₁₆ (3 bytes)
constant Constant bytes constant(0x42: Byte) Unit 8 8 ()42₁₆ (1 byte)
constant Constant bytes from integral constant(0x2342: Short, 0x42: Short) Unit 16 16 ()42 42₁₆ (2 bytes)
constant Constant bytes from integral constant(0x2342: Int, 0x42: Short) Unit 16 16 ()42 42₁₆ (2 bytes)
constant Constant bytes from integral constant(0x2342: Long, 0x42: Short) Unit 16 16 ()42 42₁₆ (2 bytes)

Combinators

Name Description Example usage Example result type Example Min Bits Example Max Bits Coding Examples
hlist Convert codec to HList uint8.hlist Int :: HNil 8 8 42 :: HNil2a₁₆ (1 byte)
pairedWith Concat two codecs into a 2-tuple uint8 pairedWith uint16 (Int, Int) 24 24 (0x12, 0x3456)12 34 56₁₆ (3 bytes)
pairedWith Concat two codecs into a 2-tuple uint8 pairedWith uint16 pairedWith cstring ((Int, Int), String) 24 ((0x12, 0x3456), "abc")12 34 56 61 62 63 00₁₆ (7 bytes)
~ Concat two codecs into a 2-tuple uint8 ~ uint16 (Int, Int) 24 24 (0x12, 0x3456)12 34 56₁₆ (3 bytes)
~ Concat two codecs into a 2-tuple uint8 ~ uint16 ~ cstring ((Int, Int), String) 24 ((0x12, 0x3456), "abc")12 34 56 61 62 63 00₁₆ (7 bytes)
flattenLeftPairs Removes left tuple nesting and converts to HList uint8 ~ uint16 ~ cstring flattenLeftPairs Int :: Int :: String :: HNil 24 0x12 :: 0x3456 :: "abc" :: HNil12 34 56 61 62 63 00₁₆ (7 bytes)
dropLeft Concat two codecs discarding the Unit value of the left one constant(0x12) dropLeft uint8 Int 16 16 0x6812 68₁₆ (2 bytes)
~> Concat two codecs discarding the Unit value of the left one constant(0x12) ~> uint8 Int 16 16 0x6812 68₁₆ (2 bytes)
dropRight Concat two codecs discarding the Unit value of the right one uint8 dropRight constant(0x12) Int 16 16 0x6868 12₁₆ (2 bytes)
<~ Concat two codecs discarding the Unit value of the right one uint8 <~ constant(0x12) Int 16 16 0x6868 12₁₆ (2 bytes)
flatZip Concat two codecs into a 2-tuple where the second codec is choosen depending on the result of the first. uint8 flatZip { case i if i < 100 ⇒ uint8; case _ ⇒ uint16 } (Int, Int) 8 (23, 42)17 2a₁₆ (2 bytes)
(112, 0x1234)70 12 34₁₆ (3 bytes)
>>~ Concat two codecs into a 2-tuple where the second codec is choosen depending on the result of the first. uint8 >>~ { case i if i < 100 ⇒ uint8; case _ ⇒ uint16 } (Int, Int) 8 (23, 42)17 2a₁₆ (2 bytes)
(112, 0x1234)70 12 34₁₆ (3 bytes)
consume Decodes the left codec and then the right codec depending on the left result, then discards the left value and returns only the right byteAligned(bool).consume[Int](isLarge ⇒ if (isLarge) uint16 else uint8)(_ > 0xff) Int 8 25500 ff₁₆ (2 bytes)
25680 01 00₁₆ (3 bytes)
0x123480 12 34₁₆ (3 bytes)
:: Concat two codecs into an HList uint8 :: cstring Int :: String :: HNil 8 0x42 :: "zweiundvierzig" :: HNil42 7a 77 65 69 75 6e 64 76 69 65 72 7a 69 67 00₁₆ (16 bytes)
dropUnits Remove Unit elements from an HList codec constant(hex"ca fe") :: cstring).dropUnits String :: HNil 16 "dreiundzwanzig" :: HNilca fe 64 72 65 69 75 6e 64 7a 77 61 6e 7a 69 67 00₁₆ (17 bytes)
:~>: Concat two codecs discarding the Unit value of the left one constant(hex"ab cd ef") :~>: uint16 :: uint8 Int :: Int :: HNil 48 48 0x1234 :: 0x23 :: HNilab cd ef 12 34 23₁₆ (6 bytes)
:+ Append to left HList codec the right codec. uint8.hlist :+ uint16 Int :: Int :: HNil 24 24 0x42 :: 0xcdef :: HNil42 cd ef₁₆ (3 bytes)
::: Concat two HList codecs (uint8 :: cstring) ::: (constant(0x23) :: uint16) Int :: String :: Unit :: Int :: HNil 32 0x42 :: "zweiundvierzig" :: () :: 0xabcd :: HNil42 7a 77 65 69 75 6e 64 76 69 65 72 7a 69 67 00 23 ab cd₁₆ (19 bytes)
flatZipHList Concat to HList result of first Codec with result of Codec determined after based on value of first part uint8 flatZipHList { case strSize ⇒ limitedSizeBytes(strSize, utf8) } Int :: String :: HNil 8 8 :: "sausages" :: HNil08 73 61 75 73 61 67 65 73₁₆ (9 bytes)
flatPrepend Concat to HList result of first Codec with result of HList Codec determined after based on value of first part uint8 flatPrepend { case strSize ⇒ limitedSizeBytes(strSize, utf8) :: uint16 } Int :: String :: Int :: HNil 8 8 :: "sausages" :: 0x1234 :: HNil08 73 61 75 73 61 67 65 73 12 34₁₆ (11 bytes)
>>:~ Concat to HList result of first Codec with result of HList Codec determined after based on value of first part uint8 >>:~ { case strSize ⇒ limitedSizeBytes(strSize, utf8) :: uint16 } Int :: String :: Int :: HNil 8 8 :: "sausages" :: 0x1234 :: HNil08 73 61 75 73 61 67 65 73 12 34₁₆ (11 bytes)
flatAppend Concat result of first HList Codec with result of Codec determined after based on value of first part uint8 :: uint16 flatAppend { case strSize :: _ :: HNil ⇒ limitedSizeBytes(strSize, utf8) } Int :: Int :: String :: HNil 24 8 :: 0xabcd :: "sausages" :: HNil08 ab cd 73 61 75 73 61 67 65 73₁₆ (11 bytes)
flatConcat Concat result of first HList Codec with result of HList Codec determined after based on value of first part uint8 :: uint16 flatConcat { case strSize :: _ :: HNil ⇒ limitedSizeBytes(strSize, utf8) :: uint16 } Int :: Int :: String :: Int :: HNil 24 8 :: 0xabcd :: "sausages" :: 0x1234 :: HNil08 ab cd 73 61 75 73 61 67 65 73 12 34₁₆ (13 bytes)

Contributing

  • Add or edit meta information in PrimitiveCodecs.scala, ParameterizedCodecs.scala, or CodecCombinators.scala
  • Run sbt "generator/runMain scodec.meta.CheatSheetGenerator" to regenerate the table (the generator will replace all content in this file between lines starting with ## Primitive Codecs and ## Contributing)
  • Commit changes + PR

License

This cheat sheet was original created by Johannes Rudolph. This document and the accompanying source code is freely available under the CC0 license.

You can’t perform that action at this time.