add example, update Readme to clarify Elixir binary, #1

README.md

@@ -2,8 +2,11 @@
 https://hex.pm/packages/b58
 
 
-This module provide the `encode/1` function which takes a binary and returns
-its base58 representation
+This module provides the `Base58Encode.encode/1` function which takes an **Elixir binary** and returns its base58 String representation.
+
+See the section [What are binary in Elixir?](#What-are-binary-in-Elixir?) for more information about the binary type in Elixir.
+
+## How to use the module
 
 1. Add the package to you dependencies
 
@@ -15,28 +18,88 @@ its base58 representation
 
   and run `mix deps.get`
 
-2. Call the `encode` fundtion with a binary as parameter:
+2. Call the `encode` function with a binary as parameter:
 
  ```
- > Base58Encode.encode("foo")
- > "bQbp"
+ Base58Encode.encode("foo")
+ "bQbp"
  ```
 
- if the parameter is not a binary the function will return `:error`
+ if the parameter is not an Elixir binary the function will return `:error`. In
+ this example 42 is an Integer and not a binary (`is_binary(42)` will return `false`)
 
  ```
- > Base58Encode.encode(42)
- > "bQbp"
+ Base58Encode.encode(42)
+ :error
  ```
 
-The alphabet used for base58 is:
+ See `example/Example.exs` file for a simple example on how to use the module.
+ You can also run this example with `mix run example/Example.exs`
+
+## What is base58?
+
+`base58` provides a way to represent an **integer to a string** where the characters of the string are selected from the following list:  
+
 `123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz`
 
+The idea is to map each character of the set to a value: 0 to 1, 2 to 2 ... 57 to z.
+
+The integer is then converted to the base58 list of codes. For example 65
+is represented as a list of two codes 1 and 7:
+```
+65 % 58 = 7 (65 modulo 58 is 7 (65 - 58 * 1 = 7))
+1 % 58 = 1
+
+So 65 is represented by 1 7 codes
+```
+
+Then by matching these two codes to the base58 character set we have **28**
+
 For more information about the implementation of this module see the issue 1:
 [How to encode a string to base58](https://github.com/dwyl/base58encode/issues/1)
 
-Read the following for more information about binary in Elixir:
-https://elixir-lang.org/getting-started/binaries-strings-and-char-lists.html
-
 Wikipedia page for base58:
 https://en.wikipedia.org/wiki/Base56
+
+
+## What are binary in Elixir?
+
+From https://elixir-lang.org/getting-started/binaries-strings-and-char-lists.html
+> A `binary` is a sequence of bytes
+
+A byte is a sequence of eight bits (i.e a sequence of eight 0 or 1)
+For example the following are bytes with their decimal representation:
+
+| byte in base2 | decimal|
+| -- | -- |
+| 00000001 | 1 |
+| 00000010 | 2 |
+| 00000011 | 3 |
+| 00000100 | 4 |
+
+In Elixir binary can be represented and created with `<< >>`
+
+For example the bytes sequence `00000001 00000010 00000011 00000100`
+is `<<1, 2, 3, 4>>`
+
+All Elixir Strings are a binaries but not all binaries are String.
+a String is a binary where the numbers represent each letter in UTF8/unicode.
+One trick to see the bynary representation of a string is to add `<<0>>` at the end of the string with the concatenation operator `<>`:
+
+```
+"hello" <> <<0>>
+<<104, 101, 108, 108, 111, 0>>
+
+"hello" == <<104, 101, 108, 108, 111 >>
+true
+```
+
+**A binary in Elixir is different to a [binary number](https://en.wikipedia.org/wiki/Binary_number) which is the representation of a number in base2, e.g 110 represents 6**
+
+However 6 in Elixir is not a binary but an Integer.
+You can use the `Integer.to_string` function to see the representation of an integer in different base:
+
+```
+Integer.to_string(6, 2)
+"110"
+```

example/Example.exs

@@ -0,0 +1,8 @@
+defmodule Example do
+
+  hello = "hello"
+  helloBase58 = Base58Encode.encode(hello)
+
+  IO.puts("the \"#{hello}\" binary is represented as \"#{helloBase58}\" in base58")
+
+end

lib/base58encode.ex

@@ -32,6 +32,8 @@ defmodule Base58Encode do
  defp get_codes(int, codes) do
    rest = div(int, 58)
    code = rem(int, 58)
+   IO.inspect "rest #{rest}"
+   IO.inspect code
    if  rest == 0 do
      [code | codes]
    else