Merge branch 'master' of github.com:tgockel/json-voorhees

config/Doxyfile

@@ -31,7 +31,7 @@ FULL_PATH_NAMES        = YES
 STRIP_FROM_PATH        = include src
 STRIP_FROM_INC_PATH    = include src
 SHORT_NAMES            = NO
-JAVADOC_AUTOBRIEF      = NO
+JAVADOC_AUTOBRIEF      = YES
 QT_AUTOBRIEF           = NO
 MULTILINE_CPP_IS_BRIEF = NO
 INHERIT_DOCS           = YES

include/jsonv/all.hpp

@@ -221,6 +221,7 @@
  *  \see http://json.org/
 **/
 
+#include "coerce.hpp"
 #include "config.hpp"
 #include "encode.hpp"
 #include "forward.hpp"

include/jsonv/coerce.hpp

@@ -0,0 +1,127 @@
+/** \file jsonv/coerce.hpp
+ *  A \c jsonv::value has a number of \c as_X operators, which strictly performs a transformation to a C++ data type.
+ *  However, sometimes when working with things like user input, you would like to be more free-form in what you accept
+ *  as "valid."
+ *  
+ *  Copyright (c) 2014 by Travis Gockel. All rights reserved.
+ *
+ *  This program is free software: you can redistribute it and/or modify it under the terms of the Apache License
+ *  as published by the Apache Software Foundation, either version 2 of the License, or (at your option) any later
+ *  version.
+ *
+ *  \author Travis Gockel ([email protected])
+**/
+#ifndef __JSONV_COERCE_HPP_INCLUDED__
+#define __JSONV_COERCE_HPP_INCLUDED__
+
+#include <jsonv/config.hpp>
+#include <jsonv/value.hpp>
+
+#include <map>
+#include <vector>
+
+namespace jsonv
+{
+
+/** \addtogroup Coercion
+ *  \{
+**/
+
+/** Can the given \c kind be converted \a from a kind \a to another?
+ *  
+ *  \returns \c true if the corresponding \c coerce_X function for the specified \a to will successfully return if given
+ *           a \c value of the kind \a from; false if there is no such conversion (the \c coerce_X function might
+ *           throw).
+**/
+JSONV_PUBLIC bool can_coerce(const kind& from, const kind& to);
+
+/** Can the given \c value be converted \a from a kind \a to another?
+ *  
+ *  \note
+ *  This is \e not only a convenience function! There is a special case for converting from a \c string into either a
+ *  \c decimal or \c integer where the contents of the string must be considered. This function will look into the given
+ *  \a from and see if it can successfully perfrom the coercion.
+ *  
+ *  \returns \c true if the corresponding \c coerce_X function for the specified \a to will successfully return if given
+ *           the \c value \a from; false if there is no such conversion (the \c coerce_X function will throw).
+**/
+JSONV_PUBLIC bool can_coerce(const value& from, const kind& to);
+
+/** Coerce \a from into a \c null. If \a from is not \c null, this will throw. It is not clear that there is a use for
+ *  this beyond completeness.
+ *  
+ *  \returns \c nullptr if \a from has \c kind::null.
+ *  \throws kind_error if \a from is not \c kind::null.
+**/
+JSONV_PUBLIC std::nullptr_t coerce_null(const value& from);
+
+/** Coerce \a from into a \c map.
+ *  
+ *  \returns a map of the contents of \a from.
+ *  \throws kind_error if \a from is not \c kind::object.
+**/
+JSONV_PUBLIC std::map<std::string, value> coerce_object(const value& from);
+
+/** Coerce \a from into a \c vector.
+ *  
+ *  \returns a vector of the contents of \a from.
+ *  \throws kind_error if \a from is not \c kind::array.
+**/
+JSONV_PUBLIC std::vector<value> coerce_array(const value& from);
+
+/** Coerce \a from into an \c std::string. If \a from is already \c kind::string, the value is simply returned. If
+ *  \a from is any other \c kind, the result will be the same as \c to_string.
+**/
+JSONV_PUBLIC std::string coerce_string(const value& from);
+
+/** Coerce \a from into an integer. If \a from is a \c decimal lower than the minimum of \c std::int64_t or higher than
+ *  the maximum of \c std::int64_t, it is clamped to the lowest or highest value, respectively.
+ *  
+ *  \returns
+ *   \c kind is... | Rules
+ *   ------------- | -------------------------------------------------
+ *   \c null       | throws \c kind_error
+ *   \c object     | throws \c kind_error
+ *   \c array      | throws \c kind_error
+ *   \c string     | \c parse(from.as_string()).as_integer()
+ *   \c integer    | \c from.as_integer()
+ *   \c decimal    | \c std::int64_t(from.as_decimal())
+ *   \c boolean    | \c from.as_boolean() ? 1 : 0
+**/
+JSONV_PUBLIC std::int64_t coerce_integer(const value& from);
+
+/** Coerce \a from into a \c double.
+ *  
+ *  \returns
+ *   \c kind is... | Rules
+ *   ------------- | -------------------------------------------------
+ *   \c null       | throws \c kind_error
+ *   \c object     | throws \c kind_error
+ *   \c array      | throws \c kind_error
+ *   \c string     | \c parse(from.as_string()).as_decimal()
+ *   \c integer    | \c from.as_decimal()
+ *   \c decimal    | \c from.as_decimal()
+ *   \c boolean    | \c from.as_boolean() ? 1.0 : 0.0
+**/
+JSONV_PUBLIC double coerce_decimal(const value& from);
+
+/** Coerce \a from into a \c bool. This follows the rules of Python's boolean coercion.
+ *  
+ *  \returns
+ *   \c kind is... | Rules
+ *   ------------- | --------------------------------------------------
+ *   \c null       | \c false
+ *   \c object     | \c !from.empty()
+ *   \c array      | \c !from.empty()
+ *   \c string     | \c !from.empty() (even if the value is \c "false")
+ *   \c integer    | \c from != 0
+ *   \c decimal    | \c from != 0.0
+ *   \c boolean    | \c from.as_boolean()
+**/
+JSONV_PUBLIC bool coerce_boolean(const value& from);
+
+/** \} **/
+
+}
+
+#endif/*__JSONV_COERCE_HPP_INCLUDED__*/

