Merge pull request #53 from mjblack/helper_macros_and_methods_docs

Added documentation to macros file and spec tests.

Author: mjblack

shard.yml

@@ -1,5 +1,5 @@
 name: win32cr
-version: 1.2.0
+version: 1.2.1
 
 authors:
   - Matthew J. Black <mjblack@gmail.com>

spec/macros_spec.cr

@@ -0,0 +1,61 @@
+require "./spec_helper"
+require "../src/macros"
+
+describe "Win32cr Macros" do
+
+  describe "pwstr" do
+    str = "Example String"
+    it "should take a string and create a UInt16 pointer" do
+      pstr = pwstr(str)
+      pstr.should be_a(Pointer(UInt16))
+    end
+
+    it "should have the value of 'Example String' in UInt16 pointer" do
+      pstr = pwstr(str)
+      val = String.from_utf16(pstr)[0] # `from_utf16` returns a tuple, first element should be the string
+      val.should eq(str)
+    end
+  end
+
+  describe "hiword" do
+    value = 0x12345678
+    pvalue = pointerof(value)
+
+    it "returns the high-order WORD from a UInt32" do
+      hiword(value.to_u32).should eq(4660_u16)
+    end
+
+    it "returns the high-order WORD from a Int32" do
+      hiword(value.to_i32).should eq(4660_u16)
+    end
+
+    it "returns the high-order WORD from a UInt32 pointer" do
+      hiword(pvalue).should eq(4660_u16)
+    end
+
+    it "returns the high-order WORD from a Int32 pointer" do
+      hiword(pvalue).should eq(4660_u16)
+    end
+  end
+
+  describe "loword" do
+    value = 0x12345678
+    pvalue = pointerof(value)
+
+    it "returns the low-order WORD from a UInt32" do
+      loword(value.to_u32).should eq(22136_u16)
+    end
+
+    it "returns the low-order WORD from a Int32" do
+      loword(value.to_i32).should eq(22136_u16)
+    end
+
+    it "returns the low-order WORD from a UInt32 pointer" do
+      loword(pvalue).should eq(22136_u16)
+    end
+
+    it "returns the low-order WORD from a Int32 pointer" do
+      loword(pvalue).should eq(22136_u16)
+    end
+  end
+end

src/macros.cr

@@ -1,26 +1,55 @@
 ## Custom Macros and top level methods go here!
 ## WinMD will not overwrite this file.
 
+# Converts a string to a pointer to a null-terminated wide string pointer.
 macro pwstr(str)
   {{str}}.to_utf16.to_unsafe
 end
 
-def loword(i : UInt64) : UInt16
+# Returns the low-order `WORD` from a `UInt64`.
+def loword(i : UInt32) : UInt16
   val = (i & 0xffff).to_u16
   val
 end
 
-def loword(i : Int64) : UInt16
-  val = (i.to_u64 & 0xffff).to_u16
+# Returns the low-order `WORD` from a `Int64`.
+def loword(i : Int32) : UInt16
+  val = (i.to_u32 & 0xffff).to_u16
   val
 end
 
+# Returns the low-order `WORD` from a `UInt64` pointer.
+def loword(i : UInt32*) : UInt16
+  val = (i.value & 0xffff).to_u16
+  val
+end
+
+# Returns the low-order `WORD` from a `Int64` pointer.
+def loword(i : Int32*) : UInt16
+  val = (i.value.to_u32 & 0xffff).to_u16
+  val
+end
+
+# Returns the high-order `WORD` from a `UInt32`.
+def hiword(i : UInt32) : UInt16
+  val = ((i >> 16) & 0xFFFF).to_u16
+  val
+end
+
+# Returns the high-order `WORD` from a `Int32`.
+def hiword(i : Int32) : UInt16
+  val = ((i.to_u32 >> 16) & 0xFFFF).to_u16
+  val
+end
+
+# Returns the high-order `WORD` from a `UInt32` pointer.
 def hiword(i : UInt32*) : UInt16
   val = ((i.value >> 16) & 0xFFFF).to_u16
   val
 end
 
-def hiword(i : Int64*) : UInt16
-  val = ((i.value.to_u64 >> 16) & 0xFFFF).to_u16
+# Returns the high-order `WORD` from a `Int32` pointer.
+def hiword(i : Int32*) : UInt16
+  val = ((i.value.to_u32 >> 16) & 0xFFFF).to_u16
   val
 end