add a doc about stream

mana-ethereum · Feb 23, 2023 · da295a7 · da295a7
1 parent cafa8e8
commit da295a7
Show file tree

Hide file tree

Showing 2 changed files with 11 additions and 6 deletions.
diff --git a/lib/ex_rlp.ex b/lib/ex_rlp.ex
@@ -54,19 +54,27 @@ defmodule ExRLP do
   """
   @spec encode(t) :: binary()
   @spec encode(t, keyword()) :: binary()
-  def encode(item, options \\ [encoding: :binary]) do
+  def encode(item, options \\ []) do
     Encode.encode(item, options)
   end
 
   @doc """
   Given an RLP-encoded string, returns a decoded RPL structure (which is an
   array of RLP structures or binaries).
 
+  If stream (`[stream: true]`) is enabled, it will just decode the first rlp sequence
+
   ## Examples
 
       iex> ExRLP.decode(<<>>)
       ** (ExRLP.DecodeError) invalid rlp encoding
 
+      iex> ExRLP.decode(<<0xc8, 0x83, ?c, ?a, ?t, 0x83, ?d, ?o, ?g>>)
+      ["cat", "dog"]
+
+      iex> ExRLP.decode(<<131, 99, 97, 116, 131, 99, 97, 116>>, stream: true)
+      {"cat", <<131, 99, 97, 116>>}
+
       iex> ExRLP.decode(<<0x83, ?d, ?o, ?g>>)
       "dog"
 
@@ -76,9 +84,6 @@ defmodule ExRLP do
       iex> ExRLP.decode(<<184, 60, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65>>)
       Enum.join(for _ <- 1..60, do: "A")
 
-      iex> ExRLP.decode(<<0xc8, 0x83, ?c, ?a, ?t, 0x83, ?d, ?o, ?g>>)
-      ["cat", "dog"]
-
       iex> ExRLP.decode(<<198, 51, 132, 99, 111, 111, 108>>)
       ["3", "cool"]
 
@@ -105,7 +110,7 @@ defmodule ExRLP do
 
   """
   @spec decode(binary()) :: t
-  @spec decode(binary(), keyword()) :: t
+  @spec decode(binary(), keyword()) :: t() | {t(), binary()} | no_return()
   def decode(item, options \\ [encoding: :binary]) do
     Decode.decode(item, options)
   end

diff --git a/lib/ex_rlp/decode.ex b/lib/ex_rlp/decode.ex
@@ -2,7 +2,7 @@ defmodule ExRLP.Decode do
   @moduledoc false
 
   alias ExRLP.DecodeItem
-  @spec decode(binary(), keyword()) :: ExRLP.t()
+  @spec decode(binary(), keyword()) :: ExRLP.t() | {ExRLP.t(), binary()} | no_return()
   def decode(item, options \\ [])
 
   def decode("", _), do: raise(ExRLP.DecodeError)