bytes 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a17c54ac2788c884d6e1d8605b54621fe1707cf3252bbc6c81ad062e4dda6ca2
-  data.tar.gz: 23189f40e8c5459ccd8d53a2796524d0b3b217dd13749e48f406652683b3367d
+  metadata.gz: 5a8baa99382e45238e96527a5aab45a04daf4b73a2d4e1f64b3bf87530e14a7d
+  data.tar.gz: ec170b28a4efd3d7b0cdf45094831a68a86d60785f313668baa24cbf5a106085
 SHA512:
-  metadata.gz: 6203bdf2072f6fc54b01029a1de95896bc7d5eb37690b30f0186dc5615bc87ed098fb9b2542d9e9c29e6c2571f3bb8bc1793d802851de0da4910163fa74a75c1
-  data.tar.gz: e1aa00e67da7a420a6f791a7ed7954a0c229d553b1c1b9e284968e69b860c85150409cacd79fe1e4bf3e16a1d954b6c2ed8dee6c380404f4e89841835cbd00b7
+  metadata.gz: 8f62ad42592bfd8e69fb9bf53526ba19e3568b7140f88bfa9bf524ee1ac8af3258dd2d156f6080d08e63ecbcb92cf0e8f531f56f4c3b32faad8477b7efdf8423
+  data.tar.gz: 728487df6ca9ad9cbe4aedcc2ae76c3f7018c195a780a5e4ef7ee487602cf0ac7fadff8b5c31b38a6e18f6a324947a1ae7e51f3c693bb65ae000ce6461a54969

data/README.md

