Deprecate isDigit and digitToInt in favor of functions which specify base (#31)

Author: milesfrain

CHANGELOG.md

@@ -5,8 +5,10 @@ Notable changes to this project are documented in this file. The format is based
 ## [Unreleased]
 
 Breaking changes (😱!!!):
+- Deprecation warnings for `isDigit` and `digitToInt` (#31 by @milesfrain)
 
 New features:
+- Added `hexDigitToInt` `decDigitToInt` `octDigitToInt` (#31 by @milesfrain)
 
 Bugfixes:
 

packages.dhall

@@ -1,4 +1,4 @@
 let upstream =
-      https://raw.githubusercontent.com/purescript/package-sets/prepare-0.14/src/packages.dhall sha256:f591635bcfb73053bcb6de2ecbf2896489fa5b580563396f52a1051ede439849
+      https://raw.githubusercontent.com/purescript/package-sets/prepare-0.14/src/packages.dhall sha256:af6c012eccebfc7447440e486d3ab8fbab02abaa003a540de62e204351d50a98
 
 in  upstream

src/Data/Char/Unicode.purs

@@ -9,9 +9,10 @@ module Data.Char.Unicode
   , isAlpha
   , isAlphaNum
   , isLetter
-  , isDigit
-  , isOctDigit
   , isHexDigit
+  , isDecDigit
+  , isOctDigit
+  , isDigit -- Deprecated
   , isControl
   , isPrint
   , isSpace
@@ -21,7 +22,11 @@ module Data.Char.Unicode
   , isMark
   , isNumber
 
-  , digitToInt
+-- Conversion to Int
+  , hexDigitToInt
+  , decDigitToInt
+  , octDigitToInt
+  , digitToInt -- Deprecated
 
   -- Case conversion
   , toLower
@@ -41,6 +46,7 @@ import Prelude
 import Data.Char (toCharCode)
 import Data.Char.Unicode.Internal (UnicodeCategory(..), uTowtitle, uTowlower, uTowupper, uIswalnum, uIswalpha, uIswlower, uIswupper, uIswspace, uIswprint, uIswcntrl, uGencat)
 import Data.Maybe (Maybe(..))
+import Prim.TypeError (class Warn, Text)
 
 -- | Unicode General Categories (column 2 of the UnicodeData table) in
 -- | the order they are listed in the Unicode standard (the Unicode
@@ -386,9 +392,9 @@ isAlpha = uIswalpha <<< toCharCode
 isAlphaNum :: Char -> Boolean
 isAlphaNum = uIswalnum <<< toCharCode
 
--- | Selects ASCII digits, i.e. `0..9`.
-isDigit :: Char -> Boolean
-isDigit c = let diff = (toCharCode c - toCharCode '0')
+-- | Selects ASCII decimal digits, i.e. `0..9`.
+isDecDigit :: Char -> Boolean
+isDecDigit c = let diff = (toCharCode c - toCharCode '0')
             in diff <= 9 && diff >= 0
 
 -- | Selects ASCII octal digits, i.e. `0..7`.
@@ -399,10 +405,13 @@ isOctDigit c = let diff = (toCharCode c - toCharCode '0')
 -- | Selects ASCII hexadecimal digits,
 -- | i.e. `0..9, A..F, a..f`.
 isHexDigit :: Char -> Boolean
-isHexDigit c = isDigit c
+isHexDigit c = isDecDigit c
             || (let diff = (toCharCode c - toCharCode 'A') in diff <= 5 && diff >= 0)
             || (let diff = (toCharCode c - toCharCode 'a') in diff <= 5 && diff >= 0)
 
+isDigit :: Warn (Text "'isDigit' is deprecated, use 'isDecDigit', 'isHexDigit', or 'isOctDigit' instead") => Char -> Boolean
+isDigit = isDecDigit
+
 -- | Selects Unicode punctuation characters, including various kinds
 -- | of connectors, brackets and quotes.
 -- |
@@ -523,26 +532,25 @@ toTitle = withCharCode uTowtitle
 foreign import withCharCode :: (Int -> Int) -> Char -> Char
 
 -- | Convert a single digit `Char` to the corresponding `Just Int` if its argument
--- | satisfies `isHexDigit`, if it is one of `0..9, A..F, a..f`. Anything else
--- | converts to `Nothing`
--- | 
+-- | satisfies `isHexDigit` (one of `0..9, A..F, a..f`). Anything else converts to `Nothing`
+-- |
 -- | ```
 -- | >>> import Data.Traversable
--- | 
--- | >>> traverse digitToInt ['0','1','2','3','4','5','6','7','8','9']
+-- |
+-- | >>> traverse hexDigitToInt ['0','1','2','3','4','5','6','7','8','9']
 -- | (Just [0,1,2,3,4,5,6,7,8,9])
--- | 
--- | >>> traverse digitToInt ['a','b','c','d','e','f']
+-- |
+-- | >>> traverse hexDigitToInt ['a','b','c','d','e','f']
 -- | (Just [10,11,12,13,14,15])
--- | 
--- | >>> traverse digitToInt ['A','B','C','D','E','F']
+-- |
+-- | >>> traverse hexDigitToInt ['A','B','C','D','E','F']
 -- | (Just [10,11,12,13,14,15])
--- | 
--- | >>> digitToInt 'G'
+-- |
+-- | >>> hexDigitToInt 'G'
 -- | Nothing
 -- | ```
-digitToInt :: Char -> Maybe Int
-digitToInt c = result
+hexDigitToInt :: Char -> Maybe Int
+hexDigitToInt c = result
   where
     result :: Maybe Int
     result
@@ -560,6 +568,43 @@ digitToInt c = result
     hexUpper :: Int
     hexUpper = toCharCode c - toCharCode 'A'
 
+-- | Convert a single digit `Char` to the corresponding `Just Int` if its argument
+-- | satisfies `isDecDigit` (one of `0..9`). Anything else converts to `Nothing`
+-- |
+-- | ```
+-- | >>> import Data.Traversable
+-- |
+-- | >>> traverse decDigitToInt ['0','1','2','3','4','5','6','7','8','9']
+-- | (Just [0,1,2,3,4,5,6,7,8,9])
+-- |
+-- | >>> decDigitToInt 'a'
+-- | Nothing
+-- | ```
+decDigitToInt :: Char -> Maybe Int
+decDigitToInt c
+  | isDecDigit c = Just $ toCharCode c - toCharCode '0'
+  | otherwise    = Nothing
+
+-- | Convert a single digit `Char` to the corresponding `Just Int` if its argument
+-- | satisfies `isOctDigit` (one of `0..7`). Anything else converts to `Nothing`
+-- |
+-- | ```
+-- | >>> import Data.Traversable
+-- |
+-- | >>> traverse octDigitToInt ['0','1','2','3','4','5','6','7']
+-- | (Just [0,1,2,3,4,5,6,7])
+-- |
+-- | >>> octDigitToInt '8'
+-- | Nothing
+-- | ```
+octDigitToInt :: Char -> Maybe Int
+octDigitToInt c
+  | isOctDigit c = Just $ toCharCode c - toCharCode '0'
+  | otherwise    = Nothing
+
+digitToInt :: Warn (Text "'digitToInt' is deprecated, use 'decDigitToInt', 'hexDigitToInt', or 'octDigitToInt' instead") => Char -> Maybe Int
+digitToInt = hexDigitToInt
+
 -- | Selects alphabetic Unicode characters (lower-case, upper-case and
 -- | title-case letters, plus letters of caseless scripts and
 -- | modifiers letters). This function is equivalent to

test/Test/Data/Char/Unicode.purs

@@ -5,10 +5,12 @@ import Prelude
 
 import Control.Monad.Reader.Class (class MonadReader, ask, local)
 import Data.Char (fromCharCode)
-import Data.Char.Unicode (GeneralCategory(..), digitToInt, generalCategory, isAlpha, isAlphaNum, isAscii, isAsciiLower, isAsciiUpper, isControl, isDigit, isHexDigit, isLatin1, isLetter, isLower, isMark, isNumber, isOctDigit, isPrint, isPunctuation, isSeparator, isSpace, isSymbol, isUpper)
+import Data.Char.Unicode (GeneralCategory(..), decDigitToInt, hexDigitToInt, octDigitToInt, generalCategory, isAlpha, isAlphaNum, isAscii, isAsciiLower, isAsciiUpper, isControl, isDecDigit, isHexDigit, isLatin1, isLetter, isLower, isMark, isNumber, isOctDigit, isPrint, isPunctuation, isSeparator, isSpace, isSymbol, isUpper)
+import Data.Foldable (traverse_)
 import Data.Maybe (Maybe(..), fromJust)
 import Data.Monoid (power, guard)
 import Data.NonEmpty ((:|))
+import Data.String.CodeUnits (singleton)
 import Effect.Console (log)
 import Effect.Class (class MonadEffect, liftEffect)
 import Partial.Unsafe (unsafePartial)
@@ -53,15 +55,17 @@ dataCharUnicodeTests = describe "module Data.Char.Unicode" do
     isUpperTests
     isAlphaTests
     isAlphaNumTests
-    isDigitTests
-    isOctDigitTests
     isHexDigitTests
+    isDecDigitTests
+    isOctDigitTests
     isPunctuationTests
     isSymbolTests
     toUpperTests
     toLowerTests
     toTitleTests
-    digitToIntTests
+    hexDigitToIntTests
+    decDigitToIntTests
+    octDigitToIntTests
     isLetterTests
     isMarkTests
     isNumberTests
@@ -295,10 +299,10 @@ isAlphaNumTests = describe "isAlphaNum" do
     it "'\\n' is not AlphaNum" $
         isAlphaNum '\n' `shouldEqual` false
 
-isDigitTests :: forall m. MonadReader Int m => MonadEffect m => m Unit
-isDigitTests = describe "isDigit" do
-    it "digits are digits" $ liftEffect $ quickCheck \(AsciiDigit char) -> isDigit char
-    it "non digits are not digits" $ liftEffect $ quickCheck \(NonAsciiDigit char) -> not $ isDigit char
+isDecDigitTests :: forall m. MonadReader Int m => MonadEffect m => m Unit
+isDecDigitTests = describe "isDecDigit" do
+    it "digits are digits" $ liftEffect $ quickCheck \(AsciiDigit char) -> isDecDigit char
+    it "non digits are not digits" $ liftEffect $ quickCheck \(NonAsciiDigit char) -> not $ isDecDigit char
 
 isOctDigitTests :: forall m. MonadReader Int m => MonadEffect m => m Unit
 isOctDigitTests = describe "isOctDigit" do
@@ -352,23 +356,38 @@ toLowerTests = pure unit
 toTitleTests :: forall m. MonadReader Int m => MonadEffect m => m Unit
 toTitleTests = pure unit
 
-digitToIntTests :: forall m. MonadReader Int m => MonadEffect m => m Unit
-digitToIntTests = describe "digitToInt" do
+notDigit :: forall m. MonadReader Int m => MonadEffect m =>
+  String -> (Char -> Maybe Int) -> Char -> m Unit
+notDigit base func char =
+  it ("'" <> singleton char <> "' is not a " <> base <> " digit") $
+      func char `shouldEqual` Nothing
+
+hexDigitToIntTests :: forall m. MonadReader Int m => MonadEffect m => m Unit
+hexDigitToIntTests = describe "hexDigitToInt" do
     it "'0'..'9' get mapped correctly" $
-        map digitToInt ['0','1','2','3','4','5','6','7','8','9'] `shouldEqual`
+        map hexDigitToInt ['0','1','2','3','4','5','6','7','8','9'] `shouldEqual`
             [Just 0, Just 1, Just 2, Just 3, Just 4, Just 5, Just 6, Just 7, Just 8, Just 9]
     it "'a'..'f' get mapped correctly" $
-        map digitToInt ['a','b','c','d','e','f'] `shouldEqual`
+        map hexDigitToInt ['a','b','c','d','e','f'] `shouldEqual`
             [Just 10, Just 11, Just 12, Just 13, Just 14, Just 15]
     it "'A'..'F' get mapped correctly" $
-        map digitToInt ['A','B','C','D','E','F'] `shouldEqual`
+        map hexDigitToInt ['A','B','C','D','E','F'] `shouldEqual`
             [Just 10, Just 11, Just 12, Just 13, Just 14, Just 15]
-    it "'G' is not a digit" $
-        digitToInt 'G' `shouldEqual` Nothing
-    it "'♥' is not a digit" $
-        digitToInt '♥' `shouldEqual` Nothing
-    it "'国' is not a digit" $
-        digitToInt '国' `shouldEqual` Nothing
+    traverse_ (notDigit "hex" hexDigitToInt) ['g', 'G', '♥', '国']
+
+decDigitToIntTests :: forall m. MonadReader Int m => MonadEffect m => m Unit
+decDigitToIntTests = describe "decDigitToInt" do
+    it "'0'..'9' get mapped correctly" $
+        map decDigitToInt ['0','1','2','3','4','5','6','7','8','9'] `shouldEqual`
+            [Just 0, Just 1, Just 2, Just 3, Just 4, Just 5, Just 6, Just 7, Just 8, Just 9]
+    traverse_ (notDigit "dec" decDigitToInt) ['a', 'A', '♥', '国']
+
+octDigitToIntTests :: forall m. MonadReader Int m => MonadEffect m => m Unit
+octDigitToIntTests = describe "octDigitToInt" do
+    it "'0'..'7' get mapped correctly" $
+        map octDigitToInt ['0','1','2','3','4','5','6','7'] `shouldEqual`
+            [Just 0, Just 1, Just 2, Just 3, Just 4, Just 5, Just 6, Just 7]
+    traverse_ (notDigit "oct" octDigitToInt) ['8', '9', '♥', '国']
 
 isLetterTests:: forall m. MonadReader Int m => MonadEffect m => m Unit
 isLetterTests = describe "isLetter" do