Mercurial > hg > ucx / file comparison

comparison: src/cx/json.h

src/cx/json.h

changeset 1513
4d641c6a2f82
parent 1426
3a89b31f0724
equal deleted inserted replaced
1512:0dc866c7863b 1513:4d641c6a2f82
554 * @param len the length of the source buffer 554 * @param len the length of the source buffer
555 * @retval zero success 555 * @retval zero success
556 * @retval non-zero internal allocation error 556 * @retval non-zero internal allocation error
557 * @see cxJsonFill() 557 * @see cxJsonFill()
558 */ 558 */
559 cx_attr_nonnull cx_attr_access_r(2, 3) 559 cx_attr_nonnull_arg(1) cx_attr_access_r(2, 3)
560 CX_EXPORT int cxJsonFilln(CxJson *json, const char *buf, size_t len); 560 CX_EXPORT int cxJsonFilln(CxJson *json, const char *buf, size_t len);
561 561
562 562
563 /** 563 /**
564 * Internal function, do not use. 564 * Internal function, do not use.
639 CX_EXPORT CxJsonValue* cxJsonCreateInteger(const CxAllocator* allocator, int64_t num); 639 CX_EXPORT CxJsonValue* cxJsonCreateInteger(const CxAllocator* allocator, int64_t num);
640 640
641 /** 641 /**
642 * Creates a new JSON string. 642 * Creates a new JSON string.
643 * 643 *
644 * Internal function - use cxJsonCreateString() instead.
645 *
644 * @param allocator the allocator to use 646 * @param allocator the allocator to use
645 * @param str the string data 647 * @param str the string data
646 * @return the new JSON value or @c NULL if allocation fails 648 * @return the new JSON value or @c NULL if allocation fails
647 * @see cxJsonCreateString()
648 * @see cxJsonObjPutString() 649 * @see cxJsonObjPutString()
649 * @see cxJsonArrAddStrings() 650 * @see cxJsonArrAddCxStrings()
650 */ 651 */
651 cx_attr_nodiscard cx_attr_nonnull_arg(2) cx_attr_cstr_arg(2) 652 cx_attr_nodiscard
652 CX_EXPORT CxJsonValue* cxJsonCreateString(const CxAllocator* allocator, const char *str); 653 CX_EXPORT CxJsonValue* cx_json_create_string(const CxAllocator* allocator, cxstring str);
653 654
654 /** 655 /**
655 * Creates a new JSON string. 656 * Creates a new JSON string.
656 * 657 *
657 * @param allocator the allocator to use 658 * @param allocator (@c CxAllocator*) the allocator to use
658 * @param str the string data 659 * @param str the string
659 * @return the new JSON value or @c NULL if allocation fails 660 * @return (@c CxJsonValue*) the new JSON value or @c NULL if allocation fails
660 * @see cxJsonCreateCxString() 661 * @see cxJsonObjPutString()
661 * @see cxJsonObjPutCxString()
662 * @see cxJsonArrAddCxStrings() 662 * @see cxJsonArrAddCxStrings()
663 */ 663 */
664 cx_attr_nodiscard 664 #define cxJsonCreateString(allocator, str) cx_json_create_string(allocator, cx_strcast(str))
665 CX_EXPORT CxJsonValue* cxJsonCreateCxString(const CxAllocator* allocator, cxstring str);
666 665
667 /** 666 /**
668 * Creates a new JSON literal. 667 * Creates a new JSON literal.
669 * 668 *
670 * @param allocator the allocator to use 669 * @param allocator the allocator to use
758 CX_EXPORT int cxJsonArrAddValues(CxJsonValue* arr, CxJsonValue* const* val, size_t count); 757 CX_EXPORT int cxJsonArrAddValues(CxJsonValue* arr, CxJsonValue* const* val, size_t count);
759 758
760 /** 759 /**
761 * Adds or replaces a value within a JSON object. 760 * Adds or replaces a value within a JSON object.
762 * 761 *
763 * The value will be directly added and not copied. 762 * Internal function - use cxJsonObjPut().
764 *
765 * @note If a value with the specified @p name already exists,
766 * it will be (recursively) freed with its own allocator.
767 * 763 *
768 * @param obj the JSON object 764 * @param obj the JSON object
769 * @param name the name of the value 765 * @param name the name of the value
770 * @param child the value 766 * @param child the value
771 * @retval zero success 767 * @retval zero success
772 * @retval non-zero allocation failure 768 * @retval non-zero allocation failure
773 */ 769 */
774 cx_attr_nonnull 770 cx_attr_nonnull
775 CX_EXPORT int cxJsonObjPut(CxJsonValue* obj, cxstring name, CxJsonValue* child); 771 CX_EXPORT int cx_json_obj_put(CxJsonValue* obj, cxstring name, CxJsonValue* child);
772
773 /**
774 * Adds or replaces a value within a JSON object.
775 *
776 * The value will be directly added and not copied.
777 *
778 * @note If a value with the specified @p name already exists,
779 * it will be (recursively) freed with its own allocator.
780 *
781 * @param obj (@c CxJsonValue*) the JSON object
782 * @param name (any string) the name of the value
783 * @param child (@c CxJsonValue*) the value
784 * @retval zero success
785 * @retval non-zero allocation failure
786 */
787 #define cxJsonObjPut(obj, name, child) cx_json_obj_put(obj, cx_strcast(name), child)
776 788
777 /** 789 /**
778 * Creates a new JSON object and adds it to an existing object. 790 * Creates a new JSON object and adds it to an existing object.
791 *
792 * Internal function - use cxJsonObjPutObj().
779 * 793 *
780 * @param obj the target JSON object 794 * @param obj the target JSON object
781 * @param name the name of the new value 795 * @param name the name of the new value
782 * @return the new value or @c NULL if allocation fails 796 * @return the new value or @c NULL if allocation fails
783 * @see cxJsonObjPut() 797 * @see cxJsonObjPut()
784 * @see cxJsonCreateObj() 798 * @see cxJsonCreateObj()
785 */ 799 */
786 cx_attr_nonnull 800 cx_attr_nonnull
787 CX_EXPORT CxJsonValue* cxJsonObjPutObj(CxJsonValue* obj, cxstring name); 801 CX_EXPORT CxJsonValue* cx_json_obj_put_obj(CxJsonValue* obj, cxstring name);
802
803 /**
804 * Creates a new JSON object and adds it to an existing object.
805 *
806 * @param obj (@c CxJsonValue*) the target JSON object
807 * @param name (any string) the name of the new value
808 * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
809 * @see cxJsonObjPut()
810 * @see cxJsonCreateObj()
811 */
812 #define cxJsonObjPutObj(obj, name) cx_json_obj_put_obj(obj, cx_strcast(name))
788 813
789 /** 814 /**
790 * Creates a new JSON array and adds it to an object. 815 * Creates a new JSON array and adds it to an object.
816 *
817 * Internal function - use cxJsonObjPutArr().
791 * 818 *
792 * @param obj the target JSON object 819 * @param obj the target JSON object
793 * @param name the name of the new value 820 * @param name the name of the new value
794 * @return the new value or @c NULL if allocation fails 821 * @return the new value or @c NULL if allocation fails
795 * @see cxJsonObjPut() 822 * @see cxJsonObjPut()
796 * @see cxJsonCreateArr() 823 * @see cxJsonCreateArr()
797 */ 824 */
798 cx_attr_nonnull 825 cx_attr_nonnull
799 CX_EXPORT CxJsonValue* cxJsonObjPutArr(CxJsonValue* obj, cxstring name); 826 CX_EXPORT CxJsonValue* cx_json_obj_put_arr(CxJsonValue* obj, cxstring name);
827
828 /**
829 * Creates a new JSON array and adds it to an object.
830 *
831 * @param obj (@c CxJsonValue*) the target JSON object
832 * @param name (any string) the name of the new value
833 * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
834 * @see cxJsonObjPut()
835 * @see cxJsonCreateArr()
836 */
837 #define cxJsonObjPutArr(obj, name) cx_json_obj_put_arr(obj, cx_strcast(name))
800 838
801 /** 839 /**
802 * Creates a new JSON number and adds it to an object. 840 * Creates a new JSON number and adds it to an object.
841 *
842 * Internal function - use cxJsonObjPutNumber().
803 * 843 *
804 * @param obj the target JSON object 844 * @param obj the target JSON object
805 * @param name the name of the new value 845 * @param name the name of the new value
806 * @param num the numeric value 846 * @param num the numeric value
807 * @return the new value or @c NULL if allocation fails 847 * @return the new value or @c NULL if allocation fails
808 * @see cxJsonObjPut() 848 * @see cxJsonObjPut()
809 * @see cxJsonCreateNumber() 849 * @see cxJsonCreateNumber()
810 */ 850 */
811 cx_attr_nonnull 851 cx_attr_nonnull
812 CX_EXPORT CxJsonValue* cxJsonObjPutNumber(CxJsonValue* obj, cxstring name, double num); 852 CX_EXPORT CxJsonValue* cx_json_obj_put_number(CxJsonValue* obj, cxstring name, double num);
853
854 /**
855 * Creates a new JSON number and adds it to an object.
856 *
857 * @param obj (@c CxJsonValue*) the target JSON object
858 * @param name (any string) the name of the new value
859 * @param num (@c double) the numeric value
860 * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
861 * @see cxJsonObjPut()
862 * @see cxJsonCreateNumber()
863 */
864 #define cxJsonObjPutNumber(obj, name, num) cx_json_obj_put_number(obj, cx_strcast(name), num)
813 865
814 /** 866 /**
815 * Creates a new JSON number, based on an integer, and adds it to an object. 867 * Creates a new JSON number, based on an integer, and adds it to an object.
868 *
869 * Internal function - use cxJsonObjPutInteger().
816 * 870 *
817 * @param obj the target JSON object 871 * @param obj the target JSON object
818 * @param name the name of the new value 872 * @param name the name of the new value
819 * @param num the numeric value 873 * @param num the numeric value
820 * @return the new value or @c NULL if allocation fails 874 * @return the new value or @c NULL if allocation fails
821 * @see cxJsonObjPut() 875 * @see cxJsonObjPut()
822 * @see cxJsonCreateInteger() 876 * @see cxJsonCreateInteger()
823 */ 877 */
824 cx_attr_nonnull 878 cx_attr_nonnull
825 CX_EXPORT CxJsonValue* cxJsonObjPutInteger(CxJsonValue* obj, cxstring name, int64_t num); 879 CX_EXPORT CxJsonValue* cx_json_obj_put_integer(CxJsonValue* obj, cxstring name, int64_t num);
880
881 /**
882 * Creates a new JSON number, based on an integer, and adds it to an object.
883 *
884 * @param obj (@c CxJsonValue*) the target JSON object
885 * @param name (any string) the name of the new value
886 * @param num (@c int64_t) the numeric value
887 * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
888 * @see cxJsonObjPut()
889 * @see cxJsonCreateInteger()
890 */
891 #define cxJsonObjPutInteger(obj, name, num) cx_json_obj_put_integer(obj, cx_strcast(name), num)
826 892
827 /** 893 /**
828 * Creates a new JSON string and adds it to an object. 894 * Creates a new JSON string and adds it to an object.
829 * 895 *
830 * The string data is copied. 896 * Internal function - use cxJsonObjPutString()
831 * 897 *
832 * @param obj the target JSON object 898 * @param obj the target JSON object
833 * @param name the name of the new value 899 * @param name the name of the new value
834 * @param str the string data 900 * @param str the string data
835 * @return the new value or @c NULL if allocation fails 901 * @return the new value or @c NULL if allocation fails
836 * @see cxJsonObjPut() 902 * @see cxJsonObjPut()
837 * @see cxJsonCreateString() 903 * @see cxJsonCreateString()
838 */ 904 */
839 cx_attr_nonnull cx_attr_cstr_arg(3) 905 cx_attr_nonnull
840 CX_EXPORT CxJsonValue* cxJsonObjPutString(CxJsonValue* obj, cxstring name, const char* str); 906 CX_EXPORT CxJsonValue* cx_json_obj_put_string(CxJsonValue* obj, cxstring name, cxstring str);
841 907
842 /** 908 /**
843 * Creates a new JSON string and adds it to an object. 909 * Creates a new JSON string and adds it to an object.
844 * 910 *
845 * The string data is copied. 911 * The string data is copied.
846 * 912 *
847 * @param obj the target JSON object 913 * @param obj (@c CxJsonValue*) the target JSON object
848 * @param name the name of the new value 914 * @param name (any string) the name of the new value
849 * @param str the string data 915 * @param str (any string) the string data
850 * @return the new value or @c NULL if allocation fails 916 * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
851 * @see cxJsonObjPut() 917 * @see cxJsonObjPut()
852 * @see cxJsonCreateCxString() 918 * @see cxJsonCreateString()
853 */ 919 */
854 cx_attr_nonnull 920 #define cxJsonObjPutString(obj, name, str) cx_json_obj_put_string(obj, cx_strcast(name), cx_strcast(str))
855 CX_EXPORT CxJsonValue* cxJsonObjPutCxString(CxJsonValue* obj, cxstring name, cxstring str);
856 921
857 /** 922 /**
858 * Creates a new JSON literal and adds it to an object. 923 * Creates a new JSON literal and adds it to an object.
924 *
925 * Internal function - use cxJsonObjPutLiteral().
859 * 926 *
860 * @param obj the target JSON object 927 * @param obj the target JSON object
861 * @param name the name of the new value 928 * @param name the name of the new value
862 * @param lit the type of literal 929 * @param lit the type of literal
863 * @return the new value or @c NULL if allocation fails 930 * @return the new value or @c NULL if allocation fails
864 * @see cxJsonObjPut() 931 * @see cxJsonObjPut()
865 * @see cxJsonCreateLiteral() 932 * @see cxJsonCreateLiteral()
866 */ 933 */
867 cx_attr_nonnull 934 cx_attr_nonnull
868 CX_EXPORT CxJsonValue* cxJsonObjPutLiteral(CxJsonValue* obj, cxstring name, CxJsonLiteral lit); 935 CX_EXPORT CxJsonValue* cx_json_obj_put_literal(CxJsonValue* obj, cxstring name, CxJsonLiteral lit);
936
937 /**
938 * Creates a new JSON literal and adds it to an object.
939 *
940 * @param obj (@c CxJsonValue*) the target JSON object
941 * @param name (any string) the name of the new value
942 * @param lit (@c CxJsonLiteral) the type of literal
943 * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
944 * @see cxJsonObjPut()
945 * @see cxJsonCreateLiteral()
946 */
947 #define cxJsonObjPutLiteral(obj, name, lit) cx_json_obj_put_literal(obj, cx_strcast(name), lit)
869 948
870 /** 949 /**
871 * Recursively deallocates the memory of a JSON value. 950 * Recursively deallocates the memory of a JSON value.
872 * 951 *
873 * @remark The type of each deallocated value will be changed 952 * @remark The type of each deallocated value will be changed
1186 */ 1265 */
1187 cx_attr_nonnull cx_attr_nodiscard 1266 cx_attr_nonnull cx_attr_nodiscard
1188 CX_EXPORT CxIterator cxJsonArrIter(const CxJsonValue *value); 1267 CX_EXPORT CxIterator cxJsonArrIter(const CxJsonValue *value);
1189 1268
1190 /** 1269 /**
1270 * Returns the size of a JSON object.
1271 *
1272 * If the @p value is not a JSON object, the behavior is undefined.
1273 *
1274 * @param value the JSON value
1275 * @return the size of the object, i.e., the number of key/value pairs
1276 * @see cxJsonIsObject()
1277 */
1278 cx_attr_nonnull
1279 CX_INLINE size_t cxJsonObjSize(const CxJsonValue *value) {
1280 return value->value.object.values_size;
1281 }
1282
1283 /**
1191 * Returns an iterator over the JSON object members. 1284 * Returns an iterator over the JSON object members.
1192 * 1285 *
1193 * The iterator yields values of type @c CxJsonObjValue* which 1286 * The iterator yields values of type @c CxJsonObjValue* which
1194 * contain the name and value of the member. 1287 * contain the name and value of the member.
1195 * 1288 *

Mercurial Repository: ucx

mercurial