Mercurial > hg > ucx / file comparison

comparison: src/cx/json.h

src/cx/json.h

changeset 1097
ef4a6cb318ec
parent 1082
46cdc8689fc4
child 1117
54df904472b0
equal deleted inserted replaced
1096:2cb1ed4da55d 1097:ef4a6cb318ec
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE. 26 * POSSIBILITY OF SUCH DAMAGE.
27 */ 27 */
28 /** 28 /**
29 * \file json.h 29 * @file json.h
30 * \brief Interface for parsing data from JSON files. 30 * @brief Interface for parsing data from JSON files.
31 * \author Mike Becker 31 * @author Mike Becker
32 * \author Olaf Wintermann 32 * @author Olaf Wintermann
33 * \copyright 2-Clause BSD License 33 * @copyright 2-Clause BSD License
34 */ 34 */
35 35
36 #ifndef UCX_JSON_H 36 #ifndef UCX_JSON_H
37 #define UCX_JSON_H 37 #define UCX_JSON_H
38 38
144 /** 144 /**
145 * JSON literal types. 145 * JSON literal types.
146 */ 146 */
147 enum cx_json_literal { 147 enum cx_json_literal {
148 /** 148 /**
149 * The \c null literal. 149 * The @c null literal.
150 */ 150 */
151 CX_JSON_NULL, 151 CX_JSON_NULL,
152 /** 152 /**
153 * The \c true literal. 153 * The @c true literal.
154 */ 154 */
155 CX_JSON_TRUE, 155 CX_JSON_TRUE,
156 /** 156 /**
157 * The \c false literal. 157 * The @c false literal.
158 */ 158 */
159 CX_JSON_FALSE 159 CX_JSON_FALSE
160 }; 160 };
161 161
162 /** 162 /**
262 */ 262 */
263 const CxAllocator *allocator; 263 const CxAllocator *allocator;
264 /** 264 /**
265 * The type of this value. 265 * The type of this value.
266 * 266 *
267 * Specifies how the \c value union shall be resolved. 267 * Specifies how the @c value union shall be resolved.
268 */ 268 */
269 CxJsonValueType type; 269 CxJsonValueType type;
270 /** 270 /**
271 * The value data. 271 * The value data.
272 */ 272 */
307 /** 307 /**
308 * The token type. 308 * The token type.
309 */ 309 */
310 CxJsonTokenType tokentype; 310 CxJsonTokenType tokentype;
311 /** 311 /**
312 * True, iff the \c content must be passed to cx_strfree(). 312 * True, iff the @c content must be passed to cx_strfree().
313 */ 313 */
314 bool allocated; 314 bool allocated;
315 /** 315 /**
316 * The token text, if any. 316 * The token text, if any.
317 * 317 *
401 CX_JSON_INCOMPLETE_DATA, 401 CX_JSON_INCOMPLETE_DATA,
402 /** 402 /**
403 * Not used as a status and never returned by any function. 403 * Not used as a status and never returned by any function.
404 * 404 *
405 * You can use this enumerator to check for all "good" status results 405 * You can use this enumerator to check for all "good" status results
406 * by checking if the status is less than \c CX_JSON_OK. 406 * by checking if the status is less than @c CX_JSON_OK.
407 * 407 *
408 * A "good" status means, that you can refill data and continue parsing. 408 * A "good" status means, that you can refill data and continue parsing.
409 */ 409 */
410 CX_JSON_OK, 410 CX_JSON_OK,
411 /** 411 /**
455 * Set true to use spaces instead of tab characters. 455 * Set true to use spaces instead of tab characters.
456 * Indentation is only used in pretty output. 456 * Indentation is only used in pretty output.
457 */ 457 */
458 bool indent_space; 458 bool indent_space;
459 /** 459 /**
460 * If \c indent_space is true, this is the number of spaces per tab. 460 * If @c indent_space is true, this is the number of spaces per tab.
461 * Indentation is only used in pretty output. 461 * Indentation is only used in pretty output.
462 */ 462 */
463 uint8_t indent; 463 uint8_t indent;
464 }; 464 };
465 465
491 * This function blocks until all data is written or an error when trying 491 * This function blocks until all data is written or an error when trying
492 * to write data occurs. 492 * to write data occurs.
493 * The write operation is not atomic in the sense that it might happen 493 * The write operation is not atomic in the sense that it might happen
494 * that the data is only partially written when an error occurs with no 494 * that the data is only partially written when an error occurs with no
495 * way to indicate how much data was written. 495 * way to indicate how much data was written.
496 * To avoid this problem, you can use a CxBuffer as \p target which is 496 * To avoid this problem, you can use a CxBuffer as @p target which is
497 * unlikely to fail a write operation and either use the buffer's flush 497 * unlikely to fail a write operation and either use the buffer's flush
498 * feature to relay the data or use the data in the buffer manually to 498 * feature to relay the data or use the data in the buffer manually to
499 * write it to the actual target. 499 * write it to the actual target.
500 * 500 *
501 * @param target the buffer or stream where to write to 501 * @param target the buffer or stream where to write to
502 * @param value the value that shall be written 502 * @param value the value that shall be written
503 * @param wfunc the write function to use 503 * @param wfunc the write function to use
504 * @param settings formatting settings (or \c NULL to use a compact default) 504 * @param settings formatting settings (or @c NULL to use a compact default)
505 * @return zero on success, non-zero when no or not all data could be written 505 * @retval zero success
506 * @retval non-zero when no or not all data could be written
506 */ 507 */
507 cx_attr_nonnull_arg(1, 2, 3) 508 cx_attr_nonnull_arg(1, 2, 3)
508 int cxJsonWrite( 509 int cxJsonWrite(
509 void* target, 510 void* target,
510 const CxJsonValue* value, 511 const CxJsonValue* value,
558 * an allocation of a new buffer and copying the previous contents. 559 * an allocation of a new buffer and copying the previous contents.
559 * 560 *
560 * @param json the json interface 561 * @param json the json interface
561 * @param buf the source buffer 562 * @param buf the source buffer
562 * @param len the length of the source buffer 563 * @param len the length of the source buffer
563 * @return zero on success, non-zero on internal allocation error 564 * @retval zero success
565 * @retval non-zero internal allocation error
564 * @see cxJsonFill() 566 * @see cxJsonFill()
565 */ 567 */
566 cx_attr_nonnull 568 cx_attr_nonnull
567 cx_attr_access_r(2, 3) 569 cx_attr_access_r(2, 3)
568 int cxJsonFilln(CxJson *json, const char *buf, size_t len); 570 int cxJsonFilln(CxJson *json, const char *buf, size_t len);
598 extern "C" { 600 extern "C" {
599 #else // __cplusplus 601 #else // __cplusplus
600 /** 602 /**
601 * Fills the input buffer. 603 * Fills the input buffer.
602 * 604 *
603 * @remark The JSON interface tries to avoid copying the input data. 605 * The JSON interface tries to avoid copying the input data.
604 * When you use this function and cxJsonNext() interleaving, 606 * When you use this function and cxJsonNext() interleaving,
605 * no copies are performed. However, you must not free the 607 * no copies are performed. However, you must not free the
606 * pointer to the data in that case. When you invoke the fill 608 * pointer to the data in that case. When you invoke the fill
607 * function more than once before calling cxJsonNext(), 609 * function more than once before calling cxJsonNext(),
608 * the additional data is appended - inevitably leading to 610 * the additional data is appended - inevitably leading to
609 * an allocation of a new buffer and copying the previous contents. 611 * an allocation of a new buffer and copying the previous contents.
610 * 612 *
611 * @param json the json interface 613 * @param json the json interface
612 * @param buf the source string 614 * @param str the source string
613 * @return zero on success, non-zero on internal allocation error 615 * @retval zero success
616 * @retval non-zero internal allocation error
614 * @see cxJsonFilln() 617 * @see cxJsonFilln()
615 */ 618 */
616 #define cxJsonFill(json, str) _Generic((str), \ 619 #define cxJsonFill(json, str) _Generic((str), \
617 cxstring: cx_json_fill_cxstr, \ 620 cxstring: cx_json_fill_cxstr, \
618 cxmutstr: cx_json_fill_mutstr, \ 621 cxmutstr: cx_json_fill_mutstr, \
657 660
658 /** 661 /**
659 * Creates a new (empty) JSON object. 662 * Creates a new (empty) JSON object.
660 * 663 *
661 * @param allocator the allocator to use 664 * @param allocator the allocator to use
662 * @return the new JSON object or \c NULL if allocation fails 665 * @return the new JSON object or @c NULL if allocation fails
666 * @see cxJsonObjPutObj()
667 * @see cxJsonArrAddValues()
663 */ 668 */
664 cx_attr_nodiscard 669 cx_attr_nodiscard
665 CxJsonValue* cxJsonCreateObj(const CxAllocator* allocator); 670 CxJsonValue* cxJsonCreateObj(const CxAllocator* allocator);
666 671
667 /** 672 /**
668 * Creates a new (empty) JSON array. 673 * Creates a new (empty) JSON array.
669 * 674 *
670 * @param allocator the allocator to use 675 * @param allocator the allocator to use
671 * @return the new JSON array or \c NULL if allocation fails 676 * @return the new JSON array or @c NULL if allocation fails
677 * @see cxJsonObjPutArr()
678 * @see cxJsonArrAddValues()
672 */ 679 */
673 cx_attr_nodiscard 680 cx_attr_nodiscard
674 CxJsonValue* cxJsonCreateArr(const CxAllocator* allocator); 681 CxJsonValue* cxJsonCreateArr(const CxAllocator* allocator);
675 682
676 /** 683 /**
677 * Creates a new JSON number value. 684 * Creates a new JSON number value.
678 * 685 *
679 * @param allocator the allocator to use 686 * @param allocator the allocator to use
680 * @param num the numeric value 687 * @param num the numeric value
681 * @return the new JSON value or \c NULL if allocation fails 688 * @return the new JSON value or @c NULL if allocation fails
682 * @see cxJsonObjPutNumber() 689 * @see cxJsonObjPutNumber()
683 * @see cxJsonArrAddNumbers() 690 * @see cxJsonArrAddNumbers()
684 */ 691 */
685 cx_attr_nodiscard 692 cx_attr_nodiscard
686 CxJsonValue* cxJsonCreateNumber(const CxAllocator* allocator, double num); 693 CxJsonValue* cxJsonCreateNumber(const CxAllocator* allocator, double num);
688 /** 695 /**
689 * Creates a new JSON number value based on an integer. 696 * Creates a new JSON number value based on an integer.
690 * 697 *
691 * @param allocator the allocator to use 698 * @param allocator the allocator to use
692 * @param num the numeric value 699 * @param num the numeric value
693 * @return the new JSON value or \c NULL if allocation fails 700 * @return the new JSON value or @c NULL if allocation fails
694 * @see cxJsonObjPutInteger() 701 * @see cxJsonObjPutInteger()
695 * @see cxJsonArrAddIntegers() 702 * @see cxJsonArrAddIntegers()
696 */ 703 */
697 cx_attr_nodiscard 704 cx_attr_nodiscard
698 CxJsonValue* cxJsonCreateInteger(const CxAllocator* allocator, int64_t num); 705 CxJsonValue* cxJsonCreateInteger(const CxAllocator* allocator, int64_t num);
700 /** 707 /**
701 * Creates a new JSON string. 708 * Creates a new JSON string.
702 * 709 *
703 * @param allocator the allocator to use 710 * @param allocator the allocator to use
704 * @param str the string data 711 * @param str the string data
705 * @return the new JSON value or \c NULL if allocation fails 712 * @return the new JSON value or @c NULL if allocation fails
706 * @see cxJsonCreateCxString() 713 * @see cxJsonCreateString()
707 * @see cxJsonObjPutString() 714 * @see cxJsonObjPutString()
708 * @see cxJsonArrAddStrings() 715 * @see cxJsonArrAddStrings()
709 */ 716 */
710 cx_attr_nodiscard 717 cx_attr_nodiscard
711 cx_attr_nonnull_arg(2) 718 cx_attr_nonnull_arg(2)
715 /** 722 /**
716 * Creates a new JSON string. 723 * Creates a new JSON string.
717 * 724 *
718 * @param allocator the allocator to use 725 * @param allocator the allocator to use
719 * @param str the string data 726 * @param str the string data
720 * @return the new JSON value or \c NULL if allocation fails 727 * @return the new JSON value or @c NULL if allocation fails
721 * @see cxJsonCreateString() 728 * @see cxJsonCreateCxString()
722 * @see cxJsonObjPutCxString() 729 * @see cxJsonObjPutCxString()
723 * @see cxJsonArrAddCxStrings() 730 * @see cxJsonArrAddCxStrings()
724 */ 731 */
725 cx_attr_nodiscard 732 cx_attr_nodiscard
726 CxJsonValue* cxJsonCreateCxString(const CxAllocator* allocator, cxstring str); 733 CxJsonValue* cxJsonCreateCxString(const CxAllocator* allocator, cxstring str);
728 /** 735 /**
729 * Creates a new JSON literal. 736 * Creates a new JSON literal.
730 * 737 *
731 * @param allocator the allocator to use 738 * @param allocator the allocator to use
732 * @param lit the type of literal 739 * @param lit the type of literal
733 * @return the new JSON value or \c NULL if allocation fails 740 * @return the new JSON value or @c NULL if allocation fails
734 * @see cxJsonObjPutLiteral() 741 * @see cxJsonObjPutLiteral()
735 * @see cxJsonArrAddLiterals() 742 * @see cxJsonArrAddLiterals()
736 */ 743 */
737 cx_attr_nodiscard 744 cx_attr_nodiscard
738 CxJsonValue* cxJsonCreateLiteral(const CxAllocator* allocator, CxJsonLiteral lit); 745 CxJsonValue* cxJsonCreateLiteral(const CxAllocator* allocator, CxJsonLiteral lit);
741 * Adds number values to a JSON array. 748 * Adds number values to a JSON array.
742 * 749 *
743 * @param arr the JSON array 750 * @param arr the JSON array
744 * @param num the array of values 751 * @param num the array of values
745 * @param count the number of elements 752 * @param count the number of elements
746 * @return zero on success, non-zero on allocation failure 753 * @retval zero success
754 * @retval non-zero allocation failure
747 */ 755 */
748 cx_attr_nonnull 756 cx_attr_nonnull
749 cx_attr_access_r(2, 3) 757 cx_attr_access_r(2, 3)
750 int cxJsonArrAddNumbers(CxJsonValue* arr, const double* num, size_t count); 758 int cxJsonArrAddNumbers(CxJsonValue* arr, const double* num, size_t count);
751 759
753 * Adds number values, of which all are integers, to a JSON array. 761 * Adds number values, of which all are integers, to a JSON array.
754 * 762 *
755 * @param arr the JSON array 763 * @param arr the JSON array
756 * @param num the array of values 764 * @param num the array of values
757 * @param count the number of elements 765 * @param count the number of elements
758 * @return zero on success, non-zero on allocation failure 766 * @retval zero success
767 * @retval non-zero allocation failure
759 */ 768 */
760 cx_attr_nonnull 769 cx_attr_nonnull
761 cx_attr_access_r(2, 3) 770 cx_attr_access_r(2, 3)
762 int cxJsonArrAddIntegers(CxJsonValue* arr, const int64_t* num, size_t count); 771 int cxJsonArrAddIntegers(CxJsonValue* arr, const int64_t* num, size_t count);
763 772
767 * The strings will be copied with the allocator of the array. 776 * The strings will be copied with the allocator of the array.
768 * 777 *
769 * @param arr the JSON array 778 * @param arr the JSON array
770 * @param str the array of strings 779 * @param str the array of strings
771 * @param count the number of elements 780 * @param count the number of elements
772 * @return zero on success, non-zero on allocation failure 781 * @retval zero success
782 * @retval non-zero allocation failure
773 * @see cxJsonArrAddCxStrings() 783 * @see cxJsonArrAddCxStrings()
774 */ 784 */
775 cx_attr_nonnull 785 cx_attr_nonnull
776 cx_attr_access_r(2, 3) 786 cx_attr_access_r(2, 3)
777 int cxJsonArrAddStrings(CxJsonValue* arr, const char* const* str, size_t count); 787 int cxJsonArrAddStrings(CxJsonValue* arr, const char* const* str, size_t count);
782 * The strings will be copied with the allocator of the array. 792 * The strings will be copied with the allocator of the array.
783 * 793 *
784 * @param arr the JSON array 794 * @param arr the JSON array
785 * @param str the array of strings 795 * @param str the array of strings
786 * @param count the number of elements 796 * @param count the number of elements
787 * @return zero on success, non-zero on allocation failure 797 * @retval zero success
798 * @retval non-zero allocation failure
788 * @see cxJsonArrAddStrings() 799 * @see cxJsonArrAddStrings()
789 */ 800 */
790 cx_attr_nonnull 801 cx_attr_nonnull
791 cx_attr_access_r(2, 3) 802 cx_attr_access_r(2, 3)
792 int cxJsonArrAddCxStrings(CxJsonValue* arr, const cxstring* str, size_t count); 803 int cxJsonArrAddCxStrings(CxJsonValue* arr, const cxstring* str, size_t count);
795 * Adds literals to a JSON array. 806 * Adds literals to a JSON array.
796 * 807 *
797 * @param arr the JSON array 808 * @param arr the JSON array
798 * @param lit the array of literal types 809 * @param lit the array of literal types
799 * @param count the number of elements 810 * @param count the number of elements
800 * @return zero on success, non-zero on allocation failure 811 * @retval zero success
812 * @retval non-zero allocation failure
801 */ 813 */
802 cx_attr_nonnull 814 cx_attr_nonnull
803 cx_attr_access_r(2, 3) 815 cx_attr_access_r(2, 3)
804 int cxJsonArrAddLiterals(CxJsonValue* arr, const CxJsonLiteral* lit, size_t count); 816 int cxJsonArrAddLiterals(CxJsonValue* arr, const CxJsonLiteral* lit, size_t count);
805 817
806 /** 818 /**
807 * Add arbitrary values to a JSON array. 819 * Add arbitrary values to a JSON array.
808 * 820 *
809 * \note In contrast to all other add functions, this function adds the values 821 * @attention In contrast to all other add functions, this function adds the values
810 * directly to the array instead of copying them. 822 * directly to the array instead of copying them.
811 * 823 *
812 * @param arr the JSON array 824 * @param arr the JSON array
813 * @param val the values 825 * @param val the values
814 * @param count the number of elements 826 * @param count the number of elements
815 * @return zero on success, non-zero on allocation failure 827 * @retval zero success
828 * @retval non-zero allocation failure
816 */ 829 */
817 cx_attr_nonnull 830 cx_attr_nonnull
818 cx_attr_access_r(2, 3) 831 cx_attr_access_r(2, 3)
819 int cxJsonArrAddValues(CxJsonValue* arr, CxJsonValue* const* val, size_t count); 832 int cxJsonArrAddValues(CxJsonValue* arr, CxJsonValue* const* val, size_t count);
820 833
821 /** 834 /**
822 * Adds or replaces a value within a JSON object. 835 * Adds or replaces a value within a JSON object.
823 * 836 *
824 * The value will be directly added and not copied. 837 * The value will be directly added and not copied.
825 * 838 *
826 * \note If a value with the specified \p name already exists, 839 * @note If a value with the specified @p name already exists,
827 * it will be (recursively) freed with its own allocator. 840 * it will be (recursively) freed with its own allocator.
828 * 841 *
829 * @param obj the JSON object 842 * @param obj the JSON object
830 * @param name the name of the value 843 * @param name the name of the value
831 * @param child the value 844 * @param child the value
832 * @return zero on success, non-zero on allocation failure 845 * @retval zero success
846 * @retval non-zero allocation failure
833 */ 847 */
834 cx_attr_nonnull 848 cx_attr_nonnull
835 int cxJsonObjPut(CxJsonValue* obj, cxstring name, CxJsonValue* child); 849 int cxJsonObjPut(CxJsonValue* obj, cxstring name, CxJsonValue* child);
836 850
837 /** 851 /**
838 * Creates a new JSON object and adds it to an existing object. 852 * Creates a new JSON object and adds it to an existing object.
839 * 853 *
840 * @param obj the target JSON object 854 * @param obj the target JSON object
841 * @param name the name of the new value 855 * @param name the name of the new value
842 * @return the new value or \c NULL if allocation fails 856 * @return the new value or @c NULL if allocation fails
843 * @see cxJsonObjPut() 857 * @see cxJsonObjPut()
844 * @see cxJsonCreateObj() 858 * @see cxJsonCreateObj()
845 */ 859 */
846 cx_attr_nonnull 860 cx_attr_nonnull
847 CxJsonValue* cxJsonObjPutObj(CxJsonValue* obj, cxstring name); 861 CxJsonValue* cxJsonObjPutObj(CxJsonValue* obj, cxstring name);
849 /** 863 /**
850 * Creates a new JSON array and adds it to an object. 864 * Creates a new JSON array and adds it to an object.
851 * 865 *
852 * @param obj the target JSON object 866 * @param obj the target JSON object
853 * @param name the name of the new value 867 * @param name the name of the new value
854 * @return the new value or \c NULL if allocation fails 868 * @return the new value or @c NULL if allocation fails
855 * @see cxJsonObjPut() 869 * @see cxJsonObjPut()
856 * @see cxJsonCreateArr() 870 * @see cxJsonCreateArr()
857 */ 871 */
858 cx_attr_nonnull 872 cx_attr_nonnull
859 CxJsonValue* cxJsonObjPutArr(CxJsonValue* obj, cxstring name); 873 CxJsonValue* cxJsonObjPutArr(CxJsonValue* obj, cxstring name);
862 * Creates a new JSON number and adds it to an object. 876 * Creates a new JSON number and adds it to an object.
863 * 877 *
864 * @param obj the target JSON object 878 * @param obj the target JSON object
865 * @param name the name of the new value 879 * @param name the name of the new value
866 * @param num the numeric value 880 * @param num the numeric value
867 * @return the new value or \c NULL if allocation fails 881 * @return the new value or @c NULL if allocation fails
868 * @see cxJsonObjPut() 882 * @see cxJsonObjPut()
869 * @see cxJsonCreateNumber() 883 * @see cxJsonCreateNumber()
870 */ 884 */
871 cx_attr_nonnull 885 cx_attr_nonnull
872 CxJsonValue* cxJsonObjPutNumber(CxJsonValue* obj, cxstring name, double num); 886 CxJsonValue* cxJsonObjPutNumber(CxJsonValue* obj, cxstring name, double num);
875 * Creates a new JSON number, based on an integer, and adds it to an object. 889 * Creates a new JSON number, based on an integer, and adds it to an object.
876 * 890 *
877 * @param obj the target JSON object 891 * @param obj the target JSON object
878 * @param name the name of the new value 892 * @param name the name of the new value
879 * @param num the numeric value 893 * @param num the numeric value
880 * @return the new value or \c NULL if allocation fails 894 * @return the new value or @c NULL if allocation fails
881 * @see cxJsonObjPut() 895 * @see cxJsonObjPut()
882 * @see cxJsonCreateInteger() 896 * @see cxJsonCreateInteger()
883 */ 897 */
884 cx_attr_nonnull 898 cx_attr_nonnull
885 CxJsonValue* cxJsonObjPutInteger(CxJsonValue* obj, cxstring name, int64_t num); 899 CxJsonValue* cxJsonObjPutInteger(CxJsonValue* obj, cxstring name, int64_t num);
890 * The string data is copied. 904 * The string data is copied.
891 * 905 *
892 * @param obj the target JSON object 906 * @param obj the target JSON object
893 * @param name the name of the new value 907 * @param name the name of the new value
894 * @param str the string data 908 * @param str the string data
895 * @return the new value or \c NULL if allocation fails 909 * @return the new value or @c NULL if allocation fails
896 * @see cxJsonObjPut() 910 * @see cxJsonObjPut()
897 * @see cxJsonCreateString() 911 * @see cxJsonCreateString()
898 */ 912 */
899 cx_attr_nonnull 913 cx_attr_nonnull
900 cx_attr_cstr_arg(3) 914 cx_attr_cstr_arg(3)
906 * The string data is copied. 920 * The string data is copied.
907 * 921 *
908 * @param obj the target JSON object 922 * @param obj the target JSON object
909 * @param name the name of the new value 923 * @param name the name of the new value
910 * @param str the string data 924 * @param str the string data
911 * @return the new value or \c NULL if allocation fails 925 * @return the new value or @c NULL if allocation fails
912 * @see cxJsonObjPut() 926 * @see cxJsonObjPut()
913 * @see cxJsonCreateCxString() 927 * @see cxJsonCreateCxString()
914 */ 928 */
915 cx_attr_nonnull 929 cx_attr_nonnull
916 CxJsonValue* cxJsonObjPutCxString(CxJsonValue* obj, cxstring name, cxstring str); 930 CxJsonValue* cxJsonObjPutCxString(CxJsonValue* obj, cxstring name, cxstring str);
919 * Creates a new JSON literal and adds it to an object. 933 * Creates a new JSON literal and adds it to an object.
920 * 934 *
921 * @param obj the target JSON object 935 * @param obj the target JSON object
922 * @param name the name of the new value 936 * @param name the name of the new value
923 * @param lit the type of literal 937 * @param lit the type of literal
924 * @return the new value or \c NULL if allocation fails 938 * @return the new value or @c NULL if allocation fails
925 * @see cxJsonObjPut() 939 * @see cxJsonObjPut()
926 * @see cxJsonCreateLiteral() 940 * @see cxJsonCreateLiteral()
927 */ 941 */
928 cx_attr_nonnull 942 cx_attr_nonnull
929 CxJsonValue* cxJsonObjPutLiteral(CxJsonValue* obj, cxstring name, CxJsonLiteral lit); 943 CxJsonValue* cxJsonObjPutLiteral(CxJsonValue* obj, cxstring name, CxJsonLiteral lit);
930 944
931 /** 945 /**
932 * Recursively deallocates the memory of a JSON value. 946 * Recursively deallocates the memory of a JSON value.
933 * 947 *
934 * \remark The type of each deallocated value will be changed 948 * @remark The type of each deallocated value will be changed
935 * to #CX_JSON_NOTHING and values of such type will be skipped 949 * to #CX_JSON_NOTHING and values of such type will be skipped
936 * by the de-allocation. That means, this function protects 950 * by the de-allocation. That means, this function protects
937 * you from double-frees when you are accidentally freeing 951 * you from double-frees when you are accidentally freeing
938 * a nested value and then the parent value (or vice versa). 952 * a nested value and then the parent value (or vice versa).
939 * 953 *
942 void cxJsonValueFree(CxJsonValue *value); 956 void cxJsonValueFree(CxJsonValue *value);
943 957
944 /** 958 /**
945 * Tries to obtain the next JSON value. 959 * Tries to obtain the next JSON value.
946 * 960 *
961 * Before this function can be called, the input buffer needs
962 * to be filled with cxJsonFill().
963 *
964 * When this function returns #CX_JSON_INCOMPLETE_DATA, you can
965 * add the missing data with another invocation of cxJsonFill()
966 * and then repeat the call to cxJsonNext().
947 * 967 *
948 * @param json the json interface 968 * @param json the json interface
949 * @param value a pointer where the next value shall be stored 969 * @param value a pointer where the next value shall be stored
950 * @return a status code 970 * @retval CX_JSON_NO_ERROR successfully retrieve the @p value
971 * @retval CX_JSON_NO_DATA there is no (more) data in the buffer to read from
972 * @retval CX_JSON_INCOMPLETE_DATA an incomplete value was read
973 * and more data needs to be filled
974 * @retval CX_JSON_NULL_DATA the buffer was never initialized
975 * @retval CX_JSON_BUFFER_ALLOC_FAILED allocating internal buffer space failed
976 * @retval CX_JSON_VALUE_ALLOC_FAILED allocating memory for a CxJsonValue failed
977 * @retval CX_JSON_FORMAT_ERROR_NUMBER the JSON text contains an illegally formatted number
978 * @retval CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN JSON syntax error
951 */ 979 */
952 cx_attr_nonnull 980 cx_attr_nonnull
953 cx_attr_access_w(2) 981 cx_attr_access_w(2)
954 CxJsonStatus cxJsonNext(CxJson *json, CxJsonValue **value); 982 CxJsonStatus cxJsonNext(CxJson *json, CxJsonValue **value);
955 983
956 /** 984 /**
957 * Checks if the specified value is a JSON object. 985 * Checks if the specified value is a JSON object.
958 * 986 *
959 * @param value a pointer to the value 987 * @param value a pointer to the value
960 * @return true if the value is a JSON object, false otherwise 988 * @retval true the value is a JSON object
989 * @retval false otherwise
961 */ 990 */
962 cx_attr_nonnull 991 cx_attr_nonnull
963 static inline bool cxJsonIsObject(const CxJsonValue *value) { 992 static inline bool cxJsonIsObject(const CxJsonValue *value) {
964 return value->type == CX_JSON_OBJECT; 993 return value->type == CX_JSON_OBJECT;
965 } 994 }
966 995
967 /** 996 /**
968 * Checks if the specified value is a JSON array. 997 * Checks if the specified value is a JSON array.
969 * 998 *
970 * @param value a pointer to the value 999 * @param value a pointer to the value
971 * @return true if the value is a JSON array, false otherwise 1000 * @retval true the value is a JSON array
1001 * @retval false otherwise
972 */ 1002 */
973 cx_attr_nonnull 1003 cx_attr_nonnull
974 static inline bool cxJsonIsArray(const CxJsonValue *value) { 1004 static inline bool cxJsonIsArray(const CxJsonValue *value) {
975 return value->type == CX_JSON_ARRAY; 1005 return value->type == CX_JSON_ARRAY;
976 } 1006 }
977 1007
978 /** 1008 /**
979 * Checks if the specified value is a string. 1009 * Checks if the specified value is a string.
980 * 1010 *
981 * @param value a pointer to the value 1011 * @param value a pointer to the value
982 * @return true if the value is a string, false otherwise 1012 * @retval true the value is a string
1013 * @retval false otherwise
983 */ 1014 */
984 cx_attr_nonnull 1015 cx_attr_nonnull
985 static inline bool cxJsonIsString(const CxJsonValue *value) { 1016 static inline bool cxJsonIsString(const CxJsonValue *value) {
986 return value->type == CX_JSON_STRING; 1017 return value->type == CX_JSON_STRING;
987 } 1018 }
991 * 1022 *
992 * This function will return true for both floating point and 1023 * This function will return true for both floating point and
993 * integer numbers. 1024 * integer numbers.
994 * 1025 *
995 * @param value a pointer to the value 1026 * @param value a pointer to the value
996 * @return true if the value is a JSON number, false otherwise 1027 * @retval true the value is a JSON number
1028 * @retval false otherwise
997 * @see cxJsonIsInteger() 1029 * @see cxJsonIsInteger()
998 */ 1030 */
999 cx_attr_nonnull 1031 cx_attr_nonnull
1000 static inline bool cxJsonIsNumber(const CxJsonValue *value) { 1032 static inline bool cxJsonIsNumber(const CxJsonValue *value) {
1001 return value->type == CX_JSON_NUMBER || value->type == CX_JSON_INTEGER; 1033 return value->type == CX_JSON_NUMBER || value->type == CX_JSON_INTEGER;
1003 1035
1004 /** 1036 /**
1005 * Checks if the specified value is an integer number. 1037 * Checks if the specified value is an integer number.
1006 * 1038 *
1007 * @param value a pointer to the value 1039 * @param value a pointer to the value
1008 * @return true if the value is an integer number, false otherwise 1040 * @retval true the value is an integer number
1041 * @retval false otherwise
1009 * @see cxJsonIsNumber() 1042 * @see cxJsonIsNumber()
1010 */ 1043 */
1011 cx_attr_nonnull 1044 cx_attr_nonnull
1012 static inline bool cxJsonIsInteger(const CxJsonValue *value) { 1045 static inline bool cxJsonIsInteger(const CxJsonValue *value) {
1013 return value->type == CX_JSON_INTEGER; 1046 return value->type == CX_JSON_INTEGER;
1014 } 1047 }
1015 1048
1016 /** 1049 /**
1017 * Checks if the specified value is a JSON literal. 1050 * Checks if the specified value is a JSON literal.
1018 * 1051 *
1019 * JSON literals are \c true, \c false, and \c null. 1052 * JSON literals are @c true, @c false, and @c null.
1020 * 1053 *
1021 * @param value a pointer to the value 1054 * @param value a pointer to the value
1022 * @return true if the value is a JSON literal, false otherwise 1055 * @retval true the value is a JSON literal
1056 * @retval false otherwise
1023 * @see cxJsonIsTrue() 1057 * @see cxJsonIsTrue()
1024 * @see cxJsonIsFalse() 1058 * @see cxJsonIsFalse()
1025 * @see cxJsonIsNull() 1059 * @see cxJsonIsNull()
1026 */ 1060 */
1027 cx_attr_nonnull 1061 cx_attr_nonnull
1031 1065
1032 /** 1066 /**
1033 * Checks if the specified value is a Boolean literal. 1067 * Checks if the specified value is a Boolean literal.
1034 * 1068 *
1035 * @param value a pointer to the value 1069 * @param value a pointer to the value
1036 * @return true if the value is either \c true or \c false, false otherwise 1070 * @retval true the value is either @c true or @c false
1071 * @retval false otherwise
1037 * @see cxJsonIsTrue() 1072 * @see cxJsonIsTrue()
1038 * @see cxJsonIsFalse() 1073 * @see cxJsonIsFalse()
1039 */ 1074 */
1040 cx_attr_nonnull 1075 cx_attr_nonnull
1041 static inline bool cxJsonIsBool(const CxJsonValue *value) { 1076 static inline bool cxJsonIsBool(const CxJsonValue *value) {
1042 return cxJsonIsLiteral(value) && value->value.literal != CX_JSON_NULL; 1077 return cxJsonIsLiteral(value) && value->value.literal != CX_JSON_NULL;
1043 } 1078 }
1044 1079
1045 /** 1080 /**
1046 * Checks if the specified value is \c true. 1081 * Checks if the specified value is @c true.
1047 * 1082 *
1048 * \remark Be advised, that this is not the same as 1083 * @remark Be advised, that this is not the same as
1049 * testing \c !cxJsonIsFalse(v). 1084 * testing @c !cxJsonIsFalse(v).
1050 * 1085 *
1051 * @param value a pointer to the value 1086 * @param value a pointer to the value
1052 * @return true if the value is \c true, false otherwise 1087 * @retval true the value is @c true
1088 * @retval false otherwise
1053 * @see cxJsonIsBool() 1089 * @see cxJsonIsBool()
1054 * @see cxJsonIsFalse() 1090 * @see cxJsonIsFalse()
1055 */ 1091 */
1056 cx_attr_nonnull 1092 cx_attr_nonnull
1057 static inline bool cxJsonIsTrue(const CxJsonValue *value) { 1093 static inline bool cxJsonIsTrue(const CxJsonValue *value) {
1058 return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_TRUE; 1094 return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_TRUE;
1059 } 1095 }
1060 1096
1061 /** 1097 /**
1062 * Checks if the specified value is \c false. 1098 * Checks if the specified value is @c false.
1063 * 1099 *
1064 * \remark Be advised, that this is not the same as 1100 * @remark Be advised, that this is not the same as
1065 * testing \c !cxJsonIsTrue(v). 1101 * testing @c !cxJsonIsTrue(v).
1066 * 1102 *
1067 * @param value a pointer to the value 1103 * @param value a pointer to the value
1068 * @return true if the value is \c false, false otherwise 1104 * @retval true the value is @c false
1105 * @retval false otherwise
1069 * @see cxJsonIsBool() 1106 * @see cxJsonIsBool()
1070 * @see cxJsonIsTrue() 1107 * @see cxJsonIsTrue()
1071 */ 1108 */
1072 cx_attr_nonnull 1109 cx_attr_nonnull
1073 static inline bool cxJsonIsFalse(const CxJsonValue *value) { 1110 static inline bool cxJsonIsFalse(const CxJsonValue *value) {
1074 return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_FALSE; 1111 return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_FALSE;
1075 } 1112 }
1076 1113
1077 /** 1114 /**
1078 * Checks if the specified value is \c null. 1115 * Checks if the specified value is @c null.
1079 * 1116 *
1080 * @param value a pointer to the value 1117 * @param value a pointer to the value
1081 * @return true if the value is \c null, false otherwise 1118 * @retval true the value is @c null
1119 * @retval false otherwise
1082 * @see cxJsonIsLiteral() 1120 * @see cxJsonIsLiteral()
1083 */ 1121 */
1084 cx_attr_nonnull 1122 cx_attr_nonnull
1085 static inline bool cxJsonIsNull(const CxJsonValue *value) { 1123 static inline bool cxJsonIsNull(const CxJsonValue *value) {
1086 return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_NULL; 1124 return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_NULL;
1087 } 1125 }
1088 1126
1089 /** 1127 /**
1090 * Obtains a C string from the given JSON value. 1128 * Obtains a C string from the given JSON value.
1091 * 1129 *
1092 * If the \p value is not a string, the behavior is undefined. 1130 * If the @p value is not a string, the behavior is undefined.
1093 * 1131 *
1094 * @param value the JSON value 1132 * @param value the JSON value
1095 * @return the value represented as C string 1133 * @return the value represented as C string
1096 * @see cxJsonIsString() 1134 * @see cxJsonIsString()
1097 */ 1135 */
1102 } 1140 }
1103 1141
1104 /** 1142 /**
1105 * Obtains a UCX string from the given JSON value. 1143 * Obtains a UCX string from the given JSON value.
1106 * 1144 *
1107 * If the \p value is not a string, the behavior is undefined. 1145 * If the @p value is not a string, the behavior is undefined.
1108 * 1146 *
1109 * @param value the JSON value 1147 * @param value the JSON value
1110 * @return the value represented as UCX string 1148 * @return the value represented as UCX string
1111 * @see cxJsonIsString() 1149 * @see cxJsonIsString()
1112 */ 1150 */
1116 } 1154 }
1117 1155
1118 /** 1156 /**
1119 * Obtains a mutable UCX string from the given JSON value. 1157 * Obtains a mutable UCX string from the given JSON value.
1120 * 1158 *
1121 * If the \p value is not a string, the behavior is undefined. 1159 * If the @p value is not a string, the behavior is undefined.
1122 * 1160 *
1123 * @param value the JSON value 1161 * @param value the JSON value
1124 * @return the value represented as mutable UCX string 1162 * @return the value represented as mutable UCX string
1125 * @see cxJsonIsString() 1163 * @see cxJsonIsString()
1126 */ 1164 */
1130 } 1168 }
1131 1169
1132 /** 1170 /**
1133 * Obtains a double-precision floating point value from the given JSON value. 1171 * Obtains a double-precision floating point value from the given JSON value.
1134 * 1172 *
1135 * If the \p value is not a JSON number, the behavior is undefined. 1173 * If the @p value is not a JSON number, the behavior is undefined.
1136 * 1174 *
1137 * @param value the JSON value 1175 * @param value the JSON value
1138 * @return the value represented as double 1176 * @return the value represented as double
1139 * @see cxJsonIsNumber() 1177 * @see cxJsonIsNumber()
1140 */ 1178 */
1148 } 1186 }
1149 1187
1150 /** 1188 /**
1151 * Obtains a 64-bit signed integer from the given JSON value. 1189 * Obtains a 64-bit signed integer from the given JSON value.
1152 * 1190 *
1153 * If the \p value is not a JSON number, the behavior is undefined. 1191 * If the @p value is not a JSON number, the behavior is undefined.
1154 * If it is a JSON number, but not an integer, the value will be 1192 * If it is a JSON number, but not an integer, the value will be
1155 * converted to an integer, possibly losing precision. 1193 * converted to an integer, possibly losing precision.
1156 * 1194 *
1157 * @param value the JSON value 1195 * @param value the JSON value
1158 * @return the value represented as double 1196 * @return the value represented as double
1169 } 1207 }
1170 1208
1171 /** 1209 /**
1172 * Obtains a Boolean value from the given JSON value. 1210 * Obtains a Boolean value from the given JSON value.
1173 * 1211 *
1174 * If the \p value is not a JSON literal, the behavior is undefined. 1212 * If the @p value is not a JSON literal, the behavior is undefined.
1175 * The \c null literal is interpreted as \c false. 1213 * The @c null literal is interpreted as @c false.
1176 * 1214 *
1177 * @param value the JSON value 1215 * @param value the JSON value
1178 * @return the value represented as double 1216 * @return the value represented as double
1179 * @see cxJsonIsLiteral() 1217 * @see cxJsonIsLiteral()
1180 */ 1218 */
1184 } 1222 }
1185 1223
1186 /** 1224 /**
1187 * Returns the size of a JSON array. 1225 * Returns the size of a JSON array.
1188 * 1226 *
1189 * If the \p value is not a JSON array, the behavior is undefined. 1227 * If the @p value is not a JSON array, the behavior is undefined.
1190 * 1228 *
1191 * @param value the JSON value 1229 * @param value the JSON value
1192 * @return the size of the array 1230 * @return the size of the array
1193 * @see cxJsonIsArray() 1231 * @see cxJsonIsArray()
1194 */ 1232 */
1198 } 1236 }
1199 1237
1200 /** 1238 /**
1201 * Returns an element from a JSON array. 1239 * Returns an element from a JSON array.
1202 * 1240 *
1203 * If the \p value is not a JSON array, the behavior is undefined. 1241 * If the @p value is not a JSON array, the behavior is undefined.
1204 * 1242 *
1205 * This function guarantees to return a value. If the index is 1243 * This function guarantees to return a value. If the index is
1206 * out of bounds, the returned value will be of type 1244 * out of bounds, the returned value will be of type
1207 * #CX_JSON_NOTHING, but never \c NULL. 1245 * #CX_JSON_NOTHING, but never @c NULL.
1208 * 1246 *
1209 * @param value the JSON value 1247 * @param value the JSON value
1210 * @param index the index in the array 1248 * @param index the index in the array
1211 * @return the value at the specified index 1249 * @return the value at the specified index
1212 * @see cxJsonIsArray() 1250 * @see cxJsonIsArray()
1216 CxJsonValue *cxJsonArrGet(const CxJsonValue *value, size_t index); 1254 CxJsonValue *cxJsonArrGet(const CxJsonValue *value, size_t index);
1217 1255
1218 /** 1256 /**
1219 * Returns an iterator over the JSON array elements. 1257 * Returns an iterator over the JSON array elements.
1220 * 1258 *
1221 * The iterator yields values of type \c CxJsonValue* . 1259 * The iterator yields values of type @c CxJsonValue* .
1222 * 1260 *
1223 * If the \p value is not a JSON array, the behavior is undefined. 1261 * If the @p value is not a JSON array, the behavior is undefined.
1224 * 1262 *
1225 * @param value the JSON value 1263 * @param value the JSON value
1226 * @return an iterator over the array elements 1264 * @return an iterator over the array elements
1227 * @see cxJsonIsArray() 1265 * @see cxJsonIsArray()
1228 */ 1266 */
1231 CxIterator cxJsonArrIter(const CxJsonValue *value); 1269 CxIterator cxJsonArrIter(const CxJsonValue *value);
1232 1270
1233 /** 1271 /**
1234 * Returns an iterator over the JSON object members. 1272 * Returns an iterator over the JSON object members.
1235 * 1273 *
1236 * The iterator yields values of type \c CxJsonObjValue* which 1274 * The iterator yields values of type @c CxJsonObjValue* which
1237 * contain the name and value of the member. 1275 * contain the name and value of the member.
1238 * 1276 *
1239 * If the \p value is not a JSON object, the behavior is undefined. 1277 * If the @p value is not a JSON object, the behavior is undefined.
1240 * 1278 *
1241 * @param value the JSON value 1279 * @param value the JSON value
1242 * @return an iterator over the object members 1280 * @return an iterator over the object members
1243 * @see cxJsonIsObject() 1281 * @see cxJsonIsObject()
1244 */ 1282 */
1271 extern "C" { 1309 extern "C" {
1272 #else 1310 #else
1273 /** 1311 /**
1274 * Returns a value corresponding to a key in a JSON object. 1312 * Returns a value corresponding to a key in a JSON object.
1275 * 1313 *
1276 * If the \p value is not a JSON object, the behavior is undefined. 1314 * If the @p value is not a JSON object, the behavior is undefined.
1277 * 1315 *
1278 * This function guarantees to return a JSON value. If the 1316 * This function guarantees to return a JSON value. If the
1279 * object does not contain \p name, the returned JSON value 1317 * object does not contain @p name, the returned JSON value
1280 * will be of type #CX_JSON_NOTHING, but never \c NULL. 1318 * will be of type #CX_JSON_NOTHING, but never @c NULL.
1281 * 1319 *
1282 * @param value the JSON object 1320 * @param value the JSON object
1283 * @param name the key to look up 1321 * @param name the key to look up
1284 * @return the value corresponding to the key 1322 * @return the value corresponding to the key
1285 * @see cxJsonIsObject() 1323 * @see cxJsonIsObject()

Mercurial Repository: ucx

mercurial