bytes 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a17c54ac2788c884d6e1d8605b54621fe1707cf3252bbc6c81ad062e4dda6ca2
-  data.tar.gz: 23189f40e8c5459ccd8d53a2796524d0b3b217dd13749e48f406652683b3367d
+  metadata.gz: 4d93d96204652bc075816b6b9a32220b7f1f72fa3765379012ecea3dfc4485c3
+  data.tar.gz: ba15bcb1f6939fd5ddb4d42da815a9ecb7edfc42e785c81bc8845101dc819b9a
 SHA512:
-  metadata.gz: 6203bdf2072f6fc54b01029a1de95896bc7d5eb37690b30f0186dc5615bc87ed098fb9b2542d9e9c29e6c2571f3bb8bc1793d802851de0da4910163fa74a75c1
-  data.tar.gz: e1aa00e67da7a420a6f791a7ed7954a0c229d553b1c1b9e284968e69b860c85150409cacd79fe1e4bf3e16a1d954b6c2ed8dee6c380404f4e89841835cbd00b7
+  metadata.gz: d3f41e967326e54022df7c16257fab59dc8bfe3d0402ba74670b16532d086162b74156937e3b4f40f2a09aee5a73521e1399b0329232da418a18599a48cfcfe1
+  data.tar.gz: 71726839412c32893a6f1a243cf4d00d84ba1558379f39e2e355940b645a5970a72c07a249481f11046486853926d8afd44aa28b4ef7ebc90afc9674534eaeb0

data/README.md

@@ -8,10 +8,310 @@ 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
 
-To be done
+### BytesHelper  - From Bytes (Binary String) to Hex(adecimal) String and Back
+
+``` ruby
+require 'bytes
+
+Bytes.bin_to_hex( "\x61\x62".b )
+#=> '6162'
+
+Bytes.hex_to_bin( '6162' )     # or
+Bytes.hex_to_bin( '0x6162' )   # or
+#=> "\x61\x62".b
+
+Bytes.is_hex?( '6162' )
+Bytes.is_hex?( '0x6162' )
+Bytes.is_hex?( '' )     # empty string or
+Bytes.is_hex?( '0x' )   # empty hex string
+#=> true
+
+Bytes.is_hex?( 'xyz' )
+Bytes.is_hex?( '0xyz' )
+#=> false
+
+Bytes.hex_to_bin( 'xzy' )  # or
+Bytes.hex_to_bin( '0xxzy' )
+#=>  raises TypeError - non-hexadecimal digit found
+```
+
+Note:  You can use the shorter alternate alias
+names  `btoh` or `htob`
+for `bin_to_hex` and `hex_to_bin`.
+
+
+Or use the mixed-in String class variants. Example:
+
+``` ruby
+"\x61\x62".b.bin_to_hex   # or
+"\x61\x62".b.btoh
+#=> '6162'
+
+'6162'.hex_to_bin      # or
+'6162'.htob            # or
+'0x6162'.hex_to_bin    # or
+'0x6162'.htob          # or
+#=> "\x61\x62".b
+
+'6162'.is_hex?
+'0x6162'is_hex?
+''.is_hex?        # empty string or
+'0x'.is_hex?      # empty hex string
+#=> true
+
+'xyz'is_hex?
+'0xyz'.is_hex?
+#=> false
+
+'xzy'.htob   # or
+'0xxzy'.htob
+#=>  raises TypeError - non-hexadecimal digit found
+```
+
+and so on.
+
+
+
 
 
 ## License

data/Rakefile

@@ -6,7 +6,7 @@ Hoe.spec 'bytes' do
 
   self.version = Cocos::Module::Bytes::VERSION
 
-  self.summary = "bytes"
+  self.summary = "bytes - bits 'n' bytes made easy/easier incl. new buffer helper / wrapper class to help with the string byte vs character dichotomy"
   self.description = summary
 
 

data/lib/bytes/version.rb

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

data/lib/bytes.rb

@@ -6,6 +6,7 @@ require 'forwardable'
 require_relative 'bytes/version'    # note: let version always go first
 
 
+
 module BytesHelper
   def hex_to_bin( hex )
     ## todo/fix:  do an argument regex hex check!!!!
@@ -18,8 +19,8 @@ module BytesHelper
       [hex].pack('H*')
     end
   end
-  alias_method :hex_to_bytes, :hex_to_bin
-  alias_method :h_to_b,       :hex_to_bin
+  ## alias_method :hex_to_bytes, :hex_to_bin
+  ## alias_method :h_to_b,       :hex_to_bin
   alias_method :htob,         :hex_to_bin
 
 
@@ -32,8 +33,8 @@ module BytesHelper
     hex.encode!( Encoding::UTF_8 )
     hex
   end
-  alias_method :bytes_to_hex, :bin_to_hex
-  alias_method :b_to_h,       :bin_to_hex
+  ## alias_method :bytes_to_hex, :bin_to_hex
+  ## alias_method :b_to_h,       :bin_to_hex
   alias_method :btoh,         :bin_to_hex
 
 
@@ -64,8 +65,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
 
 
@@ -75,8 +82,8 @@ class Bytes
                         :size, :length
 
 
-  def to_s() Bytes.bin_to_hex( @bin ); end
-  alias_method :to_hex, :to_s
+  def to_hex() Bytes.bin_to_hex( @bin ); end
+  alias_method :to_s, :to_hex
 
   def b()  @bin; end
 
@@ -113,12 +120,15 @@ end
 
 
 class String
-  def to_hex()  Bytes.bin_to_hex( self ); end
-  ## add more aliases e.g. bin_to_hex or btoh or b_to_h or such - why? why not?
-
+  def bin_to_hex()  Bytes.bin_to_hex( self ); end
+  alias_method :btoh,   :bin_to_hex
+  alias_method :to_hex, :bin_to_hex
   ## note: built-in String#hex returns string converted
-  ##                    to Integer  -same as String.to_i(16) !!!!
-end
+  ##                    to Integer  - same as String.to_i(16) !!!!
+
+  def hex_to_bin()  Bytes.hex_to_bin( self ); end
+  alias_method :htob, :hex_to_bin
+end   # class String
 
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bytes
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-12-10 00:00:00.000000000 Z
+date: 2022-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
@@ -44,7 +44,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.23'
-description: bytes
+description: bytes - bits 'n' bytes made easy/easier incl. new buffer helper / wrapper
+  class to help with the string byte vs character dichotomy
 email: wwwmake@googlegroups.com
 executables: []
 extensions: []
@@ -83,5 +84,6 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
-summary: bytes
+summary: bytes - bits 'n' bytes made easy/easier incl. new buffer helper / wrapper
+  class to help with the string byte vs character dichotomy
 test_files: []