src/cx/json.h

changeset 1180
4c3a69b9723a
parent 1139
7dfa5bcf39ee
equal deleted inserted replaced
1179:ca4c6f590a08 1180:4c3a69b9723a
473 * Creates a default writer configuration for compact output. 473 * Creates a default writer configuration for compact output.
474 * 474 *
475 * @return new JSON writer settings 475 * @return new JSON writer settings
476 */ 476 */
477 cx_attr_nodiscard 477 cx_attr_nodiscard
478 cx_attr_export
478 CxJsonWriter cxJsonWriterCompact(void); 479 CxJsonWriter cxJsonWriterCompact(void);
479 480
480 /** 481 /**
481 * Creates a default writer configuration for pretty output. 482 * Creates a default writer configuration for pretty output.
482 * 483 *
483 * @param use_spaces false if you want tabs, true if you want four spaces instead 484 * @param use_spaces false if you want tabs, true if you want four spaces instead
484 * @return new JSON writer settings 485 * @return new JSON writer settings
485 */ 486 */
486 cx_attr_nodiscard 487 cx_attr_nodiscard
488 cx_attr_export
487 CxJsonWriter cxJsonWriterPretty(bool use_spaces); 489 CxJsonWriter cxJsonWriterPretty(bool use_spaces);
488 490
489 /** 491 /**
490 * Writes a JSON value to a buffer or stream. 492 * Writes a JSON value to a buffer or stream.
491 * 493 *
505 * @param settings formatting settings (or @c NULL to use a compact default) 507 * @param settings formatting settings (or @c NULL to use a compact default)
506 * @retval zero success 508 * @retval zero success
507 * @retval non-zero when no or not all data could be written 509 * @retval non-zero when no or not all data could be written
508 */ 510 */
509 cx_attr_nonnull_arg(1, 2, 3) 511 cx_attr_nonnull_arg(1, 2, 3)
512 cx_attr_export
510 int cxJsonWrite( 513 int cxJsonWrite(
511 void* target, 514 void* target,
512 const CxJsonValue* value, 515 const CxJsonValue* value,
513 cx_write_func wfunc, 516 cx_write_func wfunc,
514 const CxJsonWriter* settings 517 const CxJsonWriter* settings
520 * @param json the json interface 523 * @param json the json interface
521 * @param allocator the allocator that shall be used for the produced values 524 * @param allocator the allocator that shall be used for the produced values
522 * @see cxJsonDestroy() 525 * @see cxJsonDestroy()
523 */ 526 */
524 cx_attr_nonnull_arg(1) 527 cx_attr_nonnull_arg(1)
528 cx_attr_export
525 void cxJsonInit(CxJson *json, const CxAllocator *allocator); 529 void cxJsonInit(CxJson *json, const CxAllocator *allocator);
526 530
527 /** 531 /**
528 * Destroys the json interface. 532 * Destroys the json interface.
529 * 533 *
530 * @param json the json interface 534 * @param json the json interface
531 * @see cxJsonInit() 535 * @see cxJsonInit()
532 */ 536 */
533 cx_attr_nonnull 537 cx_attr_nonnull
538 cx_attr_export
534 void cxJsonDestroy(CxJson *json); 539 void cxJsonDestroy(CxJson *json);
535 540
536 /** 541 /**
537 * Destroys and re-initializes the json interface. 542 * Destroys and re-initializes the json interface.
538 * 543 *
566 * @retval non-zero internal allocation error 571 * @retval non-zero internal allocation error
567 * @see cxJsonFill() 572 * @see cxJsonFill()
568 */ 573 */
569 cx_attr_nonnull 574 cx_attr_nonnull
570 cx_attr_access_r(2, 3) 575 cx_attr_access_r(2, 3)
576 cx_attr_export
571 int cxJsonFilln(CxJson *json, const char *buf, size_t len); 577 int cxJsonFilln(CxJson *json, const char *buf, size_t len);
572 578
573 #ifdef __cplusplus 579 #ifdef __cplusplus
574 } // extern "C" 580 } // extern "C"
575 581
666 * @return the new JSON object or @c NULL if allocation fails 672 * @return the new JSON object or @c NULL if allocation fails
667 * @see cxJsonObjPutObj() 673 * @see cxJsonObjPutObj()
668 * @see cxJsonArrAddValues() 674 * @see cxJsonArrAddValues()
669 */ 675 */
670 cx_attr_nodiscard 676 cx_attr_nodiscard
677 cx_attr_export
671 CxJsonValue* cxJsonCreateObj(const CxAllocator* allocator); 678 CxJsonValue* cxJsonCreateObj(const CxAllocator* allocator);
672 679
673 /** 680 /**
674 * Creates a new (empty) JSON array. 681 * Creates a new (empty) JSON array.
675 * 682 *
677 * @return the new JSON array or @c NULL if allocation fails 684 * @return the new JSON array or @c NULL if allocation fails
678 * @see cxJsonObjPutArr() 685 * @see cxJsonObjPutArr()
679 * @see cxJsonArrAddValues() 686 * @see cxJsonArrAddValues()
680 */ 687 */
681 cx_attr_nodiscard 688 cx_attr_nodiscard
689 cx_attr_export
682 CxJsonValue* cxJsonCreateArr(const CxAllocator* allocator); 690 CxJsonValue* cxJsonCreateArr(const CxAllocator* allocator);
683 691
684 /** 692 /**
685 * Creates a new JSON number value. 693 * Creates a new JSON number value.
686 * 694 *
689 * @return the new JSON value or @c NULL if allocation fails 697 * @return the new JSON value or @c NULL if allocation fails
690 * @see cxJsonObjPutNumber() 698 * @see cxJsonObjPutNumber()
691 * @see cxJsonArrAddNumbers() 699 * @see cxJsonArrAddNumbers()
692 */ 700 */
693 cx_attr_nodiscard 701 cx_attr_nodiscard
702 cx_attr_export
694 CxJsonValue* cxJsonCreateNumber(const CxAllocator* allocator, double num); 703 CxJsonValue* cxJsonCreateNumber(const CxAllocator* allocator, double num);
695 704
696 /** 705 /**
697 * Creates a new JSON number value based on an integer. 706 * Creates a new JSON number value based on an integer.
698 * 707 *
701 * @return the new JSON value or @c NULL if allocation fails 710 * @return the new JSON value or @c NULL if allocation fails
702 * @see cxJsonObjPutInteger() 711 * @see cxJsonObjPutInteger()
703 * @see cxJsonArrAddIntegers() 712 * @see cxJsonArrAddIntegers()
704 */ 713 */
705 cx_attr_nodiscard 714 cx_attr_nodiscard
715 cx_attr_export
706 CxJsonValue* cxJsonCreateInteger(const CxAllocator* allocator, int64_t num); 716 CxJsonValue* cxJsonCreateInteger(const CxAllocator* allocator, int64_t num);
707 717
708 /** 718 /**
709 * Creates a new JSON string. 719 * Creates a new JSON string.
710 * 720 *
716 * @see cxJsonArrAddStrings() 726 * @see cxJsonArrAddStrings()
717 */ 727 */
718 cx_attr_nodiscard 728 cx_attr_nodiscard
719 cx_attr_nonnull_arg(2) 729 cx_attr_nonnull_arg(2)
720 cx_attr_cstr_arg(2) 730 cx_attr_cstr_arg(2)
731 cx_attr_export
721 CxJsonValue* cxJsonCreateString(const CxAllocator* allocator, const char *str); 732 CxJsonValue* cxJsonCreateString(const CxAllocator* allocator, const char *str);
722 733
723 /** 734 /**
724 * Creates a new JSON string. 735 * Creates a new JSON string.
725 * 736 *
729 * @see cxJsonCreateCxString() 740 * @see cxJsonCreateCxString()
730 * @see cxJsonObjPutCxString() 741 * @see cxJsonObjPutCxString()
731 * @see cxJsonArrAddCxStrings() 742 * @see cxJsonArrAddCxStrings()
732 */ 743 */
733 cx_attr_nodiscard 744 cx_attr_nodiscard
745 cx_attr_export
734 CxJsonValue* cxJsonCreateCxString(const CxAllocator* allocator, cxstring str); 746 CxJsonValue* cxJsonCreateCxString(const CxAllocator* allocator, cxstring str);
735 747
736 /** 748 /**
737 * Creates a new JSON literal. 749 * Creates a new JSON literal.
738 * 750 *
741 * @return the new JSON value or @c NULL if allocation fails 753 * @return the new JSON value or @c NULL if allocation fails
742 * @see cxJsonObjPutLiteral() 754 * @see cxJsonObjPutLiteral()
743 * @see cxJsonArrAddLiterals() 755 * @see cxJsonArrAddLiterals()
744 */ 756 */
745 cx_attr_nodiscard 757 cx_attr_nodiscard
758 cx_attr_export
746 CxJsonValue* cxJsonCreateLiteral(const CxAllocator* allocator, CxJsonLiteral lit); 759 CxJsonValue* cxJsonCreateLiteral(const CxAllocator* allocator, CxJsonLiteral lit);
747 760
748 /** 761 /**
749 * Adds number values to a JSON array. 762 * Adds number values to a JSON array.
750 * 763 *
754 * @retval zero success 767 * @retval zero success
755 * @retval non-zero allocation failure 768 * @retval non-zero allocation failure
756 */ 769 */
757 cx_attr_nonnull 770 cx_attr_nonnull
758 cx_attr_access_r(2, 3) 771 cx_attr_access_r(2, 3)
772 cx_attr_export
759 int cxJsonArrAddNumbers(CxJsonValue* arr, const double* num, size_t count); 773 int cxJsonArrAddNumbers(CxJsonValue* arr, const double* num, size_t count);
760 774
761 /** 775 /**
762 * Adds number values, of which all are integers, to a JSON array. 776 * Adds number values, of which all are integers, to a JSON array.
763 * 777 *
767 * @retval zero success 781 * @retval zero success
768 * @retval non-zero allocation failure 782 * @retval non-zero allocation failure
769 */ 783 */
770 cx_attr_nonnull 784 cx_attr_nonnull
771 cx_attr_access_r(2, 3) 785 cx_attr_access_r(2, 3)
786 cx_attr_export
772 int cxJsonArrAddIntegers(CxJsonValue* arr, const int64_t* num, size_t count); 787 int cxJsonArrAddIntegers(CxJsonValue* arr, const int64_t* num, size_t count);
773 788
774 /** 789 /**
775 * Adds strings to a JSON array. 790 * Adds strings to a JSON array.
776 * 791 *
783 * @retval non-zero allocation failure 798 * @retval non-zero allocation failure
784 * @see cxJsonArrAddCxStrings() 799 * @see cxJsonArrAddCxStrings()
785 */ 800 */
786 cx_attr_nonnull 801 cx_attr_nonnull
787 cx_attr_access_r(2, 3) 802 cx_attr_access_r(2, 3)
803 cx_attr_export
788 int cxJsonArrAddStrings(CxJsonValue* arr, const char* const* str, size_t count); 804 int cxJsonArrAddStrings(CxJsonValue* arr, const char* const* str, size_t count);
789 805
790 /** 806 /**
791 * Adds strings to a JSON array. 807 * Adds strings to a JSON array.
792 * 808 *
799 * @retval non-zero allocation failure 815 * @retval non-zero allocation failure
800 * @see cxJsonArrAddStrings() 816 * @see cxJsonArrAddStrings()
801 */ 817 */
802 cx_attr_nonnull 818 cx_attr_nonnull
803 cx_attr_access_r(2, 3) 819 cx_attr_access_r(2, 3)
820 cx_attr_export
804 int cxJsonArrAddCxStrings(CxJsonValue* arr, const cxstring* str, size_t count); 821 int cxJsonArrAddCxStrings(CxJsonValue* arr, const cxstring* str, size_t count);
805 822
806 /** 823 /**
807 * Adds literals to a JSON array. 824 * Adds literals to a JSON array.
808 * 825 *
812 * @retval zero success 829 * @retval zero success
813 * @retval non-zero allocation failure 830 * @retval non-zero allocation failure
814 */ 831 */
815 cx_attr_nonnull 832 cx_attr_nonnull
816 cx_attr_access_r(2, 3) 833 cx_attr_access_r(2, 3)
834 cx_attr_export
817 int cxJsonArrAddLiterals(CxJsonValue* arr, const CxJsonLiteral* lit, size_t count); 835 int cxJsonArrAddLiterals(CxJsonValue* arr, const CxJsonLiteral* lit, size_t count);
818 836
819 /** 837 /**
820 * Add arbitrary values to a JSON array. 838 * Add arbitrary values to a JSON array.
821 * 839 *
828 * @retval zero success 846 * @retval zero success
829 * @retval non-zero allocation failure 847 * @retval non-zero allocation failure
830 */ 848 */
831 cx_attr_nonnull 849 cx_attr_nonnull
832 cx_attr_access_r(2, 3) 850 cx_attr_access_r(2, 3)
851 cx_attr_export
833 int cxJsonArrAddValues(CxJsonValue* arr, CxJsonValue* const* val, size_t count); 852 int cxJsonArrAddValues(CxJsonValue* arr, CxJsonValue* const* val, size_t count);
834 853
835 /** 854 /**
836 * Adds or replaces a value within a JSON object. 855 * Adds or replaces a value within a JSON object.
837 * 856 *
845 * @param child the value 864 * @param child the value
846 * @retval zero success 865 * @retval zero success
847 * @retval non-zero allocation failure 866 * @retval non-zero allocation failure
848 */ 867 */
849 cx_attr_nonnull 868 cx_attr_nonnull
869 cx_attr_export
850 int cxJsonObjPut(CxJsonValue* obj, cxstring name, CxJsonValue* child); 870 int cxJsonObjPut(CxJsonValue* obj, cxstring name, CxJsonValue* child);
851 871
852 /** 872 /**
853 * Creates a new JSON object and adds it to an existing object. 873 * Creates a new JSON object and adds it to an existing object.
854 * 874 *
857 * @return the new value or @c NULL if allocation fails 877 * @return the new value or @c NULL if allocation fails
858 * @see cxJsonObjPut() 878 * @see cxJsonObjPut()
859 * @see cxJsonCreateObj() 879 * @see cxJsonCreateObj()
860 */ 880 */
861 cx_attr_nonnull 881 cx_attr_nonnull
882 cx_attr_export
862 CxJsonValue* cxJsonObjPutObj(CxJsonValue* obj, cxstring name); 883 CxJsonValue* cxJsonObjPutObj(CxJsonValue* obj, cxstring name);
863 884
864 /** 885 /**
865 * Creates a new JSON array and adds it to an object. 886 * Creates a new JSON array and adds it to an object.
866 * 887 *
869 * @return the new value or @c NULL if allocation fails 890 * @return the new value or @c NULL if allocation fails
870 * @see cxJsonObjPut() 891 * @see cxJsonObjPut()
871 * @see cxJsonCreateArr() 892 * @see cxJsonCreateArr()
872 */ 893 */
873 cx_attr_nonnull 894 cx_attr_nonnull
895 cx_attr_export
874 CxJsonValue* cxJsonObjPutArr(CxJsonValue* obj, cxstring name); 896 CxJsonValue* cxJsonObjPutArr(CxJsonValue* obj, cxstring name);
875 897
876 /** 898 /**
877 * Creates a new JSON number and adds it to an object. 899 * Creates a new JSON number and adds it to an object.
878 * 900 *
882 * @return the new value or @c NULL if allocation fails 904 * @return the new value or @c NULL if allocation fails
883 * @see cxJsonObjPut() 905 * @see cxJsonObjPut()
884 * @see cxJsonCreateNumber() 906 * @see cxJsonCreateNumber()
885 */ 907 */
886 cx_attr_nonnull 908 cx_attr_nonnull
909 cx_attr_export
887 CxJsonValue* cxJsonObjPutNumber(CxJsonValue* obj, cxstring name, double num); 910 CxJsonValue* cxJsonObjPutNumber(CxJsonValue* obj, cxstring name, double num);
888 911
889 /** 912 /**
890 * Creates a new JSON number, based on an integer, and adds it to an object. 913 * Creates a new JSON number, based on an integer, and adds it to an object.
891 * 914 *
895 * @return the new value or @c NULL if allocation fails 918 * @return the new value or @c NULL if allocation fails
896 * @see cxJsonObjPut() 919 * @see cxJsonObjPut()
897 * @see cxJsonCreateInteger() 920 * @see cxJsonCreateInteger()
898 */ 921 */
899 cx_attr_nonnull 922 cx_attr_nonnull
923 cx_attr_export
900 CxJsonValue* cxJsonObjPutInteger(CxJsonValue* obj, cxstring name, int64_t num); 924 CxJsonValue* cxJsonObjPutInteger(CxJsonValue* obj, cxstring name, int64_t num);
901 925
902 /** 926 /**
903 * Creates a new JSON string and adds it to an object. 927 * Creates a new JSON string and adds it to an object.
904 * 928 *
911 * @see cxJsonObjPut() 935 * @see cxJsonObjPut()
912 * @see cxJsonCreateString() 936 * @see cxJsonCreateString()
913 */ 937 */
914 cx_attr_nonnull 938 cx_attr_nonnull
915 cx_attr_cstr_arg(3) 939 cx_attr_cstr_arg(3)
940 cx_attr_export
916 CxJsonValue* cxJsonObjPutString(CxJsonValue* obj, cxstring name, const char* str); 941 CxJsonValue* cxJsonObjPutString(CxJsonValue* obj, cxstring name, const char* str);
917 942
918 /** 943 /**
919 * Creates a new JSON string and adds it to an object. 944 * Creates a new JSON string and adds it to an object.
920 * 945 *
926 * @return the new value or @c NULL if allocation fails 951 * @return the new value or @c NULL if allocation fails
927 * @see cxJsonObjPut() 952 * @see cxJsonObjPut()
928 * @see cxJsonCreateCxString() 953 * @see cxJsonCreateCxString()
929 */ 954 */
930 cx_attr_nonnull 955 cx_attr_nonnull
956 cx_attr_export
931 CxJsonValue* cxJsonObjPutCxString(CxJsonValue* obj, cxstring name, cxstring str); 957 CxJsonValue* cxJsonObjPutCxString(CxJsonValue* obj, cxstring name, cxstring str);
932 958
933 /** 959 /**
934 * Creates a new JSON literal and adds it to an object. 960 * Creates a new JSON literal and adds it to an object.
935 * 961 *
939 * @return the new value or @c NULL if allocation fails 965 * @return the new value or @c NULL if allocation fails
940 * @see cxJsonObjPut() 966 * @see cxJsonObjPut()
941 * @see cxJsonCreateLiteral() 967 * @see cxJsonCreateLiteral()
942 */ 968 */
943 cx_attr_nonnull 969 cx_attr_nonnull
970 cx_attr_export
944 CxJsonValue* cxJsonObjPutLiteral(CxJsonValue* obj, cxstring name, CxJsonLiteral lit); 971 CxJsonValue* cxJsonObjPutLiteral(CxJsonValue* obj, cxstring name, CxJsonLiteral lit);
945 972
946 /** 973 /**
947 * Recursively deallocates the memory of a JSON value. 974 * Recursively deallocates the memory of a JSON value.
948 * 975 *
952 * you from double-frees when you are accidentally freeing 979 * you from double-frees when you are accidentally freeing
953 * a nested value and then the parent value (or vice versa). 980 * a nested value and then the parent value (or vice versa).
954 * 981 *
955 * @param value the value 982 * @param value the value
956 */ 983 */
984 cx_attr_export
957 void cxJsonValueFree(CxJsonValue *value); 985 void cxJsonValueFree(CxJsonValue *value);
958 986
959 /** 987 /**
960 * Tries to obtain the next JSON value. 988 * Tries to obtain the next JSON value.
961 * 989 *
978 * @retval CX_JSON_FORMAT_ERROR_NUMBER the JSON text contains an illegally formatted number 1006 * @retval CX_JSON_FORMAT_ERROR_NUMBER the JSON text contains an illegally formatted number
979 * @retval CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN JSON syntax error 1007 * @retval CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN JSON syntax error
980 */ 1008 */
981 cx_attr_nonnull 1009 cx_attr_nonnull
982 cx_attr_access_w(2) 1010 cx_attr_access_w(2)
1011 cx_attr_export
983 CxJsonStatus cxJsonNext(CxJson *json, CxJsonValue **value); 1012 CxJsonStatus cxJsonNext(CxJson *json, CxJsonValue **value);
984 1013
985 /** 1014 /**
986 * Checks if the specified value is a JSON object. 1015 * Checks if the specified value is a JSON object.
987 * 1016 *
1250 * @return the value at the specified index 1279 * @return the value at the specified index
1251 * @see cxJsonIsArray() 1280 * @see cxJsonIsArray()
1252 */ 1281 */
1253 cx_attr_nonnull 1282 cx_attr_nonnull
1254 cx_attr_returns_nonnull 1283 cx_attr_returns_nonnull
1284 cx_attr_export
1255 CxJsonValue *cxJsonArrGet(const CxJsonValue *value, size_t index); 1285 CxJsonValue *cxJsonArrGet(const CxJsonValue *value, size_t index);
1256 1286
1257 /** 1287 /**
1258 * Returns an iterator over the JSON array elements. 1288 * Returns an iterator over the JSON array elements.
1259 * 1289 *
1265 * @return an iterator over the array elements 1295 * @return an iterator over the array elements
1266 * @see cxJsonIsArray() 1296 * @see cxJsonIsArray()
1267 */ 1297 */
1268 cx_attr_nonnull 1298 cx_attr_nonnull
1269 cx_attr_nodiscard 1299 cx_attr_nodiscard
1300 cx_attr_export
1270 CxIterator cxJsonArrIter(const CxJsonValue *value); 1301 CxIterator cxJsonArrIter(const CxJsonValue *value);
1271 1302
1272 /** 1303 /**
1273 * Returns an iterator over the JSON object members. 1304 * Returns an iterator over the JSON object members.
1274 * 1305 *
1281 * @return an iterator over the object members 1312 * @return an iterator over the object members
1282 * @see cxJsonIsObject() 1313 * @see cxJsonIsObject()
1283 */ 1314 */
1284 cx_attr_nonnull 1315 cx_attr_nonnull
1285 cx_attr_nodiscard 1316 cx_attr_nodiscard
1317 cx_attr_export
1286 CxIterator cxJsonObjIter(const CxJsonValue *value); 1318 CxIterator cxJsonObjIter(const CxJsonValue *value);
1287 1319
1288 /** 1320 /**
1289 * @copydoc cxJsonObjGet() 1321 * @copydoc cxJsonObjGet()
1290 */ 1322 */
1291 cx_attr_nonnull 1323 cx_attr_nonnull
1292 cx_attr_returns_nonnull 1324 cx_attr_returns_nonnull
1325 cx_attr_export
1293 CxJsonValue *cx_json_obj_get_cxstr(const CxJsonValue *value, cxstring name); 1326 CxJsonValue *cx_json_obj_get_cxstr(const CxJsonValue *value, cxstring name);
1294 1327
1295 #ifdef __cplusplus 1328 #ifdef __cplusplus
1296 } // extern "C" 1329 } // extern "C"
1297 1330
1298 CxJsonValue *cxJsonObjGet(const CxJsonValue *value, cxstring name) { 1331 static inline CxJsonValue *cxJsonObjGet(const CxJsonValue *value, cxstring name) {
1299 return cx_json_obj_get_cxstr(value, name); 1332 return cx_json_obj_get_cxstr(value, name);
1300 } 1333 }
1301 1334
1302 CxJsonValue *cxJsonObjGet(const CxJsonValue *value, cxmutstr name) { 1335 static inline CxJsonValue *cxJsonObjGet(const CxJsonValue *value, cxmutstr name) {
1303 return cx_json_obj_get_cxstr(value, cx_strcast(name)); 1336 return cx_json_obj_get_cxstr(value, cx_strcast(name));
1304 } 1337 }
1305 1338
1306 CxJsonValue *cxJsonObjGet(const CxJsonValue *value, const char *name) { 1339 static inline CxJsonValue *cxJsonObjGet(const CxJsonValue *value, const char *name) {
1307 return cx_json_obj_get_cxstr(value, cx_str(name)); 1340 return cx_json_obj_get_cxstr(value, cx_str(name));
1308 } 1341 }
1309 1342
1310 extern "C" { 1343 extern "C" {
1311 #else 1344 #else

mercurial