From 1762c85e383005df895bc1082c6eb4e4e0fac6b6 Mon Sep 17 00:00:00 2001
From: Katharine Hyatt <khyatt@flatironinstitute.org>
Date: Wed, 11 Jul 2018 17:13:10 -0400
Subject: [PATCH] Doc some string parsing macros

---
 base/int.jl             | 52 +++++++++++++++++++++++++++++++++++++++++
 doc/src/base/numbers.md |  3 +++
 2 files changed, 55 insertions(+)

diff --git a/base/int.jl b/base/int.jl
index 9f98e5479065a..3c8768ad403b2 100644
--- a/base/int.jl
+++ b/base/int.jl
@@ -553,14 +553,66 @@ floor(::Type{T}, x::Integer) where {T<:Integer} = convert(T, x)
 
 ## integer construction ##
 
+"""
+    @int128_str str
+
+Parse `str` as an [`Int128`](@ref).
+
+# Examples
+```jldoctest; filter = r"Stacktrace:(\\n \\[[0-9]+\\].*)*"
+julia> @int128_str "123456789123"
+123456789123
+
+julia> @int128_str "123456789123.4"
+ERROR: LoadError: ArgumentError: invalid base 10 digit '.' in "123456789123.4"
+Stacktrace:
+ [1] tryparse_internal(::Type{Int128}, ::String, ::Int64, ::Int64, ::Int64, ::Bool) at ./parse.jl:118
+[...]
+```
+"""
 macro int128_str(s)
     return parse(Int128, s)
 end
 
+"""
+    @uint128_str str
+
+Parse `str` as an [`UInt128`](@ref).
+
+# Examples
+```jldoctest; filter = r"Stacktrace:(\\n \\[[0-9]+\\].*)*"
+julia> @uint128_str "123456789123"
+0x00000000000000000000001cbe991a83
+
+julia> @uint128_str "-123456789123"
+ERROR: LoadError: ArgumentError: invalid base 10 digit '-' in "-123456789123"
+Stacktrace:
+ [1] tryparse_internal(::Type{UInt128}, ::String, ::Int64, ::Int64, ::Int64, ::Bool) at ./parse.jl:118
+[...]
+```
+"""
 macro uint128_str(s)
     return parse(UInt128, s)
 end
 
+"""
+    @big_str str
+
+Attempt to parse `str` as a [`BigInt`](@ref) or [`BigFloat`](@ref).
+Throw an [`ArgumentError`] if `str` is in the wrong format for representation
+as either of these types.
+
+# Examples
+```jldoctest; filter = r"Stacktrace:(\\n \\[[0-9]+\\].*)*"
+julia> @big_str "1_000_000_000_000"
+1000000000000
+
+julia> @big_str "_"
+ERROR: ArgumentError: invalid number format _ for BigInt or BigFloat
+Stacktrace:
+ [1] top-level scope at none:0
+```
+"""
 macro big_str(s)
     if '_' in s
         # remove _ in s[2:end-1]
diff --git a/doc/src/base/numbers.md b/doc/src/base/numbers.md
index deea1c2746ea1..0670f22b776fb 100644
--- a/doc/src/base/numbers.md
+++ b/doc/src/base/numbers.md
@@ -57,6 +57,9 @@ Base.bswap
 Base.hex2bytes
 Base.hex2bytes!
 Base.bytes2hex
+Base.@big_str
+Base.@int128_str
+Base.@uint128_str
 ```
 
 ## General Number Functions and Constants