try_as_byte_string, try_as_byte_string_view

Author: danielaparker

CHANGELOG.md

@@ -23,12 +23,7 @@
         - `try_decode_msgpack`
         - `try_decode_ubjson`
 
-    - New non-throwing accessors for `basic_json` that return a `std::expected`-like result,
-
-        - `try_as<T>()`
-        - `try_as_integer<T>`
-        - `try_as_double`
-        - `try_as_string_view`
+    - New non-throwing accessor `try_as<T>()` for `basic_json` that return a `std::expected`-like result,
 
 - Breaking changes to staj iterator classes
 

doc/Reference.md

@@ -8,8 +8,7 @@ All core jsoncons classes and functions are in namespace `jsoncons`.
 
 [json_type_traits](ref/corelib/json_type_traits.md)  
 [encode_json](ref/corelib/encode_json.md)  
-[decode_json](ref/corelib/decode_json.md)  
-[try_decode_json](ref/corelib/try_decode_json.md)   (since 1.4.0)  
+[decode_json, try_decode_json](ref/corelib/decode_json.md)  
 [basic_json_options](ref/corelib/basic_json_options.md)    
 
 #### Streaming API for JSON (StAJ)

doc/Tutorials/Basics.md

@@ -1,6 +1,6 @@
 ## Examples
 
-The examples below illustrate the use of the [json](../ref/basic_json.md) class and [json_query](../ref/jsonpath/json_query.md) function.
+The examples below illustrate the use of the [json](../ref/corelib/basic_json.md) class and [json_query](../ref/jsonpath/json_query.md) function.
 
 ### json construction
 

doc/ref/bson/basic_bson_cursor.md

@@ -281,9 +281,9 @@ Graham Greene
 
 ### See also
 
-[staj_event](../basic_staj_event.md)  
+[staj_event](../corelib/basic_staj_event.md)  
 
-[staj_array_iterator](../staj_array_iterator.md)  
+[staj_array_iterator](../corelib/staj_array_iterator.md)  
 
-[staj_object_iterator](../staj_object_iterator.md)  
+[staj_object_iterator](../corelib/staj_object_iterator.md)  
 

doc/ref/bson/basic_bson_encoder.md

@@ -345,4 +345,4 @@ Output:
 
 ### See also
 
-[byte_string_view](../byte_string_view.md)
+[byte_string_view](../corelib/byte_string_view.md)

doc/ref/bson/bson.md

