From 2934f77660ff8efc53e1245ca02344a95b432543 Mon Sep 17 00:00:00 2001
From: Artur Wieczorek <artwik@wp.pl>
Date: Thu, 23 Feb 2017 20:00:13 +0100
Subject: [PATCH] Fix and document wxDecToHex()

1. Integer instead of floating point arithmetic should be used in calculations.
2. Because this function always returns 2 hexadecimal characters, its parameter type should be changed from 'int' to 'unsigned char' to avoid misunderstandings and prevent misuses.

Closes #12612.
---
 include/wx/utils.h      |  6 ++---
 interface/wx/utils.h    | 52 +++++++++++++++++++++++++++++++++++++++++
 src/common/utilscmn.cpp | 26 ++++++++++-----------
 3 files changed, 67 insertions(+), 17 deletions(-)

diff --git a/include/wx/utils.h b/include/wx/utils.h
index a522142c71..90c31453a1 100644
--- a/include/wx/utils.h
+++ b/include/wx/utils.h
@@ -309,9 +309,9 @@ inline int wxHexToDec(const char* buf)
 
 
 // Convert decimal integer to 2-character hex string
-WXDLLIMPEXP_BASE void wxDecToHex(int dec, wxChar *buf);
-WXDLLIMPEXP_BASE void wxDecToHex(int dec, char* ch1, char* ch2);
-WXDLLIMPEXP_BASE wxString wxDecToHex(int dec);
+WXDLLIMPEXP_BASE void wxDecToHex(unsigned char dec, wxChar *buf);
+WXDLLIMPEXP_BASE void wxDecToHex(unsigned char dec, char* ch1, char* ch2);
+WXDLLIMPEXP_BASE wxString wxDecToHex(unsigned char dec);
 
 // ----------------------------------------------------------------------------
 // Process management
diff --git a/interface/wx/utils.h b/interface/wx/utils.h
index 624ff0710e..19bce18ec4 100644
--- a/interface/wx/utils.h
+++ b/interface/wx/utils.h
@@ -1423,3 +1423,55 @@ void wxUsleep(unsigned long milliseconds);
 
 //@}
 
+
+/** @addtogroup group_funcmacro_misc */
+//@{
+/**
+    Convert decimal integer to 2-character hexadecimal string.
+
+    @param dec
+        A number to be converted.
+    @param buf
+        A pointer to the buffer that receives hexadecimal string (not prefixed
+        by @c 0x). This buffer should be large enough to hold at least
+        3 characters: 2 hexadecimal digits and the terminating null character.
+
+    @remarks
+        Returned string is composed of uppercase hexdecimal characters.
+
+    @header{wx/utils.h}
+*/
+void wxDecToHex(unsigned char dec, wxChar *buf);
+
+/**
+    Convert decimal integer to 2-character hexadecimal string.
+
+    @param dec
+        A number to be converted.
+    @return
+        String containing hexadecimal string, not prefixed by @c 0x,
+        composed of uppercase characters.
+
+    @header{wx/utils.h}
+*/
+wxString wxDecToHex(unsigned char dec);
+
+/**
+    Returns 2 characters of hexadecimal representation of a given number.
+
+    @param dec
+        A number to be converted.
+    @param ch1
+        Pointer to the variable that receives 1st hexadecimal character.
+        It must not be @NULL.
+    @param ch2
+        Pointer to the variable that receives 2nd hexadecimal character.
+        It must not be @NULL.
+
+    @remarks
+        Returned characters are uppercase.
+
+    @header{wx/utils.h}
+*/
+void wxDecToHex(unsigned char dec, char* ch1, char* ch2);
+//@}
diff --git a/src/common/utilscmn.cpp b/src/common/utilscmn.cpp
index 38ce9ef9db..b252e4cf39 100644
--- a/src/common/utilscmn.cpp
+++ b/src/common/utilscmn.cpp
@@ -117,7 +117,7 @@
 // ============================================================================
 
 // Array used in DecToHex conversion routine.
-static const wxChar hexArray[] = wxT("0123456789ABCDEF");
+static const char hexArray[] = "0123456789ABCDEF";
 
 // Convert 2-digit hex number to decimal
 int wxHexToDec(const wxString& str)
@@ -128,27 +128,25 @@ int wxHexToDec(const wxString& str)
     return wxHexToDec((const char*) buf);
 }
 
-// Convert decimal integer to 2-character hex string
-void wxDecToHex(int dec, wxChar *buf)
+// Convert decimal integer to 2-character hex string (not prefixed by 0x).
+void wxDecToHex(unsigned char dec, wxChar *buf)
 {
-    int firstDigit = (int)(dec/16.0);
-    int secondDigit = (int)(dec - (firstDigit*16.0));
-    buf[0] = hexArray[firstDigit];
-    buf[1] = hexArray[secondDigit];
+    wxASSERT_MSG( buf, wxS("Invalid argument") );
+    buf[0] = hexArray[dec >> 4];
+    buf[1] = hexArray[dec & 0x0F];
     buf[2] = 0;
 }
 
 // Convert decimal integer to 2 characters
-void wxDecToHex(int dec, char* ch1, char* ch2)
+void wxDecToHex(unsigned char dec, char* ch1, char* ch2)
 {
-    int firstDigit = (int)(dec/16.0);
-    int secondDigit = (int)(dec - (firstDigit*16.0));
-    (*ch1) = (char) hexArray[firstDigit];
-    (*ch2) = (char) hexArray[secondDigit];
+    wxASSERT_MSG( ch1 && ch2, wxS("Invalid argument(s)") );
+    *ch1 = hexArray[dec >> 4];
+    *ch2 = hexArray[dec & 0x0F];
 }
 
-// Convert decimal integer to 2-character hex string
-wxString wxDecToHex(int dec)
+// Convert decimal integer to 2-character hex string (not prefixed by 0x).
+wxString wxDecToHex(unsigned char dec)
 {
     wxChar buf[3];
     wxDecToHex(dec, buf);