@@ -8,6 +8,246 @@ bytes - bits 'n' bytes made easy/easier incl. new buffer helper / wrapper class
 * rdoc  :: [rubydoc.info/gems/bytes](http://rubydoc.info/gems/bytes)
 
 
+## Background -  Programming Bits, Bytes 'n' Blocks Step-by-Step Book / Guide
+
+_Let's start with the three types of strings, that is, bytes, (string) buffers, and (frozen) strings, ..._
+
+
+### Byte vs. Character
+
+
+#### What's a Byte?
+
+A byte is a 8-bit integer number (that is, unsigned from 0 to 255 or
+signed from -128 to 127 using 2's complement).
+Example:
+
+``` ruby
+0b01000001              #=> 65  - base 2  - binary bits
+65                      #=> 65  - base 10 - decimal numbers
+0x41                    #=> 65  - base 16 - hexadecimal numbers
+[0b01000001, 65, 0x41]
+#=> [65, 65, 65]
+```
+
+Or with conversions to 8-bit integer numbers. Example:
+
+``` ruby
+"01000001".to_i(2)     #=> 65
+"65".to_i(10)          #=> 65
+"65".to_i              #=> 65 - same as to_i(10)
+"41".to_i(16)          #=> 65
+"0x41".to_i(16)        #=> 65 - same as "41" - 0x hex prefix gets skipped
+["01000001".to_i(2), "65".to_i(10), "41".to_i(16)]
+#=> [65, 65, 65]
+```
+
+Note:  `String#hex` is a built-in short-cut / alias for `String#to_i(16)`.  Example:
+
+``` ruby
+"41".hex          #=> 65
+"0x41".hex        #=> 65 - same as "41" - 0x hex prefix gets
+```
+
+
+
+#### What's a Character?
+
+A character (or char) used to be a byte
+and, thus, a string (array) of characters
+was also an array of bytes. Example:
+
+``` ruby
+?A.ord        #=> 65 - ASCII character
+"A".ord       #=> 65 - ASCII character
+"\x41".ord    #=> 65 - ASCII character
+[?A.ord, "A".ord, "\x41".ord]
+#=> [65, 65, 65]
+```
+
+
+
+History Nostalgia Corner: ASCII 7-Bit Character Encoding
+
+![](i/us_ascii_code_chart.png)
+
+> ASCII abbreviated from American Standard Code for Information Interchange,
+> is a character encoding standard for electronic communication. ASCII codes
+> represent text in computers, telecommunications equipment, and other devices.
+> Most modern character-encoding schemes are based on ASCII,
+> although they support many additional characters.
+>
+> ASCII is the traditional name for the encoding system; the Internet Assigned
+> Numbers Authority (IANA) prefers the updated name US-ASCII, which clarifies
+> that this system was developed in the US and based on the typographical
+> symbols predominantly in use there.
+>
+> (Source: [ASCII @ Wikipedia](https://en.wikipedia.org/wiki/ASCII))
+
+
+
+Nowadays a character can have one, two or even more bytes.
+Let's try:
+
+``` ruby
+## Latin Capital Letter A (Unicode) - 1 Byte
+"A".bytes          #=> [65]
+"\x41".bytes       #=> [65] - same as "A"
+"\u0041".bytes     #=> [65]
+"\u{41}".bytes     #=> [65] - same as "\u0041" - leading zeros can be dropped
+"A".bytes.size     #=> 1
+"A".chars.size     #=> 1
+
+## Cyrillic Capital Letter A (Unicode) - 2 Bytes
+"А".bytes          #=> [208, 144]
+"\u0410".bytes     #=> [208, 144] - same "А"
+"\u{410}".bytes    #=> [208, 144] - same as "\u0410" - leading zeros can be dropped
+"А".bytes.size     #=> 2
+"А".chars.size     #=> 1
+
+# Old Persian Number One (Unicode) - 4 Bytes
+"𐏑".bytes          #=> [240, 144, 143, 145]
+"\u{103D1}".bytes  #=> [240, 144, 143, 145]
+"\u{103d1}".bytes  #=> [240, 144, 143, 145] same as "\u{103D1}"
+"𐏑".bytes.size     #=> 4
+"𐏑".chars.size     #=> 1
+
+# ...
+```
+
+
+
+### String of Bytes or String of Characters? Yes, Yes, Yes
+
+
+In ruby the String class can morph into three types:
+
+- Bytes
+- Mutable String a.k.a String Buffer
+- Immutable String a.k.a. Frozen String
+
+
+#### Bytes / Binary
+
+
+`String.new` or `"".b` creates new bytes, that is, a new binary string
+buffer with the ASCII_8BIT encoding also known as BINARY.
+Let's try:
+
+``` ruby
+String.new.encoding        #=> <Encoding::ASCII_8BIT>
+String.new("".b).encoding  #=> <Encoding::ASCII_8BIT>
+"".b.encoding              #=> <Encoding::ASCII_8BIT>
+
+Encoding::BINARY == Encoding::ASCII_8BIT  #=> true
+
+# or using the "type-safe" Bytes class
+
+Bytes.new.encoding                  #=> <Encoding::ASCII_8BIT>
+Bytes.new("").encoding              #=> <Encoding::ASCII_8BIT>
+Bytes.new("abc").encoding           #=> <Encoding::ASCII_8BIT>
+Bytes.new("\x61\x62\x63").encoding  #=> <Encoding::ASCII_8BIT>
+```
+
+
+
+#### String Buffer
+
+If you use `String.new("")` (note the `""` passed in) or
+the string literal `""` that creates a new string buffer
+with the default encoding (usually UTF-8).
+Let's try:
+
+``` ruby
+# encoding: utf-8
+String.new("").encoding     #=> <Encoding::UTF_8>
+"".encoding                 #=> <Encoding::UTF_8>
+```
+
+<!--
+
+# or using the StringBuffer c'tor helper (returning a String)
+
+StringBuffer.new.encoding         #=> <Encoding::UTF_8>
+StringBuffer.new("").encoding     #=> <Encoding::UTF_8>
+StringBuffer.new("abc").encoding  #=> <Encoding::UTF_8>
+
+-->
+
+
+#### Frozen String
+
+If you use the recommended `# frozen_string_literal: true` magic comment
+or pragma you can automagically turn all string literals into
+frozen (immutable) strings with the default encoding (usually UTF-8).
+Let's try:
+
+``` ruby
+# frozen_string_literal: true
+"".frozen?                 #=> true
+"Hello, World!".frozen?    #=> true
+String.new.frozen?         #=> false
+String.new("").frozen?     #=> false
+```
+
+
+
+<!--
+
+### Bytes
+
+bytes from hexstring
+
+bytes to hexstring
+
+bytes from string
+
+bytes to string
+
+bytes to array of integers
+
+bytes from array of integers
+
+
+
+#### Bytes to Integer Numbers - Little-Endian vs Big-Endian
+
+4 byte unsigned integer  -
+
+Example - 1
+
+bytes to integer
+
+integer to bytes
+
+Big-End first or Little-End first?
+Least significant bit (lsm) or most significant bit (msb) first?
+
+
+
+
+#### Bytes Helper
+
+
+
+### Buffer
+
+#### Buffer Helper
+
+-->
+
+
+
+
+To be continued ...
+
+---
+
+
+
+
+
+
 
 ## Usage
 

data/lib/bytes/version.rb

@@ -4,8 +4,8 @@ module Module
 module Bytes
 
   MAJOR = 0
-  MINOR = 1
-  PATCH = 1
+  MINOR = 2
+  PATCH = 0
   VERSION = [MAJOR,MINOR,PATCH].join('.')
 
   def self.version

data/lib/bytes.rb

@@ -64,8 +64,14 @@ class Bytes
   def initialize( bin=String.new )
     ## note: for now will NOT dup(licate) passed in binary array
     ##    you only get a new binary array if no arg passed in e.g. Bytes.new
-    raise ArgumentError, "Bytes.new - BINARY/ASCII-8BIT encoding expected; got: #{bin.encoding} for string >#{bin}<"  if bin.encoding != Encoding::ASCII_8BIT
-    @bin = bin
+    @bin  = if bin.encoding != Encoding::ASCII_8BIT
+             puts "!! WARN - Bytes.new - BINARY/ASCII-8BIT encoding expected; got: #{bin.encoding} for string:"
+             pp bin
+
+             bin.b
+            else
+               bin
+            end
   end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bytes
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Gerald Bauer