include/jsonv/detail/string_ref.hpp

@@ -70,7 +70,7 @@ class string_ref
     string_ref& operator=(const string_ref&) noexcept = default;
 
     template <typename UAllocator>
-    operator std::basic_string<value_type, std::char_traits<value_type>, UAllocator>() const
+    explicit operator std::basic_string<value_type, std::char_traits<value_type>, UAllocator>() const
     {
         return std::basic_string<value_type, std::char_traits<value_type>, UAllocator>(_base, _length);
     }

include/jsonv/value.hpp

@@ -731,14 +731,14 @@ class JSONV_PUBLIC value
      *  
      *  \throws kind_error if the kind is not an object.
     **/
-    size_type count(const string_ref& key) const;
+    size_type count(const std::string& key) const;
 
     /** Attempt to locate a key-value pair with the provided \a key in this object.
      *  
      *  \throws kind_error if the kind is not an object.
     **/
-    object_iterator       find(const string_ref& key);
-    const_object_iterator find(const string_ref& key) const;
+    object_iterator       find(const std::string& key);
+    const_object_iterator find(const std::string& key) const;
 
     /** Insert \a pair into this object. If \a hint is provided, this insertion could be optimized.
      *  
@@ -770,7 +770,7 @@ class JSONV_PUBLIC value
      *  \returns 1 if \a key was erased; 0 if it did not.
      *  \throws kind_error if the kind is not an object.
     **/
-    size_type erase(const string_ref& key);
+    size_type erase(const std::string& key);
 
     /** Erase the item at the given \a position.
      *