@@ -1,11 +1,10 @@
 ### bson extension
 
 The bson extension implements decode from and encode to the [Binary JSON](http://bsonspec.org/) data format.
-You can either parse into or serialize from a variant-like data structure, [basic_json](../basic_json.md), or your own
-data structures, using [json_type_traits](../json_type_traits.md).
+You can either parse into or serialize from a variant-like data structure, [basic_json](../corelib/basic_json.md), or your own
+data structures, using [json_type_traits](../corelib/json_type_traits.md).
 
-[decode_bson](decode_bson.md)
-[try_decode_bson](try_decode_bson.md)   (1.4.0)
+[decode_bson, try_decode_bson](decode_bson.md)
 
 [basic_bson_cursor](basic_bson_cursor.md)
 
@@ -292,7 +291,7 @@ Output:
 
 ### See also
 
-[byte_string_view](../byte_string_view.md)
+[byte_string_view](../corelib/byte_string_view.md)
 
 
 ### Acknowledgements

doc/ref/bson/bson_options.md

@@ -22,6 +22,6 @@ Constructs a `bson_options` with default values.
     void max_nesting_depth(int depth)
 The maximum nesting depth allowed when decoding and encoding BSON. 
 Default is 1024. Parsing can have an arbitrarily large depth
-limited only by available memory. Serializing a [basic_json](../basic_json.md) to
+limited only by available memory. Serializing a [basic_json](../corelib/basic_json.md) to
 BSON is limited by stack size.
 

doc/ref/bson/decode_bson.md

@@ -13,46 +13,78 @@ template <typename T>
 T decode_bson(std::istream& is,
     const bson_decode_options& options = bson_decode_options());        (2)
 
-template <typename T,typename BytesLike,typename Allocator,typename TempAllocator>
-T decode_bson(const allocator_set<Allocator,TempAllocator>& alloc_set,
+template <typename T,typename BytesLike,typename Alloc,typename TempAlloc>
+T decode_bson(const allocator_set<Alloc,TempAlloc>& alloc_set,
     const BytesLike& source,
     const bson_decode_options& options = bson_decode_options());        (3) (since 0.171.0)
 
-template <typename T,typename Allocator,typename TempAllocator>
-T decode_bson(const allocator_set<Allocator,TempAllocator>& alloc_set,
+template <typename T,typename Alloc,typename TempAlloc>
+T decode_bson(const allocator_set<Alloc,TempAlloc>& alloc_set,
     std::istream& is,
     const bson_decode_options& options = bson_decode_options());        (4) (since 0.171.0)
 
 template <typename T,typename InputIt>
 T decode_bson(InputIt first, InputIt last,
     const bson_decode_options& options = bson_decode_options());        (5) (since 0.153.0)
+
+template <typename T,typename BytesLike>
+read_result<T> try_decode_bson(const BytesLike& source, 
+    const bson_decode_options& options = bson_decode_options());        (6) (since 1.4.0)
+
+template <typename T>
+read_result<T> try_decode_bson(std::istream& is,
+    const bson_decode_options& options = bson_decode_options());        (7) (since 1.4.0)
+
+template <typename T,typename BytesLike,typename Alloc,typename TempAlloc>
+read_result<T> try_decode_bson(const allocator_set<Alloc,TempAlloc>& alloc_set,
+    const BytesLike& source,
+    const bson_decode_options& options = bson_decode_options());        (8) (since 1.4.0)
+
+template <typename T,typename Alloc,typename TempAlloc>
+read_result<T> try_decode_bson(const allocator_set<Alloc,TempAlloc>& alloc_set,
+    std::istream& is,
+    const bson_decode_options& options = bson_decode_options());        (9) (since 1.4.0)
+
+template <typename T,typename InputIt>
+read_result<T> try_decode_bson(InputIt first, InputIt last,
+    const bson_decode_options& options = bson_decode_options());        (10) (since 1.4.0)
 ```
 
 (1) Reads BSON data from a contiguous byte sequence provided by `source` into a type T, using the specified (or defaulted) [options](bson_options.md). 
 Type `BytesLike` must be a container that has member functions `data()` and `size()`, 
 and member type `value_type` with size exactly 8 bits (since 0.152.0.)
 Any of the values types `int8_t`, `uint8_t`, `char`, `unsigned char` and `std::byte` (since C++17) are allowed.
-Type 'T' must be an instantiation of [basic_json](../basic_json.md) 
-or support [json_type_traits](../json_type_traits.md). 
+Type 'T' must be an instantiation of [basic_json](../corelib/basic_json.md) 
+or support jsoncons reflection traits. 
 
 (2) Reads BSON data from a binary stream into a type T, using the specified (or defaulted) [options](bson_options.md). 
-Type 'T' must be an instantiation of [basic_json](../basic_json.md) 
-or support [json_type_traits](../json_type_traits.md). 
+Type 'T' must be an instantiation of [basic_json](../corelib/basic_json.md) 
+or support jsoncons reflection traits. 
 
 (3)-(4) are identical to (1)-(2) except an [allocator_set](allocator_set.md) is passed as an additional argument and
 provides allocators for result data and temporary allocations.
 
 (5) Reads BSON data from the range [`first`,`last`) into a type T, using the specified (or defaulted) [options](bson_options.md). 
-Type 'T' must be an instantiation of [basic_json](../basic_json.md) 
-or support [json_type_traits](../json_type_traits.md). 
+Type 'T' must be an instantiation of [basic_json](../corelib/basic_json.md) 
+or support jsoncons reflection traits. 
+
+(6)-(10) Non-throwing versions of (1)-(5)
+
+#### Return value
+
+(1)-(5) Deserialized value
+
+(6)-(10) [read_result<T>](../corelib/read_result.md)
 
 #### Exceptions
 
-Throws a [ser_error](../ser_error.md) if parsing fails, and a [conv_error](conv_error.md) if type conversion fails.
+(1)-(5) Throw [ser_error](../corelib/ser_error.md) if read fails.
+
+Any overload may throw `std::bad_alloc` if memory allocation fails.
 
 ### Examples
 
-#### Binary example
+#### Throwing overload
 
 ```cpp
 #include <jsoncons/json.hpp>
@@ -92,6 +124,53 @@ binary data: 48,65,6c,6c,6f
 ```
 Note that printing a json value by default encodes byte strings as base64url strings, but the json value holds the actual bytes.
 
+#### Non-throwing overload
+
+```cpp
+#include <jsoncons/json.hpp>
+#include <jsoncons_ext/bson/bson.hpp>
+#include <iostream>
+
+namespace bson = jsoncons::bson;
+
+int main()
+{
+    std::vector<uint8_t> input = {0x13, 0x00, 0x00, 0x00, // Document has 19 bytes
+        0x05, // Binary data
+        0x70, 0x44, 0x00, // "pD"
+        0x05, 0x00, 0x00, 0x00, // Length is 5
+        0x80, // Subtype is 128
+        0x48, 0x65, 0x6c, 0x6c, 0x6f, // 'H','e','l','l','o'
+        0x00 // terminating null
+    };
+
+    auto result = bson::try_decode_bson<jsoncons::json>(input);
+    if (!result)
+    {
+        std::cout << result.error() << "\n";
+        exit(1);
+    }
+    jsoncons::json& j(*result);
+    std::cout << pretty_print(j) << "\n\n";
+    std::cout << "tag: " << j["pD"].tag() << "\n";
+    std::cout << "ext_tag: " << j["pD"].ext_tag() << "\n";
+    auto bytes = j["pD"].as<std::vector<uint8_t>>();
+    std::cout << "binary data: " << jsoncons::byte_string_view{bytes} << "\n";
+}
+
+```
+Output:
+```
+
+{
+    "pD": "SGVsbG8"
+}
+
+tag: ext
+ext_tag: 128
+binary data: 48,65,6c,6c,6f
+```
+
 ### See also
 
 [encode_bson](encode_bson.md) encodes a json value to the [Bin­ary JSON](http://bsonspec.org/) data format.

doc/ref/bson/encode_bson.md

@@ -14,27 +14,27 @@ void encode_bson(const T& jval, std::ostream& os,
     const bson_decode_options& options = bson_decode_options());            (2)
 
 template <typename T,typename ByteContainer>
-void encode_bson(const allocator_set<Allocator,TempAllocator>& alloc_set,
+void encode_bson(const allocator_set<Alloc,TempAlloc>& alloc_set,
     const T& jval, ByteContainer& cont,
     const bson_decode_options& options = bson_decode_options());            (3) (since 0.171.0) 
 
 template <typename T>
-void encode_bson(const allocator_set<Allocator,TempAllocator>& alloc_set,
+void encode_bson(const allocator_set<Alloc,TempAlloc>& alloc_set,
     const T& jval, std::ostream& os,
     const bson_decode_options& options = bson_decode_options());            (4) (since 0.171.0)
 ```
 
 (1) Writes a value of type T into a byte container in the BSON data format, using the specified (or defaulted) [options](bson_options.md). 
 Type 'T' must be an instantiation of [basic_json](basic_json.md) 
-or support [json_type_traits](../json_type_traits.md). 
+or support jsoncons reflection traits. 
 Type `ByteContainer` must be back insertable and have member type `value_type` with size exactly 8 bits (since 0.152.0.)
 Any of the values types `int8_t`, `uint8_t`, `char`, `unsigned char` and `std::byte` (since C++17) are allowed.
 
 (2) Writes a value of type T into a binary stream in the BSON data format, using the specified (or defaulted) [options](bson_options.md). 
 Type 'T' must be an instantiation of [basic_json](basic_json.md) 
-or support [json_type_traits](../json_type_traits.md). 
+or support jsoncons reflection traits. 
 
-Functions (3)-(4) are identical to (1)-(2) except an [allocator_set](../allocator_set.md) is passed as an additional argument.
+Functions (3)-(4) are identical to (1)-(2) except an [allocator_set](../corelib/allocator_set.md) is passed as an additional argument.
 
 ### Examples
 

doc/ref/bson/try_decode_bson.md

@@ -493,9 +493,9 @@ end_array (n/a)
 
 ### See also
 
-[staj_event](../basic_staj_event.md)  
+[staj_event](../corelib/basic_staj_event.md)  
 
-[staj_array_iterator](staj_array_iterator.md)  
+[staj_array_iterator](../corelib/staj_array_iterator.md)  
 
-[staj_object_iterator](staj_object_iterator.md)  
+[staj_object_iterator](../corelib/staj_object_iterator.md)  
 

doc/ref/cbor/basic_cbor_cursor.md

@@ -70,7 +70,7 @@ Reset encoder to write a new value to a new sink
     void int64_value_with_tag(int64_t value, uint64_t raw_tag);            // (since 1.2.0) 
 
 
-#### Inherited from [jsoncons::basic_json_visitor](../basic_json_visitor.md)
+#### Inherited from [jsoncons::basic_json_visitor](../corelib/basic_json_visitor.md)
 
     void flush();                                                  (1)
 
@@ -553,4 +553,4 @@ d9 04 10 82 82 02 03 86 02 04 08 04 10 19 01 00
 
 ### See also
 
-[byte_string_view](../byte_string_view.md)
+[byte_string_view](../corelib/byte_string_view.md)